@promptctl/rich-js 0.18.1 → 0.19.0

package/dist/core/easing.js

@@ -0,0 +1,171 @@
+/**
+ * Easing and phase: the one vocabulary for "how far along" — every function
+ * here returns progress in [0, 1].
+ *
+ * Two kinds of curve, composed as `ease(phase(t))`:
+ *
+ * - A **phase** turns a time `t` (seconds) into raw progress: `once` runs
+ *   0 → 1 over a span and holds, `loop` wraps 0 → 1 every period,
+ *   `pingPong` goes 0 → 1 → 0 every period. A per-cell offset is added to `t`
+ *   before the phase sees it — `phase(t + offset)` — so the cells of one
+ *   effect run the same curve shifted in time.
+ * - An **ease** reshapes that progress: any `(x) => y` on [0, 1]. The
+ *   built-ins are CSS's easing functions (CSS Easing Functions Level 1):
+ *   `linear`, `cubic-bezier()` with its named curves, and `steps()` with its
+ *   jump terms, plus `sine` for pulses — a half-cosine, so a `pingPong`
+ *   through it brightens and dims with no corner at either end.
+ *
+ * [LAW:no-ambient-temporal-coupling] Nothing here reads a clock. `t` is an
+ * argument; whoever draws frames owns the clock and samples these at
+ * whatever rate it likes, so the same `t` always gives the same progress.
+ *
+ * [LAW:one-type-per-behavior] An ease is a plain function value. CSS's named
+ * curves are four instances of `cubicBezier`, not four implementations, and
+ * `ColorRamp` and every effect take the same `Ease`.
+ *
+ * Tier 0 of `src/core/`: imports nothing, so `themes/` and every later
+ * `core/` module reach it downhill. [LAW:one-way-deps]
+ */
+/**
+ * CSS `cubic-bezier(x1, y1, x2, y2)`: the curve from (0, 0) to (1, 1) with
+ * those two control points, read as y at a given x. `x1` and `x2` must lie in
+ * [0, 1] — as in CSS — which keeps x monotonic in the curve parameter, so
+ * every input has exactly one output. `y1` and `y2` may leave [0, 1]; the
+ * curve then overshoots, as a CSS "back" curve does.
+ */
+export function cubicBezier(x1, y1, x2, y2) {
+    for (const [name, v] of [["x1", x1], ["y1", y1], ["x2", x2], ["y2", y2]]) {
+        if (!Number.isFinite(v))
+            throw new RangeError(`cubicBezier ${name} must be finite, got ${v}`);
+    }
+    if (x1 < 0 || x1 > 1 || x2 < 0 || x2 > 1) {
+        throw new RangeError(`cubicBezier x1 and x2 must lie in [0, 1], got ${x1} and ${x2}`);
+    }
+    // The Bernstein form in power basis: x(s) = ((ax·s + bx)·s + cx)·s, same for y.
+    const cx = 3 * x1;
+    const bx = 3 * (x2 - x1) - cx;
+    const ax = 1 - cx - bx;
+    const cy = 3 * y1;
+    const by = 3 * (y2 - y1) - cy;
+    const ay = 1 - cy - by;
+    const xAt = (s) => ((ax * s + bx) * s + cx) * s;
+    const yAt = (s) => ((ay * s + by) * s + cy) * s;
+    const dxAt = (s) => (3 * ax * s + 2 * bx) * s + cx;
+    const EPSILON = 1e-9;
+    // The parameter s with x(s) = x: Newton's method from s = x, which converges
+    // in a few steps on every curve CSS names; bisection when the slope is too
+    // flat for Newton to trust. x(s) is monotonic on [0, 1], so bisection always
+    // lands.
+    const solve = (x) => {
+        let s = x;
+        for (let i = 0; i < 8; i++) {
+            const err = xAt(s) - x;
+            if (Math.abs(err) < EPSILON)
+                return s;
+            const slope = dxAt(s);
+            if (Math.abs(slope) < 1e-6)
+                break;
+            s -= err / slope;
+        }
+        let lo = 0;
+        let hi = 1;
+        s = x;
+        while (hi - lo > EPSILON) {
+            if (xAt(s) < x)
+                lo = s;
+            else
+                hi = s;
+            s = (lo + hi) / 2;
+        }
+        return s;
+    };
+    return (x) => yAt(solve(Math.min(1, Math.max(0, x))));
+}
+/**
+ * CSS `steps(n, position)`: progress held flat in `n` equal intervals, jumping
+ * between them. The output takes `n` distinct values between the jumps
+ * `position` names — CSS's step algorithm, so `steps(1, "end")` is 0 until
+ * the very end.
+ */
+export function steps(n, position = "jump-end") {
+    const minimum = position === "jump-none" ? 2 : 1;
+    if (!Number.isInteger(n) || n < minimum) {
+        throw new RangeError(`steps(${n}, "${position}") needs a whole number of steps ≥ ${minimum}`);
+    }
+    const jumpsAtStart = position === "jump-start" || position === "start" || position === "jump-both";
+    // How many jumps the curve makes in all, which is what each step is a fraction of.
+    const jumps = {
+        "jump-start": n,
+        start: n,
+        "jump-end": n,
+        end: n,
+        "jump-both": n + 1,
+        "jump-none": n - 1,
+    }[position];
+    const lift = jumpsAtStart ? 1 : 0;
+    return (x) => {
+        const p = Math.min(1, Math.max(0, x));
+        return Math.min(jumps, Math.floor(p * n) + lift) / jumps;
+    };
+}
+/** The identity ease: progress unchanged. */
+const linear = (x) => x;
+/** CSS `step-end`: 0 until the very end. */
+const stepEnd = steps(1, "jump-end");
+/** A half-cosine, flat at both ends: the curve a breathing pulse wants. */
+const sine = (x) => (1 - Math.cos(Math.PI * x)) / 2;
+/**
+ * Every built-in ease by the name a template spells it with — CSS's keyword
+ * names, plus `sine`, plus `step`: the spelling `ColorRamp` used before this
+ * vocabulary existed, kept so every template written against it renders the
+ * same. It is CSS's `step-end`, the same function value.
+ */
+export const EASES = {
+    linear,
+    ease: cubicBezier(0.25, 0.1, 0.25, 1),
+    "ease-in": cubicBezier(0.42, 0, 1, 1),
+    "ease-out": cubicBezier(0, 0, 0.58, 1),
+    "ease-in-out": cubicBezier(0.42, 0, 0.58, 1),
+    "step-start": steps(1, "jump-start"),
+    "step-end": stepEnd,
+    step: stepEnd,
+    sine,
+};
+/**
+ * The gate a spelled ease crosses. [LAW:parse-dont-validate] — a name in, the
+ * function out, so nothing downstream holds a string it must check again.
+ * Unknown names throw naming every legal one. [LAW:no-silent-failure]
+ */
+export function parseEase(name) {
+    if (!Object.hasOwn(EASES, name)) {
+        throw new RangeError(`unknown ease ${JSON.stringify(name)}; expected one of ` +
+            Object.keys(EASES).map((n) => JSON.stringify(n)).join(", "));
+    }
+    return EASES[name];
+}
+function positiveSeconds(what, seconds) {
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        throw new RangeError(`${what} must be a positive number of seconds, got ${seconds}`);
+    }
+}
+/** The three phase shapes. Each takes seconds and returns a `Phase`. */
+export const Phase = {
+    /** 0 before `start`, rising to 1 over `duration` seconds, then held at 1. */
+    once(start, duration) {
+        if (!Number.isFinite(start))
+            throw new RangeError(`Phase.once start must be finite, got ${start}`);
+        positiveSeconds("Phase.once duration", duration);
+        return (t) => Math.min(1, Math.max(0, (t - start) / duration));
+    },
+    /** 0 → 1 every `period` seconds, wrapping back to 0; negative `t` wraps too. */
+    loop(period) {
+        positiveSeconds("Phase.loop period", period);
+        return (t) => (((t % period) + period) % period) / period;
+    },
+    /** 0 → 1 → 0 every `period` seconds: there in the first half, back in the second. */
+    pingPong(period) {
+        positiveSeconds("Phase.pingPong period", period);
+        const wrap = Phase.loop(period);
+        return (t) => 1 - Math.abs(2 * wrap(t) - 1);
+    },
+};

package/dist/core/env.d.ts

@@ -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 type Env = Readonly<Record<string, string | undefined>>;

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.js

@@ -13,10 +13,7 @@
  * 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]);
-const escapeAttribute = (value) => value.replace(/[&"<>]/g, (c) => ENTITIES[c]);
+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

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

@@ -77,6 +77,14 @@ export type ExportLine = readonly ExportRun[];
  * 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;
@@ -85,25 +93,26 @@ export interface ExportCanvas {
 /**
  * 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.
+ * 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: 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 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.
  *
- * 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.
+ * 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

package/dist/core/export-lines.js

@@ -55,6 +55,22 @@ export function parseHref(link) {
     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.
@@ -64,9 +80,9 @@ 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.
+ * 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 {
@@ -77,29 +93,31 @@ export function exportCanvas(theme) {
 /**
  * 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 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.
  *
- * 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.
+ * 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) {
-    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);
+    // [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;

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;

package/dist/core/export-svg.js

@@ -0,0 +1,213 @@
+/**
+ * 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 { cellLen, graphemes } from "./cells.js";
+import { blendRgb } from "./color.js";
+import { fnv1a } from "./fnv1a.js";
+import { escapeAttribute, escapeText, exportCanvas, exportLines, } from "./export-lines.js";
+const CHAR_HEIGHT = 20;
+const CELL_WIDTH = CHAR_HEIGHT * 0.61;
+const LINE_HEIGHT = CHAR_HEIGHT * 1.22;
+const MARGIN = 1;
+const PADDING = { top: 40, right: 8, bottom: 8, left: 8 };
+/** A painted background sits 1.5px into its row and overlaps the next by a hair, so rows show no seam. */
+const CELL_TOP = 1.5;
+const CELL_HEIGHT = LINE_HEIGHT + 0.25;
+const LINE_THICKNESS = 1.5;
+const FONT_FAMILY = `"Fira Code", Menlo, Consolas, "DejaVu Sans Mono", monospace`;
+const FRAME_FADE = 0.35;
+const WINDOW_BUTTONS = ["#ff5f57", "#febc2e", "#28c840"];
+/** Coordinates to two decimals, so `3 × 12.2` is written `36.6` and not `36.599999999999994`. */
+const n = (value) => String(Math.round(value * 100) / 100);
+/**
+ * The blink keyframes every SVG defines identically, so one name serves them
+ * all: two inlined in one page define the same rule twice, and neither changes
+ * the other.
+ */
+const BLINK_KEYFRAMES = "rich-svg-blink";
+/**
+ * `text` cut into the pieces that are positioned one by one, starting at
+ * `column`: consecutive one-cell graphemes share a chunk, since the font's
+ * own advance is right for them to within what `textLength` corrects; every
+ * wider grapheme is a chunk of its own, since that advance is the one that
+ * drifts. A zero-cell grapheme joins the chunk before it so it can still
+ * combine, and only when a run opens with one does it stand as a chunk of no
+ * cells. Graphemes rather than code points, because `cellLen` measures a
+ * joined emoji as one glyph.
+ */
+function chunk(text, column) {
+    const pieces = [];
+    for (const grapheme of graphemes(text)) {
+        const cells = cellLen(grapheme);
+        const last = pieces[pieces.length - 1];
+        if (last !== undefined && (cells === 0 || (cells === 1 && last.narrow))) {
+            last.text += grapheme;
+            last.cells += cells;
+        }
+        else {
+            pieces.push({ text: grapheme, cells, narrow: cells === 1 });
+        }
+    }
+    let at = column;
+    return pieces.map(({ text, cells }) => {
+        const placed = { text, column: at, cells };
+        at += cells;
+        return placed;
+    });
+}
+/** Every run of every row at the column the runs before it on its row end at. */
+function place(rows) {
+    return rows.flatMap((runs, row) => {
+        let column = 0;
+        return runs.map(({ text, look }) => {
+            const chunks = chunk(text, column);
+            const cells = chunks.reduce((sum, c) => sum + c.cells, 0);
+            const placed = { row, column, cells, look, chunks };
+            column += cells;
+            return placed;
+        });
+    });
+}
+// [LAW:dataflow-not-control-flow] Each enum-valued field of a look is a table
+// from its values to what it draws, so `Record` makes a new value a compile
+// error until it has a row.
+const UNDERLINE_BELOW_BASELINE = {
+    none: [],
+    single: [2],
+    double: [2, 5],
+};
+const BLINK_PERIOD = {
+    none: null,
+    slow: "1s",
+    fast: "0.5s",
+};
+const OUTLINE_RADIUS = {
+    none: null,
+    frame: 0,
+    encircle: CELL_WIDTH,
+};
+/** The CSS a look's class carries: what a glyph's `fill` and font say, and its blink. */
+function lookCss(look) {
+    const period = BLINK_PERIOD[look.blink];
+    return [
+        `fill:${look.foreground.hex}`,
+        ...(look.bold ? ["font-weight:bold"] : []),
+        ...(look.italic ? ["font-style:italic"] : []),
+        ...(period === null ? [] : [`animation:${BLINK_KEYFRAMES} ${period} step-end infinite`]),
+    ].join(";");
+}
+const cellBox = (run) => `x="${n(run.column * CELL_WIDTH)}" y="${n(run.row * LINE_HEIGHT + CELL_TOP)}" ` +
+    `width="${n(run.cells * CELL_WIDTH)}" height="${n(CELL_HEIGHT)}"`;
+/** A run's painted background; a run showing the canvas paints nothing. */
+function backgroundSvg(run) {
+    return run.look.background === "canvas"
+        ? []
+        : [`<rect fill="${run.look.background.hex}" ${cellBox(run)} shape-rendering="crispEdges"/>`];
+}
+function textSvg({ text, column, cells }, baseline) {
+    // A chunk of no cells has no length to stretch to; it takes the font's.
+    const length = cells === 0 ? "" : ` textLength="${n(cells * CELL_WIDTH)}" lengthAdjust="spacingAndGlyphs"`;
+    return `<text x="${n(column * CELL_WIDTH)}" y="${n(baseline)}"${length} xml:space="preserve">${escapeText(text)}</text>`;
+}
+/**
+ * One run: its glyphs, then its lines and outline over them, in a group whose
+ * class carries the look — so the lines take the glyph's `fill` and blink
+ * with it. The outline is a stroke, so it names its colour itself.
+ */
+function runSvg(run, className) {
+    const { look } = run;
+    const top = run.row * LINE_HEIGHT;
+    const baseline = top + CHAR_HEIGHT;
+    const x = n(run.column * CELL_WIDTH);
+    const width = n(run.cells * CELL_WIDTH);
+    const lineYs = [
+        ...UNDERLINE_BELOW_BASELINE[look.underline].map((offset) => baseline + offset),
+        ...(look.strike ? [baseline - 6] : []),
+        ...(look.overline ? [top + CELL_TOP] : []),
+    ];
+    const radius = OUTLINE_RADIUS[look.outline];
+    const drawn = [
+        ...run.chunks.map((c) => textSvg(c, baseline)),
+        ...lineYs.map((y) => `<rect x="${x}" y="${n(y)}" width="${width}" height="${LINE_THICKNESS}"/>`),
+        ...(radius === null
+            ? []
+            : [`<rect ${cellBox(run)} rx="${n(radius)}" fill="none" stroke="${look.foreground.hex}" stroke-width="1"/>`]),
+    ].join("");
+    const group = `<g class="${className}">${drawn}</g>`;
+    return look.href === null ? group : `<a href="${escapeAttribute(look.href)}">${group}</a>`;
+}
+/**
+ * `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 function encodeSvg(segments, { theme, title, width }) {
+    const canvas = exportCanvas(theme);
+    const rows = exportLines(segments, theme);
+    const runs = place(rows);
+    // The prefix every class name carries is a hash of the rules those classes
+    // define as well as of what is drawn, since a class is page-wide once the
+    // SVG is inlined: two exports that share a prefix define every rule alike, so
+    // the same recording under another theme cannot restyle this one.
+    const styled = runs.map((run) => ({ run, css: lookCss(run.look) }));
+    const rules = [...new Set(styled.map(({ css }) => css))];
+    const text = rows.map((row) => row.map((run) => run.text).join("")).join("\n");
+    const id = `terminal-${fnv1a(`${title.length}:${title}${text.length}:${text}${rules.join("\n")}`)}`;
+    const classOf = (css) => `${id}-r${rules.indexOf(css) + 1}`;
+    const drawnRuns = styled.map(({ run, css }) => runSvg(run, classOf(css)));
+    const columns = runs.reduce((widest, run) => Math.max(widest, run.column + run.cells), width);
+    const terminalWidth = Math.ceil(columns * CELL_WIDTH + PADDING.left + PADDING.right);
+    const terminalHeight = rows.length * LINE_HEIGHT + PADDING.top + PADDING.bottom;
+    const stylesheet = [
+        `.${id}-matrix{font-family:${FONT_FAMILY};font-size:${CHAR_HEIGHT}px}`,
+        `.${id}-title{font-size:18px;font-weight:bold;font-family:arial}`,
+        ...rules.map((css) => `.${classOf(css)}{${css}}`),
+        // Blink only for a reader who has not asked for reduced motion, as in HTML.
+        `@media (prefers-reduced-motion:no-preference){@keyframes ${BLINK_KEYFRAMES}{50%{fill:transparent}}}`,
+    ].join("\n");
+    return [
+        `<svg class="rich-terminal" viewBox="0 0 ${n(terminalWidth + 2 * MARGIN)} ${n(terminalHeight + 2 * MARGIN)}" xmlns="http://www.w3.org/2000/svg">`,
+        `<style>\n${stylesheet}\n</style>`,
+        `<rect fill="${canvas.background.hex}" stroke="${blendRgb(canvas.background, canvas.foreground, FRAME_FADE).hex}" stroke-width="1" ` +
+            `x="${MARGIN}" y="${MARGIN}" width="${n(terminalWidth)}" height="${n(terminalHeight)}" rx="8"/>`,
+        `<text class="${id}-title" fill="${canvas.foreground.hex}" text-anchor="middle" ` +
+            `x="${n(MARGIN + terminalWidth / 2)}" y="${MARGIN + CHAR_HEIGHT + 6}">${escapeText(title)}</text>`,
+        `<g transform="translate(26,22)">${WINDOW_BUTTONS.map((fill, i) => `<circle cx="${i * 22}" cy="0" r="7" fill="${fill}"/>`).join("")}</g>`,
+        `<g class="${id}-matrix" transform="translate(${MARGIN + PADDING.left},${MARGIN + PADDING.top})">`,
+        ...runs.flatMap(backgroundSvg),
+        ...drawnRuns,
+        `</g>`,
+        `</svg>`,
+    ].join("\n");
+}

package/dist/core/fnv1a.d.ts

@@ -0,0 +1,10 @@
+/**
+ * fnv1a — FNV-1a, 32-bit, over a string's UTF-8 bytes, as 8 lowercase hex
+ * digits: the short deterministic name this library derives wherever output
+ * needs an identifier that is a function of what it names — an OSC 8 link id,
+ * an SVG's class prefix — rather than of a counter or a clock.
+ *
+ * UTF-8 rather than UTF-16 code units, so any other runtime computing standard
+ * FNV-1a over the same text gets the same digits.
+ */
+export declare function fnv1a(text: string): string;

package/dist/core/fnv1a.js

@@ -0,0 +1,17 @@
+/**
+ * fnv1a — FNV-1a, 32-bit, over a string's UTF-8 bytes, as 8 lowercase hex
+ * digits: the short deterministic name this library derives wherever output
+ * needs an identifier that is a function of what it names — an OSC 8 link id,
+ * an SVG's class prefix — rather than of a counter or a clock.
+ *
+ * UTF-8 rather than UTF-16 code units, so any other runtime computing standard
+ * FNV-1a over the same text gets the same digits.
+ */
+const utf8 = new TextEncoder();
+export function fnv1a(text) {
+    let hash = 0x811c9dc5;
+    for (const byte of utf8.encode(text)) {
+        hash = Math.imul(hash ^ byte, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}