Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(glass): app-painted panels lift the glass instead of stacking a second tint

iceclatterWTa8e3418de31d
diff --git a/CLAUDE.md b/CLAUDE.md
index 2b1e48df0..0062ea02d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3858,18 +3858,30 @@ glass never sits over plain black; a wallpaper the user chose is never replaced.
live in the bg word and the run gets a theme-background rectangle at alpha 1 (Codex's all-dim
header box). No xterm option exists, so the private method is wrapped on the shared prototype
(installed from `acquireWebgl`, original kept under a `Symbol.for` key so a hot reload never
- double-wraps; fail-open). Per run: inverse → opaque; attribute-only (default bg) → the theme bg's
- alpha (0 under glass); rendered bg ≠ the buffer cell's raw bg = a renderer override (selection,
- block cursor, search/decoration) → opaque; a panel nearer the theme fg than its bg (light bar on a
- dark theme) → opaque; else the node's tint alpha (`GlassTint.alpha`, so the slider and Reduce
- Transparency apply). Written premultiplied as `(c·√k, √k)` — the canvas is premultiplied and the
- addon blends alpha with SRC_ALPHA, so this stores exactly `(c·k, k)`. Only terminals registered
- through `setGlassCellAlpha` (TerminalNode, `glassOn` only) are touched — others are byte-identical;
- an alpha change calls `term.clearTextureAtlas()` because backgrounds only rebuild for changed
- cells. The test pins addon-webgl 0.18.0 and every private name — an upgrade must re-derive them
- (or delete the wrap if upstream honours bg alpha). Ceilings: panels stack on the node tint
- (Grok reads denser than a shell); the DOM-renderer fallback keeps explicit backgrounds opaque
- (inline truecolor `background-color`).
+ double-wraps; fail-open). `classifyRun`: inverse → stock opaque; attribute-only (default bg) → the
+ theme bg's alpha (0 under glass); rendered bg ≠ the buffer cell's raw bg = a renderer override
+ (selection, block cursor, search/decoration) → stock opaque; else an app PANEL → `glassPanelFill`.
+ **A panel is a vibrancy LIFT or SINK of the glass, never the panel colour at the node's tint
+ alpha** — that first version stacked a second tint on the node's own, and #3a3a3a over a bright
+ wallpaper read as a dark smudge. Overlay alpha = `PANEL_K`(1) × OKLab distance(panel, theme bg),
+ clamped [0.04, 0.22], dead zone < 0.02 (= draw nothing), INDEPENDENT of the slider (Claude's
+ #3a3a3a on #1e1e1e → 0.11, Grok's #141414 → 0.044). Colour: the panel's own hue when OKLab chroma
+ > 0.04, else white (lift) / black (sink). A move TOWARD the text (dark-theme lift, light-theme
+ sink) at or right of the Readable tick uses the glass composite over the extreme backdrop
+ (`B·t + white·(1−t)`) instead of pure white — the lift then never passes the glass's own worst
+ case, so the theme fg keeps exactly the plain glass's 4.5:1; left of the tick it slides toward pure
+ white by `(4.5 − glassWorst)/3.5`, continuous at the tick. Text check over the WHOLE run (the fg
+ the renderer passes is only the first cell's): inverted-polarity text (dark text on a light bar,
+ dark theme) must keep min(4.5, its opaque contrast) or the panel stays opaque; other text, while
+ the guarantee is on, must fare no worse than on plain glass; glyphs under 3:1 on the opaque panel
+ are decoration. Reduce Transparency (t = 1) → opaque. Written premultiplied as `(c·√k, √k)` — the
+ canvas is premultiplied and the addon blends alpha with SRC_ALPHA, so this stores exactly `(c·k, k)`.
+ Only terminals registered through `setGlassCellAlpha` (TerminalNode, `glassOn` only) are touched —
+ others are byte-identical; an alpha change calls `term.clearTextureAtlas()` because backgrounds
+ only rebuild for changed cells. The test pins addon-webgl 0.18.0 and every private name, and
+ sweeps both default themes to prove the Readable guarantee on panels. Ceilings: Increase Contrast
+ does not strengthen panels (it pins the node to Tinted already); the DOM-renderer fallback keeps
+ explicit backgrounds opaque (inline truecolor `background-color`).
- **Liquid Glass chrome** (`:root[data-nt-glass='on']`, set by App.tsx only for that appearance, so
every other look is byte-identical). ONE chrome fill, `--glass-chrome-bg` = the resolved `--panel`
at `glassChromeAlpha(--text, --panel)` — **dark 0.70, light 0.745** on the shipped palettes. The
diff --git a/src/renderer/terminal/glass-cell-backgrounds.test.ts b/src/renderer/terminal/glass-cell-backgrounds.test.ts
index 5e75ca80b..95b230ba7 100644
--- a/src/renderer/terminal/glass-cell-backgrounds.test.ts
+++ b/src/renderer/terminal/glass-cell-backgrounds.test.ts
@@ -3,8 +3,24 @@ import fs from 'fs'
import path from 'path'
import type { Terminal } from '@xterm/xterm'
import type { WebglAddon } from '@xterm/addon-webgl'
-import { glassRectAlpha, installGlassCellBackgrounds, setGlassCellAlpha } from './glass-cell-backgrounds'
-import { relativeLuminance } from '../lib/glassContrast'
+import {
+ classifyRun,
+ glassPanelFill,
+ installGlassCellBackgrounds,
+ oklab,
+ setGlassCellAlpha
+} from './glass-cell-backgrounds'
+import {
+ composite,
+ contrastRatio,
+ GLASS_READABLE_TICK,
+ glassSliderAlpha,
+ glassTintAlpha,
+ parseHex
+} from '../lib/glassContrast'
+import { resolveTerminalTheme } from './themes'
+
+type Rgb = readonly [number, number, number]
const INVERSE = 0x4000000
const CM_P256 = 0x2000000
@@ -13,43 +29,121 @@ const DIM = 0x8000000
const ITALIC = 0x4000000
const HAS_EXTENDED = 0x10000000
-const BG_LUM = relativeLuminance([30, 30, 30]) // nodeterm-dark background
-const FG_LUM = relativeLuminance([212, 212, 212])
-const L = (v: number): number => relativeLuminance([v, v, v])
+const grey = (v: number): Rgb => [v, v, v]
+const DARK = { bg: grey(30), fg: grey(230) } // nodeterm-dark
+const WHITE: Rgb = [255, 255, 255]
+const BLACK: Rgb = [0, 0, 0]
-describe('glassRectAlpha', () => {
+describe('classifyRun', () => {
const grok = CM_RGB | 0x141414
it.each([
- ['inverse video / fake cursor', INVERSE, CM_RGB | 0x3a3a3a, CM_RGB | 0x3a3a3a, L(58), 1],
- ['inverse on the default bg', INVERSE, 0, 0, FG_LUM, 1],
- ['DIM on the default bg', 0, DIM, DIM, BG_LUM, 0],
- ['ITALIC on the default bg', 0, ITALIC, ITALIC, BG_LUM, 0],
- ['hyperlink / underline style on the default bg', 0, HAS_EXTENDED, HAS_EXTENDED, BG_LUM, 0],
- ['app panel (truecolor)', 0, grok, grok, L(20), 0.4],
- ['app panel (256-colour, Claude bubble)', 0, CM_P256 | 237, CM_P256 | 237, L(58), 0.4],
- ['dim text on an app panel', 0, grok | DIM, grok | DIM, L(20), 0.4],
- ['selection / block cursor / search highlight (renderer override)', 0, CM_RGB | 0x264f78, grok, relativeLuminance([38, 79, 120]), 1],
- ['override where the buffer cell was unreadable', 0, grok, NaN, L(20), 1],
- ['light panel on a dark theme', 0, CM_RGB | 0xe0e0e0, CM_RGB | 0xe0e0e0, L(224), 1]
- ])('%s', (_name, fg, bg, cellBg, runLum, want) => {
- expect(glassRectAlpha(fg, bg, cellBg, 0.4, 0, runLum, BG_LUM, FG_LUM)).toBe(want)
+ ['inverse video / fake cursor', INVERSE, CM_RGB | 0x3a3a3a, CM_RGB | 0x3a3a3a, 'stock'],
+ ['inverse on the default bg', INVERSE, 0, 0, 'stock'],
+ ['DIM on the default bg', 0, DIM, DIM, 0],
+ ['ITALIC on the default bg', 0, ITALIC, ITALIC, 0],
+ ['hyperlink / underline style on the default bg', 0, HAS_EXTENDED, HAS_EXTENDED, 0],
+ ['app panel (truecolor)', 0, grok, grok, 'panel'],
+ ['app panel (256-colour, Claude bubble)', 0, CM_P256 | 237, CM_P256 | 237, 'panel'],
+ ['dim text on an app panel', 0, grok | DIM, grok | DIM, 'panel'],
+ ['selection / block cursor / search highlight (renderer override)', 0, CM_RGB | 0x264f78, grok, 'stock'],
+ ['override where the buffer cell was unreadable', 0, grok, NaN, 'stock']
+ ])('%s', (_name, fg, bg, cellBg, want) => {
+ expect(classifyRun(fg, bg, cellBg, 0)).toBe(want)
})
it('an attribute-only run takes the theme background alpha, whatever it is', () => {
- expect(glassRectAlpha(0, DIM, DIM, 0.4, 1, BG_LUM, BG_LUM, FG_LUM)).toBe(1)
+ expect(classifyRun(0, DIM, DIM, 1)).toBe(1)
+ })
+})
+
+describe('glassPanelFill: a lift or sink of the glass, never a second slab of tint', () => {
+ it("Claude's #3a3a3a bubble on #1e1e1e is a subtle white-ish lift, the same at every slider position", () => {
+ for (const t of [0.2, 0.539, 0.675, 0.95]) {
+ const f = glassPanelFill(grey(58), DARK, t, [WHITE])!
+ expect(f.alpha).toBeGreaterThanOrEqual(0.08)
+ expect(f.alpha).toBeLessThanOrEqual(0.12)
+ expect(f.rgb[0]).toBeGreaterThan(30) // lighter than the tint: a lift
+ }
+ })
+
+ it("Grok's full-screen #141414 is a faint black sink (≈ the theme bg)", () => {
+ const f = glassPanelFill(grey(20), DARK, 0.675, [grey(200)])!
+ expect(f.rgb).toEqual(BLACK)
+ expect(f.alpha).toBeGreaterThanOrEqual(0.04)
+ expect(f.alpha).toBeLessThanOrEqual(0.06)
+ })
+
+ it('a panel that IS the theme background draws nothing', () => {
+ expect(glassPanelFill(grey(31), DARK, 0.675, [])).toEqual({ rgb: grey(31), alpha: 0 })
+ })
+
+ it('Reduce Transparency (node alpha 1) keeps the app panel opaque', () => {
+ expect(glassPanelFill(grey(58), DARK, 1, [])).toBeNull()
+ })
+
+ it('a coloured status bar keeps its own hue', () => {
+ const f = glassPanelFill([0, 90, 200], DARK, 0.675, [WHITE])!
+ expect(f.rgb).toEqual([0, 90, 200])
+ expect(f.alpha).toBe(0.22)
+ })
+
+ it('a light bar carrying dark text on a dark theme stays opaque (the panel is what makes it readable)', () => {
+ for (const t of [0.2, 0.675, 0.95]) expect(glassPanelFill(grey(224), DARK, t, [BLACK])).toBeNull()
+ })
+
+ it('decoration under 3:1 on the opaque panel (a dim prompt chevron) does not force it opaque', () => {
+ expect(glassPanelFill(grey(58), DARK, 0.675, [grey(78)])).not.toBeNull()
})
- it('Reduce Transparency (node alpha 1) leaves app panels opaque', () => {
- expect(glassRectAlpha(0, CM_RGB | 0x141414, CM_RGB | 0x141414, 1, 0, L(20), BG_LUM, FG_LUM)).toBe(1)
+ it('is continuous at the Readable tick', () => {
+ const r = glassTintAlpha('#e6e6e6', '#1e1e1e')
+ const at = glassPanelFill(grey(58), DARK, r, [])!.rgb[0]
+ const below = glassPanelFill(grey(58), DARK, r - 1e-4, [])!.rgb[0]
+ expect(Math.abs(at - below)).toBeLessThan(0.5) // no jump: the step shrinks with the slider step
})
})
+/**
+ * The guarantee: at or right of the Readable tick, the theme foreground on a lifted/sunk panel
+ * keeps 4.5:1 over ANY backdrop — the same promise as the plain glass. Swept over grey panels on
+ * both default themes, backdrops 0..255 plus saturated corners.
+ */
+describe('theme text on a panel keeps the Readable guarantee', () => {
+ const backdrops: Rgb[] = [
+ ...Array.from({ length: 52 }, (_, i) => grey(i * 5)),
+ [255, 0, 0], [0, 255, 0], [0, 0, 255], [255, 255, 0], [0, 255, 255], [255, 0, 255]
+ ]
+ it.each(['nodeterm-dark', 'nodeterm-light'])('%s', (id) => {
+ const theme = resolveTerminalTheme(id).theme
+ const bg = parseHex(theme.background!)!
+ const fg = parseHex(theme.foreground!)!
+ const readable = glassTintAlpha(theme.foreground!, theme.background!)
+ for (const t of [readable, glassSliderAlpha((GLASS_READABLE_TICK + 1) / 2, readable), glassSliderAlpha(1, readable)]) {
+ for (let v = 0; v <= 255; v += 5) {
+ const f = glassPanelFill(grey(v), { bg, fg }, t, [fg])
+ if (!f) continue // opaque: the app's own panel
+ for (const x of backdrops) {
+ const shown = composite(f.rgb, composite(bg, x, t), f.alpha)
+ expect(contrastRatio(fg, shown), `${id} t=${t} panel=${v} backdrop=${x}`).toBeGreaterThanOrEqual(4.5 - 1e-6)
+ }
+ }
+ }
+ })
+})
+
+it('OKLab is the reference transform (white L=1, black L=0, grey is achromatic)', () => {
+ expect(oklab(WHITE)[0]).toBeCloseTo(1, 4)
+ expect(oklab(BLACK)[0]).toBeCloseTo(0, 6)
+ const [, a, b] = oklab(grey(128))
+ expect(Math.hypot(a, b)).toBeLessThan(1e-4)
+})
+
it('(c·√k, √k) blended SRC_ALPHA over a cleared premultiplied canvas stores exactly (c·k, k)', () => {
- for (const k of [0.2, 0.675, 0.95]) {
- const c = 20 / 255
+ for (const k of [0.04, 0.11, 0.22]) {
+ const c = 188 / 255
const s = Math.sqrt(k)
- expect(c * s * s).toBeCloseTo(c * k, 12) // rgb: src·srcAlpha
- expect(s * s).toBeCloseTo(k, 12) // alpha channel blends the same way
+ expect(c * s * s).toBeCloseTo(c * k, 12)
+ expect(s * s).toBeCloseTo(k, 12)
}
})
@@ -62,20 +156,25 @@ it('setGlassCellAlpha reports only real changes', () => {
expect(setGlassCellAlpha(t, null)).toBe(false)
})
+type FakeCell = { bg: number; fg?: number; ch?: string }
+
/** A structural fake of the addon's RectangleRenderer, doing what the real `_updateRectangle`
* does with the attribute array (colour, then `$a = 1`). One class per test: the wrap patches the
* prototype, like it does the real shared one. */
-function fakeAddon(cells: Record<number, number>) {
+function fakeAddon(cells: Record<number, FakeCell>) {
class RectangleRenderer {
- _themeService = { colors: { background: { rgba: 0x1e1e1e00 }, foreground: { rgba: 0xd4d4d4ff } } }
+ _themeService = { colors: { background: { rgba: 0x1e1e1e00 }, foreground: { rgba: 0xe6e6e6ff }, ansi: [] } }
_terminal = {
buffer: {
active: {
viewportY: 0,
- getNullCell: () => ({ bg: 0 }),
+ getNullCell: () => ({ bg: 0, fg: 0, getChars: () => '' }),
getLine: () => ({
- getCell: (x: number, cell: { bg: number }) => {
- cell.bg = cells[x] ?? 0
+ getCell: (x: number, cell: { bg: number; fg: number; getChars: () => string }) => {
+ const c = cells[x] ?? { bg: 0 }
+ cell.bg = c.bg
+ cell.fg = c.fg ?? 0
+ cell.getChars = () => c.ch ?? ''
return cell
}
})
@@ -90,32 +189,42 @@ function fakeAddon(cells: Record<number, number>) {
}
const rr = new RectangleRenderer()
const addon = { _renderer: { _rectangleRenderer: { value: rr } } } as unknown as WebglAddon
- const draw = (fg: number, bg: number, x = 0): number[] => {
+ const draw = (fg: number, bg: number, x = 0, endX = x + 1): number[] => {
const v = { attributes: new Float32Array(8) }
- rr._updateRectangle(v, 0, fg, bg, x, x + 1, 0)
+ rr._updateRectangle(v, 0, fg, bg, x, endX, 0)
return Array.from(v.attributes)
}
- return { addon, rr, draw, proto: RectangleRenderer.prototype }
+ return { addon, rr, draw }
}
describe('installGlassCellBackgrounds', () => {
- const panel = CM_RGB | 0x141414
+ const panel = CM_RGB | 0x3a3a3a
- it('glass: an app panel is premultiplied to the node alpha, a dim run vanishes, an override stays', () => {
- const { addon, rr, draw } = fakeAddon({ 0: panel })
+ it('glass: an app panel becomes its premultiplied lift, a dim run vanishes, overrides stay', () => {
+ const { addon, rr, draw } = fakeAddon({ 0: { bg: panel } })
expect(installGlassCellBackgrounds(addon)).toBe(true)
- setGlassCellAlpha(rr._terminal, 0.25)
+ setGlassCellAlpha(rr._terminal, 0.675)
+ const want = glassPanelFill(grey(58), DARK, 0.675, [])!
const p = draw(0, panel)
- expect(p[7]).toBeCloseTo(0.5, 6) // √0.25
- expect(p[4]).toBeCloseTo((20 / 255) * 0.5, 6)
+ expect(p[7]).toBeCloseTo(Math.sqrt(want.alpha), 6)
+ expect(p[4]).toBeCloseTo((want.rgb[0] / 255) * Math.sqrt(want.alpha), 6)
expect(draw(0, DIM)[7]).toBe(0)
expect(draw(0, CM_RGB | 0x264f78)[7]).toBe(1) // rendered bg ≠ buffer bg: selection
expect(draw(INVERSE, panel)[7]).toBe(1)
})
+ it("reads the run's text, not just its first cell: a light bar with dark text stays opaque", () => {
+ const bar = CM_RGB | 0xe0e0e0
+ const text = CM_RGB | 0x000000
+ const { addon, rr, draw } = fakeAddon({ 0: { bg: bar }, 1: { bg: bar, fg: text, ch: 'x' } })
+ installGlassCellBackgrounds(addon)
+ setGlassCellAlpha(rr._terminal, 0.675)
+ expect(draw(0, bar, 0, 2)[7]).toBe(1)
+ })
+
it('non-glass terminals are byte-identical to the stock renderer', () => {
- const stock = fakeAddon({ 0: panel })
- const wrapped = fakeAddon({ 0: panel })
+ const stock = fakeAddon({ 0: { bg: panel } })
+ const wrapped = fakeAddon({ 0: { bg: panel } })
installGlassCellBackgrounds(wrapped.addon)
for (const [fg, bg] of [[0, panel], [0, DIM], [INVERSE, panel], [0, CM_RGB | 0x264f78]]) {
expect(wrapped.draw(fg, bg)).toEqual(stock.draw(fg, bg))
@@ -123,11 +232,14 @@ describe('installGlassCellBackgrounds', () => {
})
it('a re-install (hot reload) wraps the original, never the wrap', () => {
- const { addon, rr, draw } = fakeAddon({ 0: panel })
- installGlassCellBackgrounds(addon)
- installGlassCellBackgrounds(addon)
- setGlassCellAlpha(rr._terminal, 0.25)
- expect(draw(0, panel)[7]).toBeCloseTo(0.5, 6) // applied once, not √√
+ const once = fakeAddon({ 0: { bg: panel } })
+ installGlassCellBackgrounds(once.addon)
+ setGlassCellAlpha(once.rr._terminal, 0.675)
+ const twice = fakeAddon({ 0: { bg: panel } })
+ installGlassCellBackgrounds(twice.addon)
+ installGlassCellBackgrounds(twice.addon)
+ setGlassCellAlpha(twice.rr._terminal, 0.675)
+ expect(twice.draw(0, panel)).toEqual(once.draw(0, panel))
})
it('fails open when the internals are missing', () => {
diff --git a/src/renderer/terminal/glass-cell-backgrounds.ts b/src/renderer/terminal/glass-cell-backgrounds.ts
index 4b6699da5..5ce88d95c 100644
--- a/src/renderer/terminal/glass-cell-backgrounds.ts
+++ b/src/renderer/terminal/glass-cell-backgrounds.ts
@@ -1,6 +1,6 @@
import type { Terminal } from '@xterm/xterm'
import type { WebglAddon } from '@xterm/addon-webgl'
-import { relativeLuminance } from '../lib/glassContrast'
+import { composite, contrastRatio, relativeLuminance, worstContrast } from '../lib/glassContrast'
/**
* Cell backgrounds on a Liquid Glass terminal become glass instead of opaque slabs.
@@ -16,7 +16,7 @@ import { relativeLuminance } from '../lib/glassContrast'
*
* xterm has no option for either (`allowTransparency` is all there is, and palette alpha is
* ignored), so this wraps the private `_updateRectangle` on the shared prototype and rewrites the
- * alpha the original just wrote — the same private coupling a bundle patch would need, minus the
+ * colour the original just wrote — the same private coupling a bundle patch would need, minus the
* postinstall and Vite pre-bundle cache. Fail-open like `dom-renderer-spacing.ts`: a build that
* renamed anything keeps stock rendering. `glass-cell-backgrounds.test.ts` pins the addon version
* and every private name used here.
@@ -28,41 +28,135 @@ import { relativeLuminance } from '../lib/glassContrast'
* backgrounds — its inline truecolor `background-color` cannot be re-alpha'd from CSS.
*/
+type Rgb = readonly [number, number, number]
+
// xterm's packed attribute bits (common/buffer/Constants.ts).
const FG_INVERSE = 0x4000000
const CM_MASK = 0x3000000
-
-/** ponytail: tuning knob, panel alpha = node tint alpha × this. 0.5 measured 5.6:1 at Readable
- * over a bright backdrop (tui-glass-backgrounds.md), so 1 — lower only with a new contrast check. */
-const CELL_ALPHA_SCALE = 1
+const CM_P16 = 0x1000000
+const CM_P256 = 0x2000000
+const CM_RGB = 0x3000000
/**
- * The alpha one background run gets on a glass terminal.
- * - inverse video (and the fake cursors TUIs draw with it) stays opaque;
+ * How a background run renders on glass: `'stock'` = the renderer's own opaque rectangle, `'panel'`
+ * = the app's own background (→ `glassPanelFill`), or a number = the THEME background at that alpha.
+ * - inverse video (and the fake cursors TUIs draw with it) is stock;
* - an attribute-only run (default bg + DIM/ITALIC/…) gets the theme background's alpha, which is
* what the rest of the viewport gets (0 under glass);
* - a rendered bg that differs from the buffer cell's raw bg is a RENDERER override — selection,
- * the block cursor, a search/decoration highlight — and stays opaque;
- * - a panel nearer the theme foreground than the background (a light bar on a dark theme) stays
- * opaque, since fading it would move the text on it toward the tint;
- * - everything else is the app's own panel and follows the node's glass alpha, so the Glass slider
- * and Reduce Transparency (alpha 1) apply to it like to the node.
+ * the block cursor, a search/decoration highlight — and is stock.
*/
-export function glassRectAlpha(
- fg: number,
- bg: number,
- cellBg: number,
- glassA: number,
- themeBgA: number,
- runLum: number,
- bgLum: number,
- fgLum: number
-): number {
- if (fg & FG_INVERSE) return 1
+export function classifyRun(fg: number, bg: number, cellBg: number, themeBgA: number): 'stock' | 'panel' | number {
+ if (fg & FG_INVERSE) return 'stock'
if ((bg & CM_MASK) === 0) return themeBgA
- if (bg !== cellBg) return 1
- if (Math.abs(runLum - bgLum) > Math.abs(runLum - fgLum)) return 1
- return Math.min(1, glassA * CELL_ALPHA_SCALE)
+ if (bg !== cellBg) return 'stock'
+ return 'panel'
+}
+
+/** OKLab (L, a, b) of an sRGB colour, 0..255 channels. */
+export function oklab([r, g, b]: Rgb): [number, number, number] {
+ const lin = (c: number): number => {
+ const s = c / 255
+ return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4)
+ }
+ const [R, G, B] = [lin(r), lin(g), lin(b)]
+ const l = Math.cbrt(0.4122214708 * R + 0.5363325363 * G + 0.0514459929 * B)
+ const m = Math.cbrt(0.2119034982 * R + 0.6806995451 * G + 0.1073969566 * B)
+ const s = Math.cbrt(0.0883024619 * R + 0.2817188376 * G + 0.6299787005 * B)
+ return [
+ 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+ 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+ 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s
+ ]
+}
+
+/** ponytail: tuning knobs. Panel overlay alpha = PANEL_K × OKLab distance(panel, theme bg), clamped.
+ * K = 1 puts Claude's #3a3a3a bubble on #1e1e1e at 0.11 white and Grok's #141414 screen at 0.044
+ * black; raise K for bolder panels (the contrast check below still holds). */
+const PANEL_K = 1
+const PANEL_ALPHA_MIN = 0.04
+const PANEL_ALPHA_MAX = 0.22
+/** OKLab distance under which a panel IS the theme background (drawn as nothing). */
+const PANEL_DEAD_ZONE = 0.02
+/** OKLab chroma above which a panel keeps its own hue (a coloured status bar) instead of going grey. */
+const PANEL_CHROMA_MIN = 0.04
+/** Glyphs under this contrast on the app's own opaque panel are decoration (a dim prompt chevron),
+ * not text — unprotected, like ANSI colours on plain glass. */
+const TEXT_MIN_CONTRAST = 3
+
+/**
+ * An app panel as a vibrancy fill: a gentle lift or sink of the glass, NEVER a second slab of the
+ * node's tint (drawing the panel colour at the tint alpha stacked the two, and #3a3a3a over a bright
+ * wallpaper read as a dark smudge).
+ *
+ * The panel colour C is judged against the theme background B: the overlay's alpha is
+ * `PANEL_K × OKLab distance`, clamped to [0.04, 0.22], independent of the node alpha `t` (the Glass
+ * slider keeps meaning the node's glass). Its colour: C itself when C is clearly chromatic (a
+ * coloured bar stays coloured), otherwise neutral — white for a lift, black for a sink.
+ *
+ * A neutral move AWAY from the text (a sink on a dark theme) only adds contrast. A move TOWARD it
+ * (a lift on a dark theme, a sink on a light one) is where the guarantee lives: at or right of the
+ * Readable tick the overlay is the glass's own composite over the extreme backdrop (`B·t + white·
+ * (1−t)` for a dark-theme lift), so it lifts wherever the backdrop leaves room and can never push
+ * the composite past the glass's worst case — the theme foreground keeps exactly the plain glass's
+ * 4.5:1. Left of the tick (no guarantee there, as on the plain glass) it slides toward pure white in
+ * proportion to how far the glass already is from 4.5:1, so it is continuous at the tick.
+ *
+ * Every text colour on the run is then checked (glyphs under `TEXT_MIN_CONTRAST` on the opaque
+ * panel are decoration, e.g. a dim prompt chevron):
+ * - text of INVERTED polarity (dark text on a dark theme — the panel is what makes it readable,
+ * e.g. a light bar) must keep min(4.5, its contrast on the opaque panel) over ANY backdrop;
+ * - other text, while the guarantee is on, must fare no worse than on the plain glass around it.
+ * A panel that fails returns null: opaque, exactly the app's own panel.
+ *
+ * Returns the fill (0..255 colour, alpha) or null for opaque. `alpha` 0 = draw nothing.
+ */
+export function glassPanelFill(
+ c: Rgb,
+ theme: { bg: Rgb; fg: Rgb },
+ t: number,
+ texts: readonly Rgb[]
+): { rgb: Rgb; alpha: number } | null {
+ if (t >= 1) return null // Reduce Transparency: the app's panels, opaque
+ const [lc, ac, bc] = oklab(c)
+ const [lb, ab, bb] = oklab(theme.bg)
+ const dist = Math.hypot(lc - lb, ac - ab, bc - bb)
+ if (dist < PANEL_DEAD_ZONE) return { rgb: c, alpha: 0 }
+ const alpha = Math.min(PANEL_ALPHA_MAX, Math.max(PANEL_ALPHA_MIN, PANEL_K * dist))
+ const glassWorst = worstContrast(theme.fg, theme.bg, t)
+ const guaranteed = glassWorst >= 4.5
+ const fgLight = relativeLuminance(theme.fg) > relativeLuminance(theme.bg)
+ let rgb: Rgb
+ if (Math.hypot(ac, bc) > PANEL_CHROMA_MIN) {
+ rgb = c
+ } else {
+ const lift = lc > lb
+ const extreme: Rgb = lift ? [255, 255, 255] : [0, 0, 0]
+ if (lift !== fgLight) {
+ rgb = extreme
+ } else {
+ const ceiling = composite(theme.bg, extreme, t)
+ const toward = guaranteed ? 0 : Math.min(1, (4.5 - glassWorst) / 3.5)
+ rgb = composite(extreme, ceiling, toward)
+ }
+ }
+ // Over backdrop X the node shows G(X) = B·t + X·(1−t); the panel paints rgb·alpha over it. Both
+ // are affine in X, so the composite's luminance range is spanned by X = black and X = white.
+ const lo = composite(rgb, composite(theme.bg, [0, 0, 0], t), alpha)
+ const hi = composite(rgb, composite(theme.bg, [255, 255, 255], t), alpha)
+ const [llo, lhi] = [relativeLuminance(lo), relativeLuminance(hi)].sort((x, y) => x - y)
+ const lbg = relativeLuminance(theme.bg)
+ for (const f of texts) {
+ const own = contrastRatio(f, c)
+ if (own < TEXT_MIN_CONTRAST) continue
+ const lf = relativeLuminance(f)
+ const inverted = lf > lbg !== fgLight
+ if (!inverted && !guaranteed) continue
+ const worst = lf > llo && lf < lhi ? 1 : Math.min(contrastRatio(f, lo), contrastRatio(f, hi))
+ const need = inverted ? Math.min(4.5, own) : Math.min(own, worstContrast(f, theme.bg, t))
+ if (worst < need - 1e-9) return null
+ }
+ return { rgb, alpha }
}
/** The node's glass alpha per terminal; absent = not glass = stock rendering. */
@@ -90,14 +184,32 @@ type UpdateRectangle = (
) => void
interface RectangleRendererLike {
_terminal: Terminal
- _themeService?: { colors?: { background?: { rgba: number }; foreground?: { rgba: number } } }
+ _themeService?: {
+ colors?: { background?: { rgba: number }; foreground?: { rgba: number }; ansi?: { rgba: number }[] }
+ }
+}
+interface CellLike {
+ bg?: number
+ fg?: number
+ getChars?(): string
}
/** Kept on the prototype, not in module state, so a hot-reloaded copy of this module re-wraps the
* ORIGINAL instead of stacking a second wrap over the first. */
const ORIGINAL = Symbol.for('nodeterm.glassCellBackgrounds.original')
-const lum = (rgba: number): number => relativeLuminance([(rgba >>> 24) & 255, (rgba >>> 16) & 255, (rgba >>> 8) & 255])
+const rgbOf = (rgba: number): Rgb => [(rgba >>> 24) & 255, (rgba >>> 16) & 255, (rgba >>> 8) & 255]
+
+/** Write `rgb` (0..255) at `alpha` into a rectangle's colour slots. The canvas is premultiplied and
+ * the addon blends SRC_ALPHA/ONE_MINUS_SRC_ALPHA on the alpha channel too, so writing (c, k) would
+ * store (c·k, k²); (c·√k, √k) stores exactly (c·k, k). */
+function writeFill(a: Float32Array, offset: number, rgb: Rgb, alpha: number): void {
+ const s = Math.sqrt(alpha)
+ a[offset + 4] = (rgb[0] / 255) * s
+ a[offset + 5] = (rgb[1] / 255) * s
+ a[offset + 6] = (rgb[2] / 255) * s
+ a[offset + 7] = s
+}
/** Wrap the addon's rectangle renderer once (all instances share the prototype). Call after
* `term.loadAddon(addon)`, when the renderer exists. Returns whether the wrap is in place. */
@@ -110,7 +222,7 @@ export function installGlassCellBackgrounds(addon: WebglAddon): boolean {
const orig = (proto[ORIGINAL] ?? proto._updateRectangle) as UpdateRectangle | undefined
if (typeof orig !== 'function') return false
proto[ORIGINAL] = orig
- let scratch: { bg?: number } | undefined
+ let scratch: CellLike | undefined
proto._updateRectangle = function (
this: RectangleRendererLike,
v: Vertices,
@@ -122,38 +234,50 @@ export function installGlassCellBackgrounds(addon: WebglAddon): boolean {
y: number
): void {
orig.call(this, v, offset, fg, bg, startX, endX, y)
- const glassA = cellAlpha.get(this._terminal)
- if (glassA === undefined) return
+ const t = cellAlpha.get(this._terminal)
+ if (t === undefined) return
const colors = this._themeService?.colors
const back = colors?.background?.rgba
const fore = colors?.foreground?.rgba
if (back === undefined || fore === undefined) return
const a = v.attributes // re-read: the original may have grown the array
+ let line: { getCell(x: number, cell: never): unknown } | undefined
let cellBg = NaN // unknown = treated as a renderer override (stock opaque)
if ((bg & CM_MASK) !== 0 && !(fg & FG_INVERSE)) {
const buf = this._terminal.buffer.active
- scratch ??= buf.getNullCell() as unknown as { bg?: number }
- buf.getLine(buf.viewportY + y)?.getCell(startX, scratch as never)
+ scratch ??= buf.getNullCell() as unknown as CellLike
+ line = buf.getLine(buf.viewportY + y)
+ line?.getCell(startX, scratch as never)
if (typeof scratch.bg === 'number') cellBg = scratch.bg
}
- const k = glassRectAlpha(
- fg,
- bg,
- cellBg,
- glassA,
- (back & 255) / 255,
- relativeLuminance([a[offset + 4] * 255, a[offset + 5] * 255, a[offset + 6] * 255]),
- lum(back),
- lum(fore)
- )
- if (k >= 1) return
- // The canvas is premultiplied and the addon blends SRC_ALPHA/ONE_MINUS_SRC_ALPHA on the alpha
- // channel too, so writing (c, k) would store (c·k, k²). (c·√k, √k) stores exactly (c·k, k).
- const s = Math.sqrt(k)
- a[offset + 4] *= s
- a[offset + 5] *= s
- a[offset + 6] *= s
- a[offset + 7] = s
+ const kind = classifyRun(fg, bg, cellBg, (back & 255) / 255)
+ if (kind === 'stock') return
+ if (typeof kind === 'number') {
+ if (kind < 1) writeFill(a, offset, rgbOf(back), kind)
+ return
+ }
+ // The run's text colours: a run spans cells of one bg but any fg, and the fg the renderer
+ // passes is only the first cell's.
+ const texts: Rgb[] = []
+ let lastFg = -1
+ for (let x = startX; x < endX && line && scratch; x++) {
+ line.getCell(x, scratch as never)
+ const f = scratch.fg
+ const ch = scratch.getChars?.() ?? ''
+ if (typeof f !== 'number' || f === lastFg || ch === '' || ch === ' ') continue
+ lastFg = f
+ const mode = f & CM_MASK
+ texts.push(
+ mode === CM_RGB
+ ? rgbOf((f & 0xffffff) << 8)
+ : (mode === CM_P16 || mode === CM_P256) && colors?.ansi?.[f & 0xff]
+ ? rgbOf(colors.ansi[f & 0xff].rgba)
+ : rgbOf(fore)
+ )
+ }
+ const run: Rgb = [a[offset + 4] * 255, a[offset + 5] * 255, a[offset + 6] * 255]
+ const fill = glassPanelFill(run, { bg: rgbOf(back), fg: rgbOf(fore) }, t, texts)
+ if (fill) writeFill(a, offset, fill.rgb, fill.alpha)
}
return true
} catch {