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 { describe, it, expect } from 'vitest'
import { readFileSync } from 'node:fs'
import { join } from 'node:path'
/**
* Guards on the stylesheet's theming, written after the light theme shipped with a black canvas
* and a dark sessions sidebar.
*
* The bug was not any one rule — it was the AUDIT. The literals were found by listing the most
* frequent colours, which silently skips the ones used once: `.react-flow { background: #000000 }`
* is the entire canvas and appeared exactly once. A test doesn't get bored at entry 26.
*/
// `.replace(/\r\n/g, '\n')` on every read below: a test that reads a checked-in file must not
// care how git checked it out. Git for Windows defaults to `core.autocrlf=true`, so a Windows
// clone has CRLF working files, and a slice on a literal containing `\n` (`indexOf('}\n}')`,
// `indexOf('\n}\n')`) then matches nothing and the assertion fails on a checkout with zero local
// changes (issue #578). `.gitattributes` is the durable half of the fix; this is the half that
// survives a working tree that was checked out before it landed.
const CSS = readFileSync(join(__dirname, 'styles.css'), 'utf8').replace(/\r\n/g, '\n')
/**
* Where the light block actually starts. This MUST be anchored to the selector at the start of a
* line: a plain `indexOf(":root[data-theme='light']")` matches the *doc comment* inside the `:root`
* block that points at it (styles.css line ~6), which is 90 lines too early. That is not a
* cosmetic slip — it silently hollowed out two suites below. `dark` collapsed to three lines, so
* "the light theme overrides every themeable token" passed with an EMPTY token list for every
* token added since; and `LIGHT` resolved to the tail of the DARK block, so the contrast floors
* were measuring the dark palette against itself. Keep the `^` anchor.
*/
const LIGHT_BLOCK_START = CSS.search(/^:root\[data-theme='light'\]\s*\{/m)
/** Everything before the end of the `:root[data-theme='light']` block — where literals belong. */
const TOKEN_BLOCK_END = CSS.indexOf('\n}\n', LIGHT_BLOCK_START) + 3
const RULES = CSS.slice(TOKEN_BLOCK_END)
/** The two token blocks, sliced once. */
const DARK = CSS.slice(CSS.indexOf(':root {'), LIGHT_BLOCK_START)
const LIGHT = CSS.slice(LIGHT_BLOCK_START, TOKEN_BLOCK_END)
function luminance(r: number, g: number, b: number): number {
return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255
}
function parseColor(lit: string): { lum: number; alpha: number } | null {
const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(lit.trim())
if (hex) {
const h = hex[1].length === 3 ? [...hex[1]].map((c) => c + c).join('') : hex[1]
return {
lum: luminance(parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)),
alpha: 1
}
}
const rgb = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)$/i.exec(lit.trim())
if (rgb) {
return {
lum: luminance(+rgb[1], +rgb[2], +rgb[3]),
alpha: rgb[4] === undefined ? 1 : +rgb[4]
}
}
return null
}
/**
* Scrims: a translucent wash whose JOB is to darken whatever is under it. Black is correct in
* both themes, so these are the one legitimate place for a literal dark background. Listed
* explicitly, so adding one is a decision rather than an oversight.
*/
const SCRIM_ALPHA_MAX = 0.8
describe('every opaque surface is themed', () => {
// `background: <literal>` outside the token block. An opaque near-black or near-white here is a
// surface that will not follow the theme — exactly the canvas/dock/sidebar failure.
const offenders: string[] = []
let selector = ''
const lines = RULES.split('\n')
lines.forEach((line, i) => {
if (line.includes('{')) selector = line.split('{')[0].trim() || selector
const decl = /^\s*background(?:-color)?:\s*([^;]+);/.exec(line)
if (!decl) return
// Drop `var(--x, <fallback>)` wholesale before looking for literals: a fallback is only
// reached when the variable is undefined, and the previous test already proves none are.
// An explicit `theme-exempt:` comment on the line above opts a rule out — the QR quiet zone
// is content, not chrome, and has to stay light in both themes. A marker makes that a stated
// decision instead of an oversight, which is the whole point of this test.
if (lines[i - 1]?.includes('theme-exempt:') || lines[i - 2]?.includes('theme-exempt:')) return
const value = decl[1].replace(/var\([^)]*\)/g, '')
for (const lit of value.match(/#[0-9a-fA-F]{3,8}|rgba?\([^)]*\)/g) ?? []) {
const c = parseColor(lit)
if (!c) continue
const extreme = c.lum < 0.25 || c.lum > 0.85
if (extreme && c.alpha > SCRIM_ALPHA_MAX) {
offenders.push(`${selector || '?'} (line ~${i + 1}): ${lit}`)
}
}
})
it('has no un-themed near-black or near-white background', () => {
expect(offenders).toEqual([])
})
})
describe('every CSS variable resolves', () => {
// `var(--label, #fff)` looked themed and was not: `--label` never existed, so every one of those
// sites was a hardcoded white. A referenced-but-undefined variable is either that trap or a
// typo — unless the renderer sets it at runtime.
const SET_FROM_JS = new Set([
'--term-bg', // App.tsx, from the terminal theme
'--term-glass-bg', // TerminalNode, glass tint per node theme (lib/glassContrast.ts)
'--term-glass-header-bg',
'--term-glass-fg',
'--term-glass-chip-wash', // TerminalNode, status-chip wash per theme (glassChipWash)
'--term-glass-backdrop', // TerminalNode, backdrop squeeze per node (glassBackdropFilter)
'--glass-node-bg', // App.tsx, canvas-card fill at the slider's alpha (glassSurfaceAlpha)
'--glass-node-squeeze', // App.tsx, canvas-card backdrop squeeze (glassChromeBackdropRange)
'--glass-chrome-bg', // App.tsx, Liquid Glass chrome fill (lib/glassContrast.ts glassChromeAlpha)
'--glass-control-bg', // App.tsx, Liquid Glass small-control fill (glassChromeAlphas)
'--glass-refract', // App.tsx, the rim refraction, only left of the Readable tick (glassRefractionOn)
'--frost-x', // GlassFrostSync, the wallpaper's box in flow units, written onto each frost layer
'--frost-y',
'--frost-w',
'--frost-h',
'--node-x', // TerminalNode, the node's absolute flow position (its frost layer)
'--node-y',
'--glass-fill', // GlassSlider, the slider value (fills the track)
'--glass-tick', // GlassSlider, the Readable tick position (the notch)
'--peer-color', // presence chips, per peer
'--group-label-boost', // GroupNode, zoom-compensated label size
'--mascot-w',
'--mascot-h',
'--cmascot-w',
'--cmascot-h',
'--cmascot-sheet-w',
'--cmascot-sheet-h', // notch HUD sprite sheets
'--swimlane-color', // GlobalKanbanView swimlane left border, per project
'--chat-complete-max' // ChatComposer, the `/` menu's room above the composer (completeMenuMax)
])
it('references no variable that is never defined', () => {
const defined = new Set(Array.from(CSS.matchAll(/^\s*(--[a-z0-9-]+)\s*:/gm), (x) => x[1]))
const used = new Set(Array.from(CSS.matchAll(/var\(\s*(--[a-z0-9-]+)/g), (x) => x[1]))
const dangling = [...used].filter((v) => !defined.has(v) && !SET_FROM_JS.has(v)).sort()
expect(dangling).toEqual([])
})
})
describe('the light theme overrides every themeable token', () => {
// A token defined in `:root` but absent from the light block keeps its DARK value on a light
// page. Colour-valued tokens must appear in both; geometry (radii, fonts) is theme-independent.
it('covers every colour token', () => {
const dark = DARK
const light = LIGHT
const colourish = (decl: string): boolean =>
/#[0-9a-f]{3,8}|rgba?\(|^\s*\d+,\s*\d+,\s*\d+\s*$/i.test(decl)
const darkTokens = Array.from(dark.matchAll(/^\s*(--[a-z0-9-]+)\s*:\s*([^;]+);/gm))
.filter(([, , v]) => colourish(v))
.map(([, k, v]) => [k, v] as const)
const lightTokens = new Set(
Array.from(light.matchAll(/^\s*(--[a-z0-9-]+)\s*:/gm), (x) => x[1])
)
// The git-graph lane hues are branch IDENTITY, not chrome: they must stay the same colour in
// both themes or a graph would change meaning when the theme flips.
const themeIndependent = (k: string): boolean => k.startsWith('--git-graph-')
// A token mixed ONLY from `--tint-rgb` already flips with the theme by construction — that
// triple is itself overridden in the light block, which is the whole point of routing ~280
// overlays through it. `--text: rgba(var(--tint-rgb), 0.85)` is the live example: it is
// deliberately NOT restated in the light block (only `--muted`/`--border`, whose alphas had to
// be raised to buy back the contrast warmth costs). Requiring a redundant restatement here
// would teach the next person to copy tokens that are already correct.
const followsTint = (v: string): boolean =>
/^\s*rgba?\(\s*var\(--tint-rgb\)[^)]*\)\s*$/.test(v)
const missing = darkTokens
.filter(([k]) => !lightTokens.has(k) && !themeIndependent(k))
.filter(([, v]) => !followsTint(v))
.map(([k]) => k)
expect(missing).toEqual([])
})
})
/**
* Contrast floors for the LIGHT palette.
*
* The light theme was re-tuned warm because pure white surfaces with pure black ink read as glare.
* Warmth costs contrast — brown on cream is a shorter range than black on white — so the numbers
* that made the re-tune safe are asserted here rather than claimed in a comment. Nudging a surface
* a few points paler, or an ink alpha down, is exactly the kind of change that looks harmless and
* quietly drops body text under the floor.
*/
describe('light palette contrast', () => {
/**
* A light-palette token — falling back to the dark block when light does not restate it.
* That fall-back is not laxity: the only tokens light omits are the ones mixed purely from
* `--tint-rgb` (`--text` is the live example), which read as the LIGHT ink here because
* `--tint-rgb` itself is overridden. And a hue that genuinely went missing would resolve to its
* dark-field value and fail the contrast floor below — loudly, which is the point.
*/
function token(name: string): string {
const re = new RegExp(`^\\s*${name}\\s*:\\s*([^;]+);`, 'm')
const m = re.exec(LIGHT) ?? re.exec(DARK)
if (!m) throw new Error(`neither token block defines ${name}`)
return m[1].trim()
}
const INK = token('--tint-rgb').split(',').map((n) => +n.trim()) as [number, number, number]
function hex(h: string): [number, number, number] {
const s = h.replace('#', '')
return [0, 2, 4].map((i) => parseInt(s.slice(i, i + 2), 16)) as [number, number, number]
}
/** The ink at alpha `a`, composited over an opaque surface. */
function inkOver(a: number, bg: [number, number, number]): [number, number, number] {
return bg.map((c, i) => INK[i] * a + c * (1 - a)) as [number, number, number]
}
function luminance([r, g, b]: [number, number, number]): number {
const f = (c: number): number => {
const v = c / 255
return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4
}
return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b)
}
function contrast(a: [number, number, number], b: [number, number, number]): number {
const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x)
return (hi + 0.05) / (lo + 0.05)
}
/** The alpha out of `rgba(var(--tint-rgb), α)`. */
function inkAlpha(name: string): number {
const m = /rgba\(var\(--tint-rgb\),\s*([\d.]+)\)/.exec(token(name))
if (!m) throw new Error(`${name} is not mixed from --tint-rgb`)
return +m[1]
}
// The two surfaces body text actually sits on. `--surface-deep` is the deepest chrome (dock,
// modal shells) and carries labels rather than prose, so it is held to the 3:1 large-text floor.
const SURFACES: [string, [number, number, number]][] = [
['--bg', hex(token('--bg'))],
['--panel', hex(token('--panel'))],
['--canvas-bg', hex(token('--canvas-bg'))]
]
it.each(SURFACES)('body text clears WCAG AA on %s', (_name, bg) => {
expect(contrast(inkOver(inkAlpha('--text'), bg), bg)).toBeGreaterThanOrEqual(4.5)
})
it.each(SURFACES)('secondary text clears WCAG AA on %s', (_name, bg) => {
// This is the one the warm re-tune nearly broke: the dark theme's 0.55 measured 3.2:1 here.
expect(contrast(inkOver(inkAlpha('--muted'), bg), bg)).toBeGreaterThanOrEqual(4.5)
})
it.each(SURFACES)('the status hues and link accent stay legible on %s', (_name, bg) => {
// `--agent-working` is on this list because the sidebar's project badge paints its COUNT with
// it (`.ss-group__sig--working`) — it is text, so it owes the text floor, not the 3:1 one.
const HUES = ['--accent-text', '--danger', '--warn', '--caution', '--success', '--agent-working']
for (const t of HUES) {
expect(contrast(hex(token(t)), bg), `${t}`).toBeGreaterThanOrEqual(4.3)
}
})
it('no light surface is pure white — that brightness is the glare being avoided', () => {
for (const t of ['--bg', '--panel', '--surface-raised', '--surface-overlay', '--canvas-bg']) {
expect(luminance(hex(token(t))), t).toBeLessThan(0.97)
}
})
it('the canvas sits below the panels, so nodes keep their edges', () => {
expect(luminance(hex(token('--canvas-bg')))).toBeLessThan(luminance(hex(token('--bg'))))
})
})