@promptctl/rich-js 0.16.0 → 0.18.0

package/dist/core/cells.d.ts

@@ -1,148 +0,0 @@
-/**
- * Terminal cell width calculation.
- * Handles ASCII, CJK (double-width), and emoji characters.
- */
-/**
- * Returns the terminal cell width of a string.
- */
-export declare function cellLen(text: string): number;
-declare const _cellCol: unique symbol;
-declare const _codeUnit: unique symbol;
-declare const _codePoint: unique symbol;
-/** Terminal cell-column offset. Never interchangeable with a code-unit index. */
-export type CellCol = number & {
-    readonly [_cellCol]: true;
-};
-/** JS string code-unit index. Never interchangeable with a cell-column offset. */
-export type CodeUnit = number & {
-    readonly [_codeUnit]: true;
-};
-/**
- * A `CodeUnit` index that is additionally guaranteed to fall on a Unicode
- * code-point boundary (i.e. never inside a surrogate pair). Assignable to
- * `CodeUnit`; the reverse assignment is forbidden.
- */
-export type CodePoint = CodeUnit & {
-    readonly [_codePoint]: true;
-};
-/** Brand a raw number as a CellCol. Use only at trust boundaries. */
-export declare function asCellCol(n: number): CellCol;
-/** Brand a raw number as a CodeUnit. Use only at trust boundaries. */
-export declare function asCodeUnit(n: number): CodeUnit;
-/** Brand a raw number as a CodePoint. Use only when the value is known to be
- *  on a Unicode code-point boundary. */
-export declare function asCodePoint(n: number): CodePoint;
-/**
- * [LAW:parse-dont-validate] A caller's number as a count of cells — the checked
- * counterpart to `asCellCol`'s unchecked brand, and the one place the rule "a
- * cell count is a non-negative integer" is written.
- *
- * [LAW:one-source-of-truth] Every renderable is handed `RenderOptions.maxWidth`
- * as a plain `number`, so every renderable used to answer this for itself and
- * they disagreed: at NaN, `Table` collapsed to one cell of garbage, `Columns`
- * and `Layout` threw `Invalid array length`, and `RichText` ignored the request
- * and emitted its full natural width. Parse at the entry to `render`/`measure`
- * and nothing downstream re-asks.
- *
- * The comparison is the point, not `Math.max(0, n)`: NaN fails every comparison
- * and so floors here, where `Math.max` would return it and let it poison every
- * bounds check downstream. Integral because a cell is not divisible — a
- * fractional budget reaches a largest-remainder division, which grants a whole
- * cell against a fractional residue and hands out more width than it was given.
- *
- * `Infinity` is outside what the comparison floors, so it passes through
- * unchanged, and no clamp belongs here: the finite answer to an unbounded offer
- * is the renderable's own natural width, which this function cannot see from
- * the number alone. `withBoundedWidth` in `protocol.ts` is the second half of
- * the parse and the only place that value is resolved.
- */
-export declare function cellCount(n: number): CellCol;
-/**
- * Pads or crops a string to exactly `totalWidth` terminal cells.
- * Invariant: cellLen(setCellSize(text, n)) === n (unless n is 0)
- */
-export declare function setCellSize(text: string, totalWidth: CellCol): string;
-/**
- * Splits text at a cell position. Returns [left, right].
- * When the position falls mid-wide-character, the left side is padded
- * to reach exactly `position` cells. The wide char remains in the right side.
- */
-export declare function splitText(text: string, position: CellCol): [string, string];
-/**
- * Wraps text into lines of at most `maxWidth` cells, preserving every code
- * point: `chopCells(t, w).join("") === t`. Unlike `splitText` this never pads,
- * so a line ending before a wide glyph is narrower than `maxWidth` rather than
- * padded out to it.
- *
- * A line overflows exactly where the budget cannot be met: a glyph wider than
- * `maxWidth` is force-taken whole rather than dropped, and a `maxWidth` of zero
- * or less is no budget at all, so the text comes back as one line.
- */
-export declare function chopCells(text: string, maxWidth: CellCol): string[];
-/**
- * Returns the largest prefix of `text` whose cell width fits within `cap` cells.
- * No padding — the returned string may be narrower than `cap` when the next
- * character is wide and would overshoot. Never wider than `cap` cells.
- *
- * When the first character already exceeds `cap` cells, returns "" (the caller
- * must decide whether to force-take the character or skip it).
- */
-export declare function cellFit(text: string, cap: CellCol): string;
-/**
- * Returns the largest code-unit end offset starting from `startCU` whose
- * prefix (from `startCU`) has cell width ≤ `cap`. Iterates from the given
- * offset without slicing the tail, avoiding O(N²) allocation when called
- * repeatedly across a long string.
- *
- * [LAW:types-are-the-program] returns CodePoint because for...of always
- * stops on a code-point boundary.
- */
-export declare function cellFitFrom(text: string, startCU: CodePoint, cap: CellCol): CodePoint;
-/**
- * Like `cellFitFrom`, but for any `startCU` inside `text` the result is
- * strictly past it: a glyph too wide for `cap` is force-taken whole and
- * overflows `cap` by its own width. So a `while (i < text.length)` loop driven
- * by this terminates by construction, and the re-brand is honest — both
- * operands land on code-point boundaries, so their max does too.
- *
- * [LAW:single-enforcer] `cellFit` documents that its caller must choose between
- * force-taking and skipping; this is that choice, made once. It was made twice
- * before and the copies drifted — the textarea's soft wrap force-took,
- * `chopCells` did neither and hung.
- */
-export declare function cellStepFrom(text: string, startCU: CodePoint, cap: CellCol): CodePoint;
-/**
- * Returns the largest code-unit offset into `content` whose prefix has
- * cell width ≤ `cellCol`. When `cellCol` falls mid-wide-character the
- * function stops before that character (never advances into it).
- * Clamps to `content.length` if `cellCol` exceeds the string's total
- * cell width.
- *
- * This is the inverse of `cellLen(content.slice(0, codeUnit))` — given a
- * visual column, return the corresponding string index.
- *
- * Returns `CodePoint` because `for...of` iteration always stops on a
- * code-point boundary.
- */
-export declare function cellColToCodeUnitOffset(content: string, cellCol: CellCol): CodePoint;
-/**
- * Advance one full Unicode code point from `cu`, returning the code-unit
- * offset of the start of the *next* code point. Returns `s.length` when
- * already at or past the end.
- *
- * Handles surrogate pairs: when the code point at `cu` is a supplementary
- * character (U+10000…U+10FFFF) it occupies 2 UTF-16 code units, so the
- * returned offset advances by 2.
- */
-export declare function nextCodePoint(s: string, cu: CodeUnit): CodePoint;
-/**
- * Step back one full Unicode code point from `cu`, returning the code-unit
- * offset of the start of the *previous* code point. Returns 0 when already
- * at the start.
- *
- * Handles surrogate pairs: when the code unit at `cu - 1` is a low surrogate
- * AND the code unit at `cu - 2` is a high surrogate, steps back 2 code units.
- * Unpaired surrogates are treated as 1-CU characters.
- */
-export declare function prevCodePoint(s: string, cu: CodeUnit): CodePoint;
-export {};

package/dist/core/cells.js

@@ -1,266 +0,0 @@
-/**
- * Terminal cell width calculation.
- * Handles ASCII, CJK (double-width), and emoji characters.
- */
-import stringWidth from "string-width";
-// [LAW:one-source-of-truth] string-width is the single authority for cell width
-const cellLenCache = new Map();
-const CACHE_MAX = 4096;
-/**
- * Returns the terminal cell width of a string.
- */
-export function cellLen(text) {
-    if (text.length === 0)
-        return 0;
-    // Fast path for pure ASCII
-    if (text.length <= 64) {
-        const cached = cellLenCache.get(text);
-        if (cached !== undefined)
-            return cached;
-    }
-    const width = stringWidth(text);
-    if (text.length <= 64) {
-        if (cellLenCache.size >= CACHE_MAX)
-            cellLenCache.clear();
-        cellLenCache.set(text, width);
-    }
-    return width;
-}
-/** Brand a raw number as a CellCol. Use only at trust boundaries. */
-export function asCellCol(n) { return n; }
-/** Brand a raw number as a CodeUnit. Use only at trust boundaries. */
-export function asCodeUnit(n) { return n; }
-/** Brand a raw number as a CodePoint. Use only when the value is known to be
- *  on a Unicode code-point boundary. */
-export function asCodePoint(n) { return n; }
-/**
- * [LAW:parse-dont-validate] A caller's number as a count of cells — the checked
- * counterpart to `asCellCol`'s unchecked brand, and the one place the rule "a
- * cell count is a non-negative integer" is written.
- *
- * [LAW:one-source-of-truth] Every renderable is handed `RenderOptions.maxWidth`
- * as a plain `number`, so every renderable used to answer this for itself and
- * they disagreed: at NaN, `Table` collapsed to one cell of garbage, `Columns`
- * and `Layout` threw `Invalid array length`, and `RichText` ignored the request
- * and emitted its full natural width. Parse at the entry to `render`/`measure`
- * and nothing downstream re-asks.
- *
- * The comparison is the point, not `Math.max(0, n)`: NaN fails every comparison
- * and so floors here, where `Math.max` would return it and let it poison every
- * bounds check downstream. Integral because a cell is not divisible — a
- * fractional budget reaches a largest-remainder division, which grants a whole
- * cell against a fractional residue and hands out more width than it was given.
- *
- * `Infinity` is outside what the comparison floors, so it passes through
- * unchanged, and no clamp belongs here: the finite answer to an unbounded offer
- * is the renderable's own natural width, which this function cannot see from
- * the number alone. `withBoundedWidth` in `protocol.ts` is the second half of
- * the parse and the only place that value is resolved.
- */
-export function cellCount(n) {
-    return (n > 0 ? Math.floor(n) : 0);
-}
-// ── Cell-aware string utilities ──────────────────────────────────────────────
-/**
- * Pads or crops a string to exactly `totalWidth` terminal cells.
- * Invariant: cellLen(setCellSize(text, n)) === n (unless n is 0)
- */
-export function setCellSize(text, totalWidth) {
-    if (totalWidth === 0)
-        return "";
-    const currentWidth = cellLen(text);
-    if (currentWidth === totalWidth)
-        return text;
-    if (currentWidth < totalWidth) {
-        return text + " ".repeat(totalWidth - currentWidth);
-    }
-    return cropToWidth(text, totalWidth);
-}
-/**
- * Splits text at a cell position. Returns [left, right].
- * When the position falls mid-wide-character, the left side is padded
- * to reach exactly `position` cells. The wide char remains in the right side.
- */
-export function splitText(text, position) {
-    if (position <= 0)
-        return ["", text];
-    const totalWidth = cellLen(text);
-    if (position >= totalWidth)
-        return [text, ""];
-    // Walk characters tracking cell width and source char index
-    let width = 0;
-    let charIndex = 0;
-    for (const char of text) {
-        const charWidth = cellLen(char);
-        if (width + charWidth > position)
-            break;
-        width += charWidth;
-        charIndex += char.length;
-    }
-    const left = text.slice(0, charIndex);
-    const right = text.slice(charIndex);
-    // If we stopped short of position (mid-wide-char), pad left with spaces
-    if (width < position) {
-        return [left + " ".repeat(position - width), right];
-    }
-    return [left, right];
-}
-/**
- * Wraps text into lines of at most `maxWidth` cells, preserving every code
- * point: `chopCells(t, w).join("") === t`. Unlike `splitText` this never pads,
- * so a line ending before a wide glyph is narrower than `maxWidth` rather than
- * padded out to it.
- *
- * A line overflows exactly where the budget cannot be met: a glyph wider than
- * `maxWidth` is force-taken whole rather than dropped, and a `maxWidth` of zero
- * or less is no budget at all, so the text comes back as one line.
- */
-export function chopCells(text, maxWidth) {
-    if (maxWidth <= 0 || text.length === 0)
-        return [text];
-    const lines = [];
-    let start = asCodePoint(0);
-    while (start < text.length) {
-        const end = cellStepFrom(text, start, maxWidth);
-        lines.push(text.slice(start, end));
-        start = end;
-    }
-    return lines;
-}
-/**
- * Returns the largest prefix of `text` whose cell width fits within `cap` cells.
- * No padding — the returned string may be narrower than `cap` when the next
- * character is wide and would overshoot. Never wider than `cap` cells.
- *
- * When the first character already exceeds `cap` cells, returns "" (the caller
- * must decide whether to force-take the character or skip it).
- */
-export function cellFit(text, cap) {
-    let w = 0;
-    let i = 0;
-    for (const ch of text) {
-        const cw = cellLen(ch);
-        if (w + cw > cap)
-            break;
-        w += cw;
-        i += ch.length;
-    }
-    return text.slice(0, i);
-}
-/**
- * Returns the largest code-unit end offset starting from `startCU` whose
- * prefix (from `startCU`) has cell width ≤ `cap`. Iterates from the given
- * offset without slicing the tail, avoiding O(N²) allocation when called
- * repeatedly across a long string.
- *
- * [LAW:types-are-the-program] returns CodePoint because for...of always
- * stops on a code-point boundary.
- */
-export function cellFitFrom(text, startCU, cap) {
-    let w = 0;
-    let i = startCU;
-    while (i < text.length) {
-        const cp = text.codePointAt(i);
-        const ch = String.fromCodePoint(cp);
-        const cw = cellLen(ch);
-        if (w + cw > cap)
-            break;
-        w += cw;
-        i = asCodePoint(i + ch.length);
-    }
-    return i;
-}
-/**
- * Like `cellFitFrom`, but for any `startCU` inside `text` the result is
- * strictly past it: a glyph too wide for `cap` is force-taken whole and
- * overflows `cap` by its own width. So a `while (i < text.length)` loop driven
- * by this terminates by construction, and the re-brand is honest — both
- * operands land on code-point boundaries, so their max does too.
- *
- * [LAW:single-enforcer] `cellFit` documents that its caller must choose between
- * force-taking and skipping; this is that choice, made once. It was made twice
- * before and the copies drifted — the textarea's soft wrap force-took,
- * `chopCells` did neither and hung.
- */
-export function cellStepFrom(text, startCU, cap) {
-    return asCodePoint(Math.max(cellFitFrom(text, startCU, cap), nextCodePoint(text, startCU)));
-}
-/**
- * Returns the largest code-unit offset into `content` whose prefix has
- * cell width ≤ `cellCol`. When `cellCol` falls mid-wide-character the
- * function stops before that character (never advances into it).
- * Clamps to `content.length` if `cellCol` exceeds the string's total
- * cell width.
- *
- * This is the inverse of `cellLen(content.slice(0, codeUnit))` — given a
- * visual column, return the corresponding string index.
- *
- * Returns `CodePoint` because `for...of` iteration always stops on a
- * code-point boundary.
- */
-export function cellColToCodeUnitOffset(content, cellCol) {
-    let w = 0;
-    let i = 0;
-    for (const ch of content) {
-        if (w >= cellCol)
-            break;
-        const cw = cellLen(ch);
-        if (w + cw > cellCol)
-            break;
-        w += cw;
-        i += ch.length;
-    }
-    return asCodePoint(i);
-}
-/**
- * Advance one full Unicode code point from `cu`, returning the code-unit
- * offset of the start of the *next* code point. Returns `s.length` when
- * already at or past the end.
- *
- * Handles surrogate pairs: when the code point at `cu` is a supplementary
- * character (U+10000…U+10FFFF) it occupies 2 UTF-16 code units, so the
- * returned offset advances by 2.
- */
-export function nextCodePoint(s, cu) {
-    if (cu >= s.length)
-        return asCodePoint(s.length);
-    const cp = s.codePointAt(cu);
-    return asCodePoint(cu + (cp > 0xFFFF ? 2 : 1));
-}
-/**
- * Step back one full Unicode code point from `cu`, returning the code-unit
- * offset of the start of the *previous* code point. Returns 0 when already
- * at the start.
- *
- * Handles surrogate pairs: when the code unit at `cu - 1` is a low surrogate
- * AND the code unit at `cu - 2` is a high surrogate, steps back 2 code units.
- * Unpaired surrogates are treated as 1-CU characters.
- */
-export function prevCodePoint(s, cu) {
-    if (cu <= 0)
-        return asCodePoint(0);
-    const low = s.charCodeAt(cu - 1);
-    if (low >= 0xDC00 && low <= 0xDFFF && cu >= 2) {
-        const high = s.charCodeAt(cu - 2);
-        if (high >= 0xD800 && high <= 0xDBFF)
-            return asCodePoint(cu - 2);
-    }
-    return asCodePoint(cu - 1);
-}
-// --- internal ---
-function cropToWidth(text, targetWidth) {
-    let width = 0;
-    let i = 0;
-    // Use the string's code point iterator to handle surrogate pairs
-    for (const char of text) {
-        const charWidth = cellLen(char);
-        if (width + charWidth > targetWidth)
-            break;
-        width += charWidth;
-        i += char.length;
-    }
-    const cropped = text.slice(0, i);
-    // Pad if we couldn't hit the exact width (wide char boundary)
-    const diff = targetWidth - width;
-    return diff > 0 ? cropped + " ".repeat(diff) : cropped;
-}

package/dist/core/color.d.ts

@@ -1,229 +0,0 @@
-/**
- * Terminal color representation, parsing, downgrading, and ANSI code generation.
- */
-/**
- * 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
- * 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;
-export declare class ColorTable {
-    private readonly colors;
-    private readonly firstIndex;
-    private readonly matchCache;
-    private readonly readableCache;
-    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;
-    /**
-     * 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;
-    /**
-     * 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?: NodeJS.ProcessEnv;
-    /** Whether output is going to a real terminal. Defaults to `process.stdout?.isTTY`. */
-    isTTY?: boolean;
-}
-/**
- * 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;
-/**
- * Resolve a string spec into a `ColorDepth` (or `null` for no color).
- *
- * `"auto"` triggers env-based detection; all other recognized specs are
- * direct table lookups against `STRING_TO_DEPTH`. Throws on unknown specs
- * — silent fallback would mask user typos.
- *
- * [LAW:single-enforcer] All string→ColorDepth resolution flows through here.
- */
-export declare function resolveColorSystem(spec: string, 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
-     * and the default colour 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;
-    /**
-     * Parse a color string. Cached — identical strings return the same instance.
-     */
-    static parse(colorString: string): ColorSpec;
-    private performDowngrade;
-}
-export declare function parseRgbHex(hex: string): ColorRgba;
-export declare function parseRgbaHex(hex: string): ColorRgba;
-export declare function blendRgb(color1: ColorRgba, color2: ColorRgba, crossFade?: number): ColorRgba;
-/**
- * A terminal theme — surface/foreground baseline, the ANSI 16/256 LUT, and a
- * semantic palette.
- *
- * **`ansiColors` is the canonical ANSI table, not a per-theme override.** All
- * preset themes in this codebase use `STANDARD_TABLE` for `ansiColors`. Theme
- * identity lives entirely in `palette` (primary, accent, text-*, surface, ...);
- * `ColorSpec.parse("red")` is intentionally consistent across themes — same
- * design as Textual itself, which models theming at the truecolor/semantic
- * layer rather than overloading the ANSI 16. Custom callers building bespoke
- * themes that *do* want to retint ANSI 16 are free to pass their own
- * `ColorTable`; that path is supported but not how the built-in presets work.
- */
-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;
-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[];