roundel 0.0.1 → 0.2.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,7 +1,31 @@
-# 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>
 
-**Not yet released.** This version reserves the name; the first working release follows
-[`docs/intents/cli-style/`](https://github.com/ofri-peretz/burgee/tree/main/docs/intents/cli-style).
+<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
+program's spinner, prompt and help so often disagree. **roundel** is the colours a CLI
+carries: one output policy decided once from the runtime, nine semantic tokens over
+`util.styleText`, and a theme that changes them all together, contrast-checked before it
+flies — plus chalk's API over the same tokens, for the program that is not ready to give
+chalk up. Zero dependencies, five subpaths, each costing only itself.
 
 A **roundel** is a flag's colours carried onto another surface — the rings on an aircraft's
 wing, the London Underground sign. Identity, expressed purely in colour, on something that is
@@ -9,16 +33,146 @@ 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.
 
-## What it will be
+## Start here
+
+```bash
+npm install roundel
+```
+
+```js
+import { fly } from 'roundel/theme';
+import { command, error, hint } from 'roundel/tokens';
+
+// Once, at startup. The runtime is yours to describe; nothing here reads `process`.
+fly({}, { env: process.env, isTTY: { stdout: Boolean(process.stdout.isTTY) } });
+
+console.error(`${error('missing --name')}  ${hint('try')} ${command('greet --name ada')}`);
+```
+
+Through a pipe with nothing asked, under `NO_COLOR`, or with `--json`, every token returns
+its input unchanged. On a terminal it styles, at the level the terminal has — and on a pipe
+too when the user said so with `FORCE_COLOR` or `--color`.
+
+## What is here
+
+| Subpath | Gives you |
+| :-- | :-- |
+| `roundel/policy` | `outputMode(rt, { json })` → `tty \| pipe \| json \| accessible \| ci` and `colorLevel(rt)` → `0 \| 1 \| 2 \| 3`. Pure over `{ env, isTTY: { stdout }, argv? }`; the only place in the package that reads `NO_COLOR`, `FORCE_COLOR`, `TERM`, `COLORTERM`, `CI`, `CLI_ACCESSIBLE`, the CI vendor variables or a `--color` flag. |
+| `roundel/tokens` | `error warn ok hint muted command flag value heading` — each `(s: string) => string`, the identity until `fly()` has decided a level above 0. |
+| `roundel/plugin` | `register(plugin)`, `theme()`, `contributions()`. A plugin is the family's one plain object; roundel keeps its `tokens` and ignores every key it does not understand, so the same object works on any subset of the family that is installed. |
+| `roundel/theme` | `fly(theme, rt)`. A theme maps tokens to `styleText` format names (`['bold', 'underline']`) or a `#rrggbb`, and declares the `ground` it will be read on. Hex is truecolor at level 3 and falls back to the nearest of 256 or 16 colours below it. |
+| `roundel/contrast` | `contrast(a, b)`, `luminance(hex)`, `AA` — the WCAG 2.2 maths `fly()` checks with. |
+| `roundel/chalk` | chalk 6's API — `chalk.red.bold(s)`, `chalk.hex('#…')`, `new Chalk({ level })`, `chalkStderr`, `supportsColor`, the name lists — over the tokens' emitter and the policy's level. Graded by chalk's own suite; see below. |
+
+### The policy
+
+First match wins: `json` if the run asked for it; `accessible` if `CLI_ACCESSIBLE`; `ci` if
+`CI` and not a TTY; `pipe` if not a TTY; else `tty`. **The mode decides redraws — spinners,
+progress, anything that rewrites a line — and never the colour level.**
+
+The level is chalk's, and it obeys the user's explicit instruction in any mode: `NO_COLOR`
+wins outright; then `FORCE_COLOR=0`, which supports-color settles before it reads any flag,
+so **an explicit "colour off" is never overridden into colour on** — `FORCE_COLOR=0` with
+`--color=256` is 0, not 2; then the `--color` flags (`--color=256`, `--color=16m`,
+`--no-color`, `--no-colors`, `--color=never`… both spellings, as has-flag has them) when the
+caller hands the policy its `argv`; then `FORCE_COLOR`, which names an exact level
+(`FORCE_COLOR=2` is 2, not "2 or better") or, as `true` or empty, only turns colour on and
+lets the environment decide it. `--json` is the one output the level never enters:
+structured text carries no escapes.
+
+With no instruction at all the order is supports-color's own, deliberately: **a pipe is
+`0`** — a pipe nobody asked to colour is a file or another program's stdin — and
+**accessible mode is `0` too**, because `CLI_ACCESSIBLE` is itself an instruction from a
+human and ANSI colour is noise to a screen reader; an explicit ask still colours either of
+them. Azure Pipelines (`TF_BUILD` *and* `AGENT_NAME`) is the single exception on a pipe,
+exactly where chalk puts it.
+Once colour *is* being detected, on a terminal or because the run asked, `TERM=dumb` is the
+floor, a `CI` run gets its vendor's level (GitHub and Gitea Actions and CircleCI at
+truecolor; Travis, AppVeyor, GitLab, Buildkite, Drone and Codeship at 16), and anything else
+is what `TERM` and `COLORTERM` report. So `FORCE_COLOR=true` on GitHub Actions gives you
+truecolor logs, and nobody else's pipe changes.
+
+One policy, one answer: no two components in a program can reach different conclusions,
+which is the whole point (clack #286).
+
+### The theme
+
+```js
+fly(
+  {
+    ground: '#0a0a0a', // what the hex tokens are checked against; near-black by default
+    error: '#f4794a', // truecolor, checked at 4.5:1 against the ground, or fly() throws
+    heading: ['bold', 'underline'], // the terminal's own palette — never checked or claimed
+  },
+  runtime,
+);
+```
+
+The defaults carry the burgee brand — rock for `error`, juniper for `ok`, each in whichever
+of its deep or lifted variants reads better on the declared ground — and format names for
+the other seven. A hex token below 4.5:1 is refused at every level, not only on truecolor
+terminals, so a theme that would not read fails in CI rather than on one laptop. The 16-
+and 256-colour fallbacks are the user's terminal palette and are not checked: a number
+there would be invented.
+
+## Migrating from chalk
+
+```diff
+- import chalk from 'chalk';
++ import chalk from 'roundel/chalk';
+```
+
+**Identical.** The chain (`chalk.red.bold.underline(s)`, every modifier, the sixteen
+colours and their `Bright` variants, backgrounds, chalk 6's underline styles and colours),
+`rgb`/`hex`/`ansi256` and their `bg`/`underline` forms with chalk's own downsampling at
+levels 2 and 1, nesting and line-break handling byte for byte, `chalk.level` (get and set,
+validated), `new Chalk({ level })`, `chalkStderr`, `supportsColor` / `supportsColorStderr`,
+`modifierNames` / `foregroundColorNames` / `backgroundColorNames` / `underlineColorNames` /
+`colorNames`, `visible`, `reset`, and `Function.prototype` on every link. ESM with a
+`default` condition, so `require('roundel/chalk')` works too.
+
+**Different.**
+
+- **The level is per façade.** `chalk.level = 0` silences `roundel/chalk` and nothing else;
+  the tokens and the theme keep reading the policy. chalk's global mutable level is why chalk
+  and ora disagree about the same terminal, and it stops at this door.
+- **The policy decides colour.** The level is detected once at import through
+  `colorLevel()`, reading the same `NO_COLOR`, `FORCE_COLOR`, `--color`, CI-vendor, `TERM`
+  and `COLORTERM` rules chalk does — see [The policy](#the-policy). Every other package in
+  the family reads the same answer, so `roundel/chalk` and a spinner cannot disagree about
+  the terminal the way chalk and ora do.
+- **No template literal.** `chalk\`{red x}\`` was removed in chalk 5 and is not resurrected.
+- **No emulator allow-list.** chalk's per-terminal-program detection (`TERM_PROGRAM`,
+  kitty, ghostty, wezterm, TeamCity, the Windows build number) is not reproduced; a program
+  on one of those terminals that wants colour asks for it with `FORCE_COLOR` or `--color`.
+
+**Graded by chalk's own suite**, vendored at 6.0.0 into `compat-oracle` and run unedited
+through a generated shim: **58 of 58 tests (100.0%) on 2026-09-08**, alongside the same
+suite scoring 58 / 58 against real chalk in the same run.
+
+## Weight
+
+Every subpath is a lock, not a convention. `roundel/tokens` reaches 3,258 bytes on disk
+(its ceiling is picocolors, 3.3 KB); `roundel/policy` 1,972; `roundel/theme` 6,271;
+`roundel/plugin` 2,812 and reaching no module at all;
+`roundel/contrast` 1,250; `roundel/chalk` 9,311 (its ceiling is chalk 6.0.0's own 9,370,
+before the ansi-styles and supports-color chalk also ships). Importing one never loads
+another — the tokens never carry the theme, the theme never carries the tokens, chalk
+carries neither — and `sideEffects: false` lets a bundler drop what a program does not use.
+ESM with a `default` condition, so `require('roundel/tokens')` works from CommonJS on
+Node ≥ 24.
+
+## What is next
+
+- **`roundel/import`** — `fromBase16(scheme)` and `fromITerm(plist)`: a theme from the two
+  largest corpora of terminal palettes, contrast-checked on the way in.
+
+---
 
-- **One output policy**, decided once from the runtime: `tty`, `pipe`, `json`, `accessible`
-  or `ci`. Every component reads it; none detects the terminal on its own.
-- **Semantic tokens** over `util.styleText`, silent under every mode but `tty`.
-- **A theme** that changes every token at once, contrast-checked when it emits truecolor.
-- **`roundel/chalk`** — chalk's API over Node natives, graded by chalk's own test suite, so a
-  migration is one import and your tests are unchanged.
-- **Zero dependencies**, and every subpath measured against the lightest incumbent it replaces.
+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.
 
-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, answerback replies. Each is
-an independent package; none requires the others.
+MIT © Ofri Peretz — see [LICENSE](./LICENSE).

package/dist/chalk.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `roundel/chalk` (R6): chalk 6's public API — the chainable builder, the mutable `level`,
+ * `Chalk`, `chalkStderr`, `supportsColor` — over the tokens' emitter and the policy's
+ * level, graded by chalk's own suite vendored into `compat-oracle`.
+ *
+ * chalk's mutable `level` is honoured here and nowhere else: `chalk.level = 0` silences
+ * this façade, not the tokens, which read the policy. The template literal
+ * (`chalk\`{red x}\``) went with chalk 5 and is not resurrected. Not one escape is
+ * written here: parameters are computed, `sgr()` in tokens emits them (R3).
+ *
+ * The SGR numbers below are chalk's tables (ansi-styles) as written; naming each would
+ * double the file the R8 ceiling measures, so the lint's magic-number rule is off here.
+ */
+import { type ColorLevel } from './policy.js';
+/** Colour support: none, 16 colours, 256 colours, truecolor. chalk's name for the policy's level. */
+export type ColorSupportLevel = ColorLevel;
+export interface ColorSupport {
+    level: ColorSupportLevel;
+    hasBasic: boolean;
+    has256: boolean;
+    has16m: boolean;
+}
+export type ColorInfo = ColorSupport | false;
+export interface ChalkOptions {
+    /** `undefined` asks for the level to be detected, as omitting it does. */
+    readonly level?: ColorSupportLevel | undefined;
+}
+declare const MODIFIERS: {
+    reset: [number, number];
+    bold: [number, number];
+    dim: [number, number];
+    italic: [number, number];
+    underline: [number, number];
+    underlineDouble: [string, number];
+    underlineCurly: [string, number];
+    underlineDotted: [string, number];
+    underlineDashed: [string, number];
+    overline: [number, number];
+    inverse: [number, number];
+    hidden: [number, number];
+    strikethrough: [number, number];
+};
+type Basic = 'black' | 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan' | 'white';
+type Bright = `${Basic}Bright` | 'gray' | 'grey';
+export type ModifierName = keyof typeof MODIFIERS;
+export type ForegroundColorName = Basic | Bright;
+export type BackgroundColorName = `bg${Capitalize<Basic | Bright>}`;
+export type UnderlineColorName = `underline${Capitalize<Basic | Bright>}`;
+export type ColorName = ForegroundColorName | BackgroundColorName;
+export declare const modifierNames: ModifierName[];
+export declare const foregroundColorNames: ForegroundColorName[];
+export declare const backgroundColorNames: BackgroundColorName[];
+export declare const underlineColorNames: UnderlineColorName[];
+export declare const colorNames: ColorName[];
+interface Base {
+    (...text: unknown[]): string;
+    /** Mutable, as chalk's is; every builder in a chain reads and writes the instance it came from. */
+    level: ColorSupportLevel;
+    rgb(red: number, green: number, blue: number): ChalkInstance;
+    hex(color: string): ChalkInstance;
+    ansi256(index: number): ChalkInstance;
+    bgRgb(red: number, green: number, blue: number): ChalkInstance;
+    bgHex(color: string): ChalkInstance;
+    bgAnsi256(index: number): ChalkInstance;
+    underlineRgb(red: number, green: number, blue: number): ChalkInstance;
+    underlineHex(color: string): ChalkInstance;
+    underlineAnsi256(index: number): ChalkInstance;
+}
+export type ChalkInstance = Base & {
+    readonly [K in ModifierName | ColorName | UnderlineColorName | 'visible']: ChalkInstance;
+};
+/** `new Chalk({ level })` — an instance with its own level, detected when the option is omitted. */
+export interface Chalk extends ChalkInstance {
+}
+export declare class Chalk {
+    constructor(options?: ChalkOptions);
+}
+export declare const supportsColor: ColorInfo;
+export declare const supportsColorStderr: ColorInfo;
+export declare const chalkStderr: ChalkInstance;
+declare const chalk: ChalkInstance;
+export default chalk;

package/dist/chalk.js

@@ -0,0 +1,143 @@
+import { colorLevel } from './policy.js';
+import { sgr } from './tokens.js';
+const MODIFIERS = {
+    reset: [0, 0],
+    bold: [1, 22],
+    dim: [2, 22],
+    italic: [3, 23],
+    underline: [4, 24],
+    underlineDouble: ['4:2', 24],
+    underlineCurly: ['4:3', 24],
+    underlineDotted: ['4:4', 24],
+    underlineDashed: ['4:5', 24],
+    overline: [53, 55],
+    inverse: [7, 27],
+    hidden: [8, 28],
+    strikethrough: [9, 29],
+};
+const NAMES = ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'];
+const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+const pair = (open, close) => ({ open: String(open), close: String(close) });
+function family(prefix, open, close) {
+    const t = {};
+    const key = (name) => (prefix === '' ? name : prefix + cap(name));
+    for (const bright of [false, true]) {
+        NAMES.forEach((name, i) => {
+            t[key(name) + (bright ? 'Bright' : '')] = pair(open(i, bright), close);
+            if (bright && i === 0)
+                for (const alias of ['gray', 'grey'])
+                    t[key(alias)] = pair(open(0, true), close);
+        });
+    }
+    return t;
+}
+const FOREGROUND = family('', (i, bright) => (bright ? 90 : 30) + i, 39);
+const BACKGROUND = family('bg', (i, bright) => (bright ? 100 : 40) + i, 49);
+const UNDERLINE = family('underline', (i, bright) => `58;5;${bright ? i + 8 : i}`, 59);
+const STYLES = {
+    ...Object.fromEntries(Object.entries(MODIFIERS).map(([k, [open, close]]) => [k, pair(open, close)])),
+    ...FOREGROUND,
+    ...BACKGROUND,
+    ...UNDERLINE,
+};
+export const modifierNames = Object.keys(MODIFIERS);
+export const foregroundColorNames = Object.keys(FOREGROUND);
+export const backgroundColorNames = Object.keys(BACKGROUND);
+export const underlineColorNames = Object.keys(UNDERLINE);
+export const colorNames = [...foregroundColorNames, ...backgroundColorNames];
+const step = (v) => Math.round((v / 255) * 5);
+const ramp = (v) => (v < 8 ? 16 : v > 248 ? 231 : Math.round(((v - 8) / 247) * 24) + 232);
+const rgbToAnsi256 = (r, g, b) => r === g && g === b ? ramp(r) : 16 + 36 * step(r) + 6 * step(g) + step(b);
+function ansi256ToAnsi(code) {
+    if (code < 16)
+        return (code < 8 ? 30 : 82) + code;
+    const c = code - 16;
+    const grey = ((code - 232) * 10 + 8) / 255;
+    const [r, g, b] = code >= 232 ? [grey, grey, grey] : [Math.floor(c / 36) / 5, Math.floor((c % 36) / 6) / 5, (c % 6) / 5];
+    const value = Math.max(r, g, b) * 2;
+    return value === 0 ? 30 : (value === 2 ? 90 : 30) + ((Math.round(b) << 2) | (Math.round(g) << 1) | Math.round(r));
+}
+function hexToRgb(hex) {
+    const m = /[\da-f]{6}|[\da-f]{3}/i.exec(hex)?.[0] ?? '0';
+    const n = Number.parseInt(m.length === 3 ? [...m].map((c) => c + c).join('') : m, 16);
+    return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+}
+const FAMILIES = {
+    '': { ext: 38, ansi: String, close: '39' },
+    bg: { ext: 48, ansi: (code) => String(code + 10), close: '49' },
+    underline: { ext: 58, ansi: (code) => `58;5;${code < 90 ? code - 30 : code - 82}`, close: '59' },
+};
+const MODELS = {};
+for (const [prefix, fam] of Object.entries(FAMILIES)) {
+    for (const model of ['rgb', 'hex', 'ansi256'])
+        MODELS[prefix === '' ? model : prefix + cap(model)] = [fam, model];
+}
+function open(fam, level, model, args) {
+    const rgb = model === 'ansi256' ? undefined : model === 'hex' ? hexToRgb(String(args[0])) : args.map(Number);
+    const code = rgb === undefined ? Number(args[0]) : rgbToAnsi256(...rgb);
+    return level === 3 && rgb !== undefined ? `${fam.ext};2;${rgb.join(';')}`
+        : level >= 2 ? `${fam.ext};5;${code}`
+            : fam.ansi(ansi256ToAnsi(code));
+}
+function checkLevel(level) {
+    if (!Number.isSafeInteger(level) || level < 0 || level > 3)
+        throw new Error('The `level` should be an integer from 0 to 3');
+}
+function link(root, chain, visible, key) {
+    const style = STYLES[key];
+    if (style !== undefined)
+        return builder(root, [...chain, style], visible);
+    if (key === 'visible')
+        return builder(root, chain, true);
+    const model = MODELS[key];
+    if (model === undefined)
+        return undefined;
+    const [fam, name] = model;
+    return (...args) => builder(root, [...chain, { open: open(fam, root.level, name, args), close: fam.close }], visible);
+}
+function builder(root, chain, visible) {
+    const links = new Map();
+    const fn = (...text) => {
+        const s = text.length === 1 ? String(text[0]) : text.join(' ');
+        return root.level === 0 || s === '' ? (visible ? '' : s) : chain.length === 0 ? s : sgr(chain, s);
+    };
+    return new Proxy(fn, {
+        get(target, key) {
+            if (key === 'level')
+                return root.level;
+            if (typeof key !== 'string')
+                return Reflect.get(target, key);
+            if (!links.has(key))
+                links.set(key, link(root, chain, visible, key));
+            return links.get(key) ?? Reflect.get(target, key);
+        },
+        set(target, key, value) {
+            if (key !== 'level')
+                return Reflect.set(target, key, value);
+            checkLevel(value);
+            root.level = value;
+            return true;
+        },
+    });
+}
+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 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);
+}
+export class Chalk {
+    constructor(options) {
+        return create(options);
+    }
+}
+export const supportsColor = info(stdoutLevel);
+export const supportsColorStderr = info(stderrLevel);
+export const chalkStderr = create({}, stderrLevel);
+const chalk = create();
+export default chalk;

package/dist/contrast.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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).
+ *
+ * `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
+ * user's terminal theme, and a number there would be invented.
+ */
+/** The floors WCAG 2.2 sets, as ratios. */
+export declare const AA: {
+    /** Body text against its background. */
+    readonly TEXT: 4.5;
+    /** Large text, UI components, and meaningful parts of a graphic. */
+    readonly GRAPHIC: 3;
+};
+/** `#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;

package/dist/contrast.js

@@ -0,0 +1,35 @@
+export const AA = {
+    TEXT: 4.5,
+    GRAPHIC: 3,
+};
+const SRGB_MAX = 255;
+const LINEAR_THRESHOLD = 0.03928;
+const LINEAR_DIVISOR = 12.92;
+const GAMMA_OFFSET = 0.055;
+const GAMMA_SCALE = 1.055;
+const GAMMA_EXPONENT = 2.4;
+const LUMA = { r: 0.2126, g: 0.7152, b: 0.0722 };
+const CONTRAST_OFFSET = 0.05;
+const RED_AT = 1;
+const GREEN_AT = 3;
+const BLUE_AT = 5;
+const HEX_PAIRS = [RED_AT, GREEN_AT, BLUE_AT];
+const HEX_RADIX = 16;
+const SHORT_HEX_LENGTH = 4;
+export function channels(hex) {
+    const full = hex.length === SHORT_HEX_LENGTH
+        ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`
+        : hex;
+    if (!/^#[0-9a-fA-F]{6}$/.test(full))
+        throw new Error(`roundel: "${hex}" is not a hex colour`);
+    const parsed = HEX_PAIRS.map((i) => Number.parseInt(full.slice(i, i + 2), HEX_RADIX) / SRGB_MAX);
+    return parsed;
+}
+export function luminance(hex) {
+    const [r, g, b] = channels(hex).map((v) => v <= LINEAR_THRESHOLD ? v / LINEAR_DIVISOR : ((v + GAMMA_OFFSET) / GAMMA_SCALE) ** GAMMA_EXPONENT);
+    return LUMA.r * r + LUMA.g * g + LUMA.b * b;
+}
+export function contrast(a, b) {
+    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (hi + CONTRAST_OFFSET) / (lo + CONTRAST_OFFSET);
+}

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 /**
- * roundel — reserved. The first working release follows
- * docs/intents/cli-style/ in the burgee repository. Until then this entry
- * exports only its own name, so that importing it costs nothing and promises nothing.
+ * roundel — the colours a CLI carries. Re-exports only; each subpath is its own entry
+ * and costs only itself (R7), so prefer `roundel/tokens` when that is all you need.
  */
-export declare const name: "roundel";
+export * from './contrast.js';
+export * from './plugin.js';
+export * from './policy.js';
+export * from './theme.js';
+export * from './tokens.js';

package/dist/index.js

@@ -1,7 +1,5 @@
-/**
- * roundel — reserved. The first working release follows
- * docs/intents/cli-style/ in the burgee repository. Until then this entry
- * exports only its own name, so that importing it costs nothing and promises nothing.
- */
-export const name = 'roundel';
-//# sourceMappingURL=index.js.map
+export * from './contrast.js';
+export * from './plugin.js';
+export * from './policy.js';
+export * from './theme.js';
+export * from './tokens.js';

package/dist/plugin.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The plugin host for roundel's half of the contract (`plugin-contract` R1, R4, R6, R8).
+ *
+ * A plugin is one plain object shared by the whole family. This file keeps the key roundel
+ * understands — `tokens`, a theme — and **ignores every other key without complaining**,
+ * which is what makes the same object work on any subset of the family that is installed.
+ * A plugin written for flagstaff registers here and contributes its theme; its `spinners`
+ * and `components` are not roundel's business and are not an error.
+ *
+ * **Nothing here imports flagstaff, and the shape is declared rather than imported.** Types
+ * erase, so an import would cost nothing at run time — and it would still put flagstaff in
+ * roundel's dependency story, which is the one thing the family promises it does not do.
+ * Four keys declared structurally is three lines, and keeps "none requires the others"
+ * literally true instead of true-modulo-types.
+ *
+ * **A plugin cannot smuggle an unreadable colour in.** This file collects tokens; `fly()`
+ * contrast-checks them against the ground exactly as it checks a hand-written theme, and
+ * throws below 4.5:1. That is deliberately not re-implemented here: one contrast gate, in
+ * the place that already had it (roundel R5).
+ */
+import { type Hex, type Theme } from './theme.js';
+/**
+ * The plugin contract version. One number for the family — the same `1` flagstaff declares,
+ * written out rather than imported for the reason in the file comment above.
+ */
+export declare const CONTRACT = 1;
+/**
+ * The keys roundel reads. Declared structurally: any object with these fields is a plugin
+ * here, whatever else it carries.
+ */
+export interface Plugin {
+    name: string;
+    contract?: number;
+    tokens?: Record<string, string>;
+}
+export type PluginErrorCode = 'E_PLUGIN_SCHEMA' | 'E_PLUGIN_CONTRACT';
+/** A refused plugin says what is wrong and what to do about it — the family's one vocabulary. */
+export declare class PluginError extends Error {
+    readonly code: PluginErrorCode;
+    readonly fix: string;
+    constructor(code: PluginErrorCode, message: string, fix: string);
+}
+/**
+ * Refuse a plugin that cannot contribute a theme, at the door.
+ *
+ * A misspelt token name is refused rather than ignored: a plugin whose `errror` key is
+ * silently dropped looks like it worked, and the author debugs the wrong thing.
+ */
+export declare function validate(plugin: unknown): asserts plugin is Plugin;
+/** Which plugin last contributed each token — the shadowing a `plugin check` prints. */
+export interface Contribution {
+    token: string;
+    value: Hex;
+    from: string;
+    /** Plugins that contributed this token earlier and were overridden, in order. */
+    shadowed: string[];
+}
+/**
+ * Register a plugin. Later wins, like ESLint flat config: the array is ordered, a caller
+ * reads it top to bottom, and the last word on a token is the one nearest the program.
+ */
+export declare function register(plugin: unknown): void;
+/** Forget every registered plugin. For tests, and for a program that re-themes at runtime. */
+export declare function reset(): void;
+/**
+ * The theme every registered plugin adds up to, ready for `fly()`.
+ *
+ * It is *not* flown here. A plugin contributing colour must not decide when colour is
+ * decided — `fly()` is called once by the program, and calling it from a `register()` would
+ * mean the last plugin imported quietly re-flew the theme.
+ */
+export declare function theme(): Theme;
+/** Every token a plugin contributed, with who won it and who it shadowed. */
+export declare function contributions(): Contribution[];
+/** The plugins registered, in registration order. */
+export declare function registered(): readonly Plugin[];

package/dist/plugin.js

@@ -0,0 +1,71 @@
+export const CONTRACT = 1;
+export class PluginError extends Error {
+    code;
+    fix;
+    constructor(code, message, fix) {
+        super(message);
+        this.code = code;
+        this.fix = fix;
+        this.name = 'PluginError';
+    }
+}
+const TOKEN_NAMES = new Set(['error', 'warn', 'ok', 'hint', 'muted', 'command', 'flag', 'value', 'heading', 'ground']);
+const HEX = /^#[0-9a-f]{6}$/i;
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+export function validate(plugin) {
+    if (!isRecord(plugin))
+        throw new PluginError('E_PLUGIN_SCHEMA', 'a plugin is a plain object', 'export an object, not a function or an array');
+    if (typeof plugin['name'] !== 'string' || plugin['name'] === '') {
+        throw new PluginError('E_PLUGIN_SCHEMA', 'a plugin needs a name', 'add `name: "…"` — it is how a shadowed token is reported');
+    }
+    const contract = plugin['contract'];
+    if (contract !== undefined && (!Number.isInteger(contract) || contract > CONTRACT)) {
+        throw new PluginError('E_PLUGIN_CONTRACT', `plugin "${plugin['name']}" declares contract ${String(contract)}; this roundel knows ${CONTRACT}`, 'upgrade roundel, or lower the plugin’s contract');
+    }
+    validateTokens(plugin['tokens'], plugin['name']);
+}
+function validateTokens(tokens, name) {
+    if (tokens === undefined)
+        return;
+    if (!isRecord(tokens))
+        throw new PluginError('E_PLUGIN_SCHEMA', `plugin "${name}": tokens must be an object`, 'map a token name to a #rrggbb colour');
+    for (const [token, value] of Object.entries(tokens)) {
+        if (!TOKEN_NAMES.has(token)) {
+            throw new PluginError('E_PLUGIN_SCHEMA', `plugin "${name}": "${token}" is not a token`, `use one of ${[...TOKEN_NAMES].join(', ')}`);
+        }
+        if (typeof value !== 'string' || !HEX.test(value)) {
+            throw new PluginError('E_PLUGIN_SCHEMA', `plugin "${name}": token "${token}" is ${JSON.stringify(value)}`, 'a token is a #rrggbb colour, contrast-checked when the theme is flown');
+        }
+    }
+}
+const order = [];
+export function register(plugin) {
+    validate(plugin);
+    order.push(plugin);
+}
+export function reset() {
+    order.length = 0;
+}
+export function theme() {
+    const out = new Map();
+    for (const plugin of order) {
+        for (const [token, value] of Object.entries(plugin.tokens ?? {})) {
+            if (TOKEN_NAMES.has(token))
+                out.set(token, value);
+        }
+    }
+    return Object.fromEntries(out);
+}
+export function contributions() {
+    const by = new Map();
+    for (const plugin of order) {
+        for (const [token, value] of Object.entries(plugin.tokens ?? {})) {
+            const existing = by.get(token);
+            by.set(token, { token, value: value, from: plugin.name, shadowed: existing === undefined ? [] : [...existing.shadowed, existing.from] });
+        }
+    }
+    return [...by.values()];
+}
+export function registered() {
+    return order;
+}

package/dist/policy.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The output policy — one answer to "where is this output going?", read from a
+ * `Runtime`, never from `process` (R1, R2, R9 of `roundel`; U2 of the stack).
+ *
+ * Five colour libraries disagreeing about the terminal (clack #286) is what this file
+ * exists to end: every package in the family asks here, and nothing else in it reads
+ * `isTTY`, `NO_COLOR`, `FORCE_COLOR`, `CI`, `CLI_ACCESSIBLE` or a `--color` flag. It also
+ * holds the one record `fly()` writes and every token reads, because it is the only module
+ * every subpath may import (R7).
+ *
+ * The code here is written tight — ternaries where a reader might expect statements —
+ * because `./chalk` reaches this file and R8 caps that whole graph at chalk 6's own
+ * 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[];
+}
+export type OutputMode = 'tty' | 'pipe' | 'json' | 'accessible' | 'ci';
+declare const MAX_LEVEL = 3;
+/** chalk's levels: none, 16 colours, 256 colours, truecolor. */
+export type ColorLevel = 0 | 1 | 2 | typeof MAX_LEVEL;
+export interface ModeOptions {
+    /** Whether this run was asked for `--json`: the engine's knowledge, not the process's. */
+    json?: boolean;
+}
+/**
+ * First match wins: `json` if asked; `accessible` if `CLI_ACCESSIBLE`; `ci` if `CI` and not
+ * a TTY; `pipe` if not a TTY; else `tty`.
+ */
+export declare const outputMode: (rt: Runtime, opts?: ModeOptions) => OutputMode;
+/**
+ * chalk's level, obeying the user's explicit instruction in any mode (R2 revised
+ * 2026-09-08): `NO_COLOR` wins outright; then `FORCE_COLOR=0`, which supports-color settles
+ * *before* it looks at any flag, so `FORCE_COLOR=0 --color=256` is off and not 2 — an
+ * explicit "colour off" is never undone by a level flag; then the `--color` flags in
+ * `argv`, an exact `--color=256` beating a numeric `FORCE_COLOR` as chalk's own suite says;
+ * then `FORCE_COLOR`. `--json` is the one output the level never enters: structured text
+ * carries no escapes. The mode decides redraws (U2), never the level.
+ *
+ * Accessible mode defaults to 0, on the same footing as a pipe rather than a terminal:
+ * `CLI_ACCESSIBLE` is itself an explicit instruction from a human, and ANSI colour is noise
+ * to a screen reader. As with a pipe, an explicit colour ask (`FORCE_COLOR`, `--color=…`)
+ * still wins and `NO_COLOR` still beats everything.
+ *
+ * With no instruction the order is supports-color's own, and deliberately so — chalk's
+ * `level.js` asserts it, and a family that disagreed with chalk about a bare pipe would be
+ * the clack #286 bug again. A pipe is 0, because a pipe nobody asked to colour is a file or
+ * another program's stdin; the one exception is Azure Pipelines (`TF_BUILD` *and*
+ * `AGENT_NAME` — `TF_BUILD` alone is a build without an agent), which supports-color reads
+ * before it gives up on a pipe. Once colour *is* being detected — a terminal, or a run that
+ * asked — `TERM=dumb` is the floor, a `CI` run is its vendor's level (gated on `'CI' in env`
+ * as supports-color gates it, so an empty `CI=` still selects the table), and anything else
+ * is what `TERM`/`COLORTERM` report. So the CI user who exports `FORCE_COLOR=true` to get
+ * coloured logs gets their runner's colours, and nobody else's pipe changes.
+ *
+ * ponytail: supports-color also consults the platform, TEAMCITY_VERSION, TERM_PROGRAM and
+ * the emulator allow-list; R2 refuses that detection, so those stay unread.
+ */
+export declare function colorLevel(rt: Runtime, opts?: ModeOptions): ColorLevel;
+export type TokenName = 'error' | 'warn' | 'ok' | 'hint' | 'muted' | 'command' | 'flag' | 'value' | 'heading';
+/** One `util.styleText` format name: `'bold'`, `'red'`, `'redBright'`, `'dim'`… */
+export type Format = import('node:util').InspectColor;
+/**
+ * A style as a token paints it: `styleText` format names, or the SGR parameters of one
+ * foreground colour (`38;5;n` for 256 colours, `38;2;r;g;b` for truecolor), which
+ * `styleText` cannot express.
+ */
+export type Paint = readonly Format[] | {
+    readonly sgr: readonly number[];
+};
+/**
+ * What `fly()` decided, once, for the process: the colour level and each token's paint.
+ * Every token reads it; nothing writes it but `fly()`. Until then the level is 0 and every
+ * token is the identity, so a program that never declares its runtime prints plain text.
+ */
+export declare const flown: {
+    level: ColorLevel;
+    paint: Partial<Record<TokenName, Paint>>;
+};
+export {};

package/dist/policy.js

@@ -0,0 +1,28 @@
+const MAX_LEVEL = 3;
+const set = (value) => value !== undefined && value !== '';
+export const outputMode = (rt, opts = {}) => opts.json === true ? 'json' : set(rt.env['CLI_ACCESSIBLE']) ? 'accessible' : rt.isTTY.stdout ? 'tty' : set(rt.env['CI']) ? 'ci' : 'pipe';
+const forced = (v) => v === 'false' ? 0 : v === '' || v === 'true' ? 'on' : v !== undefined && /^\d+$/.test(v) ? Math.min(Number(v), MAX_LEVEL) : undefined;
+function flagged(argv) {
+    const end = argv.indexOf('--');
+    const seen = end < 0 ? argv : argv.slice(0, end);
+    const has = (re) => seen.some((a) => re.test(a));
+    return has(/^--(no-colors?|color=(false|never))$/) ? 0
+        : has(/^--color=(16m|full|truecolor)$/) ? MAX_LEVEL
+            : has(/^--color=256$/) ? 2
+                : has(/^--(colors|color(=(true|always))?)$/) ? 'on'
+                    : undefined;
+}
+const CI_3 = ['GITHUB_ACTIONS', 'GITEA_ACTIONS', 'CIRCLECI'];
+const CI_1 = ['TRAVIS', 'APPVEYOR', 'GITLAB_CI', 'BUILDKITE', 'DRONE'];
+const ci = (env) => CI_3.some((k) => k in env) ? MAX_LEVEL : CI_1.some((k) => k in env) || env['CI_NAME'] === 'codeship' ? 1 : 0;
+const TERM_256 = /-256(color)?$/i;
+const TERM_16 = /^screen|^xterm|^vt100|^vt220|^rxvt|color|ansi|cygwin|linux/i;
+const terminal = ({ TERM = '', COLORTERM }) => COLORTERM === 'truecolor' ? MAX_LEVEL : TERM_256.test(TERM) ? 2 : TERM_16.test(TERM) || COLORTERM !== undefined ? 1 : 0;
+export function colorLevel(rt, opts) {
+    const { env } = rt;
+    const force = forced(env['FORCE_COLOR']);
+    const ask = force === 0 ? 0 : (flagged(rt.argv ?? []) ?? force);
+    const min = ask === undefined ? 0 : 1;
+    return opts?.json === true || set(env['NO_COLOR']) || (min === 0 && set(env['CLI_ACCESSIBLE'])) ? 0 : typeof ask === 'number' ? ask : 'TF_BUILD' in env && 'AGENT_NAME' in env ? 1 : min === 0 && !rt.isTTY.stdout ? 0 : env['TERM'] === 'dumb' ? min : Math.max(min, 'CI' in env ? ci(env) : terminal(env));
+}
+export const flown = { level: 0, paint: {} };

package/dist/schema.json

@@ -0,0 +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"}}}}}

package/dist/theme.d.ts

@@ -0,0 +1,13 @@
+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). */
+export type Theme = Partial<Record<TokenName, Style>> & {
+    ground?: Hex;
+};
+/**
+ * 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
+ * `{ json }` when the run was asked for `--json`; a later call replaces the theme.
+ */
+export declare function fly(theme: Theme, rt: Runtime, opts?: ModeOptions): void;

package/dist/theme.js

@@ -0,0 +1,84 @@
+import { AA, channels, contrast } from './contrast.js';
+import { colorLevel, flown, } from './policy.js';
+const ROCK = ['#a84c17', '#f4794a'];
+const JUNIPER = ['#0a6b47', '#0d9460'];
+const INK = '#0a0a0a';
+function brand(pair, ground) {
+    const [deep, lifted] = pair;
+    return contrast(lifted, ground) > contrast(deep, ground) ? lifted : deep;
+}
+const DEFAULTS = {
+    error: (ground) => brand(ROCK, ground),
+    warn: () => ['yellow'],
+    ok: (ground) => brand(JUNIPER, ground),
+    hint: () => ['dim'],
+    muted: () => ['gray'],
+    command: () => ['bold'],
+    flag: () => ['cyan'],
+    value: () => ['magenta'],
+    heading: () => ['bold', 'underline'],
+};
+const TOKENS = Object.keys(DEFAULTS);
+const SRGB_MAX = 255;
+const CUBE_STEPS = 5;
+const CUBE_START = 16;
+const CUBE_ROW = 36;
+const CUBE_COL = 6;
+const GREY_START = 232;
+const GREY_STEPS = 24;
+const GREY_LOW = 8;
+const GREY_HIGH = 248;
+const GREY_SPAN = 247;
+const CUBE_WHITE = 231;
+const BASIC_NAMES = ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'];
+const BLUE_BIT = 2;
+const GREEN_BIT = 1;
+const SGR_FG = 38;
+const SGR_256 = 5;
+const SGR_RGB = 2;
+const TRUECOLOR = 3;
+const COLORS_256 = 2;
+function ansi256(r, g, b) {
+    if (r === g && g === b) {
+        if (r < GREY_LOW)
+            return CUBE_START;
+        if (r > GREY_HIGH)
+            return CUBE_WHITE;
+        return Math.round(((r - GREY_LOW) / GREY_SPAN) * GREY_STEPS) + GREY_START;
+    }
+    const step = (v) => Math.round((v / SRGB_MAX) * CUBE_STEPS);
+    return CUBE_START + CUBE_ROW * step(r) + CUBE_COL * step(g) + step(b);
+}
+function ansi16(r, g, b) {
+    const on = (v) => Math.round(v / SRGB_MAX);
+    const index = (on(b) << BLUE_BIT) | (on(g) << GREEN_BIT) | on(r);
+    const name = BASIC_NAMES[index] ?? 'white';
+    if (index === 0)
+        return name;
+    if (Math.round((Math.max(r, g, b) / SRGB_MAX) * CUBE_STEPS) !== CUBE_STEPS)
+        return name;
+    return name === 'black' ? 'gray' : `${name}Bright`;
+}
+function resolve(style, level) {
+    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)];
+}
+export function fly(theme, rt, opts) {
+    const level = colorLevel(rt, opts);
+    const ground = theme.ground ?? INK;
+    const styles = TOKENS.map((name) => [name, theme[name] ?? DEFAULTS[name](ground)]);
+    const failures = styles.flatMap(([name, style]) => {
+        if (typeof style !== 'string')
+            return [];
+        const ratio = contrast(style, ground);
+        return ratio < AA.TEXT ? [`${name} ${style} on ${ground} is ${ratio.toFixed(2)}:1`] : [];
+    });
+    if (failures.length > 0)
+        throw new Error(`roundel: below ${AA.TEXT}:1 — ${failures.join('; ')}`);
+    flown.level = level;
+    flown.paint = Object.fromEntries(styles.map(([name, style]) => [name, resolve(style, level)]));
+}

package/dist/tokens.d.ts

@@ -0,0 +1,22 @@
+export type Token = (s: string) => string;
+/** One SGR pair as the chalk façade composes them: the parameters that open and close it, no escape. */
+export interface SgrPair {
+    readonly open: string;
+    readonly close: string;
+}
+/**
+ * Wrap `s` in a chain of SGR pairs, outermost first, as chalk does: a close already inside
+ * `s` is followed by a re-open so a nested style survives it, and every line break closes
+ * before it and re-opens after (chalk/chalk#92). The façade computes parameters; the
+ * escape itself is emitted here and nowhere else (R3, R6).
+ */
+export declare function sgr(chain: readonly SgrPair[], s: string): string;
+export declare const error: Token;
+export declare const warn: Token;
+export declare const ok: Token;
+export declare const hint: Token;
+export declare const muted: Token;
+export declare const command: Token;
+export declare const flag: Token;
+export declare const value: Token;
+export declare const heading: Token;

package/dist/tokens.js

@@ -0,0 +1,35 @@
+import { styleText } from 'node:util';
+import { flown } from './policy.js';
+const CSI = '\u001B[';
+const FG_RESET = `${CSI}39m`;
+function paint(p, s) {
+    if ('sgr' in p)
+        return `${CSI}${p.sgr.join(';')}m${s}${FG_RESET}`;
+    return styleText([...p], s, { validateStream: false });
+}
+const LINE_BREAK = /\r?\n/g;
+export function sgr(chain, s) {
+    const code = (p) => `${CSI}${p}m`;
+    const openAll = chain.map((p) => code(p.open)).join('');
+    const closeAll = chain.map((p) => code(p.close)).reverse().join('');
+    let out = s;
+    if (out.includes(CSI))
+        for (const p of chain.toReversed())
+            out = out.replaceAll(code(p.close), code(p.close) + code(p.open));
+    return openAll + out.replace(LINE_BREAK, (lf) => closeAll + lf + openAll) + closeAll;
+}
+function token(name) {
+    return (s) => {
+        const p = flown.level === 0 ? undefined : flown.paint[name];
+        return p === undefined ? s : paint(p, s);
+    };
+}
+export const error = token('error');
+export const warn = token('warn');
+export const ok = token('ok');
+export const hint = token('hint');
+export const muted = token('muted');
+export const command = token('command');
+export const flag = token('flag');
+export const value = token('value');
+export const heading = token('heading');

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "roundel",
-  "version": "0.0.1",
+  "version": "0.2.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",
+  "sideEffects": false,
   "engines": {
     "node": ">=24"
   },
@@ -12,6 +13,37 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./policy": {
+      "types": "./dist/policy.d.ts",
+      "import": "./dist/policy.js",
+      "default": "./dist/policy.js"
+    },
+    "./tokens": {
+      "types": "./dist/tokens.d.ts",
+      "import": "./dist/tokens.js",
+      "default": "./dist/tokens.js"
+    },
+    "./schema.json": "./dist/schema.json",
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js",
+      "default": "./dist/plugin.js"
+    },
+    "./theme": {
+      "types": "./dist/theme.d.ts",
+      "import": "./dist/theme.js",
+      "default": "./dist/theme.js"
+    },
+    "./contrast": {
+      "types": "./dist/contrast.d.ts",
+      "import": "./dist/contrast.js",
+      "default": "./dist/contrast.js"
+    },
+    "./chalk": {
+      "types": "./dist/chalk.d.ts",
+      "import": "./dist/chalk.js",
+      "default": "./dist/chalk.js"
     }
   },
   "files": [
@@ -20,9 +52,10 @@
     "!dist/**/*.test.*"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "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": {
@@ -47,6 +80,6 @@
     "styleText"
   ],
   "devDependencies": {
-    "vitest": "^4.0.0"
+    "vitest": "^5.0.0"
   }
 }