@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/core/console.js

@@ -0,0 +1,596 @@
+/**
+ * Console — the central orchestrator for rendering styled output to the terminal.
+ */
+import { Segment } from "./segment.js";
+import { NULL_STYLE, DEFAULT_THEME } from "./style.js";
+import { isDumbTerminal, resolveDestination } from "./color.js";
+import { encodeHtml } from "./export-html.js";
+import { encodeSvg } from "./export-svg.js";
+import { RichText } from "./text.js";
+import { activeHighlighter, renderStr } from "./markup.js";
+import { Pretty, UNSEEN_DATA_BOUNDS, isExpandable } from "./pretty.js";
+import { JSONRenderable } from "./json.js";
+import { ReprHighlighter, NullHighlighter } from "./highlighter.js";
+// [LAW:one-way-deps] exception: one of the two sanctioned upward edges out of
+// `core/`, named in CLAUDE.md and pinned by `test/seam/layering.test.ts` — the
+// orchestrator reaching down for `Rule`. `RuleOptions` rides the same edge
+// rather than being restated here; see `rule()`.
+import { Rule } from "../renderables/rule.js";
+import { segmentsToString } from "./render.js";
+import { placeBlock } from "./place.js";
+import { isRenderable } from "./protocol.js";
+// [LAW:dataflow-not-control-flow] With no live region claimed, stepping around
+// it is the text itself: every write takes the same path.
+const NO_LIVE_REGION = { around: (text) => text };
+// Rows as the bytes that reach the terminal. Every row but the last is closed
+// by a line break, and the last one when `closed` says so. Crop last, and crop
+// the line-end with the rest: in the reference `end` is the tail of the printed
+// line, so a line cut at the edge loses it too.
+function emit({ rows, closed, cropWidth }) {
+    const output = rows.flatMap((row, index) => closed || index < rows.length - 1 ? [...row, Segment.line()] : row);
+    return [...Segment.cropLines(output, cropWidth)];
+}
+// The time `log` stamps: local 24-hour `HH:MM:SS`, what the reference's `%X`
+// prints under the C locale a Python program runs in unless it asks for
+// another. The machine's locale never reaches it, so neither does the width
+// an AM/PM suffix would add, and one clock prints one stamp everywhere.
+function logTime(time) {
+    // [LAW:no-silent-failure] The clock is the caller's, and an invalid `Date`
+    // would otherwise print as `[NaN:NaN:NaN]`.
+    if (Number.isNaN(time.getTime()))
+        throw new RangeError("Console getDatetime returned an invalid Date");
+    const two = (n) => String(n).padStart(2, "0");
+    return `[${two(time.getHours())}:${two(time.getMinutes())}:${two(time.getSeconds())}] `;
+}
+// Three of the five justify methods place what a print draws as a block, the
+// way Rich's `print` wraps each renderable in `Align`. The other two leave it
+// where it was drawn: `"default"` asks for no placement, and `"full"` is a way
+// of setting a paragraph's words, which only text can do.
+const PLACED_BY = {
+    default: undefined,
+    full: undefined,
+    left: "left",
+    center: "center",
+    right: "right",
+};
+// A text run as one block: its items joined into one text, as the reference's
+// `Text.join` joins them, drawn under the print's options and ended by the
+// print's `end`. Measure and render both read that one text, so the width
+// `justify` places the run at is the width it is drawn at. Each item's own
+// `justify`, `overflow`, `noWrap` and `tabSize` stay behind, as they do in the
+// reference: the print's options set the whole run.
+class TextRun {
+    end;
+    text;
+    constructor(items, end) {
+        this.end = end;
+        this.text = items.reduce((joined, item) => joined.append(item), new RichText("", { end: "" }));
+    }
+    *render(options) {
+        yield* this.text.render(options);
+        yield this.end;
+    }
+    measure(options) {
+        return this.text.measure(options);
+    }
+}
+// A host with an environment but no streams — what a browser looks like from
+// here. Frozen so the shared instance cannot be mutated into a fake terminal.
+const DETACHED_ENVIRONMENT = Object.freeze({
+    env: Object.freeze({}),
+});
+// [LAW:single-enforcer] The only read of the ambient `process` global in this
+// module, and the reason every other function below takes its environment as
+// an argument. `process` satisfies `ConsoleEnvironment` structurally, so the
+// node path needs no adapter; the browser path degrades to a host that answers
+// "no streams" rather than throwing at the reference.
+function ambientEnvironment() {
+    return typeof process === "undefined" ? DETACHED_ENVIRONMENT : process;
+}
+// [LAW:one-source-of-truth] A console talks to exactly one stream, and every
+// question it asks the host — are you a terminal, how wide are you, where do
+// 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.
+function boundStream(environment, useStderr) {
+    return useStderr ? environment.stderr : environment.stdout;
+}
+// [LAW:single-enforcer] Effective TTY status of the console's output target is
+// computed once, at construction, and cached — an explicit `file` is not a
+// terminal, `forceTerminal` says it is regardless, and otherwise the bound
+// stream answers. Every input is fixed at construction, so recomputing per
+// read could only ever return the same answer twice.
+function effectiveIsTTY(options, stream) {
+    if (options?.forceTerminal)
+        return true;
+    if (options?.file)
+        return false;
+    return stream?.isTTY ?? false;
+}
+function terminalSize(environment, stream) {
+    const cols = environment.env["COLUMNS"];
+    const lines = environment.env["LINES"];
+    const w = cols ? parseInt(cols, 10) : (stream?.columns ?? 80);
+    const h = lines ? parseInt(lines, 10) : (stream?.rows ?? 24);
+    return { width: w || 80, height: h || 24 };
+}
+// [LAW:single-enforcer] One trust-boundary check: when no `file:` was
+// provided, the console writes to the stream it is bound to — which a browser
+// host does not have. Without this, the absence would surface as a `TypeError`
+// deep inside `_write`. Centralizing it here keeps both consumers (`file`
+// getter, `_write`) behaving identically — no second copy of the check to
+// drift.
+function defaultSink(stream) {
+    if (stream === undefined) {
+        throw new Error("Console: no `file` provided and the environment has no stream to " +
+            "write to (e.g. running in a browser). Pass " +
+            "`environment: hostEnvironment(host)` to write through a terminal " +
+            "host, or a `file` so output has somewhere to go.");
+    }
+    return stream;
+}
+// [LAW:dataflow-not-control-flow] Build one size-reading function at
+// construction time from whichever options the caller supplied. The width
+// getter is then unconditional — it always calls `_getSize()`. Variability
+// lives in the captured closure (which source it consults), not in branches
+// the getter has to evaluate on every read.
+//
+// The all-static and mixed cases get *different* closures: when both
+// dimensions are fixed, the returned function is a constant — no
+// `terminalSize` call on every read, since neither value can change.
+// When at least one dimension is dynamic, the closure consults
+// `terminalSize` to fill in the missing side.
+function resolveGetSize(options, environment, stream) {
+    if (options?.getSize)
+        return options.getSize;
+    const staticWidth = options?.width;
+    const staticHeight = options?.height;
+    if (staticWidth !== undefined && staticHeight !== undefined) {
+        // [LAW:one-source-of-truth] Freeze the captured object so consumers can't
+        // mutate `console.size` and silently change every subsequent read.
+        // Matches the dynamic-closure path (which builds a fresh object per call
+        // and is therefore implicitly immutable from a sharing standpoint).
+        const fixed = Object.freeze({ width: staticWidth, height: staticHeight });
+        return () => fixed;
+    }
+    return () => {
+        const term = terminalSize(environment, stream);
+        return {
+            width: staticWidth ?? term.width,
+            height: staticHeight ?? term.height,
+        };
+    };
+}
+// --- Console ---
+/** Shared because it is stateless: highlighting nothing has nothing to own. */
+const NO_HIGHLIGHT = new NullHighlighter();
+export class Console {
+    _destination;
+    // [LAW:one-source-of-truth] Size flows through a single function. Static
+    // `width`/`height` options collapse into a closure that returns them; a
+    // caller-supplied `getSize` overrides. Every size read in this class goes
+    // through `_getSize()` — no second path, no second source to drift.
+    _getSize;
+    _getDatetime;
+    // The stamp the last `log` row was given, which the next row's stamp is
+    // compared with: the reference's `LogRender._last_time`, one per console.
+    // [LAW:no-ambient-temporal-coupling] "same as the previous row" is a fact
+    // about an earlier call, so it is state this console owns, not order luck.
+    _lastLogTime = null;
+    _style;
+    _isTerminal;
+    _interactive;
+    _file;
+    // [LAW:one-source-of-truth] The resolved output stream, not the `stderr`
+    // flag that selected it. Storing the answer instead of the question is what
+    // stops `isTerminal`, `size`, and `file` from re-deriving it three ways.
+    _stream;
+    _record;
+    _markup;
+    _highlight;
+    _theme;
+    _onStyleError;
+    _asciiOnly;
+    _highlighter;
+    _recorded;
+    // [LAW:types-are-the-program] The capture state is carried in the *type*
+    // of this field, not in a sentinel value. `null` = not capturing; any
+    // string (including "") = capturing, this is the buffer. A paired
+    // boolean+string would admit the impossible state "not capturing, buffer
+    // non-empty" — `string | null` makes that unrepresentable.
+    _capture;
+    _liveRegion;
+    constructor(options) {
+        const environment = options?.environment ?? ambientEnvironment();
+        const stream = boundStream(environment, options?.stderr ?? false);
+        this._stream = stream;
+        this._isTerminal = effectiveIsTTY(options, stream);
+        // [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 });
+        // [LAW:single-enforcer] The console's one override, an explicit
+        // `hyperlinks`, is applied here and nowhere else; every write encodes for
+        // this value whole.
+        this._destination = {
+            colorSystem: resolved.colorSystem,
+            hyperlinks: options?.hyperlinks ?? resolved.hyperlinks,
+        };
+        this._getSize = resolveGetSize(options, environment, stream);
+        this._getDatetime = options?.getDatetime ?? (() => new Date());
+        // [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._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));
+        this._file = options?.file;
+        this._record = options?.record ?? false;
+        this._markup = options?.markup !== false;
+        this._highlight = options?.highlight !== false;
+        this._highlighter = options?.highlighter ?? new ReprHighlighter();
+        this._onStyleError = options?.onStyleError;
+        this._asciiOnly = options?.asciiOnly ?? false;
+        this._recorded = [];
+        this._capture = null;
+        this._liveRegion = NO_LIVE_REGION;
+    }
+    // --- Properties ---
+    get size() {
+        return this._getSize();
+    }
+    get width() {
+        return this._getSize().width;
+    }
+    get height() {
+        return this._getSize().height;
+    }
+    get isTerminal() {
+        return this._isTerminal;
+    }
+    get isInteractive() {
+        return this._interactive;
+    }
+    get colorSystem() {
+        return this._destination.colorSystem;
+    }
+    /**
+     * Where this console writes: the colour depth it draws at and whether it
+     * emits OSC 8 hyperlinks, overrides applied — the value its output is
+     * encoded for, for anything that encodes on its behalf (`Live`).
+     */
+    get destination() {
+        return this._destination;
+    }
+    // [LAW:one-source-of-truth] Output target lookup matches `_write`'s:
+    // explicit `file` wins, otherwise `defaultSink` returns the bound stream
+    // (or throws clearly when the environment has none). Exposed
+    // so renderables that bypass the segment pipeline (e.g. Live's raw control
+    // sequences) still write to the caller's configured stream. Return type is
+    // the narrow `ConsoleSink` — Live (and any external consumer) only needs
+    // `.write()`, so the type tells the truth about what the surface guarantees.
+    get file() {
+        return this._file ?? defaultSink(this._stream);
+    }
+    get theme() {
+        return this._theme;
+    }
+    get options() {
+        // One read of the size, so a resize cannot pair one frame's width with
+        // another's height.
+        const { width, height } = this.size;
+        return {
+            maxWidth: width,
+            // The terminal an inline print lands on: a ceiling, never a region —
+            // content keeps its natural height beneath it.
+            height: { rows: height, exact: false },
+            isTerminal: this.isTerminal,
+            asciiOnly: this._asciiOnly,
+            theme: this._theme,
+            onStyleError: this._onStyleError,
+            colorSystem: this._destination.colorSystem,
+            markup: this._markup,
+            highlight: this._highlight,
+            highlighter: this._highlighter,
+        };
+    }
+    // --- Print ---
+    print(...args) {
+        this._writeSegments(emit(this._draw(args, this.options)));
+    }
+    // What `print` draws for `args` at `options.maxWidth`.
+    _draw(args, options) {
+        // Extract options from last arg if it's a PrintOptions
+        let opts = {};
+        let items;
+        // The trailing options object is only recognised when something precedes
+        // it. A lone object is data — `print({ style: "..." })` reads as a value to
+        // format, and treating it as options would emit an empty line, which is the
+        // one outcome this method must never produce. Nothing is given up: options
+        // configure the rendering of content, so a call carrying options and no
+        // content had nothing to render either way. [LAW:no-silent-failure]
+        const lastArg = args[args.length - 1];
+        if (args.length > 1 &&
+            typeof lastArg === "object" &&
+            lastArg !== null &&
+            !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)) {
+            opts = lastArg;
+            items = args.slice(0, -1);
+        }
+        else {
+            items = args;
+        }
+        // What a string is read as, wherever in this print it lands: an argument,
+        // or a cell or label inside a renderable argument. `print`'s own flags
+        // outrank the console's, as Rich's `options.update` has them.
+        const strings = {
+            markup: opts.markup ?? this._markup,
+            highlight: opts.highlight ?? this._highlight,
+            highlighter: this._highlighter,
+        };
+        const sep = opts.sep ?? " ";
+        const end = opts.end ?? "\n";
+        const softWrap = opts.softWrap ?? false;
+        const printStyle = this._theme.resolve(opts.style ?? NULL_STYLE);
+        // A print is a column of blocks, and every argument joins one of two kinds.
+        // Text — a string, a `RichText`, or a scalar — runs together: adjacent text
+        // items are one block, joined by `sep` and ended by `end`. Any other
+        // renderable is a block of its own that occupies whole lines, so neither
+        // `sep` nor `end` ever touches it. That is the reference's split — `end`
+        // belongs to text, not to the print — and it is what lets two printed panels
+        // stack with no blank line between them. Data is cut where the reference
+        // cuts it: a container (`isExpandable`) is a block, a scalar is text. A
+        // container is laid out by `Pretty` across as many lines as it needs, and
+        // joined into a run it would start partway along a line and leave its
+        // closing bracket where the next item carries on. The line is not closed by
+        // asking where the cursor sits: `print("a\n")` is a line and an empty one,
+        // here as in the reference and in every other `print`, and only the kind of
+        // the item can tell that trailing break from a `Panel`'s. A call with
+        // nothing to print is one empty text run, so it still ends the line.
+        const blocks = items.length === 0 ? [{ kind: "text", items: [] }] : [];
+        for (const item of items) {
+            // Four arms, and they are the whole domain. A `RichText` is already text.
+            // No arm's own `end` reaches the line: `TextRun` joins the run with
+            // `append`, which leaves each part's behind, as Rich's `Text(sep).join`
+            // does, because the line end of a run is the print's. Any other renderable draws itself,
+            // as a block. A string is the only kind of argument that can *contain*
+            // markup, so it is the only kind the markup dialect is applied to.
+            // Everything else is data — a block when it is a container, text when it
+            // is not — and `Pretty` is the single authority on how a
+            // JavaScript value displays — `String(value)` was a second, weaker one
+            // that answered `[object Object]` for every object and let the markup
+            // parser eat it. [LAW:one-source-of-truth]
+            let text;
+            if (item instanceof RichText) {
+                text = item;
+            }
+            else if (isRenderable(item)) {
+                blocks.push({ kind: "lines", renderable: item });
+                continue;
+            }
+            else if (typeof item === "string") {
+                text = renderStr(item, strings);
+            }
+            else {
+                // The highlighter travels with the value. `highlight` and a custom
+                // `highlighter` are console-wide settings, so they have to reach a
+                // formatted object the same way they reach a printed string; a `Pretty`
+                // left to its own default would outrank both. [LAW:dataflow-not-control-flow]
+                // the disabled case is an identity highlighter, not a skipped call.
+                const pretty = new Pretty(item, {
+                    ...UNSEEN_DATA_BOUNDS,
+                    highlighter: activeHighlighter(strings) ?? NO_HIGHLIGHT,
+                });
+                // A scalar spells the same at every width, so it joins its run as the
+                // one text it is.
+                if (isExpandable(item)) {
+                    blocks.push({ kind: "lines", renderable: pretty });
+                    continue;
+                }
+                text = pretty.toText(options);
+            }
+            const run = blocks.at(-1);
+            if (run?.kind === "text")
+                run.items.push(new RichText(sep), text);
+            else
+                blocks.push({ kind: "text", items: [text] });
+        }
+        // Soft wrap is the reference's pair of defaults, not a mode of its own: it
+        // stops wrapping, and when no overflow was named it asks for `"ignore"`, so
+        // the line leaves unbounded. A named overflow still cuts the unwrapped line
+        // at the width, as Rich's does. What `"ignore"` does to a line — no edge,
+        // no justify — is `RichText`'s to apply, so it crosses as it was asked for.
+        const renderOpts = {
+            ...options,
+            ...strings,
+            justify: opts.justify === "default" ? undefined : opts.justify,
+            overflow: opts.overflow ?? (softWrap ? "ignore" : undefined),
+            noWrap: softWrap,
+        };
+        // The print style, then the console's base style, over each line a block
+        // drew and never over the break that ends it: a styled break carries SGR
+        // codes across the newline.
+        // [LAW:dataflow-not-control-flow] no style to apply is an empty list, not
+        // a skipped step.
+        const styles = [printStyle, this._style].filter((style) => !style.isNull);
+        const styleContent = (segments) => styles.reduce((styled, style) => Segment.applyStyle(styled, style), segments);
+        // The common default end is "\n" — reuse Segment's cached newline rather
+        // than allocating one per print; only a non-default end needs a fresh one.
+        const terminator = end === "\n" ? Segment.line() : new Segment(end);
+        const align = PLACED_BY[opts.justify ?? "default"];
+        // Each block as its lines, and whether its last line is closed. A placed
+        // block is closed line by line, as `Align` closes it. Unplaced, a text run
+        // is closed exactly where its content — its `end` included — breaks; any
+        // other block's lines are closed whether or not it closed them itself: a
+        // `Panel` ends in a line break and a bare `ProgressBar` does not (a line
+        // fragment — test/seam/line-ends.ts), and both leave the next print at the
+        // start of a line.
+        const drawBlock = (block) => {
+            const renderable = block.kind === "text" ? new TextRun(block.items, terminator) : block.renderable;
+            if (align)
+                return { lines: placeBlock(renderable, align, renderOpts), closed: true };
+            const drawn = [...renderable.render(renderOpts)];
+            // A text run's last segment is always its `end`, yielded even when
+            // empty, and `splitLines` drops the empty line after a final break only
+            // when nothing follows it — so the run is closed exactly when `end` is.
+            const closed = block.kind === "lines" || end.endsWith("\n");
+            return { lines: Segment.splitLines(drawn), closed };
+        };
+        // Every line end goes through the same writeSegments funnel as the text it
+        // ends, so it survives recording — otherwise `exportText` and `exportHtml`
+        // would join consecutive prints onto a single line. [LAW:single-enforcer]
+        // A block left open carries on along the next block's first line, so the
+        // rows are read off the joined output rather than counted per block.
+        const output = [];
+        let closed = true;
+        for (const block of blocks) {
+            const drawn = drawBlock(block);
+            drawn.lines.forEach((line, index) => {
+                output.push(...styleContent(line));
+                if (drawn.closed || index < drawn.lines.length - 1)
+                    output.push(Segment.line());
+            });
+            closed = drawn.closed;
+        }
+        // Soft wrap turns cropping off whatever `crop` says, because a line it left
+        // whole is meant to reach the terminal whole. [LAW:dataflow-not-control-flow]
+        // Not cropping is an unbounded width rather than a skipped step — the same
+        // spelling `RichText` uses for `"ignore"`.
+        const cropWidth = !softWrap && (opts.crop ?? true) ? options.maxWidth : Infinity;
+        return { rows: Segment.splitLines(output), closed, cropWidth };
+    }
+    // The reference's `LogRender`: a grid row of two cells, the time and beside it
+    // whatever `print` would draw for `args` in the width that is left. A grid row
+    // is at least one line tall and always closed, whatever `end` left open
+    // inside its cell. The time gives up cells before the content does, so a
+    // console narrower than the time still shows every argument. The time takes
+    // the console's style alone, as the reference styles only the renderables.
+    // A time that reads as the previous row's is left blank at its width, the
+    // reference's `omit_repeated_times`, so a burst of rows carries one stamp.
+    log(...args) {
+        const options = this.options;
+        const stamped = logTime(this._getDatetime());
+        const repeated = stamped === this._lastLogTime;
+        const time = new RichText(stamped, { end: "" });
+        time.stylize("log.time");
+        const width = Math.min(time.cellLength, options.maxWidth - 1);
+        const { rows, cropWidth } = this._draw(args, { ...options, maxWidth: options.maxWidth - width });
+        const [stampLine = []] = Segment.splitLines(time.render({ ...options, maxWidth: time.cellLength }));
+        const styled = (cell) => [...Segment.applyStyle(cell, this._style)];
+        const stamp = styled(Segment.adjustLineLength(stampLine, width));
+        const blank = styled([new Segment(" ".repeat(width))]);
+        const head = repeated ? blank : stamp;
+        const grid = Array.from({ length: Math.max(1, rows.length) }, (_, index) => [
+            ...(index === 0 ? head : blank),
+            ...(rows[index] ?? []),
+        ]);
+        // The row is the column wider than its cell; an uncropped cell stays so.
+        this._writeSegments(emit({ rows: grid, closed: true, cropWidth: cropWidth + width }));
+        // Remembered only once the row is written: a log that threw printed no
+        // stamp, so the next row's must show.
+        this._lastLogTime = stamped;
+    }
+    // [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
+    // then, free to drift the moment `Rule` grew an option.
+    rule(title, options) {
+        const segments = [...new Rule(title, options).render(this.options)];
+        this._writeSegments(segments);
+    }
+    // [LAW:one-source-of-truth] `JSONRenderable` is the one formatter for JSON and
+    // `JSONOptions` is its option set; this method only picks the constructor. It
+    // prints with soft wrap, as the reference does, so a line wider than the
+    // console reaches the terminal whole and the output stays valid JSON.
+    printJson(json, options) {
+        const renderable = typeof json === "string"
+            ? JSONRenderable.fromString(json, options)
+            : JSONRenderable.fromData(json, options);
+        this.print(renderable, { softWrap: true });
+    }
+    // --- Live region ---
+    /**
+     * Hold `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.
+     */
+    claimLiveRegion(region) {
+        if (this._liveRegion !== NO_LIVE_REGION) {
+            throw new Error("A live display is already running on this console; stop it before starting another.");
+        }
+        this._liveRegion = region;
+        // Letting go of a region no longer held — a second call, or after another
+        // was claimed — leaves the one that is.
+        return () => {
+            if (this._liveRegion === region)
+                this._liveRegion = NO_LIVE_REGION;
+        };
+    }
+    // --- Capture ---
+    // [LAW:one-source-of-truth] Redirect semantics match Python Rich's
+    // `Console.capture()`: while a capture is active the underlying target
+    // (file / stdout / stderr) receives nothing, and `endCapture()` returns
+    // the full text that would otherwise have been written. This is not a
+    // tee — callers wanting both must compose explicitly.
+    beginCapture() {
+        this._capture = "";
+    }
+    endCapture() {
+        const result = this._capture ?? "";
+        this._capture = null;
+        return result;
+    }
+    // --- Export (when record:true) ---
+    exportText({ clear = true } = {}) {
+        const text = this._recorded.map((s) => s.text).join("");
+        if (clear)
+            this._recorded = [];
+        return text;
+    }
+    // [LAW:single-enforcer] `encodeHtml` draws the picture `exportLines`
+    // resolves; nothing here interprets a `Style`.
+    exportHtml({ theme, clear = true } = {}) {
+        const html = encodeHtml(this._recorded, theme);
+        if (clear)
+            this._recorded = [];
+        return html;
+    }
+    // [LAW:single-enforcer] As `exportHtml`: `encodeSvg` draws, this clears.
+    exportSvg({ theme, title = "Rich", clear = true } = {}) {
+        const svg = encodeSvg(this._recorded, { theme, title, width: this.width });
+        if (clear)
+            this._recorded = [];
+        return svg;
+    }
+    // --- Internal ---
+    // [LAW:single-enforcer] One encode call per write batch routes through the
+    // same `segmentsToString` used by `renderToString`. Recording captures every
+    // non-control segment for replay.
+    _writeSegments(segments) {
+        if (this._record) {
+            for (const segment of segments) {
+                if (!segment.isControl)
+                    this._recorded.push(segment);
+            }
+        }
+        const encoded = segmentsToString(segments, this._destination);
+        if (encoded.length > 0)
+            this._write(encoded);
+    }
+    _write(text) {
+        // [LAW:types-are-the-program] `_capture !== null` is a discriminator
+        // narrow on `string | null`, not a sentinel comparison — the type
+        // carries the active/inactive state. The early return is what makes
+        // this a redirect (not a tee); see beginCapture for semantics.
+        if (this._capture !== null) {
+            this._capture += text;
+            return;
+        }
+        const target = this._file ?? defaultSink(this._stream);
+        target.write(this._liveRegion.around(text));
+    }
+}