A local-first multi-agent app development platform, built on PenguinHarness
/**
* Colour parsing and WCAG 2 contrast, for tests that judge theme tokens by their computed values
* instead of by a ratio typed into a comment.
*
* Covers the notations the theme files use: hex (3/4/6/8 digits), `rgb()`/`rgba()` in both the
* comma and the space-and-slash syntax, `hsl()`/`hsla()`, `oklch()`, `color-mix(in srgb, …)`,
* `transparent`, `white` and `black`. Anything else parses to `null`, and a caller reports that as
* a failure — an unreadable colour is never assumed to pass.
*/
/** sRGB channels 0–255 (unrounded) and alpha 0–1. */
export interface Rgba {
readonly r: number;
readonly g: number;
readonly b: number;
readonly a: number;
}
export const WHITE: Rgba = { r: 255, g: 255, b: 255, a: 1 };
export const BLACK: Rgba = { r: 0, g: 0, b: 0, a: 1 };
const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));
/** Splits on commas (or whitespace when there are none) at parenthesis depth 0. */
function splitTopLevel(text: string, separator: "," | " "): string[] {
const parts: string[] = [];
let depth = 0;
let current = "";
for (const ch of text) {
if (ch === "(") depth++;
else if (ch === ")") depth--;
const splits = separator === "," ? ch === "," : /\s/.test(ch);
if (depth === 0 && splits) {
if (current.trim() !== "") parts.push(current.trim());
current = "";
} else {
current += ch;
}
}
if (current.trim() !== "") parts.push(current.trim());
return parts;
}
/** `name(args)` → `[name, args]`, or null when the value is not a single function call. */
function functionCall(value: string): [string, string] | null {
const match = /^([a-z-]+)\((.*)\)$/is.exec(value.trim());
return match === null ? null : [match[1]!.toLowerCase(), match[2]!];
}
/** A number, or a percentage scaled so 100% = `percentScale`. */
function numberOrPercent(token: string, percentScale: number): number | null {
const match = /^(-?\d*\.?\d+(?:e-?\d+)?)(%?)$/i.exec(token.trim());
if (match === null) return null;
const n = Number(match[1]);
return match[2] === "%" ? (n / 100) * percentScale : n;
}
function hue(token: string): number | null {
const match = /^(-?\d*\.?\d+)(deg|turn|rad)?$/i.exec(token.trim());
if (match === null) return null;
const n = Number(match[1]);
const unit = (match[2] ?? "deg").toLowerCase();
return unit === "turn" ? n * 360 : unit === "rad" ? (n * 180) / Math.PI : n;
}
/** Channel and alpha tokens of a colour function, in either the legacy or the modern syntax. */
function channels(args: string): { values: string[]; alpha: string | undefined } | null {
if (args.includes(",")) {
const values = splitTopLevel(args, ",");
if (values.length === 3) return { values, alpha: undefined };
if (values.length === 4) return { values: values.slice(0, 3), alpha: values[3] };
return null;
}
const [main, alpha, ...rest] = args.split("/");
if (main === undefined || rest.length > 0) return null;
const values = splitTopLevel(main, " ");
if (values.length !== 3) return null;
return { values, alpha: alpha?.trim() };
}
function parseAlpha(token: string | undefined): number | null {
if (token === undefined) return 1;
const a = numberOrPercent(token, 1);
return a === null ? null : clamp(a, 0, 1);
}
function parseHex(value: string): Rgba | null {
const hex = /^#([0-9a-f]{3,8})$/i.exec(value)?.[1];
if (hex === undefined || hex.length === 5 || hex.length === 7) return null;
const full = hex.length <= 4 ? [...hex].map((c) => c + c).join("") : hex;
const byte = (i: number) => parseInt(full.slice(i, i + 2), 16);
return {
r: byte(0),
g: byte(2),
b: byte(4),
a: full.length === 8 ? byte(6) / 255 : 1,
};
}
function hslToRgb(h: number, s: number, l: number): [number, number, number] {
const hh = (((h % 360) + 360) % 360) / 360;
const f = (n: number) => {
const k = (n + hh * 12) % 12;
const a = s * Math.min(l, 1 - l);
return l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
};
return [f(0) * 255, f(8) * 255, f(4) * 255];
}
/** OKLCH → gamma-encoded sRGB 0–255, clamped to the gamut (Björn Ottosson's matrices). */
function oklchToRgb(lightness: number, chroma: number, hueDeg: number): [number, number, number] {
const rad = (hueDeg * Math.PI) / 180;
const A = chroma * Math.cos(rad);
const B = chroma * Math.sin(rad);
const l = (lightness + 0.3963377774 * A + 0.2158037573 * B) ** 3;
const m = (lightness - 0.1055613458 * A - 0.0638541728 * B) ** 3;
const s = (lightness - 0.0894841775 * A - 1.291485548 * B) ** 3;
const linear = [
4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
];
const encode = (c: number) => {
const v = clamp(c, 0, 1);
return (v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055) * 255;
};
return [encode(linear[0]!), encode(linear[1]!), encode(linear[2]!)];
}
/** `color-mix(in srgb, A [p%], B [q%])`, premultiplied as CSS Color 5 specifies. */
function parseColorMix(args: string): Rgba | null {
const [space, first, second, ...rest] = splitTopLevel(args, ",");
if (space?.replace(/\s+/g, " ").toLowerCase() !== "in srgb" || rest.length > 0) return null;
if (first === undefined || second === undefined) return null;
const component = (part: string): { color: Rgba; pct: number | undefined } | null => {
const tokens = splitTopLevel(part, " ");
const pctToken = tokens.find((t) => /^-?\d*\.?\d+%$/.test(t));
const colorText = tokens.filter((t) => t !== pctToken).join(" ");
const color = parseColor(colorText);
if (color === null) return null;
return { color, pct: pctToken === undefined ? undefined : Number(pctToken.slice(0, -1)) };
};
const a = component(first);
const b = component(second);
if (a === null || b === null) return null;
let p1 = a.pct;
let p2 = b.pct;
if (p1 === undefined && p2 === undefined) [p1, p2] = [50, 50];
else if (p1 === undefined) p1 = 100 - p2!;
else if (p2 === undefined) p2 = 100 - p1;
const sum = p1 + p2!;
if (sum <= 0) return null;
const w1 = p1 / sum;
const w2 = p2! / sum;
const alpha = a.color.a * w1 + b.color.a * w2;
const mix = (x: number, y: number) =>
alpha === 0 ? 0 : (x * a.color.a * w1 + y * b.color.a * w2) / alpha;
return {
r: mix(a.color.r, b.color.r),
g: mix(a.color.g, b.color.g),
b: mix(a.color.b, b.color.b),
a: alpha * Math.min(1, sum / 100),
};
}
/** Parses a CSS colour value with no `var()` left in it. `null` when the notation is not covered. */
export function parseColor(input: string): Rgba | null {
const value = input.trim();
const lower = value.toLowerCase();
if (lower === "transparent") return { r: 0, g: 0, b: 0, a: 0 };
if (lower === "white") return WHITE;
if (lower === "black") return BLACK;
if (value.startsWith("#")) return parseHex(value);
const call = functionCall(value);
if (call === null) return null;
const [name, args] = call;
if (name === "color-mix") return parseColorMix(args);
const parts = channels(args);
if (parts === null) return null;
const alpha = parseAlpha(parts.alpha);
if (alpha === null) return null;
const [c1, c2, c3] = parts.values as [string, string, string];
if (name === "rgb" || name === "rgba") {
const rgb = [c1, c2, c3].map((t) => numberOrPercent(t, 255));
if (rgb.some((c) => c === null)) return null;
const [r, g, b] = rgb.map((c) => clamp(c!, 0, 255)) as [number, number, number];
return { r, g, b, a: alpha };
}
if (name === "hsl" || name === "hsla") {
const h = hue(c1);
const s = numberOrPercent(c2, 1);
const l = numberOrPercent(c3, 1);
if (h === null || s === null || l === null) return null;
const [r, g, b] = hslToRgb(h, clamp(s, 0, 1), clamp(l, 0, 1));
return { r, g, b, a: alpha };
}
if (name === "oklch") {
const l = numberOrPercent(c1, 1);
const c = numberOrPercent(c2, 0.4);
const h = hue(c3);
if (l === null || c === null || h === null) return null;
const [r, g, b] = oklchToRgb(l, c, h);
return { r, g, b, a: alpha };
}
return null;
}
/** `top` painted over `bottom` (source-over). */
export function composite(top: Rgba, bottom: Rgba): Rgba {
const a = top.a + bottom.a * (1 - top.a);
if (a === 0) return { r: 0, g: 0, b: 0, a: 0 };
const channel = (t: number, b: number) => (t * top.a + b * bottom.a * (1 - top.a)) / a;
return {
r: channel(top.r, bottom.r),
g: channel(top.g, bottom.g),
b: channel(top.b, bottom.b),
a,
};
}
/** WCAG 2 relative luminance of an opaque colour. */
export function relativeLuminance(color: Rgba): number {
const linear = (c: number) => {
const v = c / 255;
return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
};
return 0.2126 * linear(color.r) + 0.7152 * linear(color.g) + 0.0722 * linear(color.b);
}
/**
* WCAG 2 contrast ratio of `fg` drawn on `bg`, 1–21. A translucent `fg` is composited over `bg`
* first; `bg` must already be opaque — composite it over whatever it sits on before asking.
*/
export function contrastRatio(fg: Rgba, bg: Rgba): number {
if (bg.a < 1)
throw new Error("contrastRatio: composite the background onto an opaque layer first");
const top = relativeLuminance(composite(fg, bg));
const bottom = relativeLuminance(bg);
const [light, dark] = top > bottom ? [top, bottom] : [bottom, top];
return (light + 0.05) / (dark + 0.05);
}
/** `#rrggbb` (or `#rrggbbaa` when translucent), for messages. */
export function formatColor(color: Rgba): string {
const hex = (n: number) =>
Math.round(clamp(n, 0, 255))
.toString(16)
.padStart(2, "0");
const alpha = color.a < 1 ? hex(color.a * 255) : "";
return `#${hex(color.r)}${hex(color.g)}${hex(color.b)}${alpha}`;
}