@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/core/color.d.ts

@@ -0,0 +1,326 @@
+/**
+ * Terminal color representation, parsing, downgrading, and ANSI code generation.
+ */
+import type { Env } from "./env.js";
+/**
+ * Immutable RGBA color value. Alpha defaults to 1 (fully opaque).
+ *
+ * [LAW:single-enforcer] The constructor is the sole validation site for
+ * channel/alpha invariants. Float-arithmetic callers (HSL roundtrips, blends,
+ * lerps) are responsible for `Math.round` + clamp before construction; the
+ * constructor throws rather than silently masking out-of-range input.
+ */
+export declare class ColorRgba {
+    readonly red: number;
+    readonly green: number;
+    readonly blue: number;
+    readonly alpha: number;
+    constructor(red: number, green: number, blue: number, alpha?: number);
+    /** 6-char `#RRGGBB` when fully opaque, 8-char `#RRGGBBAA` otherwise. */
+    get hex(): string;
+    /** `rgb(r,g,b)` when fully opaque, `rgba(r,g,b,a)` otherwise. */
+    get rgb(): string;
+    /** [r/255, g/255, b/255, alpha] — alpha is already 0..1, no division. */
+    get normalized(): [number, number, number, number];
+    /**
+     * Composite this color over an opaque background. Returns a fully opaque
+     * ColorRgba (alpha=1). Per-channel linear interpolation by alpha.
+     *
+     * [LAW:dataflow-not-control-flow] alpha=1 short-circuits to `this`, so
+     * callers can invoke this unconditionally; the data decides whether work
+     * happens.
+     */
+    compositeOver(bg: ColorRgba): ColorRgba;
+}
+/**
+ * The surface a terminal draws a translucent colour over. A terminal cannot
+ * know what lies under its cells, so the SGR writer (`Style.toSgrCodes`), the
+ * exports that picture its output (`resolveLook`), the strip's seam test and
+ * the contrast choosers (`themes/colorMath`) all composite over this one
+ * colour. [LAW:one-source-of-truth] One constant, so
+ * the colour text is chosen against is the colour the writer draws.
+ */
+export declare const SURFACE_BLACK: ColorRgba;
+/**
+ * WCAG 2.x relative luminance (0..1) of an opaque color. The single
+ * luminance function in the codebase — `contrastFor`, `contrastRatio`, and
+ * any caller that needs to reason about readability all funnel through it.
+ * [LAW:one-source-of-truth]
+ */
+export declare function relativeLuminance(c: ColorRgba): number;
+/**
+ * WCAG 2.x contrast ratio between two colors, in [1, 21]. Symmetric — the
+ * order of arguments does not matter. 4.5 is the AA threshold for normal
+ * text, 3.0 for large text.
+ *
+ * Assumes opaque inputs: alpha is ignored, since the displayed contrast of a
+ * translucent color depends on what it composites over. For a translucent
+ * foreground, flatten it first (or use `ensureContrast`, which does).
+ */
+export declare function contrastRatio(a: ColorRgba, b: ColorRgba): number;
+/**
+ * An indexed palette: entry `i` of `colors` is terminal index `firstIndex + i`.
+ * `firstIndex` lets a table hold only the part of a palette a downgrade may
+ * choose (the 256-colour cube and grey ramp start at 16) while every index it
+ * reports is the terminal's own.
+ */
+export declare class ColorTable {
+    private readonly colors;
+    readonly firstIndex: number;
+    private readonly matchMemo;
+    private readonly readableMemo;
+    constructor(colors: ColorRgba[], firstIndex?: number);
+    get(index: number): ColorRgba;
+    private luminanceCache;
+    /** Each entry's relative luminance, computed once per table. */
+    private luminances;
+    /** How many entries the table holds (terminal indices `firstIndex`…). */
+    get size(): number;
+    /**
+     * Finds the nearest table index to the given color (Euclidean RGB distance, cached).
+     * Alpha is part of the cache key so two values that differ only in alpha
+     * don't collide, but is not used in the distance metric.
+     */
+    match(value: ColorRgba): number;
+    private nearest;
+    /**
+     * The nearest entry to `value` (the distance `match` uses) among those that
+     * clear `minRatio` against `on`; when none does, the entry with the most
+     * contrast against `on`. Text downgraded on its own background: `match`
+     * moves text and background independently, and two independent roundings
+     * can meet in the middle, so a pair that read at 4.5:1 in truecolor can
+     * draw at 2:1. [LAW:dataflow-not-control-flow] One scan scores every entry;
+     * the ratio decides which one wins.
+     */
+    matchReadable(value: ColorRgba, on: ColorRgba, minRatio: number): number;
+    private nearestReadable;
+    /**
+     * The nearest entry to `value` (the distance `match` uses) among those
+     * `accept` takes, given each entry's colour and terminal index; `undefined`
+     * when it takes none. Entries are offered nearest-first (ties to the lower
+     * index) and the first taken wins, so an expensive predicate runs only as
+     * far out as the answer. Uncached: the predicate is the caller's, and a
+     * closure has no key.
+     */
+    matchWhere(value: ColorRgba, accept: (entry: ColorRgba, index: number) => boolean): number | undefined;
+}
+export declare enum ColorDepth {
+    DEFAULT = 0,
+    STANDARD = 1,
+    EIGHT_BIT = 2,
+    TRUECOLOR = 3,
+    WINDOWS = 4
+}
+export interface DetectColorOptions {
+    /** Environment to probe. Defaults to `process.env`. */
+    env?: Env;
+    /** Whether output is going to a real terminal. Defaults to `process.stdout?.isTTY`. */
+    isTTY?: boolean;
+}
+declare const COLOR_SYSTEM_DEPTHS: {
+    readonly truecolor: ColorDepth.TRUECOLOR;
+    readonly "256": ColorDepth.EIGHT_BIT;
+    readonly ansi: ColorDepth.STANDARD;
+    readonly none: null;
+};
+/**
+ * A colour system by name: `"auto"` detects it from the environment, and each
+ * other name is a fixed depth — `"none"` no colour. `ColorDepth.WINDOWS` has
+ * no name; pass the enum value where a `ColorDepth` is accepted.
+ */
+export type ColorSystemName = "auto" | keyof typeof COLOR_SYSTEM_DEPTHS;
+/**
+ * Detect the terminal's color capability from env + TTY state.
+ *
+ * Probes (in priority order): NO_COLOR (per https://no-color.org —
+ * any non-empty value disables color), FORCE_COLOR (numeric/boolean override),
+ * TTY presence, TERM=dumb/unknown, COLORTERM, known terminal/TERM_PROGRAM
+ * names, and TERM regex patterns. Returns `null` for "no color".
+ *
+ * [LAW:dataflow-not-control-flow] Same probes run every call; variability is
+ * in the env values, not in which checks execute.
+ */
+export declare function detectColorSystem(options?: DetectColorOptions): ColorDepth | null;
+/**
+ * A terminal that says it cannot be drawn on: `TERM` is `dumb` or `unknown`,
+ * as Emacs' shell mode sets it. It takes no colour and nothing that moves the
+ * cursor.
+ */
+export declare function isDumbTerminal(env: Env): boolean;
+/**
+ * Where segments are written, as everything the serializer (`segmentsToString`)
+ * needs to know about it: the colour depth SGR is drawn at, and whether OSC 8
+ * hyperlinks are emitted. The serializer takes this value whole, so a fact the
+ * encoding comes to need joins it here rather than the serializer's signature.
+ */
+export interface Destination {
+    readonly colorSystem: ColorDepth | null;
+    readonly hyperlinks: boolean;
+}
+/**
+ * Resolve a colour spec into a `Destination`.
+ *
+ * [LAW:single-enforcer] The one place a spec becomes both facts. A hyperlink is
+ * not a colour: an explicit depth — `"none"` and `null` included — states a
+ * colour choice and keeps links, and under `"auto"` links follow what the
+ * terminal can take (no TTY, TERM=dumb: none) while NO_COLOR and FORCE_COLOR=0,
+ * colour preferences, leave them alone. A FORCE_COLOR that forces colour on
+ * declares the destination takes escapes, so it keeps links on a pipe too.
+ */
+export declare function resolveDestination(spec: ColorSystemName | ColorDepth | null, options?: DetectColorOptions): Destination;
+/**
+ * Resolve a colour system name into a `ColorDepth` (or `null` for no color).
+ *
+ * `"auto"` triggers env-based detection; every other name is a fixed depth.
+ * A name outside the vocabulary — reachable only from untyped JavaScript —
+ * throws: silent fallback would mask a typo.
+ *
+ * [LAW:single-enforcer] All name→ColorDepth resolution flows through here.
+ */
+export declare function resolveColorSystem(spec: ColorSystemName, options?: DetectColorOptions): ColorDepth | null;
+export declare class ColorParseError extends Error {
+    constructor(message: string);
+}
+export declare class ColorSpec {
+    readonly name: string;
+    readonly type: ColorDepth;
+    readonly number: number | undefined;
+    readonly value: ColorRgba | undefined;
+    private downgradeCache;
+    constructor(name: string, type: ColorDepth, number?: number, value?: ColorRgba);
+    get isDefault(): boolean;
+    /**
+     * The colour every terminal draws this spec as, where that is fixed — before
+     * any alpha is flattened, so a translucent value is drawn composited over
+     * its ground (`flattenAlpha`) and should be measured that way: a
+     * truecolor value, or a 256-colour cube or grey-ramp entry (xterm fixes
+     * indices 16–255, and `fromAnsi` types only those as EIGHT_BIT). ANSI 0–15,
+     * the default colour and a blend reaching either are the terminal theme's
+     * own, so they have none.
+     */
+    get fixedValue(): ColorRgba | undefined;
+    get isSystemDefined(): boolean;
+    /**
+     * Generates SGR parameter strings for this color.
+     */
+    getAnsiCodes(foreground?: boolean): string[];
+    /**
+     * Composite this color's alpha (if any) against an opaque background,
+     * returning a fully-opaque ColorSpec. Non-truecolor specs (palette
+     * indices, default) have no alpha and pass through unchanged.
+     *
+     * [LAW:single-enforcer] Sole alpha-flattening site for the render
+     * pipeline. Run *before* downgrade — otherwise palette matching on the
+     * still-translucent RGB silently drops alpha (the "flatten then lose
+     * alpha" path the unification ticket forbids).
+     *
+     * [LAW:dataflow-not-control-flow] `ColorRgba.compositeOver` is a no-op
+     * when alpha=1, so callers invoke this unconditionally; the data
+     * (alpha value) decides whether work happens.
+     */
+    flattenAlpha(bg: ColorRgba): ColorSpec;
+    /**
+     * Downgrade to a lower-fidelity color depth. Cached.
+     */
+    downgrade(targetSystem: ColorDepth): ColorSpec;
+    /**
+     * Resolves to an actual RGB(A) value for any color type.
+     */
+    getTruecolor(theme?: TerminalTheme, foreground?: boolean): ColorRgba;
+    static default(): ColorSpec;
+    static fromAnsi(n: number): ColorSpec;
+    static fromRgba(value: ColorRgba): ColorSpec;
+    static fromRgb(r: number, g: number, b: number): ColorSpec;
+    /**
+     * The colour `t` of the way from `from` to `to`: what `blend(from,to,t)`
+     * parses to. Two fixed colours mix to a fixed colour. A mix reaching a
+     * theme's own colour stays a mix until it is drawn, so whatever theme draws
+     * an end draws the mix from it: exported under a theme whose `blue` is
+     * #61afef, a mix with `blue` starts from #61afef. A terminal is told its RGB
+     * under the standard table, the only one a render has.
+     *
+     * Each end is one opaque colour: `default` is no colour to mix, and a
+     * translucent end has no one shade until it is laid on a ground.
+     */
+    static blend(from: ColorSpec, to: ColorSpec, t: number): ColorSpec;
+    /**
+     * The spec that draws `value` nearest to it at `depth` on a terminal known
+     * to show `theme`, as the colour of the glyph (`foreground`) or of the
+     * ground. Where `downgrade` knows no terminal, and so rounds only against
+     * colours every terminal fixes (or, at sixteen colours, the stock
+     * sixteen), this rounds against every colour the depth can write whose
+     * look `theme` fixes: the default colour, the theme's sixteen, and at 256
+     * colours the cube and grey ramp too. A colour read off any of those and
+     * moved a little is drawn as the colour it came from — or, where the theme
+     * gives two slots one colour, as the lower slot, which looks the same.
+     *
+     * `value` is opaque: a translucent colour has no one look until it is laid
+     * on a ground (`flattenAlpha`).
+     */
+    static matchOn(value: ColorRgba, depth: ColorDepth, theme: TerminalTheme, foreground: boolean): ColorSpec;
+    /**
+     * Parse a color string. Memoized (`Memo`): a string parsed again while
+     * remembered returns the same instance.
+     */
+    static parse(colorString: string): ColorSpec;
+    private performDowngrade;
+}
+/** Six hex digits, no `#`, as an opaque colour. @throws {ColorParseError} on anything else. */
+export declare function parseRgbHex(hex: string): ColorRgba;
+/** Eight hex digits, no `#`, the last pair alpha. @throws {ColorParseError} on anything else. */
+export declare function parseRgbaHex(hex: string): ColorRgba;
+/**
+ * A `#RRGGBB` or `#RRGGBBAA` literal, exactly — no surrounding whitespace.
+ * @throws {ColorParseError} on anything else.
+ */
+export declare function parseHexColor(literal: string): ColorRgba;
+export declare function blendRgb(color1: ColorRgba, color2: ColorRgba, crossFade?: number): ColorRgba;
+/**
+ * A terminal theme — surface/foreground baseline, the sixteen ANSI colours,
+ * and a semantic palette.
+ *
+ * **`ansiColors` is the theme's own sixteen colours**, the shades a terminal
+ * showing this theme draws `red`, `blue` and the rest in. `ColorSpec.parse("red")`
+ * is ANSI colour 1 under every theme; which red that is, is the theme's to say,
+ * as it is in Rich, where each `TerminalTheme` carries its own table.
+ */
+export declare class TerminalTheme {
+    readonly backgroundColor: ColorRgba;
+    readonly foregroundColor: ColorRgba;
+    readonly ansiColors: ColorTable;
+    readonly palette: import("../themes/palette.js").Palette;
+    constructor(backgroundColor: ColorRgba, foregroundColor: ColorRgba, ansiColors: ColorTable, palette: import("../themes/palette.js").Palette);
+}
+export declare const STANDARD_TABLE: ColorTable;
+export declare const EIGHT_BIT_TABLE: ColorTable;
+/**
+ * What a downgrade to 256 colours may choose: the cube and the grey ramp,
+ * indices 16–255. Indices 0–15 are the terminal's own ANSI colours, which
+ * every theme redefines, so their RGB is unknown and a match against them is
+ * a guess; Python Rich never picks them either.
+ */
+export declare const EIGHT_BIT_DOWNGRADE_TABLE: ColorTable;
+export declare const WINDOWS_TABLE: ColorTable;
+/**
+ * The terminal a colour at `depth` is drawn by: `theme`, or when a caller names
+ * none, the one the depth assumes — the Windows console at WINDOWS, the VGA
+ * sixteen otherwise — for `ColorSpec.getTruecolor` and the contrast measurement
+ * that reads it. (Widgets fall back to `DEFAULT_TERMINAL_THEME`, which carries a
+ * palette this does not.)
+ */
+export declare function resolveTerminal(theme: TerminalTheme | undefined, depth: ColorDepth): TerminalTheme;
+/**
+ * The table a downgrade to `depth` rounds a fixed colour against.
+ * [LAW:one-source-of-truth] `ColorSpec.downgrade` picks the index a colour is
+ * written as from it, and colorMath hands back its entries as colours the
+ * writer rounds to those same indices.
+ */
+export declare function downgradeTable(depth: ColorDepth.EIGHT_BIT | ColorDepth.STANDARD | ColorDepth.WINDOWS): ColorTable;
+export declare const ANSI_COLOR_NAMES: Record<string, number>;
+/**
+ * Every word `ColorSpec.parse` accepts as a name rather than a `#hex`,
+ * `rgb()` or `color(N)` form: `default` and the named palette entries, which
+ * are exactly the two name checks `parseSingle` makes.
+ */
+export declare const COLOR_NAMES: readonly string[];
+export {};