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 { afterEach, describe, expect, it } from 'vitest'
import { GlyphAtlas, GUTTER_PX } from './atlas'
import { packColor } from './cells'
import {
ATLAS_SENTINEL_RGBA,
SENTINEL_CSS,
createCanvasRasterizer,
sentinelIntact,
shrinkEligible,
shrinkToFit,
strikethroughThickness,
underlineThickness
} from './raster'
/**
* These tests pin the three rects a colored draw uses, because the whole mip story rests on them:
* the slot's own BACKGROUND covers the FULL PITCH rect (gutter included — that is what makes a
* level-1/2 texel blend this slot's content with itself rather than with the page ground), the
* INK is clipped to the CELL rect (a glyph may never draw NEW geometry into the gutter — the
* MAX_SAFE_LOD = 2 derivation in `atlas.ts` counts on 2*GUTTER_PX texels of this-slot-only content
* between two slots' inks), and the gutter is then EDGE-EXTENDED from the cell's own border texels
* so a full-bleed glyph continues into it instead of fading to background.
*
* Node has no OffscreenCanvas, so the contract is checked against a stub. The stub does two things:
* it RECORDS the op list (order and geometry) and it maintains a tiny PIXEL MODEL of the page.
* Both are needed — the replication is uniform by design (it runs for every glyph, and is a visual
* no-op when the ink does not reach the cell edge), so the op list alone can never distinguish a
* full-bleed glyph's gutter from an ordinary letter's.
*/
interface Op {
kind: 'fillRect' | 'fillText' | 'clip' | 'clearRect' | 'drawImage' | 'translate' | 'scale'
fill?: string
args: number[]
text?: string
/** `imageSmoothingEnabled` as it stood when the op was recorded. Only meaningful for drawImage:
* a 1-texel source stretched over the gutter must REPLICATE, never resample. */
smoothing?: boolean
/** Whether the drawImage source was the rasterizer's OWN canvas — the only source it ever uses. */
self?: boolean
/** The canvas font string in effect for a `fillText` — family, size and WEIGHT. */
font?: string
}
/** The active clip as half-open texel bounds, or `null` for "no clip". */
type Clip = { x0: number; y0: number; x1: number; y1: number } | null
/**
* The pixel model is deliberately HARD-EDGED: it answers "whose content is in this texel", not
* "what exact blend". A real canvas antialiases a fractional fill edge, and replicating such a
* partial-coverage texel into the gutter is correct precisely because it is still the slot's OWN
* edge colour — but a coverage model is not needed to check WHICH slot's content lands where.
*
* `fillText` paints NOTHING into the model: the stub has no font engine. That is not a gap for
* these tests, it is the case they need — an ordinary letter is exactly a glyph whose ink stays
* inside the cell, and the model then shows the replication copying background over background.
*/
function stubCanvas(
sizePx = 256,
/** The INK width `measureText` reports, in px, split evenly either side of the origin. The
* default is comfortably inside the 10px cell, which is what every test that predates
* shrink-to-fit assumes; a test about an oversized glyph passes its own. */
inkWidth = 8
): {
ops: Op[]
pixelAt: (x: number, y: number) => string
/** The page-wide `imageSmoothingEnabled` as it stands NOW — for asserting it was restored. */
smoothingNow: () => boolean
/** Wipe every texel WITHOUT going through `clearPage` — what a GPU reset does to the backing
* store behind the rasterizer's back, and the case the sentinel exists to detect. */
blankPage: () => void
/** Drive `ctx.isContextLost()`, the cheap check that runs before the readback. */
setContextLost: (lost: boolean) => void
/** Dispatch a canvas context event; returns whether a listener cancelled it. Cancelling
* `contextlost` is how a page REFUSES automatic restoration, so "was it cancelled" is a
* behavioural assertion, not a detail. */
fire: (type: 'contextlost' | 'contextrestored') => boolean
listenerCount: () => number
restore: () => void
} {
const ops: Op[] = []
const px: string[] = new Array(sizePx * sizePx).fill('')
let selfCanvas: unknown = null
let clip: Clip = null
let pending: { x: number; y: number; w: number; h: number } | null = null
const clipStack: Clip[] = []
const setPixel = (x: number, y: number, color: string): void => {
if (x < 0 || y < 0 || x >= sizePx || y >= sizePx) return
if (clip && (x < clip.x0 || y < clip.y0 || x >= clip.x1 || y >= clip.y1)) return
px[y * sizePx + x] = color
}
// Texel centres, i.e. the pixel whose centre falls inside [a, a+len). `Math.round` is that rule
// for every rect these tests use (all of them start on a whole texel).
const paint = (x: number, y: number, w: number, h: number, color: string): void => {
for (let j = Math.round(y); j < Math.round(y + h); j++)
for (let i = Math.round(x); i < Math.round(x + w); i++) setPixel(i, j, color)
}
const ctx = {
font: '',
textBaseline: '',
fillStyle: '',
imageSmoothingEnabled: true,
save() {
clipStack.push(clip)
},
restore() {
clip = clipStack.pop() ?? null
},
beginPath() {
pending = null
},
rect(x: number, y: number, w: number, h: number) {
ops.push({ kind: 'clip', args: [x, y, w, h] })
pending = { x, y, w, h }
},
clip() {
if (!pending) return
const next = {
x0: Math.round(pending.x),
y0: Math.round(pending.y),
x1: Math.round(pending.x + pending.w),
y1: Math.round(pending.y + pending.h)
}
clip = clip
? {
x0: Math.max(clip.x0, next.x0),
y0: Math.max(clip.y0, next.y0),
x1: Math.min(clip.x1, next.x1),
y1: Math.min(clip.y1, next.y1)
}
: next
},
fillRect(x: number, y: number, w: number, h: number) {
ops.push({ kind: 'fillRect', fill: ctx.fillStyle, args: [x, y, w, h] })
paint(x, y, w, h, ctx.fillStyle)
},
clearRect(x: number, y: number, w: number, h: number) {
ops.push({ kind: 'clearRect', args: [x, y, w, h] })
paint(x, y, w, h, '')
},
fillText(text: string, x: number, y: number) {
// `font` rides along so a test can assert WHICH face/weight the ink was drawn with — the
// 2026-08-09 weight bug was invisible in the op geometry and lived entirely in this string.
ops.push({ kind: 'fillText', fill: ctx.fillStyle, args: [x, y], text, font: ctx.font })
},
// Recorded, NOT applied to the pixel model — which costs these tests nothing, because the
// model's `fillText` paints no pixels either (there is no font engine here). What the shrink
// tests need is the TRANSFORM the rasterizer asked for, and that is exactly what this keeps.
translate(x: number, y: number) {
ops.push({ kind: 'translate', args: [x, y] })
},
scale(sx: number, sy: number) {
ops.push({ kind: 'scale', args: [sx, sy] })
},
/** Only the 9-argument form, and only with WHOLE-texel destination rects — which is all the
* rasterizer's gutter replication uses. Nearest-neighbour sampling off a SNAPSHOT of the page,
* which is what the spec guarantees for a self-referencing drawImage.
*
* `imageSmoothingEnabled` is RECORDED, NOT HONOURED: this model always replicates. So the
* pixel assertions below prove WHICH texel is copied where — they do NOT prove that the real
* canvas replicates rather than resamples. That claim rests entirely on the flag being off,
* which is why it has its own op-level test. */
drawImage(
src: unknown,
sx: number,
sy: number,
sw: number,
sh: number,
dx: number,
dy: number,
dw: number,
dh: number
) {
ops.push({
kind: 'drawImage',
args: [sx, sy, sw, sh, dx, dy, dw, dh],
smoothing: ctx.imageSmoothingEnabled,
self: src === selfCanvas
})
const snap = px.slice()
for (let j = 0; j < dh; j++) {
for (let i = 0; i < dw; i++) {
const u = Math.floor(sx + ((i + 0.5) * sw) / dw)
const v = Math.floor(sy + ((j + 0.5) * sh) / dh)
if (u < 0 || v < 0 || u >= sizePx || v >= sizePx) continue
setPixel(dx + i, dy + j, snap[v * sizePx + u])
}
}
},
// The ascent/descent pin the baseline (a face whose line box exactly fills the 20px cell), so
// the baseline math is not the subject here. The actualBoundingBox pair is the INK extent
// shrink-to-fit measures — `left: 0` puts the ink
// entirely to the right of the origin, which is where a normal glyph's ink sits.
measureText: () => ({
fontBoundingBoxAscent: 16,
fontBoundingBoxDescent: 4,
actualBoundingBoxLeft: 0,
actualBoundingBoxRight: inkWidth
}),
isContextLost: () => contextLost,
/** Only the 1x1 form the sentinel check uses. The model stores CSS colour strings, so this is
* the inverse of `rgb(r,g,b)` — and an unpainted texel is transparent-black, exactly as a real
* fresh (or blanked) page reads back. */
getImageData(x: number, y: number): { data: number[] } {
const color = px[y * sizePx + x] ?? ''
const m = /^rgb\((\d+),(\d+),(\d+)\)$/.exec(color)
if (!m) return { data: [0, 0, 0, 0] }
return { data: [Number(m[1]), Number(m[2]), Number(m[3]), 255] }
}
}
const listeners = new Map<string, Set<(e: { preventDefault(): void }) => void>>()
let contextLost = false
const prev = (globalThis as Record<string, unknown>).OffscreenCanvas
;(globalThis as Record<string, unknown>).OffscreenCanvas = class {
constructor(
public width: number,
public height: number
) {
selfCanvas = this
}
getContext(): unknown {
return ctx
}
addEventListener(type: string, fn: (e: { preventDefault(): void }) => void): void {
const set = listeners.get(type) ?? new Set()
set.add(fn)
listeners.set(type, set)
}
removeEventListener(type: string, fn: (e: { preventDefault(): void }) => void): void {
listeners.get(type)?.delete(fn)
}
}
return {
ops,
pixelAt(x: number, y: number) {
return px[y * sizePx + x]
},
smoothingNow() {
return ctx.imageSmoothingEnabled
},
blankPage() {
px.fill('')
},
setContextLost(lost: boolean) {
contextLost = lost
},
fire(type) {
let cancelled = false
for (const fn of listeners.get(type) ?? []) fn({ preventDefault: () => (cancelled = true) })
return cancelled
},
listenerCount() {
let n = 0
for (const set of listeners.values()) n += set.size
return n
},
restore() {
;(globalThis as Record<string, unknown>).OffscreenCanvas = prev
}
}
}
const FONT = { family: 'monospace', sizePx: 16, cellW: 10, cellH: 20, weight: 400, weightBold: 700 }
/** The pitch this font lays out on: ceil(cell) + a gutter on each side. */
const PITCH_W = 10 + 2 * GUTTER_PX
const PITCH_H = 20 + 2 * GUTTER_PX
/** The WHOLE texel columns/rows a cell occupies — `ceil(cell)`, i.e. the pitch minus its gutters.
* The edge-extension works in these because a texel is the smallest thing it can copy. */
const COLS_W = 10
const COLS_H = 20
/** A realistic INK origin — the corner of a pitch cell plus one gutter on each axis, which is
* exactly what `GlyphAtlas.cellXY` hands the rasterizer. */
const INK_X = PITCH_W + GUTTER_PX
const INK_Y = PITCH_H + GUTTER_PX
/** Final packed colour lanes, deliberately not black/white so a swapped fg/bg is visible. */
const FG = packColor(255, 160, 0, 255)
const BG = packColor(16, 32, 48, 255)
const FG_CSS = 'rgb(255,160,0)'
const BG_CSS = 'rgb(16,32,48)'
let active: { restore: () => void } | null = null
afterEach(() => {
active?.restore()
active = null
})
describe('createCanvasRasterizer', () => {
it('degrades to null (caller keeps the DOM renderer) when OffscreenCanvas is unavailable', () => {
const prev = (globalThis as Record<string, unknown>).OffscreenCanvas
delete (globalThis as Record<string, unknown>).OffscreenCanvas
expect(createCanvasRasterizer(FONT, 256)).toBeNull()
;(globalThis as Record<string, unknown>).OffscreenCanvas = prev
})
it('paints NOTHING at creation — the page ground stays transparent-black', () => {
const stub = stubCanvas()
active = stub
createCanvasRasterizer(FONT, 256)
// The old opaque-black page fill is GONE: the backdrop is now per-slot (the bg fill in
// `draw`), and a page-wide fill would put an opaque colour in slot 0, which every space
// samples. The ONE texel painted here is the sentinel, and it lands in slot 0's GUTTER —
// outside every sampled rect on the page. See `sentinelIntact`.
expect(stub.ops).toEqual([{ kind: 'fillRect', fill: SENTINEL_CSS, args: [0, 0, 1, 1] }])
// The part that actually matters: slot 0's SAMPLED cell box is untouched, so a space still
// samples transparent-black.
expect(stub.pixelAt(GUTTER_PX, GUTTER_PX)).toBe('')
expect(stub.pixelAt(GUTTER_PX + COLS_W - 1, GUTTER_PX + COLS_H - 1)).toBe('')
})
it('fills the FULL PITCH rect with bg, then clips the ink to the CELL rect and draws it in fg', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.draw(0x41, false, false, INK_X, INK_Y, FG, BG)
// 1. The background covers the pitch cell — its origin is the INK origin minus one gutter on
// each axis, and its extent is the whole pitch (gutters included).
expect(stub.ops[0]).toEqual({
kind: 'fillRect',
fill: BG_CSS,
args: [INK_X - GUTTER_PX, INK_Y - GUTTER_PX, PITCH_W, PITCH_H]
})
// 2. The ink is clipped to the CELL rect, which starts at the ink origin.
expect(stub.ops[1]).toEqual({ kind: 'clip', args: [INK_X, INK_Y, FONT.cellW, FONT.cellH] })
// 3. The glyph itself, in the foreground colour.
const ink = stub.ops[2]
expect(ink.kind).toBe('fillText')
expect(ink.text).toBe('A')
expect(ink.fill).toBe(FG_CSS)
// Baseline: unchanged half-leading convention, now measured from the ink origin (i.e. inside
// the cell rect, one gutter into the pitch cell), on a WHOLE device pixel.
expect(ink.args[0]).toBe(INK_X)
expect(ink.args[1]).toBe(INK_Y + 16)
expect(Number.isInteger(ink.args[1])).toBe(true)
})
describe("the right half of a double-width character ('wide-right')", () => {
// A slot's ink box is one cell and step 2 CUTS the overflow, so a character the terminal gave
// two cells to was rendered as its first cell alone — the 2026-08-05 ⭐ report. The follower
// cell asks for the same character's other half, which is the same draw with the glyph's
// origin moved one cell left: the window this slot's clip keeps is then the second cell.
it('draws the glyph one cell LEFT of the ink origin', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.draw(0x4e2d, false, false, INK_X, INK_Y, FG, BG, 'wide-right')
const ink = stub.ops.find((o) => o.kind === 'fillText')!
expect(ink.args[0]).toBe(INK_X - FONT.cellW)
// The baseline does not move: only the horizontal window changes.
expect(ink.args[1]).toBe(INK_Y + 16)
})
it('leaves the CLIP on this slot’s own cell box', () => {
// This is the whole reason the fix costs nothing structurally. The clip is what holds the
// 2*GUTTER_PX separation MAX_SAFE_LOD is derived from; if it moved with the ink, the right
// half would spill into the neighbouring slot and show up as a ghost in its mip.
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.draw(0x4e2d, false, false, INK_X, INK_Y, FG, BG, 'wide-right')
expect(stub.ops.find((o) => o.kind === 'clip')).toEqual({
kind: 'clip',
args: [INK_X, INK_Y, FONT.cellW, FONT.cellH]
})
})
it('fills this slot’s own pitch rect with bg, exactly as the left half does', () => {
// The follower's background is what makes a selection or a block cursor one unbroken run
// across a wide glyph. The shift must not reach it.
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.draw(0x4e2d, false, false, INK_X, INK_Y, FG, BG, 'wide-right')
expect(stub.ops[0]).toEqual({
kind: 'fillRect',
fill: BG_CSS,
args: [INK_X - GUTTER_PX, INK_Y - GUTTER_PX, PITCH_W, PITCH_H]
})
})
it('defaults to the left half, so every existing call is unchanged', () => {
const withDefault = stubCanvas()
active = withDefault
createCanvasRasterizer(FONT, 256)!.draw(0x41, false, false, INK_X, INK_Y, FG, BG)
const explicit = stubCanvas()
active = explicit
createCanvasRasterizer(FONT, 256)!.draw(0x41, false, false, INK_X, INK_Y, FG, BG, 'whole')
expect(withDefault.ops).toEqual(explicit.ops)
})
})
/**
* The 2026-08-05 device finding: an agent CLI's task-list icon rendered with its right edge
* sliced off, while GPU mode showed it whole. A symbol whose ink is wider than its cell used to
* be CUT by the ink clip, and the clip cannot be relaxed — ink in the gutter is what the
* MAX_SAFE_LOD derivation forbids. So the glyph is made to fit instead of trimmed to fit.
*/
describe('shrink-to-fit for a glyph whose ink exceeds its cell', () => {
/** The `fillText` op, and the transform (if any) that was in effect for it. */
function inkOp(ops: Op[]): { text: Op; scale?: Op; translate?: Op } {
return {
text: ops.find((o) => o.kind === 'fillText')!,
scale: ops.find((o) => o.kind === 'scale'),
translate: ops.find((o) => o.kind === 'translate')
}
}
it('an ordinary glyph is drawn by the SAME call as before — no transform at all', () => {
// Load-bearing: a scale of exactly 1 must take the untouched path, so nothing anyone has
// already looked at moves. 8px of ink in a 10px cell is an ordinary letter.
const stub = stubCanvas(256, 8)
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.draw(0x41, false, false, INK_X, INK_Y, FG, BG)
const { text, scale, translate } = inkOp(stub.ops)
expect(scale).toBeUndefined()
expect(translate).toBeUndefined()
expect(text.args).toEqual([INK_X, INK_Y + 16])
})
it('a LETTER is never scaled, however far its ink overhangs', () => {
// The 2026-08-07 regression. An italic face measures ~1.19 of the advance at its worst glyph
// and a bold-italic one ~1.25, so a rule that shrinks "anything oversized" renders italic
// text at ~84% of the roman text beside it — and per glyph, so the narrow letters in a word
// stay full size and the wide ones do not. Overhang is normal for text; clipping its tip is
// what this renderer has always done and what nobody has ever reported.
const stub = stubCanvas(256, 14) // 14px of ink in a 10px cell — 1.4×, far past the tolerance
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.draw(0x58, false, true, INK_X, INK_Y, FG, BG) // italic 'X'
expect(inkOp(stub.ops).scale).toBeUndefined()
})
it('an oversized SYMBOL is SCALED to its cell instead of being clipped', () => {
// 14px of ink entitled to one 10px cell: without this it lost 4px off its right edge.
const stub = stubCanvas(256, 14)
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.draw(0x29c9, false, false, INK_X, INK_Y, FG, BG)
const { text, scale, translate } = inkOp(stub.ops)
expect(scale!.args).toEqual([10 / 14, 10 / 14])
// Scaled about the BASELINE, so the glyph keeps sitting on its neighbours' line, and
// re-centred inside the cell — here the scaled ink is exactly the cell, so the centring term
// is zero and the ink starts at the ink origin.
expect(translate!.args).toEqual([INK_X, INK_Y + 16])
expect(text.args).toEqual([0, 0])
})
it('a slight overhang is left alone — the tolerance absorbs an antialiasing fringe', () => {
// 10.3px in a 10px cell is a full-bleed glyph measuring a fraction over, not an oversized
// symbol. Scaling it would buy nothing and could open a hairline in a run of `───`.
const stub = stubCanvas(256, 10.3)
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.draw(0x41, false, false, INK_X, INK_Y, FG, BG)
expect(inkOp(stub.ops).scale).toBeUndefined()
})
it('a DOUBLE-WIDTH character is measured against TWO cells, not one', () => {
// The regression this guards is severe and silent: an emoji's ink is ~1.7 cells, so measuring
// either half against ONE cell would shrink every emoji back into the fragment the two-slot
// mechanism exists to prevent. 18px of ink is inside a 20px entitlement — leave it alone.
for (const part of ['wide-left', 'wide-right'] as const) {
const stub = stubCanvas(256, 18)
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.draw(0x1f44d, false, false, INK_X, INK_Y, FG, BG, part)
expect(inkOp(stub.ops).scale, part).toBeUndefined()
}
})
})
// The claim is about GEOMETRY, not about pixels: no glyph may generate NEW ink outside the slot's
// own WHOLE-TEXEL CELL BOX, because the MAX_SAFE_LOD derivation counts on 2*GUTTER_PX texels
// between two slots' inks. The gutter is not required to be BACKGROUND — the edge-extension
// strips below copy this slot's own border texels into it, and a copy of the slot's own content
// is not a second slot's ink. So this pin filters `fillRect`/`fillText` ops only, and the
// replication `drawImage`s are checked separately for their exact (this-slot-only) rects.
//
// RE-SCOPED (2026-08-04, far-edge snapping) from the fractional CELL rect to that box —
// `max(1, ceil(cell))`, the pitch minus its two gutters. A box/block op whose span REACHES the
// fractional cell edge is now grown to the whole texel, so on a fractional axis its ink
// legitimately ends past `cellW`. Nothing the LOD derivation rests on moves: the pitch is
// `ceil(cell) + 2*GUTTER_PX` by construction, so the box is exactly the pitch minus its gutters
// and two slots' inks are still 2*GUTTER_PX texels apart. What is still forbidden — and what this
// pin still catches — is ink IN THE GUTTER, which stays reachable only through step 3's
// replication of this slot's own texels. The integral case is the old assertion unchanged
// (ceil is the identity there); the fractional one is what the re-scope buys.
it.each([
['integral 10x20', { cellW: 10, cellH: 20 }],
['fractional 10.5x20.5', { cellW: 10.5, cellH: 20.5 }]
])('keeps every ink op inside the whole-texel CELL BOX on a %s cell', (_label, sizes) => {
const stub = stubCanvas()
active = stub
const font = { family: 'monospace', sizePx: 16, weight: 400, weightBold: 700, ...sizes }
const colsW = Math.max(1, Math.ceil(sizes.cellW))
const colsH = Math.max(1, Math.ceil(sizes.cellH))
const ink0 = 40
const r = createCanvasRasterizer(font, 256)!
stub.ops.length = 0
r.draw(0x2588, false, false, ink0, ink0, FG, BG) // █ — the glyph that fills the whole cell
const ink = stub.ops.filter((o) => o.kind === 'fillRect' && o.fill === FG_CSS)
expect(ink.length).toBeGreaterThan(0)
for (const op of ink) {
const [x, y, w, h] = op.args
expect(x).toBeGreaterThanOrEqual(ink0)
expect(y).toBeGreaterThanOrEqual(ink0)
expect(x + w).toBeLessThanOrEqual(ink0 + colsW)
expect(y + h).toBeLessThanOrEqual(ink0 + colsH)
}
// And the only fill that is allowed outside the cell box is the background one, which is
// exactly the pitch rect.
const outside = stub.ops.filter(
(o) =>
o.kind === 'fillRect' &&
(o.args[0] < ink0 ||
o.args[1] < ink0 ||
o.args[0] + o.args[2] > ink0 + colsW ||
o.args[1] + o.args[3] > ink0 + colsH)
)
expect(outside).toEqual([
{
kind: 'fillRect',
fill: BG_CSS,
args: [ink0 - GUTTER_PX, ink0 - GUTTER_PX, colsW + 2 * GUTTER_PX, colsH + 2 * GUTTER_PX]
}
])
})
// The pin above draws ONE glyph. The property the widened box clip actually rests on is stronger
// — no op of ANY geometric glyph may exceed the whole-texel box on a fractional cell — and the
// clip is the only thing standing behind it, so a change to box-glyphs.ts's span/snap arithmetic
// could break it without touching this file. Sweeping the two ranges box-glyphs.ts owns makes it
// a standing guarantee rather than something re-derived by hand at review time. It also pins the
// FAR-EDGE SNAP's own precondition from the other side: `span` never returns a reaching edge
// SHORT of the cell extent, so FAR_EDGE_EPS has nothing to bridge and can stay at float noise.
it('never lets any box/block glyph escape the whole-texel box, over both ranges', () => {
const stub = stubCanvas()
active = stub
const cellW = 10.5
const cellH = 20.5
const font = { family: 'monospace', sizePx: 16, cellW, cellH, weight: 400, weightBold: 700 }
const colsW = Math.max(1, Math.ceil(cellW))
const colsH = Math.max(1, Math.ceil(cellH))
const ink0 = 40
const r = createCanvasRasterizer(font, 4096)!
let drawn = 0
let short = 0
for (let code = 0x2500; code <= 0x259f; code++) {
stub.ops.length = 0
r.draw(code, false, false, ink0, ink0, FG, BG)
const ink = stub.ops.filter((o) => o.kind === 'fillRect' && o.fill === FG_CSS)
if (!ink.length) continue
drawn++
for (const op of ink) {
const [x, y, w, h] = op.args
expect(x).toBeGreaterThanOrEqual(ink0)
expect(y).toBeGreaterThanOrEqual(ink0)
expect(x + w).toBeLessThanOrEqual(ink0 + colsW)
expect(y + h).toBeLessThanOrEqual(ink0 + colsH)
// No edge may land a HAIR short of the cell extent. That band is what a "reaching" edge
// would look like if `span` ever returned float noise instead of the extent verbatim — the
// snap would miss it and the grout would survive. Edges further inside are ordinary
// interior geometry (a ┈ dash can legitimately end at 10 on a 10.5 cell), which is exactly
// what FAR_EDGE_EPS must NOT capture; only the noise band is evidence of a miss.
const right = x + w - ink0
if (right > cellW - 1e-3 && right < cellW) short++
}
}
expect(drawn).toBeGreaterThan(100)
expect(short).toBe(0)
})
it('draws the geometric box/block glyphs in the FOREGROUND over the bg fill, never with the font', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.draw(0x2591, false, false, INK_X, INK_Y, FG, BG) // ░ — a stipple, fg pixels over bg
expect(stub.ops.some((o) => o.kind === 'fillText')).toBe(false)
const fills = stub.ops.filter((o) => o.kind === 'fillRect')
expect(fills[0].fill).toBe(BG_CSS) // the slot's own backdrop, first
expect(fills.slice(1).every((o) => o.fill === FG_CSS)).toBe(true)
expect(fills.length).toBeGreaterThan(1)
})
it('converts both packed lanes to css rgb(), reading the RGB lanes in packColor order', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
// A colour whose channels are all different, so a swapped r/b lane cannot pass.
r.draw(0x41, false, false, INK_X, INK_Y, packColor(1, 2, 3, 255), packColor(4, 5, 6, 255))
expect(stub.ops[0].fill).toBe('rgb(4,5,6)')
expect(stub.ops.find((o) => o.kind === 'fillText')!.fill).toBe('rgb(1,2,3)')
})
it('keys off the UNSIGNED lanes — a negative packed colour is the same colour', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
// `0xff << 24` is negative in JS; an arithmetic path can hand us that spelling.
r.draw(0x41, false, false, INK_X, INK_Y, (0xff << 24) | 0x0000ff, (0xff << 24) | 0x00ff00)
expect(stub.ops[0].fill).toBe('rgb(0,255,0)')
expect(stub.ops.find((o) => o.kind === 'fillText')!.fill).toBe('rgb(255,0,0)')
})
it('clearPage() blanks the whole page back to transparent-black', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.clearPage()
// clearRect, NOT a fill: the page ground has to go back to transparent-black so slot 0 stays
// the blank slot every space samples. The sentinel is then REPAINTED, because a reset is a
// normal event and a page missing its sentinel afterwards would read as a lost 2D context and
// rebuild the whole canvas on the next revive.
expect(stub.ops).toEqual([
{ kind: 'clearRect', args: [0, 0, 256, 256] },
{ kind: 'fillRect', fill: SENTINEL_CSS, args: [0, 0, 1, 1] }
])
})
it('never draws slot 0, so the blank slot every space samples stays transparent', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
const atlas = new GlyphAtlas(r, 256)
stub.ops.length = 0
expect(atlas.glyphFor(0x20, false, false, FG, BG)).toBe(0)
expect(stub.ops).toEqual([])
// The first real glyph starts at slot 1 — i.e. past the origin cell. Not even its background
// fill may reach slot 0's pitch rect.
atlas.glyphFor(0x41, false, false, FG, BG)
// Which args carry the DESTINATION differs by op: a drawImage records source-then-dest, so the
// reach of a replication strip is args[4..5], not args[0..1] (its source is by construction
// inside the slot's own cell, and reading that as the destination would pin nothing).
const reachesSlot0 = (o: Op): boolean => {
const dx = o.kind === 'drawImage' ? o.args[4] : o.args[0]
const dy = o.kind === 'drawImage' ? o.args[5] : o.args[1]
return dx < PITCH_W && dy < PITCH_H
}
expect(stub.ops.some(reachesSlot0)).toBe(false)
})
/**
* EDGE-EXTENDED GUTTERS (device round, 2026-08-04). A gutter filled with flat background made the
* mip chain average cell-edge INK with background, which drew a dark "grout" line along every
* boundary between two full-bleed cells at zoom < 1 (the Claude mascot's block art, tmux's │ ─
* pane separators). The fix is the standard atlas one: clamp-to-edge padding — the gutter carries
* the cell's own outermost texel row/column, so a minified sample keeps averaging ink with ink.
*/
describe('gutter edge-extension', () => {
/** All four replication ops, in the order the rasterizer must emit them. */
const strips = (ops: Op[]): Op[] => ops.filter((o) => o.kind === 'drawImage')
it('replicates the cell border into the gutter — sides first, then full-pitch rows for the corners', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.draw(0x2588, false, false, INK_X, INK_Y, FG, BG) // █
// Order is load-bearing: the LEFT/RIGHT strips run first over the cell's rows only, then the
// TOP/BOTTOM strips copy a full-PITCH-wide row — by which time that row already holds the
// side strips, so each corner of the gutter ends up with the cell's corner texel.
expect(strips(stub.ops).map((o) => o.args)).toEqual([
// left: the cell's first column, stretched over the left gutter
[INK_X, INK_Y, 1, COLS_H, INK_X - GUTTER_PX, INK_Y, GUTTER_PX, COLS_H],
// right: its last column, over the right gutter
[
INK_X + COLS_W - 1,
INK_Y,
1,
COLS_H,
INK_X + COLS_W,
INK_Y,
GUTTER_PX,
COLS_H
],
// top: the (now side-extended) first row, over the full pitch width
[INK_X - GUTTER_PX, INK_Y, PITCH_W, 1, INK_X - GUTTER_PX, INK_Y - GUTTER_PX, PITCH_W, GUTTER_PX],
// bottom: mirrored
[
INK_X - GUTTER_PX,
INK_Y + COLS_H - 1,
PITCH_W,
1,
INK_X - GUTTER_PX,
INK_Y + COLS_H,
PITCH_W,
GUTTER_PX
]
])
// The source is the page itself — a self-referencing drawImage, which 2D canvas defines as
// reading a snapshot.
expect(strips(stub.ops).every((o) => o.self)).toBe(true)
})
it('disables image smoothing while replicating and restores it afterwards', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.draw(0x2588, false, false, INK_X, INK_Y, FG, BG)
// A 1-texel source stretched over GUTTER_PX texels has to REPLICATE, not resample: smoothing
// would fade the copy back towards whatever the gutter held before.
expect(strips(stub.ops).map((o) => o.smoothing)).toEqual([false, false, false, false])
// …and the page-wide flag is left as it was found, because the next slot's bg fill and ink
// are not this call's business. (Every draw restores it, so the second call still sees it
// disabled only for its own strips.)
r.draw(0x41, false, false, INK_X, INK_Y, FG, BG)
expect(strips(stub.ops).map((o) => o.smoothing)).toEqual(new Array(8).fill(false))
expect(stub.smoothingNow()).toBe(true)
})
/** Every texel of the slot's PITCH rect that lies outside its whole-texel cell box. */
const gutterTexels = (): { x: number; y: number }[] => {
const out: { x: number; y: number }[] = []
for (let y = INK_Y - GUTTER_PX; y < INK_Y - GUTTER_PX + PITCH_H; y++)
for (let x = INK_X - GUTTER_PX; x < INK_X - GUTTER_PX + PITCH_W; x++)
if (x < INK_X || x >= INK_X + COLS_W || y < INK_Y || y >= INK_Y + COLS_H) out.push({ x, y })
return out
}
it('a FULL-BLEED glyph leaves the whole gutter — corners included — carrying its ink', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
r.draw(0x2588, false, false, INK_X, INK_Y, FG, BG) // █ fills the cell edge to edge
for (const { x, y } of gutterTexels()) expect(`${x},${y}:${stub.pixelAt(x, y)}`).toBe(`${x},${y}:${FG_CSS}`)
})
it('a glyph whose ink stays inside the cell leaves the gutter as background', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
r.draw(0x41, false, false, INK_X, INK_Y, FG, BG) // an ordinary letter — ink nowhere near the edge
// Replication still runs (it is uniform, never conditional on where the ink landed); for
// ordinary text it copies background over background, i.e. bit-identical to the old bg-filled
// gutter. That is why no detection of "does this glyph bleed?" is needed anywhere.
for (const { x, y } of gutterTexels()) expect(`${x},${y}:${stub.pixelAt(x, y)}`).toBe(`${x},${y}:${BG_CSS}`)
})
it('a half block continues the ink on ITS side only — the other gutter stays background', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
r.draw(0x258c, false, false, INK_X, INK_Y, FG, BG) // ▌ left half
const midY = INK_Y + COLS_H / 2
// Left gutter: ink, all the way out to the pitch edge.
for (let x = INK_X - GUTTER_PX; x < INK_X; x++) expect(stub.pixelAt(x, midY)).toBe(FG_CSS)
// Right gutter: background, because the cell's last column is background.
for (let x = INK_X + COLS_W; x < INK_X + COLS_W + GUTTER_PX; x++)
expect(stub.pixelAt(x, midY)).toBe(BG_CSS)
// And the corners follow the side they belong to — the property the strip ORDER buys.
expect(stub.pixelAt(INK_X - GUTTER_PX, INK_Y - GUTTER_PX)).toBe(FG_CSS)
expect(stub.pixelAt(INK_X + COLS_W + GUTTER_PX - 1, INK_Y - GUTTER_PX)).toBe(BG_CSS)
expect(stub.pixelAt(INK_X - GUTTER_PX, INK_Y + COLS_H + GUTTER_PX - 1)).toBe(FG_CSS)
})
/**
* FRACTIONAL AND SUB-TEXEL CELLS. `device.cell.width` is `charWidth * dpr` and is fractional in
* general, so `ceil` being the identity is a property of the 10x20 font above and of nothing
* else. Two things have to hold on a fractional axis:
*
* - the strip DESTINATIONS still tile the gutter frame EXACTLY (the pitch rect minus the whole
* texel columns/rows the cell occupies) — no double-covered texel, no missed one, and in
* particular a right/bottom gutter that is exactly GUTTER_PX wide rather than
* `pitch - cell` wide;
* - the strip SOURCE is the last FULLY covered texel, one further in than the cell's outermost
* texel — which on a fractional axis is only PARTIALLY covered by the cell. See the
* coverage table in raster.ts step 3 for why (replicating the partial texel leaves a
* 37.5-point dip; sourcing the last full one drops it to 12.5).
*/
const at = (ink: number, sizes: { cellW: number; cellH: number }) => {
const cols = (c: number): number => Math.max(1, Math.ceil(c))
return {
font: { family: 'monospace', sizePx: 16, weight: 400, weightBold: 700, ...sizes },
ink,
colsW: cols(sizes.cellW),
colsH: cols(sizes.cellH),
pitchW: cols(sizes.cellW) + 2 * GUTTER_PX,
pitchH: cols(sizes.cellH) + 2 * GUTTER_PX
}
}
/** Source rects of the four strips, in emit order (left, right, top, bottom). */
const sources = (ops: Op[]): number[][] => strips(ops).map((o) => o.args.slice(0, 4))
/** Destination rects, same order. */
const dests = (ops: Op[]): number[][] => strips(ops).map((o) => o.args.slice(4))
const texelsOf = (rects: number[][]): string[] => {
const out: string[] = []
for (const [rx, ry, rw, rh] of rects)
for (let j = ry; j < ry + rh; j++) for (let i = rx; i < rx + rw; i++) out.push(`${i},${j}`)
return out
}
it('a FRACTIONAL cell sources the last FULLY COVERED column/row, not the partial edge texel', () => {
const stub = stubCanvas()
active = stub
// 10.5 x 20.5: the cell's outermost texel on each axis is only HALF covered.
const c = at(40, { cellW: 10.5, cellH: 20.5 })
const r = createCanvasRasterizer(c.font, 256)!
stub.ops.length = 0
r.draw(0x2588, false, false, c.ink, c.ink, FG, BG)
// ceil(10.5) - 1 = 10 would be the HALF-covered texel; floor(10.5) - 1 = 9 is the last full
// one. The partial texel stays exactly where it is — it is genuine cell content.
expect(sources(stub.ops)[1]).toEqual([c.ink + 9, c.ink, 1, c.colsH])
expect(sources(stub.ops)[3]).toEqual([c.ink - GUTTER_PX, c.ink + 19, c.pitchW, 1])
// The near edges are integral by construction (the ink origin is a whole texel), so their
// sources are unchanged.
expect(sources(stub.ops)[0]).toEqual([c.ink, c.ink, 1, c.colsH])
expect(sources(stub.ops)[2]).toEqual([c.ink - GUTTER_PX, c.ink, c.pitchW, 1])
// And the right gutter is exactly GUTTER_PX wide — not `pitch - cellW`.
expect(dests(stub.ops)[1]).toEqual([c.ink + c.colsW, c.ink, GUTTER_PX, c.colsH])
expect(dests(stub.ops)[3]).toEqual([c.ink - GUTTER_PX, c.ink + c.colsH, c.pitchW, GUTTER_PX])
})
it('a SUB-TEXEL cell sources its one (partial) texel rather than indexing off the page', () => {
const stub = stubCanvas()
active = stub
// 0.5 x 0.5: `floor(cell) - 1` is -1, and the clamp is what keeps the source inside the slot.
// There is exactly one texel, half covered, and it is the only thing there is to replicate.
const c = at(40, { cellW: 0.5, cellH: 0.5 })
const r = createCanvasRasterizer(c.font, 256)!
stub.ops.length = 0
r.draw(0x2588, false, false, c.ink, c.ink, FG, BG)
expect(c.colsW).toBe(1)
expect(sources(stub.ops)[1]).toEqual([c.ink, c.ink, 1, 1])
expect(sources(stub.ops)[3]).toEqual([c.ink - GUTTER_PX, c.ink, c.pitchW, 1])
expect(dests(stub.ops)[1]).toEqual([c.ink + 1, c.ink, GUTTER_PX, 1])
})
it.each([
['integral 10x20', { cellW: 10, cellH: 20 }],
['fractional 10.5x20.5', { cellW: 10.5, cellH: 20.5 }],
['barely-fractional 10.01x20.99', { cellW: 10.01, cellH: 20.99 }],
['sub-texel 0.5x0.5', { cellW: 0.5, cellH: 0.5 }]
])('tiles the gutter frame EXACTLY on a %s cell', (_label, sizes) => {
const stub = stubCanvas()
active = stub
const c = at(40, sizes)
const r = createCanvasRasterizer(c.font, 256)!
stub.ops.length = 0
r.draw(0x2588, false, false, c.ink, c.ink, FG, BG)
const covered = texelsOf(dests(stub.ops))
// No texel is written twice — the four strips abut, they do not overlap.
expect(new Set(covered).size).toBe(covered.length)
// And their union is precisely the pitch rect minus the cell's whole-texel box: every gutter
// texel gets edge-extended, and not one texel of the cell is overwritten by a strip.
const frame: string[] = []
for (let j = c.ink - GUTTER_PX; j < c.ink - GUTTER_PX + c.pitchH; j++)
for (let i = c.ink - GUTTER_PX; i < c.ink - GUTTER_PX + c.pitchW; i++)
if (i < c.ink || i >= c.ink + c.colsW || j < c.ink || j >= c.ink + c.colsH)
frame.push(`${i},${j}`)
expect(new Set(covered)).toEqual(new Set(frame))
})
})
/**
* GEOMETRIC FAR-EDGE SNAPPING (device round, 2026-08-04, second screenshot). Edge-extended
* gutters removed most of the grout, but a phase-dependent residual dip survived on a FRACTIONAL
* axis: the cell's outermost texel is only partly covered, so a full-bleed geometric glyph left it
* as a half ink / half background blend that no gutter content can cancel. In the COMPOSED frame
* the other half of that boundary pixel is the NEIGHBOUR cell's ink, so full ink is the correct
* colour there — xterm never meets this because its atlas cells are integral device px.
*
* So a box/block op whose span REACHES the far cell edge has that edge snapped outward to the
* whole-texel cell box. Two things the tests below have to keep honest: only edges that actually
* reach the boundary move (an interior edge — a half block's midline, a dash's tail — must not),
* and only the GEOMETRY branch is affected (a font glyph's partial far column is genuine
* antialiased content).
*/
describe('geometric far-edge snapping', () => {
/** A fractional cell on BOTH axes: 10.5 x 20.5, whole-texel box 11 x 21. */
const FRAC = { family: 'monospace', sizePx: 16, cellW: 10.5, cellH: 20.5, weight: 400, weightBold: 700 }
const FRAC_COLS_W = 11
const FRAC_COLS_H = 21
/** A whole-texel ink origin, as `GlyphAtlas.cellXY` always hands over. */
const IX = 40
/** The ink ops in CELL-LOCAL coordinates — i.e. exactly what the box branch filled. */
const inkRects = (ops: Op[], ink = IX): number[][] =>
ops
.filter((o) => o.kind === 'fillRect' && o.fill === FG_CSS)
.map((o) => [o.args[0] - ink, o.args[1] - ink, o.args[2], o.args[3]])
const drawFrac = (code: number, font = FRAC): ReturnType<typeof stubCanvas> => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(font, 256)!
stub.ops.length = 0
r.draw(code, false, false, IX, IX, FG, BG)
return stub
}
it('grows a FULL-BLEED block to the whole-texel cell box on a fractional cell', () => {
const stub = drawFrac(0x2588) // █
// 10.5 x 20.5 of ink would leave the outermost texel on each axis half covered; 11 x 21 fills
// it. The op still STARTS at 0 — the near edges need no snap, see the dedicated pin below.
expect(inkRects(stub.ops)).toEqual([[0, 0, FRAC_COLS_W, FRAC_COLS_H]])
})
it('snaps ONLY the far edge of a right-half block — its interior midline does not move', () => {
const stub = drawFrac(0x2590) // ▐ right half
// The midline is `round(4/8 * 10.5)` = 5, a genuine INTERIOR edge sitting ~half a cell from
// the boundary; the right edge reaches 10.5 and becomes the whole texel 11, i.e. w = 11 - 5.
expect(inkRects(stub.ops)).toEqual([[5, 0, FRAC_COLS_W - 5, FRAC_COLS_H]])
})
it('snaps the right end of a horizontal rule, leaving its thickness alone', () => {
const stub = drawFrac(0x2500) // ─
// The rule spans the cell horizontally (→ snapped) and is one device px thick, centred: its
// bottom edge is nowhere near the cell's, so the vertical axis is untouched.
expect(inkRects(stub.ops)).toEqual([[0, 10, FRAC_COLS_W, 1]])
})
it('leaves a non-edge-reaching span alone — the two axes are decided independently', () => {
const stub = drawFrac(0x2502) // │
const [x, y, w, h] = inkRects(stub.ops)[0]
// The stem sits at the cell's midline: 1 device px wide, five texels short of the far edge.
// Untouched, both position and width.
expect([x, w]).toEqual([5, 1])
// Its own far edge — the BOTTOM — does reach, and snaps. Nothing about the horizontal axis
// follows from that.
expect([y, h]).toEqual([0, FRAC_COLS_H])
})
it('does not capture a dashed rule whose last dash merely ends NEAR the far edge', () => {
const stub = drawFrac(0x2508) // ┈ — four dashes, deliberately NOT tiling
// The guard on the epsilon. On a 10.5-wide cell the last dash rounds to a right edge of 10,
// exactly HALF A PIXEL short of the boundary — so the "obvious" `>= cellW - 0.5` tolerance
// would weld it to the next cell's first dash and quietly turn ┈ into ─. The gap IS the
// character, so the tolerance has to be tight enough to leave it.
expect(inkRects(stub.ops)).toEqual([
[0, 10, 2, 1],
[3, 10, 1, 1],
[5, 10, 2, 1],
[8, 10, 2, 1]
])
})
it('needs no near-edge snap — an op that starts at the cell edge already starts on a texel', () => {
const stub = drawFrac(0x2588)
// The ink ORIGIN is a whole texel (`GlyphAtlas.cellXY` derives it from the whole-texel pitch),
// and `span`'s `snap` returns a literal 0 for anything at or before the near edge. So the near
// edges are flush with a texel boundary by construction and there is nothing to round out.
for (const [x, y] of inkRects(stub.ops)) {
expect(x).toBe(0)
expect(y).toBe(0)
}
expect(Number.isInteger(IX)).toBe(true)
})
it('clips the GEOMETRY branch to the whole-texel box and the FONT branch to the fractional cell', () => {
// Geometry: the clip has to admit the snap, or the widened rects are simply cut back.
const geo = drawFrac(0x2588)
expect(geo.ops.find((o) => o.kind === 'clip')).toEqual({
kind: 'clip',
args: [IX, IX, FRAC_COLS_W, FRAC_COLS_H]
})
active?.restore()
active = null
// Font: unchanged, and deliberately so. A glyph's partial far column carries genuine
// antialiased glyph edge — real content, drawn by the platform rasterizer — and overwriting
// or extending it would corrupt pixels rather than complete a shape we generated ourselves.
const font = drawFrac(0x41) // 'A'
expect(font.ops.find((o) => o.kind === 'clip')).toEqual({
kind: 'clip',
args: [IX, IX, FRAC.cellW, FRAC.cellH]
})
expect(font.ops.some((o) => o.kind === 'fillText')).toBe(true)
})
/**
* The PIXEL half of the claim, and why it is measured at .25 rather than at the brief's .5.
*
* The stub's pixel model is hard-edged and assigns a texel by its CENTRE (`Math.round`), so on a
* `.5`-fractional cell it already reports the half-covered edge texel as fully inked — the model
* cannot distinguish before from after there, which is precisely the kind of "green either way"
* assertion that pins nothing. At `.25` the centre of that texel falls OUTSIDE the fractional
* cell, so the model leaves it as background until the snap fills it. The `.5` case is pinned
* exactly, on op GEOMETRY, by the first test in this block.
*/
it('fills the partial far texel on a fractional cell, and the gutter beyond continues it', () => {
const stub = stubCanvas()
active = stub
// 10.25 x 20.25: whole-texel box 11 x 21, last FULLY covered texel 9 / 19.
const r = createCanvasRasterizer({ family: 'monospace', sizePx: 16, cellW: 10.25, cellH: 20.25, weight: 400, weightBold: 700 }, 256)!
r.draw(0x2588, false, false, IX, IX, FG, BG) // █
// The partial far column and row — texel 10 / 20 — now carry FULL ink rather than a blend
// fading to background.
expect(stub.pixelAt(IX + 10, IX + 5)).toBe(FG_CSS)
expect(stub.pixelAt(IX + 5, IX + 20)).toBe(FG_CSS)
// Including the corner where the two meet.
expect(stub.pixelAt(IX + 10, IX + 20)).toBe(FG_CSS)
// And the gutter past the box continues it, so a minified sample at the boundary keeps
// averaging ink with ink all the way out to the pitch edge.
for (let g = 0; g < GUTTER_PX; g++) {
expect(stub.pixelAt(IX + 11 + g, IX + 5)).toBe(FG_CSS)
expect(stub.pixelAt(IX + 5, IX + 21 + g)).toBe(FG_CSS)
}
})
it('leaves the STIPPLE shades a stipple — a far-edge dot grows by a partial texel at most', () => {
const stub = drawFrac(0x2592) // ▒ — a dither pattern, not a tint
const rects = inkRects(stub.ops)
// Still a scatter of pattern-sized runs rather than one grown slab: the snap only ever moves
// a run's OWN far edge out to the whole texel, so a dot that happens to sit against the cell
// edge gains half a texel (1 → 1.5 here) and every other dot is untouched. Half a texel of a
// dither dot reads as ~50% tone either way, which is why the shades need no special case.
expect(rects.length).toBeGreaterThan(10)
for (const [, , w, h] of rects) {
expect(w).toBeLessThanOrEqual(1.5)
expect(h).toBeLessThanOrEqual(1.5)
}
// And the tone is still a tone: ▒ is a 2-of-8 pattern, nowhere near a filled cell.
const inked = rects.reduce((sum, [, , w, h]) => sum + w * h, 0)
expect(inked).toBeLessThan(0.4 * FRAC_COLS_W * FRAC_COLS_H)
})
})
})
/**
* The shrink factor on its own — the arithmetic, without a canvas in the way.
*
* Separate from the draw tests because the interesting cases are the EDGES (the tolerance, the
* floor, a platform that reports no ink box), and each of those is one number rather than a
* rendering.
*/
describe('underline', () => {
/**
* Reported 2026-08-05: a hovered link showed no underline in shared mode while GPU mode drew one.
* The cause was broader than links — `FLAG_UNDERLINE` was written by the feed and read by nobody,
* so NO underline rendered at all, including a plain `\e[4m` run.
*/
it('draws a rule at the bottom of the cell, spanning the WHOLE-TEXEL box', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.draw(0x41, false, false, INK_X, INK_Y, FG, BG, 'whole', true)
const rule = stub.ops.filter((o) => o.kind === 'fillRect').at(-1)!
// Full box width, not the fractional cell: consecutive underlined cells have to JOIN, and a
// rule that stopped inside the partial edge texel would dash at every cell boundary.
expect(rule.args[0]).toBe(INK_X)
expect(rule.args[2]).toBe(COLS_W)
// Bottom of the cell, in the FOREGROUND colour.
expect(rule.args[1]).toBe(INK_Y + COLS_H - 1)
expect(rule.fill).toBe(FG_CSS)
})
it('draws NOTHING extra when the cell is not underlined', () => {
const plain = stubCanvas()
active = plain
createCanvasRasterizer(FONT, 256)!.draw(0x41, false, false, INK_X, INK_Y, FG, BG)
const underlined = stubCanvas()
active = underlined
createCanvasRasterizer(FONT, 256)!.draw(0x41, false, false, INK_X, INK_Y, FG, BG, 'whole', true)
expect(underlined.ops.length).toBeGreaterThan(plain.ops.length)
})
})
describe('strikethrough', () => {
it('draws a rule across the MIDDLE of the cell, spanning the WHOLE-TEXEL box', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.draw(0x41, false, false, INK_X, INK_Y, FG, BG, 'whole', false, true)
const rule = stub.ops.filter((o) => o.kind === 'fillRect').at(-1)!
expect(rule.args[0]).toBe(INK_X)
expect(rule.args[2]).toBe(COLS_W)
// Row 9 of a 20-row cell, 1px thick: the row xterm's WebGL stroke paints (centred on 10 - 0.5).
expect(rule.args[1]).toBe(INK_Y + 9)
expect(rule.args[3]).toBe(1)
expect(rule.fill).toBe(FG_CSS)
})
it('draws NOTHING extra when the cell is not struck', () => {
const plain = stubCanvas()
active = plain
createCanvasRasterizer(FONT, 256)!.draw(0x41, false, false, INK_X, INK_Y, FG, BG)
const struck = stubCanvas()
active = struck
createCanvasRasterizer(FONT, 256)!.draw(0x41, false, false, INK_X, INK_Y, FG, BG, 'whole', false, true)
expect(struck.ops.length).toBeGreaterThan(plain.ops.length)
})
it('draws BOTH rules when a cell is underlined and struck', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.ops.length = 0
r.draw(0x41, false, false, INK_X, INK_Y, FG, BG, 'whole', true, true)
const rules = stub.ops.filter((o) => o.kind === 'fillRect' && o.args[2] === COLS_W && o.fill === FG_CSS)
const ys = rules.map((o) => o.args[1])
expect(ys).toContain(INK_Y + COLS_H - 1)
expect(ys).toContain(INK_Y + 9)
})
})
describe('strikethroughThickness', () => {
it("follows xterm's WebGL rule, so the weight matches the renderer beside it", () => {
expect(strikethroughThickness(10)).toBe(1)
expect(strikethroughThickness(20)).toBe(2)
expect(strikethroughThickness(35)).toBe(3)
})
it('never rounds away to nothing', () => {
expect(strikethroughThickness(8)).toBe(1)
expect(strikethroughThickness(0)).toBe(1)
expect(strikethroughThickness(NaN)).toBe(1)
})
})
describe('underlineThickness', () => {
it("follows xterm's own rule, so the weight matches the renderer beside it", () => {
expect(underlineThickness(15)).toBe(1)
expect(underlineThickness(30)).toBe(2)
expect(underlineThickness(45)).toBe(3)
})
it('never rounds away to nothing — an absent underline IS the bug', () => {
expect(underlineThickness(8)).toBe(1)
expect(underlineThickness(0)).toBe(1)
expect(underlineThickness(NaN)).toBe(1)
})
})
describe('shrinkToFit', () => {
const metrics = (left: number, right: number): TextMetrics =>
({ actualBoundingBoxLeft: left, actualBoundingBoxRight: right }) as TextMetrics
it('returns exactly 1 for ink that fits, so the caller takes the untouched path', () => {
expect(shrinkToFit(metrics(0, 8), 10)).toBe(1)
expect(shrinkToFit(metrics(2, 6), 10)).toBe(1)
})
it('scales an oversized glyph down to its allowance', () => {
expect(shrinkToFit(metrics(0, 14), 10)).toBeCloseTo(10 / 14)
// The ink box is measured either side of the ORIGIN — a glyph with a left side bearing that
// reaches back past it is just as oversized as one that runs long to the right.
expect(shrinkToFit(metrics(4, 10), 10)).toBeCloseTo(10 / 14)
})
it('tolerates a small overhang', () => {
expect(shrinkToFit(metrics(0, 10.4), 10)).toBe(1) // 4% — the fringe
expect(shrinkToFit(metrics(0, 10.5), 10)).toBeLessThan(1) // past it
})
it('stops shrinking at the floor — a legible fragment beats an illegible whole', () => {
// 25px in a 10px cell would be a 0.4 scale. Clamped, so the excess is clipped as it always was
// (L16) rather than rendering something too small to read.
expect(shrinkToFit(metrics(0, 25), 10)).toBe(0.6)
})
it('declines to shrink when the platform reports no usable ink box', () => {
// The failure to avoid is a NaN scale silently blanking every glyph. Declining restores the
// pre-2026-08-05 behaviour for that platform, which is a correct outcome, not a broken one.
expect(shrinkToFit({} as TextMetrics, 10)).toBe(1)
expect(shrinkToFit(metrics(NaN, NaN), 10)).toBe(1)
expect(shrinkToFit(metrics(0, 0), 10)).toBe(1)
expect(shrinkToFit(metrics(0, 14), 0)).toBe(1)
})
})
/**
* The line between "this glyph may be shrunk" and "this glyph must be left alone" is not a ratio —
* bold-italic `X` measures 1.25 of its advance and so does the icon shrink-to-fit was written for.
* It is what the character IS.
*/
describe('shrinkEligible', () => {
it('refuses every letter, digit and ASCII punctuation', () => {
for (const ch of 'AZaz09.,;:!?-_/\\|()[]{}<>@#$%^&*+="\'`~') {
expect(shrinkEligible(ch.codePointAt(0) as number), ch).toBe(false)
}
})
it('refuses accented and non-Latin TEXT, which overhangs for the same reasons', () => {
for (const ch of 'çğışöüÇĞİŞÖÜéèñåøαβγдж') {
expect(shrinkEligible(ch.codePointAt(0) as number), ch).toBe(false)
}
})
it('allows the symbols drawn to a box — the class the shrink exists for', () => {
for (const ch of '⧉⎿★⭐▪◆➜✦☑⏺🎉👍') {
expect(shrinkEligible(ch.codePointAt(0) as number), ch).toBe(true)
}
})
})
/**
* The 2026-08-09 report — external feedback that "the terminal text isn't so crisp", confirmed by
* the author comparing Shared against GPU per terminal on a Retina display.
*
* The atlas was already measured innocent on resolution (dumped `cellH` 36 at dpr 2, i.e. device
* pixels), the sampler is NEAREST at zoom >= 1, the pan is snapped to whole device pixels and the
* drawing buffer follows the dpr. What was left was WEIGHT: this file built its font string with no
* weight token at all for regular text and the literal `bold` for bold, so `settings.fontWeight` /
* `fontWeightBold` were silently discarded. Invisible at the defaults — no token means 400 and
* `bold` means 700, which is exactly the default pair — and LIGHTER than the GPU renderer beside it
* for anyone who had moved the picker.
*/
describe('font weight reaches the rasterized glyph', () => {
const fontAt = (weight: number, weightBold: number) => ({
family: 'monospace',
sizePx: 16,
cellW: 10,
cellH: 20,
weight,
weightBold
})
const fontStringFor = (weight: number, weightBold: number, bold: boolean): string => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(fontAt(weight, weightBold), 256)!
stub.ops.length = 0
r.draw(0x41, bold, false, INK_X, INK_Y, FG, BG)
return stub.ops.find((o) => o.kind === 'fillText')?.font ?? ''
}
it('uses the configured regular weight, not the CSS default', () => {
expect(fontStringFor(500, 700, false)).toContain('500 16px')
})
it('uses the configured BOLD weight, not the `bold` keyword', () => {
// The keyword is 700 and nothing else, so it silently discarded a user's 600 or 800.
expect(fontStringFor(400, 600, true)).toContain('600 16px')
expect(fontStringFor(400, 600, true)).not.toContain('bold')
})
it('still produces the historical string at the DEFAULT weights', () => {
// 400/700 is what "no token" and "bold" already meant, so nobody on defaults sees a change.
expect(fontStringFor(400, 700, false)).toContain('400 16px')
expect(fontStringFor(400, 700, true)).toContain('700 16px')
})
})
/**
* THE BLANK-EVERYTHING BUG the sentinel exists for.
*
* The atlas page is an OffscreenCanvas 2D context, and a GPU reset (sleep/wake, a driver hiccup)
* blanks its backing store. Nothing downstream notices: `GlyphAtlas.slots` still holds every key, so
* no glyph is ever re-rasterized, and `engine.reviveGpu` re-uploads the now-EMPTY page as the atlas
* texture. Every terminal on the canvas shows empty cells at once, for the rest of the session.
*
* One texel of known colour, checked with a 1px readback, is what turns that into a detectable
* event — including the silent case, where the 2D context fires no `contextlost` at all.
*/
describe('sentinelIntact', () => {
it('accepts the sentinel colour', () => {
expect(sentinelIntact([...ATLAS_SENTINEL_RGBA])).toBe(true)
})
it('REJECTS transparent-black, which is what a blanked page reads back as', () => {
expect(sentinelIntact([0, 0, 0, 0])).toBe(false)
})
it('rejects an opaque black or white page — a wipe need not be to transparent', () => {
expect(sentinelIntact([0, 0, 0, 255])).toBe(false)
expect(sentinelIntact([255, 255, 255, 255])).toBe(false)
})
it('tolerates a few units of colour-management rounding either way', () => {
expect(sentinelIntact([252, 3, 251, 255])).toBe(true)
})
it('rejects a short buffer rather than reading past the end', () => {
expect(sentinelIntact([255, 0, 255])).toBe(false)
})
})
describe('atlas page health', () => {
it('reports the page intact right after construction', () => {
const stub = stubCanvas()
active = stub
expect(createCanvasRasterizer(FONT, 256)!.sourceIntact()).toBe(true)
})
it('reports the page intact after a clearPage, because a reset repaints the sentinel', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
r.clearPage()
expect(r.sourceIntact()).toBe(true)
})
it('reports LOST when the backing store was wiped behind our back', () => {
// Exactly the silent case: no event fired, `slots` still full, and the next `reviveGpu` would
// upload an empty page over every terminal on the canvas.
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.blankPage()
expect(r.sourceIntact()).toBe(false)
})
it('reports LOST on isContextLost() without needing the readback', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
stub.setContextLost(true)
expect(r.sourceIntact()).toBe(false)
})
it('routes contextlost / contextrestored to the caller and does NOT cancel the loss', () => {
// Cancelling `contextlost` tells the browser not to restore automatically, which is the
// opposite of what this wants: the restore is the signal that a fresh page can be built.
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
const seen: string[] = []
r.onSourceLoss({ lost: () => seen.push('lost'), restored: () => seen.push('restored') })
expect(stub.fire('contextlost')).toBe(false)
stub.fire('contextrestored')
expect(seen).toEqual(['lost', 'restored'])
})
it('dispose() unsubscribes, so a rebuilt context never hears the old page`s events', () => {
const stub = stubCanvas()
active = stub
const r = createCanvasRasterizer(FONT, 256)!
const seen: string[] = []
const sub = r.onSourceLoss({ lost: () => seen.push('lost'), restored: () => undefined })
sub.dispose()
expect(stub.listenerCount()).toBe(0)
stub.fire('contextlost')
expect(seen).toEqual([])
})
})