@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/core/console.js

@@ -0,0 +1,527 @@
+/**
+ * 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 { resolveDestination } from "./color.js";
+import { encodeHtml } from "./export-html.js";
+import { RichText } from "./text.js";
+import { renderMarkup } from "./markup.js";
+import { Pretty } 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";
+// 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 {
+    items;
+    end;
+    constructor(items, end) {
+        this.items = items;
+        this.end = end;
+    }
+    *render(options) {
+        yield* this.text(options).render(options);
+        yield this.end;
+    }
+    measure(options) {
+        return this.text(options).measure(options);
+    }
+    // A `Pretty` lays itself out for the width it is offered, so the run is
+    // joined per call rather than once.
+    text(options) {
+        return this.items.reduce((joined, item) => joined.append(item instanceof Pretty ? item.toText(options) : item), new RichText("", { end: "" }));
+    }
+}
+// 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();
+/**
+ * What `print` bounds a data argument by when the caller said nothing.
+ *
+ * `print` formats whatever it is handed, so it is the one place that has to
+ * assume nothing about the value's size, in any of the three ways a value can
+ * be large. Unbounded, `print(buffer)` emits a line per byte,
+ * `print(deeplyNested)` descends until the stack gives out, and a single
+ * response body assigned to a field arrives in full — each of them a debug line
+ * that costs megabytes or hangs the terminal. All three bounds announce
+ * themselves in the output (`... +N`, `{...}`, `+N` after the closing quote),
+ * so this truncates visibly and never silently. [LAW:no-silent-failure]
+ *
+ * `maxString` reaches only strings nested inside data; a string argument is
+ * printed by the arm above, where the caller asked for that string by name.
+ *
+ * A caller constructing a `Pretty` has seen their data and gets no defaults;
+ * these belong to the convenience path, not to the formatter.
+ */
+const PRINT_DATA_BOUNDS = { maxLength: 100, maxDepth: 16, maxString: 1000 };
+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;
+    _style;
+    _isTerminal;
+    _forceInteractive;
+    _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;
+    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);
+        // [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);
+        this._forceInteractive = options?.forceInteractive;
+        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;
+    }
+    // --- 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() {
+        if (this._forceInteractive !== undefined)
+            return this._forceInteractive;
+        return this.isTerminal;
+    }
+    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,
+        };
+    }
+    // --- Print ---
+    print(...args) {
+        // 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;
+        }
+        const doMarkup = opts.markup ?? this._markup;
+        const doHighlight = opts.highlight ?? this._highlight;
+        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 data — 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. The one place the reference cuts
+        // differently is data: it gives a container lines of its own, and here all
+        // data is text. 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;
+            // it runs as a copy with its own `end` cleared, as a string's is, 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, 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) {
+                const richText = item.copy();
+                richText.end = "";
+                text = richText;
+            }
+            else if (isRenderable(item)) {
+                blocks.push({ kind: "lines", renderable: item });
+                continue;
+            }
+            else if (typeof item === "string") {
+                const richText = doMarkup ? renderMarkup(item) : new RichText(item);
+                richText.end = "";
+                if (doHighlight) {
+                    this._highlighter.highlight(richText);
+                }
+                text = richText;
+            }
+            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.
+                // Indent guides are styling too, and travel with the same decision —
+                // the console owns what `highlight` means for everything it emits,
+                // rather than `Pretty` inferring it back out of the highlighter.
+                text = new Pretty(item, {
+                    ...PRINT_DATA_BOUNDS,
+                    highlighter: doHighlight ? this._highlighter : NO_HIGHLIGHT,
+                    indentGuides: doHighlight,
+                });
+            }
+            const run = blocks.at(-1);
+            if (run?.kind === "text")
+                run.items.push(new RichText(sep, { end: "" }), 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 = {
+            ...this.options,
+            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 `Spinner` or `ProgressBar` does
+        // not (they're line fragments, meant to be composed within a line —
+        // rich-flexstrip-5kf.4cq), 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]
+        const output = [];
+        for (const block of blocks) {
+            const { lines, closed } = drawBlock(block);
+            lines.forEach((line, index) => {
+                output.push(...styleContent(line));
+                if (closed || index < lines.length - 1)
+                    output.push(Segment.line());
+            });
+        }
+        // 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.
+        // 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) ? this.width : Infinity;
+        this._writeSegments([...Segment.cropLines(output, cropWidth)]);
+    }
+    log(...args) {
+        // Simple log implementation — adds timestamp
+        const now = new Date();
+        const time = now.toLocaleTimeString();
+        const timeText = new RichText(`[${time}] `, { end: "" });
+        timeText.stylize("log.time");
+        this.print(timeText, ...args);
+    }
+    // [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 });
+    }
+    // --- 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;
+    }
+    // --- Internal ---
+    // [LAW:single-enforcer] One encode call per write batch routes through the
+    // same `segmentsToString` tree-coalescer used by `renderToString`. Adjacent
+    // same-style segments share one SGR open/close pair on the wire instead of
+    // one pair per segment. Recording captures every non-control segment for
+    // replay regardless of how the bytes coalesce.
+    _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(text);
+    }
+}

package/dist/core/emoji.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Emoji shortcode support — dictionary, replacement, and renderable.
+ */
+import { Segment } from "./segment.js";
+import type { Style } from "./style.js";
+import type { Renderable, RenderOptions } from "./protocol.js";
+export declare const EMOJI: Record<string, string>;
+/**
+ * Replaces :shortcode: patterns in text with emoji characters.
+ */
+export declare function emojiReplace(text: string, defaultVariant?: "emoji" | "text"): string;
+export declare class NoEmoji extends Error {
+    constructor(name: string);
+}
+export declare class Emoji implements Renderable {
+    readonly name: string;
+    private readonly _char;
+    private readonly _style;
+    private readonly _variant;
+    constructor(name: string, style?: Style, variant?: "emoji" | "text");
+    toString(): string;
+    render(_options: RenderOptions): Iterable<Segment>;
+    static replace(text: string): string;
+}