@promptctl/rich-js 0.26.0 → 0.28.0

package/dist/core/protocol.d.ts

@@ -4,7 +4,8 @@
  */
 import type { Segment } from "./segment.js";
 import { Style, type Hold, type StyleSyntaxError, type Theme } from "./style.js";
-import { ColorDepth } from "./color.js";
+import { ColorDepth, type TerminalColors } from "./color.js";
+import type { TextOrder } from "./text-order.js";
 import type { Highlighter } from "./highlighter.js";
 /**
  * What becomes of a line still wider than its width once wrapping is done.
@@ -18,13 +19,27 @@ import type { Highlighter } from "./highlighter.js";
  */
 export type OverflowMethod = "fold" | "crop" | "ellipsis" | "ignore";
 /**
- * What draws frames — a `Live`, an `App` — as what draws in them sees it:
- * the time a frame drawn now is drawn for, the host's clock read through its
- * timeline for a view on it (`frameTime`, `./view.ts`). Not a `Clock`: under
- * a paused timeline it holds, and under a reversed one it runs backwards.
+ * The frame being drawn, as a value: `time`, the moment it is drawn for, in
+ * seconds, on the clock its cells' `nextChange` stamps are read on, and
+ * `host`, the identity of what drew it — nothing to read, so what draws in
+ * the frame has one time, this one, and cannot ask the host for another.
+ * [LAW:types-are-the-program] A `Progress` keeps the identity to refuse a
+ * frame of a host other than the one its tasks are timed on.
+ */
+export interface HostFrame {
+    readonly time: number;
+    readonly host: object;
+}
+/**
+ * What draws frames — a `Live`, an `App` — as what runs between them sees
+ * it: the frame it would draw now, its time the host's clock read through
+ * its timeline (`frameNow`, `./view.ts`). Not a `Clock`: under a paused
+ * timeline it holds, and under a reversed one it runs backwards. Asked
+ * inside a render it throws (`RenderClockError`): a frame has the time it was
+ * drawn for, and a renderable reads that one.
  */
 export interface FrameHost {
-    readonly frameTime: number;
+    frameNow(): HostFrame;
 }
 export interface RenderOptions {
     /**
@@ -83,6 +98,17 @@ export interface RenderOptions {
      * handed. Absent means truecolor.
      */
     colorSystem?: ColorDepth | null;
+    /** What the output's destination does with direction. Absent is `"plain"`. */
+    textOrder?: TextOrder;
+    /**
+     * The terminal the output is drawn on: the colours a cell that sets none is
+     * drawn in, and the sixteen an ANSI colour names. The terminal's own palette
+     * is never queried, so the program says what it is, once, where the output
+     * is decided; a renderable reads it here (`Effected`, `ProgressBar`) and
+     * nothing hands it down to one. Absent is the terminal the depth assumes
+     * (`resolveTerminal`).
+     */
+    terminal?: TerminalColors;
     /**
      * The names a style string may use. A `Console` passes its own; absent, the
      * built-in defaults apply. Read it through `getStyle` rather than directly.
@@ -97,26 +123,22 @@ export interface RenderOptions {
     onStyleError?: StyleErrorHandler;
     /**
      * The reader asked for reduced motion — CSS's `prefers-reduced-motion`,
-     * which a terminal has no way to report, so a host is told. A renderable
-     * built for the time the host draws at draws every animation reduced, its
-     * motion taken out and its content kept on time (`shownAt`,
-     * `./view.ts`; `Animation.reduced`, `./animation.ts`). Absent,
-     * everything moves. Nothing here reads it from the environment.
+     * which a terminal has no way to report, so a host is told. Every placed
+     * animation is drawn reduced, its motion taken out and its content kept on
+     * time (`shownAt`, `Animation.reduced`, `./animation.ts`), and a `Destination`
+     * told the same writes no blink (`shownOn`, `./render.ts`). Absent, everything
+     * moves. Nothing here reads it from the environment.
      */
     reducedMotion?: boolean;
     /**
-     * The frame being drawn: `time`, the moment it is drawn for, in seconds, on
-     * the clock its cells' `nextChange` stamps are read on, and `host`, the
-     * host drawing it, whose `frameTime` that moment was. It is how a
-     * renderable that lives across frames — a widget, a `Progress` — draws for
-     * the time without being rebuilt each frame with one, and without reading
-     * a clock. Absent, the frame is drawn for no moment — a `print` — and
-     * nothing drawn from it moves.
+     * The frame being drawn (`HostFrame`): how a renderable that lives across
+     * frames — a widget, a `Progress` — draws for the time without being
+     * rebuilt each frame with one, and without reading a clock. A host writes
+     * it once a frame, and a print writes the one its caller named
+     * (`PrintOptions.frame`). Absent, the frame is drawn for no moment, 0
+     * (`frameTimeOf`, `./animation.ts`), and nothing drawn from it moves.
      */
-    frame?: {
-        readonly time: number;
-        readonly host: FrameHost;
-    };
+    frame?: HostFrame;
     /**
      * Told of every renderable `render` is asked for, as it is asked, so the
      * calls arrive in document order: a container before what it holds, what
@@ -138,6 +160,15 @@ export interface RenderOptions {
      * decides the frame's layout, so when it changes, the frame may.
      */
     onHold?: (hold: Hold) => void;
+    /**
+     * Told of the hold the element `key` names, drawn for a time on its own
+     * clock, is in: an effect's frame, which alone knows, since the answer
+     * depends on what it drew. `t` is that clock's, not the frame's, so this cannot be `onHold`:
+     * the animation placed around the value carries the answer back through the
+     * combinators that remapped the time (`Moves`, `./animation.ts`). It reaches
+     * whatever `frame` reaches.
+     */
+    onMoved?: (t: number, key: string, hold: Hold) => void;
 }
 /** The one field of the render options that says whether the reader wants motion. */
 export type Motion = Pick<RenderOptions, "reducedMotion">;

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, Style } from "./style.js";
+import { DEFAULT_THEME, NEVER_CHANGES, 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) {
@@ -262,7 +262,9 @@ export function render(renderable, options) {
  * enters and takes some. A motion held at no width therefore wakes its host
  * for frames that look the same: when it next takes room is not a moment its
  * hold can name, and an early answer costs a frame where a late one hides the
- * element. It commits nothing, as a measurement commits nothing —
+ * element. An effect is not such a motion: it cannot give itself room, so
+ * however it moves, a held one reports held for good, and whatever gives it
+ * room wakes the host. It commits nothing, as a measurement commits nothing —
  * its effects (`afterPass`) are learned at a width nobody sees, so a
  * `Viewport` it shows content through keeps the scroll the last frame shown
  * left it.
@@ -273,10 +275,15 @@ export function render(renderable, options) {
  * can repeat.
  */
 function holding(options) {
-    const { onPresent } = options;
+    const { onPresent, onMoved } = options;
     return {
         phase: { pass: phaseHere().pass, effects: [] },
-        drawing: { ...options, maxWidth: 0, onPresent: onPresent && ((content) => onPresent(content, "held")) },
+        drawing: {
+            ...options,
+            maxWidth: 0,
+            onPresent: onPresent && ((content) => onPresent(content, "held")),
+            onMoved: onMoved && ((t, key) => onMoved(t, key, NEVER_CHANGES)),
+        },
     };
 }
 /**
@@ -295,13 +302,14 @@ export function measure(measurable, options) {
  * `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. It still tells its
+ * measured it, and keep one the frame then cropped away — and nothing to
+ * `onMoved`, which speaks only for what the frame shows. It still tells its
  * hold (`onHold`): a layout decided by a measurement changes when it does.
  *
  * [LAW:single-enforcer] Every measurement starts here: `measure` asks with it.
  */
 function measuring(options) {
-    return { ...options, onPresent: undefined };
+    return { ...options, onPresent: undefined, onMoved: undefined };
 }
 /**
  * The options a renderable should *lay out against*: `withCellWidth`, with an

package/dist/core/render.d.ts

@@ -49,7 +49,7 @@ import type { ColorSystemName, Destination } from "./color.js";
 import type { Env } from "./env.js";
 import { Segment } from "./segment.js";
 import type { Renderable, RenderOptions } from "./protocol.js";
-export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" | "reducedMotion" | "theme" | "onStyleError" | "highlight" | "highlighter"> {
+export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" | "reducedMotion" | "textOrder" | "terminal" | "theme" | "onStyleError" | "highlight" | "highlighter" | "frame"> {
     /** Cell width to render into. Default 80. */
     width?: number;
     /**
@@ -92,9 +92,14 @@ export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" |
 export declare function shownOn(segment: Segment, destination: Destination): Segment;
 /**
  * Encodes one segment as ANSI bytes for `destination`: the reference's
- * `Style.render` for that segment, and nothing for a control segment.
+ * `Style.render` for that segment, and nothing for a control segment. It seals
+ * the segment alone, and a `logical` row's isolate spans its segments, so a row
+ * goes through `segmentsToString` whole.
  */
 export declare function segmentToString(segment: Segment, destination: Destination): string;
-/** Encodes a sequence of segments as ANSI bytes for `destination`, one segment at a time. */
+/**
+ * Encodes a sequence of segments as ANSI bytes for `destination`, one segment
+ * at a time, over what `sealed` lets reach the wire.
+ */
 export declare function segmentsToString(segments: Iterable<Segment>, destination: Destination): string;
 export declare function renderToString(renderable: Renderable, options?: RenderToStringOptions): string;

package/dist/core/render.js

@@ -48,6 +48,7 @@ import { ColorDepth, resolveDestination } from "./color.js";
 import { Segment } from "./segment.js";
 import { render } from "./protocol.js";
 import { OSC8_CLOSE, osc8Open } from "./osc8.js";
+import { sealed } from "./seal.js";
 const DEFAULT_WIDTH = 80;
 /**
  * `segment` as `destination` shows it: under reduced motion its style
@@ -64,9 +65,14 @@ export function shownOn(segment, destination) {
 }
 /**
  * Encodes one segment as ANSI bytes for `destination`: the reference's
- * `Style.render` for that segment, and nothing for a control segment.
+ * `Style.render` for that segment, and nothing for a control segment. It seals
+ * the segment alone, and a `logical` row's isolate spans its segments, so a row
+ * goes through `segmentsToString` whole.
  */
 export function segmentToString(segment, destination) {
+    return segmentsToString([segment], destination);
+}
+function encoded(segment, destination) {
     if (segment.isControl)
         return "";
     const { text, style } = shownOn(segment, destination);
@@ -80,11 +86,14 @@ export function segmentToString(segment, destination) {
     const link = destination.hyperlinks ? style.link : undefined;
     return link === undefined ? styled : `${osc8Open(link)}${styled}${OSC8_CLOSE}`;
 }
-/** Encodes a sequence of segments as ANSI bytes for `destination`, one segment at a time. */
+/**
+ * Encodes a sequence of segments as ANSI bytes for `destination`, one segment
+ * at a time, over what `sealed` lets reach the wire.
+ */
 export function segmentsToString(segments, destination) {
     const parts = [];
-    for (const segment of segments)
-        parts.push(segmentToString(segment, destination));
+    for (const segment of sealed(segments, destination.textOrder))
+        parts.push(encoded(segment, destination));
     return parts.join("");
 }
 export function renderToString(renderable, options) {
@@ -92,7 +101,9 @@ export function renderToString(renderable, options) {
     // [LAW:dataflow-not-control-flow] An absent spec is truecolor; an explicit
     // `null` stays null (`??` would collapse it).
     // [LAW:single-enforcer] Specs resolve through `resolveDestination`.
-    const destinationOptions = { reducedMotion: options?.reducedMotion };
+    // Stated, never detected: this call's bytes have no known destination, and
+    // its output is deterministic.
+    const destinationOptions = { reducedMotion: options?.reducedMotion, textOrder: options?.textOrder ?? "plain" };
     if (options?.env !== undefined)
         destinationOptions.env = options.env;
     if (options?.isTTY !== undefined)
@@ -114,13 +125,16 @@ export function renderToString(renderable, options) {
         asciiOnly: options?.asciiOnly ?? false,
         // [LAW:one-source-of-truth] What is drawn and how it is encoded take one preference.
         reducedMotion: destination.reducedMotion,
+        terminal: options?.terminal,
         theme: options?.theme,
         onStyleError: options?.onStyleError,
         highlight: options?.highlight,
         highlighter: options?.highlighter,
+        frame: options?.frame,
         // [LAW:one-source-of-truth] The depth the segments below are encoded at,
         // so a renderable measures what this very call will draw.
         colorSystem: destination.colorSystem,
+        textOrder: destination.textOrder,
     };
     return segmentsToString(render(renderable, renderOptions), destination);
 }

package/dist/core/seal.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `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 { Segment } from "./segment.js";
+import type { TextOrder } from "./text-order.js";
+/** `segments` as the wire may hold them for `order`. */
+export declare function sealed(segments: Iterable<Segment>, order: TextOrder): Iterable<Segment>;

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;