@promptctl/rich-js 0.18.0 → 0.18.1

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

@@ -0,0 +1,94 @@
+/**
+ * The palette-dependent template functions: `color`, and `ramp` whose stops
+ * are color references.
+ *
+ * ### Why `color` is the one name resolver
+ *
+ * This module used to register four kinds of thing: one function per
+ * identifier-safe palette variable (`{{ primary child }}`, `{{ accent child }}`,
+ * …), a general `palette "spec" child`, a `paletteOver "spec" "#bg" child` for
+ * specs needing a background, and an `auto "#bg" child` sugar. That surface had
+ * two defects worth recording, because both are easy to reintroduce.
+ *
+ * **The name family could not cover its own domain.** A themed palette carries
+ * ~150 variables; roughly 14 of them are legal Go-template identifiers. So the
+ * generated functions reached under a tenth of the palette, and the other nine
+ * tenths needed `palette "text-primary" child` — a *different expression shape*
+ * for the same intent. An author who learned `{{ primary x }}` and reasonably
+ * tried `{{ text_primary x }}` got a FuncNotFound. [LAW:composability] — the
+ * `filterByStatus`/`filterByOwner` shape: names cannot enumerate a domain, and
+ * the N+1 case always needs a form you have to learn separately.
+ *
+ * **Resolution and application were fused.** Every one of those functions
+ * consumed its color instantly into a styled fragment, so a color could never
+ * be held or passed. Composition therefore had to happen inside the spec
+ * *string* — hence the old `name-darken-N alpha%` grammar. See
+ * `color-funcs.ts` for the full argument; the short version is that a string
+ * grammar is function application with the function calls spelled as
+ * punctuation, and it grows a new production for every operation.
+ *
+ * What replaces all of it: `color "name-or-hex"` produces a color value, the
+ * functions in `color-funcs.ts` transform colors, and `fg`/`bg` in
+ * `style-funcs.ts` paint them. One shape, total over the palette, open to
+ * arbitrary composition. [LAW:one-type-per-behavior]
+ *
+ * ### Why `ramp` lives here and not with the color math
+ *
+ * `ramp` is the one function whose input is a *number*, and its stops are
+ * spelled as color references — `ramp .pct "step" 0 "panel" 50 "warning" 80
+ * "error"` — resolved through the same `resolveColorRef` that `color` crosses.
+ * Requiring `(color "panel")` around every stop would put the boilerplate
+ * back that this binding exists to remove, and an author who writes a hex
+ * literal loses nothing: the resolver is idempotent on hex. The arithmetic
+ * itself is `ColorRamp` in `themes/ramp.ts`, palette-free; only the
+ * reference resolution is here. [LAW:one-way-deps]
+ *
+ * ### Why a getter, not a palette
+ *
+ * `paletteFuncs` takes `() => Palette` rather than a `Palette`. A consumer
+ * whose theme can change at runtime (a live preview, a theme picker, a
+ * status-line that recolors on click) would otherwise be frozen to whichever
+ * palette happened to be current when the engine was constructed — and since
+ * templates are parsed once and evaluated many times, that freeze outlives
+ * every subsequent theme change while the *rest* of the consumer's colors move
+ * on. Two palettes, one render: [LAW:one-source-of-truth] violated by a
+ * captured reference.
+ *
+ * The getter costs nothing structurally. `FuncMap` entries are data in the
+ * engine and their bodies run at *evaluate* time, so reading the palette
+ * through a getter leaves parse-once/evaluate-many completely intact. What the
+ * getter must not change is *which functions exist* — and it cannot, because
+ * the two names here do not depend on the palette's contents. That was not
+ * true of the generated per-variable functions, which is the second reason
+ * they are gone.
+ */
+import type { FuncMap } from "@promptctl/go-template-js";
+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
+ * 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
+ * asking whether it is a name or already a color. [LAW:dataflow-not-control-flow]
+ *
+ * An unknown name throws, carrying near-miss suggestions from the live
+ * palette. In a template that surfaces as an evaluation error at the exact
+ * call site, which is the signal an author (or an agent editing a config) needs
+ * to fix it. [LAW:no-silent-failure]
+ *
+ * @example
+ * ```ts
+ * const engine = createEngine({
+ *   fromString: (s) => new RichText(s),
+ *   toString: (rt) => rt.plain,
+ *   funcs: {
+ *     ...richTextFuncs(),
+ *     ...colorFuncs(),
+ *     ...paletteFuncs(() => currentTheme.palette),
+ *   },
+ * });
+ * ```
+ */
+export declare function paletteFuncs(getPalette: () => Palette): FuncMap;

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

@@ -0,0 +1,141 @@
+/**
+ * The palette-dependent template functions: `color`, and `ramp` whose stops
+ * are color references.
+ *
+ * ### Why `color` is the one name resolver
+ *
+ * This module used to register four kinds of thing: one function per
+ * identifier-safe palette variable (`{{ primary child }}`, `{{ accent child }}`,
+ * …), a general `palette "spec" child`, a `paletteOver "spec" "#bg" child` for
+ * specs needing a background, and an `auto "#bg" child` sugar. That surface had
+ * two defects worth recording, because both are easy to reintroduce.
+ *
+ * **The name family could not cover its own domain.** A themed palette carries
+ * ~150 variables; roughly 14 of them are legal Go-template identifiers. So the
+ * generated functions reached under a tenth of the palette, and the other nine
+ * tenths needed `palette "text-primary" child` — a *different expression shape*
+ * for the same intent. An author who learned `{{ primary x }}` and reasonably
+ * tried `{{ text_primary x }}` got a FuncNotFound. [LAW:composability] — the
+ * `filterByStatus`/`filterByOwner` shape: names cannot enumerate a domain, and
+ * the N+1 case always needs a form you have to learn separately.
+ *
+ * **Resolution and application were fused.** Every one of those functions
+ * consumed its color instantly into a styled fragment, so a color could never
+ * be held or passed. Composition therefore had to happen inside the spec
+ * *string* — hence the old `name-darken-N alpha%` grammar. See
+ * `color-funcs.ts` for the full argument; the short version is that a string
+ * grammar is function application with the function calls spelled as
+ * punctuation, and it grows a new production for every operation.
+ *
+ * What replaces all of it: `color "name-or-hex"` produces a color value, the
+ * functions in `color-funcs.ts` transform colors, and `fg`/`bg` in
+ * `style-funcs.ts` paint them. One shape, total over the palette, open to
+ * arbitrary composition. [LAW:one-type-per-behavior]
+ *
+ * ### Why `ramp` lives here and not with the color math
+ *
+ * `ramp` is the one function whose input is a *number*, and its stops are
+ * spelled as color references — `ramp .pct "step" 0 "panel" 50 "warning" 80
+ * "error"` — resolved through the same `resolveColorRef` that `color` crosses.
+ * Requiring `(color "panel")` around every stop would put the boilerplate
+ * back that this binding exists to remove, and an author who writes a hex
+ * literal loses nothing: the resolver is idempotent on hex. The arithmetic
+ * itself is `ColorRamp` in `themes/ramp.ts`, palette-free; only the
+ * reference resolution is here. [LAW:one-way-deps]
+ *
+ * ### Why a getter, not a palette
+ *
+ * `paletteFuncs` takes `() => Palette` rather than a `Palette`. A consumer
+ * whose theme can change at runtime (a live preview, a theme picker, a
+ * status-line that recolors on click) would otherwise be frozen to whichever
+ * palette happened to be current when the engine was constructed — and since
+ * templates are parsed once and evaluated many times, that freeze outlives
+ * every subsequent theme change while the *rest* of the consumer's colors move
+ * on. Two palettes, one render: [LAW:one-source-of-truth] violated by a
+ * captured reference.
+ *
+ * The getter costs nothing structurally. `FuncMap` entries are data in the
+ * engine and their bodies run at *evaluate* time, so reading the palette
+ * through a getter leaves parse-once/evaluate-many completely intact. What the
+ * getter must not change is *which functions exist* — and it cannot, because
+ * the two names here do not depend on the palette's contents. That was not
+ * true of the generated per-variable functions, which is the second reason
+ * they are gone.
+ */
+import { resolveColorRef } from "../themes/colorRef.js";
+import { ColorRamp, parseRampEasing } from "../themes/ramp.js";
+/**
+ * The `(position, color-ref)` pairs a `ramp` call's tail spells, as stops.
+ *
+ * The engine's `alternating` gate has already typed every even slot as a
+ * float and every odd slot as a string; what it cannot see is the *pairing*
+ * — a trailing position with no color — nor that the string is a color
+ * reference. Both are settled here, once, and `ColorRamp` receives resolved
+ * stops it never re-checks. [LAW:parse-dont-validate]
+ *
+ * Each reference resolves against the palette of *this* evaluation, so a
+ * ramp over palette names follows the theme exactly as `color` does.
+ */
+function colorStops(tail, palette) {
+    if (tail.length % 2 !== 0) {
+        throw new RangeError(`ramp's last stop (position ${String(tail[tail.length - 1])}) has no color — ` +
+            `stops are <position> <color> pairs`);
+    }
+    const stops = [];
+    for (let i = 0; i < tail.length; i += 2) {
+        stops.push({
+            at: tail[i],
+            color: resolveColorRef(palette, tail[i + 1]),
+        });
+    }
+    return stops;
+}
+/**
+ * Register `color "name-or-hex"` against a live palette.
+ *
+ * `color` resolves a palette variable name to a `#RRGGBB` string, 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
+ * asking whether it is a name or already a color. [LAW:dataflow-not-control-flow]
+ *
+ * An unknown name throws, carrying near-miss suggestions from the live
+ * palette. In a template that surfaces as an evaluation error at the exact
+ * call site, which is the signal an author (or an agent editing a config) needs
+ * to fix it. [LAW:no-silent-failure]
+ *
+ * @example
+ * ```ts
+ * const engine = createEngine({
+ *   fromString: (s) => new RichText(s),
+ *   toString: (rt) => rt.plain,
+ *   funcs: {
+ *     ...richTextFuncs(),
+ *     ...colorFuncs(),
+ *     ...paletteFuncs(() => currentTheme.palette),
+ *   },
+ * });
+ * ```
+ */
+export function paletteFuncs(getPalette) {
+    const colorFunc = {
+        fn: ((ref) => resolveColorRef(getPalette(), ref).hex),
+        argTypes: ["string"],
+        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
+    // 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.
+    // [LAW:types-are-the-program]
+    const rampFunc = {
+        fn: ((value, easing, ...tail) => new ColorRamp(parseRampEasing(easing), colorStops(tail, getPalette())).at(value)
+            .hex),
+        argTypes: ["float", "string"],
+        arity: { kind: "alternating", minimum: 4 },
+        returnType: "string",
+    };
+    return { color: colorFunc, ramp: rampFunc };
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Style-function registrations for the rich-js template binding.
+ *
+ * [LAW:one-source-of-truth] The function inventory below mirrors the
+ * string-syntax style vocabulary documented in `docs/style.md` — the two
+ * colour slots (`fg`/`bg`), text attributes (positive + negated), short
+ * aliases, and the hyperlink. Each registration is a templating-time analogue
+ * of a piece of `Style.parse`, so a template fragment composed by these
+ * functions round-trips through `Style` without semantic drift.
+ *
+ * [LAW:dataflow-not-control-flow] Every function follows the same
+ * shape: child `RichText` in, `RichText` out. The styling difference
+ * lives in a captured `Style` value (or constructor closure), not in
+ * branches inside a single dispatch. That is why this file is mostly
+ * factories — the data (the colour, the attribute name) is the
+ * variability; the operation is fixed.
+ */
+import type { FuncMap } from "@promptctl/go-template-js";
+/**
+ * Text-styling registrations: the two colour sinks (`fg`, `bg`), text
+ * attributes (canonical names, short aliases, and `not_*` negations), the
+ * hyperlink cell-splitter (`link`), and the multi-attribute `style` spec.
+ *
+ * Colours themselves come from elsewhere: `colorFuncs()` for the palette-free
+ * math, `paletteFuncs()` for naming a theme colour. This module only paints.
+ * [LAW:one-way-deps] — nothing here imports a palette.
+ */
+export declare function richTextStyleFuncs(): FuncMap;

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

@@ -0,0 +1,155 @@
+/**
+ * Style-function registrations for the rich-js template binding.
+ *
+ * [LAW:one-source-of-truth] The function inventory below mirrors the
+ * string-syntax style vocabulary documented in `docs/style.md` — the two
+ * colour slots (`fg`/`bg`), text attributes (positive + negated), short
+ * aliases, and the hyperlink. Each registration is a templating-time analogue
+ * of a piece of `Style.parse`, so a template fragment composed by these
+ * functions round-trips through `Style` without semantic drift.
+ *
+ * [LAW:dataflow-not-control-flow] Every function follows the same
+ * shape: child `RichText` in, `RichText` out. The styling difference
+ * lives in a captured `Style` value (or constructor closure), not in
+ * branches inside a single dispatch. That is why this file is mostly
+ * factories — the data (the colour, the attribute name) is the
+ * variability; the operation is fixed.
+ */
+import { Style, ATTRIBUTE_NAMES, ATTRIBUTE_SHORT_ALIASES, } from "../core/style.js";
+import { ColorSpec } from "../core/color.js";
+import { applyStyleToFragment } from "./helpers.js";
+function attrFunc(style) {
+    return {
+        fn: ((child) => applyStyleToFragment(child, style)),
+        argTypes: ["liftable"],
+        arity: { kind: "exact" },
+        returnType: "T",
+    };
+}
+// --- Colour sinks ---
+//
+// `fg` and `bg` are the only two colour-applying functions, and they are the
+// terminal step of the colour pipeline: `color` names a colour, the functions
+// in `color-funcs.ts` transform it, these paint it onto text.
+//
+// [LAW:composability] They replace five separate families — one function per
+// ANSI colour name (`red`, `bright_blue`, …), `hex`, `rgb`, `color` (256-index),
+// and `on` (background). Every one of those encoded *which colour* in the
+// function's identity, so the vocabulary could only grow by adding names, and
+// a colour computed at render time could not be applied at all. Here the colour
+// is an argument, so the sink admits every colour that exists and every colour
+// that will ever exist. Two functions, unbounded reach.
+//
+// [LAW:types-are-the-program] The slot accepts the full `ColorSpec.parse`
+// vocabulary, which is wider than the hex the colour math produces — and that
+// width is deliberate, not laxity. `#7aa2f7` is a *concrete* colour; `"red"`
+// and `"color(42)"` are *symbolic* ones the terminal resolves against its own
+// theme. Only concrete colours can be darkened or blended, which is why the
+// colour-math functions take hex alone; but both kinds can be painted, so the
+// sink takes the union. The type of each slot is exactly the set of values that
+// slot can mean something for.
+function colorSinkFunc(slot) {
+    return {
+        fn: ((spec, child) => applyStyleToFragment(child, new Style({ [slot]: ColorSpec.parse(spec) }))),
+        argTypes: ["string", "liftable"],
+        arity: { kind: "exact" },
+        returnType: "T",
+    };
+}
+// --- Text attributes ---
+//
+// [LAW:one-source-of-truth] The attribute and short-alias inventories
+// come from `core/style.ts`. This file derives the template registration
+// set from the same data `Style.parse` consults — adding an attribute or
+// alias in one place propagates here automatically.
+function attrStyle(name, value) {
+    return new Style({ [name]: value });
+}
+function attributeFuncs() {
+    const out = {};
+    for (const name of ATTRIBUTE_NAMES) {
+        out[name] = attrFunc(attrStyle(name, true));
+        out[`not_${name}`] = attrFunc(attrStyle(name, false));
+    }
+    for (const [alias, canonical] of Object.entries(ATTRIBUTE_SHORT_ALIASES)) {
+        out[alias] = attrFunc(attrStyle(canonical, true));
+    }
+    return out;
+}
+// --- Style spec (multi-attribute one-shot) ---
+//
+// [LAW:one-source-of-truth] `style` accepts the same space-separated grammar
+// `Style.parse` consults — i.e. the inside of `[...]` markup. There is no
+// second parser: a spec that `Style.parse` accepts produces a fragment
+// byte-equivalent to the same spec inside markup, and one that `Style.parse`
+// rejects raises the same `StyleSyntaxError` surface.
+//
+// Motivation: the per-attribute functions (`bold`, `underline`, `fg`, …)
+// compose by nesting. For "apply a fixed set of styles to this child" or
+// "apply this named style set everywhere", nesting is awkward and the
+// style description is fragmented across multiple call sites. `style`
+// collapses that to a single call, and because the spec is a string it
+// flows through Go-template `$vars` and through scope without further
+// machinery:
+//
+//   {{ $alert := "bold underline #ff6b6b" }}
+//   {{ style $alert "alarm!" }}
+//   {{ style $alert .otherField }}
+//
+// [LAW:dataflow-not-control-flow] Same shape as every other style function:
+// a `Style` value (here built by `Style.parse(spec)`) plus a child, in,
+// styled child out. The variability is the spec string; the operation is
+// fixed.
+const styleSpecFunc = {
+    fn: ((spec, child) => {
+        return applyStyleToFragment(child, Style.parse(spec));
+    }),
+    argTypes: ["string", "liftable"],
+    arity: { kind: "exact" },
+    returnType: "T",
+};
+// --- Hyperlink ---
+//
+// `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
+// `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`
+// 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
+// from `Style.add`'s right-wins-on-conflict rule.
+//
+// [LAW:dataflow-not-control-flow] No special-case AST node, no
+// `LinkFragment` subclass, no second emitter path — the variability is
+// the value of `style.link`, not whether some control-flow branch ran.
+const linkFunc = {
+    fn: ((url, child) => {
+        return applyStyleToFragment(child, new Style({ link: url }));
+    }),
+    argTypes: ["string", "liftable"],
+    arity: { kind: "exact" },
+    returnType: "T",
+};
+// --- Public assembly ---
+/**
+ * Text-styling registrations: the two colour sinks (`fg`, `bg`), text
+ * attributes (canonical names, short aliases, and `not_*` negations), the
+ * hyperlink cell-splitter (`link`), and the multi-attribute `style` spec.
+ *
+ * Colours themselves come from elsewhere: `colorFuncs()` for the palette-free
+ * math, `paletteFuncs()` for naming a theme colour. This module only paints.
+ * [LAW:one-way-deps] — nothing here imports a palette.
+ */
+export function richTextStyleFuncs() {
+    return {
+        fg: colorSinkFunc("color"),
+        bg: colorSinkFunc("bgcolor"),
+        ...attributeFuncs(),
+        link: linkFunc,
+        style: styleSpecFunc,
+    };
+}

package/dist/themes/buildPalette.d.ts

@@ -0,0 +1,36 @@
+import { ColorRgba } from "../core/color.js";
+import { Palette } from "./palette.js";
+/**
+ * Base colors required to build a full semantic palette.
+ * All are ColorRgba — callers construct from whatever source (hex, HSL, etc.).
+ */
+export interface BaseColors {
+    primary: ColorRgba;
+    secondary: ColorRgba;
+    accent: ColorRgba;
+    success: ColorRgba;
+    warning: ColorRgba;
+    error: ColorRgba;
+    background: ColorRgba;
+    foreground: ColorRgba;
+}
+/**
+ * Build a full semantic palette from base colors.
+ *
+ * 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 (use as
+ *              foreground in muted/background-tinted contexts)
+ * - `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
+ */
+export declare function buildPalette(name: string, dark: boolean, base: BaseColors): Palette;

package/dist/themes/buildPalette.js

@@ -0,0 +1,56 @@
+import { blendRgb } from "../core/color.js";
+import { alphaBlend, contrastFor } from "./colorMath.js";
+import { Palette } 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"];
+/**
+ * Build a full semantic palette from base colors.
+ *
+ * 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 (use as
+ *              foreground in muted/background-tinted contexts)
+ * - `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
+ */
+export function buildPalette(name, dark, base) {
+    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];
+        vars.set(`${key}-muted`, blendRgb(color, base.background, MUTED_BLEND));
+        vars.set(`text-${key}`, alphaBlend(color, contrastText, TEXT_ALPHA));
+        vars.set(`on-${key}`, contrastFor(color));
+    }
+    return new Palette(name, dark, vars);
+}

package/dist/themes/colorMath.d.ts

@@ -0,0 +1,82 @@
+import { ColorDepth, ColorRgba, contrastRatio, relativeLuminance } 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
+ * RGB↔HSL roundtrip; values may differ by ±1 due to rounding).
+ */
+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;
+/**
+ * Composite `fg` over `bg` with the given alpha (0..1). At alpha=0 returns bg;
+ * at alpha=1 returns fg.
+ */
+export declare function alphaBlend(fg: ColorRgba, bg: ColorRgba, alpha: number): ColorRgba;
+/**
+ * Pick a contrasting foreground (black or white) for a background, using the
+ * WCAG relative-luminance threshold of 0.179 (the perceptually correct cutoff
+ * where black and white are equally readable). A translucent `bg` is judged
+ * as drawn: composited over `substrate` (see `drawnBackground`).
+ */
+export declare function contrastFor(bg: ColorRgba, substrate?: ColorRgba): ColorRgba;
+export { relativeLuminance, contrastRatio };
+/**
+ * Return a foreground guaranteed to clear `minRatio` against `bg`, keeping the
+ * color *recognizably itself*. If the themed `fg` already passes it is returned
+ * untouched. Otherwise its OKLCH lightness is slid toward the pole that raises
+ * contrast — holding hue, and chroma where it stays in gamut (near the poles
+ * gamut clamping may reduce chroma, but hue is preserved) — until the ratio is
+ * met, so a blue on a dark-blue background becomes a lighter blue, not white.
+ * Only when no lightness of that hue can meet the ratio (a mid-toned
+ * background where even pure black-or-white tops out below the target) does it
+ * fall back to `contrastFor`'s black/white — the true maximum-contrast pick.
+ *
+ * A translucent `bg` is measured as it is drawn — composited over
+ * `substrate`, the SGR writer's black by default — and a translucent `fg` is
+ * then flattened over that drawn background, the order the writer composites
+ * in, so the ratio is measured on what the eye actually sees and the returned
+ * color is opaque.
+ *
+ * `drawnAt` is the depth the terminal will draw the pair at. At 256 colours
+ * the terminal rounds text and background independently, and two roundings
+ * 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.
+ *
+ * [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
+ * unreadable state never reaches output. [LAW:dataflow-not-control-flow] the
+ * function always runs; the measured ratio (data) decides how far the
+ * 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;
+/**
+ * `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
+ * draws from no table, so a colour refused there has no replacement;
+ * `undefined` means nothing the depth draws is accepted.
+ *
+ * `ensureContrast` is this with a contrast ratio as the floor; this is for a
+ * 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;
+/**
+ * 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.
+ */
+export declare function drawnColour(colour: ColorRgba, drawnAt: ColorDepth, substrate?: ColorRgba): ColorRgba;