@promptctl/rich-js 0.23.0 → 0.24.1

package/dist/core/strip.js

@@ -31,7 +31,7 @@ import { ColorDepth, ColorSpec, SURFACE_BLACK } from "./color.js";
 import { Oklch } from "./oklch.js";
 import { cellLen } from "./cells.js";
 import { fnv1a } from "./fnv1a.js";
-import { drawable, getStyle, isAscii } from "./protocol.js";
+import { drawable, getStyle, isAscii, render } 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
@@ -80,7 +80,7 @@ export function colorsOwnedBy(anchor, owners) {
  */
 export function drawJoin(joiner, left, right, context) {
     const join = joiner.join(left, right, context);
-    return { render: (options) => Segment.anchorLines([[...join.render(options)]], JOIN)[0] };
+    return { render: (options) => Segment.anchorLines([[...render(join, options)]], JOIN)[0] };
 }
 /**
  * [LAW:single-enforcer] What `item` draws, every cell stamped as the item's,
@@ -89,7 +89,7 @@ export function drawJoin(joiner, left, right, context) {
  * item.
  */
 export function drawItem(item) {
-    return { render: (options) => Segment.anchorLines([[...item.render(options)]], item)[0] };
+    return { render: (options) => Segment.anchorLines([[...render(item, options)]], item)[0] };
 }
 // --- Strip ---
 export class Strip {
@@ -112,12 +112,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* drawJoin(this.joiner, null, items[0], { index: 0 }).render(row);
+        yield* render(drawJoin(this.joiner, null, items[0], { index: 0 }), row);
         for (let i = 0; i < items.length; i++) {
             const item = items[i];
-            yield* drawItem(item).render(row);
+            yield* render(drawItem(item), row);
             const next = i + 1 < items.length ? items[i + 1] : null;
-            yield* drawJoin(this.joiner, item, next, { index: i + 1 }).render(row);
+            yield* render(drawJoin(this.joiner, item, next, { index: i + 1 }), row);
         }
         // [LAW:one-source-of-truth] `Strip`'s sibling `FlexStrip` ends every line
         // it emits, including the last, and the other block-level renderables
@@ -131,6 +131,10 @@ export class Strip {
         // of which renderables end their own line and which are fragments.
         yield Segment.line();
     }
+    // The items; a join is drawn from what the joiner emits for it, not held.
+    contents() {
+        return this.items;
+    }
     /**
      * [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
@@ -140,7 +144,7 @@ export class Strip {
      */
     measure(options) {
         let width = 0;
-        for (const segment of this.render(options))
+        for (const segment of render(this, options))
             width += segment.cellLength;
         return { minimum: width, maximum: width };
     }
@@ -194,59 +198,106 @@ function parsePaint(raw, absent, refuse) {
 }
 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;
+// Which argument of a joiner a part is authored in, so a refusal names it.
+const AUTHORED_IN = { seam: "seam", divider: "seam", lead: "caps", tail: "caps" };
+function parseCell(cell, form, part, refuse) {
+    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),
     });
 }
-/**
- * [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) => {
+// `raw[form][part]` as frozen cells, each checked by `parseOne`, or refused
+// naming where it sits.
+function parseCells(raw, form, part, parseOne) {
+    const forms = raw;
+    const where = AUTHORED_IN[part];
+    if (typeof forms?.[form] !== "object" || forms[form] === null)
+        throw new Error(`${where}: has no ${form} form`);
+    const cells = forms[form][part];
+    if (!Array.isArray(cells))
+        throw new Error(`${where}: ${form} ${part} is not a list of cells`);
+    return Object.freeze(cells.map((cell, i) => {
         const refuse = (why) => {
-            throw new Error(`CellJoiner: ${form} ${part}[${i}] ${why}`);
+            throw new Error(`${where}: ${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),
-        });
+        return typeof cell === "object" && cell !== null ? parseOne(cell, refuse) : refuse("is not a cell");
     }));
-    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")));
+const asCell = (form, part) => (cell, refuse) => parseCell(cell, form, part, refuse);
+const asSeamCell = (form, part) => (cell, refuse) => {
+    if (!("cap" in cell))
+        return parseCell(cell, form, part, refuse);
+    const { cap } = cell;
+    if (Object.keys(cell).length !== 1)
+        refuse("names a cap and draws cells of its own; a cell is one or the other");
+    return cap === "lead" || cap === "tail" ? Object.freeze({ cap }) : refuse(`names a cap that is neither lead nor tail: ${JSON.stringify(cap)}`);
+};
+// A seam's width as a sum over whatever caps stand in it: its own cells', and
+// how many times it names each cap. Two parts equal in all three are the same
+// width under every caps.
+const seamWidth = (cells) => [
+    partWidth(cells.filter((cell) => !("cap" in cell))),
+    cells.filter((cell) => "cap" in cell && cell.cap === "lead").length,
+    cells.filter((cell) => "cap" in cell && cell.cap === "tail").length,
+];
+/**
+ * [LAW:parse-dont-validate] The one place a seam is checked, so every rule
+ * the cell model states is refused at construction and the render reads cells
+ * that already hold them. A seam 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 parseSeam(raw) {
+    const parseForm = (form) => {
+        const seam = parseCells(raw, form, "seam", asSeamCell(form, "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[form].divider === raw[form].seam ? seam : parseCells(raw, form, "divider", asSeamCell(form, "divider"));
+        const [seamAt, dividerAt] = [seamWidth(seam), seamWidth(divider)];
+        if (seamAt.some((n, i) => n !== dividerAt[i]))
+            throw new Error(`seam: ${form} divider is not the width of the seam under every caps`);
+        return Object.freeze({ seam, divider });
+    };
+    return Object.freeze({ glyph: parseForm("glyph"), ascii: parseForm("ascii") });
+}
+/** [LAW:parse-dont-validate] `parseSeam`'s twin for the caps. */
+function parseCaps(raw) {
+    const parseForm = (form) => Object.freeze({ lead: parseCells(raw, form, "lead", asCell(form, "lead")), tail: parseCells(raw, form, "tail", asCell(form, "tail")) });
+    return Object.freeze({ glyph: parseForm("glyph"), ascii: parseForm("ascii") });
+}
+// One form of the seam joined with that form of the caps.
+function joinForms(seam, caps) {
+    const splice = (cells) => cells.flatMap((cell) => ("cap" in cell ? caps[cell.cap] : [cell]));
+    const seamCells = splice(seam.seam);
+    return { seam: seamCells, divider: seam.divider === seam.seam ? seamCells : splice(seam.divider), lead: caps.lead, tail: caps.tail };
+}
+// Whether any of `cells` paints with `side`'s ground.
+const readsGround = (cells, side) => cells.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") } };
+    const between = [...shape.seam, ...shape.divider];
+    return {
+        shape,
+        reads: {
+            seam: { left: readsGround(between, "left"), right: readsGround(between, "right") },
+            lead: readsGround(shape.lead, "right"),
+            tail: readsGround(shape.tail, "left"),
+        },
+    };
 }
 // A bg with a real colour to paint. `undefined` (no bg) and the terminal
 // DEFAULT colour (transparent — identical to the terminal background) are the
@@ -312,26 +363,29 @@ function cellStyle(cell, edges, options) {
 }
 const shapeGlyphs = (shape) => PARTS.flatMap((part) => shape[part].flatMap(glyphsOf)).join("");
 /**
- * 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.
+ * The one joiner: what it draws is a `JoinSeam` between neighbours and a
+ * `JoinCaps` at the ends of each run, picked independently, so a new joiner is
+ * a pair of values, 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.
+ * seam 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. A cap
+ * that paints with its neighbour's ground is drawn only beside a neighbour
+ * with one, so caps that need grounds never stop a seam that needs none.
  *
- * `ascii` is the shape an ASCII-only output draws instead, whole.
+ * An ASCII-only output draws the `ascii` form of both, whole.
  */
 export class CellJoiner {
-    shape;
-    ascii;
+    seam;
+    caps;
     _forms;
-    constructor(shape, ascii) {
-        this.shape = parseShape(shape, "glyph");
-        this.ascii = parseShape(ascii, "ascii");
-        this._forms = { glyph: formOf(this.shape), ascii: formOf(this.ascii) };
+    constructor(seam, caps) {
+        this.seam = parseSeam(seam);
+        this.caps = parseCaps(caps);
+        this._forms = { glyph: formOf(joinForms(this.seam.glyph, this.caps.glyph)), ascii: formOf(joinForms(this.seam.ascii, this.caps.ascii)) };
     }
     join(left, right, { index }) {
         const forms = this._forms;
@@ -341,8 +395,10 @@ export class CellJoiner {
                 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 hasLeft = left !== null && (!reads.seam.left || leftBg !== undefined);
+                const hasRight = right !== null && (!reads.seam.right || rightBg !== undefined);
+                const leads = hasRight && (!reads.lead || rightBg !== undefined);
+                const tails = hasLeft && (!reads.tail || leftBg !== 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`).
@@ -352,8 +408,8 @@ export class CellJoiner {
                     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");
+                    if (leads || tails)
+                        yield* styled(leads ? "lead" : "tail");
                     return;
                 }
                 // A seam is lost only when every cell of it is: one cell rounded into
@@ -367,30 +423,34 @@ export class CellJoiner {
         };
     }
 }
-// --- The bundled joiners ---
+// --- The bundled seams and caps ---
 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 }],
-    };
-}
-// Three powerline arrows stepping through the two thirds between the grounds.
+const LEAD = { cap: "lead" };
+const TAIL = { cap: "tail" };
+const both = (glyph, ascii) => ({ glyph, ascii });
+const POWERLINE = { glyph: "\ue0b0", thin: "\ue0b1", ascii: ">", asciiThin: ">" };
+const SLANT = { glyph: "\ue0bc", thin: "\ue0bd", ascii: "/", asciiThin: "/" };
+const BACKSLANT = { glyph: "\ue0b8", thin: "\ue0b9", ascii: "\\", asciiThin: "\\" };
+const FLAME = { glyph: "\ue0c0", thin: "\ue0c1", ascii: "}", asciiThin: "}" };
+const PIXEL = { glyph: "\ue0c4", thin: "\ue0b1", ascii: "#", asciiThin: ">" };
+const ICE = { glyph: "\ue0c8", thin: "\ue0b1", ascii: "]", asciiThin: ">" };
+const BUBBLE = { glyph: "\ue0b4", thin: "\ue0b5", ascii: ")", asciiThin: ")" };
+// `glyph` in the left ground over the right; divided by `thin` in the left
+// item's text.
+const arrow = (glyph, thin) => ({
+    seam: [{ glyph, fg: LEFT_BG, bg: RIGHT_BG }],
+    divider: [{ glyph: thin, fg: LEFT_FG, bg: LEFT_BG }],
+});
+const arrowSeam = (f) => both(arrow(f.glyph, f.thin), arrow(f.ascii, f.asciiThin));
+// Three 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) },
@@ -399,63 +459,114 @@ function prism(glyph, thin) {
         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 }] };
+// The runs parted: the caps close the one and open the other, `between` —
+// cells on the terminal's ground — set between them.
+function parted(between) {
+    const seam = [TAIL, ...between, LEAD];
+    return { seam, divider: seam };
 }
-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.
+// One cell drawn over the two grounds' midpoint, so it reads as neither item's.
 function midpoint(glyph, fg) {
     const seam = [{ glyph, fg, bg: HALF }];
-    return { seam, divider: seam, lead: [], tail: [] };
+    return { seam, divider: seam };
 }
 // 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 }] };
+    return { seam: midpoint({ oneOf: glyphs }, LEFT_BG).seam, 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: [] };
+const PLAIN = { seam: PLAIN_SEAM, divider: PLAIN_SEAM };
+const SPACE = { glyph: " ", fg: LEFT_FG, bg: GROUND };
+const rail = (glyph) => ({ glyph, fg: { role: "strip.rail" }, bg: GROUND });
 /**
- * The bundled joiners, by name. What each draws is `docs/strip.md`'s
- * "Built-in joiners"; a name from config is read with `joinerNamed`.
+ * The bundled seams, by name: what a joiner draws between two neighbours.
+ * What each draws is `docs/strip.md`'s "Seams"; any of them ends in any of
+ * `CAPS`.
+ */
+export const SEAMS = Object.freeze({
+    powerline: parseSeam(arrowSeam(POWERLINE)),
+    prism: parseSeam(both(prism(POWERLINE.glyph, POWERLINE.thin), prism(POWERLINE.ascii, POWERLINE.asciiThin))),
+    slant: parseSeam(arrowSeam(SLANT)),
+    backslant: parseSeam(arrowSeam(BACKSLANT)),
+    flame: parseSeam(arrowSeam(FLAME)),
+    pixel: parseSeam(arrowSeam(PIXEL)),
+    ice: parseSeam(arrowSeam(ICE)),
+    bubble: parseSeam(arrowSeam(BUBBLE)),
+    capsule: parseSeam(both(parted([SPACE]), parted([SPACE]))),
+    wrapper: parseSeam(both(parted([]), parted([]))),
+    metro: parseSeam(both(parted([rail("──")]), parted([rail("--")]))),
+    stitch: parseSeam(both(midpoint("┊", LEFT_FG), midpoint(":", LEFT_FG))),
+    torn: parseSeam(both(torn(["▚▞", "▞▚", "▘▗", "▝▖", "▖▝", "▗▘"]), torn(["/\\", "\\/"]))),
+    plain: parseSeam(both(PLAIN, PLAIN)),
+});
+// The family's glyph reversed out of the terminal's ground at the lead — a
+// notch whose ink is the terminal's background — and over that ground at the
+// tail, so a run reads as one chevron. ASCII opens each run flat: an ASCII
+// glyph reversed out of the terminal's ground is a block of nothing.
+const flowCaps = (f) => both({ lead: [{ glyph: f.glyph, fg: GROUND, bg: RIGHT_BG }], tail: [{ glyph: f.glyph, fg: LEFT_BG, bg: GROUND }] }, { lead: [], tail: [{ glyph: f.ascii, fg: LEFT_BG, bg: GROUND }] });
+// `open` and `close`, each in its run's ground over the terminal's.
+const pill = (open, close) => ({
+    lead: [{ glyph: open, fg: RIGHT_BG, bg: GROUND }],
+    tail: [{ glyph: close, fg: LEFT_BG, bg: GROUND }],
+});
+const FLAT = { lead: [], tail: [] };
+/**
+ * The bundled caps, by name: what a joiner draws where a run begins and ends.
+ * What each draws is `docs/strip.md`'s "Caps"; any of them ends any of
+ * `SEAMS`.
+ */
+export const CAPS = Object.freeze({
+    powerline: parseCaps(flowCaps(POWERLINE)),
+    slant: parseCaps(flowCaps(SLANT)),
+    backslant: parseCaps(flowCaps(BACKSLANT)),
+    flame: parseCaps(flowCaps(FLAME)),
+    pixel: parseCaps(flowCaps(PIXEL)),
+    ice: parseCaps(flowCaps(ICE)),
+    bubble: parseCaps(flowCaps(BUBBLE)),
+    capsule: parseCaps(both(pill("\ue0b6", "\ue0b4"), pill("(", ")"))),
+    wrapper: parseCaps(both(pill("\ue0b2", "\ue0b0"), pill("<", ">"))),
+    flat: parseCaps(both(FLAT, FLAT)),
+});
+/**
+ * The bundled joiners, by name: each a seam from `SEAMS` ended in caps from
+ * `CAPS`. What each draws is `docs/strip.md`'s "Built-in joiners"; a name from
+ * config is read with `joinerNamed`.
  */
 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),
+    powerline: new CellJoiner(SEAMS.powerline, CAPS.powerline),
+    prism: new CellJoiner(SEAMS.prism, CAPS.powerline),
+    slant: new CellJoiner(SEAMS.slant, CAPS.slant),
+    backslant: new CellJoiner(SEAMS.backslant, CAPS.backslant),
+    flame: new CellJoiner(SEAMS.flame, CAPS.flame),
+    pixel: new CellJoiner(SEAMS.pixel, CAPS.pixel),
+    ice: new CellJoiner(SEAMS.ice, CAPS.ice),
+    bubble: new CellJoiner(SEAMS.bubble, CAPS.bubble),
+    capsule: new CellJoiner(SEAMS.capsule, CAPS.capsule),
+    wrapper: new CellJoiner(SEAMS.wrapper, CAPS.wrapper),
+    metro: new CellJoiner(SEAMS.metro, CAPS.capsule),
+    stitch: new CellJoiner(SEAMS.stitch, CAPS.flat),
+    torn: new CellJoiner(SEAMS.torn, CAPS.flat),
+    plain: new CellJoiner(SEAMS.plain, CAPS.flat),
 });
 /**
- * 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.
+ * The joiner `spec` names — a joiner read from config, parsed. Throws on a
+ * name its table lacks, naming the ones there are; an own-key test, so
+ * `toString` and the rest of `Object.prototype` are no one's name.
  */
-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];
+export function joinerNamed(spec) {
+    if (typeof spec === "string")
+        return named(JOINERS, "joiner", "joiners", spec);
+    if (typeof spec !== "object" || spec === null)
+        throw new Error(`a joiner is a name or { seam, caps }, not ${JSON.stringify(spec)}`);
+    return new CellJoiner(named(SEAMS, "seam", "seams", spec.seam), named(CAPS, "caps", "caps", spec.caps));
+}
+function named(table, kind, kinds, name) {
+    if (!Object.hasOwn(table, name))
+        throw new Error(`no ${kind} named ${JSON.stringify(name)}; the ${kinds} are ${Object.keys(table).join(", ")}`);
+    return table[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),
@@ -466,15 +577,15 @@ function gradient(steps, 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: [] };
+    return { seam, divider: seam };
 }
 /**
  * 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.
+ * carries two samples; ASCII draws a space, keeping the grounds alone. Beside
+ * a neighbour with no ground there is no colour to ramp toward, so that join
+ * draws the caps the ramp is ended in.
  */
-export function gradientJoiner(steps = 4) {
-    return new CellJoiner(gradient(steps, "▌"), gradient(steps, " "));
+export function gradientSeam(steps = 4) {
+    return parseSeam(both(gradient(steps, "▌"), gradient(steps, " ")));
 }

package/dist/core/style.d.ts

@@ -38,6 +38,7 @@ export interface StyleOptions {
     link?: string;
     meta?: Record<string, unknown>;
     anchor?: Anchor;
+    nextChange?: number;
 }
 export declare class StyleSyntaxError extends Error {
     constructor(message: string, options?: ErrorOptions);
@@ -66,6 +67,18 @@ export declare class Style {
      * unequal, because they came from different places.
      */
     readonly anchor: Anchor | undefined;
+    /**
+     * When what this style's cells show next changes, in seconds on the
+     * timeline of whoever drew the frame — `t` itself for a cell drawn by
+     * something that moves every frame, and `Infinity`, the default, for one
+     * that never changes. It draws nothing. Whatever draws for a handed time
+     * stamps its cells with it (`Frames`, `Effected`), the stamp rides up
+     * through every container as the anchor does (`./anchor.ts`), and
+     * whoever holds the composed frame reads the soonest off it
+     * (`Segment.nextChange`), so a host knows when to draw again without
+     * asking each container. Two styles laid together change at the sooner.
+     */
+    readonly nextChange: number;
     constructor(options?: StyleOptions);
     get isNull(): boolean;
     get transparentBackground(): boolean;
@@ -115,7 +128,11 @@ export declare class Style {
      */
     toSgrCodes(colorSystem: ColorDepth): string;
     /**
-     * Serializes to a canonical string that round-trips through `Style.parse()`.
+     * The look as a canonical string that round-trips through `Style.parse()`:
+     * colours, attributes and the link, which is all a style string can spell.
+     * What a style carries beyond its look — `meta`, `anchor`, `nextChange` —
+     * has no spelling and is not here, so two styles that differ only there
+     * read alike; `equals` tells them apart.
      */
     toString(): string;
     static null(): Style;