@promptctl/rich-js 0.17.0 → 0.18.1

package/dist/core/color.js

@@ -5,8 +5,13 @@
 function hex2(byte) {
     return byte.toString(16).padStart(2, "0");
 }
+// [LAW:one-source-of-truth] The one statement of a colour byte's range: the
+// constructor asserts it and the string parser reports it, from this predicate.
+function isByte(v) {
+    return Number.isInteger(v) && v >= 0 && v <= 255;
+}
 function assertChannel(name, v) {
-    if (!Number.isInteger(v) || v < 0 || v > 255) {
+    if (!isByte(v)) {
         throw new RangeError(`ColorRgba.${name} must be an integer in [0, 255]; got ${v}`);
     }
 }
@@ -501,7 +506,8 @@ export class ColorSpec {
             case ColorDepth.TRUECOLOR:
                 return this.value;
             case ColorDepth.EIGHT_BIT:
-                return EIGHT_BIT_TABLE.get(this.number);
+                // Slots 0–15 are the theme's own whatever depth names them, as `fixedValue` says.
+                return this.number < 16 ? (theme ?? INTERNAL_DEFAULT_THEME).ansiColors.get(this.number) : EIGHT_BIT_TABLE.get(this.number);
             case ColorDepth.STANDARD: {
                 const t = theme ?? INTERNAL_DEFAULT_THEME;
                 return t.ansiColors.get(this.number);
@@ -569,8 +575,8 @@ export class ColorSpec {
 // --- Parsing internals ---
 const HEX_RE = /^#([0-9a-f]{6})$/;
 const HEX_RGBA_RE = /^#([0-9a-f]{8})$/;
-const RGB_RE = /^rgb\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*\)$/;
-const COLOR_NUMBER_RE = /^color\((\d{1,3})\)$/;
+const RGB_RE = /^rgb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)$/;
+const COLOR_NUMBER_RE = /^color\((\d+)\)$/;
 function parseSingle(key) {
     if (key === "default" || key === "") {
         return ColorSpec.default();
@@ -594,23 +600,30 @@ function parseSingle(key) {
     // rgb()
     const rgbMatch = RGB_RE.exec(key);
     if (rgbMatch) {
-        const r = parseInt(rgbMatch[1], 10);
-        const g = parseInt(rgbMatch[2], 10);
-        const b = parseInt(rgbMatch[3], 10);
+        const r = parseByte(key, rgbMatch[1], "red");
+        const g = parseByte(key, rgbMatch[2], "green");
+        const b = parseByte(key, rgbMatch[3], "blue");
         return new ColorSpec(key, ColorDepth.TRUECOLOR, undefined, new ColorRgba(r, g, b));
     }
     // color(N)
     const numMatch = COLOR_NUMBER_RE.exec(key);
     if (numMatch) {
-        const n = parseInt(numMatch[1], 10);
-        if (n > 255) {
-            throw new ColorParseError(`ColorSpec number ${n} is out of range (0-255)`);
-        }
+        const n = parseByte(key, numMatch[1], "number");
         const type = n < 16 ? ColorDepth.STANDARD : ColorDepth.EIGHT_BIT;
         return new ColorSpec(key, type, n);
     }
     throw new ColorParseError(`Failed to parse color: "${key}"`);
 }
+// [LAW:single-enforcer] The regexes admit any run of digits and leave the
+// range to this check alone, so every out-of-range byte is a ColorParseError
+// naming the field, never the generic parse failure or the constructor's RangeError.
+function parseByte(key, digits, field) {
+    const n = parseInt(digits, 10);
+    if (!isByte(n)) {
+        throw new ColorParseError(`ColorSpec "${key}": ${field} ${digits} is out of range (0-255)`);
+    }
+    return n;
+}
 // --- Utility functions ---
 export function parseRgbHex(hex) {
     const r = parseInt(hex.slice(0, 2), 16);
@@ -633,14 +646,10 @@ export function blendRgb(color1, color2, crossFade = 0.5) {
  * A terminal theme — surface/foreground baseline, the ANSI 16/256 LUT, and a
  * semantic palette.
  *
- * **`ansiColors` is the canonical ANSI table, not a per-theme override.** All
- * preset themes in this codebase use `STANDARD_TABLE` for `ansiColors`. Theme
- * identity lives entirely in `palette` (primary, accent, text-*, surface, ...);
- * `ColorSpec.parse("red")` is intentionally consistent across themes — same
- * design as Textual itself, which models theming at the truecolor/semantic
- * layer rather than overloading the ANSI 16. Custom callers building bespoke
- * themes that *do* want to retint ANSI 16 are free to pass their own
- * `ColorTable`; that path is supported but not how the built-in presets work.
+ * **`ansiColors` is the theme's own sixteen colours**, the shades a terminal
+ * showing this theme draws `red`, `blue` and the rest in. `ColorSpec.parse("red")`
+ * is ANSI colour 1 under every theme; which red that is, is the theme's to say,
+ * as it is in Rich, where each `TerminalTheme` carries its own table.
  */
 export class TerminalTheme {
     backgroundColor;

package/dist/core/console.d.ts

@@ -8,7 +8,7 @@ import type { TerminalTheme } from "./color.js";
 import { type JSONOptions } from "./json.js";
 import type { Highlighter } from "./highlighter.js";
 import { type RuleOptions } from "../renderables/rule.js";
-import type { RenderOptions, StyleErrorHandler } from "./protocol.js";
+import type { Height, OverflowMethod, RenderOptions, StyleErrorHandler } from "./protocol.js";
 export interface ConsoleSink {
     write(chunk: string | Uint8Array): unknown;
 }
@@ -41,6 +41,13 @@ export interface ConsoleOptions {
      * TERM=dumb: false). `false` with `colorSystem: null` writes plain text.
      */
     hyperlinks?: boolean;
+    /**
+     * The terminal can draw only ASCII: boxes, rules, tree guides and widget
+     * marks draw with ASCII characters instead of line-drawing glyphs. A
+     * property of the output device, so it is set here once and reaches every
+     * renderable this console draws. Default false.
+     */
+    asciiOnly?: boolean;
     /**
      * Static width (cells). Ignored when `getSize` is provided. Falls back to
      * the `COLUMNS` env var / the bound stream's `columns` / 80.
@@ -94,7 +101,7 @@ export interface ConsoleOptions {
 export interface PrintOptions {
     style?: string | Style;
     justify?: "default" | "left" | "center" | "right" | "full";
-    overflow?: "fold" | "crop" | "ellipsis" | "ignore";
+    overflow?: OverflowMethod;
     highlight?: boolean;
     markup?: boolean;
     softWrap?: boolean;
@@ -115,6 +122,7 @@ export declare class Console {
     private _highlight;
     private _theme;
     private _onStyleError;
+    private readonly _asciiOnly;
     private _highlighter;
     private _recorded;
     private _capture;
@@ -125,7 +133,6 @@ export declare class Console {
     };
     get width(): number;
     get height(): number;
-    get encoding(): string;
     get isTerminal(): boolean;
     get isInteractive(): boolean;
     get colorSystem(): ColorDepth | null;
@@ -137,7 +144,9 @@ export declare class Console {
     get destination(): Destination;
     get file(): ConsoleSink;
     get theme(): Theme;
-    get options(): RenderOptions;
+    get options(): RenderOptions & {
+        height: Height;
+    };
     print(...args: unknown[]): void;
     log(...args: unknown[]): void;
     rule(title?: string, options?: RuleOptions): void;

package/dist/core/console.js

@@ -16,7 +16,45 @@ import { ReprHighlighter, NullHighlighter } from "./highlighter.js";
 // rather than being restated here; see `rule()`.
 import { Rule } from "../renderables/rule.js";
 import { segmentsToString } from "./render.js";
+import { placeBlock } from "./place.js";
 import { isRenderable } from "./protocol.js";
+// Three of the five justify methods place what a print draws as a block, the
+// way Rich's `print` wraps each renderable in `Align`. The other two leave it
+// where it was drawn: `"default"` asks for no placement, and `"full"` is a way
+// of setting a paragraph's words, which only text can do.
+const PLACED_BY = {
+    default: undefined,
+    full: undefined,
+    left: "left",
+    center: "center",
+    right: "right",
+};
+// A text run as one block: its items joined into one text, as the reference's
+// `Text.join` joins them, drawn under the print's options and ended by the
+// print's `end`. Measure and render both read that one text, so the width
+// `justify` places the run at is the width it is drawn at. Each item's own
+// `justify`, `overflow`, `noWrap` and `tabSize` stay behind, as they do in the
+// reference: the print's options set the whole run.
+class TextRun {
+    items;
+    end;
+    constructor(items, end) {
+        this.items = items;
+        this.end = end;
+    }
+    *render(options) {
+        yield* this.text(options).render(options);
+        yield this.end;
+    }
+    measure(options) {
+        return this.text(options).measure(options);
+    }
+    // A `Pretty` lays itself out for the width it is offered, so the run is
+    // joined per call rather than once.
+    text(options) {
+        return this.items.reduce((joined, item) => joined.append(item instanceof Pretty ? item.toText(options) : item), new RichText("", { end: "" }));
+    }
+}
 // A host with an environment but no streams — what a browser looks like from
 // here. Frozen so the shared instance cannot be mutated into a fake terminal.
 const DETACHED_ENVIRONMENT = Object.freeze({
@@ -67,8 +105,9 @@ function terminalSize(environment, stream) {
 function defaultSink(stream) {
     if (stream === undefined) {
         throw new Error("Console: no `file` provided and the environment has no stream to " +
-            "write to (e.g. running in a browser). Pass `file: hostStream(host)` " +
-            "or any other ConsoleSink so output has somewhere to go.");
+            "write to (e.g. running in a browser). Pass " +
+            "`environment: hostEnvironment(host)` to write through a terminal " +
+            "host, or a `file` so output has somewhere to go.");
     }
     return stream;
 }
@@ -146,6 +185,7 @@ export class Console {
     _highlight;
     _theme;
     _onStyleError;
+    _asciiOnly;
     _highlighter;
     _recorded;
     // [LAW:types-are-the-program] The capture state is carried in the *type*
@@ -182,6 +222,7 @@ export class Console {
         this._highlight = options?.highlight !== false;
         this._highlighter = options?.highlighter ?? new ReprHighlighter();
         this._onStyleError = options?.onStyleError;
+        this._asciiOnly = options?.asciiOnly ?? false;
         this._recorded = [];
         this._capture = null;
     }
@@ -195,9 +236,6 @@ export class Console {
     get height() {
         return this._getSize().height;
     }
-    get encoding() {
-        return "utf-8";
-    }
     get isTerminal() {
         return this._isTerminal;
     }
@@ -231,11 +269,16 @@ export class Console {
         return this._theme;
     }
     get options() {
+        // One read of the size, so a resize cannot pair one frame's width with
+        // another's height.
+        const { width, height } = this.size;
         return {
-            maxWidth: this.width,
+            maxWidth: width,
+            // The terminal an inline print lands on: a ceiling, never a region —
+            // content keeps its natural height beneath it.
+            height: { rows: height, exact: false },
             isTerminal: this.isTerminal,
-            encoding: this.encoding,
-            asciiOnly: false,
+            asciiOnly: this._asciiOnly,
             theme: this._theme,
             onStyleError: this._onStyleError,
             colorSystem: this._destination.colorSystem,
@@ -335,53 +378,65 @@ export class Console {
             else
                 blocks.push({ kind: "text", items: [text] });
         }
-        // [LAW:parse-dont-validate] `"ignore"` is not a way of cutting a line but
-        // the absence of an edge to cut at: no break, and nothing cut at the width.
-        // That is what `noWrap` already means to `RichText`, so it crosses into the
-        // render as `noWrap`, and `overflow` carries only the methods a renderable
-        // applies. Soft wrap is the same request — the reference defaults it to
-        // `"ignore"` — which is why the two arrive at one field.
+        // Soft wrap is the reference's pair of defaults, not a mode of its own: it
+        // stops wrapping, and when no overflow was named it asks for `"ignore"`, so
+        // the line leaves unbounded. A named overflow still cuts the unwrapped line
+        // at the width, as Rich's does. What `"ignore"` does to a line — no edge,
+        // no justify — is `RichText`'s to apply, so it crosses as it was asked for.
         const renderOpts = {
             ...this.options,
             justify: opts.justify === "default" ? undefined : opts.justify,
-            overflow: opts.overflow === "ignore" ? undefined : opts.overflow,
-            noWrap: softWrap || opts.overflow === "ignore",
+            overflow: opts.overflow ?? (softWrap ? "ignore" : undefined),
+            noWrap: softWrap,
         };
-        // The print style, then the console's base style, over what each block drew
-        // and not over the line ends added below: a styled break carries SGR codes
-        // across the newline.
+        // The print style, then the console's base style, over each line a block
+        // drew and never over the break that ends it: a styled break carries SGR
+        // codes across the newline.
         // [LAW:dataflow-not-control-flow] no style to apply is an empty list, not
         // a skipped step.
         const styles = [printStyle, this._style].filter((style) => !style.isNull);
         const styleContent = (segments) => styles.reduce((styled, style) => Segment.applyStyle(styled, style), segments);
-        // Every line end goes through the same writeSegments funnel as the text it
-        // ends, so it survives recording — otherwise `exportText` and `exportHtml`
-        // would join consecutive prints onto a single line. [LAW:single-enforcer]
         // The common default end is "\n" — reuse Segment's cached newline rather
         // than allocating one per print; only a non-default end needs a fresh one.
         const terminator = end === "\n" ? Segment.line() : new Segment(end);
+        const align = PLACED_BY[opts.justify ?? "default"];
+        // Each block as its lines, and whether its last line is closed. A placed
+        // block is closed line by line, as `Align` closes it. Unplaced, a text run
+        // is closed exactly where its content — its `end` included — breaks; any
+        // other block's lines are closed whether or not it closed them itself: a
+        // `Panel` ends in a line break and a bare `Spinner` or `ProgressBar` does
+        // not (they're line fragments, meant to be composed within a line —
+        // rich-flexstrip-5kf.4cq), and both leave the next print at the start of a
+        // line.
+        const drawBlock = (block) => {
+            const renderable = block.kind === "text" ? new TextRun(block.items, terminator) : block.renderable;
+            if (align)
+                return { lines: placeBlock(renderable, align, renderOpts), closed: true };
+            const drawn = [...renderable.render(renderOpts)];
+            // A text run's last segment is always its `end`, yielded even when
+            // empty, and `splitLines` drops the empty line after a final break only
+            // when nothing follows it — so the run is closed exactly when `end` is.
+            const closed = block.kind === "lines" || end.endsWith("\n");
+            return { lines: Segment.splitLines(drawn), closed };
+        };
+        // Every line end goes through the same writeSegments funnel as the text it
+        // ends, so it survives recording — otherwise `exportText` and `exportHtml`
+        // would join consecutive prints onto a single line. [LAW:single-enforcer]
         const output = [];
         for (const block of blocks) {
-            if (block.kind === "text") {
-                output.push(...styleContent(block.items.flatMap((item) => [...item.render(renderOpts)])), terminator);
-            }
-            else {
-                // A block's lines are closed whether or not it closed them itself: a
-                // `Panel` ends in a line break and a bare `Spinner` or `ProgressBar`
-                // does not (they're line fragments, meant to be composed within a
-                // line — rich-flexstrip-5kf.4cq), and both leave the next print at
-                // the start of a line.
-                for (const line of Segment.splitLines(block.renderable.render(renderOpts))) {
-                    output.push(...styleContent(line), Segment.line());
-                }
-            }
+            const { lines, closed } = drawBlock(block);
+            lines.forEach((line, index) => {
+                output.push(...styleContent(line));
+                if (closed || index < lines.length - 1)
+                    output.push(Segment.line());
+            });
         }
         // Crop last, and crop the line-end with the rest: in the reference `end` is
         // the tail of the printed line, so a line cut at the edge loses it too.
         // Soft wrap turns cropping off whatever `crop` says, because a line it left
         // whole is meant to reach the terminal whole. [LAW:dataflow-not-control-flow]
         // Not cropping is an unbounded width rather than a skipped step — the same
-        // spelling `RichText` uses for `noWrap`.
+        // spelling `RichText` uses for `"ignore"`.
         const cropWidth = !softWrap && (opts.crop ?? true) ? this.width : Infinity;
         this._writeSegments([...Segment.cropLines(output, cropWidth)]);
     }

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

@@ -1,5 +1,6 @@
 /**
- * export-html — recorded segments drawn as a standalone HTML document.
+ * 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
@@ -14,11 +15,45 @@
 import type { TerminalTheme } from "./color.js";
 import type { Segment } from "./segment.js";
 /**
- * `segments` under `theme` as a complete HTML document.
+ * 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 `<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.
+ * 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

@@ -1,5 +1,6 @@
 /**
- * export-html — recorded segments drawn as a standalone HTML document.
+ * 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
@@ -11,6 +12,7 @@
  * 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 { exportCanvas, exportLines } from "./export-lines.js";
 const ENTITIES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" };
 const escapeText = (text) => text.replace(/[&<>]/g, (c) => ENTITIES[c]);
@@ -64,7 +66,53 @@ function glyphCss(look) {
         ...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.
  *
@@ -72,35 +120,81 @@ const span = (css, content) => `<span style="${escapeAttribute(css.join(";"))}">
  * 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.
+ * 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 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>`;
+        ? 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>`;
 }
 /**
- * `segments` under `theme` as a complete HTML document.
+ * 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 `<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.
+ * 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 encodeHtml(segments, theme) {
+export function encodeHtmlFragment(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");
+        "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><pre>\n${rows.join("")}</pre></body></html>`,
+        `<body>${encodeHtmlFragment(segments, theme)}</body></html>`,
     ].join("\n");
 }

package/dist/core/markup.d.ts

@@ -62,12 +62,35 @@ export declare class MarkupSyntaxError extends MarkupError {
 }
 /**
  * Escapes markup characters so they render as literal text.
+ *
+ * [LAW:one-source-of-truth] The inverse of the two ways the parser reads a
+ * backslash run in front of a bracket, over the same `TAG_BODY`: before a tag
+ * the run is halved and an odd one left over escapes it, so the run is doubled
+ * and one added; before any other bracket one `\[` becomes `[`, so one
+ * backslash is added.
+ *
+ * No bracket in the output can open a tag, whatever it is joined to. A bracket
+ * whose tag the text ends before finishing — `[link=x` — is escaped as a tag,
+ * because the next fragment's `]` would finish it; when what follows is instead
+ * the caller's own tag, a backslash run in front of it renders doubled. A
+ * trailing run is doubled for the same reason: `escape("C:\\")` spliced before
+ * `[/bold]` would otherwise escape the closing tag, so at the very end of a
+ * string it renders doubled. The grammar cannot tell those cases apart, and
+ * both choices fail visibly rather than let input open or escape a tag.
+ *
+ * Rich's `escape` escapes only a finished tag and doubles only a trailing run
+ * of one, so input can drop a backslash, escape the closing tag after it, or
+ * open a tag across a join. All three are departures on purpose.
  */
 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`. */
+    /**
+     * Inner markup, already parsed (registry-aware) into a `RichText`. It carries
+     * no `baseStyle`: that is painted once, under the whole output, so it sits
+     * beneath whatever the handler returns.
+     */
     children: RichText;
     /** Raw inner markup text (between the opening tag's `]` and the closing tag's `[`). */
     raw: string;
@@ -89,9 +112,8 @@ export interface RenderMarkupOptions {
 /**
  * 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.
+ * whose returned `RichText` stands in the output where its pair stood, under
+ * any style tag that encloses the pair. The recursion is into the inner slice
+ * of each plugin pair, and every recursion node returns a `RichText`.
  */
 export declare function renderMarkup(markup: string, options?: RenderMarkupOptions): RichText;