@promptctl/rich-js 0.18.1 → 0.19.0

package/dist/themes/colorMath.js

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

package/dist/themes/colorRef.d.ts

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

package/dist/themes/colorRef.js

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

package/dist/themes/palette.d.ts

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

package/dist/themes/palette.js

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

package/dist/themes/ramp.d.ts

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

package/dist/themes/ramp.js

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