@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/themes/data/tokyo-night.js

@@ -0,0 +1,177 @@
+const theme = {
+    name: "tokyo-night",
+    dark: true,
+    // iTerm2-Color-Schemes "TokyoNight Night"
+    ansi: {
+        black: "#15161E",
+        red: "#F7768E",
+        green: "#9ECE6A",
+        yellow: "#E0AF68",
+        blue: "#7AA2F7",
+        magenta: "#BB9AF7",
+        cyan: "#7DCFFF",
+        white: "#A9B1D6",
+        brightBlack: "#414868",
+        brightRed: "#F7768E",
+        brightGreen: "#9ECE6A",
+        brightYellow: "#E0AF68",
+        brightBlue: "#7AA2F7",
+        brightMagenta: "#BB9AF7",
+        brightCyan: "#7DCFFF",
+        brightWhite: "#C0CAF5",
+    },
+    vars: {
+        "accent": "#FE9E64",
+        "accent-darken-1": "#E78A51",
+        "accent-darken-2": "#D0763E",
+        "accent-darken-3": "#BA632C",
+        "accent-lighten-1": "#FFB277",
+        "accent-lighten-2": "#FFC78A",
+        "accent-lighten-3": "#FFDC9E",
+        "accent-muted": "#5E4238",
+        "background": "#1A1B26",
+        "background-darken-1": "#070817",
+        "background-darken-2": "#000000",
+        "background-darken-3": "#000000",
+        "background-lighten-1": "#292A36",
+        "background-lighten-2": "#3A3A47",
+        "background-lighten-3": "#4B4B58",
+        "block-cursor-background": "#BB9AF7",
+        "block-cursor-blurred-background": "#BB9AF74C",
+        "block-cursor-blurred-foreground": "#A9B1D6",
+        "block-cursor-foreground": "#FFFFFFDD",
+        "block-hover-background": "#FFFFFF19",
+        "boost": "#FFFFFF0A",
+        "boost-darken-1": "#E9E9E90A",
+        "boost-darken-2": "#D4D4D40A",
+        "boost-darken-3": "#BFBFBF0A",
+        "boost-lighten-1": "#FFFFFF0A",
+        "boost-lighten-2": "#FFFFFF0A",
+        "boost-lighten-3": "#FFFFFF0A",
+        "border": "#BB9AF7",
+        "border-blurred": "#1E2235",
+        "button-color-foreground": "#24283B",
+        "button-foreground": "#A9B1D6",
+        "error": "#F6768E",
+        "error-darken-1": "#E0617A",
+        "error-darken-2": "#C94D68",
+        "error-darken-3": "#B33856",
+        "error-lighten-1": "#FF8AA1",
+        "error-lighten-2": "#FF9FB5",
+        "error-lighten-3": "#FFB4CA",
+        "error-muted": "#5C3645",
+        "footer-background": "#414868",
+        "footer-description-background": "#00000000",
+        "footer-description-foreground": "#A9B1D6",
+        "footer-foreground": "#A9B1D6",
+        "footer-item-background": "#00000000",
+        "footer-key-background": "#00000000",
+        "footer-key-foreground": "#FF9E64",
+        "foreground": "#A9B1D6",
+        "foreground-darken-1": "#949CC1",
+        "foreground-darken-2": "#8189AC",
+        "foreground-darken-3": "#6D7698",
+        "foreground-disabled": "#A9B1D660",
+        "foreground-lighten-1": "#BDC5EB",
+        "foreground-lighten-2": "#D2DAFF",
+        "foreground-lighten-3": "#E7EFFF",
+        "foreground-muted": "#A9B1D699",
+        "input-cursor-background": "#A9B1D6",
+        "input-cursor-foreground": "#1A1B26",
+        "input-selection-background": "#D0AEFF66",
+        "link-background": "#00000000",
+        "link-background-hover": "#BB9AF7",
+        "link-color": "#FFFFFFDD",
+        "link-color-hover": "#FFFFFFDD",
+        "markdown-h1-background": "#00000000",
+        "markdown-h1-color": "#BB9AF7",
+        "markdown-h2-background": "#00000000",
+        "markdown-h2-color": "#BB9AF7",
+        "markdown-h3-background": "#00000000",
+        "markdown-h3-color": "#BB9AF7",
+        "markdown-h4-background": "#00000000",
+        "markdown-h4-color": "#A9B1D6",
+        "markdown-h5-background": "#00000000",
+        "markdown-h5-color": "#A9B1D6",
+        "markdown-h6-background": "#00000000",
+        "markdown-h6-color": "#A9B1D699",
+        "panel": "#414868",
+        "panel-darken-1": "#2F3755",
+        "panel-darken-2": "#1E2744",
+        "panel-darken-3": "#0C1733",
+        "panel-lighten-1": "#53597A",
+        "panel-lighten-2": "#656B8E",
+        "panel-lighten-3": "#787EA1",
+        "primary": "#BB9AF7",
+        "primary-background": "#504D60",
+        "primary-background-darken-1": "#413D52",
+        "primary-background-darken-2": "#322E45",
+        "primary-background-darken-3": "#322E45",
+        "primary-background-lighten-1": "#605D6E",
+        "primary-background-lighten-2": "#6F6C7C",
+        "primary-background-lighten-3": "#7E7C8A",
+        "primary-darken-1": "#A686E1",
+        "primary-darken-2": "#9173CC",
+        "primary-darken-3": "#7D60B7",
+        "primary-lighten-1": "#D0AEFF",
+        "primary-lighten-2": "#E5C2FF",
+        "primary-lighten-3": "#FBD7FF",
+        "primary-muted": "#4A4164",
+        "scrollbar": "#4F4270",
+        "scrollbar-active": "#BB9AF7",
+        "scrollbar-background": "#070817",
+        "scrollbar-background-active": "#070817",
+        "scrollbar-background-hover": "#070817",
+        "scrollbar-corner-color": "#070817",
+        "scrollbar-hover": "#615187",
+        "secondary": "#7AA2F7",
+        "secondary-background": "#484E60",
+        "secondary-background-darken-1": "#383E52",
+        "secondary-background-darken-2": "#282F45",
+        "secondary-background-darken-3": "#282F45",
+        "secondary-background-lighten-1": "#585D6E",
+        "secondary-background-lighten-2": "#686D7C",
+        "secondary-background-lighten-3": "#787D8A",
+        "secondary-darken-1": "#648EE1",
+        "secondary-darken-2": "#4D7BCC",
+        "secondary-darken-3": "#3468B7",
+        "secondary-lighten-1": "#8FB6FF",
+        "secondary-lighten-2": "#A5CAFF",
+        "secondary-lighten-3": "#BBDFFF",
+        "secondary-muted": "#364364",
+        "success": "#9ECE6A",
+        "success-darken-1": "#89B956",
+        "success-darken-2": "#75A443",
+        "success-darken-3": "#619030",
+        "success-lighten-1": "#B2E37D",
+        "success-lighten-2": "#C8F891",
+        "success-lighten-3": "#DDFFA6",
+        "success-muted": "#41503A",
+        "surface": "#24283B",
+        "surface-active": "#313448",
+        "surface-darken-1": "#14182A",
+        "surface-darken-2": "#00031B",
+        "surface-darken-3": "#000009",
+        "surface-lighten-1": "#34384C",
+        "surface-lighten-2": "#45495E",
+        "surface-lighten-3": "#575A70",
+        "text": "#FFFFFFDD",
+        "text-accent": "#FFBE98",
+        "text-disabled": "#FFFFFF60",
+        "text-error": "#F9A4B4",
+        "text-muted": "#FFFFFF99",
+        "text-primary": "#D2BCF9",
+        "text-secondary": "#A7C1F9",
+        "text-success": "#BEDE9C",
+        "text-warning": "#EACA9B",
+        "warning": "#DFAF68",
+        "warning-darken-1": "#C99A55",
+        "warning-darken-2": "#B48742",
+        "warning-darken-3": "#9E7430",
+        "warning-lighten-1": "#F6C37B",
+        "warning-lighten-2": "#FFD88F",
+        "warning-lighten-3": "#FFEDA3",
+        "warning-muted": "#554739",
+    },
+};
+export default theme;

package/dist/themes/data/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Static shape of a theme palette as authored. Each `data/<name>.ts` file
+ * exports one of these as its default export. The barrel (`./index.ts`)
+ * collects them into a single typed map; the registry consumes that map.
+ *
+ * Distinct from `Palette` — this is the on-disk authoring format (hex
+ * strings); `Palette` is the runtime form (parsed ColorRgba values). The
+ * registry's `getThemePalette` is the single boundary that hydrates one
+ * into the other.
+ */
+export interface ThemePaletteData {
+    readonly name: string;
+    readonly dark: boolean;
+    /**
+     * The sixteen colours a terminal showing this theme draws `red`, `blue`,
+     * `bright_black` and the rest in. A theme without its own table would draw
+     * them in the VGA defaults (`blue` as #000080), which belong to no theme.
+     */
+    readonly ansi: AnsiColorsData;
+    readonly vars: Readonly<Record<string, string>>;
+}
+/**
+ * ANSI colour numbers 0–15 in order: the eight normal colours, then their
+ * bright forms. Named rather than positional so a data file cannot shift a
+ * colour into its neighbour's slot by miscounting.
+ */
+export declare const ANSI_SLOTS: readonly ["black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "brightBlack", "brightRed", "brightGreen", "brightYellow", "brightBlue", "brightMagenta", "brightCyan", "brightWhite"];
+/** One `#RRGGBB` per ANSI colour number, keyed by `ANSI_SLOTS`. */
+export type AnsiColorsData = {
+    readonly [K in (typeof ANSI_SLOTS)[number]]: string;
+};

package/dist/themes/data/types.js

@@ -0,0 +1,10 @@
+/**
+ * ANSI colour numbers 0–15 in order: the eight normal colours, then their
+ * bright forms. Named rather than positional so a data file cannot shift a
+ * colour into its neighbour's slot by miscounting.
+ */
+export const ANSI_SLOTS = [
+    "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white",
+    "brightBlack", "brightRed", "brightGreen", "brightYellow",
+    "brightBlue", "brightMagenta", "brightCyan", "brightWhite",
+];

package/dist/themes/palette.d.ts

@@ -0,0 +1,45 @@
+import type { ColorRgba } from "../core/color.js";
+/**
+ * A semantic palette: a named map from variable name → ColorRgba.
+ *
+ * Distinct from `ColorTable` (the integer-indexed quantization LUT used by
+ * the downgrade pipeline). Palettes carry aesthetic intent — `primary`,
+ * `accent`, `error`, etc. — and are the foundation of the theming system.
+ *
+ * Storage is uniformly ColorRgba; consumers that load from hex JSON
+ * parse to ColorRgba at load time. `get` is a bare lookup — turning an
+ * 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;
+    readonly dark: boolean;
+    readonly vars: ReadonlyMap<string, ColorRgba>;
+    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

@@ -0,0 +1,71 @@
+/**
+ * A semantic palette: a named map from variable name → ColorRgba.
+ *
+ * Distinct from `ColorTable` (the integer-indexed quantization LUT used by
+ * the downgrade pipeline). Palettes carry aesthetic intent — `primary`,
+ * `accent`, `error`, etc. — and are the foundation of the theming system.
+ *
+ * Storage is uniformly ColorRgba; consumers that load from hex JSON
+ * parse to ColorRgba at load time. `get` is a bare lookup — turning an
+ * 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;
+    dark;
+    vars;
+    constructor(name, dark, vars) {
+        this.name = name;
+        this.dark = dark;
+        // [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

@@ -0,0 +1,70 @@
+/**
+ * A color ramp: a number mapped onto a color through ordered stops.
+ *
+ * "What does 73 % spent look like" has no answer in a vocabulary of discrete
+ * adjustments (`darken`, `mix`, `contrastOn`): each takes colors and returns a
+ * color, and none takes a *measurement*. Without a ramp the answer gets
+ * computed outside the theme system — a script emits a hex, a template
+ * branches `if ge .pct 80 … else if ge .pct 50 …` — and that color decision
+ * 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 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 — 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`, `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;
+}
+/**
+ * An immutable ramp over stops sorted by position.
+ *
+ * [LAW:single-enforcer] The constructor is the one place a ramp's shape is
+ * checked — at least one stop, every position finite, positions
+ * non-decreasing — matching the `ColorRgba`/`Oklch` pattern. Positions are
+ * required to arrive in order rather than being sorted here: a ramp whose
+ * stops are read from configuration (`warning at 80, error at 50`) is an
+ * authoring mistake, and sorting would quietly render a different ramp than
+ * the one written. [LAW:no-silent-failure]
+ *
+ * Two stops may share a position: that is a hard edge, the later color
+ * taking over at exactly that value (CSS gradients spell a hard stop the
+ * same way).
+ */
+export declare class ColorRamp {
+    readonly ease: Ease;
+    readonly 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 the raw progress
+     * from the lower to the upper goes through `ease`, and the eased progress
+     * says how far to mix.
+     *
+     * 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

@@ -0,0 +1,103 @@
+/**
+ * A color ramp: a number mapped onto a color through ordered stops.
+ *
+ * "What does 73 % spent look like" has no answer in a vocabulary of discrete
+ * adjustments (`darken`, `mix`, `contrastOn`): each takes colors and returns a
+ * color, and none takes a *measurement*. Without a ramp the answer gets
+ * computed outside the theme system — a script emits a hex, a template
+ * branches `if ge .pct 80 … else if ge .pct 50 …` — and that color decision
+ * 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 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 — 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`, `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";
+/**
+ * An immutable ramp over stops sorted by position.
+ *
+ * [LAW:single-enforcer] The constructor is the one place a ramp's shape is
+ * checked — at least one stop, every position finite, positions
+ * non-decreasing — matching the `ColorRgba`/`Oklch` pattern. Positions are
+ * required to arrive in order rather than being sorted here: a ramp whose
+ * stops are read from configuration (`warning at 80, error at 50`) is an
+ * authoring mistake, and sorting would quietly render a different ramp than
+ * the one written. [LAW:no-silent-failure]
+ *
+ * Two stops may share a position: that is a hard edge, the later color
+ * taking over at exactly that value (CSS gradients spell a hard stop the
+ * same way).
+ */
+export class ColorRamp {
+    ease;
+    stops;
+    constructor(ease, stops) {
+        this.ease = ease;
+        this.stops = stops;
+        if (stops.length === 0) {
+            throw new RangeError("a ColorRamp needs at least one stop");
+        }
+        for (const [i, stop] of stops.entries()) {
+            if (!Number.isFinite(stop.at)) {
+                throw new RangeError(`ColorRamp stop ${i} has a non-finite position ${stop.at}`);
+            }
+            const prev = stops[i - 1];
+            if (prev !== undefined && stop.at < prev.at) {
+                throw new RangeError(`ColorRamp stops must be in ascending position order; ` +
+                    `stop ${i} at ${stop.at} follows stop ${i - 1} at ${prev.at}`);
+            }
+        }
+    }
+    /**
+     * 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 the raw progress
+     * from the lower to the upper goes through `ease`, and the eased progress
+     * says how far to mix.
+     *
+     * 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)) {
+            throw new RangeError(`ColorRamp.at needs a finite value, got ${value}`);
+        }
+        const stops = this.stops;
+        // The last stop at or below `value`; -1 when `value` is below them all.
+        let lower = -1;
+        while (lower + 1 < stops.length && stops[lower + 1].at <= value)
+            lower++;
+        if (lower < 0)
+            return stops[0].color;
+        const from = stops[lower];
+        if (lower === stops.length - 1)
+            return from.color;
+        // `to.at > value >= from.at` by construction of `lower`, so the segment
+        // has positive width and raw progress is in [0, 1).
+        const to = stops[lower + 1];
+        const t = this.ease((value - from.at) / (to.at - from.at));
+        if (t <= 0)
+            return from.color;
+        if (t >= 1)
+            return to.color;
+        return Oklch.fromRgba(from.color).mix(Oklch.fromRgba(to.color), t).toRgba();
+    }
+}

package/dist/themes/registry.d.ts

@@ -0,0 +1,44 @@
+import { ColorRgba, ColorTable } from "../core/color.js";
+import { Palette } from "./palette.js";
+import { type ThemeName } from "./data/index.js";
+export type { ThemeName };
+/**
+ * Returns the static list of available theme names. Pure and synchronous.
+ */
+export declare function listThemePalettes(): readonly ThemeName[];
+/**
+ * Returns the Palette for `name`, or `null` if unknown.
+ *
+ * Synchronous: theme data is bundled at compile time via the data barrel,
+ * so no I/O happens here. The Palette itself (which requires hex-parsing
+ * ~150 vars into ColorRgba values) is constructed lazily on first request
+ * and cached — subsequent calls for the same name return the same instance.
+ */
+export declare function getThemePalette(name: ThemeName): Palette;
+export declare function getThemePalette(name: string): Palette | null;
+/**
+ * The eight base colors every theme must declare, and its ANSI table. Returned by
+ * `getThemeBaseColors` for callers (notably `terminalThemes.ts`) that only
+ * need the substrate and would otherwise pay the cost of hydrating the
+ * full ~150-var palette and polluting the registry cache.
+ */
+export interface ThemeBaseColors {
+    readonly name: string;
+    readonly dark: boolean;
+    readonly bg: ColorRgba;
+    readonly fg: ColorRgba;
+    readonly primary: ColorRgba;
+    readonly secondary: ColorRgba;
+    readonly accent: ColorRgba;
+    readonly success: ColorRgba;
+    readonly warning: ColorRgba;
+    readonly error: ColorRgba;
+    readonly ansi: ColorTable;
+}
+/**
+ * Read just the eight base colors from a theme's data file. Cheap — parses
+ * 8 hex strings, allocates no Palette, touches no cache. Use this when you
+ * want a `TerminalTheme`-shaped substrate without forcing the full ~150-var
+ * palette through the registry's hydration path.
+ */
+export declare function getThemeBaseColors(name: ThemeName): ThemeBaseColors;

package/dist/themes/registry.js

@@ -0,0 +1,105 @@
+import { ColorParseError, ColorTable, parseHexColor } from "../core/color.js";
+import { Palette, drawnOn } from "./palette.js";
+import { ACCENT_KEYS, accentText } from "./buildPalette.js";
+import { THEMES } from "./data/index.js";
+import { ANSI_SLOTS } from "./data/types.js";
+const THEME_NAMES = Object.freeze(Object.keys(THEMES).sort());
+const cache = new Map();
+/**
+ * Returns the static list of available theme names. Pure and synchronous.
+ */
+export function listThemePalettes() {
+    return THEME_NAMES;
+}
+export function getThemePalette(name) {
+    if (!isThemeName(name))
+        return null;
+    const cached = cache.get(name);
+    if (cached !== undefined)
+        return cached;
+    const palette = hydrate(THEMES[name]);
+    cache.set(name, palette);
+    return palette;
+}
+function isThemeName(name) {
+    return Object.hasOwn(THEMES, name);
+}
+/**
+ * Read just the eight base colors from a theme's data file. Cheap — parses
+ * 8 hex strings, allocates no Palette, touches no cache. Use this when you
+ * want a `TerminalTheme`-shaped substrate without forcing the full ~150-var
+ * palette through the registry's hydration path.
+ */
+export function getThemeBaseColors(name) {
+    const data = THEMES[name];
+    const bg = requireBaseVar(data, "background");
+    // The colours `getThemePalette(name)` hands out for the same names: drawn on
+    // the theme's own background, as a Palette draws every colour it holds.
+    const draw = drawnOn(data.name, bg);
+    const base = (key) => draw(requireBaseVar(data, key));
+    return {
+        name: data.name,
+        dark: data.dark,
+        bg,
+        fg: base("foreground"),
+        primary: base("primary"),
+        secondary: base("secondary"),
+        accent: base("accent"),
+        success: base("success"),
+        warning: base("warning"),
+        error: base("error"),
+        ansi: new ColorTable(ANSI_SLOTS.map((slot) => parseOpaqueHex(data.ansi[slot], data.name, `ansi.${slot}`))),
+    };
+}
+function requireBaseVar(data, key) {
+    const v = data.vars[key];
+    if (v === undefined) {
+        throw new Error(`Theme ${data.name}: required base var "${key}" missing from data file`);
+    }
+    return parseHex(v, data.name, key);
+}
+/**
+ * Parse a `ThemePaletteData`'s hex strings into a Palette of ColorRgba.
+ *
+ * [LAW:single-enforcer] Hex → ColorRgba conversion for theme data lives
+ * here, not on Palette. Keeping the parser in this module preserves the
+ * `core/color → themes/palette` one-way edge (palette.ts must not import
+ * ColorRgba as a value, or it cycles with core/color's own use of Palette
+ * for INTERNAL_DEFAULT_THEME).
+ */
+function hydrate(data) {
+    const map = new Map();
+    for (const [k, v] of Object.entries(data.vars)) {
+        map.set(k, parseHex(v, data.name, `var ${k}`));
+    }
+    // The data is Textual's as authored; its `text-*` is held to the pair this
+    // library promises by the same rule `buildPalette` derives it with.
+    for (const key of ACCENT_KEYS) {
+        const text = requireBaseVar(data, `text-${key}`);
+        map.set(`text-${key}`, accentText(text, requireBaseVar(data, `${key}-muted`), requireBaseVar(data, "background")));
+    }
+    return new Palette(data.name, data.dark, map);
+}
+// Theme data is authored, so a malformed colour names the theme and the key it
+// sits under; the grammar itself is `parseHexColor`'s.
+function parseHex(value, theme, key) {
+    try {
+        return parseHexColor(value);
+    }
+    catch (cause) {
+        if (!(cause instanceof ColorParseError))
+            throw cause;
+        throw new Error(`Theme ${theme}: ${key}: ${cause.message}`, { cause });
+    }
+}
+/**
+ * An ANSI slot is a colour a terminal paints, never a blend, so it takes no
+ * alpha: `flattenAlpha` leaves a STANDARD spec alone and would pass one through.
+ */
+function parseOpaqueHex(value, theme, key) {
+    const color = parseHex(value, theme, key);
+    if (color.alpha !== 1) {
+        throw new Error(`Theme ${theme}: ${key} has alpha in ${JSON.stringify(value)} (expected #RRGGBB)`);
+    }
+    return color;
+}