@crewhaus/tool-media 0.7.0

package/dist/lib/sparkline.js

@@ -0,0 +1,93 @@
+/**
+ * Sparklines — a series reduced to something that fits on one line.
+ *
+ * Two renderings: an SVG path for a report or a dashboard, and a run of
+ * Unicode block characters for a digest line, a commit message or a
+ * terminal. Both quantise the same way, so the shapes agree.
+ */
+import { MediaFormatError } from "./bytes";
+import { circle, escapeXml, num, polyline, rect, svgDocument } from "./svg";
+/** Eight levels, from an eighth of a block to a full one. */
+const BLOCKS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+function resolveRange(values, explicit) {
+    const min = explicit.min ?? Math.min(...values);
+    const max = explicit.max ?? Math.max(...values);
+    if (min > max)
+        throw new MediaFormatError(`min ${min} is above max ${max}`);
+    if (min === max) {
+        // A flat series has no shape; centre it rather than divide by zero.
+        return { min: min - 0.5, max: max + 0.5 };
+    }
+    return { min, max };
+}
+function check(values) {
+    if (values.length === 0)
+        throw new MediaFormatError("a sparkline needs at least one value");
+    for (const value of values) {
+        if (!Number.isFinite(value))
+            throw new MediaFormatError(`the series contains ${value}`);
+    }
+}
+/**
+ * The series as block characters, one per value. Values at or below `min`
+ * get the shortest block and values at or above `max` the tallest, so a
+ * caller supplying an explicit range gets clipping rather than a surprise.
+ */
+export function sparklineBlocks(values, explicit = {}) {
+    check(values);
+    const range = resolveRange(values, explicit);
+    const span = range.max - range.min;
+    let out = "";
+    for (const value of values) {
+        const fraction = (value - range.min) / span;
+        const level = Math.min(7, Math.max(0, Math.round(fraction * 7)));
+        out += BLOCKS[level];
+    }
+    return out;
+}
+/** The series as a small standalone SVG. */
+export function sparklineSvg(values, options = {}, explicit = {}) {
+    check(values);
+    const width = options.width ?? 120;
+    const height = options.height ?? 24;
+    if (width < 8 || height < 4) {
+        throw new MediaFormatError(`${width}x${height} is too small for a sparkline`);
+    }
+    const range = resolveRange(values, explicit);
+    const span = range.max - range.min;
+    const pad = 2;
+    const usableWidth = width - pad * 2;
+    const usableHeight = height - pad * 2;
+    const step = values.length === 1 ? 0 : usableWidth / (values.length - 1);
+    const points = values.map((value, i) => {
+        const clamped = Math.min(range.max, Math.max(range.min, value));
+        return [pad + i * step, pad + usableHeight - ((clamped - range.min) / span) * usableHeight];
+    });
+    const stroke = options.stroke ?? "#3b6fd4";
+    const body = [];
+    if (options.fill !== undefined) {
+        const first = points[0];
+        const last = points[points.length - 1];
+        const area = [
+            `M ${num(first[0])} ${num(height - pad)}`,
+            ...points.map(([x, y]) => `L ${num(x)} ${num(y)}`),
+            `L ${num(last[0])} ${num(height - pad)}`,
+            "Z",
+        ].join(" ");
+        // Escaped like every other caller-supplied colour: a raw `"` here would
+        // close the attribute and let the value append elements of its own.
+        body.push(`<path d="${area}" fill="${escapeXml(options.fill)}"/>`);
+    }
+    if (points.length === 1) {
+        const only = points[0];
+        body.push(rect(pad, only[1] - 1, usableWidth, 2, stroke));
+    }
+    else {
+        body.push(polyline(points, stroke, 1.5));
+    }
+    if (options.markLast === true) {
+        const last = points[points.length - 1];
+        body.push(circle(last[0], last[1], 2, stroke));
+    }
+    return svgDocument(width, height, options.background ?? "none", body);
+}

package/dist/lib/subtitle.d.ts

@@ -0,0 +1,62 @@
+export type SubtitleFormat = "srt" | "vtt";
+export type Cue = {
+    /** 1-based position in the file, renumbered on write. */
+    readonly index: number;
+    readonly startMs: number;
+    readonly endMs: number;
+    /** Cue text, with its own line breaks kept as `\n`. */
+    readonly text: string;
+    /** The cue identifier, where the file gave one. */
+    readonly id?: string;
+    /** WebVTT cue settings, verbatim, where the file gave any. */
+    readonly settings?: string;
+};
+export type ParseResult = {
+    readonly format: SubtitleFormat;
+    readonly cues: ReadonlyArray<Cue>;
+    /** Blocks that looked like cues but could not be read, with the reason. */
+    readonly skipped: ReadonlyArray<{
+        block: number;
+        reason: string;
+    }>;
+};
+/** `HH:MM:SS,mmm`, `MM:SS.mmm` and the other legal spellings, to millis. */
+export declare function parseTimestamp(text: string): number;
+/** Milliseconds to `HH:MM:SS,mmm` (SRT) or `HH:MM:SS.mmm` (WebVTT). */
+export declare function formatTimestamp(ms: number, format: SubtitleFormat): string;
+/** The format a document is in, from its first meaningful line. */
+export declare function detectSubtitleFormat(text: string): SubtitleFormat;
+/** Parse an SRT or WebVTT document. The format is detected when not given. */
+export declare function parseSubtitles(input: string, format?: SubtitleFormat): ParseResult;
+/**
+ * Greedy word wrap at `columns`, preserving the line breaks already in the
+ * text. A word longer than `columns` gets its own line rather than being
+ * broken mid-word.
+ */
+export declare function wrapCueText(text: string, columns: number): string;
+export type WriteOptions = {
+    /** Milliseconds to add to every cue; may be negative. */
+    readonly shiftMs?: number;
+    /** Re-wrap each cue's text to this many columns. */
+    readonly wrapColumns?: number;
+    /** WebVTT only: text appended to the `WEBVTT` header line. */
+    readonly header?: string;
+};
+export type WriteResult = {
+    readonly text: string;
+    readonly cueCount: number;
+    /** Cues dropped because the shift moved them before zero. */
+    readonly dropped: number;
+};
+/**
+ * Cues back to a document. A negative shift that would push a cue before
+ * zero drops that cue and says so, rather than clamping it to 00:00:00 and
+ * silently stacking several cues on top of one another.
+ *
+ * Caller values cannot change the document's STRUCTURE: cue text is put
+ * through `cueBody` so a blank line in it cannot end the cue early, and the
+ * one-line fields (a WebVTT id, its settings, the `WEBVTT` header) are
+ * refused outright when they carry a line break or a `-->`. Reading the
+ * result back therefore always yields the cues that went in, and only those.
+ */
+export declare function writeSubtitles(cues: ReadonlyArray<Cue>, format: SubtitleFormat, options?: WriteOptions): WriteResult;

package/dist/lib/subtitle.js

@@ -0,0 +1,233 @@
+/**
+ * SubRip (.srt) and WebVTT (.vtt) subtitles: parsing to cues, and writing
+ * cues back out with optional time shifting and re-wrapping.
+ *
+ * ## Read
+ *
+ * Both formats, with or without a BOM, with CRLF or LF line endings, with
+ * or without the cue identifier line. WebVTT `NOTE`, `STYLE` and `REGION`
+ * blocks are recognised and skipped rather than mistaken for cues, and cue
+ * settings (`align:start position:10%`) are preserved as an opaque string
+ * so writing a VTT back does not silently drop the positioning.
+ *
+ * ## Not read
+ *
+ * WebVTT chapter and metadata tracks, and SRT's unofficial coordinate
+ * extension. Inline markup (`<i>`, `<c.classname>`) is left in the cue text
+ * verbatim — this does not parse it and does not strip it.
+ *
+ * ## Times
+ *
+ * Every cue carries integer milliseconds. Nothing here reads a clock: a
+ * shift is an input, never "now minus something".
+ */
+import { MediaFormatError } from "./bytes";
+const TIMING = /^(.*?)-->(.*?)$/;
+const TIMESTAMP = /^(?:(\d+):)?(\d{1,2}):(\d{1,2})[.,](\d{1,3})$/;
+/** `HH:MM:SS,mmm`, `MM:SS.mmm` and the other legal spellings, to millis. */
+export function parseTimestamp(text) {
+    const match = TIMESTAMP.exec(text.trim());
+    if (!match)
+        throw new MediaFormatError(`"${text}" is not a subtitle timestamp`);
+    const hours = match[1] === undefined ? 0 : Number.parseInt(match[1], 10);
+    const minutes = Number.parseInt(match[2], 10);
+    const seconds = Number.parseInt(match[3], 10);
+    const fraction = match[4].padEnd(3, "0");
+    if (minutes > 59 || seconds > 59) {
+        throw new MediaFormatError(`"${text}" has a minute or second field above 59`);
+    }
+    return hours * 3_600_000 + minutes * 60_000 + seconds * 1000 + Number.parseInt(fraction, 10);
+}
+/** Milliseconds to `HH:MM:SS,mmm` (SRT) or `HH:MM:SS.mmm` (WebVTT). */
+export function formatTimestamp(ms, format) {
+    if (ms < 0)
+        throw new MediaFormatError(`cannot format a negative timestamp (${ms}ms)`);
+    const total = Math.round(ms);
+    const hours = Math.floor(total / 3_600_000);
+    const minutes = Math.floor((total % 3_600_000) / 60_000);
+    const seconds = Math.floor((total % 60_000) / 1000);
+    const millis = total % 1000;
+    const pad = (v, width = 2) => String(v).padStart(width, "0");
+    return `${pad(hours)}:${pad(minutes)}:${pad(seconds)}${format === "srt" ? "," : "."}${pad(millis, 3)}`;
+}
+/** The format a document is in, from its first meaningful line. */
+export function detectSubtitleFormat(text) {
+    const head = text.replace(/^/, "").trimStart();
+    return head.startsWith("WEBVTT") ? "vtt" : "srt";
+}
+const VTT_BLOCK_KEYWORDS = ["NOTE", "STYLE", "REGION"];
+/** Parse an SRT or WebVTT document. The format is detected when not given. */
+export function parseSubtitles(input, format) {
+    const resolved = format ?? detectSubtitleFormat(input);
+    const normalized = input.replace(/^/, "").replace(/\r\n?/g, "\n");
+    const body = resolved === "vtt" ? normalized.replace(/^WEBVTT[^\n]*\n?/, "") : normalized;
+    const blocks = body.split(/\n{2,}/);
+    const cues = [];
+    const skipped = [];
+    for (let b = 0; b < blocks.length; b++) {
+        const block = blocks[b].trim();
+        if (block === "")
+            continue;
+        const lines = block.split("\n");
+        const first = lines[0];
+        if (resolved === "vtt" &&
+            VTT_BLOCK_KEYWORDS.some((k) => first === k || first.startsWith(`${k} `))) {
+            continue;
+        }
+        let at = 0;
+        let id;
+        if (!TIMING.test(first)) {
+            id = first.trim();
+            at = 1;
+        }
+        const timingLine = lines[at];
+        if (timingLine === undefined || !TIMING.test(timingLine)) {
+            skipped.push({ block: b, reason: "no timing line" });
+            continue;
+        }
+        const match = TIMING.exec(timingLine);
+        const rightSide = match[2].trim();
+        // Cue settings follow the end timestamp, separated by whitespace.
+        const spaceAt = rightSide.search(/\s/);
+        const endText = spaceAt === -1 ? rightSide : rightSide.slice(0, spaceAt);
+        const settings = spaceAt === -1 ? "" : rightSide.slice(spaceAt).trim();
+        let startMs;
+        let endMs;
+        try {
+            startMs = parseTimestamp(match[1]);
+            endMs = parseTimestamp(endText);
+        }
+        catch (err) {
+            skipped.push({ block: b, reason: err.message });
+            continue;
+        }
+        if (endMs < startMs) {
+            skipped.push({ block: b, reason: `end ${endMs}ms is before start ${startMs}ms` });
+            continue;
+        }
+        cues.push({
+            index: cues.length + 1,
+            startMs,
+            endMs,
+            text: lines
+                .slice(at + 1)
+                .join("\n")
+                .trim(),
+            // An SRT identifier is a sequence number the writer regenerates, so
+            // it is not worth carrying; a WebVTT one can be referenced from CSS.
+            ...(id !== undefined && resolved === "vtt" ? { id } : {}),
+            ...(settings !== "" && resolved === "vtt" ? { settings } : {}),
+        });
+    }
+    return { format: resolved, cues, skipped };
+}
+/**
+ * Greedy word wrap at `columns`, preserving the line breaks already in the
+ * text. A word longer than `columns` gets its own line rather than being
+ * broken mid-word.
+ */
+export function wrapCueText(text, columns) {
+    if (columns <= 0)
+        throw new MediaFormatError(`cannot wrap to ${columns} columns`);
+    return text
+        .split("\n")
+        .map((paragraph) => {
+        const words = paragraph.split(/\s+/).filter((w) => w !== "");
+        if (words.length === 0)
+            return "";
+        const lines = [];
+        let current = words[0];
+        for (const word of words.slice(1)) {
+            if (current.length + 1 + word.length <= columns)
+                current += ` ${word}`;
+            else {
+                lines.push(current);
+                current = word;
+            }
+        }
+        lines.push(current);
+        return lines.join("\n");
+    })
+        .join("\n");
+}
+/**
+ * A cue's text, made safe to put in a block.
+ *
+ * Both formats separate cues with a BLANK LINE, so a blank line inside a
+ * cue's text does not render as a paragraph break — it ENDS the cue, and
+ * whatever follows is read back as a new one. Text of
+ * `"hello\n\n00:00:09,000 --> 00:00:10,000\nanything"` therefore writes two
+ * cues where the caller asked for one, which is structure injection by a
+ * value. Runs of blank lines are collapsed, and leading and trailing ones
+ * dropped, so the document a caller gets back has exactly the cues they
+ * passed in. Line endings are normalised first, because a lone `\r` becomes
+ * a line break when the document is read again.
+ */
+function cueBody(text) {
+    return text
+        .replace(/\r\n?/g, "\n")
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .join("\n")
+        .replace(/\n{2,}/g, "\n")
+        .replace(/^\n+/, "")
+        .replace(/\n+$/, "");
+}
+/**
+ * Refuse a single-line field that would not stay on its line. A cue
+ * identifier, a cue's settings and the `WEBVTT` header each occupy exactly
+ * one line; a break in any of them starts a new block, and a `-->` turns the
+ * line into a timing line. Located by cue, so the caller can fix the value.
+ */
+function requireOneLine(value, what) {
+    if (/[\n\r]/.test(value)) {
+        throw new MediaFormatError(`${what} contains a line break; it has to stay on one line`);
+    }
+    if (value.includes("-->")) {
+        throw new MediaFormatError(`${what} contains "-->", which would read back as a timing line`);
+    }
+}
+/**
+ * Cues back to a document. A negative shift that would push a cue before
+ * zero drops that cue and says so, rather than clamping it to 00:00:00 and
+ * silently stacking several cues on top of one another.
+ *
+ * Caller values cannot change the document's STRUCTURE: cue text is put
+ * through `cueBody` so a blank line in it cannot end the cue early, and the
+ * one-line fields (a WebVTT id, its settings, the `WEBVTT` header) are
+ * refused outright when they carry a line break or a `-->`. Reading the
+ * result back therefore always yields the cues that went in, and only those.
+ */
+export function writeSubtitles(cues, format, options = {}) {
+    const shift = options.shiftMs ?? 0;
+    if (options.header !== undefined)
+        requireOneLine(options.header, "the WEBVTT header");
+    const blocks = [];
+    let dropped = 0;
+    let index = 0;
+    for (const cue of cues) {
+        const startMs = cue.startMs + shift;
+        const endMs = cue.endMs + shift;
+        if (startMs < 0 || endMs < 0) {
+            dropped++;
+            continue;
+        }
+        index++;
+        const body = cueBody(options.wrapColumns === undefined ? cue.text : wrapCueText(cue.text, options.wrapColumns));
+        const timing = `${formatTimestamp(startMs, format)} --> ${formatTimestamp(endMs, format)}`;
+        if (format === "srt") {
+            blocks.push(`${index}\n${timing}\n${body}`);
+        }
+        else {
+            if (cue.id !== undefined)
+                requireOneLine(cue.id, `cue ${cue.index}'s id`);
+            if (cue.settings !== undefined)
+                requireOneLine(cue.settings, `cue ${cue.index}'s settings`);
+            const head = cue.id === undefined ? "" : `${cue.id}\n`;
+            const settings = cue.settings === undefined ? "" : ` ${cue.settings}`;
+            blocks.push(`${head}${timing}${settings}\n${body}`);
+        }
+    }
+    const prefix = format === "vtt" ? `WEBVTT${options.header === undefined ? "" : ` ${options.header}`}\n\n` : "";
+    return { text: `${prefix}${blocks.join("\n\n")}\n`, cueCount: index, dropped };
+}

package/dist/lib/svg.d.ts

@@ -0,0 +1,76 @@
+/**
+ * SVG construction, shared by the chart, sparkline and diagram renderers.
+ *
+ * Determinism is the whole contract here: same data in, byte-identical SVG
+ * out. That rules out `toLocaleString` (locale-dependent), `Intl` (ICU
+ * version-dependent) and real text measurement (font-dependent). Numbers go
+ * through `num` below, and label widths are ESTIMATED from a fixed
+ * per-character advance — an estimate that is stable everywhere rather than
+ * accurate on one machine.
+ */
+/** Escape the five characters that cannot appear raw in XML text or attributes. */
+export declare function escapeXml(text: string): string;
+/**
+ * A coordinate, to at most three decimals, with no trailing zeroes and no
+ * `-0`. `toFixed` then trim is stable across engines in a way that
+ * `toString` on a float is not.
+ */
+export declare function num(value: number): string;
+/**
+ * Format a data value for an axis label or legend. Fixed rules, no locale:
+ * integers plain, magnitudes at or above 10000 in thousands/millions/
+ * billions with one decimal, everything else to at most three significant
+ * decimals.
+ */
+export declare function formatValue(value: number): string;
+/**
+ * Estimated rendered width of `text` at `fontSize`, in user units.
+ *
+ * 0.55em per character is close to the average advance of the sans-serif
+ * faces this package's `font-family` names, wide enough that a label rarely
+ * overflows its reserved space and narrow enough that axes do not look
+ * padded. It is an estimate by design: measuring for real would make the
+ * output depend on which fonts a machine has.
+ */
+export declare function estimateTextWidth(text: string, fontSize: number): number;
+/** The font stack every renderer here names, ending in a generic family. */
+export declare const FONT_STACK = "ui-sans-serif, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif";
+export type TextAnchor = "start" | "middle" | "end";
+export type TextOptions = {
+    readonly fill?: string;
+    readonly anchor?: TextAnchor;
+    readonly weight?: "normal" | "bold";
+    readonly baseline?: "auto" | "middle" | "hanging";
+};
+/** A `<text>` element with escaped content. */
+export declare function text(x: number, y: number, content: string, fontSize: number, options?: TextOptions): string;
+/** A `<rect>`. */
+export declare function rect(x: number, y: number, width: number, height: number, fill: string, extra?: string): string;
+/** A straight `<line>`. */
+export declare function line(x1: number, y1: number, x2: number, y2: number, stroke: string, width?: number): string;
+/** A `<polyline>` with no fill. */
+export declare function polyline(points: ReadonlyArray<[number, number]>, stroke: string, width: number): string;
+/** A `<circle>`. */
+export declare function circle(cx: number, cy: number, r: number, fill: string): string;
+/** Wrap body elements in a complete, standalone SVG document. */
+export declare function svgDocument(width: number, height: number, background: string, body: ReadonlyArray<string>, title?: string): string;
+/**
+ * "Nice" axis bounds and tick step for a value range — the 1/2/5 x 10^n
+ * ladder every plotting library uses, chosen without looking at pixel
+ * widths so the same data always gets the same ticks.
+ */
+export declare function niceScale(min: number, max: number, targetTicks: number): {
+    min: number;
+    max: number;
+    step: number;
+    ticks: number[];
+};
+/**
+ * A fixed categorical palette. Fixed because "deterministic" has to include
+ * the colours: a chart that picks a hue from a hash of the series name
+ * still renders the same twice, but a chart that picks at random does not,
+ * and neither reads as one system beside its neighbours.
+ */
+export declare const PALETTE: ReadonlyArray<string>;
+/** The palette colour for series `index`, wrapping. */
+export declare function paletteColor(index: number): string;

package/dist/lib/svg.js

@@ -0,0 +1,168 @@
+/**
+ * SVG construction, shared by the chart, sparkline and diagram renderers.
+ *
+ * Determinism is the whole contract here: same data in, byte-identical SVG
+ * out. That rules out `toLocaleString` (locale-dependent), `Intl` (ICU
+ * version-dependent) and real text measurement (font-dependent). Numbers go
+ * through `num` below, and label widths are ESTIMATED from a fixed
+ * per-character advance — an estimate that is stable everywhere rather than
+ * accurate on one machine.
+ */
+/** Escape the five characters that cannot appear raw in XML text or attributes. */
+export function escapeXml(text) {
+    return text
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/**
+ * A coordinate, to at most three decimals, with no trailing zeroes and no
+ * `-0`. `toFixed` then trim is stable across engines in a way that
+ * `toString` on a float is not.
+ */
+export function num(value) {
+    if (!Number.isFinite(value))
+        return "0";
+    const fixed = value.toFixed(3);
+    const trimmed = fixed.replace(/\.?0+$/, "");
+    return trimmed === "-0" || trimmed === "" ? "0" : trimmed;
+}
+/**
+ * Format a data value for an axis label or legend. Fixed rules, no locale:
+ * integers plain, magnitudes at or above 10000 in thousands/millions/
+ * billions with one decimal, everything else to at most three significant
+ * decimals.
+ */
+export function formatValue(value) {
+    if (!Number.isFinite(value))
+        return String(value);
+    const abs = Math.abs(value);
+    if (abs >= 1e9)
+        return `${num(Math.round(value / 1e8) / 10)}B`;
+    if (abs >= 1e6)
+        return `${num(Math.round(value / 1e5) / 10)}M`;
+    if (abs >= 1e4)
+        return `${num(Math.round(value / 1e2) / 10)}k`;
+    if (Number.isInteger(value))
+        return String(value);
+    if (abs >= 100)
+        return value.toFixed(1).replace(/\.0$/, "");
+    if (abs >= 1)
+        return num(Math.round(value * 100) / 100);
+    return num(Math.round(value * 1000) / 1000);
+}
+/**
+ * Estimated rendered width of `text` at `fontSize`, in user units.
+ *
+ * 0.55em per character is close to the average advance of the sans-serif
+ * faces this package's `font-family` names, wide enough that a label rarely
+ * overflows its reserved space and narrow enough that axes do not look
+ * padded. It is an estimate by design: measuring for real would make the
+ * output depend on which fonts a machine has.
+ */
+export function estimateTextWidth(text, fontSize) {
+    return Math.round(text.length * fontSize * 0.55 * 100) / 100;
+}
+/** The font stack every renderer here names, ending in a generic family. */
+export const FONT_STACK = "ui-sans-serif, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif";
+/** A `<text>` element with escaped content. */
+export function text(x, y, content, fontSize, options = {}) {
+    const parts = [`x="${num(x)}"`, `y="${num(y)}"`, `font-size="${num(fontSize)}"`];
+    parts.push(`font-family="${escapeXml(FONT_STACK)}"`);
+    if (options.fill !== undefined)
+        parts.push(`fill="${escapeXml(options.fill)}"`);
+    if (options.anchor !== undefined)
+        parts.push(`text-anchor="${options.anchor}"`);
+    if (options.weight === "bold")
+        parts.push('font-weight="600"');
+    if (options.baseline !== undefined && options.baseline !== "auto") {
+        parts.push(`dominant-baseline="${options.baseline}"`);
+    }
+    return `<text ${parts.join(" ")}>${escapeXml(content)}</text>`;
+}
+/** A `<rect>`. */
+export function rect(x, y, width, height, fill, extra = "") {
+    return `<rect x="${num(x)}" y="${num(y)}" width="${num(width)}" height="${num(height)}" fill="${escapeXml(fill)}"${extra === "" ? "" : ` ${extra}`}/>`;
+}
+/** A straight `<line>`. */
+export function line(x1, y1, x2, y2, stroke, width = 1) {
+    return `<line x1="${num(x1)}" y1="${num(y1)}" x2="${num(x2)}" y2="${num(y2)}" stroke="${escapeXml(stroke)}" stroke-width="${num(width)}"/>`;
+}
+/** A `<polyline>` with no fill. */
+export function polyline(points, stroke, width) {
+    const d = points.map(([x, y]) => `${num(x)},${num(y)}`).join(" ");
+    return `<polyline points="${d}" fill="none" stroke="${escapeXml(stroke)}" stroke-width="${num(width)}" stroke-linejoin="round" stroke-linecap="round"/>`;
+}
+/** A `<circle>`. */
+export function circle(cx, cy, r, fill) {
+    return `<circle cx="${num(cx)}" cy="${num(cy)}" r="${num(r)}" fill="${escapeXml(fill)}"/>`;
+}
+/** Wrap body elements in a complete, standalone SVG document. */
+export function svgDocument(width, height, background, body, title) {
+    const head = `<svg xmlns="http://www.w3.org/2000/svg" width="${num(width)}" height="${num(height)}" viewBox="0 0 ${num(width)} ${num(height)}" role="img"${title === undefined ? "" : ' aria-labelledby="t"'}>`;
+    const titleElement = title === undefined ? "" : `<title id="t">${escapeXml(title)}</title>`;
+    const bg = background === "none" ? "" : rect(0, 0, width, height, background);
+    return `${head}${titleElement}${bg}${body.join("")}</svg>\n`;
+}
+/**
+ * "Nice" axis bounds and tick step for a value range — the 1/2/5 x 10^n
+ * ladder every plotting library uses, chosen without looking at pixel
+ * widths so the same data always gets the same ticks.
+ */
+export function niceScale(min, max, targetTicks) {
+    let low = min;
+    let high = max;
+    if (!Number.isFinite(low) || !Number.isFinite(high)) {
+        low = 0;
+        high = 1;
+    }
+    if (low === high) {
+        // A flat series still needs an axis: open a symmetric window round it.
+        const pad = low === 0 ? 1 : Math.abs(low) * 0.1;
+        low -= pad;
+        high += pad;
+    }
+    const range = high - low;
+    const rawStep = range / Math.max(1, targetTicks);
+    const magnitude = 10 ** Math.floor(Math.log10(rawStep));
+    const normalized = rawStep / magnitude;
+    const step = (normalized <= 1 ? 1 : normalized <= 2 ? 2 : normalized <= 5 ? 5 : 10) * magnitude;
+    const niceMin = Math.floor(low / step) * step;
+    const niceMax = Math.ceil(high / step) * step;
+    const ticks = [];
+    // Count the steps rather than accumulating, and snap each tick to the
+    // decimal place the step implies — `0 + 3 * 0.1` is 0.30000000000000004,
+    // and a tick label must not carry that into the rendered SVG.
+    const decimals = Math.min(12, Math.max(0, 1 - Math.floor(Math.log10(step))));
+    const snap = (value) => Number.parseFloat(value.toFixed(decimals));
+    const count = Math.round((niceMax - niceMin) / step);
+    for (let i = 0; i <= count; i++) {
+        const value = snap(niceMin + i * step);
+        ticks.push(value === 0 ? 0 : value);
+    }
+    return { min: niceMin, max: niceMax, step, ticks };
+}
+/**
+ * A fixed categorical palette. Fixed because "deterministic" has to include
+ * the colours: a chart that picks a hue from a hash of the series name
+ * still renders the same twice, but a chart that picks at random does not,
+ * and neither reads as one system beside its neighbours.
+ */
+export const PALETTE = Object.freeze([
+    "#3b6fd4",
+    "#e07b39",
+    "#4ba36b",
+    "#c2504a",
+    "#8a63c4",
+    "#7d5a4f",
+    "#d1719f",
+    "#6f7782",
+    "#b3a133",
+    "#3f9aa8",
+]);
+/** The palette colour for series `index`, wrapping. */
+export function paletteColor(index) {
+    return PALETTE[index % PALETTE.length];
+}