@promptctl/rich-js 0.18.1 → 0.19.0

package/dist/template-bindings/color-funcs.js

@@ -26,7 +26,7 @@
  *
  * ### The carrier is a hex string, deliberately
  *
- * A color crosses the template seam as `#RRGGBB`, not as an opaque object,
+ * A color crosses the template seam as `#RRGGBB` (or `#RRGGBBAA`), not as an opaque object,
  * for three reasons:
  *
  * 1. **The type separates.** `"string"` is the strictest arg slot the template
@@ -55,9 +55,8 @@
  * from that point on the math is pure. A consumer with no theme system at all still gets
  * the full color vocabulary by feeding it hex literals. [LAW:one-way-deps]
  */
-import { blendRgb, ColorDepth } from "../core/color.js";
+import { blendRgb, ColorDepth, ColorParseError, parseHexColor } from "../core/color.js";
 import { Oklch, IDENTITY } from "../core/oklch.js";
-import { HEX_COLOR_RE, parseHexColor } from "../themes/colorRef.js";
 import { darken, contrastFor, ensureContrast } from "../themes/colorMath.js";
 /**
  * The gate every color argument crosses. [LAW:parse-dont-validate] — the
@@ -67,15 +66,37 @@ import { darken, contrastFor, ensureContrast } from "../themes/colorMath.js";
  * its error *wording*, because the mistake it catches is almost always the
  * same one — a palette name passed where a color belongs (`darken "primary" 2`)
  * — and an author who reads "wrap it: darken (color "primary")" is corrected in
- * one step, where "expected #RRGGBB" leaves them guessing.
+ * one step, where "expected #RRGGBB" leaves them guessing. What it parses
+ * must then be a colour these functions can compute with (`computable`).
  * [LAW:no-silent-failure]
  */
 function asColor(value, func) {
-    if (!HEX_COLOR_RE.test(value.trim())) {
+    let colour;
+    try {
+        colour = parseHexColor(value.trim());
+    }
+    catch (cause) {
+        if (!(cause instanceof ColorParseError))
+            throw cause;
         throw new TypeError(`${func} expected a color (#RRGGBB or #RRGGBBAA), got ${JSON.stringify(value)}` +
-            ` — to use a palette name here, wrap it: ${func} (color ${JSON.stringify(value)}) …`);
+            ` — to use a palette name here, wrap it: ${func} (color ${JSON.stringify(value)}) …`, { cause });
+    }
+    return computable(colour, func, JSON.stringify(value));
+}
+/**
+ * A colour the colour functions can compute with. A fully transparent one — a
+ * theme's "no background", `#00000000` — has no colour of its own: what shows
+ * through it is whatever surface it lands on, which a template cannot know.
+ * Darkening, mixing or contrasting it would answer for a surface nobody named,
+ * so it is refused here, for every colour function and every `ramp` stop.
+ * [LAW:single-enforcer]
+ */
+export function computable(colour, func, written) {
+    if (colour.alpha === 0) {
+        throw new RangeError(`${func} got ${written}, which is fully transparent: it draws no colour of its own, ` +
+            `so there is nothing to compute with — use the colour of the surface it sits on, e.g. (color "background")`);
     }
-    return parseHexColor(value);
+    return colour;
 }
 // [LAW:single-enforcer] Every colour function is fixed-arity, so the engine's
 // arity gate refuses a missing or surplus argument before the body runs.
@@ -145,11 +166,16 @@ const RATIO_RANGE = {
     note: "4.5 = AA body text, 3 = AA large text",
 };
 const contrastOnFunc = colorFunc(["string"], ((bgHex) => contrastFor(asColor(bgHex, "contrastOn")).hex));
+const TRUECOLOR = { depth: ColorDepth.TRUECOLOR };
 /**
- * The `readableOn` binding, measuring at the depth `drawnAt` names when it is
- * evaluated — a consumer that renders at a per-call depth registers its own.
+ * The `readableOn` binding, measuring where `drawnAt` says the text lands when
+ * it is evaluated — a consumer that renders to a per-call destination
+ * registers its own.
  */
-export const readableOnFunc = (drawnAt) => colorFunc(["string", "string", "float"], ((fgHex, bgHex, ratio) => ensureContrast(asColor(fgHex, "readableOn"), asColor(bgHex, "readableOn"), asAmount(ratio, "readableOn", "ratio", RATIO_RANGE), drawnAt()).hex));
+export const readableOnFunc = (drawnAt) => colorFunc(["string", "string", "float"], ((fgHex, bgHex, ratio) => {
+    const { depth, terminal } = drawnAt();
+    return ensureContrast(asColor(fgHex, "readableOn"), asColor(bgHex, "readableOn"), asAmount(ratio, "readableOn", "ratio", RATIO_RANGE), depth, undefined, terminal).hex;
+}));
 // --- OKLCH axes ---
 //
 // [LAW:one-source-of-truth] One function per `ThemeKey` axis, and the table is
@@ -201,11 +227,11 @@ function oklchAxisFuncs() {
  * Pair with `paletteFuncs()` to name colors from a theme, and with
  * `richTextStyleFuncs()`'s `fg`/`bg` to paint them onto text.
  *
- * @param drawnAt the depth the terminal will draw at, read on every
- *   `readableOn` evaluation so a host that learns its depth per render passes
- *   one getter; defaults to truecolor.
+ * @param drawnAt where the text will be drawn — the depth, and the terminal
+ *   when known — read on every `readableOn` evaluation so a host that learns
+ *   its destination per render passes one getter; defaults to truecolor.
  */
-export function colorFuncs(drawnAt = () => ColorDepth.TRUECOLOR) {
+export function colorFuncs(drawnAt = () => TRUECOLOR) {
     return {
         darken: darkenFunc,
         lighten: lightenFunc,

package/dist/template-bindings/helpers.d.ts

@@ -6,7 +6,7 @@
  * registrations and the palette-function registrations use this same operation;
  * keeping one copy prevents the two from drifting.
  */
-import { Style } from "../core/style.js";
+import { type Style } from "../core/style.js";
 import { RichText } from "../core/text.js";
 /**
  * Apply a style on top of an already-styled RichText fragment.
@@ -19,6 +19,8 @@ import { RichText } from "../core/text.js";
  * is the binding's own `T`. Misuse (`{{ red someMap }}`) fails loudly here
  * rather than producing a malformed fragment.
  *
- * Conflict resolution: `Style.add` — the outer (newly applied) style wins.
+ * Conflict resolution: `Style.add` — the outer (newly applied) style wins. A
+ * base style that is a name is layered under, not resolved: a template runs
+ * before the render whose theme says what the name stands for.
  */
 export declare function applyStyleToFragment(child: unknown, style: Style): RichText;

package/dist/template-bindings/helpers.js

@@ -6,7 +6,7 @@
  * registrations and the palette-function registrations use this same operation;
  * keeping one copy prevents the two from drifting.
  */
-import { Style, StyleSyntaxError } from "../core/style.js";
+import { layerStyle } from "../core/style.js";
 import { RichText } from "../core/text.js";
 /**
  * Apply a style on top of an already-styled RichText fragment.
@@ -19,30 +19,15 @@ import { RichText } from "../core/text.js";
  * is the binding's own `T`. Misuse (`{{ red someMap }}`) fails loudly here
  * rather than producing a malformed fragment.
  *
- * Conflict resolution: `Style.add` — the outer (newly applied) style wins.
+ * Conflict resolution: `Style.add` — the outer (newly applied) style wins. A
+ * base style that is a name is layered under, not resolved: a template runs
+ * before the render whose theme says what the name stands for.
  */
 export function applyStyleToFragment(child, style) {
     if (!(child instanceof RichText)) {
         throw new TypeError(`template function expected a RichText fragment, got ${typeof child === "object" ? Object.prototype.toString.call(child) : typeof child}`);
     }
     const result = child.copy();
-    result.style = baseStyleOf(child.style).add(style);
+    result.style = layerStyle(child.style, style);
     return result;
 }
-/**
- * A fragment's base style as a `Style`. A string must parse as a definition: a
- * name resolves only against the theme of the render that draws it, and a
- * template runs before any render exists.
- */
-function baseStyleOf(style) {
-    if (style instanceof Style)
-        return style;
-    try {
-        return Style.parse(style);
-    }
-    catch (err) {
-        if (!(err instanceof StyleSyntaxError))
-            throw err;
-        throw new TypeError(`template function cannot style a fragment whose base style "${style}" is not a style definition: a style name resolves only against the theme of a render`, { cause: err });
-    }
-}

package/dist/template-bindings/index.d.ts

@@ -36,9 +36,10 @@
 import { type Engine, type FuncMap } from "@promptctl/go-template-js";
 import { RichText } from "../core/text.js";
 import { Segment } from "../core/segment.js";
-import { ColorDepth } from "../core/color.js";
+import type { RenderOptions } from "../core/protocol.js";
+import { type DrawnAt } from "./color-funcs.js";
 export { paletteFuncs } from "./palette-funcs.js";
-export { colorFuncs, readableOnFunc } from "./color-funcs.js";
+export { colorFuncs, readableOnFunc, type DrawnAt } from "./color-funcs.js";
 /**
  * Funcs registered by the rich-js binding — the colour sinks, the palette-free
  * colour math, text attributes, and the `link` cell-splitter. Nothing here
@@ -57,7 +58,7 @@ export { colorFuncs, readableOnFunc } from "./color-funcs.js";
  * into a wider engine must keep `T = RichText`; merging into an engine
  * whose `T` is something else will compile but fail at evaluation time.
  */
-export declare function richTextFuncs(drawnAt?: () => ColorDepth): FuncMap;
+export declare function richTextFuncs(drawnAt?: () => DrawnAt): FuncMap;
 /**
  * Construct an `Engine<RichText>` with the rich-js style-function set
  * registered. Consumers that already manage their own engine should call
@@ -71,6 +72,18 @@ export declare function richTextFuncs(drawnAt?: () => ColorDepth): FuncMap;
  * not desired anyway.
  */
 export declare function createRichTextEngine(): Engine<RichText>;
+export interface RenderTemplateOptions extends Partial<RenderOptions> {
+    /**
+     * Defaults to 400 — large enough that downstream `splitLines` /
+     * `adjustLineLength` clipping decides actual width, matching the typical
+     * "render wide, fit on output" pipeline. The error line is fitted to it too,
+     * so only a caller that passes the width it draws at sees a cut error end in
+     * `…` rather than be cropped by whatever draws it.
+     */
+    maxWidth?: number;
+    /** The error line's style, a `Style.parse` spec (default `"red dim"`). */
+    errorStyle?: string;
+}
 /**
  * Compile a template source against `engine` and render the result to a
  * flat `Segment[]`. The 90%-case convenience over chaining `engine.compile`,
@@ -79,14 +92,20 @@ export declare function createRichTextEngine(): Engine<RichText>;
  * - Runs `engine.compile(source)(scope)` to get the engine's `RichText[]`.
  * - Flattens that fragment list into a single styled `RichText` via
  *   `RichText.fromFragments` so every fragment's wrapping style survives.
- * - Renders to a `Segment[]` at the requested `maxWidth`.
- * - Wraps the whole flow in a try/catch — on parse/evaluate failure,
- *   emits a single dim styled `[error: <message>]` segment the caller can
- *   drop into their layout. No bespoke fallback wiring required at every
+ * - Renders to a `Segment[]` with the given render options — `maxWidth`,
+ *   `theme`, `onStyleError` and the rest — as a terminal unless they say not.
+ * - On a parse/evaluate failure, emits a single dim styled
+ *   `[error: <message>]` segment, one line fitted to `maxWidth`, the caller
+ *   can drop into their layout. No bespoke fallback wiring required at every
  *   call site.
  *
+ * Only compile, evaluate and flatten are inside the `try`: the error line reports a
+ * template that failed, nothing else. Whatever the render throws — a style
+ * error an `onStyleError` handler rethrew, or a fault in the render itself —
+ * leaves this function rather than being folded into an `[error: …]` line.
+ *
  * [LAW:single-enforcer] One place owns "render a template to segments,
- * degrade gracefully on errors" — every consumer that wants this exact
+ * degrade gracefully when the template fails" — every consumer that wants this exact
  * shape reads from here rather than re-implementing the same try/catch +
  * error-formatting glue.
  *
@@ -95,13 +114,6 @@ export declare function createRichTextEngine(): Engine<RichText>;
  * and use `RichText.fromFragments` to flatten. This helper is sugar for
  * the live-render case (e.g. a preview pane), not a replacement for the
  * compile-once-evaluate-many pattern.
- *
- * @param maxWidth defaults to 400 — large enough that downstream `splitLines`
- * / `adjustLineLength` clipping decides actual width, matching the typical
- * "render wide, fit on output" pipeline.
- * @param errorStyle is a `Style.parse` spec (default `"red dim"`).
+
  */
-export declare function renderTemplate(engine: Engine<RichText>, source: string, scope?: unknown, options?: {
-    maxWidth?: number;
-    errorStyle?: string;
-}): Segment[];
+export declare function renderTemplate(engine: Engine<RichText>, source: string, scope?: unknown, options?: RenderTemplateOptions): Segment[];

package/dist/template-bindings/index.js

@@ -91,14 +91,20 @@ export function createRichTextEngine() {
  * - Runs `engine.compile(source)(scope)` to get the engine's `RichText[]`.
  * - Flattens that fragment list into a single styled `RichText` via
  *   `RichText.fromFragments` so every fragment's wrapping style survives.
- * - Renders to a `Segment[]` at the requested `maxWidth`.
- * - Wraps the whole flow in a try/catch — on parse/evaluate failure,
- *   emits a single dim styled `[error: <message>]` segment the caller can
- *   drop into their layout. No bespoke fallback wiring required at every
+ * - Renders to a `Segment[]` with the given render options — `maxWidth`,
+ *   `theme`, `onStyleError` and the rest — as a terminal unless they say not.
+ * - On a parse/evaluate failure, emits a single dim styled
+ *   `[error: <message>]` segment, one line fitted to `maxWidth`, the caller
+ *   can drop into their layout. No bespoke fallback wiring required at every
  *   call site.
  *
+ * Only compile, evaluate and flatten are inside the `try`: the error line reports a
+ * template that failed, nothing else. Whatever the render throws — a style
+ * error an `onStyleError` handler rethrew, or a fault in the render itself —
+ * leaves this function rather than being folded into an `[error: …]` line.
+ *
  * [LAW:single-enforcer] One place owns "render a template to segments,
- * degrade gracefully on errors" — every consumer that wants this exact
+ * degrade gracefully when the template fails" — every consumer that wants this exact
  * shape reads from here rather than re-implementing the same try/catch +
  * error-formatting glue.
  *
@@ -107,27 +113,37 @@ export function createRichTextEngine() {
  * and use `RichText.fromFragments` to flatten. This helper is sugar for
  * the live-render case (e.g. a preview pane), not a replacement for the
  * compile-once-evaluate-many pattern.
- *
- * @param maxWidth defaults to 400 — large enough that downstream `splitLines`
- * / `adjustLineLength` clipping decides actual width, matching the typical
- * "render wide, fit on output" pipeline.
- * @param errorStyle is a `Style.parse` spec (default `"red dim"`).
+
  */
 export function renderTemplate(engine, source, scope = {}, options) {
+    const { errorStyle, ...renderOptions } = options ?? {};
+    const maxWidth = renderOptions.maxWidth ?? 400;
+    // Flattening belongs to the template: a scope value the engine passes
+    // through unlifted fails here, and that is a template that failed.
+    let text;
     try {
-        const frags = engine.compile(source)(scope);
-        const rt = RichText.fromFragments(frags);
-        return Array.from(rt.render({
-            maxWidth: options?.maxWidth ?? 400,
-            isTerminal: true,
-        }));
+        text = RichText.fromFragments(engine.compile(source)(scope));
     }
     catch (e) {
-        // An engine error's `message` is its one-line summary; `String(e)` adds a
-        // multi-line code frame, which would break this single segment across lines.
-        const summary = e instanceof Error ? e.message : String(e);
-        return [new Segment(`[error: ${summary.slice(0, 80)}]`, safeErrorStyle(options?.errorStyle))];
+        return [new Segment(errorLine(e, maxWidth), safeErrorStyle(errorStyle))];
     }
+    return Array.from(text.render({ isTerminal: true, ...renderOptions, maxWidth }));
+}
+/**
+ * A caught error as the one line `renderTemplate` promises. The summary is the
+ * error's `message` — `String(e)` on an engine error appends a multi-line code
+ * frame — and even a `message` can carry the character it is complaining about
+ * (`bad escape sequence \⏎`). Any whitespace that is not a plain space — a line
+ * break, or a tab, whose stop depends on the column the line is set at and so
+ * cannot be measured here — folds, with the spaces around it, to one space.
+ *
+ * [LAW:one-source-of-truth] The line fits the same `maxWidth` the success path
+ * draws at, not a width of its own, and a cut ends in an ellipsis so it never
+ * reads as the whole message.
+ */
+function errorLine(e, maxWidth) {
+    const summary = (e instanceof Error ? e.message : String(e)).replace(/\s*[^\S ]\s*/g, " ");
+    return new RichText(`[error: ${summary}]`).truncate(maxWidth).plain;
 }
 // [LAW:single-enforcer] The error-path Style must not itself throw, or
 // the whole "degrade gracefully" promise of renderTemplate is broken. A

package/dist/template-bindings/palette-funcs.d.ts

@@ -67,7 +67,9 @@ import type { Palette } from "../themes/palette.js";
 /**
  * Register `color "name-or-hex"` against a live palette.
  *
- * `color` resolves a palette variable name to a `#RRGGBB` string, and passes
+ * `color` resolves a palette variable name to its hex string — `#RRGGBB`, or
+ * `#00000000` for a theme's "no background", which `bg` paints as no
+ * background and the colour functions refuse — and passes
  * an already-literal color through unchanged. That second half is not a
  * convenience — it makes `color` **idempotent**, which is what lets consumers
  * apply it unconditionally to any author-written color string without first

package/dist/template-bindings/palette-funcs.js

@@ -63,7 +63,9 @@
  * they are gone.
  */
 import { resolveColorRef } from "../themes/colorRef.js";
-import { ColorRamp, parseRampEasing } from "../themes/ramp.js";
+import { parseEase } from "../core/easing.js";
+import { ColorRamp } from "../themes/ramp.js";
+import { computable } from "./color-funcs.js";
 /**
  * The `(position, color-ref)` pairs a `ramp` call's tail spells, as stops.
  *
@@ -85,7 +87,7 @@ function colorStops(tail, palette) {
     for (let i = 0; i < tail.length; i += 2) {
         stops.push({
             at: tail[i],
-            color: resolveColorRef(palette, tail[i + 1]),
+            color: computable(resolveColorRef(palette, tail[i + 1]), "ramp", JSON.stringify(tail[i + 1])),
         });
     }
     return stops;
@@ -93,7 +95,9 @@ function colorStops(tail, palette) {
 /**
  * Register `color "name-or-hex"` against a live palette.
  *
- * `color` resolves a palette variable name to a `#RRGGBB` string, and passes
+ * `color` resolves a palette variable name to its hex string — `#RRGGBB`, or
+ * `#00000000` for a theme's "no background", which `bg` paints as no
+ * background and the colour functions refuse — and passes
  * an already-literal color through unchanged. That second half is not a
  * convenience — it makes `color` **idempotent**, which is what lets consumers
  * apply it unconditionally to any author-written color string without first
@@ -124,14 +128,14 @@ export function paletteFuncs(getPalette) {
         arity: { kind: "exact" },
         returnType: "string",
     };
-    // `ramp <value> <easing> <position> <color> …` — the argument list is one
-    // float/string cycle end to end (value, easing, then each stop's position
+    // `ramp <value> <ease> <position> <color> …` — the argument list is one
+    // float/string cycle end to end (value, ease, then each stop's position
     // and color), so the engine's `alternating` gate types every slot; the
     // pairing and the references are parsed in `colorStops`. Its minimum is the
-    // value, the easing, and one stop, so the gate refuses a stopless call.
+    // value, the ease, and one stop, so the gate refuses a stopless call.
     // [LAW:types-are-the-program]
     const rampFunc = {
-        fn: ((value, easing, ...tail) => new ColorRamp(parseRampEasing(easing), colorStops(tail, getPalette())).at(value)
+        fn: ((value, ease, ...tail) => new ColorRamp(parseEase(ease), colorStops(tail, getPalette())).at(value)
             .hex),
         argTypes: ["float", "string"],
         arity: { kind: "alternating", minimum: 4 },

package/dist/template-bindings/style-funcs.js

@@ -113,11 +113,13 @@ const styleSpecFunc = {
 // `link` is the cell-splitter for the multi-cell consumer contract.
 // Implementation-wise it is the same shape as any other style function:
 // it sets the `link` slot of `Style` exactly as the existing string-form
-// `link URL` does, so a template-built fragment is byte-equivalent to
+// `link URL` does, so `{{ link "u" "x" }}` is byte-equivalent to
 // `RichText("x", { style: Style.parse("link u") })`.
 //
 // The cell-boundary signal that consumers (cc-candybar et al.) walk is
-// `fragment.style.link` being truthy. `Style.add` propagates `link`
+// `theme.resolve(fragment.style).link` being truthy: a fragment whose base
+// style is a string keeps the link in a `LayeredStyle` until a theme says
+// what the string stands for. `Style.add` propagates `link`
 // through any outer wrapping call, so `{{ fg "red" (link "u" "x") }}` and
 // `{{ link "u" "x" }}` produce shapes that both qualify as cells from
 // the consumer's perspective. Outer-wins on nested links comes for free

package/dist/themes/buildPalette.d.ts

@@ -14,6 +14,8 @@ export interface BaseColors {
     background: ColorRgba;
     foreground: ColorRgba;
 }
+type AccentKey = "primary" | "secondary" | "accent" | "success" | "warning" | "error";
+export declare const ACCENT_KEYS: readonly AccentKey[];
 /**
  * Build a full semantic palette from base colors.
  *
@@ -25,12 +27,31 @@ export interface BaseColors {
  *              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 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.
  */
-export declare function buildPalette(name: string, dark: boolean, base: BaseColors): Palette;
+export declare function accentText(tint: ColorRgba, muted: ColorRgba, background: ColorRgba): ColorRgba;
+export {};

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;