@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/renderables/columns.js

@@ -1,18 +1,47 @@
 /**
  * Columns — arranges renderables in a multi-column layout.
+ *
+ * A port of Rich's `Columns`. What it decides is how many columns, and which
+ * item goes in which cell. Everything after that — how wide each column is, how
+ * far apart, what `expand` does, how rows are separated — is the grid's: the
+ * items are laid out as a `Table.grid`, as the reference lays them out.
+ * [LAW:one-source-of-truth] A second copy of that geometry here is how the two
+ * drifted: an empty item's column was drawn with no width where the grid draws one cell.
  */
-import { Segment } from "../core/segment.js";
 import { Measurement } from "../core/measure.js";
-import { isMeasurable, stackedHeight, withBoundedWidth, withCellWidth } from "../core/protocol.js";
+import { normalizePadding } from "./padding.js";
+import { withBoundedWidth, withCellWidth } from "../core/protocol.js";
 import { cellCount } from "../core/cells.js";
-import { embed } from "./embed.js";
+import { EmbeddedText, embed } from "./embed.js";
+import { Constrain } from "./constrain.js";
+import { Table } from "./table.js";
+/**
+ * The item in slot `slot` of the grid for `count` columns, counting row by row;
+ * `undefined` is a slot no item fills. Constant time, so a search that stops at
+ * the first slot that overflows pays for no slot after it.
+ */
+function slotItem(slot, items, count, columnFirst) {
+    const row = Math.floor(slot / count);
+    const col = slot % count;
+    // Column-first fills each column top to bottom, and the columns that take one
+    // item more than the rest are the leading ones — Rich's `column_lengths`.
+    const base = Math.floor(items / count);
+    const extra = items % count;
+    const length = base + (col < extra ? 1 : 0);
+    const index = !columnFirst ? slot : row < length ? col * base + Math.min(col, extra) + row : items;
+    return index < items ? index : undefined;
+}
+/** How many slots the grid for `count` columns has: every row full, the last one padded. */
+function slotCount(items, count) {
+    return Math.ceil(items / count) * count;
+}
 export class Columns {
     renderables;
     expand;
     equal;
     colWidth;
     columnFirst;
-    gutterWidth;
+    padding;
     constructor(items, options) {
         this.renderables = items ? [...items].map(embed) : [];
         this.expand = options?.expand ?? false;
@@ -26,127 +55,137 @@ export class Columns {
         // read it as a declared zero.
         this.colWidth = options?.width === undefined ? undefined : cellCount(options.width);
         this.columnFirst = options?.columnFirst ?? false;
-        this.gutterWidth = 2; // default gutter between columns
+        // [LAW:parse-dont-validate] Rich's default is `(0, 1)`: one cell between
+        // columns and none between rows.
+        this.padding = normalizePadding(options?.padding ?? [0, 1]);
     }
     *render(rawOptions) {
-        const items = this.renderables;
-        if (items.length === 0)
+        if (this.renderables.length === 0)
             return;
-        // The parsed options, not just a parsed local: `_divide` hands them to
+        // The parsed options, not just a parsed local: `_layout` hands them to
         // `Measurement.get`, and a raw NaN reaching it comes back as a NaN item
-        // width, then a NaN column count, then `Invalid array length` out of
-        // `new Array(numCols)` before a single column is laid out. An unbounded
-        // width reaches the same `new Array` by the same route, which is why the
-        // parse here is the bounded one.
+        // width, then a NaN column count, then `Invalid array length` before a
+        // single column is laid out. An unbounded width reaches the same place by
+        // the same route, which is why the parse here is the bounded one.
         const options = withBoundedWidth(rawOptions, this);
-        const { numCols, colWidths } = this._divide(options);
-        // Layout items into rows
-        const numRows = Math.ceil(items.length / numCols);
-        // [LAW:types-are-the-program] The element type is Renderable — any number
-        // of lines. Each grid cell renders to its full set of lines; an out-of-range
-        // slot (the last row is rarely full) is an empty cell. mergeHorizontal then
-        // stacks every row of every cell line-by-line, so multi-line children
-        // (Panels, Tables) compose instead of being truncated to their first row.
-        for (let row = 0; row < numRows; row++) {
-            const cells = colWidths.map((width, col) => {
-                const idx = this.columnFirst ? col * numRows + row : row * numCols + col;
-                const item = items[idx];
-                const lines = item === undefined
-                    ? []
-                    : Segment.splitLines([
-                        ...item.render({ ...options, maxWidth: width, height: stackedHeight(options.height) }),
-                    ]);
-                return { lines, width };
-            });
-            yield* Segment.mergeHorizontal(cells, this.gutterWidth);
-        }
+        yield* this._grid(options).render(options);
+    }
+    measure(rawOptions) {
+        // The maximum is the grid's, which reports its width before `expand`: a
+        // stretch is what a Columns does with a width it is given, not a width it
+        // asks for. Reported as the offer instead, `Panel` in fit mode drew a
+        // 40-cell frame around five cells of content and an unbounded offer came
+        // back unbounded.
+        //
+        // A floor of one cell is what Columns asks for, since it can always fall
+        // back to one column, and the ceiling wins: a bare `minimum: 1` measured
+        // into no width at all reported the range 1..0 — a floor above its own
+        // ceiling, which the parent that asked cannot divide.
+        const parsed = withCellWidth(rawOptions);
+        if (this.renderables.length === 0)
+            return { minimum: 0, maximum: 0 };
+        const { maximum } = this._grid(parsed).measure(parsed);
+        return { minimum: Math.min(1, maximum), maximum };
     }
     /**
-     * The requested width divided into columns, once.
+     * The items at the width offered, as the reference's grid: `_layout`'s
+     * cells in a `Table.grid`.
+     *
+     * [LAW:single-enforcer] `render` draws this and `measure` reports its width,
+     * so the two cannot disagree about how wide a Columns is.
      *
-     * [LAW:single-enforcer] The three modes disagree only about how many columns
-     * there are and how wide each one is, so they disagree in one place. `render`
-     * lays out against this division and `_naturalWidth` is the width at which it
-     * comes out as one row of every item.
+     * A declared `width` is each column's natural width rather than a Table
+     * column `width`, which this port never stretches: the reference's grid
+     * stretches a Columns' declared width under `expand` like any other.
+     * `equal` holds every item to the widest, Rich's `Constrain`; without it
+     * the cap is `undefined` and holds nothing.
      */
-    _divide(options) {
-        const maxWidth = options.maxWidth;
-        const gutter = this.gutterWidth;
+    _grid(options) {
+        const { columns, rows, widest } = this._layout(options);
+        const grid = Table.grid({ padding: this.padding, expand: this.expand });
         const declared = this._declaredWidth(options);
-        if (declared !== undefined) {
-            const numCols = Math.max(1, Math.floor((maxWidth + gutter) / (declared + gutter)));
-            return { numCols, colWidths: new Array(numCols).fill(declared) };
+        for (let col = 0; col < columns; col++) {
+            grid.addColumn(undefined, { minWidth: declared, maxWidth: declared });
         }
-        if (this.equal) {
-            const itemWidth = this._itemWidth(options);
-            const numCols = Math.max(1, Math.floor((maxWidth + gutter) / (itemWidth + gutter)));
-            const equalWidth = Math.floor((maxWidth - gutter * (numCols - 1)) / numCols);
-            return { numCols, colWidths: new Array(numCols).fill(equalWidth) };
+        const cap = this.equal ? widest : undefined;
+        // A string item is read here, under the options Columns is drawn with,
+        // before the grid gets it: Rich's `Columns` reads its strings through
+        // `render_str`, so they are highlighted where a table cell's are not.
+        const items = this.renderables.map((item) => (item instanceof EmbeddedText ? item.text(options) : item));
+        for (const row of rows) {
+            grid.addRow(...row.map((index) => (index === undefined ? "" : new Constrain(items[index], cap))));
         }
-        // Auto: as many columns as the widest item fits into, capped at the item
-        // count. Sized from the content rather than from a flat four cells per
-        // column, because `_naturalWidth` below is the inverse of *this* expression
-        // and a constant has no inverse: six two-cell items reported a natural
-        // width of 22 and then wrapped into two rows at 22, since `floor(22 / 4)`
-        // is five columns no matter how narrow the items are.
-        const itemWidth = this._itemWidth(options);
-        const numCols = Math.min(this.renderables.length, Math.max(1, Math.floor((maxWidth + gutter) / (itemWidth + gutter))));
-        const colW = Math.floor((maxWidth - gutter * (numCols - 1)) / numCols);
-        return { numCols, colWidths: new Array(numCols).fill(colW) };
+        return grid;
     }
     /**
-     * The widest any one item wants to be.
+     * How many columns fit the width offered, and which item goes in each cell,
+     * decided the way Rich's `Columns` decides them.
      *
-     * An item that cannot measure itself wants the offer, which is what `Panel`,
-     * `Padding`, `Layout` and `Tree` all answer for the same case — and under an
-     * unbounded offer that is `Infinity`, so `withBoundedWidth` throws and says
-     * the request was unanswerable. Counting it as one cell instead reported a
-     * natural width of 1, which resolved an unbounded offer to a single column and
-     * cropped forty cells of content down to `"x"` with no error at all.
+     * Every item carries a width. It is what the item measures, or the declared
+     * `width` for all of them. `equal` counts every item as the widest when
+     * choosing how many columns fit, and the grid still sizes each column by
+     * what is in it — which is why an `equal` layout is not a grid of equal
+     * columns, in the reference or here.
+     *
+     * The count starts at one column per item and drops whenever the columns
+     * filled so far, and the gaps between them, pass the width offered. Two
+     * columns stand the wider of the padding's left and right sides apart, which
+     * is what the collapsed grid leaves between them. One departure from the
+     * reference: a declared `width` is searched the same way rather than by
+     * `max_width // (width + gap)`, which laid out empty trailing columns and
+     * charged the last column a gap it does not have.
      */
-    _itemWidth(options) {
-        let widest = 1;
-        for (const item of this.renderables) {
-            widest = Math.max(widest, isMeasurable(item)
-                ? Measurement.get(options, item).maximum
-                : options.maxWidth);
-        }
-        return widest;
+    _layout(options) {
+        const count = this.renderables.length;
+        const maxWidth = options.maxWidth;
+        const [, right, , left] = this.padding;
+        const gap = Math.max(left, right);
+        const declared = this._declaredWidth(options);
+        // An item that cannot measure itself wants the whole offer. Counting it as one
+        // cell instead resolved an unbounded offer to a single column and cropped
+        // forty cells of content down to `"x"` with no error at all.
+        const sizes = this.renderables.map((item) => declared ?? Measurement.get(options, item).maximum);
+        // A fold, not `Math.max(...sizes)`: spreading one argument per item
+        // overflows the call stack at a few hundred thousand items.
+        const widest = sizes.reduce((w, size) => Math.max(w, size), 0);
+        const fits = this.equal ? sizes.map(() => widest) : sizes;
+        // One attempt either fits in the offer or names the smaller count to try
+        // next. `total` is the columns so far and the gaps between them, kept as
+        // the widths grow so that a slot costs the same however many columns came
+        // before it.
+        const attempt = (columns) => {
+            const widths = [];
+            let total = 0;
+            for (let slot = 0; slot < slotCount(count, columns); slot++) {
+                const col = slot % columns;
+                const index = slotItem(slot, count, columns, this.columnFirst);
+                const held = widths[col];
+                const width = Math.max(held ?? 0, index === undefined ? 0 : fits[index]);
+                total += width - (held ?? 0) + (held === undefined && col > 0 ? gap : 0);
+                widths[col] = width;
+                // Never zero: no item measures wider than the offer, so the first
+                // column alone always fits.
+                if (total > maxWidth)
+                    return widths.length - 1;
+            }
+            return columns;
+        };
+        let columns = count;
+        for (let next = attempt(columns); next < columns; next = attempt(columns))
+            columns = next;
+        const rows = Array.from({ length: slotCount(count, columns) / columns }, (_, row) => Array.from({ length: columns }, (_, col) => slotItem(row * columns + col, count, columns, this.columnFirst)));
+        return { columns, rows, widest };
     }
     /**
      * The declared column width, bounded by the width offered.
      *
-     * [LAW:single-enforcer] A declared width is what a column asks for, not what
-     * it takes — the contract `Table._outerWidth` keeps for a declared table
-     * width. Read by `_divide` for render and by `_naturalWidth` for measure, so
-     * the two answer from one number: laid out at the raw declared width, a
-     * six-cell column offered three emitted six-cell lines while `measure`
-     * reported three, and the terminal's soft wrap took the frame of everything
-     * printed after it.
+     * A declared width is what a column asks for, not what it takes — the
+     * contract `Table._outerWidth` keeps for a declared table width. Laid out at
+     * the raw declared width, a six-cell column offered three emitted six-cell
+     * lines while `measure` reported three, and the terminal's soft wrap took the
+     * frame of everything printed after it.
      */
     _declaredWidth(options) {
         return this.colWidth === undefined ? undefined : Math.min(this.colWidth, options.maxWidth);
     }
-    /** The width at which every item sits on one row: n columns and the gutters between them. */
-    _naturalWidth(options) {
-        const count = this.renderables.length;
-        if (count === 0)
-            return 0;
-        const width = this._declaredWidth(options) ?? this._itemWidth(options);
-        return count * width + this.gutterWidth * (count - 1);
-    }
-    measure(rawOptions) {
-        // A floor of one cell is what Columns asks for; the ceiling is what it was
-        // offered, and the ceiling wins. Stated as a bare `minimum: 1`, a Columns
-        // measured into no width at all reported the range 1..0 — a floor above
-        // its own ceiling, which the parent that asked cannot divide.
-        //
-        // The ceiling is not the whole answer, though: reported as the offer alone,
-        // a Columns claimed every cell it was shown, so `Panel` in fit mode drew a
-        // 40-cell frame around five cells of content and an unbounded offer came
-        // back unbounded.
-        const parsed = withCellWidth(rawOptions);
-        const maximum = Math.min(this._naturalWidth(parsed), parsed.maxWidth);
-        return { minimum: Math.min(1, maximum), maximum };
-    }
 }

package/dist/renderables/constrain.js

@@ -2,7 +2,6 @@
  * Constrain — wraps a renderable and constrains its maximum width.
  */
 import { Measurement } from "../core/measure.js";
-import { isMeasurable } from "../core/protocol.js";
 export class Constrain {
     renderable;
     width;
@@ -22,16 +21,11 @@ export class Constrain {
         yield* this.renderable.render(innerOptions);
     }
     measure(options) {
-        if (isMeasurable(this.renderable)) {
-            const measurement = Measurement.get(options, this.renderable);
-            const maxWidth = this.width !== undefined
-                ? Math.min(this.width, options.maxWidth)
-                : options.maxWidth;
-            return {
-                minimum: measurement.minimum,
-                maximum: Math.min(measurement.maximum, maxWidth),
-            };
-        }
-        return { minimum: 1, maximum: options.maxWidth };
+        // Measured at the width it will be drawn at, as Rich's `update_width` does;
+        // `Measurement.get` then holds the answer inside that offer.
+        const maxWidth = this.width !== undefined
+            ? Math.min(this.width, options.maxWidth)
+            : options.maxWidth;
+        return Measurement.get({ ...options, maxWidth }, this.renderable);
     }
 }

package/dist/renderables/effect.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Effected — a renderable whose finished cells' colours pass through an
+ * effect at a moment `t`.
+ *
+ * An effect is one pure function: a cell's colours, where the cell is, and a
+ * time in, the cell's new colours out. Shimmer, pulse, fade and dissolve are
+ * all this one shape, differing by what the function does with its inputs
+ * [LAW:one-type-per-behavior]; two effects stack by nesting one wrapper in
+ * another, which is the same as calling one after the other.
+ *
+ * [LAW:no-ambient-temporal-coupling] `t` is a constructor argument, not a
+ * clock read. Whoever draws frames builds the view for each frame's `t`, so
+ * the same `t` always draws the same bytes, at 30 frames a second or one
+ * every two seconds.
+ *
+ * What an effect may not do is the contract this module holds:
+ *
+ * - It changes how cells look, never which cells exist or who drew them. The
+ *   child's text is walked by grapheme cluster, so a wide glyph is one cell
+ *   to the effect and is never cut, and a run cut out of a segment keeps that
+ *   segment's link and meta and carries its anchor shifted to the run's first
+ *   cell (`Style.shiftedBy`), so hit testing still finds the owner.
+ * - A cell whose colours come back unchanged keeps its original `ColorSpec`,
+ *   and a segment whose every cell is unchanged is yielded as it was, so the
+ *   identity effect is byte-identical. Neighbouring cells the output depth
+ *   writes alike stay one segment: a segment is cut only where the written
+ *   colours change, so two colours that land on one index are one run.
+ * - New colours are built with `ColorSpec.fromRgba`, never parsed from a
+ *   string, so no frame adds an entry to a parse cache.
+ * - With no colour output (`colorSystem: null`) there is nothing for an
+ *   effect to change, and the child's segments pass through untouched.
+ *
+ * Positions are the child's own: row and column count from the top-left of
+ * what the child drew, so a sweep crosses the element, not the screen.
+ */
+import { type ColorRgba, type TerminalTheme } from "../core/color.js";
+import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+import { Segment } from "../core/segment.js";
+/**
+ * A cell's foreground and background as they appear on screen — the glyph's
+ * colour and the colour behind it — which are the colours an effect moves.
+ * Under `reverse` they are the style's two colours swapped.
+ */
+export interface CellColors {
+    readonly fg: ColorRgba;
+    readonly bg: ColorRgba;
+}
+/**
+ * Where a cell is in the output of the renderable an effect wraps, its seed:
+ * a number in [0, 1) that is the same for that cell on every frame, for an
+ * effect that varies cell by cell (a per-cell offset in time, a sparkle) —
+ * and which of its on-screen colours are the terminal's.
+ */
+export interface EffectCell {
+    readonly row: number;
+    readonly col: number;
+    readonly seed: number;
+    /**
+     * Whether the glyph's colour and the colour behind it, as the screen shows
+     * them, are the terminal's own: a slot the element's style leaves unset or
+     * sets to `default`. Such a colour is resolved through the theme, so its
+     * hex can equal one the element wrote; this is what tells them apart.
+     */
+    readonly terminal: {
+        readonly fg: boolean;
+        readonly bg: boolean;
+    };
+}
+/** A cell's colours at time `t`, in seconds. Return `colors` to leave it be. */
+export type Effect = (colors: CellColors, cell: EffectCell, t: number) => CellColors;
+export interface EffectedOptions {
+    /** The moment to draw, in seconds. */
+    readonly t: number;
+    /**
+     * Names the element for its seeds, so two elements showing the same text do
+     * not twinkle in lockstep. The same key gives the same seeds on every frame.
+     */
+    readonly key: string;
+    /**
+     * The terminal the frame is drawn on: the colours a cell that sets none is
+     * drawn in, and the sixteen an ANSI colour names. The terminal's own palette
+     * is never queried, so the caller says what it is.
+     */
+    readonly theme: TerminalTheme;
+}
+export declare class Effected implements Renderable, Measurable {
+    readonly renderable: Renderable;
+    readonly effect: Effect;
+    readonly t: number;
+    readonly key: string;
+    readonly theme: TerminalTheme;
+    constructor(renderable: Renderable, effect: Effect, options: EffectedOptions);
+    render(options: RenderOptions): Iterable<Segment>;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+    /**
+     * The specs that draw a cell's slot colours `to` where the segment drew
+     * `from` with `wire`: a slot the effect left alone keeps its written spec,
+     * and a moved one is laid on what is beneath it — the ground on
+     * `SURFACE_BLACK`, the glyph on that ground, as the writer lays any
+     * translucent colour (`Style.drawnColors`) — then drawn in the colour nearest it at `depth`
+     * that the terminal shows (`ColorSpec.matchOn`). A move the depth cannot
+     * show is no move: where the written spec is as near the moved colour as
+     * that match, the slot keeps it, so below truecolor a colour moved a little
+     * off any colour it can write — a theme slot, the default colour, the cube —
+     * is still drawn as that one.
+     */
+    private respec;
+    /** A cell's seed: FNV-1a of the key and the position, scaled into [0, 1). */
+    private seed;
+}

package/dist/renderables/effect.js

@@ -0,0 +1,182 @@
+/**
+ * Effected — a renderable whose finished cells' colours pass through an
+ * effect at a moment `t`.
+ *
+ * An effect is one pure function: a cell's colours, where the cell is, and a
+ * time in, the cell's new colours out. Shimmer, pulse, fade and dissolve are
+ * all this one shape, differing by what the function does with its inputs
+ * [LAW:one-type-per-behavior]; two effects stack by nesting one wrapper in
+ * another, which is the same as calling one after the other.
+ *
+ * [LAW:no-ambient-temporal-coupling] `t` is a constructor argument, not a
+ * clock read. Whoever draws frames builds the view for each frame's `t`, so
+ * the same `t` always draws the same bytes, at 30 frames a second or one
+ * every two seconds.
+ *
+ * What an effect may not do is the contract this module holds:
+ *
+ * - It changes how cells look, never which cells exist or who drew them. The
+ *   child's text is walked by grapheme cluster, so a wide glyph is one cell
+ *   to the effect and is never cut, and a run cut out of a segment keeps that
+ *   segment's link and meta and carries its anchor shifted to the run's first
+ *   cell (`Style.shiftedBy`), so hit testing still finds the owner.
+ * - A cell whose colours come back unchanged keeps its original `ColorSpec`,
+ *   and a segment whose every cell is unchanged is yielded as it was, so the
+ *   identity effect is byte-identical. Neighbouring cells the output depth
+ *   writes alike stay one segment: a segment is cut only where the written
+ *   colours change, so two colours that land on one index are one run.
+ * - New colours are built with `ColorSpec.fromRgba`, never parsed from a
+ *   string, so no frame adds an entry to a parse cache.
+ * - With no colour output (`colorSystem: null`) there is nothing for an
+ *   effect to change, and the child's segments pass through untouched.
+ *
+ * Positions are the child's own: row and column count from the top-left of
+ * what the child drew, so a sweep crosses the element, not the screen.
+ */
+import { cellLen, graphemes } from "../core/cells.js";
+import { ColorDepth, ColorSpec, SURFACE_BLACK, rgbDistance } from "../core/color.js";
+import { fnv1a } from "../core/fnv1a.js";
+import { Measurement } from "../core/measure.js";
+import { Segment } from "../core/segment.js";
+import { Style } from "../core/style.js";
+export class Effected {
+    renderable;
+    effect;
+    t;
+    key;
+    theme;
+    constructor(renderable, effect, options) {
+        this.renderable = renderable;
+        this.effect = effect;
+        if (!Number.isFinite(options.t)) {
+            throw new RangeError(`Effected needs a finite t, got ${options.t}`);
+        }
+        this.t = options.t;
+        this.key = options.key;
+        this.theme = options.theme;
+    }
+    *render(options) {
+        const segments = this.renderable.render(options);
+        if (options.colorSystem === null) {
+            yield* segments;
+            return;
+        }
+        // No depth named is no downgrade, as `drawnColors` reads it.
+        const depth = options.colorSystem ?? ColorDepth.TRUECOLOR;
+        let row = 0;
+        let col = 0;
+        for (const segment of segments) {
+            if (segment.isControl) {
+                yield segment;
+                continue;
+            }
+            const base = segment.style ?? Style.null();
+            // [LAW:single-enforcer] `drawnColors` is what the wire writes at this
+            // depth — alpha flattened, downgraded — and the theme resolves what it
+            // leaves to the terminal. A slot the effect leaves alone keeps the
+            // written spec, so it stays what the screen showed whatever moves
+            // beside it.
+            const wire = base.drawnColors(options.colorSystem ?? undefined);
+            const ink = (wire.color ?? DEFAULT).getTruecolor(this.theme, true);
+            const paper = (wire.bgcolor ?? DEFAULT).getTruecolor(this.theme, false);
+            const slots = { fg: ink, bg: paper };
+            const from = onScreen(slots, base);
+            const terminal = onScreen({ fg: wire.color?.isDefault ?? true, bg: wire.bgcolor?.isDefault ?? true }, base);
+            // [LAW:one-source-of-truth] A run is cells the wire writes alike: each
+            // cell is drawn at the output depth first and merged on the colours that
+            // writes, so two truecolors landing on one index stay one run. A cell
+            // the effect gave its neighbour's colours is drawn as that neighbour was.
+            const runs = [];
+            for (const glyph of graphemes(segment.text)) {
+                let colors = slots;
+                if (glyph === "\n") {
+                    row++;
+                    col = 0;
+                }
+                else {
+                    // Back from the screen to the style's slots: the same swap undoes itself.
+                    colors = onScreen(this.effect(from, { row, col, seed: this.seed(row, col), terminal }, this.t), base);
+                    col += cellLen(glyph);
+                }
+                const last = runs[runs.length - 1];
+                const drawn = last !== undefined && sameColors(last.colors, colors) ? last.drawn : this.respec(wire, slots, colors, depth);
+                if (last !== undefined && writesAlike(last.drawn, drawn)) {
+                    last.text += glyph;
+                    last.cells += cellLen(glyph);
+                    last.colors = colors;
+                }
+                else {
+                    runs.push({ text: glyph, cells: cellLen(glyph), colors, drawn });
+                }
+            }
+            if (runs.every((run) => writesAlike(run.drawn, wire))) {
+                yield segment;
+                continue;
+            }
+            let offset = 0;
+            for (const run of runs) {
+                const shifted = base.shiftedBy(offset);
+                const style = writesAlike(run.drawn, wire) ? shifted : shifted.add(Style.fromColor(run.drawn.color, run.drawn.bgcolor));
+                yield new Segment(run.text, style);
+                offset += run.cells;
+            }
+        }
+    }
+    measure(options) {
+        return Measurement.get(options, this.renderable);
+    }
+    /**
+     * The specs that draw a cell's slot colours `to` where the segment drew
+     * `from` with `wire`: a slot the effect left alone keeps its written spec,
+     * and a moved one is laid on what is beneath it — the ground on
+     * `SURFACE_BLACK`, the glyph on that ground, as the writer lays any
+     * translucent colour (`Style.drawnColors`) — then drawn in the colour nearest it at `depth`
+     * that the terminal shows (`ColorSpec.matchOn`). A move the depth cannot
+     * show is no move: where the written spec is as near the moved colour as
+     * that match, the slot keeps it, so below truecolor a colour moved a little
+     * off any colour it can write — a theme slot, the default colour, the cube —
+     * is still drawn as that one.
+     */
+    respec(wire, from, to, depth) {
+        // [LAW:one-source-of-truth] The writer's surface, so one translucent colour draws one way in a frame.
+        const ground = to.bg.compositeOver(SURFACE_BLACK);
+        const glyph = to.fg.compositeOver(ground);
+        const drawn = (spec, was, now, foreground) => {
+            const match = ColorSpec.matchOn(now, depth, this.theme, foreground);
+            return rgbDistance(was, now) <= rgbDistance(match.getTruecolor(this.theme, foreground), now) ? spec : match;
+        };
+        return { color: drawn(wire.color, from.fg, glyph, true), bgcolor: drawn(wire.bgcolor, from.bg, ground, false) };
+    }
+    /** A cell's seed: FNV-1a of the key and the position, scaled into [0, 1). */
+    seed(row, col) {
+        return Number.parseInt(fnv1a(`${this.key}:${row}:${col}`), 16) / 0x1_0000_0000;
+    }
+}
+const DEFAULT = ColorSpec.default();
+/**
+ * A style's colour slots as the screen shows them, or the reverse: `reverse`
+ * swaps glyph and ground, and swapping twice is where you started.
+ */
+function onScreen(slots, style) {
+    return style.reverse === true ? { fg: slots.bg, bg: slots.fg } : slots;
+}
+/**
+ * Whether two cells' colours are written alike. A slot with no colour is not
+ * the default colour: it writes nothing, so a style a container lays beneath
+ * (`Segment.applyStyle`) still shows through it, where `39`/`49` would not.
+ */
+function writesAlike(a, b) {
+    return slotWritesAlike(a.color, b.color, true) && slotWritesAlike(a.bgcolor, b.bgcolor, false);
+}
+function slotWritesAlike(a, b, foreground) {
+    return a === b || written(a, foreground) === written(b, foreground);
+}
+function written(spec, foreground) {
+    return spec?.getAnsiCodes(foreground).join(";") ?? "";
+}
+function sameColors(a, b) {
+    return sameColor(a.fg, b.fg) && sameColor(a.bg, b.bg);
+}
+function sameColor(a, b) {
+    return a.red === b.red && a.green === b.green && a.blue === b.blue && a.alpha === b.alpha;
+}