@promptctl/rich-js 0.18.1 → 0.19.0

package/dist/core/protocol.d.ts

@@ -4,7 +4,8 @@
  */
 import type { Segment } from "./segment.js";
 import { type Style, type StyleSyntaxError, type Theme } from "./style.js";
-import type { ColorDepth } from "./color.js";
+import { ColorDepth } from "./color.js";
+import type { Highlighter } from "./highlighter.js";
 /**
  * What becomes of a line still wider than its width once wrapping is done.
  * `"fold"` breaks it across lines, `"crop"` cuts it at the edge, `"ellipsis"`
@@ -41,8 +42,30 @@ export interface RenderOptions {
     justify?: "left" | "center" | "right" | "full";
     overflow?: OverflowMethod;
     noWrap?: boolean;
-    highlight?: unknown;
-    markup?: unknown;
+    /**
+     * Whether a string handed to a renderable — a cell, a label, a pane — is
+     * read as markup when it is drawn. Absent, it is, as a `Console`'s is unless
+     * told otherwise. A `Console` passes its own setting, and `print`'s.
+     */
+    markup?: boolean;
+    /**
+     * Whether a string handed to a renderable is highlighted when it is drawn,
+     * by `highlighter`. Absent, it is, as a `Console`'s is unless told
+     * otherwise. A `Console` passes its own setting, and `print`'s; a renderable
+     * that draws its strings plain, as Rich's `Panel`, `Table` and `Tree` do by
+     * default, sets it false for what it renders — Rich's
+     * `options.update(highlight=False)` — and a table column's `highlight` sets
+     * it either way. `activeHighlighter` is the one reading of the pair.
+     */
+    highlight?: boolean;
+    /**
+     * What highlights a string handed to a renderable, while `highlight` says
+     * to. A `Console` passes its highlighter whether or not its own `highlight`
+     * is on, as Rich's `render_str` reaches `console.highlighter`, so content
+     * that turns highlighting on finds the console's highlighter there. Absent,
+     * nothing highlights.
+     */
+    highlighter?: Highlighter;
     /**
      * The depth the output will be encoded at, `null` when it carries no colour.
      * A renderable choosing between two ways of drawing something — the strip's
@@ -177,6 +200,21 @@ export type StyleErrorHandler = (error: StyleSyntaxError, style: string) => void
  * theme })` changed nothing.
  */
 export declare function getStyle(options: RenderOptions, style: string | Style): Style;
+/**
+ * `style` as the depth the render is encoded at can draw it. A style that
+ * paints its own ground in fixed colours chose its ink and ground as a pair;
+ * at sixteen colours the writer rounds a fixed colour to an ANSI slot, which
+ * the terminal paints in its own theme's colour, and no pair of slots reads in
+ * every bundled theme. So where the depth would turn a fixed colour of the
+ * pair into a slot, the pair is dropped and the run is drawn on the
+ * terminal's own foreground and background, which its theme does make
+ * readable; its attributes still set it apart. A style whose colours are
+ * slots already (`white on blue`), or that paints no ground (`bold magenta`),
+ * was written for the terminal's own colours and is drawn as written. Rich
+ * draws a highlighted line number the same way below 256 colours
+ * (`Syntax._get_number_styles`).
+ */
+export declare function groundedStyle(options: RenderOptions, style: Style): Style;
 /**
  * The options a renderable should work from: the caller's, with `maxWidth`
  * parsed into an actual count of cells.

package/dist/core/protocol.js

@@ -60,6 +60,26 @@ export function fitHeight(lines, height) {
 export function getStyle(options, style) {
     return (options.theme ?? DEFAULT_THEME).resolve(style);
 }
+/**
+ * `style` as the depth the render is encoded at can draw it. A style that
+ * paints its own ground in fixed colours chose its ink and ground as a pair;
+ * at sixteen colours the writer rounds a fixed colour to an ANSI slot, which
+ * the terminal paints in its own theme's colour, and no pair of slots reads in
+ * every bundled theme. So where the depth would turn a fixed colour of the
+ * pair into a slot, the pair is dropped and the run is drawn on the
+ * terminal's own foreground and background, which its theme does make
+ * readable; its attributes still set it apart. A style whose colours are
+ * slots already (`white on blue`), or that paints no ground (`bold magenta`),
+ * was written for the terminal's own colours and is drawn as written. Rich
+ * draws a highlighted line number the same way below 256 colours
+ * (`Syntax._get_number_styles`).
+ */
+export function groundedStyle(options, style) {
+    const drawn = style.drawnColors(options.colorSystem ?? undefined);
+    const lost = (written, shown) => written?.fixedValue !== undefined && shown?.fixedValue === undefined;
+    const pairLost = style.bgcolor !== undefined && (lost(style.color, drawn.color) || lost(style.bgcolor, drawn.bgcolor));
+    return pairLost ? style.withoutColor : style;
+}
 /**
  * The options a renderable should work from: the caller's, with `maxWidth`
  * parsed into an actual count of cells.

package/dist/core/render.d.ts

@@ -10,50 +10,57 @@
  * an explicit `ColorDepth` enum / non-`"auto"` spec, or supply `env` and
  * `isTTY` in the options so detection does not consult ambient process state.
  *
- * [LAW:single-enforcer] The Segment-to-ANSI conversion lives in `segmentsToString`
- * and is the single way segments become wire bytes. `Console._writeSegments`,
- * `Live.refresh`, `Screen`'s frame paint, `renderToString`, and
- * `segmentToString` all delegate here, so terminal output, live frames, widget
- * frames, string export, and single-segment encoding agree by construction.
+ * [LAW:single-enforcer] The Segment-to-ANSI conversion lives in `segmentToString`
+ * and is the single way a segment becomes wire bytes. `segmentsToString` is
+ * that encoding joined, and `Console._writeSegments`, `Painter` (every `Live`
+ * and `App` frame) and `renderToString` all go through it, so terminal output,
+ * live and app frames and string export agree by construction.
  *
  * [LAW:one-source-of-truth] What the encoding needs from where it writes
  * arrives as one `Destination` value. Each caller resolves its destination
  * once — spec, detection, and its own overrides — and hands it through whole,
  * so a depth is never paired with a link setting taken from somewhere else.
  *
- * [LAW:dataflow-not-control-flow] The same pipeline runs every render: collect
- * non-control non-empty pieces, partition by SGR-codes (SGR-runs), partition
- * each run by link (link-runs), emit one SGR open/close per run with link
- * open/close pairs sitting inside. Colour and hyperlinks are two facts about
- * the destination: `colorSystem === null` empties every piece's SGR-codes, and
- * `hyperlinks === false` empties every piece's link. A colour depth never
- * removes a link — a hyperlink is not a colour, and a NO_COLOR terminal still
- * follows OSC 8.
+ * Every segment is written alone, exactly as Python Rich 9d8f9a3 writes it
+ * (`Console._render_buffer` calls `Style.render` per segment): its SGR codes
+ * open, its text, a reset, and an OSC 8 pair around all three when it carries
+ * a link. Two adjacent segments with equal codes are two runs, not one. That
+ * costs a reset and a reopen the terminal draws identically, and it is what
+ * lets a fixture generated from the reference hold any sequence of segments,
+ * rather than only those in which no two neighbours happen to share a style
+ * (rich-render-g5g8). The price of that is that where a renderable cuts its
+ * segments is now in the bytes, so a renderable pinned against the reference
+ * has to cut where the reference cuts, as `Box`'s rules and `Table`'s blank
+ * cell lines do. A link split across segments still hovers as one link,
+ * because every pair it becomes carries the id `osc8Open` derives from the URL.
  *
- * [LAW:types-are-the-program] Adjacent same-style segments share an SGR wrap
- * because the SGR-codes string is the same group key for both — the
- * partitioning shape (data) encodes the byte structure; the emit walk is a
- * mechanical fold over it.
+ * Colour and hyperlinks are two facts about the destination:
+ * `colorSystem === null` empties every segment's SGR codes, and
+ * `hyperlinks === false` drops every segment's link. A colour depth never
+ * removes a link — a hyperlink is not a colour, and a NO_COLOR terminal still
+ * follows OSC 8. This is where the port departs from the reference, whose
+ * `Style.render` returns bare text for a null colour system.
  */
 import { ColorDepth } from "./color.js";
-import type { Destination } from "./color.js";
+import type { ColorSystemName, Destination } from "./color.js";
+import type { Env } from "./env.js";
 import type { Segment } from "./segment.js";
 import type { Renderable, RenderOptions } from "./protocol.js";
-export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" | "onStyleError"> {
+export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" | "theme" | "onStyleError" | "highlight" | "highlighter"> {
     /** Cell width to render into. Default 80. */
     width?: number;
     /**
-     * Color encoding to emit. Accepts a string spec (`"auto"`, `"truecolor"`,
-     * `"256"`, `"ansi"`, `"none"`), a `ColorDepth` enum value, or `null` to
+     * Color encoding to emit. Accepts a `ColorSystemName` (`"auto"`,
+     * `"truecolor"`, `"256"`, `"ansi"`, `"none"`), a `ColorDepth` enum value, or `null` to
      * strip SGR colors/attributes. Hyperlinks are `hyperlinks`' concern. Default
      * truecolor.
      */
-    colorSystem?: string | ColorDepth | null;
+    colorSystem?: ColorSystemName | ColorDepth | null;
     /**
      * Environment to consult when `colorSystem` is `"auto"`. Defaults to
      * `process.env`. Pass an explicit value to keep rendering deterministic.
      */
-    env?: NodeJS.ProcessEnv;
+    env?: Env;
     /**
      * Whether output is going to a TTY when `colorSystem` is `"auto"`. Defaults
      * to `process.stdout?.isTTY`. Pass an explicit value to keep rendering
@@ -71,14 +78,10 @@ export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" |
     hyperlinks?: boolean;
 }
 /**
- * Encodes a single segment as ANSI bytes for `destination`. Equivalent to
- * `segmentsToString([segment], destination)` — same SGR / OSC 8 layout.
+ * Encodes one segment as ANSI bytes for `destination`: the reference's
+ * `Style.render` for that segment, and nothing for a control segment.
  */
 export declare function segmentToString(segment: Segment, destination: Destination): string;
-/**
- * Encodes a sequence of segments as ANSI bytes for `destination`, coalescing
- * adjacent same-SGR segments under a single SGR open/close pair, with OSC 8
- * link pairs nested inside per same-link sub-run.
- */
+/** Encodes a sequence of segments as ANSI bytes for `destination`, one segment at a time. */
 export declare function segmentsToString(segments: Iterable<Segment>, destination: Destination): string;
 export declare function renderToString(renderable: Renderable, options?: RenderToStringOptions): string;

package/dist/core/render.js

@@ -10,106 +10,63 @@
  * an explicit `ColorDepth` enum / non-`"auto"` spec, or supply `env` and
  * `isTTY` in the options so detection does not consult ambient process state.
  *
- * [LAW:single-enforcer] The Segment-to-ANSI conversion lives in `segmentsToString`
- * and is the single way segments become wire bytes. `Console._writeSegments`,
- * `Live.refresh`, `Screen`'s frame paint, `renderToString`, and
- * `segmentToString` all delegate here, so terminal output, live frames, widget
- * frames, string export, and single-segment encoding agree by construction.
+ * [LAW:single-enforcer] The Segment-to-ANSI conversion lives in `segmentToString`
+ * and is the single way a segment becomes wire bytes. `segmentsToString` is
+ * that encoding joined, and `Console._writeSegments`, `Painter` (every `Live`
+ * and `App` frame) and `renderToString` all go through it, so terminal output,
+ * live and app frames and string export agree by construction.
  *
  * [LAW:one-source-of-truth] What the encoding needs from where it writes
  * arrives as one `Destination` value. Each caller resolves its destination
  * once — spec, detection, and its own overrides — and hands it through whole,
  * so a depth is never paired with a link setting taken from somewhere else.
  *
- * [LAW:dataflow-not-control-flow] The same pipeline runs every render: collect
- * non-control non-empty pieces, partition by SGR-codes (SGR-runs), partition
- * each run by link (link-runs), emit one SGR open/close per run with link
- * open/close pairs sitting inside. Colour and hyperlinks are two facts about
- * the destination: `colorSystem === null` empties every piece's SGR-codes, and
- * `hyperlinks === false` empties every piece's link. A colour depth never
- * removes a link — a hyperlink is not a colour, and a NO_COLOR terminal still
- * follows OSC 8.
+ * Every segment is written alone, exactly as Python Rich 9d8f9a3 writes it
+ * (`Console._render_buffer` calls `Style.render` per segment): its SGR codes
+ * open, its text, a reset, and an OSC 8 pair around all three when it carries
+ * a link. Two adjacent segments with equal codes are two runs, not one. That
+ * costs a reset and a reopen the terminal draws identically, and it is what
+ * lets a fixture generated from the reference hold any sequence of segments,
+ * rather than only those in which no two neighbours happen to share a style
+ * (rich-render-g5g8). The price of that is that where a renderable cuts its
+ * segments is now in the bytes, so a renderable pinned against the reference
+ * has to cut where the reference cuts, as `Box`'s rules and `Table`'s blank
+ * cell lines do. A link split across segments still hovers as one link,
+ * because every pair it becomes carries the id `osc8Open` derives from the URL.
  *
- * [LAW:types-are-the-program] Adjacent same-style segments share an SGR wrap
- * because the SGR-codes string is the same group key for both — the
- * partitioning shape (data) encodes the byte structure; the emit walk is a
- * mechanical fold over it.
+ * Colour and hyperlinks are two facts about the destination:
+ * `colorSystem === null` empties every segment's SGR codes, and
+ * `hyperlinks === false` drops every segment's link. A colour depth never
+ * removes a link — a hyperlink is not a colour, and a NO_COLOR terminal still
+ * follows OSC 8. This is where the port departs from the reference, whose
+ * `Style.render` returns bare text for a null colour system.
  */
 import { ColorDepth, resolveDestination } from "./color.js";
 import { OSC8_CLOSE, osc8Open } from "./osc8.js";
 const DEFAULT_WIDTH = 80;
-function segmentToPiece(segment, destination) {
-    if (segment.isControl)
-        return undefined;
-    if (segment.text.length === 0)
-        return undefined;
-    const style = segment.style;
-    if (!style || style.isNull) {
-        return { text: segment.text, sgrCodes: "", link: undefined };
-    }
-    // [LAW:one-type-per-behavior] Colour depth governs SGR only; hyperlinks are
-    // their own fact. Coupling them let a colour setting delete every control.
-    return {
-        text: segment.text,
-        sgrCodes: destination.colorSystem === null ? "" : style.toSgrCodes(destination.colorSystem),
-        link: destination.hyperlinks ? style.link : undefined,
-    };
-}
 /**
- * Encodes a single segment as ANSI bytes for `destination`. Equivalent to
- * `segmentsToString([segment], destination)` — same SGR / OSC 8 layout.
+ * Encodes one segment as ANSI bytes for `destination`: the reference's
+ * `Style.render` for that segment, and nothing for a control segment.
  */
 export function segmentToString(segment, destination) {
-    return segmentsToString([segment], destination);
+    if (segment.isControl)
+        return "";
+    const { text, style } = segment;
+    // As the reference's `if not text` and `if style:` — no pair around nothing.
+    if (text.length === 0 || style === undefined)
+        return text;
+    // [LAW:one-type-per-behavior] Colour depth governs SGR only; hyperlinks are
+    // their own fact. Coupling them let a colour setting delete every control.
+    const codes = destination.colorSystem === null ? "" : style.toSgrCodes(destination.colorSystem);
+    const styled = codes.length > 0 ? `\x1b[${codes}m${text}\x1b[0m` : text;
+    const link = destination.hyperlinks ? style.link : undefined;
+    return link === undefined ? styled : `${osc8Open(link)}${styled}${OSC8_CLOSE}`;
 }
-/**
- * Encodes a sequence of segments as ANSI bytes for `destination`, coalescing
- * adjacent same-SGR segments under a single SGR open/close pair, with OSC 8
- * link pairs nested inside per same-link sub-run.
- */
+/** Encodes a sequence of segments as ANSI bytes for `destination`, one segment at a time. */
 export function segmentsToString(segments, destination) {
-    const pieces = [];
-    for (const s of segments) {
-        const p = segmentToPiece(s, destination);
-        if (p)
-            pieces.push(p);
-    }
-    if (pieces.length === 0)
-        return "";
-    // [LAW:dataflow-not-control-flow] One linear chunk accumulator for the
-    // entire output; SGR / OSC 8 boundaries and piece texts all push into it
-    // in order. No per-link-run intermediate string, no quadratic `+=` chains.
     const parts = [];
-    let i = 0;
-    while (i < pieces.length) {
-        const sgr = pieces[i].sgrCodes;
-        let j = i + 1;
-        while (j < pieces.length && pieces[j].sgrCodes === sgr)
-            j++;
-        if (sgr.length > 0)
-            parts.push(`\x1b[${sgr}m`);
-        let k = i;
-        while (k < j) {
-            const link = pieces[k].link;
-            let l = k + 1;
-            while (l < j && pieces[l].link === link)
-                l++;
-            if (link) {
-                parts.push(osc8Open(link));
-                for (let m = k; m < l; m++)
-                    parts.push(pieces[m].text);
-                parts.push(OSC8_CLOSE);
-            }
-            else {
-                for (let m = k; m < l; m++)
-                    parts.push(pieces[m].text);
-            }
-            k = l;
-        }
-        if (sgr.length > 0)
-            parts.push("\x1b[0m");
-        i = j;
-    }
+    for (const segment of segments)
+        parts.push(segmentToString(segment, destination));
     return parts.join("");
 }
 export function renderToString(renderable, options) {
@@ -136,7 +93,10 @@ export function renderToString(renderable, options) {
         maxWidth: width,
         isTerminal: false,
         asciiOnly: options?.asciiOnly ?? false,
+        theme: options?.theme,
         onStyleError: options?.onStyleError,
+        highlight: options?.highlight,
+        highlighter: options?.highlighter,
         // [LAW:one-source-of-truth] The depth the segments below are encoded at,
         // so a renderable measures what this very call will draw.
         colorSystem: destination.colorSystem,

package/dist/core/segment.d.ts

@@ -33,12 +33,13 @@ export declare class Segment {
     get hasText(): boolean;
     get isControl(): boolean;
     /**
-     * Splits at a cell position. Returns [left, right].
+     * Splits at a cell position. Returns [left, right]: the first `position`
+     * cells and the rest, so the two halves are exactly as wide as this one —
+     * `cutCells` blanks a wide glyph the cut goes through rather than keep it
+     * whole on a side it would widen by a cell.
      *
-     * [LAW:single-enforcer] The right half starts as many cells further into
-     * whatever drew it as the left half took from this one, and its anchor says
-     * so; see `./anchor.ts`. That is not `leftText`'s width: a cut through a
-     * wide glyph pads the left half and keeps the whole glyph on the right.
+     * [LAW:single-enforcer] The right half starts `position` cells further into
+     * whatever drew it, and its anchor says so; see `./anchor.ts`.
      */
     splitCells(position: CellCol): [Segment, Segment];
     private static _line;

package/dist/core/segment.js

@@ -2,7 +2,7 @@
  * Segment — the atomic rendering unit. Every piece of styled terminal output
  * is represented as a Segment: (text, style?, control?).
  */
-import { cellLen, splitText, asCellCol } from "./cells.js";
+import { cellLen, cutCells, splitText, asCellCol } from "./cells.js";
 import { Style } from "./style.js";
 import { shiftAnchor } from "./anchor.js";
 // --- ControlType ---
@@ -45,12 +45,13 @@ export class Segment {
         return this.control !== undefined;
     }
     /**
-     * Splits at a cell position. Returns [left, right].
+     * Splits at a cell position. Returns [left, right]: the first `position`
+     * cells and the rest, so the two halves are exactly as wide as this one —
+     * `cutCells` blanks a wide glyph the cut goes through rather than keep it
+     * whole on a side it would widen by a cell.
      *
-     * [LAW:single-enforcer] The right half starts as many cells further into
-     * whatever drew it as the left half took from this one, and its anchor says
-     * so; see `./anchor.ts`. That is not `leftText`'s width: a cut through a
-     * wide glyph pads the left half and keeps the whole glyph on the right.
+     * [LAW:single-enforcer] The right half starts `position` cells further into
+     * whatever drew it, and its anchor says so; see `./anchor.ts`.
      */
     splitCells(position) {
         const len = this.cellLength;
@@ -58,10 +59,10 @@ export class Segment {
             return [this, new Segment("")];
         if (position <= 0)
             return [new Segment(""), this];
-        const [leftText, rightText] = splitText(this.text, position);
+        const [leftText, rightText] = cutCells(this.text, position);
         return [
             new Segment(leftText, this.style),
-            new Segment(rightText, this.style?.shiftedBy(len - cellLen(rightText))),
+            new Segment(rightText, this.style?.shiftedBy(position)),
         ];
     }
     // --- Static factories ---
@@ -394,13 +395,8 @@ export class Segment {
         for (const cut of cuts) {
             const section = [];
             while (currentSegment && cellOffset + currentSegment.cellLength <= cut) {
-                if (currentSegment.isControl) {
-                    section.push(currentSegment);
-                }
-                else {
-                    section.push(currentSegment);
-                    cellOffset += currentSegment.cellLength;
-                }
+                section.push(currentSegment);
+                cellOffset += currentSegment.cellLength;
                 segmentIndex++;
                 currentSegment = segments[segmentIndex];
             }

package/dist/core/strip.d.ts

@@ -27,7 +27,7 @@
  */
 import { Segment } from "./segment.js";
 import { Style } from "./style.js";
-import { 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.
@@ -52,11 +52,22 @@ export interface Joiner<T extends StyledRenderable = StyledRenderable> {
      */
     join(left: T | null, right: T | null): Renderable;
 }
-export declare class Strip<T extends StyledRenderable = StyledRenderable> implements Renderable {
+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>;
+    /**
+     * [LAW:one-source-of-truth] The width of the one row it draws, and that is
+     * both bounds: the row never wraps and no item is offered less than the whole
+     * width, so there is no narrower strip to report as a minimum. Read off the
+     * drawing rather than summed from the items' measurements, which describe
+     * how an item could be drawn, not how the walk draws it.
+     */
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
 }
 /**
  * The least ΔE_OK two neighbouring backgrounds must differ by for the powerline

package/dist/core/strip.js

@@ -27,7 +27,7 @@
  */
 import { Segment } from "./segment.js";
 import { Style } from "./style.js";
-import { ColorDepth, ColorSpec, blendRgb } from "./color.js";
+import { ColorDepth, ColorSpec, SURFACE_BLACK } from "./color.js";
 import { Oklch } from "./oklch.js";
 import { drawable } from "./protocol.js";
 // --- Strip ---
@@ -46,12 +46,17 @@ export class Strip {
         // start-cap, item, mid-join, item, ..., item, end-cap. Variability lives
         // in `items` and in what the joiner emits at each position — never in
         // whether a join runs.
-        yield* this.joiner.join(null, items[0]).render(options);
+        //
+        // The row sits its items side by side, so none is handed a justify: a
+        // `left` fills the canvas, and the first item would pad over the rest of
+        // the row. Where the row sits in the width is its container's to say.
+        const row = { ...options, justify: undefined };
+        yield* this.joiner.join(null, items[0]).render(row);
         for (let i = 0; i < items.length; i++) {
             const item = items[i];
-            yield* item.render(options);
+            yield* item.render(row);
             const next = i + 1 < items.length ? items[i + 1] : null;
-            yield* this.joiner.join(item, next).render(options);
+            yield* this.joiner.join(item, next).render(row);
         }
         // [LAW:one-source-of-truth] `Strip`'s sibling `FlexStrip` ends every line
         // it emits, including the last, and the other block-level renderables
@@ -61,11 +66,23 @@ export class Strip {
         // under composition: printed alone, Console's own "close whatever the
         // renderable left open" step (console.ts) papered over it, and a `Group`
         // of a Strip and a RichText ran the RichText onto the Strip's line
-        // instead of below it. (Not every renderable follows this — a `Spinner`
-        // or `ProgressBar` is a line *fragment*, not a block; see
-        // rich-flexstrip-5kf.4cq for the open question of formalizing that split.)
+        // instead of below it. `LINE_ENDS` in test/seam/line-ends.ts is the list
+        // of which renderables end their own line and which are fragments.
         yield Segment.line();
     }
+    /**
+     * [LAW:one-source-of-truth] The width of the one row it draws, and that is
+     * both bounds: the row never wraps and no item is offered less than the whole
+     * width, so there is no narrower strip to report as a minimum. Read off the
+     * drawing rather than summed from the items' measurements, which describe
+     * how an item could be drawn, not how the walk draws it.
+     */
+    measure(options) {
+        let width = 0;
+        for (const segment of this.render(options))
+            width += segment.cellLength;
+        return { minimum: width, maximum: width };
+    }
 }
 // --- Helpers ---
 const EMPTY = {
@@ -91,11 +108,11 @@ function bgAsFg(edge) {
 function paintableBg(bg) {
     return bg !== undefined && !bg.isDefault ? bg : undefined;
 }
-// A cap or arrow is its cell continuing: that cell's ground as the writer draws
-// it, so a translucent ground is not composited a second time over whatever it
-// enters.
+// A cap, arrow or gradient is its cell continuing: that cell's ground as the
+// writer draws it (`Style.drawnColors`, onto the terminal's black), so a
+// translucent ground is not composited a second time over whatever it enters.
 function drawnGround(bg) {
-    return new Style({ bgcolor: bg }).drawnColors().bgcolor;
+    return bg.flattenAlpha(SURFACE_BLACK);
 }
 // A cap is its glyph in its cell's ground, and "" is a flat end: no glyph, so
 // no segment — the same output as a join with nothing to paint.
@@ -117,10 +134,12 @@ export const SEAM_MIN_DELTA_E = 0.04;
 // encodes: the arrow's colour flattened onto its ground and the ground onto
 // the terminal's black, both downgraded to the depth the render encodes at,
 // so two grounds 256 colours round to one cube entry are the one entry they
-// render as. A colour whose RGB is the terminal theme's own (ANSI 0–15) has no
-// value here, so two of them are the same only when they are the same palette
-// slot — its `number`, never the name or the depth that spells it ("red",
-// "color(1)", an EIGHT_BIT spec on 0–15 are one slot).
+// render as. A colour whose RGB is the terminal theme's own (ANSI 0–15, a
+// blend reaching one) has no value here, so two of them are the same only
+// when they are one expression: the same palette slot — its `number`, never
+// the name or the depth that spells it ("red", "color(1)", an EIGHT_BIT spec
+// on 0–15 are one slot) — or the same blend, whose name spells each end by its
+// slot for the same reason.
 function vanishes(arrow, colorSystem) {
     // No colour emitted draws nothing to tell apart; measure what was handed.
     const { color, bgcolor } = arrow.drawnColors(colorSystem ?? ColorDepth.TRUECOLOR);
@@ -130,7 +149,7 @@ function vanishes(arrow, colorSystem) {
     const bv = bgcolor.fixedValue;
     return av !== undefined && bv !== undefined
         ? Oklch.fromRgba(av).deltaE(Oklch.fromRgba(bv)) < SEAM_MIN_DELTA_E
-        : color.number === bgcolor.number;
+        : color.number !== undefined ? color.number === bgcolor.number : color.name === bgcolor.name;
 }
 /**
  * The powerline set: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow),
@@ -275,17 +294,17 @@ export class GradientJoiner {
     join(left, right) {
         // [LAW:dataflow-not-control-flow] Endpoints have no opposite anchor to
         // interpolate toward — the data (a missing neighbor) makes the gradient
-        // empty. Same for edges lacking a bgcolor: nothing to blend between.
+        // empty. Same for edges with nothing to paint: nothing to blend between.
         if (left === null || right === null)
             return EMPTY;
         const steps = this._steps;
         return deferred(function* (options) {
-            const lbg = left.edgeStyle("right", options).bgcolor;
-            const rbg = right.edgeStyle("left", options).bgcolor;
+            const lbg = paintableBg(left.edgeStyle("right", options).bgcolor);
+            const rbg = paintableBg(right.edgeStyle("left", options).bgcolor);
             if (!lbg || !rbg)
                 return;
-            const lTrip = lbg.getTruecolor();
-            const rTrip = rbg.getTruecolor();
+            const from = drawnGround(lbg);
+            const to = drawnGround(rbg);
             // An ASCII cell carries one sample, the background: the gradient keeps
             // its colours at half the resolution.
             const half = drawable(options, HALF_BLOCK, " ");
@@ -296,8 +315,10 @@ export class GradientJoiner {
             for (let i = 0; i < steps; i++) {
                 const tLeft = (2 * i + 0.5) / samples;
                 const tRight = (2 * i + 1.5) / samples;
-                const fg = ColorSpec.fromRgba(blendRgb(lTrip, rTrip, tLeft));
-                const bg = ColorSpec.fromRgba(blendRgb(lTrip, rTrip, tRight));
+                // Each sample stays a mix of the two grounds, so a theme that draws
+                // `blue` in its own shade draws the ramp from that shade.
+                const fg = ColorSpec.blend(from, to, tLeft);
+                const bg = ColorSpec.blend(from, to, tRight);
                 yield new Segment(half, new Style({ color: fg, bgcolor: bg }));
             }
         });