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
/**
* The contrast guarantee behind glass terminal nodes.
*
* A glass node paints the terminal theme's background as a translucent tint over whatever is
* behind it (a wallpaper, the canvas), so the effective background of every glyph is
* `tint·a + backdrop·(1−a)`. The backdrop is unknowable — any pixel of any wallpaper.
*
* Why checking pure white and pure black is enough: contrast depends only on luminance, and the
* composite's luminance rises monotonically with each backdrop channel, so EVERY backdrop's
* composite lies in the luminance interval [composite over black, composite over white]. Against a
* fixed text colour, contrast falls as the background's luminance approaches the text's and rises
* away from it — so over that interval the worst case is an endpoint, UNLESS the text's own
* luminance falls inside the interval, where some backdrop matches it exactly (ratio 1). That case
* is checked explicitly (`worstContrast`) and fails. For the built-in themes' foregrounds it never
* arises at a ≥ 0.55: the tint then dominates the composite, keeping the whole interval on the
* tint's side of the text. `glassContrast.test.ts` samples grey backdrops to pin the claim.
*
* Compositing is in gamma-encoded sRGB, the way the browser blends an rgba() fill; the WCAG
* relative luminance is computed on the result.
*
* Pure and platform-free (no DOM), so it runs under vitest's node environment.
*/
type Rgb = readonly [number, number, number]
/** `#rgb`, `#rrggbb` or `#rrggbbaa` (alpha ignored) → 0..255 channels; null when unparseable. */
export function parseHex(hex: string): Rgb | null {
const m = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(hex.trim())
if (!m) return null
let h = m[1]
if (h.length === 3) h = h.replace(/./g, (c) => c + c)
return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)]
}
function channelLuminance(c: number): number {
const s = c / 255
return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4)
}
export function relativeLuminance([r, g, b]: Rgb): number {
return 0.2126 * channelLuminance(r) + 0.7152 * channelLuminance(g) + 0.0722 * channelLuminance(b)
}
export function contrastRatio(a: Rgb, b: Rgb): number {
const la = relativeLuminance(a)
const lb = relativeLuminance(b)
return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05)
}
/** `tint` at `alpha` over `backdrop`, in sRGB (what `background: rgba(...)` renders). */
export function composite(tint: Rgb, backdrop: Rgb, alpha: number): Rgb {
return [0, 1, 2].map((i) => tint[i] * alpha + backdrop[i] * (1 - alpha)) as unknown as Rgb
}
export const GLASS_ALPHA_MIN = 0.55
export const GLASS_ALPHA_MAX = 0.95
const WHITE: Rgb = [255, 255, 255]
const BLACK: Rgb = [0, 0, 0]
const STEP = 0.005
/** The lowest contrast `fg` can have against the tint over ANY backdrop (see the module header).
* `lo`/`hi` narrow the backdrop to sRGB greys lo..hi (0..1), the range `glassBackdropFilter` squeezes
* it into; the endpoint argument holds unchanged, since every channel then lies in that range. */
export function worstContrast(fg: Rgb, tint: Rgb, alpha: number, lo = 0, hi = 1): number {
const overLo = composite(tint, lo === 0 ? BLACK : grey(lo), alpha)
const overHi = composite(tint, hi === 1 ? WHITE : grey(hi), alpha)
const l = relativeLuminance(fg)
if (l > relativeLuminance(overLo) && l < relativeLuminance(overHi)) return 1
return Math.min(contrastRatio(fg, overHi), contrastRatio(fg, overLo))
}
function grey(v: number): Rgb {
return [v * 255, v * 255, v * 255]
}
function passes(fg: Rgb, tint: Rgb, alpha: number, minRatio: number): boolean {
return worstContrast(fg, tint, alpha) >= minRatio
}
/**
* The smallest tint alpha at which `fg` keeps `minRatio` contrast over BOTH a white and a black
* backdrop, floored at 0.55 so the glass never gets clearer than that.
*
* Scanned DOWN from opaque, stopping at the first failure. Contrast is not monotonic in alpha when
* the fg's luminance lies between the backdrop's and the tint's (light text on a dark tint over
* white: the composite passes through the text's own grey), so a scan up from 0 could return an
* alpha whose neighbours above it fail. Scanning down returns the bottom of the contiguous passing
* range that reaches opaque, so every alpha at or above the answer passes.
*
* The design ceiling is 0.95, and for every built-in theme but the two Solarized ones the answer
* sits under it (measured: 0.62–0.885). The guarantee outranks the ceiling, though — readable text
* is the load-bearing requirement and "never fully opaque" is a look:
* - Solarized Dark (opaque contrast 4.75) needs 0.985, and gets it.
* - Solarized Light is 4.13:1 OPAQUE — under 4.5 before any glass — so no alpha passes. It gets 1:
* the glass can only match the theme's own contrast, and 1 is the one alpha that never makes it
* worse. `glassContrast.test.ts` pins both as named exceptions.
* Unparseable colours get the ceiling.
*/
export function glassTintAlpha(fg: string, tint: string, minRatio = 4.5): number {
const f = parseHex(fg)
const t = parseHex(tint)
if (!f || !t) return GLASS_ALPHA_MAX
let lowest = Infinity
for (let i = Math.round(1 / STEP); i >= 0; i--) {
const a = i * STEP
if (!passes(f, t, a, minRatio)) break
lowest = a
}
if (lowest === Infinity) return 1
return Math.max(GLASS_ALPHA_MIN, lowest)
}
/* ------------------------------------------------------------------------------------------- *
* Backdrop squeeze: readable at EVERY slider position.
*
* Left of the Readable tick the tint alone cannot hold its ratio over any backdrop (at Clear, 0.05,
* every built-in theme measures about 1:1: dark text over a black wallpaper, light text over a
* white one). So the backdrop filter squeezes the wallpaper into a range the tint CAN cover before
* the tint lands on it: light glass lifts it to a floor (`contrast(c) brightness(b)` maps 0..1 to
* lo..1), dark glass caps it (`brightness(hi)` maps 0..1 to 0..hi). Shapes and colour still show,
* at lower contrast, which is what Clear should mean: more wallpaper, never less text. Both are
* colour-matrix filters: per-pixel arithmetic, far cheaper than the blur they follow. Glass that
* needs no squeeze gets no filter at all (`glassBackdropFilter` returns null). CSS filter
* functions work per channel on gamma-encoded sRGB, the same space `composite` blends in
* (measured: predicted 153, rendered 154).
*
* The promise slides with the slider (`glassMinRatio`): 3:1 at Clear, 4.5:1 from the Readable
* tick. Picked by eye over light and dark wallpapers in both themes: 4.5:1 at Clear dimmed a
* bright wallpaper to brown and washed a dark one to grey, and Clear stopped looking clear.
* ------------------------------------------------------------------------------------------- */
/** From the Readable tick on, light glass lifts a black backdrop at least this far (sRGB grey,
* 0..1): without it light glass over a dark wallpaper reads as muddy grey, not frost. Left of the
* tick it fades out (`glassFrostFloor`) so Clear keeps the wallpaper's colour. The chrome's
* `--glass-frost` in styles.css is this floor (pinned by glassContrast.test.ts). */
export const GLASS_LIGHT_FROST = 0.5
/** The contrast a glass surface's text keeps at Clear: WCAG's large-text minimum. */
export const GLASS_CLEAR_RATIO = 3
/** The contrast promised at slider position `t`: GLASS_CLEAR_RATIO at Clear, rising to 4.5:1 at
* the Readable tick and holding it to Tinted. */
export function glassMinRatio(t: number): number {
return GLASS_CLEAR_RATIO + (4.5 - GLASS_CLEAR_RATIO) * Math.min(1, t / GLASS_READABLE_TICK)
}
/** The light-glass frost floor at slider position `t`: 0 at Clear, GLASS_LIGHT_FROST from the tick. */
export function glassFrostFloor(t: number): number {
return GLASS_LIGHT_FROST * Math.min(1, t / GLASS_READABLE_TICK)
}
/** The sRGB grey range (0..1) the backdrop is squeezed into. */
export interface BackdropRange {
lo: number
hi: number
}
/**
* The gentlest squeeze that keeps `fg` at `minRatio` (or the theme's own opaque contrast, if lower)
* on `tint`@`alpha`: light glass gets the LOWEST floor (never below `floor`), dark glass the
* HIGHEST ceiling. Both are monotone in the bound, so a bisection finds them; at or right of the
* Readable tick dark glass needs none (hi = 1).
*/
export function glassBackdropRange(
fg: Rgb,
tint: Rgb,
alpha: number,
minRatio = 4.5,
floor = GLASS_LIGHT_FROST
): BackdropRange {
const target = Math.min(minRatio, contrastRatio(fg, tint))
const light = relativeLuminance(fg) < relativeLuminance(tint)
const ok = (v: number): boolean =>
(light ? worstContrast(fg, tint, alpha, v, 1) : worstContrast(fg, tint, alpha, 0, v)) >= target
return bisectRange(light, ok, floor)
}
/**
* `glassBackdropRange` for a chrome-coloured surface whose text is the app's translucent `--text`
* (canvas cards: subagent, files, loop, trigger, dino). The ink moves with the backdrop, so this
* samples like `glassChromeAlpha`, with every backdrop first squeezed into the candidate range.
* Null when a colour cannot be parsed.
*/
export function glassChromeBackdropRange(
text: string,
panel: string,
alpha: number,
minRatio = 4.5,
floor = GLASS_LIGHT_FROST
): BackdropRange | null {
const t = parseCssColor(text)
const p = parseCssColor(panel)
if (!t || !p) return null
const light = relativeLuminance(p.rgb) > relativeLuminance(t.rgb)
const squeeze = (b: Rgb, v: number): Rgb =>
(light ? b.map((c) => v * 255 + c * (1 - v)) : b.map((c) => c * v)) as unknown as Rgb
const ok = (v: number): boolean => CHROME_BACKDROPS.every((b) => chromeContrast(t, p.rgb, alpha, squeeze(b, v)) >= minRatio)
return bisectRange(light, ok, floor)
}
/** The shared search of both squeezes: the lowest passing floor (light, from `floor` up) or the
* highest passing ceiling (dark, from 1 down). `ok` is monotone in the bound. */
function bisectRange(light: boolean, ok: (v: number) => boolean, floor: number): BackdropRange {
let pass = light ? 1 : 0
let fail = light ? floor : 1
if (ok(fail)) return light ? { lo: fail, hi: 1 } : { lo: 0, hi: 1 }
if (!ok(pass)) return light ? { lo: 1, hi: 1 } : { lo: 0, hi: 0 }
for (let i = 0; i < 12; i++) {
const mid = (pass + fail) / 2
if (ok(mid)) pass = mid
else fail = mid
}
return light ? { lo: pass, hi: 1 } : { lo: 0, hi: pass }
}
/** The CSS for a squeeze, appended to a surface's backdrop-filter; null when none is needed. Each
* bound moves 1/255 the safe way so the 3-decimal rounding can never cost contrast. */
export function glassBackdropFilter({ lo, hi }: BackdropRange): string | null {
if (lo > 0) {
const l = Math.min(1, lo + 1 / 255)
const c = (1 - l) / (1 + l)
return `contrast(${c.toFixed(3)}) brightness(${(2 / (1 + c)).toFixed(3)})`
}
if (hi < 1) return `brightness(${Math.max(0, hi - 1 / 255).toFixed(3)})`
return null
}
/* Status chips on a glass header (styles.css `.term-node__status` under Liquid Glass): the label
is the terminal foreground, and the chip behind it is a wash of the status hue. The wash moves
the surface under the text, so it gets the same treatment as the tint: the LARGEST wash (up to
GLASS_CHIP_WASH_MAX) at which the foreground keeps 4.5:1 for every hue a badge can take, over
any backdrop. A fixed wash cannot do it — measured, One Dark's yellow chip falls to 3.93:1 at
12% — and a theme with no margin (Solarized Dark) gets 0, where the chip is its ring alone. */
export const GLASS_CHIP_WASH_MAX = 0.24
/** Every hue a glass status badge can be: the text-safe and fill tokens those badges read under
* Liquid Glass, dark then light values (styles.palette.test.ts pins them to the stylesheet). */
export const GLASS_CHIP_HUES = [
'#30d158', '#6cb0ff', '#ff9f0a', '#ff453a', '#ffd60a', '#98989d', '#bf5af2',
'#1f7a38', '#0060df', '#a85c00', '#c62a1f', '#34c759', '#806100', '#8e8e93', '#af52de'
]
/** The glass header's own layer over the node tint (see `glassTint().header`). */
const HEADER_LAYER_ALPHA = 0.35
const CHIP_BACKDROPS: Rgb[] = (() => {
const out: Rgb[] = []
for (const r of [0, 255]) for (const g of [0, 255]) for (const b of [0, 255]) out.push([r, g, b])
for (let v = 0; v <= 255; v += 5) out.push([v, v, v])
return out
})()
const chipWashCache = new Map<string, number>()
/** Largest status-chip wash keeping `fg` at 4.5:1 on a glass header tinted `bg` at `alpha`. */
export function glassChipWash(fg: string, bg: string, alpha: number): number {
const key = `${fg}|${bg}|${alpha.toFixed(3)}`
const hit = chipWashCache.get(key)
if (hit !== undefined) return hit
const f = parseHex(fg)
const b = parseHex(bg)
const hues = GLASS_CHIP_HUES.map((h) => parseHex(h)!)
let best = 0
if (f && b) {
const heads = CHIP_BACKDROPS.map((d) => composite(b, composite(b, d, alpha), HEADER_LAYER_ALPHA))
for (let i = 1; i <= Math.round(GLASS_CHIP_WASH_MAX * 100); i++) {
const w = i / 100
if (!heads.every((h) => hues.every((hue) => contrastRatio(f, composite(hue, h, w)) >= 4.5))) break
best = w
}
}
chipWashCache.set(key, best)
return best
}
export interface GlassTint {
/** The node's glass fill, `rgba(r, g, b, a)`. */
background: string
/** The header's extra layer on top of it — slightly more opaque in total. */
header: string
/** The status-chip wash for this theme, as a CSS percentage (`glassChipWash`). */
chipWash: string
/** The theme foreground: header text sits on the TERMINAL's tint, so it takes the terminal's
* text colour, not the app's (a light app theme over a dark terminal theme measured 1.31:1). */
foreground: string
/** The fill's alpha as a number — app-painted cell backgrounds follow it
* (`terminal/glass-cell-backgrounds.ts`). */
alpha: number
/** The backdrop squeeze for this alpha (`glassBackdropFilter`), appended to the node's blur;
* null when the tint alone holds the contrast. */
backdrop: string | null
}
/** CSS for a theme's glass at a Glass-slider position (default: the Readable tick), or null when
* its background is not a colour we can parse. */
export function glassTint(
theme: { background?: string; foreground?: string },
slider: number = GLASS_READABLE_TICK,
a11y: GlassA11y = NO_GLASS_A11Y
): GlassTint | null {
const bg = theme.background ? parseHex(theme.background) : null
if (!bg) return null
const foreground = theme.foreground ?? '#ffffff'
const readable = glassTintAlpha(foreground, theme.background!)
const alpha = glassSurfaceAlpha(slider, readable, a11y)
const rgb = bg.join(', ')
// Sized at the Readable tick, whatever the slider: left of it the promise is off anyway, and
// right of it a denser tint only leaves MORE room for the wash, so the tick's wash still passes —
// one computation per theme instead of a ~21k-check cache miss per slider step.
const chipWash = glassChipWash(foreground, theme.background!, readable)
const fg = parseHex(foreground)
const t = a11y.moreContrast ? 1 : slider
const backdrop = fg ? glassBackdropFilter(glassBackdropRange(fg, bg, alpha, glassMinRatio(t), glassFrostFloor(t))) : null
return {
background: `rgba(${rgb}, ${alpha.toFixed(3)})`,
header: `rgba(${rgb}, ${HEADER_LAYER_ALPHA})`,
chipWash: `${Math.round(chipWash * 100)}%`,
foreground,
alpha,
backdrop
}
}
/* ------------------------------------------------------------------------------------------- *
* Liquid Glass CHROME (tab bar, dock, menus, sidebar, dialogs, Settings, non-terminal nodes).
*
* Same guarantee, one difference that matters: the app's `--text` is itself TRANSLUCENT
* (`rgba(var(--tint-rgb), 0.85)`), so the ink a user sees is the text colour blended over the
* surface it sits on — and that surface is now a blend over an unknown backdrop. The foreground
* therefore moves WITH the backdrop, which breaks the white/black endpoint argument above (it
* assumes a fixed fg). So this one samples: a 6×6×6 grid of backdrop colours (every channel at
* 0, 51, …, 255) plus a grey ramp at step 5. `glassContrast.test.ts` re-checks the answer on a
* finer grey sweep for both app themes.
* ------------------------------------------------------------------------------------------- */
/** `#hex`, `rgb(r, g, b)` or `rgba(r, g, b, a)` → channels + alpha; null when unparseable. */
export function parseCssColor(css: string): { rgb: Rgb; alpha: number } | null {
const hex = parseHex(css)
if (hex) return { rgb: hex, alpha: 1 }
const m = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)$/i.exec(css.trim())
if (!m) return null
return { rgb: [Number(m[1]), Number(m[2]), Number(m[3])], alpha: m[4] === undefined ? 1 : Number(m[4]) }
}
const CHROME_BACKDROPS: Rgb[] = (() => {
const out: Rgb[] = []
for (let r = 0; r <= 255; r += 51)
for (let g = 0; g <= 255; g += 51) for (let b = 0; b <= 255; b += 51) out.push([r, g, b])
for (let v = 0; v <= 255; v += 5) out.push([v, v, v])
return out
})()
/** Contrast of (possibly translucent) text on `panel`@`alpha` over one backdrop pixel. */
export function chromeContrast(
text: { rgb: Rgb; alpha: number },
panel: Rgb,
alpha: number,
backdrop: Rgb
): number {
const surface = composite(panel, backdrop, alpha)
return contrastRatio(composite(text.rgb, surface, text.alpha), surface)
}
/** The highlight washes on glass rows (styles.css `--glass-lift` = theme ink at this alpha,
* `--glass-select` = the accent mixed at this share). Pinned to the stylesheet by
* glassContrast.test.ts, so the two cannot drift apart. */
export const GLASS_LIFT_ALPHA = 0.14
export const GLASS_SELECT_MIX = 0.3
/** A highlighted state on a chrome surface: `wash` composited over the fill, `ink` on top. */
export interface ChromeHighlight {
ink: string
wash: string
}
/** Contrast of `text` on a highlight `wash` over `panel`@`alpha` over one backdrop pixel. */
export function chromeHighlightContrast(
text: { rgb: Rgb; alpha: number },
wash: { rgb: Rgb; alpha: number },
panel: Rgb,
alpha: number,
backdrop: Rgb
): number {
return chromeContrast(text, wash.rgb, wash.alpha, composite(panel, backdrop, alpha))
}
/** The highlighted states every glass chrome surface carries, from the resolved tokens: the ink
* lift (hover, active tab) and the accent selection, both with `--text-strong` labels (styles.css
* sets that ink on them under glass). An unparseable accent drops only the selection check. */
export function glassChromeHighlights(textStrong: string, tintRgb: string, accent: string): ChromeHighlight[] {
const out: ChromeHighlight[] = [{ ink: textStrong, wash: `rgba(${tintRgb}, ${GLASS_LIFT_ALPHA})` }]
const a = parseCssColor(accent)
if (a) out.push({ ink: textStrong, wash: `rgba(${a.rgb.join(', ')}, ${GLASS_SELECT_MIX})` })
return out
}
/**
* The smallest alpha (floored at 0.55) for a chrome surface of colour `panel` that keeps `text`
* at `minRatio` over every sampled backdrop; 1 when even opaque does not reach it; null when a
* colour cannot be parsed (the caller then leaves the chrome opaque).
*
* `highlights` are the washes a row or tab lays over the same fill (hover lift, active tab,
* selected row) with the ink they carry: the fill must hold `minRatio` for EVERY one of them too.
* A lift of the theme's own ink moves the surface toward the text, so without this the plain fill
* passed and the active tab measured 3.9:1 (visual QA round 2, N2).
*/
export function glassChromeAlpha(
text: string,
panel: string,
minRatio = 4.5,
highlights: readonly ChromeHighlight[] = []
): number | null {
const t = parseCssColor(text)
const p = parseCssColor(panel)
if (!t || !p) return null
const hs = highlights.map((h) => ({ ink: parseCssColor(h.ink), wash: parseCssColor(h.wash) }))
if (hs.some((h) => !h.ink || !h.wash)) return null
const holds = (a: number, b: Rgb): boolean =>
chromeContrast(t, p.rgb, a, b) >= minRatio &&
hs.every((h) => chromeHighlightContrast(h.ink!, h.wash!, p.rgb, a, b) >= minRatio)
let lowest = Infinity
for (let i = Math.round(1 / STEP); i >= 0; i--) {
const a = i * STEP
if (!CHROME_BACKDROPS.every((b) => holds(a, b))) break
lowest = a
}
if (lowest === Infinity) return 1
return Math.max(GLASS_ALPHA_MIN, lowest)
}
/* ------------------------------------------------------------------------------------------- *
* The Glass slider (Settings → Appearance, Liquid Glass only): Clear ↔ Tinted, like iOS 26.
*
* One setting drives every glass surface, and every surface has its OWN readable alpha (the chrome
* fill, each terminal theme). So the slider is not an alpha: it is a position `t` in 0..1, and each
* surface maps it through three points — Clear at 0, its own readable alpha at the Readable tick,
* Tinted at 1. At the tick every surface sits exactly at the alpha the functions above computed,
* which is why the tick can promise 4.5:1; right of it every alpha is higher, and the scans above
* return the bottom of a range that reaches opaque, so the promise holds all the way to Tinted.
* Left of the tick is clearer than the guarantee, and the Settings row says so.
* ------------------------------------------------------------------------------------------- */
/** Tint alpha at the Clear end: never fully clear, the tint still says where a surface is. The
* backdrop squeeze, not the tint, keeps the text readable there (picked by eye: 0.2 hid the
* wallpaper's colour without buying contrast the squeeze could not give). */
export const GLASS_CLEAR_ALPHA = 0.05
/** Chrome floor at Clear for the small floating CONTROLS (dock, zoom, toolbar buttons, minimap,
* pills, tab bar): Apple's one published dimming figure ("consider adding a dark dimming layer of
* 35% opacity", materials.md). At 0.2 their icons vanished over a bright wallpaper (visual QA H4). */
export const GLASS_CONTROL_CLEAR_ALPHA = 0.35
/** Tint alpha at the Tinted end (a surface whose readable alpha is higher keeps its own). */
export const GLASS_TINTED_ALPHA = 0.95
/** Where the Readable tick sits on the track — also the default, so an untouched slider is the
* look Liquid Glass shipped with. 0.7 is close to where the chrome's readable alpha falls on a
* straight Clear→Tinted scale (dark 0.70 → 0.67, light 0.745 → 0.73), so the track reads as
* roughly linear. */
export const GLASS_READABLE_TICK = 0.7
/** `settings.glassTint` → a slider position. Absent / not a finite number = the Readable tick. */
export function resolveGlassSlider(value: unknown): number {
return typeof value === 'number' && Number.isFinite(value)
? Math.min(1, Math.max(0, value))
: GLASS_READABLE_TICK
}
/** The tint alpha of a surface whose readable alpha is `readable`, at slider position `t`.
* `clear` is the surface's alpha at the Clear end (terminal nodes 0.2, controls 0.35). */
export function glassSliderAlpha(t: number, readable: number, clear = GLASS_CLEAR_ALPHA): number {
const tinted = Math.max(readable, GLASS_TINTED_ALPHA)
if (t <= GLASS_READABLE_TICK) {
return clear + ((readable - clear) * t) / GLASS_READABLE_TICK
}
return readable + ((tinted - readable) * (t - GLASS_READABLE_TICK)) / (1 - GLASS_READABLE_TICK)
}
/** Edge-lens displacement (feDisplacementMap `scale`, objectBoundingBox units): strongest at
* Clear, flat at Tinted. It moves backdrop pixels, never the tint, so it cannot touch contrast. */
export const GLASS_REFRACT_MAX = 0.025
export function glassRefraction(t: number): number {
return GLASS_REFRACT_MAX * (1 - t)
}
/** Whether the refraction filter runs at all at slider position `t`: only LEFT of the Readable
* tick, where the blur is light enough for the bend to show. From the tick to Tinted it moved an
* already ~20px-blurred backdrop by 3px or less (0 at Tinted), and it was the costliest part of
* the glass: MEASURED on an M2 with one streaming terminal and six glass terminals, 74% → 42% GPU
* without it. Its feImage source makes Chromium treat every refracting surface as damaged across
* its whole rect, so one changing pixel re-ran the blur of the surfaces around it too. */
export function glassRefractionOn(t: number): boolean {
return t < GLASS_READABLE_TICK
}
/** The system accessibility settings that outrank the Glass slider, like iOS. */
export interface GlassA11y {
/** Reduce Transparency: glass becomes opaque (and loses blur, refraction and sheen in CSS). */
reduceTransparency: boolean
/** Increase Contrast: the slider pins to the Tinted end. */
moreContrast: boolean
}
export const NO_GLASS_A11Y: GlassA11y = { reduceTransparency: false, moreContrast: false }
/** The tint alpha a surface actually gets: the slider's, unless an accessibility setting wins. */
export function glassSurfaceAlpha(
t: number,
readable: number,
a11y: GlassA11y = NO_GLASS_A11Y,
clear = GLASS_CLEAR_ALPHA
): number {
if (a11y.reduceTransparency) return 1
return glassSliderAlpha(a11y.moreContrast ? 1 : t, readable, clear)
}
/**
* The two chrome fills (Phase 4 slider scope; HIG: the regular variant for anything with a lot of
* text). Left of the Readable tick only the small floating CONTROLS follow the slider, down to
* `GLASS_CONTROL_CLEAR_ALPHA`; TEXT surfaces (Settings, menus, popovers, the palette, dialogs, the
* sessions sidebar, kanban columns) never go below their readable alpha. Right of the tick both
* follow the slider. Terminal nodes are neither: they keep their own tint (`glassTint`).
*/
export function glassChromeAlphas(
t: number,
readable: number,
a11y: GlassA11y = NO_GLASS_A11Y,
controlClear = GLASS_CONTROL_CLEAR_ALPHA
): { text: number; control: number } {
return {
text: glassSurfaceAlpha(Math.max(t, GLASS_READABLE_TICK), readable, a11y),
control: glassSurfaceAlpha(t, readable, a11y, Math.min(controlClear, readable))
}
}
/**
* The CONTROLS' alpha at Clear: at least `GLASS_CONTROL_CLEAR_ALPHA`, and enough that `text` (their
* icons) keeps 3:1 — WCAG's non-text minimum — over every sampled backdrop once the control blur's
* `brightness(dim)` has scaled it (styles.css `--glass-control-dim`: 0.7 dark, 1.3 light). The
* dark theme's dimming carries it at 0.35; brightening cannot lift near-black water, so light glass
* needs a denser floor (visual QA round 2, H4: zoom − measured 2.1:1 in light at Clear).
*/
export function glassControlClearAlpha(text: string, panel: string, dim: number): number {
const t = parseCssColor(text)
const p = parseCssColor(panel)
if (!t || !p || !Number.isFinite(dim)) return GLASS_CONTROL_CLEAR_ALPHA
const dimmed = CHROME_BACKDROPS.map((b) => b.map((c) => Math.min(255, c * dim)) as unknown as Rgb)
for (let i = Math.round(GLASS_CONTROL_CLEAR_ALPHA / STEP); i <= Math.round(1 / STEP); i++) {
const a = i * STEP
if (dimmed.every((b) => chromeContrast(t, p.rgb, a, b) >= 3)) return a
}
return 1
}
/** Magnetic detent, like a macOS slider's tick marks: a drag within this of the tick lands on it. */
export const GLASS_TICK_DETENT = 0.03
/** Keyboard arrow step. */
export const GLASS_SLIDER_STEP = 0.05
export function snapGlassSlider(v: number): number {
return Math.abs(v - GLASS_READABLE_TICK) <= GLASS_TICK_DETENT + 1e-9 ? GLASS_READABLE_TICK : v
}
/** One arrow press from `v` (dir -1 / +1): a step of 0.05 that stops on the tick if it crosses it. */
export function stepGlassSlider(v: number, dir: -1 | 1): number {
const next = Math.min(1, Math.max(0, Math.round((v + dir * GLASS_SLIDER_STEP) * 1000) / 1000))
const crosses = dir > 0 ? v < GLASS_READABLE_TICK && next > GLASS_READABLE_TICK : v > GLASS_READABLE_TICK && next < GLASS_READABLE_TICK
return crosses ? GLASS_READABLE_TICK : snapGlassSlider(next)
}
/** `settings.glassBlurWhileMoving`: only a literal false pauses the blur during camera moves. */
export function keepGlassBlurWhileMoving(value: unknown): boolean {
return value !== false
}