@promptctl/rich-js 0.27.0 → 0.29.0

package/dist/core/color.js

@@ -1,13 +1,15 @@
 /**
  * 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";
+import { detectTextOrder } from "./text-order.js";
 // --- ColorRgba ---
 function hex2(byte) {
     return byte.toString(16).padStart(2, "0");
 }
-// [LAW:one-source-of-truth] The one statement of a colour byte's range: the
+// [LAW:one-source-of-truth] The one statement of a color byte's range: the
 // constructor asserts it and the string parser reports it, from this predicate.
 function isByte(v) {
     return Number.isInteger(v) && v >= 0 && v <= 255;
@@ -73,12 +75,12 @@ export class ColorRgba {
     }
 }
 /**
- * The surface a terminal draws a translucent colour over. A terminal cannot
+ * The surface a terminal draws a translucent color over. A terminal cannot
  * know what lies under its cells, so the SGR writer (`Style.toSgrCodes`), the
  * exports that picture its output (`resolveLook`), the strip's seam test and
  * the contrast choosers (`themes/colorMath`) all composite over this one
- * colour. [LAW:one-source-of-truth] One constant, so
- * the colour text is chosen against is the colour the writer draws.
+ * color. [LAW:one-source-of-truth] One constant, so
+ * the color text is chosen against is the color the writer draws.
  */
 export const SURFACE_BLACK = new ColorRgba(0, 0, 0);
 /**
@@ -115,7 +117,7 @@ function luminanceRatio(la, lb) {
 // --- ColorTable ---
 // [LAW:one-source-of-truth] The one distance every table scan ranks by, so
 // `matchWhere`'s "nearest by the distance `match` uses" cannot drift, and
-// `Effected` weighs a written colour against `ColorSpec.matchOn` by it too.
+// `Effected` weighs a written color against `ColorSpec.matchOn` by it too.
 export function rgbDistance(a, b) {
     const dr = a.red - b.red;
     const dg = a.green - b.green;
@@ -125,7 +127,7 @@ export function rgbDistance(a, b) {
 /**
  * An indexed palette: entry `i` of `colors` is terminal index `firstIndex + i`.
  * `firstIndex` lets a table hold only the part of a palette a downgrade may
- * choose (the 256-colour cube and grey ramp start at 16) while every index it
+ * choose (the 256-color cube and grey ramp start at 16) while every index it
  * reports is the terminal's own.
  */
 export class ColorTable {
@@ -133,7 +135,7 @@ export class ColorTable {
     /** Each entry's relative luminance. */
     luminances;
     firstIndex;
-    // Keyed by colours a host computes without end (ramp stops, mixes), so bounded.
+    // Keyed by colors a host computes without end (ramp stops, mixes), so bounded.
     matchMemo = new Memo();
     readableMemo = new Memo();
     constructor(colors, firstIndex = 0) {
@@ -207,7 +209,7 @@ export class ColorTable {
     }
     /**
      * The nearest entry to `value` (the distance `match` uses) among those
-     * `accept` takes, given each entry's colour and terminal index; `undefined`
+     * `accept` takes, given each entry's color and terminal index; `undefined`
      * when it takes none. Entries are offered nearest-first (ties to the lower
      * index) and the first taken wins, so an expensive predicate runs only as
      * far out as the answer. Uncached: the predicate is the caller's, and a
@@ -230,7 +232,7 @@ export var ColorDepth;
     ColorDepth[ColorDepth["WINDOWS"] = 4] = "WINDOWS";
 })(ColorDepth || (ColorDepth = {}));
 /**
- * How many colours a depth can name, as a rank. WINDOWS is a sixteen-colour
+ * How many colors a depth can name, as a rank. WINDOWS is a sixteen-color
  * depth whose enum value sits above TRUECOLOR, so the enum's order is not this.
  * STANDARD and WINDOWS share a rank: the same sixteen slots, drawn by
  * different terminals, so each converts to the other by keeping the slot.
@@ -248,7 +250,7 @@ function fidelity(depth) {
             return 3;
     }
 }
-// The depths a colour system is named for. Its keys and "auto" are the whole
+// The depths a color system is named for. Its keys and "auto" are the whole
 // vocabulary: `ColorSystemName` is derived from them, so the type and the
 // table cannot disagree. [LAW:one-source-of-truth]
 const COLOR_SYSTEM_DEPTHS = {
@@ -257,11 +259,11 @@ const COLOR_SYSTEM_DEPTHS = {
     ansi: ColorDepth.STANDARD,
     none: null,
 };
-// [LAW:one-source-of-truth] What the environment says about colour, by the
+// [LAW:one-source-of-truth] What the environment says about color, by the
 // value it says it with: FORCE_COLOR values (the chalk/supports-color
-// convention), TERM_PROGRAM identifiers, and exact TERM names whose colour
+// convention), TERM_PROGRAM identifiers, and exact TERM names whose color
 // capability is known. A different vocabulary from `ColorSystemName`, so a
-// different table: `FORCE_COLOR=none` is not a request for no colour. A `Map`,
+// different table: `FORCE_COLOR=none` is not a request for no color. A `Map`,
 // so a value naming an `Object.prototype` member is unknown, not a function.
 // `null` means "no color".
 const ENV_DEPTHS = new Map([
@@ -297,7 +299,7 @@ const ENV_DEPTHS = new Map([
  * in the env values, not in which checks execute.
  */
 export function detectColorSystem(options = {}) {
-    // NO_COLOR and FORCE_COLOR are preferences about colour, not facts about the
+    // NO_COLOR and FORCE_COLOR are preferences about color, not facts about the
     // terminal, so they sit outside the probe. NO_COLOR (any non-empty value)
     // beats FORCE_COLOR; FORCE_COLOR beats TTY/TERM detection.
     const noColor = envOf(options)["NO_COLOR"];
@@ -317,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;
@@ -365,22 +359,25 @@ function terminalColorSystem(options) {
     return ColorDepth.STANDARD;
 }
 /**
- * Resolve a colour spec into a `Destination`.
+ * Resolve a color spec into an `OutputTarget`.
  *
  * [LAW:single-enforcer] The one place a spec becomes both facts. A hyperlink is
- * not a colour: an explicit depth — `"none"` and `null` included — states a
- * colour choice and keeps links, and under `"auto"` links follow what the
+ * not a color: an explicit depth — `"none"` and `null` included — states a
+ * color choice and keeps links, and under `"auto"` links follow what the
  * terminal can take (no TTY, TERM=dumb: none) while NO_COLOR and FORCE_COLOR=0,
- * colour preferences, leave them alone. A FORCE_COLOR that forces colour on
+ * color preferences, leave them alone. A FORCE_COLOR that forces color on
  * declares the destination takes escapes, so it keeps links on a pipe too.
  */
-export function resolveDestination(spec, options = {}) {
+export function resolveOutputTarget(spec, options = {}) {
     const reducedMotion = options.reducedMotion ?? false;
+    // Ahead of both arms: a color 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 {
@@ -388,10 +385,11 @@ export function resolveDestination(spec, options = {}) {
         hyperlinks: (forcedColorSystem(envOf(options)) ?? null) !== null ||
             terminalColorSystem(options) !== null,
         reducedMotion,
+        textOrder,
     };
 }
 /**
- * Resolve a colour system name into a `ColorDepth` (or `null` for no color).
+ * Resolve a color system name into a `ColorDepth` (or `null` for no color).
  *
  * `"auto"` triggers env-based detection; every other name is a fixed depth.
  * A name outside the vocabulary — reachable only from untyped JavaScript —
@@ -431,12 +429,12 @@ export class ColorSpec {
         return this.type === ColorDepth.DEFAULT;
     }
     /**
-     * The colour every terminal draws this spec as, where that is fixed — before
+     * The color every terminal draws this spec as, where that is fixed — before
      * any alpha is flattened, so a translucent value is drawn composited over
      * its ground (`flattenAlpha`) and should be measured that way: a
-     * truecolor value, or a 256-colour cube or grey-ramp entry (xterm fixes
+     * truecolor value, or a 256-color cube or grey-ramp entry (xterm fixes
      * indices 16–255, and `fromAnsi` types only those as EIGHT_BIT). ANSI 0–15,
-     * the default colour and a blend reaching either are the terminal theme's
+     * the default color and a blend reaching either are the terminal theme's
      * own, so they have none.
      */
     get fixedValue() {
@@ -555,20 +553,20 @@ export class ColorSpec {
         return ColorSpec.fromRgba(new ColorRgba(r, g, b));
     }
     /**
-     * The colour `t` of the way from `from` to `to`: what `blend(from,to,t)`
-     * parses to. Two fixed colours mix to a fixed colour. A mix reaching a
-     * theme's own colour stays a mix until it is drawn, so whatever theme draws
+     * The color `t` of the way from `from` to `to`: what `blend(from,to,t)`
+     * parses to. Two fixed colors mix to a fixed color. A mix reaching a
+     * theme's own color stays a mix until it is drawn, so whatever theme draws
      * an end draws the mix from it: exported under a theme whose `blue` is
      * #61afef, a mix with `blue` starts from #61afef. A terminal is told its RGB
      * under the standard table, the only one a render has.
      *
-     * Each end is one opaque colour: `default` is no colour to mix, and a
+     * Each end is one opaque color: `default` is no color to mix, and a
      * translucent end has no one shade until it is laid on a ground.
      */
     static blend(from, to, t) {
         for (const end of [from, to]) {
             if (end.isDefault)
-                throw new ColorParseError(`A blend cannot mix "default", which is no colour`);
+                throw new ColorParseError(`A blend cannot mix "default", which is no color`);
             if (end.value !== undefined && end.value.alpha < 1) {
                 throw new ColorParseError(`A blend's ends are opaque; "${end.name}" is translucent`);
             }
@@ -591,21 +589,21 @@ export class ColorSpec {
     }
     /**
      * The spec that draws `value` nearest to it at `depth` on a terminal known
-     * to show `theme`, as the colour of the glyph (`foreground`) or of the
+     * to show `theme`, as the color of the glyph (`foreground`) or of the
      * ground. Where `downgrade` knows no terminal, and so rounds only against
-     * colours every terminal fixes (or, at sixteen colours, the stock
-     * sixteen), this rounds against every colour the depth can write whose
-     * look `theme` fixes: the default colour, the theme's sixteen, and at 256
-     * colours the cube and grey ramp too. A colour read off any of those and
-     * moved a little is drawn as the colour it came from — or, where the theme
-     * gives two slots one colour, as the lower slot, which looks the same.
+     * colors every terminal fixes (or, at sixteen colors, the stock
+     * sixteen), this rounds against every color the depth can write whose
+     * look `theme` fixes: the default color, the theme's sixteen, and at 256
+     * colors the cube and grey ramp too. A color read off any of those and
+     * moved a little is drawn as the color it came from — or, where the theme
+     * gives two slots one color, as the lower slot, which looks the same.
      *
-     * `value` is opaque: a translucent colour has no one look until it is laid
+     * `value` is opaque: a translucent color has no one look until it is laid
      * on a ground (`flattenAlpha`).
      */
     static matchOn(value, depth, theme, foreground) {
         if (value.alpha < 1)
-            throw new RangeError(`matchOn rounds an opaque colour; got alpha ${value.alpha}`);
+            throw new RangeError(`matchOn rounds an opaque color; got alpha ${value.alpha}`);
         if (depth === ColorDepth.TRUECOLOR)
             return ColorSpec.fromRgba(value);
         if (depth === ColorDepth.DEFAULT)
@@ -623,23 +621,23 @@ export class ColorSpec {
         return candidates.reduce((best, next) => (rgbDistance(next[1], value) < rgbDistance(best[1], value) ? next : best))[0];
     }
     /**
-     * Every colour `depth` writes by index, each with the colour a terminal
+     * Every color `depth` writes by index, each with the color a terminal
      * known to show `theme` draws it in, lowest index first: the theme's
-     * sixteen, and at 256 colours the cube and grey ramp after them. Each is
-     * drawn alike as glyph and as ground, which the default colour is not, so
-     * it is not among them. Truecolor writes a colour itself and the default
-     * depth only the default, so neither writes any by index. The colours
+     * sixteen, and at 256 colors the cube and grey ramp after them. Each is
+     * drawn alike as glyph and as ground, which the default color is not, so
+     * it is not among them. Truecolor writes a color itself and the default
+     * depth only the default, so neither writes any by index. The colors
      * `matchOn` rounds to, but for the default, read off the same two tables.
      */
     static indexed(depth, theme) {
         return indexedMemo.get(theme, () => new Memo()).get(`${depth}`, () => listIndexed(depth, theme));
     }
     /**
-     * The spec a slot is written in once its colour moves from `was`, what its
+     * The spec a slot is written in once its color moves from `was`, what its
      * written spec draws on `theme`, to the opaque `now`: `matchOn`'s — or
      * none, where the written spec is as near `now` as that match. A move the
-     * depth cannot show is no move, so below truecolor a colour moved a little
-     * off any colour the depth can write — a theme slot, the default colour,
+     * depth cannot show is no move, so below truecolor a color moved a little
+     * off any color the depth can write — a theme slot, the default color,
      * the cube — keeps the spec it was written in.
      */
     static matchMove(was, now, depth, theme, foreground) {
@@ -655,7 +653,7 @@ export class ColorSpec {
     }
     // --- private ---
     performDowngrade(targetSystem) {
-        // The colour as the terminal this depth assumes draws it: a blend's named
+        // The color as the terminal this depth assumes draws it: a blend's named
         // ends are the Windows console's own at WINDOWS.
         const triplet = this.getTruecolor(resolveTerminal(undefined, targetSystem));
         switch (targetSystem) {
@@ -664,7 +662,7 @@ export class ColorSpec {
             case ColorDepth.STANDARD:
             case ColorDepth.WINDOWS: {
                 // An ANSI slot is already one of the sixteen either depth writes; only
-                // a fixed colour is matched against the depth's table, as Rich does.
+                // a fixed color is matched against the depth's table, as Rich does.
                 const index = this.number !== undefined && this.number < 16 ? this.number : downgradeTable(targetSystem).match(triplet);
                 return new ColorSpec(`color(${index})`, targetSystem, index);
             }
@@ -675,7 +673,7 @@ export class ColorSpec {
         }
     }
 }
-/** The cube or grey-ramp entry nearest `value`, and its colour. */
+/** The cube or grey-ramp entry nearest `value`, and its color. */
 function cubeCandidate(value) {
     const index = EIGHT_BIT_DOWNGRADE_TABLE.match(value);
     return [ColorSpec.fromAnsi(index), EIGHT_BIT_DOWNGRADE_TABLE.get(index)];
@@ -701,7 +699,7 @@ function mix(from, to, t, theme) {
     return blendRgb(from.getTruecolor(theme), to.getTruecolor(theme), t);
 }
 // How a blend spells an end: by what it draws as, so every spelling of one
-// colour ("blue", "color(4)", an EIGHT_BIT 4) gives the blend one name.
+// color ("blue", "color(4)", an EIGHT_BIT 4) gives the blend one name.
 function blendTerm(end) {
     return end.fixedValue?.hex ?? (end.number !== undefined ? `color(${end.number})` : end.name);
 }
@@ -804,8 +802,8 @@ function parseByte(key, digits, field) {
     return n;
 }
 // --- Utility functions ---
-// [LAW:single-enforcer] The hex colour grammar, checked here and nowhere else:
-// every string spelling a colour in hex — a ColorSpec, a theme's data, a colour
+// [LAW:single-enforcer] The hex color grammar, checked here and nowhere else:
+// every string spelling a color in hex — a ColorSpec, a theme's data, a color
 // reference, a template argument — becomes one through the three parsers below,
 // and each is this check at the lengths it admits. Each digit pair is a byte, so
 // the grammar holding is what keeps `ColorRgba`'s channels in range.
@@ -816,12 +814,12 @@ const HEX_GRAMMARS = { 6: "RRGGBB", 8: "RRGGBBAA" };
 function hexColor(input, lead, digits, lengths) {
     if (!lengths.includes(digits.length) || !HEX_DIGITS_RE.test(digits)) {
         const expected = lengths.map((n) => lead + HEX_GRAMMARS[n]).join(" or ");
-        throw new ColorParseError(`Invalid hex colour ${JSON.stringify(input)} (expected ${expected})`);
+        throw new ColorParseError(`Invalid hex color ${JSON.stringify(input)} (expected ${expected})`);
     }
     const byte = (at) => parseInt(digits.slice(at, at + 2), 16);
     return new ColorRgba(byte(0), byte(2), byte(4), digits.length === 8 ? byte(6) / 255 : 1);
 }
-/** Six hex digits, no `#`, as an opaque colour. @throws {ColorParseError} on anything else. */
+/** Six hex digits, no `#`, as an opaque color. @throws {ColorParseError} on anything else. */
 export function parseRgbHex(hex) {
     return hexColor(hex, "", hex, [6]);
 }
@@ -841,7 +839,7 @@ export function blendRgb(color1, color2, crossFade = 0.5) {
 }
 // --- TerminalTheme ---
 /**
- * What a terminal draws with: the part of a `TerminalTheme` a colour resolves
+ * What a terminal draws with: the part of a `TerminalTheme` a color resolves
  * against.
  */
 export class TerminalColors {
@@ -855,17 +853,17 @@ export class TerminalColors {
         // [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) {
-            throw new RangeError(`a TerminalTheme's ansiColors are the sixteen ANSI colours, indices 0–15; got ${ansiColors.size} from index ${ansiColors.firstIndex}`);
+            throw new RangeError(`a TerminalTheme's ansiColors are the sixteen ANSI colors, indices 0–15; got ${ansiColors.size} from index ${ansiColors.firstIndex}`);
         }
     }
 }
 /**
- * A terminal theme — surface/foreground baseline, the sixteen ANSI colours,
+ * A terminal theme — surface/foreground baseline, the sixteen ANSI colors,
  * and a semantic palette.
  *
- * **`ansiColors` is the theme's own sixteen colours**, the shades a terminal
+ * **`ansiColors` is the theme's own sixteen colors**, 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,
+ * is ANSI color 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 {
@@ -916,8 +914,8 @@ function build256Table() {
 }
 /**
  * The Windows console's own sixteen (its default Campbell scheme), in ANSI
- * index order: a WINDOWS colour is written as the same `30+n`/`90+n` SGR a
- * STANDARD one is, so slot `n` here is the colour the console draws for it.
+ * index order: a WINDOWS color is written as the same `30+n`/`90+n` SGR a
+ * STANDARD one is, so slot `n` here is the color the console draws for it.
  */
 function buildWindowsTable() {
     return [
@@ -942,8 +940,8 @@ function buildWindowsTable() {
 export const STANDARD_TABLE = new ColorTable(buildStandard16());
 export const EIGHT_BIT_TABLE = new ColorTable(build256Table());
 /**
- * What a downgrade to 256 colours may choose: the cube and the grey ramp,
- * indices 16–255. Indices 0–15 are the terminal's own ANSI colours, which
+ * What a downgrade to 256 colors may choose: the cube and the grey ramp,
+ * indices 16–255. Indices 0–15 are the terminal's own ANSI colors, which
  * every theme redefines, so their RGB is unknown and a match against them is
  * a guess; Python Rich never picks them either.
  */
@@ -952,18 +950,18 @@ export const WINDOWS_TABLE = new ColorTable(buildWindowsTable());
 // --- 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, its own sixteen and no palette, which the
+// terminal a color'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. */
+/** The Windows console in its default Campbell scheme: a WINDOWS color's terminal. */
 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
+ * The terminal a color at `depth` is drawn by: `theme`, or when a caller names
  * none, the one the depth assumes — the Windows console at WINDOWS, the VGA
  * sixteen otherwise — for `ColorSpec.getTruecolor` and the contrast measurement
  * that reads it. (Widgets fall back to `DEFAULT_TERMINAL_THEME`, which carries a
@@ -973,9 +971,9 @@ export function resolveTerminal(theme, depth) {
     return theme ?? (depth === ColorDepth.WINDOWS ? WINDOWS_CONSOLE_TERMINAL : INTERNAL_DEFAULT_TERMINAL);
 }
 /**
- * The table a downgrade to `depth` rounds a fixed colour against.
- * [LAW:one-source-of-truth] `ColorSpec.downgrade` picks the index a colour is
- * written as from it, and colorMath hands back its entries as colours the
+ * The table a downgrade to `depth` rounds a fixed color against.
+ * [LAW:one-source-of-truth] `ColorSpec.downgrade` picks the index a color is
+ * written as from it, and colorMath hands back its entries as colors the
  * writer rounds to those same indices.
  */
 export function downgradeTable(depth) {

package/dist/core/console.d.ts

@@ -3,9 +3,10 @@
  */
 import { Style, Theme } from "./style.js";
 import { ColorDepth } from "./color.js";
-import type { ColorSystemName, Destination } from "./color.js";
+import type { TextOrder } from "./text-order.js";
+import type { ColorSystemName, OutputTarget } 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";
@@ -44,7 +45,7 @@ export interface ConsoleOptions {
      * Color encoding. Accepts a `ColorSystemName` (`"auto"`, `"truecolor"`,
      * `"256"`, `"ansi"`, `"none"`), a `ColorDepth` enum value (use this for
      * `WINDOWS`, which has no name), or `null` for no color. Default `"auto"`.
-     * Colour only: an explicit depth, `null` included, keeps hyperlinks.
+     * Color only: an explicit depth, `null` included, keeps hyperlinks.
      */
     colorSystem?: ColorSystemName | ColorDepth | null;
     /**
@@ -53,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
@@ -69,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 colors on. Default: the one the
+     * color 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.
@@ -104,7 +113,7 @@ export interface ConsoleOptions {
     stderr?: boolean;
     file?: ConsoleSink;
     /**
-     * Host facilities to consult for colour detection, size detection, and the
+     * Host facilities to consult for color detection, size detection, and the
      * default output sink. Defaults to the ambient `process`, or — where there
      * is no `process` — an empty environment with no streams. Pass this to drive
      * a `Console` deterministically, or to run one against a simulated terminal.
@@ -149,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;
@@ -156,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;
@@ -174,12 +185,12 @@ export declare class Console {
     get isInteractive(): boolean;
     get colorSystem(): ColorDepth | null;
     /**
-     * Where this console writes: the colour depth it draws at, whether it
+     * Where this console writes: the color depth it draws at, whether it
      * emits OSC 8 hyperlinks, and whether its reader asked for reduced motion,
      * overrides applied — the value its output is
      * encoded for, for anything that encodes on its behalf (`Live`).
      */
-    get destination(): Destination;
+    get destination(): OutputTarget;
     get file(): ConsoleSink;
     get theme(): Theme;
     get options(): RenderOptions & {
@@ -188,10 +199,16 @@ 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;
     /**
-     * Hold `region` under everything this console writes until the returned
+     * Keep `region` under everything this console writes until the returned
      * call lets it go. One region at a time: a second would be erased and
      * painted over by the first, so claiming one while another is held throws.
      */

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 { resolveOutputTarget } 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";
@@ -93,7 +95,7 @@ function ambientEnvironment() {
 // bytes go — is a question about *that* stream. Selecting it once, here, is
 // what makes the three answers agree. When each site re-selected for itself,
 // one of them (size) silently didn't, and a `Console({ stderr: true })` keyed
-// its colour to stderr and its width to stdout.
+// its color to stderr and its width to stdout.
 function boundStream(environment, useStderr) {
     return useStderr ? environment.stderr : environment.stdout;
 }
@@ -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 = resolveOutputTarget(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;
@@ -254,7 +261,7 @@ export class Console {
         return this._destination.colorSystem;
     }
     /**
-     * Where this console writes: the colour depth it draws at, whether it
+     * Where this console writes: the color depth it draws at, whether it
      * emits OSC 8 hyperlinks, and whether its reader asked for reduced motion,
      * overrides applied — the value its output is
      * encoded for, for anything that encodes on its behalf (`Live`).
@@ -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,
@@ -495,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
@@ -515,7 +534,7 @@ export class Console {
     }
     // --- Live region ---
     /**
-     * Hold `region` under everything this console writes until the returned
+     * Keep `region` under everything this console writes until the returned
      * call lets it go. One region at a time: a second would be erased and
      * painted over by the first, so claiming one while another is held throws.
      */
@@ -547,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;