@promptctl/rich-js 0.10.0 → 0.11.0

package/dist/core/export-html.d.ts

@@ -0,0 +1,24 @@
+/**
+ * export-html — recorded segments drawn as a standalone HTML document.
+ *
+ * An encoding of `export-lines` and nothing more. What a run looks like under
+ * a theme is decided there; this module decides only how CSS says it. It never
+ * sees a `Style`, so it cannot disagree with the SVG exporter about what
+ * `reverse` or `dim` means — the two old converters that did disagree were
+ * deleted when this replaced them.
+ *
+ * The rows are already laid out at console width, so `pre` never re-wraps
+ * them: `white-space: pre`, and a scrollbar rather than a reflow when the page
+ * is narrower than the terminal was.
+ */
+import type { TerminalTheme } from "./color.js";
+import type { Segment } from "./segment.js";
+/**
+ * `segments` under `theme` as a complete HTML document.
+ *
+ * A browser draws no line for a newline at either edge of a `pre`: the parser
+ * drops the one straight after `<pre>`, and the one before `</pre>` ends a
+ * line without starting another. So the page opens with a newline of its own
+ * and every row ends with one, and a blank first or last row is still drawn.
+ */
+export declare function encodeHtml(segments: Iterable<Segment>, theme?: TerminalTheme): string;

package/dist/core/export-html.js

@@ -0,0 +1,106 @@
+/**
+ * export-html — recorded segments drawn as a standalone HTML document.
+ *
+ * An encoding of `export-lines` and nothing more. What a run looks like under
+ * a theme is decided there; this module decides only how CSS says it. It never
+ * sees a `Style`, so it cannot disagree with the SVG exporter about what
+ * `reverse` or `dim` means — the two old converters that did disagree were
+ * deleted when this replaced them.
+ *
+ * The rows are already laid out at console width, so `pre` never re-wraps
+ * them: `white-space: pre`, and a scrollbar rather than a reflow when the page
+ * is narrower than the terminal was.
+ */
+import { exportCanvas, exportLines } from "./export-lines.js";
+const ENTITIES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" };
+const escapeText = (text) => text.replace(/[&<>]/g, (c) => ENTITIES[c]);
+const escapeAttribute = (value) => value.replace(/[&"<>]/g, (c) => ENTITIES[c]);
+const BLINK_KEYFRAMES = "rich-blink";
+// [LAW:dataflow-not-control-flow] Each enum-valued field of a look is a table
+// from its values to the declarations it adds, so every value is spelled once
+// and `Record` makes a new value a compile error until it has a row.
+// A double underline adds no line to the glyph's own span; `runHtml` draws it.
+const UNDERLINE_LINE = {
+    none: [],
+    single: ["underline"],
+    double: [],
+};
+const BLINK = {
+    none: [],
+    slow: [`animation:${BLINK_KEYFRAMES} 1s step-end infinite`],
+    fast: [`animation:${BLINK_KEYFRAMES} 0.5s step-end infinite`],
+};
+const FRAME = "box-shadow:inset 0 0 0 1px currentColor";
+const OUTLINE = {
+    none: [],
+    frame: [FRAME],
+    encircle: [FRAME, "border-radius:0.5em"],
+};
+/**
+ * The glyph colour, and the background when one is painted.
+ *
+ * Dim arrives already blended into `foreground`. `opacity` is never written:
+ * it fades a painted background along with the glyph, which is the bug the
+ * blend exists to avoid.
+ */
+function paintCss(look) {
+    return [
+        `color:${look.foreground.hex}`,
+        ...(look.background === "canvas" ? [] : [`background-color:${look.background.hex}`]),
+    ];
+}
+/** What is drawn on the glyph: weight, slant, single-style lines, blink, outline. */
+function glyphCss(look) {
+    const lines = [
+        ...UNDERLINE_LINE[look.underline],
+        ...(look.strike ? ["line-through"] : []),
+        ...(look.overline ? ["overline"] : []),
+    ];
+    return [
+        ...(look.bold ? ["font-weight:bold"] : []),
+        ...(look.italic ? ["font-style:italic"] : []),
+        ...(lines.length === 0 ? [] : [`text-decoration-line:${lines.join(" ")}`]),
+        ...BLINK[look.blink],
+        ...OUTLINE[look.outline],
+    ];
+}
+const span = (css, content) => `<span style="${escapeAttribute(css.join(";"))}">${content}</span>`;
+/**
+ * One run as markup.
+ *
+ * An element has one `text-decoration-style`, so a double underline sharing a
+ * span with a strike would double the strike too. It gets an outer span of its
+ * own instead. That span carries the paint, because a descendant's background
+ * may be painted over an ancestor's underline, and the blink, so the underline
+ * blinks with the glyph.
+ */
+function runHtml({ text, look }) {
+    const glyph = escapeText(text);
+    const drawn = look.underline === "double"
+        ? span([...paintCss(look), "text-decoration-line:underline", "text-decoration-style:double", ...BLINK[look.blink]], span([`color:${look.foreground.hex}`, ...glyphCss(look)], glyph))
+        : span([...paintCss(look), ...glyphCss(look)], glyph);
+    return look.href === null ? drawn : `<a href="${escapeAttribute(look.href)}">${drawn}</a>`;
+}
+/**
+ * `segments` under `theme` as a complete HTML document.
+ *
+ * A browser draws no line for a newline at either edge of a `pre`: the parser
+ * drops the one straight after `<pre>`, and the one before `</pre>` ends a
+ * line without starting another. So the page opens with a newline of its own
+ * and every row ends with one, and a blank first or last row is still drawn.
+ */
+export function encodeHtml(segments, theme) {
+    const canvas = exportCanvas(theme);
+    const rows = exportLines(segments, theme).map((row) => `${row.map(runHtml).join("")}\n`);
+    const css = [
+        `body{background:${canvas.background.hex};color:${canvas.foreground.hex};padding:1em}`,
+        "pre{margin:0;font-family:monospace;white-space:pre;overflow-x:auto}",
+        "a{color:inherit;text-decoration:inherit}",
+        `@keyframes ${BLINK_KEYFRAMES}{50%{color:transparent}}`,
+    ].join("\n");
+    return [
+        "<!DOCTYPE html>",
+        `<html><head><meta charset="utf-8"><style>\n${css}\n</style></head>`,
+        `<body><pre>\n${rows.join("")}</pre></body></html>`,
+    ].join("\n");
+}

package/dist/core/export-lines.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 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 { type ColorRgba, type TerminalTheme } from "./color.js";
+import { type Style } from "./style.js";
+import type { Segment } from "./segment.js";
+declare const _href: unique symbol;
+/**
+ * A link target that is safe to write into a published document.
+ *
+ * [LAW:parse-dont-validate] Only `parseHref` produces one, so an exporter that
+ * writes an `href` attribute from an `Href` cannot have skipped the check.
+ */
+export type Href = string & {
+    readonly [_href]: true;
+};
+/**
+ * Where a run's background comes from. `"canvas"` is the theme background
+ * showing through — nothing painted — and is distinct from a painted colour
+ * that happens to equal it, because `on default` and `on #000000` are
+ * different requests even over a black theme.
+ */
+export type Background = ColorRgba | "canvas";
+/** Everything an exporter needs to draw one run, and nothing left to resolve. */
+export interface ExportLook {
+    readonly foreground: ColorRgba;
+    readonly background: Background;
+    readonly bold: boolean;
+    readonly italic: boolean;
+    readonly underline: "none" | "single" | "double";
+    readonly strike: boolean;
+    readonly overline: boolean;
+    readonly blink: "none" | "slow" | "fast";
+    readonly outline: "none" | "frame" | "encircle";
+    readonly href: Href | null;
+}
+export interface ExportRun {
+    readonly text: string;
+    readonly look: ExportLook;
+}
+/** One terminal row, left to right. An empty array is a blank row. */
+export type ExportLine = readonly ExportRun[];
+/**
+ * `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 declare function parseHref(link: string): Href | null;
+/** What an unstyled cell shows under a theme: the canvas, and ink on it. */
+export interface ExportCanvas {
+    readonly background: ColorRgba;
+    readonly foreground: ColorRgba;
+}
+/**
+ * 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 declare function exportCanvas(theme?: TerminalTheme): ExportCanvas;
+/**
+ * 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 declare function resolveLook(style: Style, theme?: TerminalTheme): ExportLook;
+/**
+ * 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 declare function exportLines(segments: Iterable<Segment>, theme?: TerminalTheme): ExportLine[];
+export {};

package/dist/core/export-lines.js

@@ -0,0 +1,141 @@
+/**
+ * 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

@@ -31,4 +31,3 @@ export declare class ISO8601Highlighter extends RegexHighlighter {
     static baseStyle: string;
     static highlights: RegExp[];
 }
-//# sourceMappingURL=highlighter.d.ts.map

package/dist/core/highlighter.js

@@ -122,4 +122,3 @@ export class ISO8601Highlighter extends RegexHighlighter {
         /(?<timezone>[+-]\d{2}:\d{2}|Z)/g,
     ];
 }
-//# sourceMappingURL=highlighter.js.map

package/dist/core/json.d.ts

@@ -25,4 +25,3 @@ export declare class JSONRenderable implements Renderable, Measurable {
         maximum: number;
     };
 }
-//# sourceMappingURL=json.d.ts.map

package/dist/core/json.js

@@ -51,4 +51,3 @@ export class JSONRenderable {
         return this.text.measure(options);
     }
 }
-//# sourceMappingURL=json.js.map

package/dist/core/markup.d.ts

@@ -14,7 +14,7 @@
  * (`[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 `MarkupError`.
+ * and is rejected with a `MarkupSyntaxError`.
  */
 import { Style } from "./style.js";
 import { RichText } from "./text.js";
@@ -28,6 +28,38 @@ export declare class Tag {
 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.
  */
@@ -63,4 +95,3 @@ export interface RenderMarkupOptions {
  * append path is uniform.
  */
 export declare function renderMarkup(markup: string, options?: RenderMarkupOptions): RichText;
-//# sourceMappingURL=markup.d.ts.map