@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/core/env.js

@@ -0,0 +1,16 @@
+/**
+ * Env — the environment variables a program running on a terminal sees, as
+ * every public type that carries them names it.
+ *
+ * [LAW:types-are-the-program] The strongest true theorem about what this
+ * library does with an environment is "reads a variable by name, which may be
+ * unset." It never writes one, and it never touches the rest of node's
+ * `NodeJS.ProcessEnv`. Node's `process.env` satisfies this as-is, and so does
+ * a frozen literal in a browser, where there is no `process` at all.
+ *
+ * It lives here rather than being spelled `NodeJS.ProcessEnv` because a public
+ * signature is emitted into the `.d.ts` verbatim, and a TypeScript project
+ * without `@types/node` — the ordinary browser project — cannot resolve the
+ * `NodeJS` namespace. `test/seam/browser-types.test.ts` holds that line.
+ */
+export {};

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

@@ -0,0 +1,59 @@
+/**
+ * export-html — recorded segments drawn as HTML: a fragment that can sit in
+ * a page this library does not own, and a standalone document around it.
+ *
+ * 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";
+/**
+ * The CSS a page includes once, wherever fragments appear: what an inline
+ * style cannot say. A fragment that blinks draws steadily without it.
+ *
+ * The keyframes exist only for a reader who has not asked for reduced motion,
+ * so for one who has, the inline `animation` names nothing and the glyph holds
+ * still. One rule, so no second rule's order or survival in a host's CSS
+ * pipeline can bring the blink back.
+ */
+export declare const HTML_FRAGMENT_CSS = "@media (prefers-reduced-motion:no-preference){@keyframes rich-blink{50%{color:transparent}}}";
+/**
+ * `segments` under `theme` as one `pre` carrying its canvas, for embedding.
+ *
+ * [LAW:locality-or-seam] Every rule is inline on the `pre` or below it, so the
+ * fragment styles nothing outside itself; the host page keeps its own `body`,
+ * `pre` and `a` rules. The seam holds the other way too: `all:initial` stops
+ * the host's `pre` rules and inherited typography from reaching the rows, and
+ * the two properties `all` does not cover pin the rows left to right.
+ *
+ * The one way in is the `--rich-fragment-font` custom property, read as the
+ * `font` shorthand (`14px/1.3 "JetBrains Mono", monospace`). `all` resets no
+ * custom property, so a host sets it on any ancestor to draw the rows in its
+ * own code font; unset, the rows are the browser's default monospace at a
+ * fixed line height, as a terminal's rows are. A host's value wants one too: at
+ * `normal`, a row holding a glyph from a taller fallback font grows and shifts
+ * every row below it. It must be a whole shorthand, a size and a family at
+ * least: any other value is invalid when computed, and the rows then inherit
+ * the host's font.
+ *
+ * A browser draws no line for a newline at either edge of a `pre`: the parser
+ * drops the one straight after the open tag, and the one before `</pre>` ends a
+ * line without starting another. So the fragment 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 encodeHtmlFragment(segments: Iterable<Segment>, theme?: TerminalTheme): string;
+/**
+ * `segments` under `theme` as a complete HTML document.
+ *
+ * [LAW:one-source-of-truth] The document is the fragment in a shell, so the
+ * two cannot draw different pictures. The shell paints the page around the
+ * `pre` in the same canvas and includes the fragment CSS once.
+ */
+export declare function encodeHtml(segments: Iterable<Segment>, theme?: TerminalTheme): string;

package/dist/core/export-html.js

@@ -0,0 +1,197 @@
+/**
+ * export-html — recorded segments drawn as HTML: a fragment that can sit in
+ * a page this library does not own, and a standalone document around it.
+ *
+ * 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 { cellLen, graphemes } from "./cells.js";
+import { escapeAttribute, escapeText, exportCanvas, exportLines, } from "./export-lines.js";
+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],
+    ];
+}
+// `unset` hands the anchor the run's look and drops the host's `a` rules;
+// `revert` gives back the browser's link cursor and focus ring.
+const ANCHOR_CSS = "all:unset;cursor:revert;outline:revert";
+const span = (css, content) => `<span style="${escapeAttribute(css.join(";"))}">${content}</span>`;
+/** Text of printable ASCII only: one cell a character, nothing to box. */
+const ONE_CELL = /^[\x20-\x7e]*$/;
+/**
+ * A box exactly `cells` of the monospace font wide (`ch` is one of its cells)
+ * for glyphs the browser would otherwise draw at a fallback font's width,
+ * which for a CJK character is rarely two cells: left to it, everything after
+ * them on the row shifts off its column. The box carries no paint, so the
+ * run's background runs through it at the run's own height; an atomic inline
+ * takes no decoration from its ancestors, so it inherits its parent's lines.
+ */
+const cellBox = (cells) => ["display:inline-block", `width:${cells}ch`, "text-align:center", "text-decoration:inherit"];
+/**
+ * `text` with each stretch of graphemes wider than one cell in one box as wide
+ * as their cells together, and `draw` applied to every stretch of escaped text
+ * inside and between the boxes. A stretch, not a glyph apiece, because a
+ * browser's find-in-page does not match across two boxes. Graphemes, not code
+ * points, because `cellLen` measures a joined emoji as one glyph; a zero-width
+ * one joins the stretch before it, so it can still combine.
+ */
+function onGrid(text, draw) {
+    if (ONE_CELL.test(text))
+        return draw(escapeText(text));
+    const pieces = [];
+    let stretch = "";
+    let wideCells = 0;
+    const flush = () => {
+        if (stretch !== "")
+            pieces.push(wideCells === 0 ? draw(escapeText(stretch)) : span(cellBox(wideCells), draw(escapeText(stretch))));
+        stretch = "";
+        wideCells = 0;
+    };
+    for (const segment of graphemes(text)) {
+        const cells = cellLen(segment);
+        const wide = cells === 0 ? wideCells > 0 : cells > 1;
+        if (wide !== (wideCells > 0))
+            flush();
+        stretch += segment;
+        if (wide)
+            wideCells += cells;
+    }
+    flush();
+    return pieces.join("");
+}
+/**
+ * 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. A wide glyph's box sits between the two: it inherits
+ * the double underline, and the inner span inside it draws the other lines.
+ */
+function runHtml({ text, look }) {
+    const drawn = look.underline === "double"
+        ? span([...paintCss(look), "text-decoration-line:underline", "text-decoration-style:double", ...BLINK[look.blink]], onGrid(text, (glyph) => span([`color:${look.foreground.hex}`, ...glyphCss(look)], glyph)))
+        : span([...paintCss(look), ...glyphCss(look)], onGrid(text, (glyph) => glyph));
+    return look.href === null
+        ? drawn
+        : `<a href="${escapeAttribute(look.href)}" style="${ANCHOR_CSS}">${drawn}</a>`;
+}
+/**
+ * The CSS a page includes once, wherever fragments appear: what an inline
+ * style cannot say. A fragment that blinks draws steadily without it.
+ *
+ * The keyframes exist only for a reader who has not asked for reduced motion,
+ * so for one who has, the inline `animation` names nothing and the glyph holds
+ * still. One rule, so no second rule's order or survival in a host's CSS
+ * pipeline can bring the blink back.
+ */
+export const HTML_FRAGMENT_CSS = `@media (prefers-reduced-motion:no-preference){@keyframes ${BLINK_KEYFRAMES}{50%{color:transparent}}}`;
+/**
+ * `segments` under `theme` as one `pre` carrying its canvas, for embedding.
+ *
+ * [LAW:locality-or-seam] Every rule is inline on the `pre` or below it, so the
+ * fragment styles nothing outside itself; the host page keeps its own `body`,
+ * `pre` and `a` rules. The seam holds the other way too: `all:initial` stops
+ * the host's `pre` rules and inherited typography from reaching the rows, and
+ * the two properties `all` does not cover pin the rows left to right.
+ *
+ * The one way in is the `--rich-fragment-font` custom property, read as the
+ * `font` shorthand (`14px/1.3 "JetBrains Mono", monospace`). `all` resets no
+ * custom property, so a host sets it on any ancestor to draw the rows in its
+ * own code font; unset, the rows are the browser's default monospace at a
+ * fixed line height, as a terminal's rows are. A host's value wants one too: at
+ * `normal`, a row holding a glyph from a taller fallback font grows and shifts
+ * every row below it. It must be a whole shorthand, a size and a family at
+ * least: any other value is invalid when computed, and the rows then inherit
+ * the host's font.
+ *
+ * A browser draws no line for a newline at either edge of a `pre`: the parser
+ * drops the one straight after the open tag, and the one before `</pre>` ends a
+ * line without starting another. So the fragment 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 encodeHtmlFragment(segments, theme) {
+    const canvas = exportCanvas(theme);
+    const rows = exportLines(segments, theme).map((row) => `${row.map(runHtml).join("")}\n`);
+    const css = [
+        "all:initial",
+        "direction:ltr",
+        "unicode-bidi:isolate",
+        "display:block",
+        `background:${canvas.background.hex}`,
+        `color:${canvas.foreground.hex}`,
+        "padding:1em",
+        "font:var(--rich-fragment-font,medium/1.2 monospace)",
+        "white-space:pre",
+        "overflow-x:auto",
+    ].join(";");
+    return `<pre style="${css}">\n${rows.join("")}</pre>`;
+}
+/**
+ * `segments` under `theme` as a complete HTML document.
+ *
+ * [LAW:one-source-of-truth] The document is the fragment in a shell, so the
+ * two cannot draw different pictures. The shell paints the page around the
+ * `pre` in the same canvas and includes the fragment CSS once.
+ */
+export function encodeHtml(segments, theme) {
+    const canvas = exportCanvas(theme);
+    const css = `body{background:${canvas.background.hex};color:${canvas.foreground.hex};margin:0}\n${HTML_FRAGMENT_CSS}`;
+    return [
+        "<!DOCTYPE html>",
+        `<html><head><meta charset="utf-8"><style>\n${css}\n</style></head>`,
+        `<body>${encodeHtmlFragment(segments, theme)}</body></html>`,
+    ].join("\n");
+}

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

@@ -0,0 +1,130 @@
+/**
+ * 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;
+/**
+ * Text as character data in HTML or SVG markup. Both exporters write markup,
+ * and [LAW:single-enforcer] one escaper is what keeps a title or a run that is
+ * safe in one format from being live markup, or no markup at all, in the other.
+ */
+export declare const escapeText: (text: string) => string;
+/** A value inside a double-quoted attribute in HTML or SVG markup. */
+export declare const escapeAttribute: (value: string) => string;
+/** 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, and a run with no
+ * background of its own resolves to `"canvas"` rather than a colour, 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: the colours are `Style.drawnColors`, the ones
+ * `toSgrCodes` writes, resolved through the theme — `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 works on
+ * opaque colour, so no exporter ever draws a translucent one. Text under
+ * `conceal` is still present, and still selectable, in both formats.
+ *
+ * A translucent colour is flattened where the writer flattens it, over
+ * `SURFACE_BLACK`, not over this export's canvas. The writer's truecolor
+ * bytes are absolute — no terminal theme retints them — so a terminal under
+ * `theme` shows that colour, and an export that flattened over its own canvas
+ * would picture a colour no terminal draws.
+ *
+ * `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,159 @@
+/**
+ * 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;
+}
+const ENTITIES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" };
+/**
+ * The characters XML 1.0 admits nowhere in a document: C0 controls but tab,
+ * newline and return, the two noncharacters U+FFFE and U+FFFF, and unpaired
+ * surrogates. One of them leaves a whole SVG unparsable, not one glyph missing.
+ * Each takes no cell, so dropping it moves nothing on the grid.
+ */
+const NOT_XML = /[\x00-\x08\x0B\x0C\x0E-\x1F￾￿]|\p{Cs}/gu;
+/**
+ * Text as character data in HTML or SVG markup. Both exporters write markup,
+ * and [LAW:single-enforcer] one escaper is what keeps a title or a run that is
+ * safe in one format from being live markup, or no markup at all, in the other.
+ */
+export const escapeText = (text) => text.replace(NOT_XML, "").replace(/[&<>]/g, (c) => ENTITIES[c]);
+/** A value inside a double-quoted attribute in HTML or SVG markup. */
+export const escapeAttribute = (value) => value.replace(NOT_XML, "").replace(/[&"<>]/g, (c) => ENTITIES[c]);
+/**
+ * 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, and a run with no
+ * background of its own resolves to `"canvas"` rather than a colour, 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: the colours are `Style.drawnColors`, the ones
+ * `toSgrCodes` writes, resolved through the theme — `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 works on
+ * opaque colour, so no exporter ever draws a translucent one. Text under
+ * `conceal` is still present, and still selectable, in both formats.
+ *
+ * A translucent colour is flattened where the writer flattens it, over
+ * `SURFACE_BLACK`, not over this export's canvas. The writer's truecolor
+ * bytes are absolute — no terminal theme retints them — so a terminal under
+ * `theme` shows that colour, and an export that flattened over its own canvas
+ * would picture a colour no terminal draws.
+ *
+ * `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) {
+    // [LAW:one-source-of-truth] `drawnColors` is the one account of what a style
+    // puts on screen; the export reads it rather than flattening a second way.
+    const drawn = style.drawnColors();
+    const inkSpec = drawn.color ?? DEFAULT_COLOR;
+    const paperSpec = drawn.bgcolor ?? DEFAULT_COLOR;
+    const paper = paperSpec.getTruecolor(theme, false);
+    const ink = inkSpec.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/export-svg.d.ts

@@ -0,0 +1,49 @@
+/**
+ * export-svg — recorded segments drawn as an SVG terminal window: rounded
+ * chrome with a title and three window buttons, the rows inside it, every
+ * glyph where its terminal cell was, and the text still selectable.
+ *
+ * An encoding of `export-lines` and nothing more, the same as `export-html`.
+ * What a run looks like under a theme is decided there; this module decides
+ * only where SVG puts it. It never sees a `Style`.
+ *
+ * The geometry is Rich's — a 20px character, a cell 0.61 of that wide, a row
+ * 1.22 of it tall, the same margin and padding — so a screenshot of the same
+ * program matches the library this ports. The frame's colour is not Rich's:
+ * Rich strokes it white at 35% whatever the theme, which vanishes around a
+ * light canvas. Here it is the theme's ink blended 35% into the canvas — over
+ * a black canvas the colour Rich draws — and opaque, so the half of the stroke
+ * lying outside the canvas does not take on the colour of the page around it.
+ *
+ * Nor is how a glyph lands on its cell. The exporter has no font engine and
+ * does not know which font the viewer will draw with, so no advance width can
+ * be trusted: a CJK character drawn from a fallback font is rarely two cells,
+ * and every glyph after it on the row drifts. So every chunk of a run is
+ * anchored at its own column and stretched to its own cells with
+ * `textLength`, and alignment is guaranteed by the numbers written here rather
+ * than by the font. Measured in headless Chromium on `"ab漢字cd😀ef é̂x"`:
+ * Rich's `textLength` (cell width × string length) was off by up to 12px, one
+ * `<text>` a run by 3.9px, this chunking by 0.
+ *
+ * Decorations are rectangles, not CSS `text-decoration`: SVG has no reliable
+ * double underline, and one `text-decoration` property cannot hold an
+ * underline and a strike with different styles.
+ */
+import { type TerminalTheme } from "./color.js";
+import type { Segment } from "./segment.js";
+export interface SvgOptions {
+    readonly theme?: TerminalTheme;
+    /** The window title, centred in the chrome. */
+    readonly title: string;
+    /** The console width in cells; a wider row widens the window rather than being clipped. */
+    readonly width: number;
+}
+/**
+ * `segments` under `theme` as a standalone SVG document.
+ *
+ * Every background is painted before any glyph, so no run's paint covers its
+ * neighbour's text. Whitespace is emitted as real spaces under
+ * `xml:space="preserve"`, never as `&#160;`, so a selection copies what the
+ * terminal showed.
+ */
+export declare function encodeSvg(segments: Iterable<Segment>, { theme, title, width }: SvgOptions): string;