@promptctl/rich-js 0.27.0 → 0.29.0

package/dist/core/style.js

@@ -6,7 +6,7 @@ import { shiftAnchor } from "./anchor.js";
 import { Memo } from "./memo.js";
 import { pattern } from "./pattern.js";
 // [LAW:one-way-deps] `core/style` depends only on `core/color`. The substrate
-// a translucent colour is flattened over is `SURFACE_BLACK`, defined beside
+// a translucent color is flattened over is `SURFACE_BLACK`, defined beside
 // `compositeOver`.
 // --- Attribute definitions ---
 /**
@@ -21,11 +21,11 @@ export const ATTRIBUTE_NAMES = [
     "italic",
     "underline",
     "blink",
-    "blink2",
+    "rapidBlink",
     "reverse",
     "conceal",
     "strike",
-    "underline2",
+    "doubleUnderline",
     "frame",
     "encircle",
     "overline",
@@ -37,11 +37,11 @@ export const ATTRIBUTE_SGR = {
     italic: 3,
     underline: 4,
     blink: 5,
-    blink2: 6,
+    rapidBlink: 6,
     reverse: 7,
     conceal: 8,
     strike: 9,
-    underline2: 21,
+    doubleUnderline: 21,
     frame: 51,
     encircle: 52,
     overline: 53,
@@ -60,10 +60,14 @@ export const ATTRIBUTE_SHORT_ALIASES = {
     s: "strike",
     r: "reverse",
     o: "overline",
-    uu: "underline2",
+    uu: "doubleUnderline",
 };
 /** The hold of a cell that never changes: always was, and always will be. */
-const NEVER_CHANGES = { lastChange: Number.NEGATIVE_INFINITY, nextChange: Number.POSITIVE_INFINITY };
+export const NEVER_CHANGES = { validFrom: Number.NEGATIVE_INFINITY, validUntil: Number.POSITIVE_INFINITY };
+/** The moments both `a` and `b` hold through: the later `validFrom` and the sooner `validUntil`. */
+export function intersection(a, b) {
+    return { validFrom: Math.max(a.validFrom, b.validFrom), validUntil: Math.min(a.validUntil, b.validUntil) };
+}
 export class StyleSyntaxError extends Error {
     constructor(message, options) {
         super(message, options);
@@ -81,11 +85,11 @@ export class Style {
     italic;
     underline;
     blink;
-    blink2;
+    rapidBlink;
     reverse;
     conceal;
     strike;
-    underline2;
+    doubleUnderline;
     frame;
     encircle;
     overline;
@@ -97,32 +101,49 @@ export class Style {
      * unequal, because they came from different places.
      */
     anchor;
+    /**
+     * The drawing of a box these cells are the frame of (`Box.frame`), compared
+     * by identity. A frame is told by what drew it, never by its glyphs, as a
+     * strip's seam is (`JOIN`, `./strip.ts`): a box may draw its frame in blanks,
+     * and what it draws in ink an element's own content may draw too. It is a
+     * drawing and not a box, so two panels of one `ROUNDED` are two frames, and
+     * it is no `Anchor`: a frame's cells say whose they are and not where, since
+     * a table draws its top rule before it knows its height. It draws nothing.
+     */
+    boxFrame;
+    /**
+     * What drawing said of these cells' direction, compared by identity, as a
+     * link is a fact the encoder turns into bytes: `Segment` never holds a control
+     * the library wrote, so no cut of a row can unbalance one, and what survives a
+     * cut still names its stamp (`./seal.ts`). It draws nothing.
+     */
+    bidi;
     /**
      * The hold this style's cells are in, on the timeline of whoever drew the
-     * frame: since when what they show has been what it is (`lastChange`), and
-     * when it next changes (`nextChange`) — both `t` for a cell drawn by
+     * frame: since when what they show has been what it is (`validFrom`), and
+     * when it next changes (`validUntil`) — both `t` for a cell drawn by
      * something that moves every frame, and `-Infinity`/`Infinity` for one
      * that never changes. It draws nothing. Whatever draws for a handed time
      * stamps its cells with it (`placedRender`, `Effected`), the stamp rides up
      * through every container as the anchor does (`./anchor.ts`), and whoever
-     * holds the composed frame reads it off (`Segment.nextChange`, and
-     * `Segment.lastChange` for a host running its timeline backwards), so a
+     * holds the composed frame reads it off (`Segment.validUntil`, and
+     * `Segment.validFrom` for a host running its timeline backwards), so a
      * host knows when to draw again without asking each container. Two styles
      * laid together are in the intersection of their holds.
      */
-    hold;
+    validity;
     constructor(options = {}) {
-        const hold = options.hold ?? NEVER_CHANGES;
-        const { lastChange, nextChange } = hold;
+        const validity = options.validity ?? NEVER_CHANGES;
+        const { validFrom, validUntil } = validity;
         // [LAW:parse-dont-validate] A time or never, settled where the style is
         // made: NaN and the far infinity fail here, so no reader of a frame meets one.
-        if (!(nextChange > Number.NEGATIVE_INFINITY)) {
-            throw new RangeError(`Style nextChange must be a time in seconds or Infinity, got ${nextChange}`);
+        if (!(validUntil > Number.NEGATIVE_INFINITY)) {
+            throw new RangeError(`Style validUntil must be a time in seconds or Infinity, got ${validUntil}`);
         }
-        if (!(lastChange < Number.POSITIVE_INFINITY)) {
-            throw new RangeError(`Style lastChange must be a time in seconds or -Infinity, got ${lastChange}`);
+        if (!(validFrom < Number.POSITIVE_INFINITY)) {
+            throw new RangeError(`Style validFrom must be a time in seconds or -Infinity, got ${validFrom}`);
         }
-        this.hold = hold;
+        this.validity = validity;
         this.color = resolveColor(options.color);
         this.bgcolor = resolveBackground(options.bgcolor);
         this.bold = options.bold;
@@ -130,11 +151,11 @@ export class Style {
         this.italic = options.italic;
         this.underline = options.underline;
         this.blink = options.blink;
-        this.blink2 = options.blink2;
+        this.rapidBlink = options.rapidBlink;
         this.reverse = options.reverse;
         this.conceal = options.conceal;
         this.strike = options.strike;
-        this.underline2 = options.underline2;
+        this.doubleUnderline = options.doubleUnderline;
         this.frame = options.frame;
         this.encircle = options.encircle;
         this.overline = options.overline;
@@ -142,6 +163,8 @@ export class Style {
         this.link = options.link || undefined;
         this.meta = options.meta;
         this.anchor = options.anchor;
+        this.boxFrame = options.boxFrame;
+        this.bidi = options.bidi;
     }
     get isNull() {
         return (this.color === undefined &&
@@ -151,19 +174,21 @@ export class Style {
             this.italic === undefined &&
             this.underline === undefined &&
             this.blink === undefined &&
-            this.blink2 === undefined &&
+            this.rapidBlink === undefined &&
             this.reverse === undefined &&
             this.conceal === undefined &&
             this.strike === undefined &&
-            this.underline2 === undefined &&
+            this.doubleUnderline === undefined &&
             this.frame === undefined &&
             this.encircle === undefined &&
             this.overline === undefined &&
             this.link === undefined &&
             this.meta === undefined &&
             this.anchor === undefined &&
-            this.hold.nextChange === Number.POSITIVE_INFINITY &&
-            this.hold.lastChange === Number.NEGATIVE_INFINITY);
+            this.boxFrame === undefined &&
+            this.bidi === undefined &&
+            this.validity.validUntil === Number.POSITIVE_INFINITY &&
+            this.validity.validFrom === Number.NEGATIVE_INFINITY);
     }
     get transparentBackground() {
         return this.bgcolor === undefined || this.bgcolor.isDefault;
@@ -199,6 +224,14 @@ export class Style {
     withAnchor(anchor) {
         return this.with({ anchor });
     }
+    /** The same look, as the frame of the drawing `boxFrame` names, or of none. */
+    withBoxFrame(boxFrame) {
+        return this.with({ boxFrame });
+    }
+    /** The same look, its cells' direction as `bidi` says. */
+    withBidi(bidi) {
+        return this.with({ bidi });
+    }
     /** The style's text attributes, each as it sets it. */
     get attributes() {
         // [LAW:one-source-of-truth] Keyed by `ATTRIBUTE_NAMES`, whose every name is a key here: the cast is that list's own claim.
@@ -210,16 +243,16 @@ export class Style {
      */
     withAttributes(attributes) {
         // Only the attribute names are read: a wider object — a `Style`, say —
-        // satisfies the type and must not carry its colours or anchor in with it.
+        // satisfies the type and must not carry its colors or anchor in with it.
         return this.with(Object.fromEntries(ATTRIBUTE_NAMES.filter((name) => name in attributes).map((name) => [name, attributes[name]])));
     }
     /**
      * This style with its motion taken out, what reduced motion draws: `blink`
-     * and `blink2`, the motion a terminal makes on its own, unset, and every
+     * and `rapidBlink`, the motion a terminal makes on its own, unset, and every
      * other field as it was. A style that does not blink is its own.
      */
     reduced() {
-        return this.blink || this.blink2 ? this.withAttributes({ blink: undefined, blink2: undefined }) : this;
+        return this.blink || this.rapidBlink ? this.withAttributes({ blink: undefined, rapidBlink: undefined }) : this;
     }
     /**
      * This style on the cell `cells` to the right: its anchor shifted along its
@@ -244,11 +277,11 @@ export class Style {
             italic: other.italic ?? this.italic,
             underline: other.underline ?? this.underline,
             blink: other.blink ?? this.blink,
-            blink2: other.blink2 ?? this.blink2,
+            rapidBlink: other.rapidBlink ?? this.rapidBlink,
             reverse: other.reverse ?? this.reverse,
             conceal: other.conceal ?? this.conceal,
             strike: other.strike ?? this.strike,
-            underline2: other.underline2 ?? this.underline2,
+            doubleUnderline: other.doubleUnderline ?? this.doubleUnderline,
             frame: other.frame ?? this.frame,
             encircle: other.encircle ?? this.encircle,
             overline: other.overline ?? this.overline,
@@ -257,9 +290,10 @@ export class Style {
                 ? { ...this.meta, ...other.meta }
                 : other.meta ?? this.meta,
             anchor: other.anchor ?? this.anchor,
-            // Cells under both change when either does: the sooner, and have been
-            // what they are since the later — the intersection of the two holds.
-            hold: { lastChange: Math.max(this.hold.lastChange, other.hold.lastChange), nextChange: Math.min(this.hold.nextChange, other.hold.nextChange) },
+            boxFrame: other.boxFrame ?? this.boxFrame,
+            bidi: other.bidi ?? this.bidi,
+            // Cells under both change when either does.
+            validity: intersection(this.validity, other.validity),
         });
     }
     equals(other) {
@@ -272,21 +306,23 @@ export class Style {
             this.italic === other.italic &&
             this.underline === other.underline &&
             this.blink === other.blink &&
-            this.blink2 === other.blink2 &&
+            this.rapidBlink === other.rapidBlink &&
             this.reverse === other.reverse &&
             this.conceal === other.conceal &&
             this.strike === other.strike &&
-            this.underline2 === other.underline2 &&
+            this.doubleUnderline === other.doubleUnderline &&
             this.frame === other.frame &&
             this.encircle === other.encircle &&
             this.overline === other.overline &&
             this.link === other.link &&
             anchorsEqual(this.anchor, other.anchor) &&
-            this.hold.nextChange === other.hold.nextChange &&
-            this.hold.lastChange === other.hold.lastChange);
+            this.boxFrame === other.boxFrame &&
+            this.bidi === other.bidi &&
+            this.validity.validUntil === other.validity.validUntil &&
+            this.validity.validFrom === other.validity.validFrom);
     }
     /**
-     * The colours this style puts on screen at `colorSystem`: each flattened
+     * The colors this style puts on screen at `colorSystem`: each flattened
      * onto what lies beneath it — the background onto the terminal's black, the
      * foreground onto that background — then downgraded to the depth. The one
      * account of what a style draws: `toSgrCodes` encodes exactly these, and a
@@ -332,8 +368,8 @@ export class Style {
     }
     /**
      * The look as a canonical string that round-trips through `Style.parse()`:
-     * colours, attributes and the link, which is all a style string can spell.
-     * What a style carries beyond its look — `meta`, `anchor`, `hold` —
+     * colors, attributes and the link, which is all a style string can spell.
+     * What a style carries beyond its look — `meta`, `anchor`, `boxFrame`, `bidi`, `hold` —
      * has no spelling and is not here, so two styles that differ only there
      * read alike; `equals` tells them apart.
      */
@@ -480,7 +516,7 @@ export class Theme {
 // --- Parse helpers ---
 const ATTRIBUTE_SET = new Set(ATTRIBUTE_NAMES);
 // The words each position of a definition can hold: a bare token is a keyword,
-// an attribute or a colour name; `on` takes a colour name; `not` an attribute.
+// an attribute or a color name; `on` takes a color name; `not` an attribute.
 // The short aliases are left out, since `b` is no help to someone who typed
 // `bolt` and a one-letter name sits one edit from every other short word.
 // [LAW:one-source-of-truth] Derived from the lists the parser accepts from; the
@@ -512,8 +548,8 @@ function editDistance(a, b) {
  * Plausible means within one edit per three letters, at least one, which lets
  * `rd` reach `red` and keeps `hello` from reaching `yellow`. Every name tied
  * for nearest is offered: `gold` is one edit from `bold` and from three
- * `goldN` colours, and choosing among them would be a guess the reader cannot
- * tell from a finding. Case is not an edit, because the colour parser ignores
+ * `goldN` colors, and choosing among them would be a guess the reader cannot
+ * tell from a finding. Case is not an edit, because the color parser ignores
  * it: `Cyna` is as near `cyan` as `cyna` is.
  *
  * This runs on every render that meets the bad style, since only successful
@@ -535,12 +571,12 @@ function nearMiss(word, words) {
     return names.length === 0 ? "" : ` (did you mean ${names.join(" or ")}?)`;
 }
 /**
- * A style token read as a colour. The colour parser's own error is the reason
+ * A style token read as a color. The color parser's own error is the reason
  * the token failed, so it rides along twice: in the message, for a reader with
  * only the text, and as `cause`, for code that wants the original error.
  *
- * [LAW:single-enforcer] Both colour positions in a definition rewrap here, and
- * the near miss is named here rather than by the colour parser: only a
+ * [LAW:single-enforcer] Both color positions in a definition rewrap here, and
+ * the near miss is named here rather than by the color parser: only a
  * definition knows whether the token could also have been an attribute.
  */
 function parseStyleColor(token, failure, words) {
@@ -619,7 +655,7 @@ function resolveColor(c) {
 // so it is no background: a style added on top of another keeps that one's,
 // which is what Textual's `#00000000` means. A transparent foreground is not
 // the same, it draws its glyph in whatever lies beneath it — the background,
-// or `SURFACE_BLACK` when there is none — so it stays a colour.
+// or `SURFACE_BLACK` when there is none — so it stays a color.
 function resolveBackground(c) {
     const spec = resolveColor(c);
     return spec?.value?.alpha === 0 ? undefined : spec;
@@ -636,11 +672,11 @@ export const DEFAULT_STYLES = {
         italic: false,
         underline: false,
         blink: false,
-        blink2: false,
+        rapidBlink: false,
         reverse: false,
         conceal: false,
         strike: false,
-        underline2: false,
+        doubleUnderline: false,
         frame: false,
         encircle: false,
         overline: false,
@@ -650,11 +686,11 @@ export const DEFAULT_STYLES = {
     italic: new Style({ italic: true }),
     underline: new Style({ underline: true }),
     blink: new Style({ blink: true }),
-    blink2: new Style({ blink2: true }),
+    rapidBlink: new Style({ rapidBlink: true }),
     reverse: new Style({ reverse: true }),
     conceal: new Style({ conceal: true }),
     strike: new Style({ strike: true }),
-    underline2: new Style({ underline2: true }),
+    doubleUnderline: new Style({ doubleUnderline: true }),
     frame: new Style({ frame: true }),
     encircle: new Style({ encircle: true }),
     overline: new Style({ overline: true }),
@@ -719,9 +755,9 @@ export const DEFAULT_STYLES = {
     "syntax.number": Style.parse("cyan"),
     "syntax.comment": Style.parse("dim italic"),
     "syntax.line_number": Style.parse("dim"),
-    // Ink and ground both from the fixed 256-colour greys: the terminal theme's
+    // Ink and ground both from the fixed 256-color greys: the terminal theme's
     // own foreground is dark on a light theme and would vanish on grey27. At 16
-    // colours `Syntax` draws it without the pair (`groundedStyle`).
+    // colors `Syntax` draws it without the pair (`groundedStyle`).
     "syntax.line_number.highlight": Style.parse("bold grey93 on grey27"),
     // Markdown
     "markdown.h1": Style.parse("bold underline"),
@@ -731,7 +767,7 @@ export const DEFAULT_STYLES = {
     "markdown.h5": Style.parse("italic"),
     "markdown.h6": Style.parse("dim"),
     // A fixed cyan, not the theme's: `cyan` is dark enough on some themes to
-    // sink into grey11. Bold, as Rich's is: at 16 colours a renderable draws it
+    // sink into grey11. Bold, as Rich's is: at 16 colors a renderable draws it
     // without its pair (`groundedStyle`), and bold is what still marks code.
     "markdown.code": Style.parse("bold dark_turquoise on grey11"),
     "markdown.em": Style.parse("italic"),

package/dist/core/text-order.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What a destination does with text direction.
+ *
+ * Every order above `plain` is a claim about the terminal, and a wrong claim
+ * costs more than none. Visual order on a terminal that also reorders reverses
+ * the text twice, and no query answers for every such terminal. An isolate on a
+ * terminal whose width table predates it advances the cursor (xterm.js 6 does),
+ * which moves a table's border and the rows a painter goes back over. So what
+ * nothing is known about gets bare text, and `detectTextOrder` grants more only
+ * on evidence.
+ */
+import { type Env } from "./env.js";
+/**
+ * - `plain`: nothing is known of the destination, or it is not a display: a
+ *   pipe, a file, an unknown terminal. Characters only, in logical order, with
+ *   no explicit bidi control.
+ * - `logical`: a display known to reorder and to hold the controls at zero
+ *   width. Rows are sealed in isolates.
+ * - `visual`: a display known not to reorder. Rows are written reordered and
+ *   shaped, with no controls.
+ */
+export type TextOrder = "plain" | "logical" | "visual";
+/** A row's paragraph direction: 0 left to right, 1 right to left. */
+export type ParagraphLevel = 0 | 1;
+/** Cells written for a terminal that reorders them: their row's direction, and what is still open where they begin. */
+export interface LogicalStamp {
+    readonly order: "logical";
+    readonly level: ParagraphLevel;
+    readonly opens: string;
+}
+/** Cells already in visual order, for an export not to reverse again. */
+export interface VisualStamp {
+    readonly order: "visual";
+}
+export type BidiStamp = LogicalStamp | VisualStamp;
+/**
+ * The order `env` gives evidence for.
+ *
+ * An environment is inherited: `code .` from Windows Terminal carries
+ * `WT_SESSION` into VS Code's xterm.js terminal, and Alacritty clears nothing
+ * from GNOME Terminal. `TERM` is the one variable every terminal writes for its
+ * own child, so it is read first, and a variable a parent could have left counts
+ * only beside the `TERM` its own terminal sets. The rows are in the order that
+ * makes that true; a terminal naming itself off this list is `plain`.
+ *
+ * Not listed, each for a reason: xterm.js lays a row out through the browser and
+ * advances for an isolate, and VS Code is xterm.js. WezTerm's bidi is a setting
+ * the environment cannot show. iTerm2, Konsole, Terminal.app, mintty and mlterm
+ * are unmeasured. Any program may state its order.
+ */
+export declare function detectTextOrder(env: Env, isTTY: boolean): TextOrder;

package/dist/core/text-order.js

@@ -0,0 +1,50 @@
+/**
+ * What a destination does with text direction.
+ *
+ * Every order above `plain` is a claim about the terminal, and a wrong claim
+ * costs more than none. Visual order on a terminal that also reorders reverses
+ * the text twice, and no query answers for every such terminal. An isolate on a
+ * terminal whose width table predates it advances the cursor (xterm.js 6 does),
+ * which moves a table's border and the rows a painter goes back over. So what
+ * nothing is known about gets bare text, and `detectTextOrder` grants more only
+ * on evidence.
+ */
+import { isDumbTerminal } from "./env.js";
+import { pattern } from "./pattern.js";
+// Terminals that paint their own cells and do not reorder, by the `TERM` each
+// writes for its child. Ghostty forces the embedding level to 0
+// (font/shaper/coretext.zig); Alacritty (#663) and foot (#756) run no bidi.
+const VISUAL_TERM = pattern(/^(alacritty|foot|xterm-ghostty)/);
+/**
+ * The order `env` gives evidence for.
+ *
+ * An environment is inherited: `code .` from Windows Terminal carries
+ * `WT_SESSION` into VS Code's xterm.js terminal, and Alacritty clears nothing
+ * from GNOME Terminal. `TERM` is the one variable every terminal writes for its
+ * own child, so it is read first, and a variable a parent could have left counts
+ * only beside the `TERM` its own terminal sets. The rows are in the order that
+ * makes that true; a terminal naming itself off this list is `plain`.
+ *
+ * Not listed, each for a reason: xterm.js lays a row out through the browser and
+ * advances for an isolate, and VS Code is xterm.js. WezTerm's bidi is a setting
+ * the environment cannot show. iTerm2, Konsole, Terminal.app, mintty and mlterm
+ * are unmeasured. Any program may state its order.
+ */
+export function detectTextOrder(env, isTTY) {
+    if (!isTTY || isDumbTerminal(env))
+        return "plain";
+    if (env["TMUX"] || env["STY"] || env["ZELLIJ"] || env["INSIDE_EMACS"] || env["NVIM"] || env["VIM_TERMINAL"])
+        return "plain";
+    if ((env["TERM"] ?? "").match(VISUAL_TERM) !== null)
+        return "visual";
+    if (env["TERM_PROGRAM"] || env["TERMINAL_EMULATOR"] || env["KONSOLE_VERSION"])
+        return "plain";
+    // VTE reorders, and takes the controls at zero width past column 0
+    // (`src/unicode-width.hh`, `Terminal::insert_char`).
+    if (env["VTE_VERSION"] && env["TERM"] === "xterm-256color")
+        return "logical";
+    // Windows Terminal (microsoft/terminal#538): a console there has no `TERM`, WSL has this one.
+    if (env["WT_SESSION"] && (env["TERM"] === undefined || env["TERM"] === "xterm-256color"))
+        return "visual";
+    return "plain";
+}

package/dist/core/text.d.ts

@@ -5,6 +5,13 @@ import { Segment } from "./segment.js";
 import { Style, type TextStyle } from "./style.js";
 import type { Renderable, Measurable, OverflowMethod, RenderOptions } from "./protocol.js";
 export declare function stripControlChars(text: string): string;
+/**
+ * `text` as a Text's characters hold it: stripped, every line ending an LF, and
+ * every control its picture. One code unit for one, so an offset into stripped
+ * text holds, and every reader of a Text finds one line break without having to
+ * know the others.
+ */
+export declare function sanitized(text: string): string;
 /**
  * The style a stored `TextStyle` stands for in this render.
  *
@@ -35,9 +42,12 @@ export interface RichTextOptions {
 export declare class RichText implements Renderable, Measurable {
     private readonly _text;
     private readonly _spans;
+    private readonly _closure;
     private readonly _format;
     private readonly _tabSize;
     constructor(text?: string, options?: RichTextOptions);
+    /** The part of the text whose direction state nothing has closed. */
+    private _unclosed;
     private _reformat;
     get plain(): string;
     set plain(value: string);
@@ -75,8 +85,8 @@ export declare class RichText implements Renderable, Measurable {
      * any spans covering the leftmost (side="left") or rightmost (side="right")
      * character.
      *
-     * [LAW:locality-or-seam] Used by `Joiner`s to paint the transition between
-     * adjacent `Strip` items. Joiners only ever need the column adjacent to
+     * [LAW:locality-or-seam] Used by `Separator`s to paint the transition between
+     * adjacent `Strip` items. Separators only ever need the column adjacent to
      * them, so the cell type exposes that column rather than constraining its
      * interior to be uniform. For RichText with uniform styling, both edges
      * return the same style; for RichText with edge variation, each edge