roundel 0.2.0 → 0.3.1

package/README.md

@@ -176,3 +176,18 @@ colours, [flagstaff](https://www.npmjs.com/package/flagstaff) flies it, and
 none requires the others.
 
 MIT © Ofri Peretz — see [LICENSE](./LICENSE).
+
+## Benchmarks
+
+Every number here is produced by `npm run bench` and published at [/docs/benchmarks](/docs/benchmarks).
+
+Graded by the incumbent's own test suite:
+
+| suite | passing |
+| :-- | --: |
+| `chalk` | 58 / 58 |
+## Where it sits
+
+Plugins register under the `tokens` key, against the one schema the whole family shares.
+
+`burgee` and `flagstaff` build on it, and it builds on nothing in this family.

package/dist/chalk.js

@@ -1,4 +1,5 @@
 import { colorLevel } from './policy.js';
+import { processRuntime } from './runtime.js';
 import { sgr } from './tokens.js';
 const MODIFIERS = {
     reset: [0, 0],
@@ -120,16 +121,13 @@ function builder(root, chain, visible) {
         },
     });
 }
-const proc = globalThis
-    .process;
-const detect = (stream) => colorLevel({ env: proc?.env ?? {}, argv: proc?.argv ?? [], isTTY: { stdout: proc?.[stream]?.isTTY === true } });
-const stdoutLevel = detect('stdout');
-const stderrLevel = detect('stderr');
+const stdoutLevel = colorLevel(processRuntime());
+const stderrLevel = colorLevel(processRuntime('stderr'));
 const info = (level) => (level === 0 ? false : { level, hasBasic: true, has256: level >= 2, has16m: level === 3 });
 function create(options = {}, detected = stdoutLevel) {
-    if (options.level !== undefined)
-        checkLevel(options.level);
-    return builder({ level: options.level ?? detected }, [], false);
+    const { level = detected } = options;
+    checkLevel(level);
+    return builder({ level }, [], false);
 }
 export class Chalk {
     constructor(options) {

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/policy.d.ts

@@ -13,21 +13,7 @@
  * 9,370 bytes. Comments are stripped from `dist`, so the prose is free; the statements
  * are not.
  */
-/**
- * The slice of a runtime the policy needs. burgee's `processRuntime` satisfies it, so
- * does a two-line literal in a test; nothing here imports a type from anywhere.
- */
-export interface Runtime {
-    env: Record<string, string | undefined>;
-    isTTY: {
-        stdout: boolean;
-    };
-    /**
-     * The process arguments, when the caller owns them: `--color`, `--no-color` and
-     * `--color=…` are read here and nowhere else. A test literal leaves it out.
-     */
-    argv?: readonly string[];
-}
+import { type Runtime } from './runtime.js';
 export type OutputMode = 'tty' | 'pipe' | 'json' | 'accessible' | 'ci';
 declare const MAX_LEVEL = 3;
 /** chalk's levels: none, 16 colours, 256 colours, truecolor. */
@@ -90,4 +76,13 @@ export declare const flown: {
     level: ColorLevel;
     paint: Partial<Record<TokenName, Paint>>;
 };
-export {};
+/**
+ * The slice of a runtime this file reads is declared in `./runtime.js`, beside the one
+ * function in the package that names the process (Y9), and re-exported here because
+ * `roundel/policy` is the subpath a caller imports it from. One declaration, two doors.
+ *
+ * The import at the top is type-only, so `verbatimModuleSyntax` erases it whole: `policy.js`
+ * reaches no new module, and the weight of every subpath that stands on it is unchanged.
+ * `subpath-isolation.test.ts` is what holds that.
+ */
+export type { Runtime };

package/dist/runtime.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The slice of the world this package needs, and the one file in it that names the process
+ * (Y9). The same seam `paratext/src/runtime.ts` and `burgee/src/runtime.ts` declare, for
+ * the same reason: `policy.ts` answers "where is this output going?" from a `Runtime`, so a
+ * test declares a terminal in two lines and a host can lie about one on purpose.
+ *
+ * The guarded cast below moved here whole from `chalk.ts`, unchanged. It is guarded because
+ * `process` is not a given where a bundle runs, and it is bound to a local because a
+ * textual lock cannot tell `proc?.env` from any other local — the exemption is recorded in
+ * burgee's `process-reference-lock.test.ts` against this file, so a reader looking for it
+ * finds it, but it is the cast and not the entry that keeps roundel honest.
+ *
+ * Nothing is cached here. `./chalk` calls `processRuntime()` twice at import because
+ * chalk's contract is "detect the terminal at import" (R6); every other caller in the
+ * family passes its own `Runtime` and never reaches this file at all.
+ */
+/**
+ * The slice of a runtime the policy needs. burgee's `processRuntime` satisfies it, so does
+ * a two-line literal in a test; nothing here imports a type from anywhere.
+ */
+export interface Runtime {
+    env: Record<string, string | undefined>;
+    isTTY: {
+        stdout: boolean;
+    };
+    /**
+     * The process arguments, when the caller owns them: `--color`, `--no-color` and
+     * `--color=…` are read in `policy.ts` and nowhere else. A test literal leaves it out.
+     */
+    argv?: readonly string[];
+}
+/**
+ * The real process. `stream` names the stream this output is going to — `chalkStderr` and
+ * `supportsColorStderr` detect against stderr, as chalk does — and its `isTTY` lands in
+ * `isTTY.stdout`, which is the policy's name for "the stream this output goes to" rather
+ * than for fd 1 in particular.
+ *
+ * `argv` defaults to empty rather than absent: `exactOptionalPropertyTypes` makes an
+ * optional `argv` mean "the key may be missing", not "the value may be undefined".
+ */
+export declare const processRuntime: (stream?: "stdout" | "stderr") => Runtime;

package/dist/runtime.js

@@ -0,0 +1,2 @@
+const proc = globalThis.process;
+export const processRuntime = (stream = 'stdout') => ({ env: proc?.env ?? {}, argv: proc?.argv ?? [], isTTY: { stdout: proc?.[stream]?.isTTY === true } });

package/dist/schema.json

@@ -1 +1 @@
-{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://github.com/ofri-peretz/burgee/blob/main/packages/flagstaff/src/schema.json","title":"flagstaff plugin","description":"A plugin is one plain object. Everything in it is data that can be read without running it; the only functions allowed are a component's `static` (required) and `frame` (optional). A spinner or component without a static projection is refused at register().","type":"object","required":["name"],"additionalProperties":true,"properties":{"name":{"type":"string","minLength":1,"description":"The plugin's name; also the prefix a host may use when two plugins contribute the same key."},"contract":{"type":"integer","minimum":1,"description":"The plugin contract this object follows. A host refuses a newer contract than it knows."},"tokens":{"type":"object","description":"A roundel theme: semantic token name to a hex colour, contrast-checked when flown.","additionalProperties":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}},"glyphs":{"type":"object","description":"Symbols by meaning: `ok`, `fail`, `warn`, `info`, `running`. A plugin that ships glyphs changes every built-in that draws one.","additionalProperties":{"type":"string","minLength":1}},"spinners":{"type":"object","description":"Spinner styles by name, in cli-spinners' shape plus the static projection.","additionalProperties":{"$ref":"#/$defs/spinner"}},"borders":{"type":"object","description":"Border styles a box can be drawn with, by name.","additionalProperties":{"$ref":"#/$defs/border"}},"components":{"type":"object","description":"Components by name: `static(state)` returns the text a pipe, an agent or a screen reader gets; `frame(t, state)` is the optional animated form.","additionalProperties":{"$ref":"#/$defs/component"}}},"$defs":{"spinner":{"type":"object","required":["frames","interval","static"],"properties":{"frames":{"type":"array","items":{"type":"string"},"minItems":1},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between frames on a terminal."},"static":{"type":"string","description":"What a pipe prints instead of the animation."}}},"component":{"type":"object","required":["static"],"properties":{"static":{"description":"(state) => string. Required: the projection every non-terminal mode prints."},"frame":{"description":"(t, state) => string. Optional: the frame at t milliseconds since hoisting."},"sample":{"type":"object","required":["running","done"],"description":"Two states to *show* this component with: `flagstaff check` and the docs gallery render `running` then `done`. Omitted, they assume `{ phase: 'running' }` and `{ phase: 'done' }` and say so in the output. The loop never reads it — a running program's state comes from the program.","properties":{"running":{"description":"The state to open with."},"done":{"description":"The state to close with."}}},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between repaints when `frame` is given; 80 when omitted."}}},"border":{"type":"object","required":["topLeft","top","topRight","left","right","bottomLeft","bottom","bottomRight"],"description":"cli-boxes' shape exactly, so that corpus imports unchanged.","properties":{"topLeft":{"type":"string"},"top":{"type":"string"},"topRight":{"type":"string"},"left":{"type":"string"},"right":{"type":"string"},"bottomLeft":{"type":"string"},"bottom":{"type":"string"},"bottomRight":{"type":"string"}}}}}
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://github.com/ofri-peretz/burgee/blob/main/packages/flagstaff/src/schema.json","title":"flagstaff plugin","description":"A plugin is one plain object. Everything in it is data that can be read without running it; the only functions allowed are a component's `static` (required) and `frame` (optional). A spinner or component without a static projection is refused at register().","type":"object","required":["name"],"additionalProperties":true,"properties":{"name":{"type":"string","minLength":1,"description":"The plugin's name; also the prefix a host may use when two plugins contribute the same key."},"contract":{"type":"integer","minimum":1,"description":"The plugin contract this object follows. A host refuses a newer contract than it knows."},"tokens":{"type":"object","description":"A roundel theme: semantic token name to a hex colour, contrast-checked when flown.","additionalProperties":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"propertyNames":{"enum":["error","warn","ok","hint","muted","command","flag","value","heading","ground"],"description":"roundel's ten semantic tokens, and nothing else — `roundel`'s own validate() refuses any other name."}},"glyphs":{"type":"object","description":"Symbols by meaning: `ok`, `fail`, `warn`, `info`, `running`. A plugin that ships glyphs changes every built-in that draws one.","additionalProperties":{"type":"string","minLength":1}},"spinners":{"type":"object","description":"Spinner styles by name, in cli-spinners' shape plus the static projection.","additionalProperties":{"$ref":"#/$defs/spinner"}},"borders":{"type":"object","description":"Border styles a box can be drawn with, by name.","additionalProperties":{"$ref":"#/$defs/border"}},"components":{"type":"object","description":"Components by name: `static(state)` returns the text a pipe, an agent or a screen reader gets; `frame(t, state)` is the optional animated form.","additionalProperties":{"$ref":"#/$defs/component"}},"capabilities":{"$ref":"#/$defs/capabilities"}},"$defs":{"spinner":{"type":"object","required":["frames","interval","static"],"properties":{"frames":{"type":"array","items":{"type":"string"},"minItems":1},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between frames on a terminal."},"static":{"type":"string","description":"What a pipe prints instead of the animation."}}},"component":{"type":"object","required":["static"],"properties":{"static":{"description":"(state) => string. Required: the projection every non-terminal mode prints."},"frame":{"description":"(t, state) => string. Optional: the frame at t milliseconds since hoisting."},"sample":{"type":"object","required":["running","done"],"description":"Two states to *show* this component with: `flagstaff check` and the docs gallery render `running` then `done`. Omitted, they assume `{ phase: 'running' }` and `{ phase: 'done' }` and say so in the output. The loop never reads it — a running program's state comes from the program.","properties":{"running":{"description":"The state to open with."},"done":{"description":"The state to close with."}}},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between repaints when `frame` is given; 80 when omitted."}}},"border":{"type":"object","required":["topLeft","top","topRight","left","right","bottomLeft","bottom","bottomRight"],"description":"cli-boxes' shape exactly, so that corpus imports unchanged.","properties":{"topLeft":{"type":"string"},"top":{"type":"string"},"topRight":{"type":"string"},"left":{"type":"string"},"right":{"type":"string"},"bottomLeft":{"type":"string"},"bottom":{"type":"string"},"bottomRight":{"type":"string"}}},"capability":{"type":"object","required":["name","osc","when","encode","fallback"],"additionalProperties":false,"description":"One paratext capability: what it says to the terminal, when the terminal is believed to understand it, and what prints when it does not. No functions, so it travels through JSON. `encode` and `fallback` are templates: `{field}` is the field's value, `{field|base64}` is it base64-encoded, and `[ … ]` is emitted only when every field inside it has a value.","properties":{"name":{"type":"string","minLength":1,"description":"How callers name it. Registering an existing name replaces it — how a caller corrects a guess we got wrong."},"osc":{"description":"The OSC code this speaks, or 'BEL' for the bell and for protocols that are not OSC at all, such as Kitty's.","oneOf":[{"type":"integer","minimum":0},{"const":"BEL"}]},"when":{"type":"object","description":"When the terminal is believed to understand it. Every clause must hold; `termProgram` and `envAny` are ORs within themselves. Guesses — no terminal answers 'do you do OSC 1337' — and therefore data a caller can replace.","additionalProperties":false,"properties":{"tty":{"type":"boolean","description":"Refuse a pipe. Almost always true: a file that receives OSC gets control bytes in it."},"termProgram":{"type":"array","items":{"type":"string"},"description":"Any one of these TERM_PROGRAM values."},"envAny":{"type":"array","items":{"type":"string"},"description":"Any one of these environment variables merely being set, as VTE announces itself."},"term":{"type":"string","description":"An exact TERM — Kitty is xterm-kitty."}}},"encode":{"type":"string","minLength":1,"description":"The bytes, as a template, for a terminal that does understand."},"fallback":{"type":"string","description":"What to print when it does not — PRINCIPLES rule 6. '' is a legitimate answer, a window title having nothing to say in a log; absence is not, which is why this is required and may be ''."}},"examples":[{"name":"kitty-image","osc":"BEL","when":{"tty":true,"term":"xterm-kitty"},"encode":"\u001b_Ga=T,f=100;{base64}\u001b\\","fallback":"{caption}"}]},"capabilities":{"type":"object","description":"paratext capabilities by name — the OSC section of a plugin, read the way flagstaff reads `spinners`.","additionalProperties":{"$ref":"#/$defs/capability"}},"capabilityDocument":{"description":"What paratext's `check()` accepts. Two shapes, and only one of them survives 1.0.","oneOf":[{"description":"The family shape: a plugin carrying its capabilities under `capabilities`.","type":"object","required":["name","capabilities"],"properties":{"name":{"type":"string","minLength":1},"contract":{"type":"integer","minimum":1},"capabilities":{"$ref":"#/$defs/capabilities"}}},{"deprecated":true,"description":"Deprecated: one capability as the whole document, the shape paratext's schema had before this one absorbed it. Accepted for one minor release, removed at 1.0 — `check()` validates it and says so.","$ref":"#/$defs/capability"}]}}}

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.2.0",
+  "version": "0.3.1",
   "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",