@promptctl/rich-js 0.26.0 → 0.27.0

package/dist/themes/buildPalette.d.ts

@@ -1,5 +1,5 @@
 import { ColorRgba } from "../core/color.js";
-import { Palette } from "./palette.js";
+import { Palette, type PaletteRole, type PaletteRoles } from "./palette.js";
 /**
  * Base colors required to build a full semantic palette.
  * All are ColorRgba — callers construct from whatever source (hex, HSL, etc.).
@@ -14,44 +14,19 @@ export interface BaseColors {
     background: ColorRgba;
     foreground: ColorRgba;
 }
-type AccentKey = "primary" | "secondary" | "accent" | "success" | "warning" | "error";
-export declare const ACCENT_KEYS: readonly AccentKey[];
+/** The eight roles every palette is given, and every role it may also state. */
+export type StatedRoles = BaseColors & Partial<PaletteRoles>;
+/** Every role of every palette, read off the rules. */
+export declare const PALETTE_ROLES: readonly PaletteRole[];
 /**
- * Build a full semantic palette from base colors.
+ * Build a full semantic palette from its base colors and any other role it
+ * states: a stated role keeps its colour, and everything derived from it
+ * follows it, but for `text-*`, which is held to read on its `*-muted`. An
+ * authored theme is this with most roles stated; see `RULES` for what a role
+ * not stated becomes.
  *
- * Derived entries follow Textual's formulas:
- * - `*-muted` = color blended 70% toward its opposite base role. Defined for
- *              every accent AND for the two base roles themselves
- *              (`foreground-muted` blends toward `background`,
- *              `background-muted` blends toward `foreground`) — a caller
- *              de-emphasizing body/structural text reaches for
- *              `foreground-muted` the same way it reaches for
- *              `primary-muted` to de-emphasize an accent.
- * - `text-*`  = contrast text tinted 66% with the accent color, then held
- *              to WCAG AA (4.5:1) on `*-muted` — the foreground for a
- *              `*-muted` ground
- * - `on-*`    = WCAG-correct contrast colour (black or white) for use as
- *              foreground when the FULL accent is the background. Picked
- *              by relative luminance — single source of truth so widgets
- *              never need to invert / reverse fg/bg to get readable text.
- * - `surface` = background blended 5% toward foreground
- *
- * A translucent base colour is drawn onto `background` before anything is
- * derived from it, so `on-*` is chosen against the colour the accent is drawn
- * as and every derived entry is opaque.
- */
-export declare function buildPalette(name: string, dark: boolean, given: BaseColors): Palette;
-/**
- * A palette's `text-*`: its tint held to WCAG AA on `*-muted`, moved toward
- * the palette's own text side so it also reads on `background`, where widgets
- * draw it too. The muted floor is the promise: where no lightness on the text
- * side clears it, the colour that does is on the other side, and the
- * background pair is the one given up. Every bundled palette clears both
- * (test/themes/text-on-muted.test.ts).
- *
- * [LAW:single-enforcer] The one rule for the pair, for the palettes derived
- * here and the authored ones the registry hydrates: the tint is the theme's,
- * whether it reads is decided here.
+ * A translucent colour is drawn onto `background` before anything is derived
+ * from it, so `on-*` is chosen against the colour the accent is drawn as.
+ * `boost` alone stays a layer: it is what `panel` composites.
  */
-export declare function accentText(tint: ColorRgba, muted: ColorRgba, background: ColorRgba): ColorRgba;
-export {};
+export declare function buildPalette(name: string, dark: boolean, given: StatedRoles): Palette;

package/dist/themes/buildPalette.js

@@ -1,87 +1,217 @@
-import { blendRgb } from "../core/color.js";
-import { alphaBlend, contrastFor, ensureContrastToward } from "./colorMath.js";
+import { ColorRgba, blendRgb } from "../core/color.js";
+import { alphaBlend, contrastFor, ensureContrastToward, shiftLightness } from "./colorMath.js";
 import { Palette, drawnOn } from "./palette.js";
 const MUTED_BLEND = 0.7;
 const TEXT_ALPHA = 0.66;
 const SURFACE_LIFT = 0.05;
+const LADDER_STEP = 0.075;
+const SURFACE_ACTIVE_LIFT = 0.06;
+const BORDER_BLUR_DROP = 0.025;
+const PANEL_TINT = 0.1;
+const BACKGROUND_TINT = 0.15;
+const BACKGROUND_TINT_LIFT = 0.15;
+const BOOST_ALPHA = 0.04;
+const TEXT_FULL_ALPHA = 0.87;
+const TEXT_MUTED_ALPHA = 0.6;
+const DISABLED_ALPHA = 0.38;
+const BLURRED_CURSOR_ALPHA = 0.3;
+const HOVER_ALPHA = 0.1;
+const SELECTION_ALPHA = 0.4;
+const SCROLLBAR_ALPHA = 0.4;
+const SCROLLBAR_HOVER_ALPHA = 0.5;
 // WCAG AA for body text: `text-*` is the label drawn on `*-muted`.
 const TEXT_ON_MUTED = 4.5;
-export const ACCENT_KEYS = ["primary", "secondary", "accent", "success", "warning", "error"];
+const ACCENT_KEYS = ["primary", "secondary", "accent", "success", "warning", "error"];
+const TRANSPARENT = new ColorRgba(0, 0, 0, 0);
+const WHITE = new ColorRgba(255, 255, 255);
+const withAlpha = (colour, alpha) => new ColorRgba(colour.red, colour.green, colour.blue, alpha);
+const textOn = (alpha) => (at) => withAlpha(contrastFor(at("background")), alpha);
+// [LAW:one-type-per-behavior] The roles naming another role's colour outright.
+const same = (role) => (at) => at(role);
+const none = () => TRANSPARENT;
+/** The six rungs around `root`, each `-darken-3`…`-lighten-3` one `LADDER_STEP` apart. */
+function ladder(root, rung) {
+    const rungs = ["darken", "lighten"].flatMap((direction) => [1, 2, 3].map((n) => {
+        return [`${root}-${direction}-${n}`, rung((direction === "darken" ? -n : n) * LADDER_STEP)];
+    }));
+    return Object.fromEntries(rungs);
+}
+const lightness = (root) => ladder(root, (step) => (at) => shiftLightness(at(root), step));
+/**
+ * `primary-background` at `step` from its root: on a dark palette a tint of the
+ * background lifted toward white and floored at the tint, so the bottom rungs
+ * meet rather than fall below it; on a light one the accent's own ladder. Every
+ * rung reads the accent, as Textual's do, so a stated root does not move them.
+ */
+const accentBackground = (accent, step) => (at, dark) => dark
+    ? blendRgb(blendRgb(at("background"), at(accent), BACKGROUND_TINT), WHITE, Math.max(0, BACKGROUND_TINT_LIFT + step))
+    : shiftLightness(at(accent), step);
+function accentRules(accent) {
+    return {
+        ...lightness(accent),
+        [`${accent}-muted`]: ((at) => blendRgb(at(accent), at("background"), MUTED_BLEND)),
+        [`on-${accent}`]: ((at) => contrastFor(at(accent))),
+        [`text-${accent}`]: ((at) => alphaBlend(at(accent), contrastFor(at("background")), TEXT_ALPHA)),
+    };
+}
 /**
- * Build a full semantic palette from base colors.
+ * How each role not given to `buildPalette` is derived, following Textual's
+ * `ColorSystem`, which generated the bundled themes:
  *
- * Derived entries follow Textual's formulas:
- * - `*-muted` = color blended 70% toward its opposite base role. Defined for
- *              every accent AND for the two base roles themselves
- *              (`foreground-muted` blends toward `background`,
- *              `background-muted` blends toward `foreground`) — a caller
- *              de-emphasizing body/structural text reaches for
- *              `foreground-muted` the same way it reaches for
- *              `primary-muted` to de-emphasize an accent.
- * - `text-*`  = contrast text tinted 66% with the accent color, then held
- *              to WCAG AA (4.5:1) on `*-muted` — the foreground for a
- *              `*-muted` ground
- * - `on-*`    = WCAG-correct contrast colour (black or white) for use as
- *              foreground when the FULL accent is the background. Picked
- *              by relative luminance — single source of truth so widgets
- *              never need to invert / reverse fg/bg to get readable text.
- * - `surface` = background blended 5% toward foreground
+ * - `*-muted`  = the colour blended 70% toward its opposite base role — every
+ *               accent AND the two base roles themselves, so a caller
+ *               de-emphasizing body text reaches for `foreground-muted` the
+ *               way it reaches for `primary-muted` to de-emphasize an accent.
+ *               `foreground-muted` is opaque here where Textual's is translucent,
+ *               drawing structural text at reduced weight without a
+ *               terminal-support-dependent SGR attribute.
+ * - `text-*`   = contrast text tinted 66% with the accent, the foreground for
+ *               a `*-muted` ground; `buildPalette` then holds it to that ground
+ * - `on-*`     = WCAG-correct contrast colour (black or white) for use as
+ *               foreground when the FULL accent is the background. Picked by
+ *               relative luminance — single source of truth so widgets never
+ *               need to invert fg/bg to get readable text. `contrastFor` is
+ *               the only place that decides black-vs-white.
+ * - `surface`  = background blended 5% toward foreground, a subtle lift
+ * - `*-darken-N` / `*-lighten-N` = the root moved 7.5% of CIE L* per rung
+ * - the component roles (`footer-*`, `markdown-*`, …) name the base role
+ *   Textual draws that component in
  *
- * A translucent base colour is drawn onto `background` before anything is
- * derived from it, so `on-*` is chosen against the colour the accent is drawn
- * as and every derived entry is opaque.
+ * [LAW:types-are-the-program] Total over every role but the eight given, so a
+ * palette cannot lack one and a role cannot exist without a way to derive it.
+ */
+const RULES = {
+    ...accentRules("primary"),
+    ...accentRules("secondary"),
+    ...accentRules("accent"),
+    ...accentRules("success"),
+    ...accentRules("warning"),
+    ...accentRules("error"),
+    ...lightness("background"),
+    ...lightness("foreground"),
+    ...lightness("panel"),
+    ...lightness("boost"),
+    ...lightness("surface"),
+    ...ladder("primary-background", (step) => accentBackground("primary", step)),
+    ...ladder("secondary-background", (step) => accentBackground("secondary", step)),
+    "background-muted": (at) => blendRgb(at("background"), at("foreground"), MUTED_BLEND),
+    "foreground-muted": (at) => blendRgb(at("foreground"), at("background"), MUTED_BLEND),
+    "foreground-disabled": (at) => withAlpha(at("foreground"), DISABLED_ALPHA),
+    surface: (at) => blendRgb(at("background"), at("foreground"), SURFACE_LIFT),
+    "surface-active": (at) => shiftLightness(at("surface"), SURFACE_ACTIVE_LIFT),
+    boost: textOn(BOOST_ALPHA),
+    panel: (at, dark) => {
+        const tinted = blendRgb(at("surface"), at("primary"), PANEL_TINT);
+        return dark ? at("boost").compositeOver(tinted) : tinted;
+    },
+    "primary-background": accentBackground("primary", 0),
+    "secondary-background": accentBackground("secondary", 0),
+    text: textOn(TEXT_FULL_ALPHA),
+    "text-muted": textOn(TEXT_MUTED_ALPHA),
+    "text-disabled": textOn(DISABLED_ALPHA),
+    border: same("primary"),
+    "border-blurred": (at) => shiftLightness(at("surface"), -BORDER_BLUR_DROP),
+    "block-cursor-background": same("primary"),
+    "block-cursor-foreground": same("on-primary"),
+    "block-cursor-blurred-background": (at) => withAlpha(at("primary"), BLURRED_CURSOR_ALPHA),
+    "block-cursor-blurred-foreground": same("foreground"),
+    "block-hover-background": (at) => withAlpha(at("boost"), HOVER_ALPHA),
+    "button-foreground": same("foreground"),
+    "button-color-foreground": same("on-primary"),
+    "footer-background": same("panel"),
+    "footer-foreground": same("foreground"),
+    "footer-description-background": none,
+    "footer-description-foreground": same("foreground"),
+    "footer-item-background": none,
+    "footer-key-background": none,
+    "footer-key-foreground": same("accent"),
+    "input-cursor-background": same("foreground"),
+    "input-cursor-foreground": same("background"),
+    "input-selection-background": (at) => withAlpha(at("primary-lighten-1"), SELECTION_ALPHA),
+    "link-background": none,
+    "link-background-hover": same("primary"),
+    "link-color": same("text"),
+    "link-color-hover": same("on-primary"),
+    "markdown-h1-background": none,
+    "markdown-h1-color": same("primary"),
+    "markdown-h2-background": none,
+    "markdown-h2-color": same("primary"),
+    "markdown-h3-background": none,
+    "markdown-h3-color": same("primary"),
+    "markdown-h4-background": none,
+    "markdown-h4-color": same("foreground"),
+    "markdown-h5-background": none,
+    "markdown-h5-color": same("foreground"),
+    "markdown-h6-background": none,
+    "markdown-h6-color": same("text-muted"),
+    scrollbar: (at) => alphaBlend(at("primary"), at("background-darken-1"), SCROLLBAR_ALPHA),
+    "scrollbar-active": same("primary"),
+    "scrollbar-hover": (at) => alphaBlend(at("primary"), at("background-darken-1"), SCROLLBAR_HOVER_ALPHA),
+    "scrollbar-background": same("background-darken-1"),
+    "scrollbar-background-active": same("scrollbar-background"),
+    "scrollbar-background-hover": same("scrollbar-background"),
+    "scrollbar-corner-color": same("scrollbar-background"),
+};
+const BASE_KEYS = [...ACCENT_KEYS, "background", "foreground"];
+/** Every role of every palette, read off the rules. */
+export const PALETTE_ROLES = [...BASE_KEYS, ...Object.keys(RULES)];
+const ROLE_NAMES = new Set(PALETTE_ROLES);
+/**
+ * Build a full semantic palette from its base colors and any other role it
+ * states: a stated role keeps its colour, and everything derived from it
+ * follows it, but for `text-*`, which is held to read on its `*-muted`. An
+ * authored theme is this with most roles stated; see `RULES` for what a role
+ * not stated becomes.
+ *
+ * A translucent colour is drawn onto `background` before anything is derived
+ * from it, so `on-*` is chosen against the colour the accent is drawn as.
+ * `boost` alone stays a layer: it is what `panel` composites.
  */
 export function buildPalette(name, dark, given) {
+    const known = statedRoles(name, given);
+    // [LAW:no-ambient-temporal-coupling] A rule asks for the roles it reads, so
+    // no order among the rules matters. The eight base roles are always known.
+    const at = (role) => {
+        const colour = known.get(role) ?? RULES[role](at, dark);
+        known.set(role, colour);
+        return colour;
+    };
+    // [LAW:single-enforcer] Stated and derived `text-*` alike: the tint is the
+    // palette's, whether it reads is decided here. A stated tint stays translucent
+    // because it composites on its `*-muted`, and a `*-muted` that draws nothing
+    // leaves it on `background`.
+    for (const key of ACCENT_KEYS) {
+        const ground = at(`${key}-muted`).compositeOver(at("background"));
+        known.set(`text-${key}`, accentText(given[`text-${key}`] ?? at(`text-${key}`), ground, at("background")));
+    }
+    return new Palette(name, dark, Object.fromEntries(PALETTE_ROLES.map((role) => [role, at(role)])));
+}
+/**
+ * The roles `given` states, drawn on `background`. The one place a caller's
+ * roles are read: a key that names no role is refused, and one holding
+ * `undefined` states nothing. [LAW:parse-dont-validate]
+ */
+function statedRoles(name, given) {
     const drawn = drawnOn(name, given.background);
+    const stated = Object.entries(given).flatMap(([role, colour]) => {
+        if (!ROLE_NAMES.has(role))
+            throw new RangeError(`palette ${JSON.stringify(name)}: ${JSON.stringify(role)} is not a role`);
+        if (colour === undefined)
+            return [];
+        return [[role, role === "boost" ? colour : drawn(colour)]];
+    });
+    const known = new Map(stated);
     // Every base colour is derived from, and a fully transparent one draws no
     // colour of its own to derive a muted shade or a contrast from.
     // [LAW:no-silent-failure]
-    const draw = (key) => {
+    for (const key of BASE_KEYS) {
         const colour = given[key];
         if (colour.alpha === 0) {
             throw new RangeError(`palette ${JSON.stringify(name)}: ${key} is fully transparent (${colour.hex}), so there is no colour to derive the palette from`);
         }
-        return drawn(colour);
-    };
-    const base = {
-        primary: draw("primary"),
-        secondary: draw("secondary"),
-        accent: draw("accent"),
-        success: draw("success"),
-        warning: draw("warning"),
-        error: draw("error"),
-        background: given.background,
-        foreground: draw("foreground"),
-    };
-    const vars = new Map();
-    // Base entries
-    vars.set("background", base.background);
-    vars.set("foreground", base.foreground);
-    for (const key of ACCENT_KEYS) {
-        vars.set(key, base[key]);
-    }
-    // Muted variants of the two base roles, same "blend 70% toward
-    // background" formula as the accent `*-muted` family below — every
-    // base color the palette defines gets a de-emphasized variant, not just
-    // the accents. `foreground-muted` is what a caller reaches for to draw
-    // structural/contextual text (labels, punctuation, ids) at reduced visual
-    // weight without a terminal-support-dependent SGR attribute.
-    vars.set("foreground-muted", blendRgb(base.foreground, base.background, MUTED_BLEND));
-    vars.set("background-muted", blendRgb(base.background, base.foreground, MUTED_BLEND));
-    // Surface — subtle lift from background
-    vars.set("surface", blendRgb(base.background, base.foreground, SURFACE_LIFT));
-    // Derived: muted, text-, and on- for each accent.
-    // [LAW:single-enforcer] contrastFor is the only place that decides
-    // black-vs-white for "text on this accent" — widgets read on-${accent}.
-    const contrastText = contrastFor(base.background);
-    for (const key of ACCENT_KEYS) {
-        const color = base[key];
-        const muted = blendRgb(color, base.background, MUTED_BLEND);
-        vars.set(`${key}-muted`, muted);
-        vars.set(`text-${key}`, accentText(alphaBlend(color, contrastText, TEXT_ALPHA), muted, base.background));
-        vars.set(`on-${key}`, contrastFor(color));
+        known.set(key, drawn(colour));
     }
-    return new Palette(name, dark, vars);
+    return known;
 }
 /**
  * A palette's `text-*`: its tint held to WCAG AA on `*-muted`, moved toward
@@ -92,9 +222,8 @@ export function buildPalette(name, dark, given) {
  * (test/themes/text-on-muted.test.ts).
  *
  * [LAW:single-enforcer] The one rule for the pair, for the palettes derived
- * here and the authored ones the registry hydrates: the tint is the theme's,
- * whether it reads is decided here.
+ * from a tint and the authored ones alike.
  */
-export function accentText(tint, muted, background) {
+function accentText(tint, muted, background) {
     return ensureContrastToward(tint, muted, TEXT_ON_MUTED, contrastFor(background));
 }

package/dist/themes/colorMath.d.ts

@@ -1,4 +1,4 @@
-import { ColorDepth, ColorRgba, contrastRatio, relativeLuminance, type TerminalTheme } from "../core/color.js";
+import { ColorDepth, ColorRgba, contrastRatio, relativeLuminance, type TerminalColors } from "../core/color.js";
 /**
  * Darken a color by N levels, where each level reduces HSL lightness by 10%.
  * Negative levels lighten. Level 0 returns an equivalent triplet (after the
@@ -9,6 +9,12 @@ export declare function darken(color: ColorRgba, levels: number): ColorRgba;
  * Lighten a color by N levels. Equivalent to `darken(color, -levels)`.
  */
 export declare function lighten(color: ColorRgba, levels: number): ColorRgba;
+/**
+ * Move a colour's CIE L* by `amount` (0..1 of the L* scale), keeping its alpha.
+ * Textual's `Color.lighten`, which drew every shade ladder in the bundled
+ * themes, so a ladder derived here continues the ones authored there.
+ */
+export declare function shiftLightness(color: ColorRgba, amount: number): ColorRgba;
 /**
  * Composite `fg` over `bg` with the given alpha (0..1). At alpha=0 returns bg;
  * at alpha=1 returns fg.
@@ -57,7 +63,7 @@ export { relativeLuminance, contrastRatio };
  * lightness moves — there is no caller-side "should I check contrast" branch.
  */
 export declare function ensureContrast(fg: ColorRgba, bg: ColorRgba, minRatio?: number, // WCAG AA for normal text
-drawnAt?: ColorDepth, substrate?: ColorRgba, terminal?: TerminalTheme): ColorRgba;
+drawnAt?: ColorDepth, substrate?: ColorRgba, terminal?: TerminalColors): ColorRgba;
 /**
  * `chosen` (composited opaque over `substrate`), or — when the depth the
  * terminal draws at rounds it to a colour `accept` refuses — the colour the
@@ -73,7 +79,7 @@ drawnAt?: ColorDepth, substrate?: ColorRgba, terminal?: TerminalTheme): ColorRgb
  * floor that is not text on its background (an open state standing off every
  * closed cell, two planes standing off each other).
  */
-export declare function ensureDrawn(chosen: ColorRgba, drawnAt: ColorDepth, accept: (candidate: ColorRgba, drawn: (c: ColorRgba) => ColorRgba) => boolean, substrate?: ColorRgba, terminal?: TerminalTheme): ColorRgba | undefined;
+export declare function ensureDrawn(chosen: ColorRgba, drawnAt: ColorDepth, accept: (candidate: ColorRgba, drawn: (c: ColorRgba) => ColorRgba) => boolean, substrate?: ColorRgba, terminal?: TerminalColors): ColorRgba | undefined;
 /**
  * The colour a ground is shown as at `drawnAt`: composited over `substrate`
  * (the SGR writer's black by default), rounded to the index the writer emits
@@ -81,7 +87,7 @@ export declare function ensureDrawn(chosen: ColorRgba, drawnAt: ColorDepth, acce
  * `terminal`'s own colour. The one account `ensureDrawn` and `ensureContrast`
  * measure by, for a caller that measures a floor of its own.
  */
-export declare function drawnColour(colour: ColorRgba, drawnAt: ColorDepth, substrate?: ColorRgba, terminal?: TerminalTheme): ColorRgba;
+export declare function drawnColour(colour: ColorRgba, drawnAt: ColorDepth, substrate?: ColorRgba, terminal?: TerminalColors): ColorRgba;
 /**
  * `fg` held to `minRatio` on `bg` in truecolor, moving in lightness toward
  * `toward` (black or white). `ensureContrast` moves toward the pole `bg`

package/dist/themes/colorMath.js

@@ -1,5 +1,5 @@
 import { ColorDepth, ColorRgba, ColorSpec, blendRgb, contrastRatio, downgradeTable, relativeLuminance, resolveTerminal, SURFACE_BLACK, } from "../core/color.js";
-import { Oklch } from "../core/oklch.js";
+import { Oklch, linearToSrgb, srgbToLinear } from "../core/oklch.js";
 const LEVEL_STEP = 0.1;
 function rgbToHsl(c) {
     const r = c.red / 255;
@@ -72,6 +72,38 @@ export function darken(color, levels) {
 export function lighten(color, levels) {
     return darken(color, -levels);
 }
+/** sRGB → CIE L*a*b* (D65, 2°): the space `shiftLightness` moves a colour in. */
+function rgbToLab(c) {
+    const [r, g, b] = [c.red, c.green, c.blue].map((v) => srgbToLinear(v / 255));
+    const [x, y, z] = [
+        (r * 41.24 + g * 35.76 + b * 18.05) / 95.047,
+        (r * 21.26 + g * 71.52 + b * 7.22) / 100,
+        (r * 1.93 + g * 11.92 + b * 95.05) / 108.883,
+    ].map((v) => (v > 0.008856 ? Math.cbrt(v) : 7.787 * v + 16 / 116));
+    return [116 * y - 16, 500 * (x - y), 200 * (y - z)];
+}
+function labToRgb(l, a, b, alpha) {
+    const cube = (v) => (v > 0.2068930344 ? v ** 3 : (v - 16 / 116) / 7.787);
+    const fy = (l + 16) / 116;
+    const y = cube(fy);
+    const x = 0.95047 * cube(a / 500 + fy);
+    const z = 1.08883 * cube(fy - b / 200);
+    const [red, green, blue] = [
+        x * 3.2406 + y * -1.5372 + z * -0.4986,
+        x * -0.9689 + y * 1.8758 + z * 0.0415,
+        x * 0.0557 + y * -0.204 + z * 1.057,
+    ].map((v) => clampChannel(255 * linearToSrgb(v)));
+    return new ColorRgba(red, green, blue, alpha);
+}
+/**
+ * Move a colour's CIE L* by `amount` (0..1 of the L* scale), keeping its alpha.
+ * Textual's `Color.lighten`, which drew every shade ladder in the bundled
+ * themes, so a ladder derived here continues the ones authored there.
+ */
+export function shiftLightness(color, amount) {
+    const [l, a, b] = rgbToLab(color);
+    return labToRgb(l + amount * 100, a, b, color.alpha);
+}
 /**
  * Composite `fg` over `bg` with the given alpha (0..1). At alpha=0 returns bg;
  * at alpha=1 returns fg.

package/dist/themes/data/types.d.ts

@@ -1,3 +1,4 @@
+import type { BaseRole, PaletteRole } from "../palette.js";
 /**
  * Static shape of a theme palette as authored. Each `data/<name>.ts` file
  * exports one of these as its default export. The barrel (`./index.ts`)
@@ -17,7 +18,8 @@ export interface ThemePaletteData {
      * them in the VGA defaults (`blue` as #000080), which belong to no theme.
      */
     readonly ansi: AnsiColorsData;
-    readonly vars: Readonly<Record<string, string>>;
+    /** The base roles and any other role this theme states; the rest are derived. */
+    readonly vars: Readonly<Record<BaseRole, string> & Partial<Record<PaletteRole, string>>>;
 }
 /**
  * ANSI colour numbers 0–15 in order: the eight normal colours, then their

package/dist/themes/palette.d.ts

@@ -1,6 +1,20 @@
 import type { ColorRgba } from "../core/color.js";
+export type AccentRole = "primary" | "secondary" | "accent" | "success" | "warning" | "error";
+export type BaseRole = AccentRole | "background" | "foreground";
+export type ShadedRole = BaseRole | "panel" | "boost" | "surface" | "primary-background" | "secondary-background";
+export type Shade = `-${"darken" | "lighten"}-${1 | 2 | 3}`;
 /**
- * A semantic palette: a named map from variable name → ColorRgba.
+ * Every role every palette has. [LAW:one-source-of-truth] This type is the one
+ * statement of the set: `buildPalette`'s rules are a total map over it, so a
+ * role added here does not compile until it can be derived, and the runtime
+ * list is read off those rules.
+ */
+export type PaletteRole = ShadedRole | `${ShadedRole}${Shade}` | `${AccentRole}-muted` | `text-${AccentRole}` | `on-${AccentRole}` | "background-muted" | "foreground-muted" | "foreground-disabled" | "surface-active" | "text" | "text-muted" | "text-disabled" | "border" | "border-blurred" | "block-cursor-background" | "block-cursor-foreground" | "block-cursor-blurred-background" | "block-cursor-blurred-foreground" | "block-hover-background" | "button-foreground" | "button-color-foreground" | "footer-background" | "footer-foreground" | "footer-description-background" | "footer-description-foreground" | "footer-item-background" | "footer-key-background" | "footer-key-foreground" | "input-cursor-background" | "input-cursor-foreground" | "input-selection-background" | "link-background" | "link-background-hover" | "link-color" | "link-color-hover" | `markdown-h${1 | 2 | 3 | 4 | 5 | 6}-${"background" | "color"}` | "scrollbar" | "scrollbar-active" | "scrollbar-hover" | "scrollbar-background" | "scrollbar-background-active" | "scrollbar-background-hover" | "scrollbar-corner-color";
+/** A colour for each role: what proves a palette complete. */
+export type PaletteRoles = Readonly<Record<PaletteRole, ColorRgba>>;
+/**
+ * A semantic palette: a named map from role → ColorRgba, holding every
+ * `PaletteRole`.
  *
  * Distinct from `ColorTable` (the integer-indexed quantization LUT used by
  * the downgrade pipeline). Palettes carry aesthetic intent — `primary`,
@@ -25,15 +39,17 @@ import type { ColorRgba } from "../core/color.js";
  * draws nothing on any surface, so it needs none and is handed out as it is,
  * and a `Style` reads it as no background at all.
  *
- * @throws RangeError when `background` is translucent, or when a colour is
- * partly transparent and there is no `background` to draw it on.
+ * @throws RangeError when `background` is translucent.
  */
 export declare class Palette {
     readonly name: string;
     readonly dark: boolean;
-    readonly vars: ReadonlyMap<string, ColorRgba>;
-    constructor(name: string, dark: boolean, vars: ReadonlyMap<string, ColorRgba>);
-    get(key: string): ColorRgba | undefined;
+    readonly vars: ReadonlyMap<PaletteRole, ColorRgba>;
+    constructor(name: string, dark: boolean, roles: PaletteRoles);
+    get(role: PaletteRole): ColorRgba;
+    get(role: string): ColorRgba | undefined;
+    /** This palette's roles, each put through `colour`: what a new palette is built from. */
+    mapRoles(colour: (colour: ColorRgba, role: PaletteRole) => ColorRgba): PaletteRoles;
 }
 /**
  * A palette colour as it is drawn: composited onto the palette's own

package/dist/themes/palette.js

@@ -1,5 +1,6 @@
 /**
- * A semantic palette: a named map from variable name → ColorRgba.
+ * A semantic palette: a named map from role → ColorRgba, holding every
+ * `PaletteRole`.
  *
  * Distinct from `ColorTable` (the integer-indexed quantization LUT used by
  * the downgrade pipeline). Palettes carry aesthetic intent — `primary`,
@@ -24,26 +25,26 @@
  * draws nothing on any surface, so it needs none and is handed out as it is,
  * and a `Style` reads it as no background at all.
  *
- * @throws RangeError when `background` is translucent, or when a colour is
- * partly transparent and there is no `background` to draw it on.
+ * @throws RangeError when `background` is translucent.
  */
 export class Palette {
     name;
     dark;
     vars;
-    constructor(name, dark, vars) {
+    constructor(name, dark, roles) {
         this.name = name;
         this.dark = dark;
         // [LAW:single-enforcer] Every palette is built through here, so this is
-        // where "a palette colour is opaque or draws nothing" holds. The fresh map is also the
-        // defensive copy: ReadonlyMap is a compile-time aliasing constraint, not a
-        // runtime one.
-        const background = vars.get("background");
-        const draw = background === undefined ? opaqueOnly(name) : drawnOn(name, background);
-        this.vars = new Map([...vars].map(([key, colour]) => [key, draw(colour, key)]));
+        // where "a palette colour is opaque or draws nothing" holds.
+        const draw = drawnOn(name, roles.background);
+        this.vars = new Map(Object.entries(roles).map(([role, colour]) => [role, draw(colour)]));
     }
-    get(key) {
-        return this.vars.get(key);
+    get(role) {
+        return this.vars.get(role);
+    }
+    /** This palette's roles, each put through `colour`: what a new palette is built from. */
+    mapRoles(colour) {
+        return Object.fromEntries([...this.vars].map(([role, was]) => [role, colour(was, role)]));
     }
 }
 /**
@@ -60,12 +61,3 @@ export function drawnOn(name, background) {
     // A fully transparent colour is not a tint: it draws nothing on any surface.
     return (colour) => (colour.alpha === 0 ? colour : colour.compositeOver(background));
 }
-// A palette with no background has nothing to draw a translucent colour on.
-function opaqueOnly(name) {
-    return (colour, key) => {
-        if (colour.alpha !== 1 && colour.alpha !== 0) {
-            throw new RangeError(`palette ${JSON.stringify(name)}: ${key} is translucent (${colour.hex}) but the palette has no "background" to draw it on`);
-        }
-        return colour;
-    };
-}

package/dist/themes/registry.d.ts

@@ -1,5 +1,5 @@
 import { ColorRgba, ColorTable } from "../core/color.js";
-import { Palette } from "./palette.js";
+import { type Palette } from "./palette.js";
 import { type ThemeName } from "./data/index.js";
 export type { ThemeName };
 /**
@@ -19,8 +19,7 @@ export declare function getThemePalette(name: string): Palette | null;
 /**
  * The eight base colors every theme must declare, and its ANSI table. Returned by
  * `getThemeBaseColors` for callers (notably `terminalThemes.ts`) that only
- * need the substrate and would otherwise pay the cost of hydrating the
- * full ~150-var palette and polluting the registry cache.
+ * need the substrate and would otherwise fill the registry cache.
  */
 export interface ThemeBaseColors {
     readonly name: string;