@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/core/cells.js

@@ -0,0 +1,287 @@
+/**
+ * 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;
+}
+// [LAW:no-shared-mutable-globals] A private memo, written only by `graphemes`.
+let segmenter;
+/**
+ * The grapheme clusters of `text`, in order: the unit `string-width` measures,
+ * and so the unit `cellLen` of a whole string is the sum of. Summing `cellLen`
+ * over code points instead disagrees with it on every glyph built from several:
+ * `❤️` is 1 + 0 by code point and 2 as a cluster, `👨‍👩‍👧` is 6 and 2, and a cut
+ * between two of its code points leaves half a glyph.
+ */
+export function graphemes(text) {
+    segmenter ??= new Intl.Segmenter(undefined, { granularity: "grapheme" });
+    return Array.from(segmenter.segment(text), (s) => s.segment);
+}
+/**
+ * Returns the largest prefix of `text` whose cell width fits within `cap` cells,
+ * cut between grapheme clusters. No padding — the returned string may be
+ * narrower than `cap` when the next glyph is wide and would overshoot. Never
+ * wider than `cap` cells.
+ *
+ * When the first glyph already exceeds `cap` cells, returns "" (the caller
+ * must decide whether to force-take the glyph or skip it).
+ */
+export function cellFit(text, cap) {
+    return fitClusters(graphemes(text), cap).join("");
+}
+/** `cellFit` from the other end: the largest suffix of `text` within `cap` cells. */
+export function cellFitEnd(text, cap) {
+    return fitClusters(graphemes(text).reverse(), cap).reverse().join("");
+}
+function fitClusters(clusters, cap) {
+    let w = 0;
+    let n = 0;
+    for (const cluster of clusters) {
+        const cw = cellLen(cluster);
+        if (w + cw > cap)
+            break;
+        w += cw;
+        n++;
+    }
+    return clusters.slice(0, n);
+}
+/**
+ * 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

@@ -0,0 +1,246 @@
+/**
+ * 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;
+/**
+ * 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: string | ColorDepth | null, options?: DetectColorOptions): Destination;
+/**
+ * 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 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;
+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[];