@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/core/strip.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Strip + Joiner — edge-aware horizontal layout primitive.
+ *
+ * A `Strip` renders a horizontal sequence of styled items with a `Joiner`
+ * deciding how each transition between adjacent items looks. The joiner is
+ * a pure function of `(leftItem | null, rightItem | null) -> Renderable`,
+ * so endpoint joins (the start and end of the strip) are explicit positions
+ * in the protocol — the joiner names what an endpoint looks like rather than
+ * the strip guessing.
+ *
+ * [LAW:one-source-of-truth] The render walk
+ *   joiner(null, items[0]), items[0],
+ *   joiner(items[0], items[1]), items[1], ...,
+ *   joiner(items[N-1], null)
+ * is the single authority for how strips lay out. Every joiner participates
+ * in the same protocol; "look up the previous segment's bg" is no longer a
+ * powerline-specific hack but the contract every joiner shares.
+ *
+ * [LAW:locality-or-seam] The joiner protocol asks each item only for its
+ * *edge* style — the column adjacent to the joiner — not for a single
+ * whole-item style. This pushes the bg-uniformity requirement out of the
+ * cell type and into the narrowest place that actually needs it: the column
+ * boundary. Items with uniform styling report the same style at both edges;
+ * items with varying styling report the actual boundary column. There is no
+ * single-style invariant on the cell type — the terminal supports per-column
+ * styling, so the cell type does too.
+ */
+import { Segment } from "./segment.js";
+import { Style } from "./style.js";
+import { type Measurable, type Renderable, type RenderOptions } from "./protocol.js";
+/**
+ * Items in a `Strip` expose their per-edge style so joiners can paint the
+ * transition glyph at each boundary.
+ *
+ * `edgeStyle("left", options)` reports the style of the item's leftmost cell
+ * column; `edgeStyle("right", options)` reports the rightmost. Joiners read
+ * only these — the item's interior may carry any per-column variation without
+ * breaking the join.
+ *
+ * The edge is asked in a render, with that render's options, because a style
+ * name only becomes a colour against the render's theme. A joiner therefore
+ * reads edges inside the `render` of what it returns, never in `join`.
+ */
+export interface StyledRenderable extends Renderable {
+    edgeStyle(side: "left" | "right", options: RenderOptions): Style;
+}
+export interface Joiner<T extends StyledRenderable = StyledRenderable> {
+    /**
+     * `left === null` marks the start endpoint; `right === null` marks the end
+     * endpoint. The joiner decides what an endpoint looks like — typically
+     * fg-only with no bg so the strip blends into the terminal background.
+     */
+    join(left: T | null, right: T | null): Renderable;
+}
+export declare class Strip<T extends StyledRenderable = StyledRenderable> implements Renderable, Measurable {
+    readonly items: readonly T[];
+    readonly joiner: Joiner<T>;
+    constructor(items: readonly T[], joiner: Joiner<T>);
+    render(options: RenderOptions): Iterable<Segment>;
+    /**
+     * [LAW:one-source-of-truth] The width of the one row it draws, and that is
+     * both bounds: the row never wraps and no item is offered less than the whole
+     * width, so there is no narrower strip to report as a minimum. Read off the
+     * drawing rather than summed from the items' measurements, which describe
+     * how an item could be drawn, not how the walk draws it.
+     */
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}
+/**
+ * The least ΔE_OK two neighbouring backgrounds must differ by for the powerline
+ * arrow between them to be seen. Below it the arrow is drawn in a colour the
+ * eye cannot tell from its own background, so the joiner draws the divider
+ * instead. Twice the ~.02 threshold of a visible difference, because a seam is
+ * one cell wide.
+ */
+export declare const SEAM_MIN_DELTA_E = 0.04;
+export interface PowerlineJoinerOptions {
+    /** Glyph for every join between two coloured items. */
+    glyph: string;
+    /**
+     * Glyph drawn between neighbours whose backgrounds the eye cannot tell apart,
+     * in the left item's text colour — the arrow itself would vanish into the
+     * shared background.
+     */
+    divider: string;
+    /**
+     * Glyph for every join a coloured item is entered from nothing — the strip's
+     * start, or a colourless left neighbour — painted in the right item's
+     * background. `""` begins a coloured run flat.
+     */
+    lead: string;
+    /**
+     * Glyph for every join a coloured item leaves into nothing — the strip's end,
+     * or a colourless right neighbour — painted in the left item's background.
+     * `""` ends a coloured run flat.
+     */
+    tail: string;
+}
+/**
+ * The powerline set: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow),
+ * led by U+E0D7 (Nerd Fonts ple-left_hard_divider_inverse, the right-arrow's
+ * inverse) and tailed by the arrow itself. The lead leaves empty a triangle
+ * whose base is its cell's left edge and whose point touches the first item, so
+ * the run opens notched — as if an arrow before it pointed in — rather than
+ * with a shape pointing out. The notch is the terminal's own background showing
+ * through, never a colour painted to imitate it, so it matches under a
+ * translucent terminal background too. The lead is a Powerline Extra glyph: a
+ * classic powerline font lacks it.
+ */
+export declare const POWERLINE_JOINER_GLYPHS: Readonly<PowerlineJoinerOptions>;
+export declare class PowerlineJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
+    private readonly _glyphs;
+    constructor(options?: PowerlineJoinerOptions);
+    join(left: T | null, right: T | null): Renderable;
+}
+export interface CapsuleJoinerOptions {
+    /** Left-cap glyph (default: U+E0B6, powerline rounded left). */
+    left?: string;
+    /** Right-cap glyph (default: U+E0B4, powerline rounded right). */
+    right?: string;
+    /** Separator inserted between adjacent capsules in the middle position. */
+    separator?: string;
+}
+export declare class CapsuleJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
+    private readonly _caps;
+    private readonly _separator;
+    constructor(options?: CapsuleJoinerOptions);
+    _emit(left: T | null, right: T | null, options: RenderOptions): Iterable<Segment>;
+    join(left: T | null, right: T | null): Renderable;
+}
+export interface PlainJoinerOptions {
+    separator?: string;
+    style?: Style;
+}
+export declare class PlainJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
+    private readonly _separator;
+    private readonly _style;
+    constructor(options?: PlainJoinerOptions);
+    join(left: T | null, right: T | null): Renderable;
+}
+export interface GradientJoinerOptions {
+    /** Number of cells between adjacent items (default: 4). */
+    steps?: number;
+}
+export declare class GradientJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
+    private readonly _steps;
+    constructor(options?: GradientJoinerOptions);
+    join(left: T | null, right: T | null): Renderable;
+}

package/dist/core/strip.js

@@ -0,0 +1,326 @@
+/**
+ * Strip + Joiner — edge-aware horizontal layout primitive.
+ *
+ * A `Strip` renders a horizontal sequence of styled items with a `Joiner`
+ * deciding how each transition between adjacent items looks. The joiner is
+ * a pure function of `(leftItem | null, rightItem | null) -> Renderable`,
+ * so endpoint joins (the start and end of the strip) are explicit positions
+ * in the protocol — the joiner names what an endpoint looks like rather than
+ * the strip guessing.
+ *
+ * [LAW:one-source-of-truth] The render walk
+ *   joiner(null, items[0]), items[0],
+ *   joiner(items[0], items[1]), items[1], ...,
+ *   joiner(items[N-1], null)
+ * is the single authority for how strips lay out. Every joiner participates
+ * in the same protocol; "look up the previous segment's bg" is no longer a
+ * powerline-specific hack but the contract every joiner shares.
+ *
+ * [LAW:locality-or-seam] The joiner protocol asks each item only for its
+ * *edge* style — the column adjacent to the joiner — not for a single
+ * whole-item style. This pushes the bg-uniformity requirement out of the
+ * cell type and into the narrowest place that actually needs it: the column
+ * boundary. Items with uniform styling report the same style at both edges;
+ * items with varying styling report the actual boundary column. There is no
+ * single-style invariant on the cell type — the terminal supports per-column
+ * styling, so the cell type does too.
+ */
+import { Segment } from "./segment.js";
+import { Style } from "./style.js";
+import { ColorDepth, ColorSpec, SURFACE_BLACK } from "./color.js";
+import { Oklch } from "./oklch.js";
+import { drawable } from "./protocol.js";
+// --- Strip ---
+export class Strip {
+    items;
+    joiner;
+    constructor(items, joiner) {
+        this.items = items;
+        this.joiner = joiner;
+    }
+    *render(options) {
+        const items = this.items;
+        if (items.length === 0)
+            return;
+        // [LAW:dataflow-not-control-flow] The walk is the same shape every render:
+        // start-cap, item, mid-join, item, ..., item, end-cap. Variability lives
+        // in `items` and in what the joiner emits at each position — never in
+        // whether a join runs.
+        //
+        // The row sits its items side by side, so none is handed a justify: a
+        // `left` fills the canvas, and the first item would pad over the rest of
+        // the row. Where the row sits in the width is its container's to say.
+        const row = { ...options, justify: undefined };
+        yield* this.joiner.join(null, items[0]).render(row);
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            yield* item.render(row);
+            const next = i + 1 < items.length ? items[i + 1] : null;
+            yield* this.joiner.join(item, next).render(row);
+        }
+        // [LAW:one-source-of-truth] `Strip`'s sibling `FlexStrip` ends every line
+        // it emits, including the last, and the other block-level renderables
+        // (`Panel`/`Rule`/`Table` structurally, `RichText` via `end`) do too — so
+        // `Group` can emit children back to back with nothing in between
+        // (docs/group.md). A `Strip` that left its last line open broke only
+        // under composition: printed alone, Console's own "close whatever the
+        // renderable left open" step (console.ts) papered over it, and a `Group`
+        // of a Strip and a RichText ran the RichText onto the Strip's line
+        // instead of below it. `LINE_ENDS` in test/seam/line-ends.ts is the list
+        // of which renderables end their own line and which are fragments.
+        yield Segment.line();
+    }
+    /**
+     * [LAW:one-source-of-truth] The width of the one row it draws, and that is
+     * both bounds: the row never wraps and no item is offered less than the whole
+     * width, so there is no narrower strip to report as a minimum. Read off the
+     * drawing rather than summed from the items' measurements, which describe
+     * how an item could be drawn, not how the walk draws it.
+     */
+    measure(options) {
+        let width = 0;
+        for (const segment of this.render(options))
+            width += segment.cellLength;
+        return { minimum: width, maximum: width };
+    }
+}
+// --- Helpers ---
+const EMPTY = {
+    *render(_options) {
+        // intentionally empty
+    },
+};
+/** A renderable whose segments are computed from the options it is rendered with. */
+function deferred(emit) {
+    return { render: emit };
+}
+// Endpoint and powerline join glyphs paint the adjacent item's edge bg
+// *as* their fg. If the edge has no bgcolor, the glyph degrades to the
+// default fg — which renders as nothing visible against the terminal
+// background, the right outcome for an unstyled edge.
+function bgAsFg(edge) {
+    return new Style({ color: edge.bgcolor });
+}
+// A bg with a real colour to paint. `undefined` (no bg) and the terminal
+// DEFAULT colour (transparent — identical to the terminal background) are the
+// two representations of "nothing to paint"; the powerline separator treats
+// them the same, so the gate cannot be fooled by an explicit `… on default`.
+function paintableBg(bg) {
+    return bg !== undefined && !bg.isDefault ? bg : undefined;
+}
+// A cap, arrow or gradient is its cell continuing: that cell's ground as the
+// writer draws it (`Style.drawnColors`, onto the terminal's black), so a
+// translucent ground is not composited a second time over whatever it enters.
+function drawnGround(bg) {
+    return bg.flattenAlpha(SURFACE_BLACK);
+}
+// A cap is its glyph in its cell's ground, and "" is a flat end: no glyph, so
+// no segment — the same output as a join with nothing to paint.
+function* cap(glyph, bg) {
+    if (glyph !== "")
+        yield new Segment(glyph, new Style({ color: drawnGround(bg) }));
+}
+// --- PowerlineJoiner ---
+/**
+ * The least ΔE_OK two neighbouring backgrounds must differ by for the powerline
+ * arrow between them to be seen. Below it the arrow is drawn in a colour the
+ * eye cannot tell from its own background, so the joiner draws the divider
+ * instead. Twice the ~.02 threshold of a visible difference, because a seam is
+ * one cell wide.
+ */
+export const SEAM_MIN_DELTA_E = 0.04;
+// An arrow the eye cannot tell from the ground it is drawn on. What is
+// measured is what is drawn — `Style.drawnColors`, the colours the writer
+// encodes: the arrow's colour flattened onto its ground and the ground onto
+// the terminal's black, both downgraded to the depth the render encodes at,
+// so two grounds 256 colours round to one cube entry are the one entry they
+// render as. A colour whose RGB is the terminal theme's own (ANSI 0–15, a
+// blend reaching one) has no value here, so two of them are the same only
+// when they are one expression: the same palette slot — its `number`, never
+// the name or the depth that spells it ("red", "color(1)", an EIGHT_BIT spec
+// on 0–15 are one slot) — or the same blend, whose name spells each end by its
+// slot for the same reason.
+function vanishes(arrow, colorSystem) {
+    // No colour emitted draws nothing to tell apart; measure what was handed.
+    const { color, bgcolor } = arrow.drawnColors(colorSystem ?? ColorDepth.TRUECOLOR);
+    if (color === undefined || bgcolor === undefined)
+        return false;
+    const av = color.fixedValue;
+    const bv = bgcolor.fixedValue;
+    return av !== undefined && bv !== undefined
+        ? Oklch.fromRgba(av).deltaE(Oklch.fromRgba(bv)) < SEAM_MIN_DELTA_E
+        : color.number !== undefined ? color.number === bgcolor.number : color.name === bgcolor.name;
+}
+/**
+ * The powerline set: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow),
+ * led by U+E0D7 (Nerd Fonts ple-left_hard_divider_inverse, the right-arrow's
+ * inverse) and tailed by the arrow itself. The lead leaves empty a triangle
+ * whose base is its cell's left edge and whose point touches the first item, so
+ * the run opens notched — as if an arrow before it pointed in — rather than
+ * with a shape pointing out. The notch is the terminal's own background showing
+ * through, never a colour painted to imitate it, so it matches under a
+ * translucent terminal background too. The lead is a Powerline Extra glyph: a
+ * classic powerline font lacks it.
+ */
+export const POWERLINE_JOINER_GLYPHS = Object.freeze({
+    glyph: "\ue0b0",
+    divider: "\ue0b1",
+    lead: "\ue0d7",
+    tail: "\ue0b0",
+});
+/** The powerline set in ASCII: an arrow for every join, runs begun flat. */
+const ASCII_POWERLINE_GLYPHS = Object.freeze({
+    glyph: ">",
+    divider: ">",
+    lead: "",
+    tail: ">",
+});
+const powerlineGlyphs = ({ glyph, divider, lead, tail }) => glyph + divider + lead + tail;
+export class PowerlineJoiner {
+    _glyphs;
+    constructor(options = POWERLINE_JOINER_GLYPHS) {
+        this._glyphs = options;
+    }
+    join(left, right) {
+        // [LAW:dataflow-not-control-flow] One table for all three positions (start
+        // cap, mid-join, end cap), read off which side has a colour to paint. The
+        // endpoints are not control-flow special cases; they are the DATA cases
+        // where a neighbour (hence its bg) is absent:
+        //   • both bgs — the arrow in the LEFT bg (the colour bleeding rightward)
+        //     over the RIGHT bg.
+        //   • left bg only — the end cap, OR a coloured item before a colourless
+        //     one — the tail bleeds the left colour out over the terminal
+        //     background (fg = left bg, no bg).
+        //   • right bg only — the start cap, OR a colourless item before a coloured
+        //     one — the lead: the right colour painted over the terminal
+        //     background in the lead's shape (fg = right bg, no bg).
+        //   • neither — nothing to paint, so the join yields nothing.
+        // Equal REAL bgs still emit: a same-bg seam between two distinct items is a
+        // structural boundary, never suppressed. The arrow would be drawn in its own
+        // background colour there and vanish, so the seam is the DIVIDER instead, in
+        // the left item's text colour — the vim-airline convention for neighbours
+        // that share a background. "Equal" is perceptual (SEAM_MIN_DELTA_E) and
+        // measured on the colours the terminal draws at `options.colorSystem`: an
+        // arrow a hair off its background is as invisible as one exactly on it,
+        // and two backgrounds 256 colours round to one entry are one background.
+        // Background colour is paint, not structure; its ABSENCE (nothing to paint)
+        // is the only thing that elides the separator, and that is paint logic.
+        // "Absent" = no bg OR the terminal default (transparent) — paintableBg folds
+        // both to undefined so an explicit `… on default` cannot smuggle a separator.
+        const glyphs = this._glyphs;
+        return deferred(function* (options) {
+            const { glyph, divider, lead, tail } = drawable(options, glyphs, ASCII_POWERLINE_GLYPHS, powerlineGlyphs);
+            const leftEdge = left?.edgeStyle("right", options);
+            const leftBg = paintableBg(leftEdge?.bgcolor);
+            const rightBg = paintableBg(right?.edgeStyle("left", options).bgcolor);
+            if (leftBg === undefined) {
+                if (rightBg !== undefined)
+                    yield* cap(lead, rightBg);
+                return;
+            }
+            if (rightBg === undefined) {
+                yield* cap(tail, leftBg);
+                return;
+            }
+            const arrow = new Style({ color: drawnGround(leftBg), bgcolor: rightBg });
+            // The divider is the left item's text on the left item's own ground,
+            // so it reads exactly as well as that item's text does, at any depth.
+            yield vanishes(arrow, options.colorSystem)
+                ? new Segment(divider, new Style({ color: leftEdge?.color, bgcolor: leftBg }))
+                : new Segment(glyph, arrow);
+        });
+    }
+}
+const ASCII_CAPS = { left: "(", right: ")" };
+const capGlyphs = ({ left, right }) => left + right;
+export class CapsuleJoiner {
+    _caps;
+    _separator;
+    constructor(options) {
+        this._caps = { left: options?.left ?? "", right: options?.right ?? "" };
+        this._separator = options?.separator ?? " ";
+    }
+    *_emit(left, right, options) {
+        const caps = drawable(options, this._caps, ASCII_CAPS, capGlyphs);
+        const separator = drawable(options, this._separator, " ");
+        if (left === null && right === null)
+            return;
+        if (left === null) {
+            yield new Segment(caps.left, bgAsFg(right.edgeStyle("left", options)));
+            return;
+        }
+        if (right === null) {
+            yield new Segment(caps.right, bgAsFg(left.edgeStyle("right", options)));
+            return;
+        }
+        // Middle: close the left capsule, separator (unstyled), open the right.
+        yield new Segment(caps.right, bgAsFg(left.edgeStyle("right", options)));
+        if (separator.length > 0)
+            yield new Segment(separator);
+        yield new Segment(caps.left, bgAsFg(right.edgeStyle("left", options)));
+    }
+    join(left, right) {
+        return deferred((options) => this._emit(left, right, options));
+    }
+}
+export class PlainJoiner {
+    _separator;
+    _style;
+    constructor(options) {
+        this._separator = options?.separator ?? " | ";
+        this._style = options?.style ?? Style.parse("dim");
+    }
+    join(left, right) {
+        // Endpoints are empty — a fixed separator has no natural cap.
+        if (left === null || right === null)
+            return EMPTY;
+        const separator = this._separator;
+        const style = this._style;
+        return deferred((options) => [new Segment(drawable(options, separator, " | "), style)]);
+    }
+}
+/**
+ * Half-block dithering glyph: paints the cell's left half with the foreground
+ * colour and the right half with the background colour. Lets each cell carry
+ * two colour samples — `2 * steps` samples in `steps` cells — so the gradient
+ * looks twice as smooth as one-colour-per-cell at the same width.
+ */
+const HALF_BLOCK = "▌"; // ▌
+export class GradientJoiner {
+    _steps;
+    constructor(options) {
+        this._steps = options?.steps ?? 4;
+    }
+    join(left, right) {
+        // [LAW:dataflow-not-control-flow] Endpoints have no opposite anchor to
+        // interpolate toward — the data (a missing neighbor) makes the gradient
+        // empty. Same for edges with nothing to paint: nothing to blend between.
+        if (left === null || right === null)
+            return EMPTY;
+        const steps = this._steps;
+        return deferred(function* (options) {
+            const lbg = paintableBg(left.edgeStyle("right", options).bgcolor);
+            const rbg = paintableBg(right.edgeStyle("left", options).bgcolor);
+            if (!lbg || !rbg)
+                return;
+            const from = drawnGround(lbg);
+            const to = drawnGround(rbg);
+            // An ASCII cell carries one sample, the background: the gradient keeps
+            // its colours at half the resolution.
+            const half = drawable(options, HALF_BLOCK, " ");
+            const samples = 2 * steps;
+            // Midpoint sampling across `2 * steps` half-cell positions: sample j has
+            // t = (j + 0.5) / samples. Cell i takes samples 2i (left half) and 2i+1
+            // (right half). No sample ever equals either anchor.
+            for (let i = 0; i < steps; i++) {
+                const tLeft = (2 * i + 0.5) / samples;
+                const tRight = (2 * i + 1.5) / samples;
+                // Each sample stays a mix of the two grounds, so a theme that draws
+                // `blue` in its own shade draws the ramp from that shade.
+                const fg = ColorSpec.blend(from, to, tLeft);
+                const bg = ColorSpec.blend(from, to, tRight);
+                yield new Segment(half, new Style({ color: fg, bgcolor: bg }));
+            }
+        });
+    }
+}

package/dist/core/style.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Immutable style descriptors — colors, text attributes, links, metadata.
+ */
+import { ColorSpec, ColorDepth } from "./color.js";
+import { type Anchor } from "./anchor.js";
+/**
+ * Canonical text-attribute inventory. Single source of truth consumed by
+ * `Style.parse` / `Style.toString` and the template bindings — adding an
+ * attribute here propagates to every styling surface without a second
+ * list to keep in sync. [LAW:one-source-of-truth]
+ */
+export declare const ATTRIBUTE_NAMES: readonly ["bold", "dim", "italic", "underline", "blink", "blink2", "reverse", "conceal", "strike", "underline2", "frame", "encircle", "overline"];
+export type AttributeName = (typeof ATTRIBUTE_NAMES)[number];
+export declare const ATTRIBUTE_SGR: Record<AttributeName, number>;
+/**
+ * Canonical short-attribute aliases (`b` → `bold`, `i` → `italic`, …).
+ * Single source of truth consumed by `Style.parse` and the template
+ * bindings — adding an alias here makes it available everywhere.
+ * [LAW:one-source-of-truth]
+ */
+export declare const ATTRIBUTE_SHORT_ALIASES: Record<string, AttributeName>;
+export interface StyleOptions {
+    color?: string | ColorSpec;
+    bgcolor?: string | ColorSpec;
+    bold?: boolean;
+    dim?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    blink?: boolean;
+    blink2?: boolean;
+    reverse?: boolean;
+    conceal?: boolean;
+    strike?: boolean;
+    underline2?: boolean;
+    frame?: boolean;
+    encircle?: boolean;
+    overline?: boolean;
+    link?: string;
+    meta?: Record<string, unknown>;
+    anchor?: Anchor;
+}
+export declare class StyleSyntaxError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class Style {
+    readonly color: ColorSpec | undefined;
+    readonly bgcolor: ColorSpec | undefined;
+    readonly bold: boolean | undefined;
+    readonly dim: boolean | undefined;
+    readonly italic: boolean | undefined;
+    readonly underline: boolean | undefined;
+    readonly blink: boolean | undefined;
+    readonly blink2: boolean | undefined;
+    readonly reverse: boolean | undefined;
+    readonly conceal: boolean | undefined;
+    readonly strike: boolean | undefined;
+    readonly underline2: boolean | undefined;
+    readonly frame: boolean | undefined;
+    readonly encircle: boolean | undefined;
+    readonly overline: boolean | undefined;
+    readonly link: string | undefined;
+    readonly meta: Record<string, unknown> | undefined;
+    /**
+     * Where this style's cells sat in the output of whatever drew them; see
+     * `./anchor.ts`. It draws nothing, and it makes two styles that draw alike
+     * unequal, because they came from different places.
+     */
+    readonly anchor: Anchor | undefined;
+    constructor(options?: StyleOptions);
+    get isNull(): boolean;
+    get transparentBackground(): boolean;
+    get backgroundStyle(): Style;
+    /**
+     * This style with `overrides` in place of its own fields.
+     *
+     * [LAW:one-source-of-truth] The field list is the class's own fields, so a
+     * field added to `Style` is carried by every copy without being named here.
+     */
+    private with;
+    get withoutColor(): Style;
+    withLink(link: string | undefined): Style;
+    clearMetaAndLinks(): Style;
+    /**
+     * The same look, drawn from the place `anchor` names, or from nowhere.
+     */
+    withAnchor(anchor: Anchor | undefined): Style;
+    /**
+     * This style on the cell `cells` to the right: its anchor shifted along its
+     * row, or the style itself when it has no anchor.
+     */
+    shiftedBy(cells: number): Style;
+    /**
+     * Merges two styles. `other`'s values take priority.
+     */
+    add(other: Style | undefined): Style;
+    equals(other: Style): boolean;
+    /**
+     * The colours this style puts on screen at `colorSystem`: each flattened
+     * onto what lies beneath it — the background onto the terminal's black, the
+     * foreground onto that background — then downgraded to the depth. The one
+     * account of what a style draws: `toSgrCodes` encodes exactly these, and a
+     * renderable choosing between two ways of drawing measures them.
+     */
+    drawnColors(colorSystem?: ColorDepth): {
+        readonly color: ColorSpec | undefined;
+        readonly bgcolor: ColorSpec | undefined;
+    };
+    /**
+     * Returns the SGR parameter list this style emits (e.g. `"1;31;48;2;0;0;255"`),
+     * or `""` when the style has no SGR contribution. Excludes OSC 8 link bytes —
+     * links are not SGR. The segment encoder (`segmentToString`) wraps it in
+     * `\x1b[...m`; styled text reaches the wire only through that encoder.
+     *
+     * [LAW:one-source-of-truth] One computation of SGR codes.
+     */
+    toSgrCodes(colorSystem: ColorDepth): string;
+    /**
+     * Serializes to a canonical string that round-trips through `Style.parse()`.
+     */
+    toString(): string;
+    static null(): Style;
+    static fromColor(color?: ColorSpec, bgcolor?: ColorSpec): Style;
+    static fromMeta(meta: Record<string, unknown>): Style;
+    static pickFirst(...args: (Style | undefined)[]): Style;
+    static combine(styles: (Style | undefined)[]): Style;
+    static chain(...styles: (Style | undefined)[]): Style;
+    static normalize(definition: string): string;
+    /**
+     * Parse a space-separated style definition. Memoized (`Memo`).
+     *
+     * A definition only: `"bold red"` parses, `"repr.number"` does not. Names
+     * belong to a `Theme`, and `Theme.resolve` is where one is looked up.
+     */
+    static parse(definition: string): Style;
+}
+export declare const NULL_STYLE: Style;
+export declare class StyleStack {
+    private readonly stack;
+    constructor(base?: Style);
+    get current(): Style;
+    push(style: Style): void;
+    pop(): Style;
+}
+/**
+ * A `Style` added over a style name or definition a render has yet to
+ * resolve. Which it is cannot be told before then: a theme's names shadow
+ * definitions (`Theme.resolve`), so the addition waits for the render whose
+ * theme says what `under` stands for, and draws as `under` resolved with
+ * `over` added on top.
+ */
+export interface LayeredStyle {
+    readonly under: string;
+    readonly over: Style;
+}
+/** A style as a RichText stores it, base or span: resolved when it is drawn. */
+export type TextStyle = string | Style | LayeredStyle;
+/**
+ * `over` added to `base`, the outer style winning as `Style.add` has it. A
+ * `Style` base takes the addition now, and so does `""`, the definition that
+ * adds nothing; any other string keeps it as a `LayeredStyle` for the render
+ * that resolves the string.
+ */
+export declare function layerStyle(base: TextStyle, over: Style): TextStyle;
+export declare class Theme {
+    private readonly styles;
+    constructor(definitions?: Record<string, string>, options?: {
+        inherit?: boolean;
+    });
+    get(name: string): Style | undefined;
+    /**
+     * The style a `TextStyle` stands for under this theme: a name this theme
+     * defines, otherwise a definition for `Style.parse`, which throws
+     * `StyleSyntaxError` when the string is neither. A `LayeredStyle` is its
+     * `under` resolved here with its `over` added on top.
+     *
+     * [LAW:one-source-of-truth] The theme is the one map from names to styles.
+     * The lookup stays outside `Style.parse`'s process-wide cache on purpose:
+     * cached there, the first console to resolve `repr.number` would decide it
+     * for every console after it, whatever theme each was given.
+     */
+    resolve(style: TextStyle): Style;
+    has(name: string): boolean;
+}
+export declare const DEFAULT_STYLES: Record<string, Style>;
+/**
+ * The theme a render resolves names against when nothing supplied one — what
+ * a renderable sees outside a `Console`, as in `renderToString`.
+ */
+export declare const DEFAULT_THEME: Theme;