@promptctl/rich-js 0.23.0 → 0.24.1

package/dist/core/protocol.js

@@ -3,7 +3,7 @@
  * [LAW:one-source-of-truth] These interfaces are the single authority for the rendering contract.
  */
 import { cellCount } from "./cells.js";
-import { DEFAULT_THEME } from "./style.js";
+import { DEFAULT_THEME, Style } from "./style.js";
 /** Whether `text` is all ASCII — what an `asciiOnly` output can draw. */
 export const isAscii = (text) => /^[\x00-\x7F]*$/.test(text);
 export function drawable(options, chosen, ascii, glyphs = String) {
@@ -61,6 +61,8 @@ export function fitHeight(lines, height) {
 export function getStyle(options, style) {
     return (options.theme ?? DEFAULT_THEME).resolve(style);
 }
+/** The terminal's own foreground on its own background. */
+const TERMINAL_GROUND = Style.parse("default on default");
 /**
  * `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;
@@ -69,7 +71,10 @@ export function getStyle(options, style) {
  * 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
+ * readable; its attributes still set it apart. Both are named, not left
+ * unset, so the colour of whatever the run sits in — a quote, a link — does
+ * not show through: Rich's code keeps its own colours inside a quote, and the
+ * terminal's are the ones it keeps here. 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
@@ -79,7 +84,7 @@ 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;
+    return pairLost ? style.add(TERMINAL_GROUND) : style;
 }
 /**
  * The options a renderable should work from: the caller's, with `maxWidth`
@@ -104,6 +109,51 @@ export function groundedStyle(options, style) {
 export function withCellWidth(options) {
     return { ...options, maxWidth: cellCount(options.maxWidth) };
 }
+/** Under one column there is nothing to draw, or to measure. */
+export function drawsNothing(options) {
+    return cellCount(options.maxWidth) < 1;
+}
+/**
+ * `renderable` drawn under `options`: Rich's `Console.render`, which every
+ * renderable there is drawn through, so under one column nothing is.
+ *
+ * [LAW:single-enforcer] The one place that rule is kept. Every call of a
+ * `Renderable`'s `render` in `src/` goes through here — a container drawing
+ * its child, a renderable drawing the text it built, a host drawing a frame —
+ * and `test/seam/render-calls.test.ts` fails on one that does not. Before
+ * this, each container asked `drawsNothing` itself, and the ones that forgot
+ * drew a child handed no column anyway.
+ *
+ * It is also the one reporter of what the view holds (`onPresent`). Under one
+ * column a renderable is held, not drawn: what it holds (`Composite`) is
+ * walked and reported held in turn, and nothing renders, so no renderable
+ * that keeps state while it renders — a `Viewport`'s offset, a `TextInput`'s
+ * scroll window — ever commits it at a width that is not shown. The walk runs
+ * whether or not anyone listens. Drawing the squeezed subtree at one column
+ * instead, and dropping what it drew, did commit that state.
+ */
+export function render(renderable, options) {
+    const presence = drawsNothing(options) ? "held" : "drawn";
+    options.onPresent?.(renderable, presence);
+    if (presence === "drawn")
+        return renderable.render(options);
+    if (isComposite(renderable))
+        for (const content of renderable.contents())
+            render(content, options);
+    return [];
+}
+/**
+ * `options` as a measurement is asked with. A `measure` that renders to learn
+ * its shape draws nothing on the frame, so it reports nothing to `onPresent` —
+ * one that did would put a widget in the view at the moment a container
+ * measured it, and keep one the frame then cropped away.
+ *
+ * [LAW:single-enforcer] Every measurement starts here: `Measurement.get` and
+ * `withBoundedWidth` ask through it, and each `measure` passes it on.
+ */
+export function measuring(options) {
+    return { ...options, onPresent: undefined };
+}
 /**
  * The options a renderable should *lay out against*: `withCellWidth`, with an
  * unbounded offer resolved to the renderable's own natural width.
@@ -139,18 +189,6 @@ export function withCellWidth(options) {
  * rather than zero, and saying so names the cause — where `String.repeat` and
  * `new Array` only ever name their own argument.
  */
-/**
- * `options` as a measurement is asked with. A `measure` that renders to learn
- * its shape draws nothing on the frame, so it reports no owner to `onDraw` —
- * one that did would put a widget in document order at the moment a
- * container measured it, and keep one the frame then cropped away.
- *
- * [LAW:single-enforcer] Every measurement starts here: `Measurement.get` and
- * `withBoundedWidth` ask through it, and each `measure` passes it on.
- */
-export function measuring(options) {
-    return { ...options, onDraw: undefined };
-}
 export function withBoundedWidth(options, self) {
     const parsed = withCellWidth(options);
     if (Number.isFinite(parsed.maxWidth))
@@ -182,3 +220,6 @@ export function isScrollable(obj) {
         "scrollBy" in obj &&
         typeof obj.scrollBy === "function");
 }
+export function isComposite(obj) {
+    return "contents" in obj && typeof obj.contents === "function";
+}

package/dist/core/render.js

@@ -42,6 +42,7 @@
  * `Style.render` returns bare text for a null colour system.
  */
 import { ColorDepth, resolveDestination } from "./color.js";
+import { render } from "./protocol.js";
 import { OSC8_CLOSE, osc8Open } from "./osc8.js";
 const DEFAULT_WIDTH = 80;
 /**
@@ -101,5 +102,5 @@ export function renderToString(renderable, options) {
         // so a renderable measures what this very call will draw.
         colorSystem: destination.colorSystem,
     };
-    return segmentsToString(renderable.render(renderOptions), destination);
+    return segmentsToString(render(renderable, renderOptions), destination);
 }

package/dist/core/segment.d.ts

@@ -42,6 +42,15 @@ export declare class Segment {
      * whatever drew it, and its anchor says so; see `./anchor.ts`.
      */
     splitCells(position: CellCol): [Segment, Segment];
+    /**
+     * Cuts at each of `positions`, non-decreasing and inside this segment's
+     * cells: one piece more than there are positions, each exactly as wide as
+     * the distance between its cuts, the way `splitCells` cuts at one.
+     *
+     * [LAW:single-enforcer] Each piece but the first starts that many cells
+     * further into whatever drew it, and its anchor says so; see `./anchor.ts`.
+     */
+    private cutAt;
     private static _line;
     static line(): Segment;
     /**
@@ -51,6 +60,16 @@ export declare class Segment {
      * the owner's row that `lines[0]` is, for output that arrives in pieces.
      */
     static anchorLines(lines: Segment[][], owner: object, firstRow?: number): Segment[][];
+    /**
+     * When what `segments` show next changes, in seconds on the timeline of
+     * whoever drew them: the soonest `Style.nextChange` among them, read off
+     * the composed frame the way `anchorAt` reads an owner — `t` itself for a
+     * frame something in moves every frame, `Infinity` for one that never
+     * changes. What a host that drew the frame at `t` asks before drawing
+     * again: a frame of frames answers the next frame's start, a transition
+     * `t` until it is done, still content never.
+     */
+    static nextChange(segments: Iterable<Segment>): number;
     /**
      * The anchor of the cell at column `x` of row `y` in a composed frame, or
      * `undefined` when that cell was drawn by no owner or lies outside the frame.
@@ -140,7 +159,15 @@ export declare class Segment {
      */
     static removeColor(segments: Iterable<Segment>): Iterable<Segment>;
     /**
-     * Divides segments at cell positions. Yields arrays of segments for each section.
+     * Divides segments at cell positions: a section ending at each cut, and the
+     * cells after the last cut when there are any. A segment wider than zero
+     * that starts at a cut opens the section after it; one with no cells stays
+     * in the section it ends.
+     *
+     * One walk, and each segment is cut once at every cut that falls inside it:
+     * cutting what is left of it again at each cut re-measures and copies the
+     * rest every time, so a long line wrapped into many rows took time quadratic
+     * in its length.
      */
     static divide(segments: Segment[], cuts: number[]): Segment[][];
     /**

package/dist/core/segment.js

@@ -59,11 +59,10 @@ export class Segment {
             return [this, new Segment("")];
         if (position <= 0)
             return [new Segment(""), this];
-        const [leftText, rightText] = cutCells(this.text, position);
-        return [
-            new Segment(leftText, this.style),
-            new Segment(rightText, this.style?.shiftedBy(position)),
-        ];
+        return this.cutAt([position]);
+    }
+    cutAt(positions) {
+        return cutCells(this.text, positions).map((text, piece) => new Segment(text, piece === 0 ? this.style : this.style?.shiftedBy(positions[piece - 1])));
     }
     // --- Static factories ---
     static _line;
@@ -91,6 +90,21 @@ export class Segment {
             });
         });
     }
+    /**
+     * When what `segments` show next changes, in seconds on the timeline of
+     * whoever drew them: the soonest `Style.nextChange` among them, read off
+     * the composed frame the way `anchorAt` reads an owner — `t` itself for a
+     * frame something in moves every frame, `Infinity` for one that never
+     * changes. What a host that drew the frame at `t` asks before drawing
+     * again: a frame of frames answers the next frame's start, a transition
+     * `t` until it is done, still content never.
+     */
+    static nextChange(segments) {
+        let soonest = Number.POSITIVE_INFINITY;
+        for (const segment of segments)
+            soonest = Math.min(soonest, segment.style?.nextChange ?? Number.POSITIVE_INFINITY);
+        return soonest;
+    }
     /**
      * The anchor of the cell at column `x` of row `y` in a composed frame, or
      * `undefined` when that cell was drawn by no owner or lies outside the frame.
@@ -114,8 +128,11 @@ export class Segment {
      */
     static *applyStyle(segments, style, postStyle) {
         // Applying no style is the identity, so the segments pass through as they
-        // are instead of each being copied into an equal one.
-        if (!style && !postStyle) {
+        // are instead of each being copied into an equal one. A null style — a
+        // theme's plain entry, such as `markdown.item` — is no style.
+        const pre = style?.isNull ? undefined : style;
+        const post = postStyle?.isNull ? undefined : postStyle;
+        if (!pre && !post) {
             yield* segments;
             return;
         }
@@ -125,10 +142,10 @@ export class Segment {
                 continue;
             }
             let s = segment.style;
-            if (style)
-                s = style.add(s);
-            if (postStyle)
-                s = s ? s.add(postStyle) : postStyle;
+            if (pre)
+                s = pre.add(s);
+            if (post)
+                s = s ? s.add(post) : post;
             yield new Segment(segment.text, s, segment.control);
         }
     }
@@ -383,45 +400,44 @@ export class Segment {
         }
     }
     /**
-     * Divides segments at cell positions. Yields arrays of segments for each section.
+     * Divides segments at cell positions: a section ending at each cut, and the
+     * cells after the last cut when there are any. A segment wider than zero
+     * that starts at a cut opens the section after it; one with no cells stays
+     * in the section it ends.
+     *
+     * One walk, and each segment is cut once at every cut that falls inside it:
+     * cutting what is left of it again at each cut re-measures and copies the
+     * rest every time, so a long line wrapped into many rows took time quadratic
+     * in its length.
      */
     static divide(segments, cuts) {
         if (cuts.length === 0)
             return [segments];
-        const result = [];
-        let segmentIndex = 0;
-        let cellOffset = 0;
-        let currentSegment = segments[segmentIndex];
-        for (const cut of cuts) {
-            const section = [];
-            while (currentSegment && cellOffset + currentSegment.cellLength <= cut) {
-                section.push(currentSegment);
-                cellOffset += currentSegment.cellLength;
-                segmentIndex++;
-                currentSegment = segments[segmentIndex];
-            }
-            if (currentSegment && !currentSegment.isControl && cellOffset < cut) {
-                const splitAt = asCellCol(cut - cellOffset);
-                const [left, right] = currentSegment.splitCells(splitAt);
-                if (left.hasText)
-                    section.push(left);
-                cellOffset += left.cellLength;
-                currentSegment = right;
+        const sections = [[]];
+        let offset = 0;
+        let next = 0;
+        for (const segment of segments) {
+            const end = offset + segment.cellLength;
+            const inside = [];
+            for (; next < cuts.length && cuts[next] < end; next++) {
+                const cut = cuts[next];
+                if (cut <= offset)
+                    sections.push([]);
+                else
+                    inside.push(asCellCol(cut - offset));
             }
-            result.push(section);
+            const [head, ...rest] = inside.length === 0 ? [segment] : segment.cutAt(inside);
+            sections[sections.length - 1].push(head);
+            // A piece between two cuts at one cell has no text: the section it is holds nothing.
+            for (const piece of rest)
+                sections.push(piece.hasText ? [piece] : []);
+            offset = end;
         }
-        // Remaining segments
-        const tail = [];
-        if (currentSegment?.hasText)
-            tail.push(currentSegment);
-        segmentIndex++;
-        while (segmentIndex < segments.length) {
-            tail.push(segments[segmentIndex]);
-            segmentIndex++;
-        }
-        if (tail.length > 0)
-            result.push(tail);
-        return result;
+        for (; next < cuts.length; next++)
+            sections.push([]);
+        if (sections[sections.length - 1].length === 0)
+            sections.pop();
+        return sections;
     }
     // --- Layout helpers ---
     /**

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 Measurable, type Renderable, type RenderOptions } from "./protocol.js";
+import { type Composite, 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,11 +97,12 @@ 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 {
+export declare class Strip<T extends StyledRenderable = StyledRenderable> implements Renderable, Measurable, Composite {
     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
@@ -156,22 +157,49 @@ export interface JoinCell {
     readonly bg: CellColor;
 }
 /**
- * The cells a joiner draws at each kind of join:
- *   • `seam` — between two neighbours;
+ * A cell of a seam, or one of the joiner's caps standing in a seam's place:
+ * `{ cap: "tail" }` closes the run the seam leaves, `{ cap: "lead" }` opens the
+ * run it enters, drawn as whatever caps the seam is joined with. That is how
+ * a seam that parts its runs — `capsule`, `metro` — ends each in the caps
+ * picked for it rather than in caps of its own.
+ */
+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`;
+ *     would vanish; the same width as `seam`.
+ */
+export interface SeamForm {
+    readonly seam: readonly SeamCell[];
+    readonly divider: readonly SeamCell[];
+}
+/**
+ * What a joiner draws at the ends of a run, in one form:
  *   • `lead` — where a run is entered from nothing: the strip's start, or a
  *     neighbour with no ground for the seam to paint. It cannot name `left`;
  *   • `tail` — where a run leaves into nothing. It cannot name `right`.
  */
-export interface JoinShape {
-    readonly seam: readonly JoinCell[];
-    readonly divider: readonly JoinCell[];
+export interface CapsForm {
     readonly lead: readonly JoinCell[];
     readonly tail: readonly JoinCell[];
 }
+/**
+ * The middle of a joiner: its seam, and the `ascii` seam an ASCII-only output
+ * draws instead. Picked apart from the caps, so any seam ends in any caps.
+ */
+export interface JoinSeam {
+    readonly glyph: SeamForm;
+    readonly ascii: SeamForm;
+}
+/** The ends of a joiner: its caps, and the `ascii` caps an ASCII-only output draws instead. */
+export interface JoinCaps {
+    readonly glyph: CapsForm;
+    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,
@@ -180,28 +208,70 @@ export interface JoinShape {
  */
 export declare const SEAM_MIN_DELTA_E = 0.04;
 /**
- * The one joiner: what it draws at each join is the `JoinShape` it is given,
- * so a new joiner is a value, never a class.
+ * The one joiner: what it draws is a `JoinSeam` between neighbours and a
+ * `JoinCaps` at the ends of each run, picked independently, so a new joiner is
+ * a pair of values, never a class.
  *
  * Which part a join draws is read off its two neighbours. A neighbour is
  * missing at the strip's ends, and counts as missing — an endpoint — when the
- * shape paints with its ground anywhere and it has none to paint. With both present the
- * join is the seam, or the divider where every seam cell's ink is drawn
- * indistinct from its ground at `options.colorSystem`; with only the right, the lead; with only
- * the left, the tail; with neither, nothing.
+ * seam paints with its ground anywhere and it has none to paint. With both
+ * present the join is the seam, or the divider where every seam cell's ink is
+ * drawn indistinct from its ground at `options.colorSystem`; with only the
+ * right, the lead; with only the left, the tail; with neither, nothing. A cap
+ * that paints with its neighbour's ground is drawn only beside a neighbour
+ * with one, so caps that need grounds never stop a seam that needs none.
  *
- * `ascii` is the shape an ASCII-only output draws instead, whole.
+ * An ASCII-only output draws the `ascii` form of both, whole.
  */
 export declare class CellJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
-    readonly shape: JoinShape;
-    readonly ascii: JoinShape;
+    readonly seam: JoinSeam;
+    readonly caps: JoinCaps;
     private readonly _forms;
-    constructor(shape: JoinShape, ascii: JoinShape);
+    constructor(seam: JoinSeam, caps: JoinCaps);
     join(left: T | null, right: T | null, { index }: JoinContext): Renderable;
 }
 /**
- * The bundled joiners, by name. What each draws is `docs/strip.md`'s
- * "Built-in joiners"; a name from config is read with `joinerNamed`.
+ * The bundled seams, by name: what a joiner draws between two neighbours.
+ * What each draws is `docs/strip.md`'s "Seams"; any of them ends in any of
+ * `CAPS`.
+ */
+export declare const SEAMS: Readonly<{
+    powerline: JoinSeam;
+    prism: JoinSeam;
+    slant: JoinSeam;
+    backslant: JoinSeam;
+    flame: JoinSeam;
+    pixel: JoinSeam;
+    ice: JoinSeam;
+    bubble: JoinSeam;
+    capsule: JoinSeam;
+    wrapper: JoinSeam;
+    metro: JoinSeam;
+    stitch: JoinSeam;
+    torn: JoinSeam;
+    plain: JoinSeam;
+}>;
+/**
+ * The bundled caps, by name: what a joiner draws where a run begins and ends.
+ * What each draws is `docs/strip.md`'s "Caps"; any of them ends any of
+ * `SEAMS`.
+ */
+export declare const CAPS: Readonly<{
+    powerline: JoinCaps;
+    slant: JoinCaps;
+    backslant: JoinCaps;
+    flame: JoinCaps;
+    pixel: JoinCaps;
+    ice: JoinCaps;
+    bubble: JoinCaps;
+    capsule: JoinCaps;
+    wrapper: JoinCaps;
+    flat: JoinCaps;
+}>;
+/**
+ * The bundled joiners, by name: each a seam from `SEAMS` ended in caps from
+ * `CAPS`. What each draws is `docs/strip.md`'s "Built-in joiners"; a name from
+ * config is read with `joinerNamed`.
  */
 export declare const JOINERS: Readonly<{
     powerline: CellJoiner<StyledRenderable>;
@@ -220,16 +290,24 @@ export declare const JOINERS: Readonly<{
     plain: CellJoiner<StyledRenderable>;
 }>;
 /**
- * The bundled joiner `name` names — a name read from config, parsed. Throws on
- * any other string, naming the ones there are; an own-key test, so `toString`
- * and the rest of `Object.prototype` are not joiners.
+ * A joiner as config names it: one of `JOINERS`, or a seam from `SEAMS` ended
+ * in caps from `CAPS`, each named apart.
+ */
+export type JoinerSpec = string | {
+    readonly seam: string;
+    readonly caps: string;
+};
+/**
+ * The joiner `spec` names — a joiner read from config, parsed. Throws on a
+ * name its table lacks, naming the ones there are; an own-key test, so
+ * `toString` and the rest of `Object.prototype` are no one's name.
  */
-export declare function joinerNamed(name: string): CellJoiner;
+export declare function joinerNamed(spec: JoinerSpec): CellJoiner;
 /**
  * A ramp of `steps` cells from the left ground to the right. Each cell is the
  * half block U+258C, ink on its left half and ground on its right, so it
- * carries two samples; ASCII draws a space, keeping the grounds alone. Nothing
- * at the ends, or beside a neighbour with no ground — there is no colour to
- * ramp toward.
+ * carries two samples; ASCII draws a space, keeping the grounds alone. Beside
+ * a neighbour with no ground there is no colour to ramp toward, so that join
+ * draws the caps the ramp is ended in.
  */
-export declare function gradientJoiner(steps?: number): CellJoiner;
+export declare function gradientSeam(steps?: number): JoinSeam;