@promptctl/rich-js 0.24.1 → 0.25.0

package/dist/core/strip.d.ts

@@ -28,7 +28,7 @@
 import type { Anchor } from "./anchor.js";
 import { Segment } from "./segment.js";
 import { Style } from "./style.js";
-import { type Composite, type Measurable, type Renderable, type RenderOptions } from "./protocol.js";
+import { type Measurable, type Renderable, type RenderOptions } from "./protocol.js";
 /**
  * Items in a `Strip` expose their per-edge style so joiners can paint the
  * transition glyph at each boundary.
@@ -97,12 +97,11 @@ export declare function drawJoin<T extends StyledRenderable>(joiner: Joiner<T>,
  * item.
  */
 export declare function drawItem(item: StyledRenderable): Renderable;
-export declare class Strip<T extends StyledRenderable = StyledRenderable> implements Renderable, Measurable, Composite {
+export declare class Strip<T extends StyledRenderable = StyledRenderable> implements Renderable, Measurable {
     readonly items: readonly T[];
     readonly joiner: Joiner<T>;
     constructor(items: readonly T[], joiner: Joiner<T>);
     render(options: RenderOptions): Iterable<Segment>;
-    contents(): Iterable<Renderable>;
     /**
      * [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
@@ -167,15 +166,12 @@ export type SeamCell = JoinCell | {
     readonly cap: "lead" | "tail";
 };
 /**
- * What a joiner draws between two neighbours, in one form:
- *   • `seam` — the cells between them;
- *   • `divider` — in the seam's place where every seam cell's ink is drawn
- *     indistinct from its own ground (see `SEAM_MIN_DELTA_E`), so the seam
- *     would vanish; the same width as `seam`.
+ * What a joiner draws between two neighbours, in one form: `seam`, the cells
+ * between them. Each is drawn with its ink held off its own ground
+ * (`SEAM_MIN_DELTA_E`, `standOff`).
  */
 export interface SeamForm {
     readonly seam: readonly SeamCell[];
-    readonly divider: readonly SeamCell[];
 }
 /**
  * What a joiner draws at the ends of a run, in one form:
@@ -201,10 +197,10 @@ export interface JoinCaps {
     readonly ascii: CapsForm;
 }
 /**
- * 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.
+ * The least ΔE_OK a join cell's ink must stand off its own ground by to be
+ * seen. Below it the eye cannot tell the ink from the ground, so the joiner
+ * lifts the ink to it (`standOff`). Twice the ~.02 threshold of a visible
+ * difference, because a seam is one cell wide.
  */
 export declare const SEAM_MIN_DELTA_E = 0.04;
 /**
@@ -215,9 +211,10 @@ export declare const SEAM_MIN_DELTA_E = 0.04;
  * 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
  * 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
+ * present the join is the seam; with only the right, the lead; with only the
+ * left, the tail; with neither, nothing. Every cell is drawn with its ink held
+ * off its ground at `options.colorSystem` (`standOff`), measured per cell, so a
+ * seam stepping in thirds shows every step however close its grounds. 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.
  *

package/dist/core/strip.js

@@ -131,10 +131,6 @@ 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
@@ -149,12 +145,12 @@ export class Strip {
         return { minimum: width, maximum: width };
     }
 }
-const PARTS = ["seam", "divider", "lead", "tail"];
+const PARTS = ["seam", "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.
+ * The least ΔE_OK a join cell's ink must stand off its own ground by to be
+ * seen. Below it the eye cannot tell the ink from the ground, so the joiner
+ * lifts the ink to it (`standOff`). 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) {
@@ -174,7 +170,6 @@ const pickGlyph = (cell, part, index, at) => {
     return glyphs[Math.floor((parseInt(fnv1a(`${part}:${index}:${at}`), 16) / 2 ** 32) * glyphs.length)];
 };
 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) {
@@ -197,9 +192,9 @@ function parsePaint(raw, absent, refuse) {
     return refuse(`has a colour that is not a Paint: ${JSON.stringify(raw)}`);
 }
 const parseColor = (raw, absent, refuse) => raw === "ground" ? raw : parsePaint(raw, absent, refuse);
-const ABSENT = { seam: undefined, divider: undefined, lead: "left", tail: "right" };
+const ABSENT = { seam: undefined, lead: "left", tail: "right" };
 // 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" };
+const AUTHORED_IN = { seam: "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;
@@ -247,14 +242,6 @@ const asSeamCell = (form, part) => (cell, refuse) => {
         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
@@ -263,16 +250,7 @@ const seamWidth = (cells) => [
  * 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 });
-    };
+    const parseForm = (form) => Object.freeze({ seam: parseCells(raw, form, "seam", asSeamCell(form, "seam")) });
     return Object.freeze({ glyph: parseForm("glyph"), ascii: parseForm("ascii") });
 }
 /** [LAW:parse-dont-validate] `parseSeam`'s twin for the caps. */
@@ -282,18 +260,15 @@ function parseCaps(raw) {
 }
 // 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 };
+    return { seam: seam.seam.flatMap((cell) => ("cap" in cell ? caps[cell.cap] : [cell])), 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) {
-    const between = [...shape.seam, ...shape.divider];
     return {
         shape,
         reads: {
-            seam: { left: readsGround(between, "left"), right: readsGround(between, "right") },
+            seam: { left: readsGround(shape.seam, "left"), right: readsGround(shape.seam, "right") },
             lead: readsGround(shape.lead, "right"),
             tail: readsGround(shape.tail, "left"),
         },
@@ -312,29 +287,82 @@ function paintableBg(bg) {
 function drawnGround(bg) {
     return bg.flattenAlpha(SURFACE_BLACK);
 }
-// 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;
-    const bv = bgcolor.fixedValue;
-    return av !== undefined && bv !== undefined
-        ? Oklch.fromRgba(av).deltaE(Oklch.fromRgba(bv)) < SEAM_MIN_DELTA_E
-        : color.number !== undefined ? color.number === bgcolor.number : color.name === bgcolor.name;
+// Whether ink stands off its ground, both as a depth draws them, by the floor a
+// seam is seen at. 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 stand apart unless 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. At sixteen colours, then, the floor is a different slot. The
+// terminal's default colour is nobody's to measure, and stands apart.
+function standsOff(ink, ground) {
+    if (ink.isDefault || ground.isDefault)
+        return true;
+    const [a, b] = [ink.fixedValue, ground.fixedValue];
+    return a !== undefined && b !== undefined
+        ? Oklch.fromRgba(a).deltaE(Oklch.fromRgba(b)) >= SEAM_MIN_DELTA_E
+        : ink.number !== undefined ? ink.number !== ground.number : ink.name !== ground.name;
+}
+// A step along a lightness ray: finer than the steps between the colours a
+// truecolor writer draws, so the walk passes over none of them.
+const LIFT_STEP = 0.001;
+// The steps along `origin`'s lightness ray, its chroma and hue held, in the
+// order the lift tries them: the smaller move first, and at an equal move the
+// lighter, out to black and to white.
+function* lightnessRay(origin) {
+    for (let k = 1; k * LIFT_STEP <= 1; k++) {
+        for (const l of [origin.l + k * LIFT_STEP, origin.l - k * LIFT_STEP]) {
+            if (l >= 0 && l <= 1)
+                yield new Oklch(l, origin.c, origin.h);
+        }
+    }
+}
+/**
+ * `ink`, a glyph's colour on `ground`, held at least `SEAM_MIN_DELTA_E` off it
+ * as `depth` draws both (`Style.drawnColors`). Ink that already stands off is
+ * returned as it is. Ink that does not becomes the drawn form of the nearest
+ * step along its own OKLCH lightness ray, chroma and hue held, that stands off:
+ * the smaller step, toward white or toward black. Every step is measured as the
+ * depth draws it, so at 256 colours and at sixteen the candidates are the
+ * entries the depth draws, and the side the ink moves to can differ between
+ * depths. A floor measured on rounded colours is not monotone along a ray, so
+ * the walk enumerates and never bisects. A side with no colour to measure is
+ * left alone.
+ *
+ * [LAW:one-source-of-truth] The colour returned is the one measured — the
+ * entry the depth draws, not the step that rounds to it — so a reader of the
+ * cell at another depth (an export reads a recording in truecolor) sees the
+ * colour that cleared the floor, never a step one unit off its ground.
+ *
+ * [LAW:single-enforcer] The one place a join cell's visibility is decided:
+ * nothing outside the joiner predicts whether a seam will show.
+ */
+function standOff(ink, ground, depth) {
+    if (ink === undefined || ground === undefined)
+        return ink;
+    const drawn = (color, at) => new Style({ color, bgcolor: ground }).drawnColors(at);
+    const { color: shown, bgcolor: under } = drawn(ink, depth);
+    if (standsOff(shown, under))
+        return ink;
+    // The ray starts from the ink as it is laid on its ground, before a depth
+    // rounds it; ink the terminal's theme draws starts from the colour the
+    // default terminal theme gives it. Ink that vanishes is drawn in the same
+    // kind as its ground — both fixed, or both the theme's — and every step is
+    // drawn in that kind too, so it is measured as the ink was. Ink the depth
+    // draws as the theme's (a slot, or a mix reaching one at truecolor) steps
+    // between slots: an RGB beside a colour only the terminal knows could be
+    // that very colour. Ink the depth fixes (that same mix is a cube entry at
+    // 256) steps between fixed colours, for the same reason turned round.
+    const laid = drawn(ink).color;
+    const kind = shown.fixedValue === undefined ? ColorDepth.STANDARD : ColorDepth.TRUECOLOR;
+    for (const step of lightnessRay(Oklch.fromRgba(laid.getTruecolor()))) {
+        const candidate = drawn(ColorSpec.fromRgba(step.toRgba()).downgrade(kind), depth).color;
+        if (standsOff(candidate, under))
+            return candidate;
+    }
+    // [LAW:no-silent-failure] Unreachable: the ray runs out to black and to
+    // white, and no ground lies within the floor of both, nor is one slot both.
+    throw new Error(`no colour on the lightness ray of ${ink.name} stands off ${ground.name} at depth ${ColorDepth[depth]}`);
 }
 function resolvePaint(paint, edges, options) {
     if ("edge" in paint) {
@@ -358,8 +386,10 @@ function cellStyle(cell, edges, options) {
     // 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 bgcolor = cell.bg === "ground" ? undefined : resolvePaint(cell.bg, edges, options);
+    // [LAW:dataflow-not-control-flow] Every cell's ink is held off its ground;
+    // the gap measured between them decides how far it moves, usually not at all.
+    return new Style({ color: standOff(resolvePaint(cell.fg, edges, options), bgcolor, options.colorSystem ?? ColorDepth.TRUECOLOR), bgcolor });
 }
 const shapeGlyphs = (shape) => PARTS.flatMap((part) => shape[part].flatMap(glyphsOf)).join("");
 /**
@@ -370,9 +400,10 @@ const shapeGlyphs = (shape) => PARTS.flatMap((part) => shape[part].flatMap(glyph
  * 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
  * 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
+ * present the join is the seam; with only the right, the lead; with only the
+ * left, the tail; with neither, nothing. Every cell is drawn with its ink held
+ * off its ground at `options.colorSystem` (`standOff`), measured per cell, so a
+ * seam stepping in thirds shows every step however close its grounds. 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.
  *
@@ -412,13 +443,7 @@ export class CellJoiner {
                         yield* styled(leads ? "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;
+                yield* styled("seam");
             },
         };
     }
@@ -432,52 +457,35 @@ const GROUND = "ground";
 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));
+const POWERLINE = { glyph: "\ue0b0", ascii: ">" };
+const SLANT = { glyph: "\ue0bc", ascii: "/" };
+const BACKSLANT = { glyph: "\ue0b8", ascii: "\\" };
+const FLAME = { glyph: "\ue0c0", ascii: "}" };
+const PIXEL = { glyph: "\ue0c4", ascii: "#" };
+const ICE = { glyph: "\ue0c8", ascii: "]" };
+const BUBBLE = { glyph: "\ue0b4", ascii: ")" };
+// `glyph` in the left ground over the right.
+const arrow = (glyph) => ({ seam: [{ glyph, fg: LEFT_BG, bg: RIGHT_BG }] });
+const arrowSeam = (f) => both(arrow(f.glyph), arrow(f.ascii));
 // Three arrows stepping through the two thirds between the grounds.
-function prism(glyph, thin) {
+function prism(glyph) {
     const third = (t) => ({ mix: [LEFT_BG, RIGHT_BG, t] });
-    const pad = { glyph: " ", fg: LEFT_FG, bg: LEFT_BG };
     return {
         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],
     };
 }
 // 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 parted = (between) => ({ seam: [TAIL, ...between, LEAD] });
 // 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 };
-}
-// 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 { 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 };
+const midpoint = (glyph, fg) => ({ seam: [{ glyph, fg, bg: HALF }] });
+// A ragged tear in the left ground over the midpoint.
+const torn = (glyphs) => midpoint({ oneOf: glyphs }, LEFT_BG);
+const PLAIN = { seam: [{ glyph: " | ", fg: { role: "strip.separator" }, bg: GROUND }] };
 const SPACE = { glyph: " ", fg: LEFT_FG, bg: GROUND };
 const rail = (glyph) => ({ glyph, fg: { role: "strip.rail" }, bg: GROUND });
 /**
@@ -487,7 +495,7 @@ const rail = (glyph) => ({ glyph, fg: { role: "strip.rail" }, bg: GROUND });
  */
 export const SEAMS = Object.freeze({
     powerline: parseSeam(arrowSeam(POWERLINE)),
-    prism: parseSeam(both(prism(POWERLINE.glyph, POWERLINE.thin), prism(POWERLINE.ascii, POWERLINE.asciiThin))),
+    prism: parseSeam(both(prism(POWERLINE.glyph), prism(POWERLINE.ascii))),
     slant: parseSeam(arrowSeam(SLANT)),
     backslant: parseSeam(arrowSeam(BACKSLANT)),
     flame: parseSeam(arrowSeam(FLAME)),
@@ -572,12 +580,13 @@ function gradient(steps, glyph) {
     // 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 };
+    return {
+        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] },
+        })),
+    };
 }
 /**
  * A ramp of `steps` cells from the left ground to the right. Each cell is the

package/dist/core/style.d.ts

@@ -11,6 +11,13 @@ import { type Anchor } from "./anchor.js";
  */
 export declare const ATTRIBUTE_NAMES: readonly ["bold", "dim", "italic", "underline", "blink", "blink2", "reverse", "conceal", "strike", "underline2", "frame", "encircle", "overline"];
 export type AttributeName = (typeof ATTRIBUTE_NAMES)[number];
+/**
+ * Each text attribute as a style sets it: on, off, or unset — and an unset
+ * one lets a style laid beneath (`Style.add`) show through.
+ */
+export type Attributes = {
+    readonly [A in AttributeName]: boolean | undefined;
+};
 export declare const ATTRIBUTE_SGR: Record<AttributeName, number>;
 /**
  * Canonical short-attribute aliases (`b` → `bold`, `i` → `italic`, …).
@@ -18,7 +25,7 @@ export declare const ATTRIBUTE_SGR: Record<AttributeName, number>;
  * bindings — adding an alias here makes it available everywhere.
  * [LAW:one-source-of-truth]
  */
-export declare const ATTRIBUTE_SHORT_ALIASES: Record<string, AttributeName>;
+export declare const ATTRIBUTE_SHORT_ALIASES: Readonly<Record<string, AttributeName>>;
 export interface StyleOptions {
     color?: string | ColorSpec;
     bgcolor?: string | ColorSpec;
@@ -38,7 +45,18 @@ export interface StyleOptions {
     link?: string;
     meta?: Record<string, unknown>;
     anchor?: Anchor;
-    nextChange?: number;
+    /**
+     * The hold the style's cells are in, both ends or neither: a cell saying
+     * only when it next changes would claim, by default, that it always was,
+     * and a timeline run backwards past its change would never wake for it.
+     * [LAW:types-are-the-program] Absent, the cells never change.
+     */
+    hold?: Hold;
+}
+/** A hold: since when a sample has been what it is, and until when it stays so, on one clock. */
+export interface Hold {
+    readonly lastChange: number;
+    readonly nextChange: number;
 }
 export declare class StyleSyntaxError extends Error {
     constructor(message: string, options?: ErrorOptions);
@@ -60,7 +78,7 @@ export declare class Style {
     readonly encircle: boolean | undefined;
     readonly overline: boolean | undefined;
     readonly link: string | undefined;
-    readonly meta: Record<string, unknown> | undefined;
+    readonly meta: Readonly<Record<string, unknown>> | undefined;
     /**
      * Where this style's cells sat in the output of whatever drew them; see
      * `./anchor.ts`. It draws nothing, and it makes two styles that draw alike
@@ -68,17 +86,19 @@ export declare class Style {
      */
     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
+     * The hold this style's cells are in, on the timeline of whoever drew the
+     * frame: since when what they show has been what it is (`lastChange`), and
+     * when it next changes (`nextChange`) — both `t` for a cell drawn by
+     * something that moves every frame, and `-Infinity`/`Infinity` 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.
+     * stamps its cells with it (`placedRender`, `Effected`), the stamp rides up
+     * through every container as the anchor does (`./anchor.ts`), and whoever
+     * holds the composed frame reads it off (`Segment.nextChange`, and
+     * `Segment.lastChange` for a host running its timeline backwards), so a
+     * host knows when to draw again without asking each container. Two styles
+     * laid together are in the intersection of their holds.
      */
-    readonly nextChange: number;
+    readonly hold: Hold;
     constructor(options?: StyleOptions);
     get isNull(): boolean;
     get transparentBackground(): boolean;
@@ -97,6 +117,19 @@ export declare class Style {
      * The same look, drawn from the place `anchor` names, or from nowhere.
      */
     withAnchor(anchor: Anchor | undefined): Style;
+    /** The style's text attributes, each as it sets it. */
+    get attributes(): Attributes;
+    /**
+     * The same style with each attribute `attributes` names set as it says —
+     * on, off, or unset — and every other field as it was.
+     */
+    withAttributes(attributes: Partial<Attributes>): Style;
+    /**
+     * This style with its motion taken out, what reduced motion draws: `blink`
+     * and `blink2`, the motion a terminal makes on its own, unset, and every
+     * other field as it was. A style that does not blink is its own.
+     */
+    reduced(): Style;
     /**
      * This style on the cell `cells` to the right: its anchor shifted along its
      * row, or the style itself when it has no anchor.
@@ -130,7 +163,7 @@ export declare class Style {
     /**
      * 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` —
+     * What a style carries beyond its look — `meta`, `anchor`, `hold` —
      * has no spelling and is not here, so two styles that differ only there
      * read alike; `equals` tells them apart.
      */
@@ -198,7 +231,7 @@ export declare class Theme {
     resolve(style: TextStyle): Style;
     has(name: string): boolean;
 }
-export declare const DEFAULT_STYLES: Record<string, Style>;
+export declare const DEFAULT_STYLES: Readonly<Record<string, Style>>;
 /**
  * The theme a render resolves names against when nothing supplied one — what
  * a renderable sees outside a `Console`, as in `renderToString`.