@promptctl/rich-js 0.17.0 → 0.18.0

package/dist/core/export-lines.js

@@ -1,141 +0,0 @@
-/**
- * export-lines — recorded segments resolved against a `TerminalTheme` into the
- * lines every exporter draws.
- *
- * The HTML and SVG exporters are two encodings of one picture, and this module
- * is the picture. What a styled cell *looks like* — which colour its glyph is,
- * whether its background is painted, which decorations it carries, where it
- * links — is decided here, once, and an exporter decides only how to write
- * that down. Before it existed the decision was made twice, by a CSS method
- * on `Style` and by a private converter on `Console`, and the two had already
- * disagreed: one honoured `underline2`, the other dropped it.
- *
- * [LAW:types-are-the-program] `ExportLook` has no `reverse`, `dim`, `conceal`
- * or default colour, because all four are consumed by `resolveLook` and turned
- * into plain RGB. An exporter holding a look cannot forget to swap a reversed
- * run or to fade a dim one: there is nothing left in its hands to forget. That
- * is the whole reason the representation is resolved rather than a `Style`
- * handed through.
- *
- * Runs rather than a cell grid. A grid gives a wide character a phantom
- * continuation cell every consumer must know to skip, and gives an HTML
- * exporter — which lays text out by flowing it — nothing it needs. A run's
- * column and cell width are `cellLen` of the text before it and of its own
- * text; they are not stored, so they cannot disagree with the text
- * [LAW:one-source-of-truth]. The SVG exporter, the one consumer that positions
- * anything, derives them.
- *
- * Browser-safe by construction: this imports `color`, `style`, `segment` and
- * nothing that touches the host, so `Console` can reach it from the main
- * barrel and the fs half of exporting stays in `src/node/save.ts`.
- */
-import { blendRgb, ColorSpec } from "./color.js";
-import { NULL_STYLE } from "./style.js";
-/**
- * The URL schemes an export will link.
- *
- * A terminal hands an OSC 8 target to the user's opener; an exported page hands
- * it to whoever loads the page, and exports are made to be published. A
- * `javascript:` target that was inert in a terminal is script in a README. The
- * list is an allowance, not a denylist, so a scheme nobody considered is
- * refused rather than trusted.
- */
-const LINKABLE_SCHEMES = new Set(["http:", "https:", "mailto:", "ftp:", "file:"]);
-/**
- * `Style.link` as a link an export may write, or `null` when it may not.
- *
- * A refused link loses only its target: the run keeps its text and every other
- * attribute, so nothing the terminal showed disappears from the export. The
- * canonical `URL.href` is what comes back, since the parse is what vouches for
- * it.
- */
-export function parseHref(link) {
-    if (!URL.canParse(link))
-        return null;
-    const url = new URL(link);
-    return LINKABLE_SCHEMES.has(url.protocol) ? url.href : null;
-}
-/**
- * How far a dim glyph moves toward its background — Rich's own factor, so an
- * export of the same program matches the library this ports.
- */
-const DIM_FADE = 0.4;
-const DEFAULT_COLOR = ColorSpec.default();
-/**
- * The ground every export is drawn on under `theme`.
- *
- * An exporter paints its page or window with this; `resolveLook` flattens
- * every run over the same `background`, so a run showing the canvas and the
- * page around it cannot come out different colours.
- */
-export function exportCanvas(theme) {
-    return {
-        background: DEFAULT_COLOR.getTruecolor(theme, false),
-        foreground: DEFAULT_COLOR.getTruecolor(theme, true),
-    };
-}
-/**
- * A `Style` as it appears on screen under `theme`.
- *
- * The order is the terminal's: colours resolve through the theme and lose
- * their alpha — paper over the canvas, ink over the paper, as `toSgrCodes`
- * flattens them — `reverse` swaps them, `dim` fades the glyph toward whatever
- * background it ended up on, and `conceal` finally paints the glyph in that
- * background. Every step after flattening works on opaque colour, so no
- * exporter ever draws a translucent one. Text under `conceal` is still
- * present, and still selectable, in both formats.
- *
- * The one difference from `toSgrCodes` is the substrate: a terminal cannot
- * know what lies under its cells and assumes black, while an export draws its
- * own canvas and flattens over that.
- *
- * `theme` omitted is `ColorSpec.getTruecolor`'s own fallback — black canvas,
- * white ink, the standard ANSI table. Choosing it there rather than naming a
- * preset here is what keeps `core/` from a third upward edge into `themes/`.
- */
-export function resolveLook(style, theme) {
-    const inkSpec = style.color ?? DEFAULT_COLOR;
-    const paperSpec = style.bgcolor ?? DEFAULT_COLOR;
-    const canvas = exportCanvas(theme).background;
-    // [LAW:single-enforcer] `flattenAlpha` is the one place alpha is composited.
-    const paper = paperSpec.flattenAlpha(canvas).getTruecolor(theme, false);
-    const ink = inkSpec.flattenAlpha(paper).getTruecolor(theme, true);
-    // A reversed run always paints: its background is the ink, which is never
-    // the canvas, even when the ink is the theme's default foreground.
-    const glyph = style.reverse ? paper : ink;
-    const ground = style.reverse ? ink : paper;
-    const background = style.reverse || !paperSpec.isDefault ? ground : "canvas";
-    const faded = style.dim ? blendRgb(glyph, ground, DIM_FADE) : glyph;
-    return {
-        foreground: style.conceal ? ground : faded,
-        background,
-        bold: style.bold === true,
-        italic: style.italic === true,
-        underline: style.underline2 ? "double" : style.underline ? "single" : "none",
-        strike: style.strike === true,
-        overline: style.overline === true,
-        blink: style.blink2 ? "fast" : style.blink ? "slow" : "none",
-        outline: style.encircle ? "encircle" : style.frame ? "frame" : "none",
-        href: style.link === undefined ? null : parseHref(style.link),
-    };
-}
-/**
- * Recorded segments as terminal rows under `theme`.
- *
- * `"\n"` ends a row, so output that ends with a newline — every `print` does —
- * has no empty row after it, and `"a\n\nb"` keeps its blank row. Callers pass
- * the recording buffer, which already holds no control segments.
- */
-export function exportLines(segments, theme) {
-    const rows = [[]];
-    for (const segment of segments) {
-        const look = resolveLook(segment.style ?? NULL_STYLE, theme);
-        segment.text.split("\n").forEach((piece, index) => {
-            if (index > 0)
-                rows.push([]);
-            if (piece.length > 0)
-                rows[rows.length - 1].push({ text: piece, look });
-        });
-    }
-    return rows[rows.length - 1].length === 0 ? rows.slice(0, -1) : rows;
-}

package/dist/core/highlighter.d.ts

@@ -1,33 +0,0 @@
-/**
- * Highlighters — apply styled spans to RichText based on pattern matching.
- */
-import { RichText } from "./text.js";
-export declare abstract class Highlighter {
-    abstract highlight(text: RichText): void;
-    call(input: string): RichText;
-}
-export declare class NullHighlighter extends Highlighter {
-    highlight(_text: RichText): void;
-}
-export declare class RegexHighlighter extends Highlighter {
-    static highlights: (string | RegExp)[];
-    /** Style applied to matches. When ending with "." it acts as a namespace
-     *  prefix: named groups become `baseStyle + groupName` (e.g. "repr." + "url"
-     *  → "repr.url"). Otherwise it's used as a literal style for all matches
-     *  (e.g. "bold red" applies "bold red" to every named group). */
-    static baseStyle: string;
-    highlight(text: RichText): void;
-}
-export declare class ReprHighlighter extends RegexHighlighter {
-    static baseStyle: string;
-    static highlights: RegExp[];
-}
-export declare class JSONHighlighter extends RegexHighlighter {
-    static baseStyle: string;
-    static highlights: string[];
-    highlight(text: RichText): void;
-}
-export declare class ISO8601Highlighter extends RegexHighlighter {
-    static baseStyle: string;
-    static highlights: RegExp[];
-}

package/dist/core/highlighter.js

@@ -1,124 +0,0 @@
-/**
- * Highlighters — apply styled spans to RichText based on pattern matching.
- */
-import { RichText } from "./text.js";
-// --- Base ---
-export class Highlighter {
-    call(input) {
-        const text = new RichText(input);
-        this.highlight(text);
-        return text;
-    }
-}
-// --- NullHighlighter ---
-export class NullHighlighter extends Highlighter {
-    highlight(_text) {
-        // No-op
-    }
-}
-// --- RegexHighlighter ---
-export class RegexHighlighter extends Highlighter {
-    static highlights = [];
-    /** Style applied to matches. When ending with "." it acts as a namespace
-     *  prefix: named groups become `baseStyle + groupName` (e.g. "repr." + "url"
-     *  → "repr.url"). Otherwise it's used as a literal style for all matches
-     *  (e.g. "bold red" applies "bold red" to every named group). */
-    static baseStyle = "";
-    highlight(text) {
-        const ctor = this.constructor;
-        const baseStyle = ctor.baseStyle;
-        // Namespace mode: "repr." + groupName → "repr.url"
-        // Literal mode: "bold red" → applied directly to every match
-        const isNamespace = baseStyle.endsWith(".");
-        for (const pattern of ctor.highlights) {
-            const re = pattern instanceof RegExp
-                ? new RegExp(pattern.source, pattern.flags.includes("g") ? pattern.flags : pattern.flags + "g")
-                : new RegExp(pattern, "g");
-            let match;
-            while ((match = re.exec(text.plain)) !== null) {
-                if (match[0].length === 0) {
-                    re.lastIndex++;
-                    continue;
-                }
-                if (match.groups) {
-                    let searchFrom = 0;
-                    for (const [groupName, groupValue] of Object.entries(match.groups)) {
-                        if (groupValue !== undefined) {
-                            const posInMatch = match[0].indexOf(groupValue, searchFrom);
-                            if (posInMatch >= 0) {
-                                const start = match.index + posInMatch;
-                                const style = isNamespace
-                                    ? `${baseStyle}${groupName}`
-                                    : baseStyle || groupName;
-                                text.stylize(style, start, start + groupValue.length);
-                                searchFrom = posInMatch + groupValue.length;
-                            }
-                        }
-                    }
-                }
-            }
-        }
-    }
-}
-// --- ReprHighlighter ---
-// [LAW:one-type-per-behavior] All repr patterns use the same RegexHighlighter mechanism
-export class ReprHighlighter extends RegexHighlighter {
-    static baseStyle = "repr.";
-    static highlights = [
-        // URLs
-        /(?<url>https?:\/\/[^\s<>"']+)/g,
-        // UUIDs
-        /(?<uuid>[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/gi,
-        // Quoted strings
-        /(?<str>'[^']*'|"[^"]*")/g,
-        // Booleans
-        /(?<bool>\btrue\b|\bfalse\b)/g,
-        // None/null/undefined
-        /(?<none>\bnull\b|\bundefined\b|\bNone\b)/g,
-        // Numbers (integers and floats)
-        /(?<number>(?<!\w)-?(?:0x[0-9a-f]+|\d+(?:\.\d+)?(?:e[+-]?\d+)?)(?!\w))/gi,
-    ];
-}
-// --- JSONHighlighter ---
-// A JSON string as Python Rich 9d8f9a3 matches one, `b` bytes prefix included:
-// an opening quote with no backslash or word character before it, through the
-// first quote with no backslash before it, so an escaped quote stays inside.
-const JSON_STR = String.raw `(?<![\\\w])(?<str>b?".*?(?<!\\)")`;
-export class JSONHighlighter extends RegexHighlighter {
-    static baseStyle = "json.";
-    // [LAW:dataflow-not-control-flow] One alternation, scanned once, as Rich's
-    // `_combine_regex` joins it. A token claims its characters where the scan
-    // meets it, so the `true` and `12` inside `"true 12"` belong to the string.
-    static highlights = [
-        [
-            String.raw `(?<brace>[\{\[\(\)\]\}])`,
-            String.raw `\b(?<bool_true>true)\b|\b(?<bool_false>false)\b|\b(?<null>null)\b`,
-            String.raw `(?<number>(?<!\w)\-?[0-9]+\.?[0-9]*(e[\-\+]?\d+?)?\b|0x[0-9a-fA-F]*)`,
-            JSON_STR,
-        ].join("|"),
-    ];
-    // A string followed by a colon is also a key. Its `json.key` span comes after
-    // its `json.str` span, so the key style lands on top. Each string is found on
-    // its own and then checked for a colon. One `string(?=:)` pattern would get
-    // this wrong: its lazy body can stretch past a value's closing quote to the
-    // next key's, marking `"b", "c"` in `{"a": "b", "c": 1}` as one key.
-    highlight(text) {
-        super.highlight(text);
-        const colon = /[ \n\r\t]*:/y;
-        for (const { index, 0: str } of text.plain.matchAll(new RegExp(JSON_STR, "g"))) {
-            const end = index + str.length;
-            colon.lastIndex = end;
-            if (colon.test(text.plain))
-                text.stylize("json.key", index, end);
-        }
-    }
-}
-// --- ISO8601Highlighter ---
-export class ISO8601Highlighter extends RegexHighlighter {
-    static baseStyle = "iso8601.";
-    static highlights = [
-        /(?<date>\d{4}-\d{2}-\d{2})/g,
-        /(?<time>\d{2}:\d{2}:\d{2}(?:\.\d+)?)/g,
-        /(?<timezone>[+-]\d{2}:\d{2}|Z)/g,
-    ];
-}

package/dist/core/json.d.ts

@@ -1,27 +0,0 @@
-/**
- * JSON — renders JSON data with syntax highlighting and pretty-printing.
- *
- * Lives in `core/` for the reason `pretty.ts` does, argued in its header: it
- * turns foreign input into `RichText`, composes no other renderable, and
- * imports core primitives only. `Console.printJson` delegates here, so this is
- * where the console can reach it without an upward edge. [LAW:one-way-deps]
- */
-import { Segment } from "./segment.js";
-import { RichText } from "./text.js";
-import type { Renderable, Measurable, RenderOptions } from "./protocol.js";
-export interface JSONOptions {
-    indent?: number;
-    sortKeys?: boolean;
-    highlight?: boolean;
-}
-export declare class JSONRenderable implements Renderable, Measurable {
-    readonly text: RichText;
-    private constructor();
-    static fromString(jsonString: string, options?: JSONOptions): JSONRenderable;
-    static fromData(data: unknown, options?: JSONOptions): JSONRenderable;
-    render(options: RenderOptions): Iterable<Segment>;
-    measure(options: RenderOptions): {
-        minimum: number;
-        maximum: number;
-    };
-}

package/dist/core/json.js

@@ -1,53 +0,0 @@
-/**
- * JSON — renders JSON data with syntax highlighting and pretty-printing.
- *
- * Lives in `core/` for the reason `pretty.ts` does, argued in its header: it
- * turns foreign input into `RichText`, composes no other renderable, and
- * imports core primitives only. `Console.printJson` delegates here, so this is
- * where the console can reach it without an upward edge. [LAW:one-way-deps]
- */
-import { RichText } from "./text.js";
-import { JSONHighlighter } from "./highlighter.js";
-const highlighter = new JSONHighlighter();
-export class JSONRenderable {
-    text;
-    constructor(text) {
-        this.text = text;
-    }
-    static fromString(jsonString, options) {
-        const indent = options?.indent ?? 2;
-        const sortKeys = options?.sortKeys ?? false;
-        // Parse and re-serialize for consistent formatting
-        const data = JSON.parse(jsonString);
-        return JSONRenderable.fromData(data, { ...options, indent, sortKeys });
-    }
-    static fromData(data, options) {
-        const indent = options?.indent ?? 2;
-        const sortKeys = options?.sortKeys ?? false;
-        const doHighlight = options?.highlight !== false;
-        const replacer = sortKeys
-            ? (_key, value) => {
-                if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-                    const sorted = {};
-                    for (const k of Object.keys(value).sort()) {
-                        sorted[k] = value[k];
-                    }
-                    return sorted;
-                }
-                return value;
-            }
-            : undefined;
-        const jsonStr = JSON.stringify(data, replacer, indent);
-        const text = new RichText(jsonStr, { end: "" });
-        if (doHighlight) {
-            highlighter.highlight(text);
-        }
-        return new JSONRenderable(text);
-    }
-    *render(options) {
-        yield* this.text.render(options);
-    }
-    measure(options) {
-        return this.text.measure(options);
-    }
-}

package/dist/core/markup.d.ts

@@ -1,97 +0,0 @@
-/**
- * Markup — BBCode-inspired markup parser for inline styling.
- * Parses `[bold red]text[/bold red]` into RichText with styled spans.
- *
- * Plugin tags ([LAW:locality-or-seam]): a `MarkupRegistry` lets consumers
- * register tag handlers without forking the parser. When the parser sees
- * `[name attrs...]inner[/name]` and `name` is registered, it parses attrs,
- * recursively renders the inner markup as a child Renderable, and calls the
- * handler — splicing the handler's returned Renderable into the output. The
- * built-in style dialect and the plugin dialect are routed by the registry,
- * which is the single trust boundary between them.
- *
- * Plugin pairs must nest. The built-in dialect admits non-strict nesting
- * (`[bold]a[italic]b[/bold]c[/italic]`) because a style is an annotation and
- * annotations may overlap freely; a plugin tag is a replacement whose handler
- * takes one contiguous `inner`, so an overlapping pair has no slice to hand it
- * and is rejected with a `MarkupSyntaxError`.
- */
-import { Style } from "./style.js";
-import { RichText } from "./text.js";
-export declare class Tag {
-    readonly name: string;
-    readonly parameters: string | undefined;
-    constructor(name: string, parameters?: string);
-    toString(): string;
-    get markup(): string;
-}
-export declare class MarkupError extends Error {
-    constructor(message: string);
-}
-/**
- * A markup string that cannot be parsed, with where it went wrong.
- *
- * [LAW:types-are-the-program] A subclass rather than optional fields on
- * `MarkupError`, because the parent is also what `MarkupRegistry.register`
- * throws, and a registration has no source text to point into. Every error this
- * class describes has a location, so none of its fields is optional and no
- * caller has to ask whether one is present — `instanceof` is the only question.
- *
- * [LAW:one-source-of-truth] The constructor takes the facts the parser holds —
- * the string, the offset of the offending tag, what was open — and derives
- * `line`, `column` and the message from them, so the numbers a caller reads
- * and the caret the message draws cannot disagree.
- */
-export declare class MarkupSyntaxError extends MarkupError {
-    /** The problem alone, with no location, for callers building their own message. */
-    readonly reason: string;
-    /** The whole markup string that failed, as the caller passed it. */
-    readonly markup: string;
-    /** Index into `markup` of the tag the parser rejected. */
-    readonly offset: number;
-    /** 1-based line of `offset`; lines are separated by `\n`. */
-    readonly line: number;
-    /** 1-based column of `offset` within its line, in UTF-16 code units. */
-    readonly column: number;
-    /**
-     * The opening tags still open at `offset`, outermost first, as written. For
-     * overlapping plugin tags, only plugin tags are named.
-     */
-    readonly openTags: readonly string[];
-    constructor(reason: string, markup: string, offset: number, openTags: readonly string[]);
-}
-/**
- * Escapes markup characters so they render as literal text.
- */
-export declare function escape(text: string): string;
-export interface MarkupTagContext {
-    /** Parsed `key=value` attributes from the opening tag. */
-    attrs: Record<string, string>;
-    /** Inner markup, already parsed (registry-aware) into a `RichText`. */
-    children: RichText;
-    /** Raw inner markup text (between the opening tag's `]` and the closing tag's `[`). */
-    raw: string;
-}
-export type MarkupTagHandler = (ctx: MarkupTagContext) => RichText;
-export declare class MarkupRegistry {
-    private readonly _handlers;
-    register(name: string, handler: MarkupTagHandler): void;
-    unregister(name: string): void;
-    has(name: string): boolean;
-    get(name: string): MarkupTagHandler | undefined;
-}
-export declare const globalMarkupRegistry: MarkupRegistry;
-export interface RenderMarkupOptions {
-    registry?: MarkupRegistry;
-    baseStyle?: string | Style;
-    emoji?: boolean;
-}
-/**
- * Plugin-aware markup render. Always returns a `RichText`. Built-in style
- * tags become spans; registered plugin tags are resolved by their handler,
- * whose returned `RichText` is appended (text + spans) into the output. The
- * recursion is over markup *slices* — between top-level plugin tag pairs and
- * inside each pair — and every recursion node returns a `RichText`, so the
- * append path is uniform.
- */
-export declare function renderMarkup(markup: string, options?: RenderMarkupOptions): RichText;