@promptctl/rich-js 0.27.0 → 0.28.0

package/dist/core/seal.js

@@ -0,0 +1,75 @@
+/**
+ * `sealed` — the one total enforcer of what the wire holds.
+ *
+ * [LAW:single-enforcer] An explicit bidi control reaches the bytes only inside
+ * an isolate that accounts for it. The rule has no list of who wrote what: in a
+ * segment with no logical stamp every explicit control is deleted, in every
+ * order, so a raw `new Segment(text)` is contained and merely shows no effect.
+ * What the census withholds goes here too (`wireText`), a segment at a time, on
+ * text nothing cuts again, which is why a rule that reads neighbours can live here
+ * and not in the sanitizer. A span edge is therefore where that reading stops. A
+ * flag cut by one loses its tags and stays a flag; a selector after one is kept;
+ * a ZWJ before one is not taken with a deletion past it, so a join can form that
+ * `cellLen`, which reads the whole string, did not measure. Segments have always
+ * been measured apart and written together, so the same edge in the same text with
+ * nothing deleted draws the same row.
+ *
+ * This runs on the way out, below every cut, because a row is cut after it is
+ * drawn: `scroll` divides it, `mergeHorizontal` and a viewport crop it, an
+ * overlay splices into it. Controls written at drawing time would be cut with
+ * it. `Style.bidi` is a fact on the cells instead, so what survives still names
+ * its stamp, and the controls are written around the survivors.
+ */
+import { advance, closersOf, opened, withoutExplicit } from "./bidi.js";
+import { wireText } from "./cells.js";
+import { Segment } from "./segment.js";
+const LRI = "\u2066";
+const RLI = "\u2067";
+const PDI = "\u2069";
+/** `text` with closers that match nothing in `open` dropped, so content cannot end the isolate around it. */
+function balanced(text, open) {
+    return Array.from(text, (character) => (advance(open, character) ? character : "")).join("");
+}
+/**
+ * One row's run of one stamp in its isolate. The initiator is stated from the
+ * whole line's direction rather than FSI, so a wrapped row does not re-detect
+ * it. Embeddings close by PDF ahead of the PDI because VTE discards a zero-width
+ * character at column 0, initiator included, and a PDI matching nothing there
+ * closes nothing.
+ */
+function* isolated(run, { level, opens }) {
+    const open = opened(opens);
+    yield new Segment((level === 1 ? RLI : LRI) + opens);
+    for (const segment of run) {
+        const text = balanced(segment.text, open);
+        yield text === segment.text ? segment : new Segment(text, segment.style, segment.control);
+    }
+    yield new Segment(closersOf(open.stack.join("")) + PDI);
+}
+/** `segments` as the wire may hold them for `order`. */
+export function* sealed(segments, order) {
+    let run = [];
+    let stamp;
+    const flush = function* () {
+        if (stamp !== undefined)
+            yield* isolated(run, stamp);
+        run = [];
+        stamp = undefined;
+    };
+    for (const raw of segments) {
+        const drawn = wireText(raw.text);
+        const segment = drawn === raw.text ? raw : new Segment(drawn, raw.style, raw.control);
+        const own = order === "logical" && !segment.isControl ? segment.style?.bidi : undefined;
+        if (own?.order === "logical") {
+            if (own !== stamp)
+                yield* flush();
+            stamp = own;
+            run.push(segment);
+            continue;
+        }
+        yield* flush();
+        const text = withoutExplicit(segment.text);
+        yield text === segment.text ? segment : new Segment(text, segment.style, segment.control);
+    }
+    yield* flush();
+}

package/dist/core/segment.d.ts

@@ -130,6 +130,14 @@ export declare class Segment {
      * short rows padded with spaces, long ones cut.
      */
     static splitAndCropLines(segments: Iterable<Segment>, width: number): Segment[][];
+    /**
+     * The plain text of one line of segments, in the coordinate system
+     * `divideLine` and `Segment.divide` share: cell offsets into the styled line
+     * are cell offsets into this string. [LAW:one-source-of-truth] for that
+     * correspondence — the offsets are found in this text and applied to the
+     * segments it came from.
+     */
+    static plainOf(line: readonly Segment[]): string;
     /**
      * Returns total cell width of a line. Ignores control segments.
      */
@@ -177,7 +185,7 @@ export declare class Segment {
      * rest every time, so a long line wrapped into many rows took time quadratic
      * in its length.
      */
-    static divide(segments: Segment[], cuts: number[]): Segment[][];
+    static divide(segments: readonly Segment[], cuts: number[]): Segment[][];
     /**
      * Pads below to fill height.
      */

package/dist/core/segment.js

@@ -307,6 +307,16 @@ export class Segment {
     static splitAndCropLines(segments, width) {
         return Segment.splitLines(segments).map((line) => Segment.adjustLineLength(line, width));
     }
+    /**
+     * The plain text of one line of segments, in the coordinate system
+     * `divideLine` and `Segment.divide` share: cell offsets into the styled line
+     * are cell offsets into this string. [LAW:one-source-of-truth] for that
+     * correspondence — the offsets are found in this text and applied to the
+     * segments it came from.
+     */
+    static plainOf(line) {
+        return line.map((segment) => segment.text).join("");
+    }
     /**
      * Returns total cell width of a line. Ignores control segments.
      */
@@ -426,7 +436,7 @@ export class Segment {
      */
     static divide(segments, cuts) {
         if (cuts.length === 0)
-            return [segments];
+            return [[...segments]];
         const sections = [[]];
         let offset = 0;
         let next = 0;

package/dist/core/style.d.ts

@@ -3,6 +3,7 @@
  */
 import { ColorSpec, ColorDepth } from "./color.js";
 import { type Anchor } from "./anchor.js";
+import type { BidiStamp } from "./text-order.js";
 /**
  * Canonical text-attribute inventory. Single source of truth consumed by
  * `Style.parse` / `Style.toString` and the template bindings — adding an
@@ -45,6 +46,8 @@ export interface StyleOptions {
     link?: string;
     meta?: Record<string, unknown>;
     anchor?: Anchor;
+    boxFrame?: object;
+    bidi?: BidiStamp;
     /**
      * The hold the style's cells are in, both ends or neither: a cell saying
      * only when it next changes would claim, by default, that it always was,
@@ -58,6 +61,10 @@ export interface Hold {
     readonly lastChange: number;
     readonly nextChange: number;
 }
+/** The hold of a cell that never changes: always was, and always will be. */
+export declare const NEVER_CHANGES: Hold;
+/** The moments both `a` and `b` hold through: the later `lastChange` and the sooner `nextChange`. */
+export declare function intersection(a: Hold, b: Hold): Hold;
 export declare class StyleSyntaxError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }
@@ -85,6 +92,23 @@ export declare class Style {
      * unequal, because they came from different places.
      */
     readonly anchor: Anchor | undefined;
+    /**
+     * 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.
+     */
+    readonly boxFrame: object | undefined;
+    /**
+     * 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.
+     */
+    readonly bidi: BidiStamp | undefined;
     /**
      * 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
@@ -117,6 +141,10 @@ export declare class Style {
      * The same look, drawn from the place `anchor` names, or from nowhere.
      */
     withAnchor(anchor: Anchor | undefined): Style;
+    /** The same look, as the frame of the drawing `boxFrame` names, or of none. */
+    withBoxFrame(boxFrame: object | undefined): Style;
+    /** The same look, its cells' direction as `bidi` says. */
+    withBidi(bidi: BidiStamp | undefined): Style;
     /** The style's text attributes, each as it sets it. */
     get attributes(): Attributes;
     /**
@@ -163,7 +191,7 @@ export declare 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` —
+     * 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.
      */

package/dist/core/style.js

@@ -63,7 +63,11 @@ export const ATTRIBUTE_SHORT_ALIASES = {
     uu: "underline2",
 };
 /** 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 = { lastChange: Number.NEGATIVE_INFINITY, nextChange: Number.POSITIVE_INFINITY };
+/** The moments both `a` and `b` hold through: the later `lastChange` and the sooner `nextChange`. */
+export function intersection(a, b) {
+    return { lastChange: Math.max(a.lastChange, b.lastChange), nextChange: Math.min(a.nextChange, b.nextChange) };
+}
 export class StyleSyntaxError extends Error {
     constructor(message, options) {
         super(message, options);
@@ -97,6 +101,23 @@ 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
@@ -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 &&
@@ -162,6 +185,8 @@ export class Style {
             this.link === undefined &&
             this.meta === undefined &&
             this.anchor === undefined &&
+            this.boxFrame === undefined &&
+            this.bidi === undefined &&
             this.hold.nextChange === Number.POSITIVE_INFINITY &&
             this.hold.lastChange === Number.NEGATIVE_INFINITY);
     }
@@ -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.
@@ -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.
+            hold: intersection(this.hold, other.hold),
         });
     }
     equals(other) {
@@ -282,6 +316,8 @@ export class Style {
             this.overline === other.overline &&
             this.link === other.link &&
             anchorsEqual(this.anchor, other.anchor) &&
+            this.boxFrame === other.boxFrame &&
+            this.bidi === other.bidi &&
             this.hold.nextChange === other.hold.nextChange &&
             this.hold.lastChange === other.hold.lastChange);
     }
@@ -333,7 +369,7 @@ 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` —
+     * 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.
      */

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);