@promptctl/rich-js 0.16.0 → 0.18.0

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

@@ -1,151 +0,0 @@
-/**
- * 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"],
-        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"],
-        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"],
-    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"],
-    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

@@ -1,36 +0,0 @@
-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

@@ -1,56 +0,0 @@
-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

@@ -1,82 +0,0 @@
-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;

package/dist/themes/colorMath.js

@@ -1,254 +0,0 @@
-import { ColorDepth, ColorRgba, EIGHT_BIT_DOWNGRADE_TABLE, STANDARD_TABLE, blendRgb, contrastRatio, relativeLuminance, SURFACE_BLACK, } from "../core/color.js";
-import { Oklch } from "../core/oklch.js";
-const LEVEL_STEP = 0.1;
-function rgbToHsl(c) {
-    const r = c.red / 255;
-    const g = c.green / 255;
-    const b = c.blue / 255;
-    const max = Math.max(r, g, b);
-    const min = Math.min(r, g, b);
-    const l = (max + min) / 2;
-    const d = max - min;
-    if (d === 0)
-        return { h: 0, s: 0, l };
-    const s = d / (l > 0.5 ? 2 - max - min : max + min);
-    let h;
-    if (max === r)
-        h = ((g - b) / d) % 6;
-    else if (max === g)
-        h = (b - r) / d + 2;
-    else
-        h = (r - g) / d + 4;
-    h = (h * 60 + 360) % 360;
-    return { h, s, l };
-}
-function clampChannel(v) {
-    // Float HSL math + Math.round can land at -1 or 256 at the boundaries; clamp
-    // so an invalid ColorRgba never escapes this function.
-    const r = Math.round(v);
-    return r < 0 ? 0 : r > 255 ? 255 : r;
-}
-function hslToRgb(hsl) {
-    const { h, s, l } = hsl;
-    if (s === 0) {
-        const v = clampChannel(l * 255);
-        return new ColorRgba(v, v, v);
-    }
-    const c = (1 - Math.abs(2 * l - 1)) * s;
-    const hp = h / 60;
-    const x = c * (1 - Math.abs((hp % 2) - 1));
-    let r = 0, g = 0, b = 0;
-    if (hp < 1)
-        [r, g, b] = [c, x, 0];
-    else if (hp < 2)
-        [r, g, b] = [x, c, 0];
-    else if (hp < 3)
-        [r, g, b] = [0, c, x];
-    else if (hp < 4)
-        [r, g, b] = [0, x, c];
-    else if (hp < 5)
-        [r, g, b] = [x, 0, c];
-    else
-        [r, g, b] = [c, 0, x];
-    const m = l - c / 2;
-    return new ColorRgba(clampChannel((r + m) * 255), clampChannel((g + m) * 255), clampChannel((b + m) * 255));
-}
-function clamp01(v) {
-    return v < 0 ? 0 : v > 1 ? 1 : v;
-}
-/**
- * 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 function darken(color, levels) {
-    const hsl = rgbToHsl(color);
-    hsl.l = clamp01(hsl.l - LEVEL_STEP * levels);
-    return hslToRgb(hsl);
-}
-/**
- * Lighten a color by N levels. Equivalent to `darken(color, -levels)`.
- */
-export function lighten(color, levels) {
-    return darken(color, -levels);
-}
-/**
- * Composite `fg` over `bg` with the given alpha (0..1). At alpha=0 returns bg;
- * at alpha=1 returns fg.
- */
-export function alphaBlend(fg, bg, alpha) {
-    return blendRgb(bg, fg, clamp01(alpha));
-}
-/**
- * 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 function contrastFor(bg, substrate = SURFACE_BLACK) {
-    const lum = relativeLuminance(drawnBackground(bg, substrate));
-    return lum > 0.179
-        ? new ColorRgba(0, 0, 0)
-        : new ColorRgba(255, 255, 255);
-}
-// [LAW:one-way-deps] The WCAG measures live in core/color.ts, beside the
-// ColorTable whose `matchReadable` needs them to pick a drawn text colour, and
-// below the theme math here. Re-exported so this module stays the colour-math
-// surface.
-export { relativeLuminance, contrastRatio };
-// Iterations for the lightness bisection below. 20 resolves L to ~1e-6 — far
-// finer than 8-bit quantization or the eye.
-const CONTRAST_ITERS = 20;
-/**
- * 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 function ensureContrast(fg, bg, minRatio = 4.5, // WCAG AA for normal text
-drawnAt = ColorDepth.TRUECOLOR, substrate = SURFACE_BLACK) {
-    const ground = drawnBackground(bg, substrate);
-    const chosen = ensureTruecolorContrast(fg, ground, minRatio);
-    // [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];
-    if (table === undefined)
-        return chosen;
-    const drawnBg = drawnColour(ground, drawnAt, substrate);
-    if (contrastRatio(drawnColour(chosen, drawnAt, substrate), drawnBg) >= minRatio)
-        return chosen;
-    return table.get(table.matchReadable(chosen, drawnBg, 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
- * 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 function ensureDrawn(chosen, drawnAt, accept, substrate = SURFACE_BLACK) {
-    // 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);
-    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);
-}
-/**
- * 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 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));
-}
-/**
- * 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.
- * [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.
- * [LAW:one-source-of-truth] Text is chosen against the colour the surface will
- * show — measuring the raw RGBA reads a colour that is drawn nowhere, and text
- * that "clears" it can land below the floor. Opaque colours composite to
- * themselves.
- */
-function drawnBackground(bg, substrate) {
-    if (substrate.alpha !== 1) {
-        throw new RangeError(`a contrast substrate is the opaque surface under a translucent background; got ${substrate.hex}`);
-    }
-    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.
- */
-const DRAWN_FROM = {
-    [ColorDepth.EIGHT_BIT]: EIGHT_BIT_DOWNGRADE_TABLE,
-    [ColorDepth.STANDARD]: STANDARD_TABLE,
-};
-function ensureTruecolorContrast(fg, bg, minRatio) {
-    // Flatten translucency so the guarantee holds for the displayed color, not
-    // the raw bytes (e.g. a "#FFFFFF60" text-disabled 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;
-    // 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
-    // contrastFor is at least as strong and is the honest maximum.
-    const pole = new Oklch(poleL, lab.c, lab.h, lab.alpha).toRgba();
-    if (contrastRatio(pole, bg) < minRatio)
-        return contrastFor(bg);
-    // Bisect for the lightness nearest the original that still clears the ratio:
-    // the smallest perceptual change that achieves accessibility. Contrast is
-    // monotone in L over [lab.l, poleL] (everything below the crossing fails),
-    // so the search is well-posed.
-    let fail = lab.l;
-    let pass = poleL;
-    for (let i = 0; i < CONTRAST_ITERS; i++) {
-        const mid = (fail + pass) / 2;
-        const candidate = new Oklch(mid, lab.c, lab.h, lab.alpha).toRgba();
-        if (contrastRatio(candidate, bg) >= minRatio)
-            pass = mid;
-        else
-            fail = mid;
-    }
-    return new Oklch(pass, lab.c, lab.h, lab.alpha).toRgba();
-}

package/dist/themes/colorRef.d.ts

@@ -1,51 +0,0 @@
-import { 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
- * concrete color: a palette variable name (`"primary"`, `"surface-active"`,
- * `"text-primary"`) or a literal `#RRGGBB` / `#RRGGBBAA`.
- *
- * [LAW:parse-dont-validate] `resolveColorRef` is the single checkpoint that
- * turns an untrusted reference string into a `ColorRgba`. Everything
- * downstream — color math, `Style` construction, serialization — takes
- * `ColorRgba` and therefore cannot ask again whether the name existed. There
- * is no `isValidColorRef` companion, deliberately: a validator would hand back
- * the same `string` it was given and every consumer would re-check.
- *
- * [LAW:no-silent-failure] A miss throws. An unknown palette name is a broken
- * config, and the author needs to see which name and what was available — not
- * a silently substituted default that makes the bar merely look wrong.
- */
-export declare class ColorRefError extends Error {
-    readonly ref: string;
-    constructor(ref: string, detail: string);
-}
-/**
- * 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`.
- *
- * Accepting hex alongside names is what makes this **idempotent**:
- * `resolveColorRef(p, resolveColorRef(p, r).hex)` equals
- * `resolveColorRef(p, r)` for every `r` this function accepts. Callers
- * therefore never branch on "is this a palette name or already a color" —
- * they call it unconditionally on whatever the author wrote, whether that is
- * `"surface-active"` or the output of a chain of color math.
- * [LAW:dataflow-not-control-flow]
- *
- * @throws {ColorRefError} on malformed hex or an unknown palette name.
- */
-export declare function resolveColorRef(palette: Palette, ref: string): ColorRgba;