@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/host/terminal-host.d.ts

@@ -0,0 +1,179 @@
+/**
+ * TerminalHost — the capability seam between the interactive runtime and its
+ * I/O environment.
+ *
+ * [LAW:locality-or-seam] The missing seam *was* the missing type. Before this
+ * type existed, Screen and EventRouter reached for ambient `process.stdin`/
+ * `process.stdout`, which crystallised them to node. With a `TerminalHost`
+ * value flowing across one boundary, the same runtime code runs against any
+ * implementation — node's TTY (`NodeTerminalHost`, on the `node/terminal-host`
+ * subpath) or a browser xterm.js terminal (`BrowserTerminalHost`, below).
+ *
+ * [LAW:dataflow-not-control-flow] The runtime never branches on "am I in
+ * node or browser." The host is the value that differs; the code path is
+ * the same. Variability lives in which host is constructed at the program
+ * entry, not in any `if` inside the runtime.
+ *
+ * [LAW:one-way-deps] The interface and the browser host live here, on the
+ * `host` subpath; the node host lives in `src/node/terminal-host.ts`, behind
+ * its own subpath, because it reads `process.stdin` / `process.stdout`. The
+ * dependency runs one way — the node adapter imports this seam; nothing here
+ * imports the adapter — so importing a browser-facing entry point cannot
+ * reach the ambient `process` global by any path, rather than merely not
+ * reaching it in practice. `test/seam/browser-safe.test.ts` is what holds
+ * that direction; who reads the host at all is `HOST_ACCESS` in
+ * `test/seam/ambient-process.ts`, and neither list is repeated here.
+ *
+ * [LAW:decomposition] This seam is not part of the interactive layer, which is
+ * why it is not in it. It sits below `src/widgets/` and imports nothing from
+ * it, so a program that wants to write bytes through a host — every non-
+ * interactive consumer — reaches one without loading the widget set or its
+ * `mobx` dependency.
+ *
+ * [boundaries: capabilities over context] A `TerminalHost` grants exactly
+ * the I/O capabilities the runtime needs: write bytes, read input, query
+ * size, observe resize, switch raw mode, read the terminal's environment,
+ * hear the program end, hand the terminal back for a while, lifecycle. It is
+ * not an omniscient handle to "the process."
+ */
+import type { Unsubscribe } from "../core/subscription.js";
+export interface TerminalSize {
+    readonly cols: number;
+    readonly rows: number;
+}
+export type DataHandler = (chunk: Uint8Array | string) => void;
+export type ResizeHandler = (size: TerminalSize) => void;
+export type ExitHandler = () => void;
+export interface TerminalHost {
+    /**
+     * Write raw bytes (or UTF-8 text) to the terminal as a program's output
+     * reaches it: no escape interpretation, no framing, and a terminal on a
+     * tty receives each newline as carriage return + newline, the tty's own
+     * output translation, which node's raw mode leaves on. A host with no tty
+     * in front of its terminal does that translation itself.
+     */
+    write(data: Uint8Array | string): void;
+    /**
+     * Subscribe to input data. The host emits whatever its underlying
+     * transport produces (Buffer on node, string on browser xterm.js); the
+     * runtime's parser accepts either.
+     */
+    onData(handler: DataHandler): Unsubscribe;
+    /**
+     * Subscribe to terminal resize events. The handler fires with the new
+     * size after a resize is observed.
+     */
+    onResize(handler: ResizeHandler): Unsubscribe;
+    /** Current terminal size in cells. Always returns a valid size. */
+    size(): TerminalSize;
+    /**
+     * Enable or disable raw mode on the input side. Implementations whose
+     * transport has no "cooked" mode (xterm.js, non-TTY pipes) silently
+     * no-op so callers don't need to branch on capability.
+     */
+    setRawMode(raw: boolean): void;
+    /**
+     * Whether the host is connected to a real interactive terminal — input and
+     * output both: what an interactive program checks before it starts.
+     */
+    readonly isTTY: boolean;
+    /**
+     * Whether the bytes `write` sends land on a terminal, whatever the input
+     * is. Colour detection asks this: a program with piped stdin and a terminal
+     * stdout still draws on a terminal, and `isTTY` would call it plain.
+     */
+    readonly writesToTerminal: boolean;
+    /**
+     * The environment a program running on this terminal sees — `TERM`,
+     * `COLORTERM`, `NO_COLOR` and the rest. Colour detection reads it: what a
+     * terminal can draw is a fact about the host, so it travels with the host
+     * rather than being read off whatever `process` the renderer happens to
+     * share a runtime with, which in a browser is none.
+     */
+    readonly env: NodeJS.ProcessEnv;
+    /**
+     * Run `handler` once, when the program ends by any path this host can
+     * observe, so whoever changed the terminal can hand it back. The program
+     * still ends as it would have without the handler: a signal still
+     * terminates and a crash is still reported.
+     */
+    onExit(handler: ExitHandler): Unsubscribe;
+    /**
+     * Hand the terminal to whatever launched the program, and resolve once it
+     * hands it back. Raw mode delivers Ctrl+Z as a key rather than a signal, so
+     * suspending is something a program asks for, and it restores the terminal
+     * before asking.
+     */
+    suspend(): Promise<void>;
+    /**
+     * Begin the host's lifecycle. Implementations attach whatever resources
+     * they own — or no-op when there is nothing to attach. Idempotent. See
+     * the concrete host's own JSDoc for what its `start()` actually does:
+     * `NodeTerminalHost` and `BrowserTerminalHost` both no-op because their
+     * underlying transports (process streams; a caller-managed xterm.js
+     * Terminal) are already live by the time the host is constructed.
+     */
+    start(): void;
+    /**
+     * Stop the host's lifecycle. Pairs with `start`. Idempotent. After
+     * `stop()`, the host releases its own subscriptions to the underlying
+     * transport and clears its handler sets; the transport itself is not
+     * torn down (that is the caller's concern — process streams persist;
+     * an xterm.js Terminal is disposed by the caller). Re-subscribing via
+     * `onData` / `onResize` after `stop()` re-engages the host.
+     */
+    stop(): void;
+}
+/**
+ * Subset of xterm.js's `Terminal` surface the browser host depends on.
+ *
+ * [LAW:locality-or-seam] Declaring the dependency by *shape* — rather than
+ * importing xterm.js's types — keeps this package free of an xterm.js
+ * dev-dep at the type level, lets the browser-bundle pipeline (downstream
+ * ticket) pin whichever xterm.js version it wants, and lets unit tests
+ * pass a hand-built fake: ask for exactly the capabilities the host uses,
+ * no more.
+ */
+export interface XtermDisposable {
+    dispose(): void;
+}
+export interface XtermResizeEvent {
+    cols: number;
+    rows: number;
+}
+export interface XtermTerminal {
+    readonly cols: number;
+    readonly rows: number;
+    write(data: Uint8Array | string): void;
+    onData(handler: (data: string) => void): XtermDisposable;
+    onResize(handler: (size: XtermResizeEvent) => void): XtermDisposable;
+}
+export interface BrowserTerminalHostOptions {
+    /**
+     * The xterm.js `Terminal` instance to wrap. The caller is responsible
+     * for its DOM lifecycle (`terminal.open(element)`, `terminal.dispose()`)
+     * — the host only owns its own subscriber lifecycle, exactly mirroring
+     * `NodeTerminalHost`'s relationship to `process.stdin`/`process.stdout`.
+     */
+    terminal: XtermTerminal;
+}
+export declare class BrowserTerminalHost implements TerminalHost {
+    private readonly terminal;
+    private readonly dataHandlers;
+    private readonly resizeHandlers;
+    private dataSubscription;
+    private resizeSubscription;
+    constructor(options: BrowserTerminalHostOptions);
+    get isTTY(): boolean;
+    get writesToTerminal(): boolean;
+    get env(): NodeJS.ProcessEnv;
+    write(data: Uint8Array | string): void;
+    size(): TerminalSize;
+    setRawMode(_raw: boolean): void;
+    onExit(_handler: ExitHandler): Unsubscribe;
+    suspend(): Promise<void>;
+    onData(handler: DataHandler): Unsubscribe;
+    onResize(handler: ResizeHandler): Unsubscribe;
+    start(): void;
+    stop(): void;
+}

package/dist/host/terminal-host.js

@@ -0,0 +1,186 @@
+/**
+ * TerminalHost — the capability seam between the interactive runtime and its
+ * I/O environment.
+ *
+ * [LAW:locality-or-seam] The missing seam *was* the missing type. Before this
+ * type existed, Screen and EventRouter reached for ambient `process.stdin`/
+ * `process.stdout`, which crystallised them to node. With a `TerminalHost`
+ * value flowing across one boundary, the same runtime code runs against any
+ * implementation — node's TTY (`NodeTerminalHost`, on the `node/terminal-host`
+ * subpath) or a browser xterm.js terminal (`BrowserTerminalHost`, below).
+ *
+ * [LAW:dataflow-not-control-flow] The runtime never branches on "am I in
+ * node or browser." The host is the value that differs; the code path is
+ * the same. Variability lives in which host is constructed at the program
+ * entry, not in any `if` inside the runtime.
+ *
+ * [LAW:one-way-deps] The interface and the browser host live here, on the
+ * `host` subpath; the node host lives in `src/node/terminal-host.ts`, behind
+ * its own subpath, because it reads `process.stdin` / `process.stdout`. The
+ * dependency runs one way — the node adapter imports this seam; nothing here
+ * imports the adapter — so importing a browser-facing entry point cannot
+ * reach the ambient `process` global by any path, rather than merely not
+ * reaching it in practice. `test/seam/browser-safe.test.ts` is what holds
+ * that direction; who reads the host at all is `HOST_ACCESS` in
+ * `test/seam/ambient-process.ts`, and neither list is repeated here.
+ *
+ * [LAW:decomposition] This seam is not part of the interactive layer, which is
+ * why it is not in it. It sits below `src/widgets/` and imports nothing from
+ * it, so a program that wants to write bytes through a host — every non-
+ * interactive consumer — reaches one without loading the widget set or its
+ * `mobx` dependency.
+ *
+ * [boundaries: capabilities over context] A `TerminalHost` grants exactly
+ * the I/O capabilities the runtime needs: write bytes, read input, query
+ * size, observe resize, switch raw mode, read the terminal's environment,
+ * hear the program end, hand the terminal back for a while, lifecycle. It is
+ * not an omniscient handle to "the process."
+ */
+const XTERM_ENV = Object.freeze({
+    TERM: "xterm-256color",
+    COLORTERM: "truecolor",
+});
+export class BrowserTerminalHost {
+    terminal;
+    dataHandlers = new Set();
+    resizeHandlers = new Set();
+    dataSubscription;
+    resizeSubscription;
+    constructor(options) {
+        this.terminal = options.terminal;
+    }
+    // [LAW:dataflow-not-control-flow] xterm.js is always an interactive
+    // terminal — there is no "non-TTY" code path in the browser. The
+    // runtime never branches on the value; this is the only sensible
+    // constant for this host.
+    get isTTY() {
+        return true;
+    }
+    get writesToTerminal() {
+        return true;
+    }
+    // What xterm.js is, stated the way a terminal states it: it identifies as
+    // `xterm-256color` and draws 24-bit SGR. With no env at all, detection saw
+    // an unnamed TTY and drew every colour at 16-colour depth.
+    get env() {
+        return XTERM_ENV;
+    }
+    // [LAW:single-enforcer] xterm.js is a terminal with no tty in front of
+    // it, so this host is where the tty's newline translation happens. Left to
+    // the terminal, a bare newline moves down without returning, and every row
+    // a Console writes starts where the last one ended — every demo drew as a
+    // staircase. Here and not in each page's xterm options, so every writer
+    // through this host gets it.
+    write(data) {
+        this.terminal.write(returnBeforeNewline(data));
+    }
+    size() {
+        return { cols: this.terminal.cols, rows: this.terminal.rows };
+    }
+    // [LAW:dataflow-not-control-flow] xterm.js delivers keystrokes raw
+    // unconditionally — there is no cooked mode to toggle. The no-op
+    // matches the TerminalHost contract's documented "silently no-op when
+    // the transport has no cooked mode," so callers stay uniform across
+    // hosts. (Mirror: NodeTerminalHost on a non-TTY stream takes the same
+    // no-op path via the optional-chain in `applyRawMode`.)
+    setRawMode(_raw) { }
+    // The page owns the terminal's life: a program here ends when the page
+    // does, and nothing is left to restore.
+    onExit(_handler) {
+        return () => { };
+    }
+    // Nothing launched the program that could take the terminal back, so the
+    // hand-back is immediate.
+    suspend() {
+        return Promise.resolve();
+    }
+    // [LAW:single-enforcer] One underlying `terminal.onData` subscription
+    // fans out to every host-level handler — the same lazy-attach,
+    // last-unsubscribe-detaches shape as NodeTerminalHost.onData. The
+    // runtime never sees the underlying subscription; it sees a single
+    // uniform `(handler) => Unsubscribe` API across hosts.
+    onData(handler) {
+        this.dataHandlers.add(handler);
+        if (!this.dataSubscription) {
+            this.dataSubscription = this.terminal.onData((chunk) => {
+                for (const h of this.dataHandlers)
+                    h(chunk);
+            });
+        }
+        return () => {
+            this.dataHandlers.delete(handler);
+            if (this.dataHandlers.size === 0 && this.dataSubscription) {
+                this.dataSubscription.dispose();
+                this.dataSubscription = undefined;
+            }
+        };
+    }
+    onResize(handler) {
+        this.resizeHandlers.add(handler);
+        if (!this.resizeSubscription) {
+            this.resizeSubscription = this.terminal.onResize((size) => {
+                const snapshot = { cols: size.cols, rows: size.rows };
+                for (const h of this.resizeHandlers)
+                    h(snapshot);
+            });
+        }
+        return () => {
+            this.resizeHandlers.delete(handler);
+            if (this.resizeHandlers.size === 0 && this.resizeSubscription) {
+                this.resizeSubscription.dispose();
+                this.resizeSubscription = undefined;
+            }
+        };
+    }
+    start() {
+        // [LAW:one-source-of-truth] The host does NOT own the terminal's DOM
+        // lifecycle (`terminal.open` / `terminal.dispose`). That is the
+        // caller's responsibility, exactly as NodeTerminalHost does not own
+        // `process.stdin`/`process.stdout`. start() is here so the runtime
+        // can call it uniformly across hosts; for this host there is
+        // nothing to do at this seam.
+    }
+    stop() {
+        // [LAW:one-source-of-truth] Symmetric teardown mirroring
+        // NodeTerminalHost.stop: drop every host-level subscriber and
+        // dispose the underlying terminal subscriptions. The terminal
+        // itself stays alive — re-subscribing via onData/onResize after
+        // stop() works, since the lazy-attach path re-creates the
+        // subscription on next subscribe. Calling stop() repeatedly is
+        // safe — the subscription guards make later calls no-ops.
+        if (this.dataSubscription) {
+            this.dataSubscription.dispose();
+            this.dataSubscription = undefined;
+        }
+        if (this.resizeSubscription) {
+            this.resizeSubscription.dispose();
+            this.resizeSubscription = undefined;
+        }
+        this.dataHandlers.clear();
+        this.resizeHandlers.clear();
+    }
+}
+/**
+ * `data` with a carriage return before every newline — the tty's ONLCR. A
+ * newline byte never occurs inside a multi-byte UTF-8 character, so the bytes
+ * are translated as bytes. A newline already preceded by a carriage return
+ * gains a second one, which returns to a column the cursor is already in, as
+ * the kernel's translation does.
+ */
+function returnBeforeNewline(data) {
+    if (typeof data === "string")
+        return data.replaceAll("\n", "\r\n");
+    let newlines = 0;
+    for (let i = 0; i < data.length; i++)
+        newlines += Number(data[i] === 0x0a);
+    if (newlines === 0)
+        return data;
+    const out = new Uint8Array(data.length + newlines);
+    let at = 0;
+    for (let i = 0; i < data.length; i++) {
+        if (data[i] === 0x0a)
+            out[at++] = 0x0d;
+        out[at++] = data[i];
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+export { cellLen, setCellSize, splitText, chopCells, cellFit, asCellCol, asCodePoint, } from "./core/cells.js";
+export type { CellCol, CodeUnit, CodePoint } from "./core/cells.js";
+export { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, parseRgbHex, parseRgbaHex, blendRgb, resolveColorSystem, detectColorSystem, resolveDestination, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
+export type { DetectColorOptions, Destination } from "./core/color.js";
+export { Oklch, IDENTITY, INVERT_LIGHTNESS, isIdentityKey, } from "./core/oklch.js";
+export type { ThemeKey, OklchWeights } from "./core/oklch.js";
+export { Palette } from "./themes/palette.js";
+export { resolveColorRef, parseHexColor, ColorRefError, HEX_COLOR_RE, } from "./themes/colorRef.js";
+export { buildPalette } from "./themes/buildPalette.js";
+export type { BaseColors } from "./themes/buildPalette.js";
+export { DEFAULT_TERMINAL_THEME, MONOKAI, SVG_EXPORT_THEME, NORD, GRUVBOX, DRACULA, TOKYO_NIGHT, FLEXOKI, CYBERPUNK, CATPPUCCIN_MOCHA, CATPPUCCIN_LATTE, CATPPUCCIN_FRAPPE, CATPPUCCIN_MACCHIATO, SOLARIZED_DARK, SOLARIZED_LIGHT, ROSE_PINE, ROSE_PINE_MOON, ROSE_PINE_DAWN, ATOM_ONE_DARK, ATOM_ONE_LIGHT, TEXTUAL_DARK, TEXTUAL_LIGHT, TEXTUAL_ANSI, } from "./themes/terminalThemes.js";
+export { getThemePalette, listThemePalettes } from "./themes/registry.js";
+export type { ThemeName } from "./themes/registry.js";
+export { transposePalette, themeKeyForRoot, isAnchored, ANCHORED_ROOTS, } from "./themes/transpose.js";
+export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureContrast, ensureDrawn, drawnColour, } from "./themes/colorMath.js";
+export { ColorRamp, RAMP_EASING_NAMES, parseRampEasing } from "./themes/ramp.js";
+export type { ColorStop, RampEasing } from "./themes/ramp.js";
+export { Style, StyleSyntaxError, StyleStack, Theme, NULL_STYLE, DEFAULT_STYLES, } from "./core/style.js";
+export type { StyleOptions } from "./core/style.js";
+export { Segment, ControlType, } from "./core/segment.js";
+export type { ControlCode } from "./core/segment.js";
+export type { Anchor } from "./core/anchor.js";
+export { Box } from "./core/box.js";
+export type { EdgeChars, ContentChars, RowLevel, SubstituteOptions } from "./core/box.js";
+export { ASCII, ASCII2, ASCII_DOUBLE_HEAD, SQUARE, SQUARE_DOUBLE_HEAD, MINIMAL, MINIMAL_HEAVY_HEAD, MINIMAL_DOUBLE_HEAD, SIMPLE, SIMPLE_HEAD, SIMPLE_HEAVY, HORIZONTALS, ROUNDED, HEAVY, HEAVY_EDGE, HEAVY_HEAD, DOUBLE, DOUBLE_EDGE, MARKDOWN, } from "./core/box.js";
+export { isRenderable, isMeasurable, withCellWidth, withBoundedWidth, insetHeight, stackedHeight, regionRows, fitHeight, getStyle, } from "./core/protocol.js";
+export type { RenderOptions, OverflowMethod, Height, Renderable, Measurable, StyleErrorHandler, } from "./core/protocol.js";
+export type { Unsubscribe } from "./core/subscription.js";
+export { Measurement, measureRenderables } from "./core/measure.js";
+export { Span, RichText } from "./core/text.js";
+export type { RichTextOptions } from "./core/text.js";
+export { Strip, PowerlineJoiner, SEAM_MIN_DELTA_E, POWERLINE_JOINER_GLYPHS, CapsuleJoiner, PlainJoiner, GradientJoiner, } from "./core/strip.js";
+export type { StyledRenderable, Joiner, PowerlineJoinerOptions, CapsuleJoinerOptions, PlainJoinerOptions, GradientJoinerOptions, } from "./core/strip.js";
+export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
+export type { RenderToStringOptions } from "./core/render.js";
+export { OSC8, osc8Sequences } from "./core/osc8.js";
+export type { Osc8Sequence } from "./core/osc8.js";
+export { AnsiDecoder, decodeAnsi } from "./core/ansi.js";
+export { MarkupRegistry, globalMarkupRegistry, renderMarkup, } from "./core/markup.js";
+export type { MarkupTagContext, MarkupTagHandler, RenderMarkupOptions, } from "./core/markup.js";
+export { EMOJI, emojiReplace, Emoji, NoEmoji } from "./core/emoji.js";
+export { MarkupError, MarkupSyntaxError, escape as escapeMarkup } from "./core/markup.js";
+export { Highlighter, NullHighlighter, RegexHighlighter, ReprHighlighter, JSONHighlighter, ISO8601Highlighter, } from "./core/highlighter.js";
+export { Pretty } from "./core/pretty.js";
+export type { PrettyOptions } from "./core/pretty.js";
+export { JSONRenderable } from "./core/json.js";
+export type { JSONOptions } from "./core/json.js";
+export { SPINNERS, DEFAULT_SPINNER } from "./core/spinnerData.js";
+export type { SpinnerData } from "./core/spinnerData.js";
+export { Console } from "./core/console.js";
+export type { ConsoleOptions, ConsoleSink, ConsoleStream, ConsoleEnvironment, PrintOptions, } from "./core/console.js";
+export { Constrain } from "./renderables/constrain.js";
+export { Align } from "./renderables/align.js";
+export type { Alignment } from "./core/place.js";
+export { Padding } from "./renderables/padding.js";
+export type { PaddingDimensions } from "./renderables/padding.js";
+export { Viewport, SCROLLBAR } from "./renderables/viewport.js";
+export type { Scrollbar, ScrollbarPart, ViewportOptions } from "./renderables/viewport.js";
+export { Rule } from "./renderables/rule.js";
+export type { RuleAlign, RuleOptions } from "./renderables/rule.js";
+export { Panel } from "./renderables/panel.js";
+export type { PanelOptions } from "./renderables/panel.js";
+export { Group } from "./renderables/group.js";
+export { ProgressBar } from "./renderables/progressBar.js";
+export type { ProgressBarOptions } from "./renderables/progressBar.js";
+export { Spinner } from "./renderables/spinner.js";
+export type { SpinnerOptions } from "./renderables/spinner.js";
+export { Table, Column } from "./renderables/table.js";
+export type { TableOptions, ColumnOptions } from "./renderables/table.js";
+export { Tree } from "./renderables/tree.js";
+export type { TreeOptions } from "./renderables/tree.js";
+export { Columns } from "./renderables/columns.js";
+export type { ColumnsOptions } from "./renderables/columns.js";
+export { FlexStrip } from "./renderables/flexStrip.js";
+export type { FlexStripOptions, FlexAlign } from "./renderables/flexStrip.js";
+export { Live } from "./renderables/live.js";
+export type { LiveOptions } from "./renderables/live.js";
+export { Status } from "./renderables/status.js";
+export type { StatusOptions } from "./renderables/status.js";
+export { Progress, TextColumn, BarColumn, TaskProgressColumn, TimeRemainingColumn, TimeElapsedColumn, SpinnerColumn, MofNCompleteColumn, track, } from "./renderables/progress.js";
+export type { ProgressOptions, TaskOptions, TaskUpdateOptions } from "./renderables/progress.js";
+export { Prompt, IntPrompt, FloatPrompt, Confirm } from "./renderables/prompt.js";
+export type { PromptInput, PromptOptions } from "./renderables/prompt.js";
+export { Traceback } from "./renderables/traceback.js";
+export type { TracebackOptions } from "./renderables/traceback.js";
+export { Syntax } from "./renderables/syntax.js";
+export type { SyntaxOptions } from "./renderables/syntax.js";
+export { Markdown } from "./renderables/markdown.js";
+export type { MarkdownOptions } from "./renderables/markdown.js";
+export { Layout } from "./renderables/layout.js";
+export type { LayoutOptions } from "./renderables/layout.js";

package/dist/index.js

@@ -0,0 +1,107 @@
+// Core primitives
+export { cellLen, setCellSize, splitText, chopCells, cellFit, asCellCol, asCodePoint, } from "./core/cells.js";
+export { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, parseRgbHex, parseRgbaHex, blendRgb, resolveColorSystem, detectColorSystem, resolveDestination, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
+// Perceptually-uniform color space (manipulation, transposition).
+export { Oklch, IDENTITY, INVERT_LIGHTNESS, isIdentityKey, } from "./core/oklch.js";
+// Themes — semantic palettes (distinct from ColorTable quantization LUTs)
+export { Palette } from "./themes/palette.js";
+// The one checkpoint turning an author-written colour string — a palette
+// variable name or a `#RRGGBB` literal — into a colour. [LAW:parse-dont-validate]
+export { resolveColorRef, parseHexColor, ColorRefError, HEX_COLOR_RE, } from "./themes/colorRef.js";
+export { buildPalette } from "./themes/buildPalette.js";
+export { DEFAULT_TERMINAL_THEME, MONOKAI, SVG_EXPORT_THEME, NORD, GRUVBOX, DRACULA, TOKYO_NIGHT, FLEXOKI, CYBERPUNK, CATPPUCCIN_MOCHA, CATPPUCCIN_LATTE, CATPPUCCIN_FRAPPE, CATPPUCCIN_MACCHIATO, SOLARIZED_DARK, SOLARIZED_LIGHT, ROSE_PINE, ROSE_PINE_MOON, ROSE_PINE_DAWN, ATOM_ONE_DARK, ATOM_ONE_LIGHT, TEXTUAL_DARK, TEXTUAL_LIGHT, TEXTUAL_ANSI, } from "./themes/terminalThemes.js";
+export { getThemePalette, listThemePalettes } from "./themes/registry.js";
+export { transposePalette, themeKeyForRoot, isAnchored, ANCHORED_ROOTS, } from "./themes/transpose.js";
+// WCAG contrast toolkit — accessibility-aware color for styled output.
+// `ensureContrast` keeps a color's hue and only slides its OKLCH lightness to
+// meet the ratio, so themed text stays themed; `contrastFor` picks black/white
+// from scratch when there is no color to preserve.
+// `lighten`/`darken` slide a color's HSL lightness by whole "levels" (each
+// level ≈ 10%), returning a new ColorRgba — the relative transform a consumer
+// reaches for to tint a resolved color against itself (e.g. a focused-while-open
+// menu cell lightening its inherited background) without re-deriving from a
+// palette name. Negative levels invert (lighten(c,-n) === darken(c,n)).
+export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureContrast, ensureDrawn, drawnColour, } from "./themes/colorMath.js";
+// A number → a color through ordered stops, interpolated in OKLCH — the one
+// color operation whose input is a measurement rather than a color, so a
+// gradient (or, with the `step` easing, a threshold cascade) stays inside the
+// theme system instead of being computed beside it.
+export { ColorRamp, RAMP_EASING_NAMES, parseRampEasing } from "./themes/ramp.js";
+export { Style, StyleSyntaxError, StyleStack, Theme, NULL_STYLE, DEFAULT_STYLES, } from "./core/style.js";
+export { Segment, ControlType, } from "./core/segment.js";
+export { Box } from "./core/box.js";
+export { ASCII, ASCII2, ASCII_DOUBLE_HEAD, SQUARE, SQUARE_DOUBLE_HEAD, MINIMAL, MINIMAL_HEAVY_HEAD, MINIMAL_DOUBLE_HEAD, SIMPLE, SIMPLE_HEAD, SIMPLE_HEAVY, HORIZONTALS, ROUNDED, HEAVY, HEAVY_EDGE, HEAVY_HEAD, DOUBLE, DOUBLE_EDGE, MARKDOWN, } from "./core/box.js";
+// Protocol
+export { isRenderable, isMeasurable, withCellWidth, withBoundedWidth, insetHeight, stackedHeight, regionRows, fitHeight, getStyle, } from "./core/protocol.js";
+// Measurement
+export { Measurement, measureRenderables } from "./core/measure.js";
+// Text
+export { Span, RichText } from "./core/text.js";
+// Strip + Joiner
+export { Strip, PowerlineJoiner, SEAM_MIN_DELTA_E, POWERLINE_JOINER_GLYPHS, CapsuleJoiner, PlainJoiner, GradientJoiner, } from "./core/strip.js";
+// renderToString — stateless one-shot emission
+export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
+// OSC 8 hyperlink wire grammar — for consumers that read rendered bytes back
+export { OSC8, osc8Sequences } from "./core/osc8.js";
+// ANSI bytes back into styled text
+export { AnsiDecoder, decodeAnsi } from "./core/ansi.js";
+// Markup plugin tags
+export { MarkupRegistry, globalMarkupRegistry, renderMarkup, } from "./core/markup.js";
+// Emoji
+export { EMOJI, emojiReplace, Emoji, NoEmoji } from "./core/emoji.js";
+// Markup
+export { MarkupError, MarkupSyntaxError, escape as escapeMarkup } from "./core/markup.js";
+// Highlighter
+export { Highlighter, NullHighlighter, RegexHighlighter, ReprHighlighter, JSONHighlighter, ISO8601Highlighter, } from "./core/highlighter.js";
+// Pretty
+export { Pretty } from "./core/pretty.js";
+// JSON
+export { JSONRenderable } from "./core/json.js";
+// Spinner data
+export { SPINNERS, DEFAULT_SPINNER } from "./core/spinnerData.js";
+// Console
+export { Console } from "./core/console.js";
+// Renderables
+export { Constrain } from "./renderables/constrain.js";
+export { Align } from "./renderables/align.js";
+export { Padding } from "./renderables/padding.js";
+export { Viewport, SCROLLBAR } from "./renderables/viewport.js";
+export { Rule } from "./renderables/rule.js";
+export { Panel } from "./renderables/panel.js";
+export { Group } from "./renderables/group.js";
+export { ProgressBar } from "./renderables/progressBar.js";
+export { Spinner } from "./renderables/spinner.js";
+export { Table, Column } from "./renderables/table.js";
+export { Tree } from "./renderables/tree.js";
+export { Columns } from "./renderables/columns.js";
+export { FlexStrip } from "./renderables/flexStrip.js";
+export { Live } from "./renderables/live.js";
+export { Status } from "./renderables/status.js";
+export { Progress, TextColumn, BarColumn, TaskProgressColumn, TimeRemainingColumn, TimeElapsedColumn, SpinnerColumn, MofNCompleteColumn, track, } from "./renderables/progress.js";
+export { Prompt, IntPrompt, FloatPrompt, Confirm } from "./renderables/prompt.js";
+export { Traceback } from "./renderables/traceback.js";
+export { Syntax } from "./renderables/syntax.js";
+export { Markdown } from "./renderables/markdown.js";
+export { Layout } from "./renderables/layout.js";
+// The barrel stops at `renderables/`, and the two subsystems above it are reached
+// through their own `package.json#exports` subpaths instead:
+//
+//   `@promptctl/rich-js/widgets`            — the interactive layer  (pulls in `mobx`)
+//   `@promptctl/rich-js/template-bindings`  — the styling vocabulary (pulls in
+//                                             `@promptctl/go-template-js`)
+//
+// `@promptctl/rich-js/host` is a third subpath but a different kind of thing: the
+// terminal seam has no third-party dependency at all, and sits on its own subpath
+// because it is what a *non*-interactive program reaches for. Folding it into either
+// neighbour is what the split was undoing — inside `widgets/` it charged mobx to
+// consumers who only wanted to write bytes; in this barrel it would put an I/O
+// capability in front of consumers who never touch a terminal directly.
+//
+// `export … from` is a static edge, so anything named here is *evaluated* by every
+// consumer, including one that only wanted a Table. Re-exporting the two subsystems
+// therefore charged their dependencies to the whole package — mobx and, transitively,
+// @noble/hashes. The subpaths make that cost something a consumer opts into, the same
+// bargain `src/node/` strikes for Node built-ins.
+//
+// This is also why there is no widget list here to keep in sync: `src/widgets/index.ts`
+// is that list, and a copy of it in this file would be a second one to drift from.

package/dist/node/prompt.d.ts

@@ -0,0 +1,21 @@
+/**
+ * node:prompt — readline-backed `PromptInput` for use with the prompt
+ * renderable in a Node runtime.
+ *
+ * [LAW:locality-or-seam] `node:readline` lives only here, on the node side
+ * of the API boundary. The main barrel stays browser-safe; consumers that
+ * want interactive prompts in Node opt in by importing `nodeAsk` and
+ * passing it as the input capability:
+ *
+ *     import { Prompt } from "@promptctl/rich-js";
+ *     import { nodeAsk } from "@promptctl/rich-js/node/prompt";
+ *     const answer = await Prompt.ask("What's your name?", nodeAsk);
+ *     // or with options:
+ *     const choice = await Prompt.ask("Pick one", nodeAsk, { choices: ["a", "b"] });
+ *
+ * [LAW:single-enforcer] One readline interface per `nodeAsk` call —
+ * created, asked, closed. No shared `rl` across prompts, no listener-leak
+ * pitfalls when callers stack prompts in a loop.
+ */
+import type { PromptInput } from "../renderables/prompt.js";
+export declare const nodeAsk: PromptInput;

package/dist/node/prompt.js

@@ -0,0 +1,30 @@
+/**
+ * node:prompt — readline-backed `PromptInput` for use with the prompt
+ * renderable in a Node runtime.
+ *
+ * [LAW:locality-or-seam] `node:readline` lives only here, on the node side
+ * of the API boundary. The main barrel stays browser-safe; consumers that
+ * want interactive prompts in Node opt in by importing `nodeAsk` and
+ * passing it as the input capability:
+ *
+ *     import { Prompt } from "@promptctl/rich-js";
+ *     import { nodeAsk } from "@promptctl/rich-js/node/prompt";
+ *     const answer = await Prompt.ask("What's your name?", nodeAsk);
+ *     // or with options:
+ *     const choice = await Prompt.ask("Pick one", nodeAsk, { choices: ["a", "b"] });
+ *
+ * [LAW:single-enforcer] One readline interface per `nodeAsk` call —
+ * created, asked, closed. No shared `rl` across prompts, no listener-leak
+ * pitfalls when callers stack prompts in a loop.
+ */
+import * as readline from "node:readline";
+export const nodeAsk = (prompt) => new Promise((resolve) => {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    rl.question(prompt, (answer) => {
+        rl.close();
+        resolve(answer);
+    });
+});

package/dist/node/save.d.ts

@@ -0,0 +1,17 @@
+/**
+ * node:save — node-only file helpers that persist recorded console output.
+ *
+ * [LAW:locality-or-seam] These functions live outside the main barrel so
+ * Console can stop importing `fs`. Importing `Console` itself stays
+ * browser-safe; importing this module is the explicit opt-in for the
+ * fs-backed surface, and bundlers targeting the browser will (correctly)
+ * refuse to resolve `fs` if a consumer ever pulls it in by accident.
+ *
+ * [LAW:single-enforcer] One funnel per format: `saveText` consumes
+ * `Console.exportText()` and `saveHtml` consumes `Console.exportHtml()`.
+ * The encoding and recording logic stays on Console; this file is purely
+ * the IO sink.
+ */
+import type { Console } from "../core/console.js";
+export declare function saveText(out: Console, path: string, options?: Parameters<Console["exportText"]>[0]): void;
+export declare function saveHtml(out: Console, path: string, options?: Parameters<Console["exportHtml"]>[0]): void;

package/dist/node/save.js

@@ -0,0 +1,21 @@
+/**
+ * node:save — node-only file helpers that persist recorded console output.
+ *
+ * [LAW:locality-or-seam] These functions live outside the main barrel so
+ * Console can stop importing `fs`. Importing `Console` itself stays
+ * browser-safe; importing this module is the explicit opt-in for the
+ * fs-backed surface, and bundlers targeting the browser will (correctly)
+ * refuse to resolve `fs` if a consumer ever pulls it in by accident.
+ *
+ * [LAW:single-enforcer] One funnel per format: `saveText` consumes
+ * `Console.exportText()` and `saveHtml` consumes `Console.exportHtml()`.
+ * The encoding and recording logic stays on Console; this file is purely
+ * the IO sink.
+ */
+import { writeFileSync } from "node:fs";
+export function saveText(out, path, options) {
+    writeFileSync(path, out.exportText(options), "utf-8");
+}
+export function saveHtml(out, path, options) {
+    writeFileSync(path, out.exportHtml(options), "utf-8");
+}