@promptctl/rich-js 0.10.0 → 0.12.0

package/dist/core/pretty.js

@@ -20,7 +20,28 @@ import { cellLen } from "./cells.js";
 import { RichText } from "./text.js";
 import { ReprHighlighter } from "./highlighter.js";
 const reprHighlighter = new ReprHighlighter();
-const rootFrame = (maxWidth) => ({ inset: 0, level: 0, maxWidth, open: new WeakSet() });
+const rootFrame = (maxWidth) => ({
+    inset: 0,
+    level: 0,
+    maxWidth,
+    column: 0,
+    reserve: 0,
+    open: new WeakSet(),
+});
+/**
+ * The column reached after `text` is appended to a line currently at `column`.
+ *
+ * A hole's formatted value can itself span multiple lines — a nested
+ * container that failed its own compact try. What comes after it (a Map
+ * entry's tail, the next hole) sits after `text`'s *last* line, not at
+ * `column + cellLen(text)`, so a multi-line insert resets the column to that
+ * last line's width instead of accumulating across lines that were never on
+ * the same row.
+ */
+function lineColumn(column, text) {
+    const lastNewline = text.lastIndexOf("\n");
+    return lastNewline === -1 ? column + cellLen(text) : cellLen(text.slice(lastNewline + 1));
+}
 /**
  * The text, when it is a single line no wider than `budget` — otherwise `null`.
  *
@@ -111,6 +132,15 @@ function describesItself(value) {
 }
 /** What joins a container's positions on one line. Its width is charged for, so it is named once. */
 const SEPARATOR = ", ";
+/**
+ * What joins a container's positions across lines, once it has expanded —
+ * `SEPARATOR` without the trailing space a newline already provides.
+ * rich-pretty-xms: named, and derived rather than a second hand-typed
+ * literal, so the width it costs a non-last slot's own compact try —
+ * reserved via `Frame.reserve` — cannot drift from what `_formatObject`
+ * actually joins with.
+ */
+const EXPAND_SEPARATOR = SEPARATOR.trimEnd();
 /** The marker for positions the bound dropped, or nothing when it dropped none. */
 const elided = (dropped) => dropped > 0 ? [{ head: `... +${dropped}`, holes: [] }] : [];
 export class Pretty {
@@ -165,11 +195,15 @@ export class Pretty {
             return "undefined";
         switch (typeof value) {
             case "string": {
-                let str = value;
-                if (this.maxString !== undefined && str.length > this.maxString) {
-                    str = str.slice(0, this.maxString) + `+${value.length - this.maxString}`;
+                // The dropped count is an annotation about the value, not part of it,
+                // so it goes after the closing quote — the way `maxLength`'s `... +N`
+                // sits beside the kept entries rather than inside the last one. Inside
+                // the quotes it reads as content, and copying it out yields a string
+                // the program never held.
+                if (this.maxString === undefined || value.length <= this.maxString) {
+                    return JSON.stringify(value);
                 }
-                return JSON.stringify(str);
+                return JSON.stringify(value.slice(0, this.maxString)) + `+${value.length - this.maxString}`;
             }
             case "number":
             case "bigint":
@@ -281,35 +315,76 @@ export class Pretty {
         const shape = this._shape(value, at.level, Infinity);
         if (shape.kind === "text")
             return shape.text;
-        const indentStr = " ".repeat(this.indent * at.inset);
         if (!this.expandAll) {
+            // rich-pretty-xms: budget from `at.column` and `at.reserve`, not from
+            // `at.inset` alone. `at.column` is where *this* value's text actually
+            // starts on its line, which already includes whatever `_expandSlot`
+            // prepended for us (a key and its separator, a Map entry's `" => "`,
+            // ...); `at.reserve` is what a fixed piece of literal text — the rest
+            // of this hole's own tail, or the trailing `,` a non-last slot gets
+            // joined with — is known to cost right after, before this value's own
+            // text even starts. Deriving the budget from the indent alone assumed
+            // nothing precedes *or follows* the value on its line, which is only
+            // true at the root and for the last hole of an array's last element.
             const compact = this._joinOneLine(shape, {
                 level: at.level + 1,
-                budget: at.maxWidth - cellLen(indentStr),
+                budget: at.maxWidth - at.column - at.reserve,
                 open: at.open,
             });
             if (compact !== null)
                 return compact;
         }
+        const indentStr = " ".repeat(this.indent * at.inset);
         const innerIndent = " ".repeat(this.indent * (at.inset + 1));
-        const deeper = { inset: at.inset + 1, level: at.level + 1, maxWidth: at.maxWidth, open: at.open };
-        const parts = shape.slots.map((slot) => innerIndent + this._expandSlot(slot, deeper));
-        return shape.open + "\n" + parts.join(",\n") + "\n" + indentStr + shape.close;
+        // Every non-last slot gets `EXPAND_SEPARATOR` appended right after it
+        // below, on the same line as whatever its own last character was — the
+        // last slot doesn't. Two frames, not one per slot: `reserve` is the only
+        // field that varies, and it only ever takes these two values.
+        const base = { inset: at.inset + 1, level: at.level + 1, maxWidth: at.maxWidth, column: cellLen(innerIndent), open: at.open };
+        const midFrame = { ...base, reserve: cellLen(EXPAND_SEPARATOR) };
+        const lastFrame = { ...base, reserve: 0 };
+        const lastSlot = shape.slots.length - 1;
+        const parts = shape.slots.map((slot, i) => innerIndent + this._expandSlot(slot, i === lastSlot ? lastFrame : midFrame));
+        return shape.open + "\n" + parts.join(EXPAND_SEPARATOR + "\n") + "\n" + indentStr + shape.close;
     }
-    /** One position, with every value in it laid out. */
+    /**
+     * One position, with every value in it laid out.
+     *
+     * `at.column` is where `slot.head` begins. Rather than hand-tracking a
+     * second, parallel "column so far" alongside `out` — two values a future
+     * edit could update out of step, silently reintroducing a stale-budget bug
+     * of the same shape this file just fixed — each hole derives its own
+     * column fresh from `out` via `lineColumn`, the one place "text just
+     * emitted" becomes "column now". [LAW:one-source-of-truth] `out` is
+     * already the complete record; `column` is a read of it, not a second copy
+     * of the same fact. `_joinOneLine`'s probe sibling tracks the analogous
+     * thing via `budget` shrinking instead, because a probe already discards
+     * anything that overruns and so never needs to know where a multi-line
+     * insert's last line ends.
+     *
+     * Each hole's `reserve` is its own `tail` plus, only for the slot's last
+     * hole, whatever `at.reserve` already asked this whole slot to leave room
+     * for (`_formatObject`'s trailing `,`). An earlier hole's tail is never
+     * folded into a later hole's reserve — it is spent, not carried, the moment
+     * `out` grows past it.
+     */
     _expandSlot(slot, at) {
         let out = slot.head;
-        for (const hole of slot.holes) {
+        const lastHole = slot.holes.length - 1;
+        for (let i = 0; i < slot.holes.length; i++) {
+            const hole = slot.holes[i];
             // This is the read that costs the least when it fails: neighbours are
             // unaffected, so `{ a: 1, b: [Threw: …], c: 3 }` still shows everything
             // that could be read.
+            let text;
             try {
-                out += this._format(hole.read(), at);
+                const reserve = cellLen(hole.tail) + (i === lastHole ? at.reserve : 0);
+                text = this._format(hole.read(), { ...at, column: lineColumn(at.column, out), reserve });
             }
             catch (error) {
-                out += threw(error);
+                text = threw(error);
             }
-            out += hole.tail;
+            out += text + hole.tail;
         }
         return out;
     }
@@ -395,4 +470,3 @@ export class Pretty {
         }
     }
 }
-//# sourceMappingURL=pretty.js.map

package/dist/core/protocol.d.ts

@@ -3,7 +3,7 @@
  * [LAW:one-source-of-truth] These interfaces are the single authority for the rendering contract.
  */
 import type { Segment } from "./segment.js";
-import { type Style, type Theme } from "./style.js";
+import { type Style, type StyleSyntaxError, type Theme } from "./style.js";
 export interface RenderOptions {
     /**
      * The cells this renderable may occupy. A count of cells, so a non-negative
@@ -30,7 +30,24 @@ export interface RenderOptions {
      * built-in defaults apply. Read it through `getStyle` rather than directly.
      */
     theme?: Theme;
+    /**
+     * Called each time a render degrades a style string it cannot parse to
+     * unstyled, once per resolution — a style the render reads twice is reported
+     * twice. Absent, the failure passes silently. A handler that throws makes
+     * the render strict: the error leaves `render`.
+     */
+    onStyleError?: StyleErrorHandler;
 }
+/**
+ * Receives a style error a render would otherwise absorb: the parse failure,
+ * and the whole style string it came from — the error names only the token
+ * that failed, and `"bold rd"` loses its `bold` too.
+ *
+ * [LAW:no-mode-explosion] Strict mode is not a second option beside this one.
+ * It is a handler that throws, so there is no "strict and a callback" state
+ * whose order anyone has to define.
+ */
+export type StyleErrorHandler = (error: StyleSyntaxError, style: string) => void;
 /**
  * The style a `string | Style` stands for in this render.
  *
@@ -109,4 +126,3 @@ export interface Measurable {
 }
 export declare function isRenderable(obj: unknown): obj is Renderable;
 export declare function isMeasurable(obj: unknown): obj is Measurable;
-//# sourceMappingURL=protocol.d.ts.map

package/dist/core/protocol.js

@@ -99,4 +99,3 @@ export function isMeasurable(obj) {
         "measure" in obj &&
         typeof obj.measure === "function");
 }
-//# sourceMappingURL=protocol.js.map

package/dist/core/render.d.ts

@@ -67,4 +67,3 @@ export declare function segmentToString(segment: Segment, colorSystem: ColorDept
  */
 export declare function segmentsToString(segments: Iterable<Segment>, colorSystem: ColorDepth | null): string;
 export declare function renderToString(renderable: Renderable, options?: RenderToStringOptions): string;
-//# sourceMappingURL=render.d.ts.map

package/dist/core/render.js

@@ -29,7 +29,7 @@
  * mechanical fold over it.
  */
 import { ColorDepth, resolveColorSystem } from "./color.js";
-import { stripOscTerminators } from "./sanitize.js";
+import { OSC8_CLOSE, osc8Open } from "./osc8.js";
 const DEFAULT_WIDTH = 80;
 function segmentToPiece(segment, colorSystem) {
     if (segment.isControl)
@@ -86,16 +86,10 @@ export function segmentsToString(segments, colorSystem) {
             while (l < j && pieces[l].link === link)
                 l++;
             if (link) {
-                // [LAW:single-enforcer] Wire-byte trust boundary — sanitize the URL
-                // at the one place it becomes an OSC 8 sequence, regardless of which
-                // upstream API attached it to the Style. Defense-in-depth for the
-                // RichText data-model boundary in text.ts; also covers Style paths
-                // that don't go through RichText (Console.print({style: ...}), any
-                // direct `Segment.applyStyle(... new Style({ link })) ...`).
-                parts.push(`\x1b]8;;${stripOscTerminators(link)}\x1b\\`);
+                parts.push(osc8Open(link));
                 for (let m = k; m < l; m++)
                     parts.push(pieces[m].text);
-                parts.push("\x1b]8;;\x1b\\");
+                parts.push(OSC8_CLOSE);
             }
             else {
                 for (let m = k; m < l; m++)
@@ -141,4 +135,3 @@ export function renderToString(renderable, options) {
     };
     return segmentsToString(renderable.render(renderOptions), colorSystem);
 }
-//# sourceMappingURL=render.js.map

package/dist/core/segment.d.ts

@@ -140,4 +140,3 @@ export declare class Segment {
      */
     static splitAndCropLines(segments: Iterable<Segment>, width: number, pad?: boolean, includeNewLines?: boolean, style?: Style): Segment[][];
 }
-//# sourceMappingURL=segment.d.ts.map

package/dist/core/segment.js

@@ -431,4 +431,3 @@ function stylesEqual(a, b) {
         return false;
     return a.equals(b);
 }
-//# sourceMappingURL=segment.js.map

package/dist/core/spinnerData.d.ts

@@ -8,4 +8,3 @@ export interface SpinnerData {
 }
 export declare const SPINNERS: Record<string, SpinnerData>;
 export declare const DEFAULT_SPINNER = "dots";
-//# sourceMappingURL=spinnerData.d.ts.map

package/dist/core/spinnerData.js

@@ -113,4 +113,3 @@ export const SPINNERS = {
         ], interval: 80 },
 };
 export const DEFAULT_SPINNER = "dots";
-//# sourceMappingURL=spinnerData.js.map

package/dist/core/strip.d.ts

@@ -58,12 +58,29 @@ export declare class Strip<T extends StyledRenderable = StyledRenderable> implem
     constructor(items: readonly T[], joiner: Joiner<T>);
     render(options: RenderOptions): Iterable<Segment>;
 }
+/**
+ * The least ΔE_OK two neighbouring backgrounds must differ by for the powerline
+ * arrow between them to be seen. Below it the arrow is drawn in a colour the
+ * eye cannot tell from its own background, so the joiner draws the divider
+ * instead. Twice the ~.02 threshold of a visible difference, because a seam is
+ * one cell wide.
+ */
+export declare const SEAM_MIN_DELTA_E = 0.04;
 export interface PowerlineJoinerOptions {
-    /** Glyph used for every join (default: U+E0B0, the powerline right-arrow). */
-    glyph?: string;
+    /** Glyph used for every join. */
+    glyph: string;
+    /**
+     * Glyph drawn between neighbours whose backgrounds the eye cannot tell apart,
+     * in the left item's text colour — the arrow itself would vanish into the
+     * shared background.
+     */
+    divider: string;
 }
+/** The powerline pair: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow). */
+export declare const POWERLINE_JOINER_GLYPHS: Readonly<PowerlineJoinerOptions>;
 export declare class PowerlineJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
     private readonly _glyph;
+    private readonly _divider;
     constructor(options?: PowerlineJoinerOptions);
     join(left: T | null, right: T | null): Renderable;
 }
@@ -102,4 +119,3 @@ export declare class GradientJoiner<T extends StyledRenderable = StyledRenderabl
     constructor(options?: GradientJoinerOptions);
     join(left: T | null, right: T | null): Renderable;
 }
-//# sourceMappingURL=strip.d.ts.map

package/dist/core/strip.js

@@ -26,8 +26,9 @@
  * styling, so the cell type does too.
  */
 import { Segment } from "./segment.js";
-import { Style } from "./style.js";
+import { Style, SURFACE_BLACK } from "./style.js";
 import { ColorSpec, blendRgb } from "./color.js";
+import { Oklch } from "./oklch.js";
 // --- Strip ---
 export class Strip {
     items;
@@ -51,6 +52,18 @@ export class Strip {
             const next = i + 1 < items.length ? items[i + 1] : null;
             yield* this.joiner.join(item, next).render(options);
         }
+        // [LAW:one-source-of-truth] `Strip`'s sibling `FlexStrip` ends every line
+        // it emits, including the last, and the other block-level renderables
+        // (`Panel`/`Rule`/`Table` structurally, `RichText` via `end`) do too — so
+        // `Group` can emit children back to back with nothing in between
+        // (docs/group.md). A `Strip` that left its last line open broke only
+        // 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.)
+        yield Segment.line();
     }
 }
 // --- Helpers ---
@@ -88,10 +101,38 @@ function bgAsFg(edge) {
 function paintableBg(bg) {
     return bg !== undefined && !bg.isDefault ? bg : undefined;
 }
+// --- PowerlineJoiner ---
+/**
+ * The least ΔE_OK two neighbouring backgrounds must differ by for the powerline
+ * arrow between them to be seen. Below it the arrow is drawn in a colour the
+ * eye cannot tell from its own background, so the joiner draws the divider
+ * instead. Twice the ~.02 threshold of a visible difference, because a seam is
+ * one cell wide.
+ */
+export const SEAM_MIN_DELTA_E = 0.04;
+// Two backgrounds the eye cannot tell apart. What is measured is what is
+// drawn: each colour flattened onto the substrate Style.toSgrCodes flattens it
+// onto, so two alphas over one RGB are the two greys they render as. A palette
+// colour has no value here, so two of them are the same only when they are the
+// same palette slot — `type` + `number`, never the name, which spells one slot
+// many ways ("red", "color(1)").
+function indistinct(a, b) {
+    if (b === undefined)
+        return false;
+    const av = a.flattenAlpha(SURFACE_BLACK).value;
+    const bv = b.flattenAlpha(SURFACE_BLACK).value;
+    return av !== undefined && bv !== undefined
+        ? Oklch.fromRgba(av).deltaE(Oklch.fromRgba(bv)) < SEAM_MIN_DELTA_E
+        : a.type === b.type && a.number === b.number;
+}
+/** The powerline pair: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow). */
+export const POWERLINE_JOINER_GLYPHS = Object.freeze({ glyph: "\ue0b0", divider: "\ue0b1" });
 export class PowerlineJoiner {
     _glyph;
-    constructor(options) {
-        this._glyph = options?.glyph ?? "";
+    _divider;
+    constructor(options = POWERLINE_JOINER_GLYPHS) {
+        this._glyph = options.glyph;
+        this._divider = options.divider;
     }
     join(left, right) {
         // [LAW:dataflow-not-control-flow] One expression for all three positions
@@ -105,20 +146,27 @@ export class PowerlineJoiner {
         //     colourless arrow is not drawn.)
         //   • no right bg — the end cap — bleeds the left colour out over the
         //     terminal background (fg = left bg, no bg).
-        // Equal REAL bgs still emit: the glyph is drawn in its own background colour
-        // and is invisible, but the cell is present — a same-bg seam between two
-        // distinct items is a structural boundary, never suppressed. Background
-        // colour is paint, not structure; its ABSENCE (nothing to paint) is the only
-        // thing that elides the separator, and that is paint logic, not structure.
+        // Equal REAL bgs still emit: a same-bg seam between two distinct items is a
+        // structural boundary, never suppressed. The arrow would be drawn in its own
+        // background colour there and vanish, so the seam is the DIVIDER instead, in
+        // the left item's text colour — the vim-airline convention for neighbours
+        // that share a background. "Equal" is perceptual (SEAM_MIN_DELTA_E): an
+        // arrow a hair off its background is as invisible as one exactly on it.
+        // Background colour is paint, not structure; its ABSENCE (nothing to paint)
+        // is the only thing that elides the separator, and that is paint logic.
         // "Absent" = no bg OR the terminal default (transparent) — paintableBg folds
         // both to undefined so an explicit `… on default` cannot smuggle a separator.
         const glyph = this._glyph;
+        const divider = this._divider;
         return deferred(function* (options) {
-            const leftBg = paintableBg(left?.edgeStyle("right", options).bgcolor);
+            const leftEdge = left?.edgeStyle("right", options);
+            const leftBg = paintableBg(leftEdge?.bgcolor);
             if (leftBg === undefined)
                 return;
             const rightBg = paintableBg(right?.edgeStyle("left", options).bgcolor);
-            yield new Segment(glyph, new Style({ color: leftBg, bgcolor: rightBg }));
+            yield indistinct(leftBg, rightBg)
+                ? new Segment(divider, new Style({ color: leftEdge?.color, bgcolor: rightBg }))
+                : new Segment(glyph, new Style({ color: leftBg, bgcolor: rightBg }));
         });
     }
 }
@@ -206,4 +254,3 @@ export class GradientJoiner {
         });
     }
 }
-//# sourceMappingURL=strip.js.map

package/dist/core/style.d.ts

@@ -1,8 +1,8 @@
 /**
  * Immutable style descriptors — colors, text attributes, links, metadata.
  */
-import { ColorSpec, ColorDepth } from "./color.js";
-import type { TerminalTheme } from "./color.js";
+import { ColorRgba, ColorSpec, ColorDepth } from "./color.js";
+export declare const SURFACE_BLACK: ColorRgba;
 /**
  * Canonical text-attribute inventory. Single source of truth consumed by
  * `Style.parse` / `Style.toString` and the template bindings — adding an
@@ -38,7 +38,7 @@ export interface StyleOptions {
     meta?: Record<string, unknown>;
 }
 export declare class StyleSyntaxError extends Error {
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
 export declare class Style {
     readonly color: ColorSpec | undefined;
@@ -85,10 +85,6 @@ export declare class Style {
      * Render text with this style's ANSI escape codes.
      */
     render(text: string, colorSystem?: ColorDepth): string;
-    /**
-     * Returns a CSS style string for HTML rendering.
-     */
-    getHtmlStyle(theme?: TerminalTheme): string;
     /**
      * Serializes to a canonical string that round-trips through `Style.parse()`.
      */
@@ -141,4 +137,3 @@ export declare const DEFAULT_STYLES: Record<string, Style>;
  * a renderable sees outside a `Console`, as in `renderToString`.
  */
 export declare const DEFAULT_THEME: Theme;
-//# sourceMappingURL=style.d.ts.map