roundel 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ofri Peretz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,23 @@
-# roundel
+<p align="center">
+  <a href="https://github.com/ofri-peretz/burgee/tree/main/packages/roundel" target="blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ofri-peretz/burgee/main/brand-assets/roundel-lockup.svg" />
+      <img src="https://raw.githubusercontent.com/ofri-peretz/burgee/main/brand-assets/roundel-lockup-light.svg" alt="roundel" width="360" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  The colours a CLI carries — error and hint, not red and blue.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/roundel"><img src="https://img.shields.io/npm/v/roundel?style=flat-square&color=0a6b47" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/roundel"><img src="https://img.shields.io/npm/dm/roundel?style=flat-square" alt="npm downloads" /></a>
+  <img src="https://img.shields.io/badge/runtime%20dependencies-0-0a6b47?style=flat-square" alt="Zero runtime dependencies" />
+  <img src="https://img.shields.io/badge/Node.js-24+-green.svg?style=flat-square" alt="Node.js 24+" />
+  <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT" />
+</p>
 
 chalk gives you `red`; picocolors gives you `red` for fewer bytes. Neither gives you
 `error`, and each decides on its own whether the terminal has colour — which is why a
@@ -14,7 +33,11 @@ not a flag. That is what this package is for a command-line program: not `red` a
 but `error`, `hint`, `command` and `flag`, the colours that mean *you*, carried onto the
 terminal as a theme.
 
-## Use
+## Start here
+
+```bash
+npm install roundel
+```
 
 ```js
 import { fly } from 'roundel/theme';
@@ -144,6 +167,12 @@ Node ≥ 24.
 - **`roundel/import`** — `fromBase16(scheme)` and `fromITerm(plist)`: a theme from the two
   largest corpora of terminal palettes, contrast-checked on the way in.
 
-Part of the [burgee](https://github.com/ofri-peretz/burgee) family: a CLI on burgee declares
-what it is, roundel carries its colours, flagstaff flies it, caique answers back. Each is
-an independent package; none requires the others.
+---
+
+Part of the [burgee](https://github.com/ofri-peretz/burgee) family: a CLI on
+[burgee](https://www.npmjs.com/package/burgee) declares what it is, roundel carries its
+colours, [flagstaff](https://www.npmjs.com/package/flagstaff) flies it, and
+[caique](https://www.npmjs.com/package/caique) answers back. Each is an independent package;
+none requires the others.
+
+MIT © Ofri Peretz — see [LICENSE](./LICENSE).

package/dist/contrast.d.ts

@@ -1,9 +1,16 @@
 /**
- * The WCAG 2.2 contrast maths (R5), copied from `burgee/contrast` on purpose: sixty lines
- * duplicated beats a dependency arrow pointing the wrong way (U1). This copy is held to
- * `contrast-vectors.json` by its test; burgee's test does not read that file yet, so the
- * drift lock is one-sided until the follow-up lands (burgee contrast test to read roundel's
- * contrast-vectors.json).
+ * The WCAG 2.2 contrast maths (R5).
+ *
+ * It was copied from `burgee/contrast` under Y1 — "sixty lines duplicated beats a dependency
+ * arrow pointing the wrong way" — on the condition that the two copies share a test-vector
+ * file. That condition was met half way for five days: this copy was pinned to
+ * `contrast-vectors.json` and burgee's was not, which is the worse arrangement, because the
+ * pinned copy cannot drift and the unpinned one can while keeping a green suite.
+ *
+ * **#194 settled it differently and better:** the arrow was reversed, so there is one
+ * implementation and `burgee/contrast` imports this one. The vectors remain as a reference —
+ * values computed outside this file, which is the only kind that can catch a wrong constant —
+ * and `scripts/shared-vectors-lock.test.ts` keeps them read rather than kept.
  *
  * `fly()` uses it to refuse a truecolor token that would not read against the declared
  * ground. Nothing here is asked about the 16- and 256-colour palettes: those are the
@@ -16,9 +23,54 @@ export declare const AA: {
     /** Large text, UI components, and meaningful parts of a graphic. */
     readonly GRAPHIC: 3;
 };
+/**
+ * The stricter conformance level, for a caller who needs it: low-vision users, a CLI run on a
+ * projector, a terminal in daylight, or an organisation whose accessibility policy says AAA
+ * and does not care that this is a terminal.
+ *
+ * Not the default, and not because AA is good enough. At 7:1 the 256-colour palette runs out
+ * of room fast — a great many perfectly reasonable brand colours have no readable substitute
+ * in the cube at that floor — so defaulting to AAA would refuse themes that work for almost
+ * everyone on almost every terminal. It is the caller's call, which is the only place that
+ * judgement can honestly sit.
+ */
+export declare const AAA: {
+    /** Body text against its background. */
+    readonly TEXT: 7;
+    /** Large text, UI components, and meaningful parts of a graphic. */
+    readonly GRAPHIC: 4.5;
+};
+/** Which WCAG conformance level a theme is held to. `AA` unless a caller asks for more. */
+export type Conformance = 'AA' | 'AAA';
+/** The floors for a conformance level, so a caller names a standard rather than a number. */
+export declare const floors: (level?: Conformance) => typeof AA | typeof AAA;
 /** `#abc` and `#aabbcc` both parse, to sRGB channels in 0..1. Anything else is a mistake worth throwing on. */
 export declare function channels(hex: string): [number, number, number];
 /** WCAG relative luminance. */
 export declare function luminance(hex: string): number;
 /** The WCAG contrast ratio between two colours. Order does not matter. */
 export declare function contrast(a: string, b: string): number;
+/** One token's verdict at one colour level, in the words somebody fixing it would use. */
+export interface ThemeFinding {
+    /** The token name — `error`, `ok`, `command`. */
+    token: string;
+    /** `truecolor` or `256`. Never `16`: those values are the user's terminal theme. */
+    at: 'truecolor' | '256';
+    /** What the terminal is actually sent at this level, which is not always the hex written. */
+    colour: string;
+    ground: string;
+    ratio: number;
+    required: number;
+    passes: boolean;
+}
+export declare const round2: (value: number) => number;
+/**
+ * One line per finding, aligned, for a terminal or a failing test. Mirrors
+ * `burgee/contrast`'s `report` — the same shape in both packages, because somebody reading a
+ * theme audit and a brand audit on the same day should not have to learn two layouts.
+ *
+ * Passing rows are printed too. A report that lists only failures cannot tell "nothing is
+ * wrong" from "nothing was checked", and the second is the state this package was in for the
+ * 256-colour level until 2026-09-13.
+ */
+export declare function reportTheme(findings: readonly ThemeFinding[]): string;

package/dist/contrast.js

@@ -2,6 +2,11 @@ export const AA = {
     TEXT: 4.5,
     GRAPHIC: 3,
 };
+export const AAA = {
+    TEXT: 7,
+    GRAPHIC: 4.5,
+};
+export const floors = (level = 'AA') => (level === 'AAA' ? AAA : AA);
 const SRGB_MAX = 255;
 const LINEAR_THRESHOLD = 0.03928;
 const LINEAR_DIVISOR = 12.92;
@@ -33,3 +38,15 @@ export function contrast(a, b) {
     const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
     return (hi + CONTRAST_OFFSET) / (lo + CONTRAST_OFFSET);
 }
+const CENTS = 100;
+export const round2 = (value) => Math.round(value * CENTS) / CENTS;
+export function reportTheme(findings) {
+    if (findings.length === 0)
+        return "no hex tokens to check — every token is a format name, and those are the terminal's own colours";
+    const token = Math.max(...findings.map((f) => f.token.length));
+    const at = Math.max(...findings.map((f) => f.at.length));
+    return findings
+        .map((f) => `${f.passes ? 'pass' : 'FAIL'}  ${f.token.padEnd(token)}  ${f.at.padEnd(at)}  ` +
+        `${f.colour} on ${f.ground}  ${f.ratio.toFixed(2)}:1 (needs ${f.required}:1)`)
+        .join('\n');
+}

package/dist/theme.d.ts

@@ -1,10 +1,74 @@
+/**
+ * The theme (R4, R5): one map from token to style, flown once for the whole program.
+ *
+ * A style is either a list of `util.styleText` format names — the user's own terminal
+ * palette, never checked or claimed — or a `#rrggbb`, which is truecolor at level 3 and
+ * falls back to the nearest of 256 or 16 colours below it. Every hex token is checked against
+ * the declared ground at 4.5:1 before it is flown — **and so is the 256-colour entry it
+ * degrades to**, at every level, so a theme that would not read on somebody's 256-colour
+ * terminal fails in CI on a truecolor one. Level 1 is not checked and cannot be: the basic
+ * sixteen are the user's own theme, and a ratio over them would be invented.
+ */
+import { type Conformance, type ThemeFinding } from './contrast.js';
 import { type Format, type ModeOptions, type Runtime, type TokenName } from './policy.js';
 export type Hex = `#${string}`;
 export type Style = Hex | readonly Format[];
 /** Each token's style, and the ground the hex ones are checked against (default: near-black). */
+/**
+ * A theme: a style per token, the ground the hex ones are checked against, and which WCAG
+ * level to hold them to.
+ *
+ * `conformance` is the knob a team turns when AA is not enough — low vision, a projector, a
+ * policy that says AAA. It raises the floor for **both** jobs at once: the check that refuses
+ * a theme, and the search that picks the 256-colour substitute. Those two have to agree, or a
+ * caller asking for AAA gets a verdict at one standard and a colour chosen at another.
+ */
 export type Theme = Partial<Record<TokenName, Style>> & {
     ground?: Hex;
+    conformance?: Conformance;
 };
+/**
+ * The sRGB of a 256-palette index, which is `ansi256` run backwards. Defined for 16–255 only,
+ * and that is the whole reason this check is possible: **entries 0–15 are the user's terminal
+ * theme and entries 16–255 are not.** Exported because it is the only honest way to ask
+ * "what will the terminal actually paint", which is a question a caller checking its own
+ * theme has as much right to ask as `fly()` does. The 6×6×6 cube and the 24-step grey ramp are the xterm
+ * values every terminal ships and none of them themes, so a contrast number over them is
+ * measured rather than invented — which is exactly what `contrast.ts` says cannot be done for
+ * the basic sixteen. `ansi256` never returns below 16, so every paint it produces is knowable.
+ */
+export declare function rgb256(index: number): Hex;
+/**
+ * sRGB 0–255 to OKLab. Björn Ottosson's matrices, written as straight-line arithmetic.
+ *
+ * The first draft used `map`/`reduce` over two 9-element matrices, which read better and cost
+ * **2,766 bytes** — `./theme` grew 44% against a 6,300-byte budget, on a package whose whole
+ * claim is that each subpath is at or under the incumbent it replaces. Eighteen multiplies
+ * written out are a third of that. The matrices are not data anyone configures, so making them
+ * data bought nothing and charged for it.
+ *
+ * Exported so the coefficients are pinnable. They were not, at first: nudging the first one
+ * from 0.4122214708 to 0.4022214708 left all 253 tests green, because everything downstream
+ * computed distance with the *same* corrupted matrix and the palette is coarse enough to
+ * absorb the error. A transform can only be checked against numbers from outside it, so
+ * `theme.test.ts` holds it to the five published reference values.
+ */
+export declare function toOklab(r: number, g: number, b: number): [number, number, number];
+/**
+ * Every token's verdict, as data — **without throwing.**
+ *
+ * `fly()` refuses a theme that does not read, which is right at startup and useless while you
+ * are choosing colours: a caller who wants to *know* should not have to catch an exception and
+ * parse its message. So the judgement lives here and `fly()` is a filter over it, which also
+ * means the refusal and the report can never disagree about what passes.
+ *
+ * Two rows per hex token — `truecolor` and `256` — because those are the two colours a
+ * terminal can actually be sent, and they are not the same colour. **No row for 16**: those
+ * values are the user's own terminal theme, so there is no ratio to report and a number there
+ * would be invented. A token given format names rather than a hex gets no row either, for the
+ * same reason: `['bold', 'red']` is the terminal's red.
+ */
+export declare function audit(theme?: Theme): ThemeFinding[];
 /**
  * Fly the theme: decide the colour level from the runtime once, check every hex token
  * against the ground, and set what the tokens paint from now on. Call it at startup, with

package/dist/theme.js

@@ -1,4 +1,4 @@
-import { AA, channels, contrast } from './contrast.js';
+import { channels, contrast, floors, round2 } from './contrast.js';
 import { colorLevel, flown, } from './policy.js';
 const ROCK = ['#a84c17', '#f4794a'];
 const JUNIPER = ['#0a6b47', '#0d9460'];
@@ -25,11 +25,16 @@ const CUBE_START = 16;
 const CUBE_ROW = 36;
 const CUBE_COL = 6;
 const GREY_START = 232;
+const GREY_STEP = 10;
+const HEX_BASE = 16;
+const RGB_PARTS = 3;
+const CUBE_LEVELS = [0, 95, 135, 175, 215, 255];
 const GREY_STEPS = 24;
 const GREY_LOW = 8;
 const GREY_HIGH = 248;
 const GREY_SPAN = 247;
 const CUBE_WHITE = 231;
+const GREY_LAST = 255;
 const BASIC_NAMES = ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'];
 const BLUE_BIT = 2;
 const GREEN_BIT = 1;
@@ -59,26 +64,93 @@ function ansi16(r, g, b) {
         return name;
     return name === 'black' ? 'gray' : `${name}Bright`;
 }
-function resolve(style, level) {
+export function rgb256(index) {
+    const hex = (r, g, b) => `#${[r, g, b].map((v) => v.toString(HEX_BASE).padStart(2, '0')).join('')}`;
+    if (index >= GREY_START)
+        return hex(...Array(RGB_PARTS).fill(GREY_LOW + (index - GREY_START) * GREY_STEP));
+    const n = index - CUBE_START;
+    const at = (i) => CUBE_LEVELS[i];
+    return hex(at(Math.floor(n / CUBE_ROW)), at(Math.floor((n % CUBE_ROW) / CUBE_COL)), at(n % CUBE_COL));
+}
+const LINEAR_THRESHOLD = 0.04045;
+const LINEAR_DIVISOR = 12.92;
+const GAMMA_OFFSET = 0.055;
+const GAMMA_EXPONENT = 2.4;
+export function toOklab(r, g, b) {
+    const lin = (v) => {
+        const c = v / SRGB_MAX;
+        return c <= LINEAR_THRESHOLD ? c / LINEAR_DIVISOR : ((c + GAMMA_OFFSET) / (1 + GAMMA_OFFSET)) ** GAMMA_EXPONENT;
+    };
+    const R = lin(r);
+    const G = lin(g);
+    const B = 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.793_617_785 * m - 0.004_072_046_8 * s,
+        1.9779984951 * l - 2.428_592_205 * m + 0.4505937099 * s,
+        0.0259040371 * l + 0.7827717662 * m - 0.808_675_766 * s,
+    ];
+}
+function degrade(r, g, b, ground, floor) {
+    const plain = ansi256(r, g, b);
+    const target = toOklab(r, g, b);
+    let best = -1;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (let index = CUBE_START; index <= GREY_LAST; index++) {
+        const candidate = rgb256(index);
+        if (contrast(candidate, ground) < floor)
+            continue;
+        const [cr, cg, cb] = channels(candidate).map((v) => Math.round(v * SRGB_MAX));
+        const [cl, ca, cb2] = toOklab(cr, cg, cb);
+        const distance = (target[0] - cl) ** 2 + (target[1] - ca) ** 2 + (target[2] - cb2) ** 2;
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = index;
+        }
+    }
+    return best === -1 ? plain : best;
+}
+function resolve(style, level, ground, floor) {
     if (typeof style !== 'string')
         return style;
     const [r, g, b] = channels(style).map((v) => Math.round(v * SRGB_MAX));
     if (level === TRUECOLOR)
         return { sgr: [SGR_FG, SGR_RGB, r, g, b] };
-    return level === COLORS_256 ? { sgr: [SGR_FG, SGR_256, ansi256(r, g, b)] } : [ansi16(r, g, b)];
+    return level === COLORS_256 ? { sgr: [SGR_FG, SGR_256, degrade(r, g, b, ground, floor)] } : [ansi16(r, g, b)];
 }
-export function fly(theme, rt, opts) {
-    const level = colorLevel(rt, opts);
+export function audit(theme = {}) {
     const ground = theme.ground ?? INK;
-    const styles = TOKENS.map((name) => [name, theme[name] ?? DEFAULTS[name](ground)]);
-    const failures = styles.flatMap(([name, style]) => {
+    const required = floors(theme.conformance).TEXT;
+    return TOKENS.flatMap((name) => {
+        const style = theme[name] ?? DEFAULTS[name](ground);
         if (typeof style !== 'string')
             return [];
-        const ratio = contrast(style, ground);
-        return ratio < AA.TEXT ? [`${name} ${style} on ${ground} is ${ratio.toFixed(2)}:1`] : [];
+        const [r, g, b] = channels(style).map((v) => Math.round(v * SRGB_MAX));
+        const at = [
+            ['truecolor', style],
+            ['256', rgb256(degrade(r, g, b, ground, required))],
+        ];
+        return at.map(([where, colour]) => {
+            const ratio = round2(contrast(colour, ground));
+            return { token: name, at: where, colour, ground, ratio, required, passes: ratio >= required };
+        });
     });
+}
+export function fly(theme, rt, opts) {
+    const level = colorLevel(rt, opts);
+    const ground = theme.ground ?? INK;
+    const floor = floors(theme.conformance).TEXT;
+    const styles = TOKENS.map((name) => [name, theme[name] ?? DEFAULTS[name](ground)]);
+    const written = new Map(styles);
+    const failures = audit(theme)
+        .filter((f) => !f.passes)
+        .map((f) => f.at === 'truecolor'
+        ? `${f.token} ${f.colour} on ${f.ground} is ${f.ratio.toFixed(2)}:1`
+        : `${f.token} ${String(written.get(f.token))} at 256 colours is ${f.colour} on ${f.ground}, ${f.ratio.toFixed(2)}:1`);
     if (failures.length > 0)
-        throw new Error(`roundel: below ${AA.TEXT}:1 — ${failures.join('; ')}`);
+        throw new Error(`roundel: below ${floor}:1 (WCAG ${theme.conformance ?? 'AA'}) — ${failures.join('; ')}`);
     flown.level = level;
-    flown.paint = Object.fromEntries(styles.map(([name, style]) => [name, resolve(style, level)]));
+    flown.paint = Object.fromEntries(styles.map(([name, style]) => [name, resolve(style, level, ground, floor)]));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roundel",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "The colours a CLI carries. One output policy, semantic tokens, a theme, and a chalk migration path lighter than chalk. Zero dependencies.",
   "license": "MIT",
   "type": "module",
@@ -55,6 +55,7 @@
     "build": "tsc -p tsconfig.build.json && node ../../scripts/schema-to-dist.mjs && node ../../scripts/strip-comments.mjs dist",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run --passWithNoTests",
+    "coverage": "vitest run --coverage.enabled",
     "lint": "eslint src"
   },
   "repository": {