@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/themes/buildPalette.js

@@ -1,10 +1,12 @@
 import { blendRgb } from "../core/color.js";
-import { alphaBlend, contrastFor } from "./colorMath.js";
-import { Palette } from "./palette.js";
+import { alphaBlend, contrastFor, ensureContrastToward } 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 ACCENT_KEYS = ["primary", "secondary", "accent", "success", "warning", "error"];
+// 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"];
 /**
  * Build a full semantic palette from base colors.
  *
@@ -16,15 +18,41 @@ const ACCENT_KEYS = ["primary", "secondary", "accent", "success", "warning", "er
  *              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 (use as
- *              foreground in muted/background-tinted contexts)
+ * - `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 function buildPalette(name, dark, base) {
+export function buildPalette(name, dark, given) {
+    const drawn = drawnOn(name, given.background);
+    // 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) => {
+        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);
@@ -48,9 +76,25 @@ export function buildPalette(name, dark, base) {
     const contrastText = contrastFor(base.background);
     for (const key of ACCENT_KEYS) {
         const color = base[key];
-        vars.set(`${key}-muted`, blendRgb(color, base.background, MUTED_BLEND));
-        vars.set(`text-${key}`, alphaBlend(color, contrastText, TEXT_ALPHA));
+        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));
     }
     return new Palette(name, dark, vars);
 }
+/**
+ * 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.
+ */
+export 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 } from "../core/color.js";
+import { ColorDepth, ColorRgba, contrastRatio, relativeLuminance, type TerminalTheme } 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
@@ -44,10 +44,11 @@ export { relativeLuminance, contrastRatio };
  * can meet in the middle, so the ratio is measured on the drawn pair: a
  * colour that loses the floor there is replaced by the nearest cube/grey entry
  * that clears it (whose own rounding is itself). At ANSI the terminal draws
- * its own theme's colours, so the ratio is measured on the table's nominal
- * ones (`DRAWN_FROM`): they say which side of the ground text belongs on, and
- * text on its background's index measures 1:1 and is always replaced.
- * Truecolor draws the colour chosen.
+ * each index in its own theme's colour, so the ratio is measured on
+ * `terminal`'s sixteen: a theme whose black is light and white dark (Rosé Pine
+ * Dawn) turns the nominal table's sides over. A replacement is the colour the
+ * writer emits as the index nearest `fg` that clears the floor as `terminal`
+ * draws it. Truecolor draws the colour chosen.
  *
  * [LAW:single-enforcer] The one place "is this text readable, and if not fix
  * it" is decided. Callers route every fg/bg pair through here and the
@@ -56,14 +57,15 @@ 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): ColorRgba;
+drawnAt?: ColorDepth, substrate?: ColorRgba, terminal?: TerminalTheme): ColorRgba;
 /**
  * `chosen` (composited opaque over `substrate`), or — when the depth the
- * terminal draws at rounds it to a colour `accept` refuses — the nearest colour that depth draws as itself which
- * `accept` takes. `accept` sees the candidate as drawn, and `drawn`, the same
- * rounding for any other colour it measures against, so the caller states a
- * floor once and it holds on the colours the terminal shows — at ANSI, on
- * the table's nominal colours, as `ensureContrast` measures there. Truecolor
+ * terminal draws at rounds it to a colour `accept` refuses — the colour the
+ * writer emits as the nearest entry `accept` takes. `accept` sees the
+ * candidate as drawn, and `drawn`, the same rounding for any other colour it
+ * measures against, so the caller states a floor once and it holds on the
+ * colours the terminal shows — at ANSI, `terminal`'s own sixteen, as
+ * `ensureContrast` measures there. Truecolor
  * draws from no table, so a colour refused there has no replacement;
  * `undefined` means nothing the depth draws is accepted.
  *
@@ -71,12 +73,22 @@ drawnAt?: ColorDepth, substrate?: ColorRgba): ColorRgba;
  * 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): ColorRgba | undefined;
+export declare function ensureDrawn(chosen: ColorRgba, drawnAt: ColorDepth, accept: (candidate: ColorRgba, drawn: (c: ColorRgba) => ColorRgba) => boolean, substrate?: ColorRgba, terminal?: TerminalTheme): ColorRgba | undefined;
 /**
  * The colour a ground is shown as at `drawnAt`: composited over `substrate`
- * (the SGR writer's black by default), then rounded to the table that depth
- * draws from — at ANSI, that table's nominal colour stands in for the
- * theme's. The one account `ensureDrawn` and `ensureContrast` measure by, for
- * a caller that measures a floor of its own.
+ * (the SGR writer's black by default), rounded to the index the writer emits
+ * at that depth, and shown as the terminal shows that index — at ANSI, in
+ * `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): ColorRgba;
+export declare function drawnColour(colour: ColorRgba, drawnAt: ColorDepth, substrate?: ColorRgba, terminal?: TerminalTheme): ColorRgba;
+/**
+ * `fg` held to `minRatio` on `bg` in truecolor, moving in lightness toward
+ * `toward` (black or white). `ensureContrast` moves toward the pole `bg`
+ * itself contrasts with; a colour that already has a side (a palette's
+ * `text-*` is its text, tinted) passes that side, since on a ground near the
+ * 0.179 cutoff both poles clear and only one also reads on everything else
+ * the colour is drawn on. Where `toward` cannot clear `minRatio` on `bg`,
+ * the floor wins over the side: the answer is `contrastFor(bg)`.
+ */
+export declare function ensureContrastToward(fg: ColorRgba, bg: ColorRgba, minRatio: number, toward: ColorRgba): ColorRgba;

package/dist/themes/colorMath.js

@@ -1,4 +1,4 @@
-import { ColorDepth, ColorRgba, EIGHT_BIT_DOWNGRADE_TABLE, STANDARD_TABLE, blendRgb, contrastRatio, relativeLuminance, SURFACE_BLACK, } from "../core/color.js";
+import { ColorDepth, ColorRgba, ColorSpec, blendRgb, contrastRatio, downgradeTable, relativeLuminance, resolveTerminal, SURFACE_BLACK, } from "../core/color.js";
 import { Oklch } from "../core/oklch.js";
 const LEVEL_STEP = 0.1;
 function rgbToHsl(c) {
@@ -121,10 +121,11 @@ const CONTRAST_ITERS = 20;
  * can meet in the middle, so the ratio is measured on the drawn pair: a
  * colour that loses the floor there is replaced by the nearest cube/grey entry
  * that clears it (whose own rounding is itself). At ANSI the terminal draws
- * its own theme's colours, so the ratio is measured on the table's nominal
- * ones (`DRAWN_FROM`): they say which side of the ground text belongs on, and
- * text on its background's index measures 1:1 and is always replaced.
- * Truecolor draws the colour chosen.
+ * each index in its own theme's colour, so the ratio is measured on
+ * `terminal`'s sixteen: a theme whose black is light and white dark (Rosé Pine
+ * Dawn) turns the nominal table's sides over. A replacement is the colour the
+ * writer emits as the index nearest `fg` that clears the floor as `terminal`
+ * draws it. Truecolor draws the colour chosen.
  *
  * [LAW:single-enforcer] The one place "is this text readable, and if not fix
  * it" is decided. Callers route every fg/bg pair through here and the
@@ -133,26 +134,27 @@ const CONTRAST_ITERS = 20;
  * lightness moves — there is no caller-side "should I check contrast" branch.
  */
 export function ensureContrast(fg, bg, minRatio = 4.5, // WCAG AA for normal text
-drawnAt = ColorDepth.TRUECOLOR, substrate = SURFACE_BLACK) {
+drawnAt = ColorDepth.TRUECOLOR, substrate = SURFACE_BLACK, terminal) {
     const ground = drawnBackground(bg, substrate);
-    const chosen = ensureTruecolorContrast(fg, ground, minRatio);
+    const chosen = ensureContrastToward(fg, ground, minRatio, contrastFor(ground));
     // [LAW:dataflow-not-control-flow] The depth names the table the terminal
     // draws from; every table is measured the same way.
-    const table = DRAWN_FROM[drawnAt];
+    const table = drawnTable(drawnAt, terminal);
     if (table === undefined)
         return chosen;
-    const drawnBg = drawnColour(ground, drawnAt, substrate);
-    if (contrastRatio(drawnColour(chosen, drawnAt, substrate), drawnBg) >= minRatio)
+    const shownBg = shownAs(table, ground);
+    if (contrastRatio(shownAs(table, chosen), shownBg) >= minRatio)
         return chosen;
-    return table.get(table.matchReadable(chosen, drawnBg, minRatio));
+    return table.written.get(table.shown.matchReadable(fg.compositeOver(ground), shownBg, minRatio));
 }
 /**
  * `chosen` (composited opaque over `substrate`), or — when the depth the
- * terminal draws at rounds it to a colour `accept` refuses — the nearest colour that depth draws as itself which
- * `accept` takes. `accept` sees the candidate as drawn, and `drawn`, the same
- * rounding for any other colour it measures against, so the caller states a
- * floor once and it holds on the colours the terminal shows — at ANSI, on
- * the table's nominal colours, as `ensureContrast` measures there. Truecolor
+ * terminal draws at rounds it to a colour `accept` refuses — the colour the
+ * writer emits as the nearest entry `accept` takes. `accept` sees the
+ * candidate as drawn, and `drawn`, the same rounding for any other colour it
+ * measures against, so the caller states a floor once and it holds on the
+ * colours the terminal shows — at ANSI, `terminal`'s own sixteen, as
+ * `ensureContrast` measures there. Truecolor
  * draws from no table, so a colour refused there has no replacement;
  * `undefined` means nothing the depth draws is accepted.
  *
@@ -160,38 +162,45 @@ drawnAt = ColorDepth.TRUECOLOR, substrate = SURFACE_BLACK) {
  * floor that is not text on its background (an open state standing off every
  * closed cell, two planes standing off each other).
  */
-export function ensureDrawn(chosen, drawnAt, accept, substrate = SURFACE_BLACK) {
+export function ensureDrawn(chosen, drawnAt, accept, substrate = SURFACE_BLACK, terminal) {
     // The floor was measured on `chosen` composited over `substrate`, so that
     // opaque colour is what is returned — never a translucent one a different
     // ground would composite into a colour `accept` never saw.
     const opaque = drawnBackground(chosen, substrate);
-    const drawn = (c) => drawnColour(c, drawnAt, substrate);
+    const table = drawnTable(drawnAt, terminal);
+    const drawn = (c) => shownAs(table, drawnBackground(c, substrate));
     if (accept(drawn(opaque), drawn))
         return opaque;
     // [LAW:dataflow-not-control-flow] Truecolor draws from no table, so it has
     // no candidates: a refusal there is `undefined` like any exhausted search.
-    const table = DRAWN_FROM[drawnAt];
-    const index = table?.matchWhere(opaque, (entry) => accept(entry, drawn));
-    return index === undefined ? undefined : table.get(index);
+    const index = table?.shown.matchWhere(opaque, (entry) => accept(entry, drawn));
+    return index === undefined ? undefined : table.written.get(index);
 }
 /**
  * The colour a ground is shown as at `drawnAt`: composited over `substrate`
- * (the SGR writer's black by default), then rounded to the table that depth
- * draws from — at ANSI, that table's nominal colour stands in for the
- * theme's. The one account `ensureDrawn` and `ensureContrast` measure by, for
- * a caller that measures a floor of its own.
+ * (the SGR writer's black by default), rounded to the index the writer emits
+ * at that depth, and shown as the terminal shows that index — at ANSI, in
+ * `terminal`'s own colour. The one account `ensureDrawn` and `ensureContrast`
+ * measure by, for a caller that measures a floor of its own.
  */
-export function drawnColour(colour, drawnAt, substrate = SURFACE_BLACK) {
-    const opaque = drawnBackground(colour, substrate);
-    const table = DRAWN_FROM[drawnAt];
-    return table === undefined ? opaque : table.get(table.match(opaque));
+export function drawnColour(colour, drawnAt, substrate = SURFACE_BLACK, terminal) {
+    return shownAs(drawnTable(drawnAt, terminal), drawnBackground(colour, substrate));
+}
+/**
+ * An opaque colour as the terminal shows it: downgraded to the index the
+ * writer emits and drawn as the terminal draws that index.
+ * [LAW:one-source-of-truth] That rounding is `ColorSpec.downgrade`'s, the one
+ * `Style.drawnColors` writes; the tables here only list the candidates.
+ */
+function shownAs(table, opaque) {
+    return table === undefined ? opaque : ColorSpec.fromRgba(opaque).downgrade(table.depth).getTruecolor(table.terminal);
 }
 /**
  * A background as it is drawn: composited over the surface beneath it. That
  * surface is a fact about where the pair is drawn, so it arrives as a value:
- * the SGR writer (`Style.toSgrCodes`) composites over `SURFACE_BLACK`, the
- * default here; a caller choosing text for a different surface — an export's
- * canvas, `exportCanvas(theme).background` — names that one.
+ * the SGR writer (`Style.toSgrCodes`) and the exports that picture its output
+ * composite over `SURFACE_BLACK`, the default here; a caller that composites
+ * its colours onto a different surface itself names that one.
  * [LAW:no-silent-failure] A surface has nothing under it, so a translucent one
  * has no drawn colour to offer; `compositeOver` would read its raw RGB as if
  * it were opaque, so it is refused here rather than measured wrong.
@@ -207,28 +216,45 @@ function drawnBackground(bg, substrate) {
     return bg.compositeOver(substrate);
 }
 /**
- * The downgrade table the terminal draws from, by depth, measured at each
- * entry's colour. The 256-colour cube and grey ramp are fixed by xterm, so
- * those measurements are exact. ANSI 0–15 are the terminal theme's own, so
- * the table's nominal colours stand in for them: they are wrong in hue from
- * theme to theme, but not about which side of a ground an entry sits on —
- * and two colours on one index are one colour in every theme, which the
- * nominal ratio of 1 refuses. Truecolor draws the chosen colour itself.
+ * The table the terminal draws from at `drawnAt`. The 256-colour cube and
+ * grey ramp are fixed by xterm, so the colour written is the colour shown.
+ * ANSI 0–15 are the terminal theme's own: the writer still picks the index by
+ * the nominal table — the Windows console's at WINDOWS — and the terminal
+ * shows `terminal`'s colour there.
+ * Truecolor draws the chosen colour itself, as do the depths no table stands
+ * behind.
+ */
+function drawnTable(drawnAt, terminal) {
+    const drawnBy = resolveTerminal(terminal, drawnAt);
+    switch (drawnAt) {
+        case ColorDepth.EIGHT_BIT:
+            return { depth: drawnAt, terminal: drawnBy, written: downgradeTable(drawnAt), shown: downgradeTable(drawnAt) };
+        case ColorDepth.STANDARD:
+        case ColorDepth.WINDOWS:
+            return { depth: drawnAt, terminal: drawnBy, written: downgradeTable(drawnAt), shown: drawnBy.ansiColors };
+        case ColorDepth.TRUECOLOR:
+        case ColorDepth.DEFAULT:
+            return undefined;
+    }
+}
+/**
+ * `fg` held to `minRatio` on `bg` in truecolor, moving in lightness toward
+ * `toward` (black or white). `ensureContrast` moves toward the pole `bg`
+ * itself contrasts with; a colour that already has a side (a palette's
+ * `text-*` is its text, tinted) passes that side, since on a ground near the
+ * 0.179 cutoff both poles clear and only one also reads on everything else
+ * the colour is drawn on. Where `toward` cannot clear `minRatio` on `bg`,
+ * the floor wins over the side: the answer is `contrastFor(bg)`.
  */
-const DRAWN_FROM = {
-    [ColorDepth.EIGHT_BIT]: EIGHT_BIT_DOWNGRADE_TABLE,
-    [ColorDepth.STANDARD]: STANDARD_TABLE,
-};
-function ensureTruecolorContrast(fg, bg, minRatio) {
+export function ensureContrastToward(fg, bg, minRatio, toward) {
     // Flatten translucency so the guarantee holds for the displayed color, not
-    // the raw bytes (e.g. a "#FFFFFF60" text-disabled over a light surface).
+    // the raw bytes (e.g. a hand-written "#FFFFFF60" over a light surface).
     const opaqueFg = fg.compositeOver(bg);
     if (contrastRatio(opaqueFg, bg) >= minRatio)
         return opaqueFg;
     const lab = Oklch.fromRgba(opaqueFg);
-    // The pole that increases contrast: lighten toward white on a dark bg, darken
-    // toward black on a light one. `contrastFor`'s 0.179 cutoff names it.
-    const poleL = relativeLuminance(bg) > 0.179 ? 0 : 1;
+    // `toward` is black or white, the pole the lightness moves to.
+    const poleL = relativeLuminance(toward) > 0.179 ? 1 : 0;
     // If even the pole of this hue can't reach the ratio, the hue physically
     // can't — return the true maximum-contrast pick (pure black/white from
     // contrastFor). The gamut-clamped OKLCH pole is only *near* b/w, so

package/dist/themes/colorRef.d.ts

@@ -1,4 +1,4 @@
-import { ColorRgba } from "../core/color.js";
+import { type ColorRgba } from "../core/color.js";
 import type { Palette } from "./palette.js";
 /**
  * A **color reference** is the one string form an author uses to name a
@@ -18,23 +18,8 @@ import type { Palette } from "./palette.js";
  */
 export declare class ColorRefError extends Error {
     readonly ref: string;
-    constructor(ref: string, detail: string);
+    constructor(ref: string, detail: string, options?: ErrorOptions);
 }
-/**
- * The literal-color shape, exported so the template bindings gate on the same
- * pattern this module parses. [LAW:one-source-of-truth] — one regex, one
- * parser body; the bindings add only their own error wording.
- */
-export declare const HEX_COLOR_RE: RegExp;
-/**
- * Parse a `#RRGGBB` / `#RRGGBBAA` literal. The hex arm of
- * {@link resolveColorRef}, separated so callers that accept *only* literal
- * colors (color math, which cannot meaningfully operate on a palette name)
- * share the one implementation instead of re-deriving it.
- *
- * @throws {ColorRefError} when `hex` is not a well-formed literal.
- */
-export declare function parseHexColor(hex: string): ColorRgba;
 /**
  * Resolve a color reference against `palette`.
  *

package/dist/themes/colorRef.js

@@ -1,4 +1,4 @@
-import { parseRgbHex, parseRgbaHex } from "../core/color.js";
+import { ColorParseError, parseHexColor } from "../core/color.js";
 /**
  * A **color reference** is the one string form an author uses to name a
  * concrete color: a palette variable name (`"primary"`, `"surface-active"`,
@@ -17,8 +17,8 @@ import { parseRgbHex, parseRgbaHex } from "../core/color.js";
  */
 export class ColorRefError extends Error {
     ref;
-    constructor(ref, detail) {
-        super(`color reference ${JSON.stringify(ref)} did not resolve — ${detail}`);
+    constructor(ref, detail, options) {
+        super(`color reference ${JSON.stringify(ref)} did not resolve — ${detail}`, options);
         this.ref = ref;
         this.name = "ColorRefError";
     }
@@ -30,32 +30,6 @@ export class ColorRefError extends Error {
 // palette lookup that would report a confusing "unknown name" instead of
 // "malformed hex".
 const HEX_LEAD = "#";
-/**
- * The literal-color shape, exported so the template bindings gate on the same
- * pattern this module parses. [LAW:one-source-of-truth] — one regex, one
- * parser body; the bindings add only their own error wording.
- */
-export const HEX_COLOR_RE = /^#[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/;
-const OPAQUE_HEX_LENGTH = 7; // "#RRGGBB"
-/**
- * Parse a `#RRGGBB` / `#RRGGBBAA` literal. The hex arm of
- * {@link resolveColorRef}, separated so callers that accept *only* literal
- * colors (color math, which cannot meaningfully operate on a palette name)
- * share the one implementation instead of re-deriving it.
- *
- * @throws {ColorRefError} when `hex` is not a well-formed literal.
- */
-export function parseHexColor(hex) {
-    const trimmed = hex.trim();
-    if (!HEX_COLOR_RE.test(trimmed)) {
-        throw new ColorRefError(hex, "expected #RRGGBB or #RRGGBBAA");
-    }
-    // Both parsers take the digits without the leading `#`.
-    const digits = trimmed.slice(1);
-    return trimmed.length > OPAQUE_HEX_LENGTH
-        ? parseRgbaHex(digits)
-        : parseRgbHex(digits);
-}
 // Cap the "did you mean" list. Palettes carry ~150 variables; dumping all of
 // them buries the message. Nearby names are what a mistyped reference needs.
 const SUGGESTION_LIMIT = 8;
@@ -74,8 +48,16 @@ const SUGGESTION_LIMIT = 8;
  */
 export function resolveColorRef(palette, ref) {
     const trimmed = ref.trim();
-    if (trimmed.startsWith(HEX_LEAD))
-        return parseHexColor(trimmed);
+    if (trimmed.startsWith(HEX_LEAD)) {
+        try {
+            return parseHexColor(trimmed);
+        }
+        catch (cause) {
+            if (!(cause instanceof ColorParseError))
+                throw cause;
+            throw new ColorRefError(ref, cause.message, { cause });
+        }
+    }
     const hit = palette.get(trimmed);
     if (hit === undefined) {
         throw new ColorRefError(ref, `no such variable in palette ${JSON.stringify(palette.name)}` +

package/dist/themes/palette.d.ts

@@ -11,6 +11,22 @@ import type { ColorRgba } from "../core/color.js";
  * author-written *reference* (a name, or a `#RRGGBB` literal) into a colour
  * is `resolveColorRef`'s job in `colorRef.ts`, so a Palette never has to
  * know about the syntax callers write.
+ *
+ * Every colour a Palette hands out is opaque or fully transparent. A theme's translucent variable
+ * (Textual's `boost`, a hover overlay) is a tint meant for that theme's own
+ * background, and a colour leaving the palette no longer knows which
+ * background that was: the SGR writer would composite it over the terminal's
+ * black, which is not the theme's background, and draw a tint the theme never
+ * meant.
+ * So it is drawn onto `background` here, once, and the writer, the exporters
+ * and the contrast choosers all read the colour it has there. On any other
+ * surface it keeps that colour: the tint does not follow what is under it.
+ * The exception is a fully transparent colour, Textual's "no background": it
+ * 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.
  */
 export declare class Palette {
     readonly name: string;
@@ -19,3 +35,11 @@ export declare class Palette {
     constructor(name: string, dark: boolean, vars: ReadonlyMap<string, ColorRgba>);
     get(key: string): ColorRgba | undefined;
 }
+/**
+ * A palette colour as it is drawn: composited onto the palette's own
+ * `background`, which has nothing under it and so must itself be opaque.
+ * [LAW:one-source-of-truth] The one statement of what a translucent palette
+ * colour means; `buildPalette` draws its base colours through it before
+ * deriving from them.
+ */
+export declare function drawnOn(name: string, background: ColorRgba): (colour: ColorRgba) => ColorRgba;

package/dist/themes/palette.js

@@ -10,6 +10,22 @@
  * author-written *reference* (a name, or a `#RRGGBB` literal) into a colour
  * is `resolveColorRef`'s job in `colorRef.ts`, so a Palette never has to
  * know about the syntax callers write.
+ *
+ * Every colour a Palette hands out is opaque or fully transparent. A theme's translucent variable
+ * (Textual's `boost`, a hover overlay) is a tint meant for that theme's own
+ * background, and a colour leaving the palette no longer knows which
+ * background that was: the SGR writer would composite it over the terminal's
+ * black, which is not the theme's background, and draw a tint the theme never
+ * meant.
+ * So it is drawn onto `background` here, once, and the writer, the exporters
+ * and the contrast choosers all read the colour it has there. On any other
+ * surface it keeps that colour: the tint does not follow what is under it.
+ * The exception is a fully transparent colour, Textual's "no background": it
+ * 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.
  */
 export class Palette {
     name;
@@ -18,11 +34,38 @@ export class Palette {
     constructor(name, dark, vars) {
         this.name = name;
         this.dark = dark;
-        // Defensive copy: ReadonlyMap is a compile-time aliasing constraint, not a
-        // runtime one. Copying at the seam makes Palette genuinely immutable.
-        this.vars = new Map(vars);
+        // [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)]));
     }
     get(key) {
         return this.vars.get(key);
     }
 }
+/**
+ * A palette colour as it is drawn: composited onto the palette's own
+ * `background`, which has nothing under it and so must itself be opaque.
+ * [LAW:one-source-of-truth] The one statement of what a translucent palette
+ * colour means; `buildPalette` draws its base colours through it before
+ * deriving from them.
+ */
+export function drawnOn(name, background) {
+    if (background.alpha !== 1) {
+        throw new RangeError(`palette ${JSON.stringify(name)}: background is the surface its translucent colours are drawn on, so it must be opaque; got ${background.hex}`);
+    }
+    // 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/ramp.d.ts

@@ -9,46 +9,28 @@
  * can no longer transpose with the palette it was meant to belong to. A ramp
  * is the one function whose input is a number, so the decision stays inside.
  *
- * A threshold cascade is a ramp too: the same stops with a `step` easing hold
+ * A threshold cascade is a ramp too: the same stops with the `step` ease hold
  * each color until the next position, which is exactly `≥ threshold → hotter`
  * written as data. [LAW:one-type-per-behavior] One primitive; the easing is a
- * value, so a gradient and a cascade differ by one word, not by which function
- * was called.
+ * value — any `Ease` from `core/easing`, the vocabulary every effect shares —
+ * so a gradient and a cascade differ by one word, not by which function was
+ * called. [LAW:dataflow-not-control-flow] `at` applies it unconditionally.
  *
  * Interpolation is in OKLCH (`Oklch.mix`), so a `linear` ramp between two
  * theme colors passes through perceptually even steps rather than the muddy
  * midpoints of an sRGB blend.
  *
- * [LAW:one-way-deps] Imports `core/color` and `core/oklch` only; nothing here
- * knows what a palette is. Resolving stop *names* is the template binding's
+ * [LAW:one-way-deps] Imports `core/color`, `core/easing` and `core/oklch`
+ * only; nothing here knows what a palette is. Resolving stop *names* is the template binding's
  * job (`paletteFuncs`), which hands this module resolved colors.
  */
 import type { ColorRgba } from "../core/color.js";
+import type { Ease } from "../core/easing.js";
 /** One stop: the color the ramp is exactly `color` at position `at`. */
 export interface ColorStop {
     readonly at: number;
     readonly color: ColorRgba;
 }
-/**
- * How a value between two stops maps to progress along them. Each easing is
- * a function on segment progress `t ∈ [0, 1)` — `linear` keeps it, `step`
- * holds the left stop for the whole segment.
- *
- * [LAW:dataflow-not-control-flow] The easing is looked up by name and applied
- * unconditionally; `at` runs the same code for a gradient and a cascade.
- */
-export declare const RAMP_EASINGS: {
-    readonly linear: (t: number) => number;
-    readonly step: () => number;
-};
-export type RampEasing = keyof typeof RAMP_EASINGS;
-export declare const RAMP_EASING_NAMES: readonly RampEasing[];
-/**
- * The gate a spelled easing crosses. [LAW:parse-dont-validate] — returns the
- * narrowed name, so `ColorRamp` never re-checks. Unknown names throw naming
- * every legal one. [LAW:no-silent-failure]
- */
-export declare function parseRampEasing(name: string): RampEasing;
 /**
  * An immutable ramp over stops sorted by position.
  *
@@ -65,19 +47,24 @@ export declare function parseRampEasing(name: string): RampEasing;
  * same way).
  */
 export declare class ColorRamp {
-    readonly easing: RampEasing;
+    readonly ease: Ease;
     readonly stops: readonly ColorStop[];
-    constructor(easing: RampEasing, stops: readonly ColorStop[]);
+    constructor(ease: Ease, stops: readonly ColorStop[]);
     /**
      * The color at `value`. Below the first stop it is the first color; at or
-     * above the last stop it is the last; between two stops it is `easing`
-     * of the way from the lower to the upper, so a value exactly on a stop is
-     * that stop's color, byte for byte.
+     * above the last stop it is the last; between two stops the raw progress
+     * from the lower to the upper goes through `ease`, and the eased progress
+     * says how far to mix.
      *
-     * The two endpoint returns are the exactness contract, not a shortcut:
-     * the sRGB → OKLCH → sRGB round-trip can land a channel one unit off, and a
-     * ramp that does not hit its own stops exactly would make a `step` ramp
-     * paint a color the author never wrote.
+     * Eased progress 0 is the lower stop's color and 1 the upper's, byte for
+     * byte — the exactness contract, not a shortcut: the sRGB → OKLCH → sRGB
+     * round-trip can land a channel one unit off, and a ramp that did not hit
+     * its own stops exactly would make a `step` ramp paint a color the author
+     * never wrote. So a value on a stop is that stop's color whenever the ease
+     * starts at 0, as every built-in does but `step-start` and the
+     * `jump-start`/`jump-both` steps, which jump at the start of the interval as
+     * CSS defines them. An ease that overshoots [0, 1] holds the end colors
+     * where it does: a ramp never paints outside its stops.
      */
     at(value: number): ColorRgba;
 }