@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/core/console.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Console — the central orchestrator for rendering styled output to the terminal.
+ */
+import { Style, Theme } from "./style.js";
+import { ColorDepth } from "./color.js";
+import type { ColorSystemName, Destination } from "./color.js";
+import type { Env } from "./env.js";
+import type { TerminalTheme } from "./color.js";
+import { type JSONOptions } from "./json.js";
+import type { Highlighter } from "./highlighter.js";
+import { type RuleOptions } from "../renderables/rule.js";
+import type { Height, OverflowMethod, RenderOptions, StyleErrorHandler } from "./protocol.js";
+import type { Unsubscribe } from "./subscription.js";
+export interface ConsoleSink {
+    write(chunk: string | Uint8Array): unknown;
+}
+/**
+ * A frame standing on the terminal under the cursor — a running `Live` — that
+ * everything the console writes has to go above. `around` returns the bytes
+ * that take the frame off the terminal, write `text`, and paint the frame
+ * back under it; the console writes them in one piece.
+ */
+export interface LiveRegion {
+    around(text: string): string;
+}
+export interface ConsoleStream extends ConsoleSink {
+    readonly isTTY?: boolean;
+    readonly columns?: number;
+    readonly rows?: number;
+}
+/**
+ * The host facilities a `Console` consults: an environment map and the two
+ * standard streams. Node's `process` satisfies this shape as-is, which is the
+ * point — injecting a fake terminal needs no adapter at either end.
+ */
+export interface ConsoleEnvironment {
+    readonly env: Env;
+    readonly stdout?: ConsoleStream;
+    readonly stderr?: ConsoleStream;
+}
+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.
+     */
+    colorSystem?: ColorSystemName | ColorDepth | null;
+    /**
+     * Whether OSC 8 hyperlinks are emitted. Default: what the destination takes
+     * — true for an explicit `colorSystem`, detected under `"auto"` (no TTY or
+     * TERM=dumb: false). `false` with `colorSystem: null` writes plain text.
+     */
+    hyperlinks?: boolean;
+    /**
+     * The terminal can draw only ASCII: boxes, rules, tree guides and widget
+     * marks draw with ASCII characters instead of line-drawing glyphs. A
+     * property of the output device, so it is set here once and reaches every
+     * renderable this console draws. Default false.
+     */
+    asciiOnly?: boolean;
+    /**
+     * Static width (cells). Ignored when `getSize` is provided. Falls back to
+     * the `COLUMNS` env var / the bound stream's `columns` / 80.
+     */
+    width?: number;
+    /**
+     * Static height (lines). Ignored when `getSize` is provided. Falls back to
+     * the `LINES` env var / the bound stream's `rows` / 24.
+     */
+    height?: number;
+    /**
+     * Live size source. When provided, the console reads its width/height from
+     * this function on every access, overriding any static `width`/`height` and
+     * the bound stream's dimensions. Pass this when the output target's
+     * dimensions can change at runtime (e.g. xterm.js in a browser).
+     *
+     * [LAW:dataflow-not-control-flow] Live size is a function value the
+     * console reads, not a branch the call site has to install via
+     * `Object.defineProperty`.
+     */
+    getSize?: () => {
+        width: number;
+        height: number;
+    };
+    /**
+     * The clock `log` stamps each row from, read once per call. Default: the
+     * wall clock. Pass a fixed one to make logged output repeatable.
+     */
+    getDatetime?: () => Date;
+    style?: string | Style;
+    forceTerminal?: boolean;
+    forceInteractive?: boolean;
+    stderr?: boolean;
+    file?: ConsoleSink;
+    /**
+     * Host facilities to consult for colour 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.
+     */
+    environment?: ConsoleEnvironment;
+    record?: boolean;
+    markup?: boolean;
+    highlight?: boolean;
+    theme?: Theme;
+    highlighter?: Highlighter;
+    /**
+     * Called each time a render resolves a style string it cannot parse — a
+     * misspelled name, a key the theme lacks — and degrades it to unstyled.
+     * Calls are per resolution, not per distinct string: a style read twice, or
+     * redrawn by a refresh, is reported again. Throw from it to make rendering
+     * strict.
+     */
+    onStyleError?: StyleErrorHandler;
+}
+export interface PrintOptions {
+    style?: string | Style;
+    justify?: "default" | "left" | "center" | "right" | "full";
+    overflow?: OverflowMethod;
+    highlight?: boolean;
+    markup?: boolean;
+    softWrap?: boolean;
+    crop?: boolean;
+    end?: string;
+    sep?: string;
+}
+export declare class Console {
+    private readonly _destination;
+    private _getSize;
+    private readonly _getDatetime;
+    private _lastLogTime;
+    private _style;
+    private _isTerminal;
+    private readonly _interactive;
+    private _file;
+    private _stream;
+    private _record;
+    private _markup;
+    private _highlight;
+    private _theme;
+    private _onStyleError;
+    private readonly _asciiOnly;
+    private _highlighter;
+    private _recorded;
+    private _capture;
+    private _liveRegion;
+    constructor(options?: ConsoleOptions);
+    get size(): {
+        width: number;
+        height: number;
+    };
+    get width(): number;
+    get height(): number;
+    get isTerminal(): boolean;
+    get isInteractive(): boolean;
+    get colorSystem(): ColorDepth | null;
+    /**
+     * 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(): Destination;
+    get file(): ConsoleSink;
+    get theme(): Theme;
+    get options(): RenderOptions & {
+        height: Height;
+    };
+    print(...args: unknown[]): void;
+    private _draw;
+    log(...args: unknown[]): void;
+    rule(title?: string, options?: RuleOptions): void;
+    printJson(json: string | object, options?: JSONOptions): void;
+    /**
+     * 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: LiveRegion): Unsubscribe;
+    beginCapture(): void;
+    endCapture(): string;
+    exportText({ clear }?: {
+        clear?: boolean;
+    }): string;
+    exportHtml({ theme, clear }?: {
+        theme?: TerminalTheme;
+        clear?: boolean;
+    }): string;
+    exportSvg({ theme, title, clear }?: {
+        theme?: TerminalTheme;
+        title?: string;
+        clear?: boolean;
+    }): string;
+    private _writeSegments;
+    private _write;
+}