@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/core/strip.js

@@ -27,9 +27,10 @@
  */
 import { Segment } from "./segment.js";
 import { Style } from "./style.js";
-import { ColorDepth, ColorSpec, blendRgb } from "./color.js";
+import { ColorDepth, ColorSpec, SURFACE_BLACK } from "./color.js";
 import { Oklch } from "./oklch.js";
-import { drawable } from "./protocol.js";
+import { cellLen } from "./cells.js";
+import { drawable, getStyle, isAscii } from "./protocol.js";
 // --- Strip ---
 export class Strip {
     items;
@@ -46,12 +47,17 @@ export class Strip {
         // 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.
-        yield* this.joiner.join(null, items[0]).render(options);
+        //
+        // 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(options);
+            yield* item.render(row);
             const next = i + 1 < items.length ? items[i + 1] : null;
-            yield* this.joiner.join(item, next).render(options);
+            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
@@ -61,245 +67,288 @@ export class Strip {
         // 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. (Not every renderable follows this — a `Spinner`
-        // or `ProgressBar` is a line *fragment*, not a block; see
-        // rich-flexstrip-5kf.4cq for the open question of formalizing that split.)
+        // 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 };
+    }
+}
+const PARTS = ["seam", "divider", "lead", "tail"];
+/**
+ * The least ΔE_OK two neighbouring backgrounds must differ by for a seam drawn
+ * between them to be seen. Below it the seam 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;
+function* paintsIn(paint) {
+    yield paint;
+    if ("mix" in paint) {
+        yield* paintsIn(paint.mix[0]);
+        yield* paintsIn(paint.mix[1]);
+    }
 }
-// --- 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 };
+const glyphsOf = (cell) => (typeof cell.glyph === "string" ? [cell.glyph] : cell.glyph.oneOf);
+const cellWidth = (cell) => cellLen(glyphsOf(cell)[0] ?? "");
+const partWidth = (cells) => cells.reduce((width, cell) => width + cellWidth(cell), 0);
+// `raw` as a `Paint`, or refused. `absent` is the neighbour this part may not
+// name, because the part is also drawn where that neighbour does not exist.
+function parsePaint(raw, absent, refuse) {
+    if (raw === "ground")
+        return refuse("mixes ground, whose colour is unknown");
+    const p = (typeof raw === "object" && raw !== null ? raw : {});
+    if ((p.edge === "left" || p.edge === "right") && (p.part === "bg" || p.part === "fg")) {
+        if (p.edge === absent)
+            refuse(`names the ${absent} neighbour, which this part is drawn without`);
+        return Object.freeze({ edge: p.edge, part: p.part });
+    }
+    if (typeof p.role === "string")
+        return Object.freeze({ role: p.role });
+    if (Array.isArray(p.mix) && p.mix.length === 3) {
+        const [from, to, t] = p.mix;
+        if (typeof t !== "number" || !(t >= 0 && t <= 1))
+            refuse(`mixes at ${String(t)}, outside 0..1`);
+        return Object.freeze({ mix: Object.freeze([parsePaint(from, absent, refuse), parsePaint(to, absent, refuse), t]) });
+    }
+    return refuse(`has a colour that is not a Paint: ${JSON.stringify(raw)}`);
 }
-// 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 });
+const parseColor = (raw, absent, refuse) => raw === "ground" ? raw : parsePaint(raw, absent, refuse);
+const ABSENT = { seam: undefined, divider: undefined, lead: "left", tail: "right" };
+function parseList(raw, where) {
+    if (!Array.isArray(raw))
+        throw new Error(`CellJoiner: ${where} is not a list of cells`);
+    return raw.map((cell, i) => {
+        if (typeof cell !== "object" || cell === null)
+            throw new Error(`CellJoiner: ${where}[${i}] is not a cell`);
+        return cell;
+    });
+}
+/**
+ * [LAW:parse-dont-validate] The one place a shape is checked, so every rule
+ * the cell model states is refused at construction and the render reads a
+ * shape that already holds them. A shape is often authored as data — a
+ * consumer's config — so the rules the types state are checked here too, and
+ * what comes back is a frozen copy the caller can no longer change.
+ */
+function parseShape(raw, form) {
+    const parseCells = (part) => Object.freeze(parseList(raw[part], `${form} ${part}`).map((cell, i) => {
+        const refuse = (why) => {
+            throw new Error(`CellJoiner: ${form} ${part}[${i}] ${why}`);
+        };
+        const glyph = cell.glyph;
+        const oneOf = typeof glyph === "object" && glyph !== null ? glyph.oneOf : undefined;
+        if (typeof glyph !== "string" && !(Array.isArray(oneOf) && oneOf.every((g) => typeof g === "string"))) {
+            refuse(`has a glyph that is neither a string nor a oneOf of strings: ${JSON.stringify(glyph)}`);
+        }
+        if (cell.fg === "ground" && cell.bg === "ground")
+            refuse("has ground on both sides");
+        const glyphs = glyphsOf(cell);
+        if (glyphs.length === 0)
+            refuse("has an empty oneOf");
+        if (glyphs.some((glyph) => cellLen(glyph) !== cellWidth(cell)))
+            refuse("has oneOf members of different widths");
+        if (form === "ascii" && !glyphs.every(isAscii))
+            refuse("is not ASCII");
+        return Object.freeze({
+            glyph: typeof cell.glyph === "string" ? cell.glyph : Object.freeze({ oneOf: Object.freeze([...glyphs]) }),
+            fg: parseColor(cell.fg, ABSENT[part], refuse),
+            bg: parseColor(cell.bg, ABSENT[part], refuse),
+        });
+    }));
+    const seam = parseCells("seam");
+    // A divider authored as the seam itself stays the seam, so a render can see
+    // it has no choice to make.
+    const divider = raw.divider === raw.seam ? seam : parseCells("divider");
+    if (partWidth(divider) !== partWidth(seam))
+        throw new Error(`CellJoiner: ${form} divider is not the width of the seam`);
+    return Object.freeze({ seam, divider, lead: parseCells("lead"), tail: parseCells("tail") });
+}
+// Whether any cell of `shape` paints with `side`'s ground.
+const readsGround = (shape, side) => PARTS.flatMap((part) => shape[part]).some((cell) => [cell.fg, cell.bg].some((color) => color !== "ground" && [...paintsIn(color)].some((p) => "edge" in p && p.edge === side && p.part === "bg")));
+function formOf(shape) {
+    return { shape, reads: { left: readsGround(shape, "left"), right: readsGround(shape, "right") } };
 }
 // 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`.
+// two representations of "nothing to paint", so an explicit `… on default`
+// cannot smuggle a seam.
 function paintableBg(bg) {
     return bg !== undefined && !bg.isDefault ? bg : undefined;
 }
-// A cap or arrow is its cell continuing: that cell's ground as the writer draws
-// it, so a translucent ground is not composited a second time over whatever it
-// enters.
+// A neighbour'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 a join cell enters.
 function drawnGround(bg) {
-    return new Style({ bgcolor: bg }).drawnColors().bgcolor;
+    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) has no
-// value here, so two of them are the same only when they are 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).
-function vanishes(arrow, colorSystem) {
-    // No colour emitted draws nothing to tell apart; measure what was handed.
-    const { color, bgcolor } = arrow.drawnColors(colorSystem ?? ColorDepth.TRUECOLOR);
+// A seam 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
+// left ground flattened onto the right and the right 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(leftBg, rightBg, colorSystem) {
+    const { color, bgcolor } = new Style({ color: drawnGround(leftBg), bgcolor: rightBg }).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 === bgcolor.number;
+        : color.number !== undefined ? color.number === bgcolor.number : color.name === bgcolor.name;
+}
+function resolvePaint(paint, edges, options) {
+    if ("edge" in paint) {
+        const edge = edges[paint.edge];
+        if (paint.part === "fg")
+            return edge?.color;
+        const bg = paintableBg(edge?.bgcolor);
+        return bg && drawnGround(bg);
+    }
+    if ("role" in paint)
+        return getStyle(options, paint.role).color;
+    const [from, to, t] = paint.mix;
+    const a = resolvePaint(from, edges, options);
+    const b = resolvePaint(to, edges, options);
+    // A mix with no colour at one end has nothing to blend toward.
+    return a && b && ColorSpec.blend(a, b, t);
 }
+function cellStyle(cell, edges, options) {
+    // [LAW:dataflow-not-control-flow] "ground" is the absence of a colour on its
+    // side; as the fg it is reverse video over the bg colour, so the glyph's ink
+    // is the terminal's own background.
+    if (cell.fg === "ground")
+        return new Style({ color: cell.bg === "ground" ? undefined : resolvePaint(cell.bg, edges, options), reverse: true });
+    const color = resolvePaint(cell.fg, edges, options);
+    return new Style({ color, bgcolor: cell.bg === "ground" ? undefined : resolvePaint(cell.bg, edges, options) });
+}
+const shapeGlyphs = (shape) => PARTS.flatMap((part) => shape[part].flatMap(glyphsOf)).join("");
 /**
- * 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.
+ * The one joiner: what it draws at each join is the `JoinShape` it is given,
+ * so a new joiner is a value, never a class.
+ *
+ * Which part a join draws is read off its two neighbours. A neighbour is
+ * missing at the strip's ends, and counts as missing — an endpoint — when the
+ * shape paints with its ground anywhere and it has none to paint. With both present the
+ * join is the seam, or the divider where the two grounds are drawn as one
+ * colour at `options.colorSystem`; with only the right, the lead; with only
+ * the left, the tail; with neither, nothing.
+ *
+ * `ascii` is the shape an ASCII-only output draws instead, whole.
  */
-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;
+export class CellJoiner {
+    shape;
+    ascii;
+    _forms;
+    constructor(shape, ascii) {
+        this.shape = parseShape(shape, "glyph");
+        this.ascii = parseShape(ascii, "ascii");
+        this._forms = { glyph: formOf(this.shape), ascii: formOf(this.ascii) };
     }
     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 forms = this._forms;
+        return {
+            *render(options) {
+                const { shape: drawn, reads } = drawable(options, forms.glyph, forms.ascii, (form) => shapeGlyphs(form.shape));
+                const edges = { left: left?.edgeStyle("right", options), right: right?.edgeStyle("left", options) };
+                const leftBg = paintableBg(edges.left?.bgcolor);
+                const rightBg = paintableBg(edges.right?.bgcolor);
+                const hasLeft = left !== null && (!reads.left || leftBg !== undefined);
+                const hasRight = right !== null && (!reads.right || rightBg !== undefined);
+                const divides = drawn.divider !== drawn.seam && leftBg !== undefined && rightBg !== undefined && vanishes(leftBg, rightBg, options.colorSystem);
+                const cells = hasLeft && hasRight ? (divides ? drawn.divider : drawn.seam) : hasRight ? drawn.lead : hasLeft ? drawn.tail : [];
+                // A oneOf draws its first member until a join knows its seam index
+                // (rich-joiners-9ntp.bex).
+                for (const cell of cells)
+                    yield new Segment(glyphsOf(cell)[0], cellStyle(cell, edges, options));
+            },
+        };
     }
 }
-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));
-    }
+// --- The four joiners as shapes ---
+const LEFT_BG = { edge: "left", part: "bg" };
+const RIGHT_BG = { edge: "right", part: "bg" };
+const LEFT_FG = { edge: "left", part: "fg" };
+const GROUND = "ground";
+/**
+ * The powerline joiner: U+E0B0 (right-arrow) in the left ground over the
+ * right, divided by U+E0B1 (thin right-arrow) in the left item's text. The
+ * lead is the arrow with the left ground replaced by the terminal's — drawn
+ * in reverse video it leaves a notch whose base is the cell's left edge, inked
+ * in the terminal's background colour. That ink is opaque, so under a
+ * translucent terminal the notch does not let what is behind it through. The
+ * tail is the arrow over the terminal's ground.
+ * ASCII draws `>` everywhere and begins each run flat.
+ */
+export const POWERLINE_JOINER = new CellJoiner({
+    seam: [{ glyph: "", fg: LEFT_BG, bg: RIGHT_BG }],
+    divider: [{ glyph: "", fg: LEFT_FG, bg: LEFT_BG }],
+    lead: [{ glyph: "", fg: GROUND, bg: RIGHT_BG }],
+    tail: [{ glyph: "", fg: LEFT_BG, bg: GROUND }],
+}, {
+    seam: [{ glyph: ">", fg: LEFT_BG, bg: RIGHT_BG }],
+    divider: [{ glyph: ">", fg: LEFT_FG, bg: LEFT_BG }],
+    lead: [],
+    tail: [{ glyph: ">", fg: LEFT_BG, bg: GROUND }],
+});
+function capsule(open, close) {
+    const seam = [
+        { glyph: close, fg: LEFT_BG, bg: GROUND },
+        { glyph: " ", fg: LEFT_FG, bg: GROUND },
+        { glyph: open, fg: RIGHT_BG, bg: GROUND },
+    ];
+    return { seam, divider: seam, lead: [{ glyph: open, fg: RIGHT_BG, bg: GROUND }], tail: [{ glyph: close, fg: LEFT_BG, bg: GROUND }] };
 }
-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)]);
-    }
+/**
+ * Rounded pills: each run opened by U+E0B6 and closed by U+E0B4, both in its
+ * ground over the terminal's, a space between pills. ASCII draws `(` and `)`.
+ */
+export const CAPSULE_JOINER = new CellJoiner(capsule("", ""), capsule("(", ")"));
+const PLAIN_SEAM = [{ glyph: " | ", fg: { role: "strip.separator" }, bg: GROUND }];
+const PLAIN = { seam: PLAIN_SEAM, divider: PLAIN_SEAM, lead: [], tail: [] };
+/**
+ * ` | ` between every pair of items, in the theme's `strip.separator` colour;
+ * nothing at the ends. Its shape names no neighbour, so it joins items with no
+ * ground too.
+ */
+export const PLAIN_JOINER = new CellJoiner(PLAIN, PLAIN);
+function gradient(steps, glyph) {
+    // Midpoint sampling across `2 * steps` half-cell positions: cell i takes
+    // samples 2i (its ink, the left half) and 2i+1 (its ground, the right half),
+    // so no sample equals either neighbour's ground.
+    const samples = 2 * steps;
+    const seam = Array.from({ length: steps }, (_, i) => ({
+        glyph,
+        fg: { mix: [LEFT_BG, RIGHT_BG, (2 * i + 0.5) / samples] },
+        bg: { mix: [LEFT_BG, RIGHT_BG, (2 * i + 1.5) / samples] },
+    }));
+    return { seam, divider: seam, lead: [], tail: [] };
 }
 /**
- * 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.
+ * A ramp of `steps` cells from the left ground to the right. Each cell is the
+ * half block U+258C, ink on its left half and ground on its right, so it
+ * carries two samples; ASCII draws a space, keeping the grounds alone. Nothing
+ * at the ends, or beside a neighbour with no ground — there is no colour to
+ * ramp toward.
  */
-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 lacking a bgcolor: nothing to blend between.
-        if (left === null || right === null)
-            return EMPTY;
-        const steps = this._steps;
-        return deferred(function* (options) {
-            const lbg = left.edgeStyle("right", options).bgcolor;
-            const rbg = right.edgeStyle("left", options).bgcolor;
-            if (!lbg || !rbg)
-                return;
-            const lTrip = lbg.getTruecolor();
-            const rTrip = rbg.getTruecolor();
-            // 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;
-                const fg = ColorSpec.fromRgba(blendRgb(lTrip, rTrip, tLeft));
-                const bg = ColorSpec.fromRgba(blendRgb(lTrip, rTrip, tRight));
-                yield new Segment(half, new Style({ color: fg, bgcolor: bg }));
-            }
-        });
-    }
+export function gradientJoiner(steps = 4) {
+    return new CellJoiner(gradient(steps, "▌"), gradient(steps, " "));
 }

package/dist/core/style.d.ts

@@ -108,8 +108,7 @@ export declare class Style {
     /**
      * 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 (`segmentsToString`) uses this
-     * string as the group key for adjacent-same-style coalescing and wraps it in
+     * 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.
@@ -127,7 +126,7 @@ export declare class Style {
     static chain(...styles: (Style | undefined)[]): Style;
     static normalize(definition: string): string;
     /**
-     * Parse a space-separated style definition. Cached.
+     * 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.
@@ -142,6 +141,26 @@ export declare class StyleStack {
     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?: {
@@ -149,16 +168,17 @@ export declare class Theme {
     });
     get(name: string): Style | undefined;
     /**
-     * The style a `string | Style` stands for under this theme: a name this
-     * theme defines, otherwise a definition for `Style.parse`, which throws
-     * `StyleSyntaxError` when the string is neither.
+     * 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: string | Style): Style;
+    resolve(style: TextStyle): Style;
     has(name: string): boolean;
 }
 export declare const DEFAULT_STYLES: Record<string, Style>;