@promptctl/rich-js 0.19.0 → 0.21.0

package/dist/core/strip.js

@@ -29,7 +29,66 @@ 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";
+import { cellLen } from "./cells.js";
+import { fnv1a } from "./fnv1a.js";
+import { drawable, getStyle, isAscii } from "./protocol.js";
+/**
+ * The owner every cell a strip's joiner draws is stamped with
+ * (`Segment.anchorLines`), whatever the joiner: a seam is told by what drew
+ * it, never by its glyph, which an ASCII joiner draws otherwise and a lead may
+ * not draw at all. An effect reads it to leave a seam out of the words it
+ * keeps legible (`drawnOf`, `../renderables/effect.ts`).
+ *
+ * Inside it, every cell a `CellJoiner` draws names whose colour each of its
+ * two sides shows (`colorsOwnedBy`). One seam cell can show two neighbours —
+ * a powerline arrow is inked in the fill it points out of, over the fill it
+ * points into — so a cell has no single owner; each side has one.
+ */
+export const JOIN = Object.freeze({ name: "join" });
+/**
+ * Whose colour each side of a join cell shows on screen, its ink and its
+ * ground: the neighbour whose edge a `Paint` names, or `null` for a role, a
+ * mix or the terminal's ground, which are no neighbour's.
+ */
+class ColorOwners {
+    fg;
+    bg;
+    constructor(fg, bg) {
+        this.fg = fg;
+        this.bg = bg;
+    }
+}
+/**
+ * Which of a cell's two colours on screen are `owner`'s: both, for a cell
+ * `owner` drew, itself or through an owner nested in its output; for a cell a
+ * `CellJoiner` drew, the sides shown in `owner`'s colour.
+ */
+export function colorsOwnedBy(anchor, owner) {
+    for (let level = anchor; level; level = level.inner) {
+        if (level.owner === owner)
+            return { fg: true, bg: true };
+        if (level.owner instanceof ColorOwners)
+            return { fg: level.owner.fg === owner, bg: level.owner.bg === owner };
+    }
+    return { fg: false, bg: false };
+}
+/**
+ * [LAW:single-enforcer] What `joiner` draws at one join, every cell stamped
+ * as `JOIN`'s: the one way `Strip` and `FlexStrip` draw a join.
+ */
+export function drawJoin(joiner, left, right, context) {
+    const join = joiner.join(left, right, context);
+    return { render: (options) => Segment.anchorLines([[...join.render(options)]], JOIN)[0] };
+}
+/**
+ * [LAW:single-enforcer] What `item` draws, every cell stamped as the item's,
+ * so whoever holds the composed row reads which item drew a cell however the
+ * row was laid out or wrapped: the one way `Strip` and `FlexStrip` draw an
+ * item.
+ */
+export function drawItem(item) {
+    return { render: (options) => Segment.anchorLines([[...item.render(options)]], item)[0] };
+}
 // --- Strip ---
 export class Strip {
     items;
@@ -51,12 +110,12 @@ export class Strip {
         // `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);
+        yield* drawJoin(this.joiner, null, items[0], { index: 0 }).render(row);
         for (let i = 0; i < items.length; i++) {
             const item = items[i];
-            yield* item.render(row);
+            yield* drawItem(item).render(row);
             const next = i + 1 < items.length ? items[i + 1] : null;
-            yield* this.joiner.join(item, next).render(row);
+            yield* drawJoin(this.joiner, item, next, { index: i + 1 }).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
@@ -84,65 +143,138 @@ export class Strip {
         return { minimum: width, maximum: width };
     }
 }
-// --- Helpers ---
-const EMPTY = {
-    *render(_options) {
-        // intentionally empty
-    },
+const PARTS = ["seam", "divider", "lead", "tail"];
+/**
+ * The least ΔE_OK a seam cell's ink must differ from its own ground by for the
+ * seam to be seen. Below it the eye cannot tell the ink from the ground,
+ * 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]);
+    }
+}
+const glyphsOf = (cell) => (typeof cell.glyph === "string" ? [cell.glyph] : cell.glyph.oneOf);
+// An integer hash, so every engine picks the same member, scaled from its high
+// bits — FNV-1a's low bits barely mix — so the pick is in range by
+// construction. The part is in the key so a wrap's tail and lead, which share
+// an index, are picked independently.
+const pickGlyph = (cell, part, index, at) => {
+    const glyphs = glyphsOf(cell);
+    return glyphs[Math.floor((parseInt(fnv1a(`${part}:${index}:${at}`), 16) / 2 ** 32) * glyphs.length)];
 };
-/** A renderable whose segments are computed from the options it is rendered with. */
-function deferred(emit) {
-    return { render: emit };
+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, 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.
+// 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 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);
+// A cell whose ink the eye cannot tell from its ground, read off the style it
+// is drawn in. What is measured is what is drawn — `Style.drawnColors`, the
+// colours the writer encodes: the ink flattened onto the cell's own ground and
+// the ground onto the terminal's black, both downgraded to the depth the
+// render encodes at, so two colours that depth rounds to one 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. A cell on the terminal's ground, or in
+// reverse video over it, has a colour nobody knows on one side, and is seen.
+function vanishes(style, colorSystem) {
+    if (style.reverse)
+        return false;
+    const { color, bgcolor } = style.drawnColors(colorSystem ?? ColorDepth.TRUECOLOR);
     if (color === undefined || bgcolor === undefined)
         return false;
     const av = color.fixedValue;
@@ -151,176 +283,196 @@ function vanishes(arrow, colorSystem) {
         ? Oklch.fromRgba(av).deltaE(Oklch.fromRgba(bv)) < SEAM_MIN_DELTA_E
         : 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 every seam cell's ink is drawn
+ * indistinct from its ground 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);
-        });
+    join(left, right, { index }) {
+        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 neighbours = { left, right };
+                // On screen a cell's ink is its `fg` paint and its ground its `bg`,
+                // reverse video or not (`cellStyle`).
+                const ownerOf = (color) => (color !== "ground" && "edge" in color ? neighbours[color.edge] : null);
+                const styled = (part) => drawn[part].map((cell, at) => {
+                    const owners = new ColorOwners(ownerOf(cell.fg), ownerOf(cell.bg));
+                    return new Segment(pickGlyph(cell, part, index, at), cellStyle(cell, edges, options).withAnchor({ owner: owners, row: 0, col: 0, inner: undefined }));
+                });
+                if (!hasLeft || !hasRight) {
+                    if (hasLeft || hasRight)
+                        yield* styled(hasRight ? "lead" : "tail");
+                    return;
+                }
+                // A seam is lost only when every cell of it is: one cell rounded into
+                // its ground at a shallow depth still leaves the others to show the
+                // step, and measuring per cell, not across the two grounds, divides a
+                // seam stepping in thirds where each third would not be seen.
+                const seam = styled("seam");
+                const lost = drawn.divider !== drawn.seam && seam.every((segment) => segment.style !== undefined && vanishes(segment.style, options.colorSystem));
+                yield* lost ? styled("divider") : seam;
+            },
+        };
     }
 }
-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 bundled joiners ---
+const LEFT_BG = { edge: "left", part: "bg" };
+const RIGHT_BG = { edge: "right", part: "bg" };
+const LEFT_FG = { edge: "left", part: "fg" };
+const HALF = { mix: [LEFT_BG, RIGHT_BG, 1 / 2] };
+const GROUND = "ground";
+// A one-cell edge in the powerline family: `glyph` in the left ground over the
+// right; divided by `thin` in the left item's text; led by the same glyph with
+// the left ground replaced by the terminal's — in reverse video, a notch whose
+// ink is the terminal's background — and tailed by it over the terminal's.
+function edge(glyph, thin) {
+    return {
+        seam: [{ glyph, fg: LEFT_BG, bg: RIGHT_BG }],
+        divider: [{ glyph: thin, fg: LEFT_FG, bg: LEFT_BG }],
+        lead: [{ glyph, fg: GROUND, bg: RIGHT_BG }],
+        tail: [{ glyph, 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)]);
-    }
+// Three powerline arrows stepping through the two thirds between the grounds.
+function prism(glyph, thin) {
+    const third = (t) => ({ mix: [LEFT_BG, RIGHT_BG, t] });
+    const pad = { glyph: " ", fg: LEFT_FG, bg: LEFT_BG };
+    return {
+        ...edge(glyph, thin),
+        seam: [
+            { glyph, fg: LEFT_BG, bg: third(1 / 3) },
+            { glyph, fg: third(1 / 3), bg: third(2 / 3) },
+            { glyph, fg: third(2 / 3), bg: RIGHT_BG },
+        ],
+        divider: [pad, { glyph: thin, fg: LEFT_FG, bg: LEFT_BG }, pad],
+    };
+}
+// A powerline-family joiner: `shape` over `glyph`, its ASCII form the same
+// shape over `ascii`, beginning each run flat — an ASCII arrow reversed out of
+// the terminal's ground is a block of nothing.
+const arrows = (shape, glyph, thin, ascii, asciiThin) => new CellJoiner(shape(glyph, thin), { ...shape(ascii, asciiThin), lead: [] });
+// Each run closed by `close` and opened by `open`, both in its ground over the
+// terminal's, with `between` — cells on the terminal's ground — between runs.
+function pill(open, close, between) {
+    const seam = [{ glyph: close, fg: LEFT_BG, bg: GROUND }, ...between, { 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 }] };
 }
+const capsule = (open, close) => pill(open, close, [{ glyph: " ", fg: LEFT_FG, bg: GROUND }]);
+const metro = (open, close, rail) => pill(open, close, [{ glyph: rail, fg: { role: "strip.rail" }, bg: GROUND }]);
+// One cell drawn over the two grounds' midpoint, so it reads as neither item's;
+// nothing at the ends, where there is no second ground to meet.
+function midpoint(glyph, fg) {
+    const seam = [{ glyph, fg, bg: HALF }];
+    return { seam, divider: seam, lead: [], tail: [] };
+}
+// A ragged tear in the left ground over the midpoint; where that ink would
+// vanish into the midpoint — grounds a few steps apart, or one ground — the
+// same tear in the left item's text.
+function torn(glyphs) {
+    return { ...midpoint({ oneOf: glyphs }, LEFT_BG), divider: [{ glyph: { oneOf: glyphs }, fg: LEFT_FG, bg: HALF }] };
+}
+const PLAIN_SEAM = [{ glyph: " | ", fg: { role: "strip.separator" }, bg: GROUND }];
+const PLAIN = { seam: PLAIN_SEAM, divider: PLAIN_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.
+ * The bundled joiners, by name. What each draws is `docs/strip.md`'s
+ * "Built-in joiners"; a name from config is read with `joinerNamed`.
  */
-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 }));
-            }
-        });
-    }
+export const JOINERS = Object.freeze({
+    powerline: arrows(edge, "\ue0b0", "\ue0b1", ">", ">"),
+    prism: arrows(prism, "\ue0b0", "\ue0b1", ">", ">"),
+    slant: arrows(edge, "\ue0bc", "\ue0bd", "/", "/"),
+    backslant: arrows(edge, "\ue0b8", "\ue0b9", "\\", "\\"),
+    flame: arrows(edge, "\ue0c0", "\ue0c1", "}", "}"),
+    pixel: arrows(edge, "\ue0c4", "\ue0b1", "#", ">"),
+    ice: arrows(edge, "\ue0c8", "\ue0b1", "]", ">"),
+    bubble: arrows(edge, "\ue0b4", "\ue0b5", ")", ")"),
+    capsule: new CellJoiner(capsule("\ue0b6", "\ue0b4"), capsule("(", ")")),
+    wrapper: new CellJoiner(pill("\ue0b2", "\ue0b0", []), pill("<", ">", [])),
+    metro: new CellJoiner(metro("\ue0b6", "\ue0b4", "\u2500\u2500"), metro("(", ")", "--")),
+    stitch: new CellJoiner(midpoint("\u250a", LEFT_FG), midpoint(":", LEFT_FG)),
+    torn: new CellJoiner(torn(["\u259a\u259e", "\u259e\u259a", "\u2598\u2597", "\u259d\u2596", "\u2596\u259d", "\u2597\u2598"]), torn(["/\\", "\\/"])),
+    plain: new CellJoiner(PLAIN, PLAIN),
+});
+/**
+ * The bundled joiner `name` names — a name read from config, parsed. Throws on
+ * any other string, naming the ones there are; an own-key test, so `toString`
+ * and the rest of `Object.prototype` are not joiners.
+ */
+export function joinerNamed(name) {
+    if (!isJoinerName(name))
+        throw new Error(`no joiner named ${JSON.stringify(name)}; the joiners are ${Object.keys(JOINERS).join(", ")}`);
+    return JOINERS[name];
+}
+const isJoinerName = (name) => Object.hasOwn(JOINERS, name);
+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: [] };
+}
+/**
+ * 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.
+ */
+export function gradientJoiner(steps = 4) {
+    return new CellJoiner(gradient(steps, "▌"), gradient(steps, " "));
 }