@promptctl/rich-js 0.26.0 → 0.28.0

package/dist/core/color.js

@@ -1,11 +1,10 @@
 /**
  * Terminal color representation, parsing, downgrading, and ANSI code generation.
  */
+import { isDumbTerminal } from "./env.js";
 import { Memo, WeakMemo } from "./memo.js";
 import { pattern } from "./pattern.js";
-// Runtime-importing `Palette` from `themes/palette.ts` is safe: that module
-// only `import type`s from `core/color.ts`, so there is no runtime cycle.
-import { Palette } from "../themes/palette.js";
+import { detectTextOrder } from "./text-order.js";
 // --- ColorRgba ---
 function hex2(byte) {
     return byte.toString(16).padStart(2, "0");
@@ -320,23 +319,15 @@ function forcedColorSystem(env) {
 function envOf(options) {
     return options.env ?? (typeof process !== "undefined" ? process.env : {});
 }
-/**
- * A terminal that says it cannot be drawn on: `TERM` is `dumb` or `unknown`,
- * as Emacs' shell mode sets it. It takes no colour and nothing that moves the
- * cursor.
- */
-export function isDumbTerminal(env) {
-    const term = env["TERM"];
-    return term === "dumb" || term === "unknown";
+function isTTYOf(options) {
+    return options.isTTY ?? (typeof process !== "undefined" ? (process.stdout?.isTTY ?? false) : false);
 }
 // What the destination can draw, preferences aside: TTY presence,
 // TERM=dumb/unknown, COLORTERM, known terminal names, TERM patterns. `null`
 // here means the destination takes no escapes at all.
 function terminalColorSystem(options) {
     const env = envOf(options);
-    const isTTY = options.isTTY ??
-        (typeof process !== "undefined" ? (process.stdout?.isTTY ?? false) : false);
-    if (!isTTY)
+    if (!isTTYOf(options))
         return null;
     if (isDumbTerminal(env))
         return null;
@@ -379,11 +370,14 @@ function terminalColorSystem(options) {
  */
 export function resolveDestination(spec, options = {}) {
     const reducedMotion = options.reducedMotion ?? false;
+    // Ahead of both arms: a colour spec says nothing about order.
+    const textOrder = options.textOrder ?? detectTextOrder(envOf(options), isTTYOf(options));
     if (spec !== "auto") {
         return {
             colorSystem: typeof spec === "string" ? resolveColorSystem(spec) : spec,
             hyperlinks: true,
             reducedMotion,
+            textOrder,
         };
     }
     return {
@@ -391,6 +385,7 @@ export function resolveDestination(spec, options = {}) {
         hyperlinks: (forcedColorSystem(envOf(options)) ?? null) !== null ||
             terminalColorSystem(options) !== null,
         reducedMotion,
+        textOrder,
     };
 }
 /**
@@ -844,24 +839,17 @@ export function blendRgb(color1, color2, crossFade = 0.5) {
 }
 // --- TerminalTheme ---
 /**
- * A terminal theme — surface/foreground baseline, the sixteen ANSI colours,
- * and a semantic palette.
- *
- * **`ansiColors` is the theme's own sixteen colours**, the shades a terminal
- * showing this theme draws `red`, `blue` and the rest in. `ColorSpec.parse("red")`
- * is ANSI colour 1 under every theme; which red that is, is the theme's to say,
- * as it is in Rich, where each `TerminalTheme` carries its own table.
+ * What a terminal draws with: the part of a `TerminalTheme` a colour resolves
+ * against.
  */
-export class TerminalTheme {
+export class TerminalColors {
     backgroundColor;
     foregroundColor;
     ansiColors;
-    palette;
-    constructor(backgroundColor, foregroundColor, ansiColors, palette) {
+    constructor(backgroundColor, foregroundColor, ansiColors) {
         this.backgroundColor = backgroundColor;
         this.foregroundColor = foregroundColor;
         this.ansiColors = ansiColors;
-        this.palette = palette;
         // [LAW:parse-dont-validate] Every reader indexes `ansiColors` 0–15 as the
         // terminal's sixteen, so a theme is the proof it holds exactly those.
         if (ansiColors.firstIndex !== 0 || ansiColors.size !== 16) {
@@ -869,6 +857,22 @@ export class TerminalTheme {
         }
     }
 }
+/**
+ * A terminal theme — surface/foreground baseline, the sixteen ANSI colours,
+ * and a semantic palette.
+ *
+ * **`ansiColors` is the theme's own sixteen colours**, the shades a terminal
+ * showing this theme draws `red`, `blue` and the rest in. `ColorSpec.parse("red")`
+ * is ANSI colour 1 under every theme; which red that is, is the theme's to say,
+ * as it is in Rich, where each `TerminalTheme` carries its own table.
+ */
+export class TerminalTheme extends TerminalColors {
+    palette;
+    constructor(backgroundColor, foregroundColor, ansiColors, palette) {
+        super(backgroundColor, foregroundColor, ansiColors);
+        this.palette = palette;
+    }
+}
 // --- ColorTable data ---
 function buildStandard16() {
     return [
@@ -943,20 +947,19 @@ export const EIGHT_BIT_TABLE = new ColorTable(build256Table());
  */
 export const EIGHT_BIT_DOWNGRADE_TABLE = new ColorTable(build256Table().slice(16), 16);
 export const WINDOWS_TABLE = new ColorTable(buildWindowsTable());
-// --- Internal fallback theme ---
+// --- Internal fallback terminals ---
 //
 // [LAW:one-way-deps] Preset themes (DEFAULT_TERMINAL_THEME, MONOKAI, NORD, ...)
-// live in `src/themes/terminalThemes.ts` because they need `buildPalette` from
-// `themes/`. Keeping them out of `core/color.ts` makes the dependency strictly
+// live in `src/themes/terminalThemes.ts` because they hold the registry's
+// palettes. Keeping them out of `core/color.ts` makes the dependency strictly
 // `themes/* -> core/color`, with no runtime back-edge.
 //
 // `getTruecolor()` retains a fallback for callers that omit `theme`: the
-// terminal a colour's depth assumes, built from that depth's own sixteen with
-// an empty Palette — sufficient for the lookups it serves, which never read
-// `palette`.
-const INTERNAL_DEFAULT_THEME = new TerminalTheme(new ColorRgba(0, 0, 0), new ColorRgba(255, 255, 255), STANDARD_TABLE, new Palette("default", true, new Map()));
+// terminal a colour's depth assumes, its own sixteen and no palette, which the
+// lookups it serves never read.
+const INTERNAL_DEFAULT_TERMINAL = new TerminalColors(new ColorRgba(0, 0, 0), new ColorRgba(255, 255, 255), STANDARD_TABLE);
 /** The Windows console in its default Campbell scheme: a WINDOWS colour's terminal. */
-const WINDOWS_CONSOLE_THEME = new TerminalTheme(WINDOWS_TABLE.get(0), WINDOWS_TABLE.get(7), WINDOWS_TABLE, new Palette("windows", true, new Map()));
+const WINDOWS_CONSOLE_TERMINAL = new TerminalColors(WINDOWS_TABLE.get(0), WINDOWS_TABLE.get(7), WINDOWS_TABLE);
 /**
  * The terminal a colour at `depth` is drawn by: `theme`, or when a caller names
  * none, the one the depth assumes — the Windows console at WINDOWS, the VGA
@@ -965,7 +968,7 @@ const WINDOWS_CONSOLE_THEME = new TerminalTheme(WINDOWS_TABLE.get(0), WINDOWS_TA
  * palette this does not.)
  */
 export function resolveTerminal(theme, depth) {
-    return theme ?? (depth === ColorDepth.WINDOWS ? WINDOWS_CONSOLE_THEME : INTERNAL_DEFAULT_THEME);
+    return theme ?? (depth === ColorDepth.WINDOWS ? WINDOWS_CONSOLE_TERMINAL : INTERNAL_DEFAULT_TERMINAL);
 }
 /**
  * The table a downgrade to `depth` rounds a fixed colour against.

package/dist/core/console.d.ts

@@ -3,13 +3,15 @@
  */
 import { Style, Theme } from "./style.js";
 import { ColorDepth } from "./color.js";
+import type { TextOrder } from "./text-order.js";
 import type { ColorSystemName, Destination } from "./color.js";
 import type { Env } from "./env.js";
-import type { TerminalTheme } from "./color.js";
+import type { TerminalColors, TerminalTheme } from "./color.js";
 import { type JSONOptions } from "./json.js";
 import type { Highlighter } from "./highlighter.js";
 import { type RuleOptions } from "../renderables/rule.js";
 import type { Height, OverflowMethod, RenderOptions, StyleErrorHandler } from "./protocol.js";
+import { type HostFrame } from "./protocol.js";
 import type { Unsubscribe } from "./subscription.js";
 export interface ConsoleSink {
     write(chunk: string | Uint8Array): unknown;
@@ -52,6 +54,8 @@ export interface ConsoleOptions {
      * TERM=dumb: false). `false` with `colorSystem: null` writes plain text.
      */
     hyperlinks?: boolean;
+    /** What the output's destination does with direction. Default: what `detectTextOrder` finds. */
+    textOrder?: TextOrder;
     /**
      * The terminal can draw only ASCII: boxes, rules, tree guides and widget
      * marks draw with ASCII characters instead of line-drawing glyphs. A
@@ -68,6 +72,12 @@ export interface ConsoleOptions {
      * it in; nothing here reads the environment for it. Default false.
      */
     reducedMotion?: boolean;
+    /**
+     * The terminal this console draws on (`RenderOptions.terminal`), which
+     * every effect it draws resolves its colours on. Default: the one the
+     * colour depth assumes.
+     */
+    terminal?: TerminalColors;
     /**
      * Static width (cells). Ignored when `getSize` is provided. Falls back to
      * the `COLUMNS` env var / the bound stream's `columns` / 80.
@@ -125,6 +135,13 @@ export interface ConsoleOptions {
 }
 export interface PrintOptions {
     style?: string | Style;
+    /**
+     * The frame this print is drawn in (`RenderOptions.frame`): the moment
+     * everything in it that moves is drawn for, named by the caller — a host's
+     * `frameNow()`. [LAW:single-enforcer] The one place a print's time is
+     * decided; absent, the print is drawn for no moment, 0 (`frameTimeOf`).
+     */
+    frame?: HostFrame;
     justify?: "default" | "left" | "center" | "right" | "full";
     overflow?: OverflowMethod;
     highlight?: boolean;
@@ -141,6 +158,7 @@ export declare class Console {
     private readonly _lastLogTime;
     private readonly _style;
     private readonly _isTerminal;
+    private readonly _attended;
     private readonly _interactive;
     private readonly _file;
     private readonly _stream;
@@ -148,6 +166,7 @@ export declare class Console {
     private readonly _markup;
     private readonly _highlight;
     private readonly _theme;
+    private readonly _terminal;
     private readonly _onStyleError;
     private readonly _asciiOnly;
     private readonly _highlighter;
@@ -180,6 +199,12 @@ export declare class Console {
     print(...args: unknown[]): void;
     private _draw;
     log(...args: unknown[]): void;
+    /**
+     * Sounds the terminal's bell, Rich's `Console.bell`, for whoever is at it: a
+     * pipe, a dumb terminal and a capture get nothing. It goes straight to the sink
+     * because a bell moves no cursor, and a live region would repaint its frame.
+     */
+    bell(): void;
     rule(title?: string, options?: RuleOptions): void;
     printJson(json: string | object, options?: JSONOptions): void;
     /**

package/dist/core/console.js

@@ -3,7 +3,8 @@
  */
 import { Segment } from "./segment.js";
 import { NULL_STYLE, DEFAULT_THEME } from "./style.js";
-import { isDumbTerminal, resolveDestination } from "./color.js";
+import { resolveDestination } from "./color.js";
+import { isDumbTerminal } from "./env.js";
 import { encodeHtml } from "./export-html.js";
 import { encodeSvg } from "./export-svg.js";
 import { RichText } from "./text.js";
@@ -17,6 +18,7 @@ import { ReprHighlighter, NullHighlighter } from "./highlighter.js";
 // rather than being restated here; see `rule()`.
 import { Rule } from "../renderables/rule.js";
 import { segmentsToString, shownOn } from "./render.js";
+import { sealed } from "./seal.js";
 import { placeBlock } from "./place.js";
 import { activePass, isRenderable, measure, render } from "./protocol.js";
 import { ListState, State, refuseRenderWrite } from "./state.js";
@@ -181,6 +183,7 @@ export class Console {
     _lastLogTime = new State(null);
     _style;
     _isTerminal;
+    _attended;
     _interactive;
     _file;
     // [LAW:one-source-of-truth] The resolved output stream, not the `stderr`
@@ -191,6 +194,7 @@ export class Console {
     _markup;
     _highlight;
     _theme;
+    _terminal;
     _onStyleError;
     _asciiOnly;
     _highlighter;
@@ -211,7 +215,7 @@ export class Console {
         // [LAW:dataflow-not-control-flow] `isTTY` and `env` are forwarded
         // unconditionally, so detection stays inside the console's injected
         // environment rather than the ambient process's.
-        const resolved = resolveDestination(options?.colorSystem === undefined ? "auto" : options.colorSystem, { isTTY: this._isTerminal, env: environment.env, reducedMotion: options?.reducedMotion });
+        const resolved = resolveDestination(options?.colorSystem === undefined ? "auto" : options.colorSystem, { isTTY: this._isTerminal, env: environment.env, reducedMotion: options?.reducedMotion, ...(options?.textOrder === undefined ? {} : { textOrder: options.textOrder }) });
         // [LAW:single-enforcer] The console's one override, an explicit
         // `hyperlinks`, is applied here and nowhere else; every write encodes for
         // this value whole. [LAW:one-source-of-truth] The reader's motion
@@ -223,9 +227,12 @@ export class Console {
         // [LAW:no-ambient-temporal-coupling] The theme is assigned before the
         // style, because the console's own style may be one of the theme's names.
         this._theme = options?.theme ?? DEFAULT_THEME;
+        this._terminal = options?.terminal;
         this._style = this._theme.resolve(options?.style ?? NULL_STYLE);
-        // Rich's rule: a terminal is interactive unless it is a dumb one.
-        this._interactive = options?.forceInteractive ?? (this._isTerminal && !isDumbTerminal(environment.env));
+        // Rich's rule: a terminal is interactive unless it is a dumb one. Forcing that
+        // is animation policy, and says nothing of who is at the terminal.
+        this._attended = this._isTerminal && !isDumbTerminal(environment.env);
+        this._interactive = options?.forceInteractive ?? this._attended;
         this._file = options?.file;
         this._record = options?.record ?? false;
         this._markup = options?.markup !== false;
@@ -290,6 +297,8 @@ export class Console {
             theme: this._theme,
             onStyleError: this._onStyleError,
             colorSystem: this._destination.colorSystem,
+            textOrder: this._destination.textOrder,
+            terminal: this._terminal,
             markup: this._markup,
             highlight: this._highlight,
             highlighter: this._highlighter,
@@ -317,7 +326,7 @@ export class Console {
             !isRenderable(lastArg) &&
             ("style" in lastArg || "justify" in lastArg || "markup" in lastArg ||
                 "highlight" in lastArg || "overflow" in lastArg || "end" in lastArg ||
-                "softWrap" in lastArg || "crop" in lastArg || "sep" in lastArg)) {
+                "softWrap" in lastArg || "crop" in lastArg || "sep" in lastArg || "frame" in lastArg)) {
             opts = lastArg;
             items = args.slice(0, -1);
         }
@@ -407,6 +416,7 @@ export class Console {
         const renderOpts = {
             ...options,
             ...strings,
+            frame: opts.frame,
             justify: opts.justify === "default" ? undefined : opts.justify,
             overflow: opts.overflow ?? (softWrap ? "ignore" : undefined),
             noWrap: softWrap,
@@ -494,6 +504,16 @@ export class Console {
         // stamp, so the next row's must show.
         this._lastLogTime.set(stamped);
     }
+    /**
+     * Sounds the terminal's bell, Rich's `Console.bell`, for whoever is at it: a
+     * pipe, a dumb terminal and a capture get nothing. It goes straight to the sink
+     * because a bell moves no cursor, and a live region would repaint its frame.
+     */
+    bell() {
+        refuseRenderWrite(this._madeIn);
+        if (this._attended && this._capture.get() === null)
+            this.file.write("\x07");
+    }
     // [LAW:one-source-of-truth] `RuleOptions` is `Rule`'s, not a restatement of
     // it. `console.ts` used to declare its own copy and field-by-field forward
     // into this constructor, which made a second map of one shape — identical
@@ -546,7 +566,7 @@ export class Console {
     }
     // --- Export (when record:true) ---
     exportText({ clear = true } = {}) {
-        const text = this._recorded.get().map((s) => s.text).join("");
+        const text = [...sealed(this._recorded.get(), "plain")].map((s) => s.text).join("");
         if (clear)
             this._recorded.set([]);
         return text;

package/dist/core/control-codes.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The census of code points that do not print: every one in Unicode's general
+ * categories Cc, Cf, Zl and Zp, and the variation selectors, with what `RichText`
+ * does when content carries it. [LAW:one-source-of-truth] The sanitizer
+ * (`sanitized`), the wire (`wireText`) and the cell-width measure
+ * (`cellLen`) all read this table, so whether content keeps a code point has one
+ * statement. `docs/control-codes.md` is each family's use and harm, and what real
+ * terminals were measured doing with it.
+ *
+ * A row does not carry a width. A kept code point takes the cells Rich's table
+ * gives it (`cell-widths.ts`), and a second statement of them here would be one
+ * that could drift.
+ */
+/**
+ * What `RichText` does with a code point. `strip` deletes it from content. `keep`
+ * holds it as a character. `line-break` is a line ending, so content holds an LF
+ * in its place. `pictured` means nothing inside a span, so content holds the
+ * stand-in `pictureOf` gives in its place and the reader sees something was there.
+ * `withheld` is held in content and measured as nothing, and `wireText` decides
+ * from its neighbours whether it is written.
+ *
+ * Only `keep`, and a `withheld` code point `wireText` lets by, reaches the wire. A
+ * raw `Segment` is not content, so what it holds of the others is deleted there.
+ */
+export type Disposition = "strip" | "keep" | "line-break" | "pictured" | "withheld";
+/**
+ * The code points `first` to `last`, inclusive, and what is done with each. A
+ * `pictured` row carries what content shows in place of each of its code points.
+ */
+export type ControlCodeRow = {
+    readonly first: number;
+    readonly last: number;
+    readonly disposition: Exclude<Disposition, "pictured">;
+} | {
+    readonly first: number;
+    readonly last: number;
+    readonly disposition: "pictured";
+    readonly picture: (codePoint: number) => string;
+};
+/**
+ * Ascending and disjoint, every Cc, Cf, Zl, Zp and Variation_Selector code point
+ * in exactly one row (`test/core/control-codes.test.ts`).
+ *
+ * Rich's `Text` strips only `STRIP_CONTROL_CODES` (BEL, BS, VT, FF, CR) and writes
+ * every other code point to the wire. Here a directive reaches the wire only
+ * through the library's own constructs: `Style`, a link, `Console.bell`, the paint
+ * layer.
+ */
+export declare const CONTROL_CODES: readonly ControlCodeRow[];
+/** What content shows in place of `codePoint`, whose disposition is `pictured`. */
+export declare function pictureOf(codePoint: number): string;
+/** A regular expression class of the code points in rows `chosen` picks, for `u`. */
+export declare function controlClass(chosen: (disposition: Disposition) => boolean): string;
+/**
+ * UTS #51's subdivision flag, as a `u` source: the black flag, a CLDR subdivision
+ * spelled in tag letters and digits, and CANCEL TAG. The one sequence tag
+ * characters have a reader for.
+ */
+export declare const SUBDIVISION_FLAG = "\uD83C\uDFF4[\uDB40\uDC30-\uDB40\uDC39\uDB40\uDC61-\uDB40\uDC7A]{3,6}\uDB40\uDC7F";
+/** What happens to `codePoint`. One in no row is kept. */
+export declare function dispositionOf(codePoint: number): Disposition;

package/dist/core/control-codes.js

@@ -0,0 +1,157 @@
+/**
+ * The census of code points that do not print: every one in Unicode's general
+ * categories Cc, Cf, Zl and Zp, and the variation selectors, with what `RichText`
+ * does when content carries it. [LAW:one-source-of-truth] The sanitizer
+ * (`sanitized`), the wire (`wireText`) and the cell-width measure
+ * (`cellLen`) all read this table, so whether content keeps a code point has one
+ * statement. `docs/control-codes.md` is each family's use and harm, and what real
+ * terminals were measured doing with it.
+ *
+ * A row does not carry a width. A kept code point takes the cells Rich's table
+ * gives it (`cell-widths.ts`), and a second statement of them here would be one
+ * that could drift.
+ */
+const strip = (first, last) => ({ first, last, disposition: "strip" });
+const keep = (first, last) => ({ first, last, disposition: "keep" });
+const lineBreak = (first, last) => ({ first, last, disposition: "line-break" });
+const pictured = (first, last, picture) => ({ first, last, disposition: "pictured", picture });
+/**
+ * The stand-ins. A C0 control's Control Pictures symbol is U+2400 up, DEL's is
+ * U+2421. Unicode gives C1 no pictures, so each shows U+2426 SYMBOL FOR SUBSTITUTE:
+ * one cell under every East Asian width setting, which U+FFFD is not, and apart
+ * from a real decoding error. Each is one code unit, so offsets hold.
+ */
+const controlPicture = (codePoint) => String.fromCharCode(0x2400 + codePoint);
+const deletePicture = () => "\u2421";
+const substitute = () => "\u2426";
+const withheld = (first, last) => ({ first, last, disposition: "withheld" });
+/**
+ * Ascending and disjoint, every Cc, Cf, Zl, Zp and Variation_Selector code point
+ * in exactly one row (`test/core/control-codes.test.ts`).
+ *
+ * Rich's `Text` strips only `STRIP_CONTROL_CODES` (BEL, BS, VT, FF, CR) and writes
+ * every other code point to the wire. Here a directive reaches the wire only
+ * through the library's own constructs: `Style`, a link, `Console.bell`, the paint
+ * layer.
+ */
+export const CONTROL_CODES = [
+    // NUL to BS. BEL's alert is `Console.bell`, and BS's overstrike, bold and
+    // underline in nroff output, is `decodeAnsi`: taken a code point at a time, text
+    // can turn neither into what it means.
+    pictured(0x00, 0x08, controlPicture),
+    keep(0x09, 0x0a),
+    // VT and FF, mandatory breaks in UAX #14 as LS and PS are.
+    lineBreak(0x0b, 0x0c),
+    // CR. A CRLF's LF ends its line however the two were chunked, and a CR's
+    // overwrite is `decodeAnsi`'s. What is given up is a classic Mac file's lines.
+    strip(0x0d, 0x0d),
+    // SO and SI switch the terminal's character set; DLE to SUB are transmission
+    // controls, and CAN and SUB abort a sequence; ESC begins one, and content that
+    // means styling says so with `decodeAnsi`; FS to US are data separators.
+    pictured(0x0e, 0x1f, controlPicture),
+    // DEL.
+    pictured(0x7f, 0x7f, deletePicture),
+    // The C1 controls. VTE, WezTerm and xterm.js read U+009B as CSI and U+009D as
+    // OSC; xterm, kitty and others ignore them. None has a meaning in text but NEL,
+    // which Unicode treats as CR, LF and CRLF are treated (§5.8). A stray one is
+    // often windows-1252 decoded as Latin-1, but which, a code point alone cannot
+    // say, so mojibake is the caller's to repair. `TextInput` refuses them as keys.
+    pictured(0x80, 0x84, substitute),
+    lineBreak(0x85, 0x85),
+    pictured(0x86, 0x9f, substitute),
+    // SOFT HYPHEN: a place a word may break, drawn as a hyphen only where one does.
+    // Terminals disagree on its cell, so it never reaches them.
+    withheld(0xad, 0xad),
+    // The Arabic and Syriac number signs and other prepended concatenation marks,
+    // which draw a glyph.
+    keep(0x600, 0x605),
+    // ARABIC LETTER MARK, a bidi mark like LRM and RLM below: it holds no state,
+    // so right-to-left text can use it.
+    keep(0x61c, 0x61c),
+    // More prepended concatenation marks.
+    keep(0x6dd, 0x6dd),
+    keep(0x70f, 0x70f),
+    keep(0x890, 0x891),
+    keep(0x8e2, 0x8e2),
+    // The Mongolian free variation selectors.
+    withheld(0x180b, 0x180d),
+    // MONGOLIAN VOWEL SEPARATOR, which shapes the vowel after it.
+    keep(0x180e, 0x180e),
+    withheld(0x180f, 0x180f),
+    // ZWSP, a place a line may break (`wrap.ts`); ZWNJ, which Persian and Urdu spell
+    // with; ZWJ, for emoji and conjuncts; and the bidi marks LRM and RLM, which hold
+    // no state, so right-to-left text can use them. ZWJ's joining is Rich's width
+    // rule, which `cells.ts` holds apart from this row.
+    keep(0x200b, 0x200f),
+    // LINE SEPARATOR and PARAGRAPH SEPARATOR.
+    lineBreak(0x2028, 0x2029),
+    // The bidi embeddings and overrides with their closer PDF, and the isolates
+    // below. Content holds them; what reaches the wire is `sealed`'s to decide.
+    keep(0x202a, 0x202e),
+    // WORD JOINER, which only asks that nothing break here, and the invisible
+    // mathematical operators.
+    keep(0x2060, 0x2064),
+    // The bidi isolates with their closer PDI.
+    keep(0x2066, 0x2069),
+    // The deprecated shaping and swapping switches. Each holds state to the end of
+    // the text, Unicode deprecates them, and no terminal was found honouring one.
+    strip(0x206a, 0x206f),
+    // VARIATION SELECTOR-1 to 16: glyph variants, and text or emoji presentation.
+    withheld(0xfe00, 0xfe0f),
+    // ZERO WIDTH NO-BREAK SPACE, the byte order mark, as a word joiner.
+    keep(0xfeff, 0xfeff),
+    // Interlinear annotation. No terminal draws ruby, the annotating text stays
+    // visible, and the anchors hold no state, so there is nothing to contain.
+    keep(0xfff9, 0xfffb),
+    // The Kaithi number signs, which draw a glyph.
+    keep(0x110bd, 0x110bd),
+    keep(0x110cd, 0x110cd),
+    // Egyptian hieroglyph, shorthand and musical format controls.
+    keep(0x13430, 0x1343f),
+    keep(0x1bca0, 0x1bca3),
+    keep(0x1d173, 0x1d17a),
+    // LANGUAGE TAG, deprecated.
+    strip(0xe0001, 0xe0001),
+    // The tag characters: an emoji subdivision flag, or text no reader can see.
+    withheld(0xe0020, 0xe007f),
+    // The ideographic variation selectors: Japanese and Chinese glyph variants.
+    withheld(0xe0100, 0xe01ef),
+];
+/** What content shows in place of `codePoint`, whose disposition is `pictured`. */
+export function pictureOf(codePoint) {
+    const row = rowOf(codePoint);
+    if (row?.disposition !== "pictured")
+        throw new RangeError(`U+${codePoint.toString(16).padStart(4, "0")} is not pictured`);
+    return row.picture(codePoint);
+}
+/** A regular expression class of the code points in rows `chosen` picks, for `u`. */
+export function controlClass(chosen) {
+    const hex = (codePoint) => `\\u{${codePoint.toString(16)}}`;
+    return `[${CONTROL_CODES.filter((row) => chosen(row.disposition)).map((row) => `${hex(row.first)}-${hex(row.last)}`).join("")}]`;
+}
+/**
+ * UTS #51's subdivision flag, as a `u` source: the black flag, a CLDR subdivision
+ * spelled in tag letters and digits, and CANCEL TAG. The one sequence tag
+ * characters have a reader for.
+ */
+export const SUBDIVISION_FLAG = "\u{1f3f4}[\u{e0030}-\u{e0039}\u{e0061}-\u{e007a}]{3,6}\u{e007f}";
+/** What happens to `codePoint`. One in no row is kept. */
+export function dispositionOf(codePoint) {
+    return rowOf(codePoint)?.disposition ?? "keep";
+}
+/** The row holding `codePoint`, if any. */
+function rowOf(codePoint) {
+    let low = 0;
+    let high = CONTROL_CODES.length - 1;
+    while (low <= high) {
+        const mid = (low + high) >> 1;
+        const row = CONTROL_CODES[mid];
+        if (codePoint < row.first)
+            high = mid - 1;
+        else if (codePoint > row.last)
+            low = mid + 1;
+        else
+            return row;
+    }
+    return undefined;
+}

package/dist/core/easing.js

@@ -379,7 +379,12 @@ export function passAt(what, t, period) {
     // takes off; carrying a pass's start out of `t` itself would leave each
     // sample its own rounding. `+ 0` turns the `-0` a small negative `t` rounds
     // to into pass 0, so the pass is a plain integer whoever reads it.
-    return { pass: Math.round((t - into) / period) + 0, into };
+    const pass = Math.round((t - into) / period) + 0;
+    // [LAW:no-silent-failure] Past where a pass is a float, `period` is finer than time resolves: the refusal a
+    // boundary walked there gives, said of `t` and not of the infinite sum a pass that overflowed would build.
+    if (!Number.isFinite(pass))
+        throw new RangeError(`${what}: a period of ${period} s is finer than time resolves near t = ${t}`);
+    return { pass, into };
 }
 /** The least normal double, 2^-1022: below it every double is a multiple of `Number.MIN_VALUE`. */
 const MIN_NORMAL = 2 ** -1022;

package/dist/core/env.d.ts

@@ -14,3 +14,9 @@
  * `NodeJS` namespace. `test/seam/browser-types.test.ts` holds that line.
  */
 export type Env = Readonly<Record<string, string | undefined>>;
+/**
+ * A terminal that says it cannot be drawn on: `TERM` is `dumb` or `unknown`,
+ * as Emacs' shell mode sets it. It takes no colour and nothing that moves the
+ * cursor.
+ */
+export declare function isDumbTerminal(env: Env): boolean;

package/dist/core/env.js

@@ -13,4 +13,12 @@
  * without `@types/node` — the ordinary browser project — cannot resolve the
  * `NodeJS` namespace. `test/seam/browser-types.test.ts` holds that line.
  */
-export {};
+/**
+ * A terminal that says it cannot be drawn on: `TERM` is `dumb` or `unknown`,
+ * as Emacs' shell mode sets it. It takes no colour and nothing that moves the
+ * cursor.
+ */
+export function isDumbTerminal(env) {
+    const term = env["TERM"];
+    return term === "dumb" || term === "unknown";
+}

package/dist/core/export-html.js

@@ -121,13 +121,14 @@ function onGrid(text, draw) {
  * blinks with the glyph. A wide glyph's box sits between the two: it inherits
  * the double underline, and the inner span inside it draws the other lines.
  */
-function runHtml({ text, look }) {
+function runHtml({ text, look, inVisualOrder }) {
     const drawn = look.underline === "double"
         ? span([...paintCss(look), "text-decoration-line:underline", "text-decoration-style:double", ...BLINK[look.blink]], onGrid(text, (glyph) => span([`color:${look.foreground.hex}`, ...glyphCss(look)], glyph)))
         : span([...paintCss(look), ...glyphCss(look)], onGrid(text, (glyph) => glyph));
+    const ordered = inVisualOrder ? span(["unicode-bidi:bidi-override"], drawn) : drawn;
     return look.href === null
-        ? drawn
-        : `<a href="${escapeAttribute(look.href)}" style="${ANCHOR_CSS}">${drawn}</a>`;
+        ? ordered
+        : `<a href="${escapeAttribute(look.href)}" style="${ANCHOR_CSS}">${ordered}</a>`;
 }
 /**
  * The CSS a page includes once, wherever fragments appear: what an inline

package/dist/core/export-lines.d.ts

@@ -65,6 +65,8 @@ export interface ExportLook {
 export interface ExportRun {
     readonly text: string;
     readonly look: ExportLook;
+    /** Its cells are in display order already, so a browser must not reorder them. */
+    readonly inVisualOrder: boolean;
 }
 /** One terminal row, left to right. An empty array is a blank row. */
 export type ExportLine = readonly ExportRun[];

package/dist/core/export-lines.js

@@ -31,6 +31,7 @@
  */
 import { blendRgb, ColorSpec } from "./color.js";
 import { NULL_STYLE } from "./style.js";
+import { sealed } from "./seal.js";
 /**
  * The URL schemes an export will link.
  *
@@ -146,13 +147,16 @@ export function resolveLook(style, theme) {
  */
 export function exportLines(segments, theme) {
     const rows = [[]];
-    for (const segment of segments) {
-        const look = resolveLook(segment.style ?? NULL_STYLE, theme);
+    // A browser is a display that reorders and holds the controls at zero width.
+    for (const segment of sealed(segments, "logical")) {
+        const style = segment.style ?? NULL_STYLE;
+        const look = resolveLook(style, theme);
+        const inVisualOrder = style.bidi?.order === "visual";
         segment.text.split("\n").forEach((piece, index) => {
             if (index > 0)
                 rows.push([]);
             if (piece.length > 0)
-                rows[rows.length - 1].push({ text: piece, look });
+                rows[rows.length - 1].push({ text: piece, look, inVisualOrder });
         });
     }
     return rows[rows.length - 1].length === 0 ? rows.slice(0, -1) : rows;