@tangle-network/charts 0.4.0 → 0.7.0

package/README.md

@@ -24,6 +24,26 @@ Five figures cover the decisions a benchmark reader makes:
 | `taskMatrix` | Where does each setup succeed and fail? |
 | `breakdown` | Why do attempts fail? |
 
+Operational timings also have three static figures: `heatmap` for complete recorded matrices with producer supplied pass, breach and no-data states; `latencyRange` for p50 dots, p95 bars, a supplied SLO and a minimum observation count; and `phaseWaterfall` for ordered, disjoint phase durations with unaccounted wall time shown explicitly. They return the same `Figure | Refusal` contract.
+
+```ts
+import { heatmap, latencyRange, phaseWaterfall } from "@tangle-network/charts";
+
+heatmap(paths, harnesses.map(h => ({
+  id: h.id, label: h.label,
+  cells: paths.map(p => ({ status: h[p.id].status === "blocked" ? "no-data" : h[p.id].status,
+    value: h[p.id].p95Ms === null ? null : h[p.id].p95Ms / 1000 })),
+})), { measure: "p95 latency", unit: "s", statusRule: "5 s SLO" });
+
+latencyRange([{ id: "pi", label: "pi", p50Ms: 3572, p95Ms: 4102, n: 9 }],
+  { measure: "cold create", sloMs: 5000, minN: 5 });
+
+phaseWaterfall([{ id: "route", label: "Route", ms: 5 }, { id: "restore", label: "Restore", ms: 9500 }],
+  { measure: "create", totalMs: 30398 });
+```
+
+The producer maps its own blocked or absent states to `no-data`; Charts never assigns a status from a value. `latencyRange` refuses any row below `minN`; when the producer omits those rows, pass their reasons in `excluded` so the note names them. `phaseWaterfall` refuses phases whose sum exceeds the reported total because overlapping spans cannot be drawn as a cumulative waterfall. Its input order is retained, including zero-duration phases. The producer marks known unaccounted leaves with `kind: "unaccounted"`; Charts also marks any difference between their sum and `totalMs`.
+
 The library draws and never decides.
 Ranks, intervals, frontier membership, estimate labels and pass counts come from the producer: a board record, a VerticalBench report or an agent-eval lens.
 A figure function returns a `Refusal` in place of a figure it cannot draw honestly, for example a bar over too few units, an interval that names no method, or a frontier the producer did not compute.
@@ -74,13 +94,16 @@ Identity is carried by direct labels, never by hue.
 ## Develop
 
 ```sh
-pnpm --filter @tangle-network/charts gen:css   # after editing src/figure.css or brand tokens.css
-pnpm --filter @tangle-network/charts build     # fails when src/css.generated.ts is stale
+npm ci
+npm run gen:css       # after editing src/figure.css or Brand tokens
+npm run typecheck
+npm test
+npm run build         # fails when src/css.generated.ts is stale
 ```
 
 ## Release
 
-Versions publish from the brand release workflow through npm trusted publishing, like `@tangle-network/brand` and `@tangle-network/ui`.
+Versions publish from this repository's release workflow through npm trusted publishing. Merge the verified change, then push a `vX.Y.Z` tag matching `package.json`; the workflow runs frozen install, typecheck, tests, build, and `npm publish --provenance`.
 
 ### Chart-first vertical rates
 
@@ -135,6 +158,42 @@ Optional annotations carry independent recorded facts, such as all checks passin
 Hover or focus a mark for its value, observation count, interval and annotation.
 The data table retains missing positions and full labels.
 
+### Run events, lanes, parts of a whole and small multiples
+
+A run page draws recorded events, never inferred ones. Every addition below has a static form (`Figure | Refusal`, no DOM) and a React form, takes its colours from Brand tokens through `var()`, and hatches missing data instead of drawing zero.
+
+| Need | Static | React |
+|---|---|---|
+| Vertical events (first pass, deadline, died) and shaded spans (after pass, idle, no data) | `timeSeries(rows, { ..., marks, bands })` | `<Lines marks bands>` |
+| Lanes of spans with marks; an open span runs to `now` | `timeline(lanes, { measure, now, marks })` | `<Gantt lanes now marks>` |
+| Part of a whole with untraced time hatched | `phaseWaterfall` (unaccounted leaves and the remainder are hatched) | `<Meter total segments>` |
+| One panel per arm on shared axes, with no-data panels and early ends | `smallMultiples(panels, { x, y, shared })` | `<FigureView figure>` |
+| Series that stay distinct without colour | later series add a dash and a marker shape | `series[].dash`, `series[].marker` |
+
+```ts
+type ChartMark = { at: number; label: string; kind: "pass" | "deadline" | "died" | "event" };
+type ChartBand = { from: number; to: number; label: string; kind: "after-pass" | "idle" | "missing" };
+type TimelineLane = { id: string; label: string; spans: Array<{ start: number; end: number | null; state: string; note?: string }> };
+type MultiplePanel = { id: string; label: string; unit?: string; domain?: [number, number]; points?: TimePoint[];
+  missing?: { why: string; detail?: string }; end?: { at: number; kind: ChartMark["kind"]; label?: string }; marks?: ChartMark[] };
+type MeterSegment = { label: string; value: number | null; color?: string; kind?: "measured" | "untraced" };
+```
+
+Mark kinds differ by stroke as well as colour: pass is solid, deadline dashed, died ends in a cross, and other events are dotted.
+Marks and bands appear in the figure's table (`Recorded events by …`) and, for React, in a text list under the plot.
+Static figures refuse marks or bands outside the x domain; React components throw `RangeError` for the same input, as `StackedBarChart` does.
+
+`timeline` refuses an open span without `now`, a span outside a supplied `start`/`end` window and reversed times. States named in `hatch` (default `missing`, `untraced`) are hatched; states in `muted` (default `idle`) use the muted tone.
+`Gantt` keeps its single-span `rows` input; `lanes` takes the same shape as `timeline`.
+
+`Meter` with `segments` draws each recorded part of `total`; the remainder no segment accounts for is hatched and labelled `untraced` (rename it with `untraced`). A null segment is listed as `not recorded` and takes no width; a missing total hatches the whole track. Parts that sum past the total throw.
+
+`smallMultiples` draws one panel per arm. A `missing` panel is hatched and reads `no data: <why>`; an `end` stops the line at a mark of its kind. It refuses mixed units, values outside the shared domain, points after an end and a missing panel that also carries data. `shared: "x"` keeps one x domain and requires each panel's own y `domain`. The lede counts `n of m <noun>s have data`.
+
+`FigureView` embeds any static `Figure | Refusal` in React: the wide render in containers of 720 px or more, the phone render (or the table, when a figure has none) below that, and the data, reading and method in a closed disclosure. A refusal renders as its sentence. Import `figure.css` for its styles.
+
+`node scripts/capture-run-page.mjs [dir]` (after `npm run build`) captures each addition at 1440 px light and 390 px dark; the reviewed images are `docs/screenshots/run-page-*.png`.
+
 ### Plots without visible report controls
 
 Use `renderFigure(figure, noteNumber, { presentation: "plot" })` to show the responsive plot alone.
@@ -189,30 +248,16 @@ Selection is controlled by bucket ID. Hover, focus, click, Enter, Space and touc
 ### React and package-boundary checks
 
 ```sh
-pnpm exec vitest run packages/charts/src/react/sparkline.test.tsx packages/charts/src/react/stacked-bar-chart.test.tsx
-pnpm exec vitest run packages/charts/src/package-boundary.test.ts
-pnpm exec vitest run packages/charts
-pnpm --filter @tangle-network/charts exec tsc --noEmit
-pnpm --filter @tangle-network/charts build
+npm ci
+npm run typecheck
+npm test
+npm run build
 ```
 
-The package-boundary test builds and packs Charts, installs the tarball in an OS-temporary consumer with a normal offline npm install (no peer-omission flags), asserts React/React DOM/React types cannot resolve, and executes the static root without DOM globals. It compares root exports, static SVG/tables, Refusals, report/chart/plot HTML and CSS with the untouched source implementation, then compiles a static-only consumer with `lib: ["ES2022"]`, `types: []` and `skipLibCheck: false`. Only afterward does it supply the workspace React peer/types to verify the packed React runtime and declarations. It runs under the existing root `pnpm test`; no CI workflow or shared UI smoke-script changes are needed.
+The package-boundary test builds and packs Charts, installs the tarball in an OS-temporary consumer with a normal offline npm install (no peer-omission flags), asserts React/React DOM/React types cannot resolve, and executes the static root without DOM globals. It compares root exports, static SVG/tables, Refusals, report/chart/plot HTML and CSS with the untouched source implementation, then compiles a static-only consumer with `lib: ["ES2022"]`, `types: []` and `skipLibCheck: false`. Only afterward does it supply the installed React peer/types to verify the packed React runtime and declarations. It runs under `npm test`.
 
 The component tests cover gap/zero/one/equal/negative cases, controlled identity, keyboard/touch selection, nonvisual values and resize contracts. The jsdom resize check verifies fluid/minimum-width attributes and preserved selection, **not browser-computed layout**; The retained packed-browser fixture checks Chromium at 1100px and 390px, keyboard selection, emulated touch, light/dark Brand tokens, reduced motion, and top-layer positioning inside a transformed, paint-contained panel. It passes with React 18 and React 19; the React 18 consumer also compiles the packed declarations with React 18 types. Physical touch hardware and screen-reader audio remain unchecked.
 
-### Packed browser proof
-
-Build Charts, then run the reusable fixture from the repository root.
-Pass a tarball path to test a published artifact after downloading it with npm pack.
-
-```sh
-pnpm --filter @tangle-network/charts build
-PORT=46489 node scripts/charts-browser-smoke.mjs /absolute/path/to/charts.tgz
-python3 scripts/charts-browser-proof.py http://127.0.0.1:46489 /tmp/charts-proof
-```
+### Figure browser proof
 
-Set `CHARTS_REACT_VERSION=18` to install and check an isolated React 18 runtime and type consumer.
-The default fixture uses the installed workspace React peer and bundles only the packed Charts export.
-The fixture imports Brand token CSS and creates a transformed, paint-contained panel.
-It needs Python Playwright and Chromium at `/snap/bin/chromium`.
-Receipts and screenshots are in [the retained proof](../../docs/evidence/charts-react-189/README.md).
+`node scripts/render-figures.mjs` writes a comparison page from the retained fixtures and approved speed reference. `node scripts/capture-figures.mjs` uses Playwright Chromium to capture all three figures at phone and desktop widths in light and dark themes. The reviewed images are in [`docs/screenshots`](docs/screenshots).

package/dist/events-Cw6abvgR.js

@@ -0,0 +1,491 @@
+//#region src/text.ts
+/**
+* Text: escaping, measurement and wrapping.
+*
+* Layout runs with no DOM (a Worker, a build step), so text width comes from
+* Inter's advance widths, the face tangle.tools and the reports load. Numbers
+* render in a monospace face at 0.6 em per glyph. Widths carry a 4% margin so a
+* fallback face does not collide with its neighbour.
+*/
+/** Every dynamic string in markup passes through here. */
+function esc(value) {
+	return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+const REGULAR = [
+	281,
+	288,
+	466,
+	633,
+	642,
+	982,
+	644,
+	300,
+	365,
+	365,
+	501,
+	662,
+	288,
+	460,
+	288,
+	360,
+	631,
+	407,
+	610,
+	618,
+	646,
+	608,
+	620,
+	566,
+	619,
+	620,
+	288,
+	302,
+	662,
+	662,
+	662,
+	511,
+	966,
+	690,
+	654,
+	730,
+	722,
+	601,
+	590,
+	746,
+	743,
+	269,
+	571,
+	672,
+	565,
+	903,
+	753,
+	765,
+	639,
+	765,
+	644,
+	642,
+	646,
+	744,
+	690,
+	985,
+	682,
+	679,
+	629,
+	365,
+	360,
+	365,
+	471,
+	456,
+	323,
+	562,
+	612,
+	571,
+	612,
+	583,
+	370,
+	613,
+	591,
+	242,
+	242,
+	549,
+	242,
+	876,
+	591,
+	600,
+	612,
+	612,
+	376,
+	528,
+	327,
+	591,
+	562,
+	818,
+	546,
+	562,
+	552,
+	426,
+	333,
+	426,
+	662
+];
+const SEMIBOLD = [
+	252,
+	321,
+	523,
+	644,
+	650,
+	1004,
+	663,
+	326,
+	373,
+	373,
+	540,
+	673,
+	319,
+	465,
+	319,
+	379,
+	660,
+	423,
+	623,
+	636,
+	666,
+	629,
+	640,
+	576,
+	640,
+	640,
+	319,
+	329,
+	673,
+	673,
+	673,
+	543,
+	999,
+	728,
+	659,
+	737,
+	722,
+	605,
+	588,
+	749,
+	746,
+	277,
+	580,
+	703,
+	565,
+	922,
+	759,
+	769,
+	645,
+	773,
+	652,
+	650,
+	660,
+	736,
+	728,
+	1020,
+	720,
+	713,
+	652,
+	373,
+	379,
+	373,
+	481,
+	469,
+	351,
+	574,
+	624,
+	583,
+	624,
+	591,
+	389,
+	625,
+	612,
+	262,
+	262,
+	569,
+	262,
+	900,
+	612,
+	609,
+	624,
+	624,
+	397,
+	549,
+	353,
+	612,
+	587,
+	839,
+	569,
+	588,
+	566,
+	455,
+	359,
+	455,
+	673
+];
+const EXTRA = {
+	"·": 300,
+	"×": 670,
+	"—": 1e3,
+	"–": 500,
+	"…": 900,
+	"≥": 670,
+	"≤": 670,
+	"±": 670,
+	"→": 954,
+	"−": 662
+};
+const MARGIN = 1.04;
+function textWidth(text, size, face = "sans") {
+	if (face === "mono") return text.length * .6 * size * MARGIN;
+	const table = face === "sans-semibold" ? SEMIBOLD : REGULAR;
+	let units = 0;
+	for (const ch of text) {
+		const code = ch.codePointAt(0) ?? 0;
+		units += code >= 32 && code <= 126 ? table[code - 32] : EXTRA[ch] ?? 620;
+	}
+	return units / 1e3 * size * MARGIN;
+}
+/**
+* Breaks `text` into at most `maxLines` lines no wider than `width`. Breaks at
+* spaces, and after `-`, `/`, `_` or `·` when a word alone is too wide. A line
+* that still overflows the last allowed line ends with an ellipsis; callers put
+* the full text in a `<title>` and in the table.
+*/
+function wrap(text, width, size, face = "sans", maxLines = 2) {
+	const fits = (s) => textWidth(s, size, face) <= width;
+	const lines = [];
+	const glue = [];
+	let line = "";
+	const breakLine = (next, joiner) => {
+		lines.push(line);
+		glue.push(joiner);
+		line = next;
+	};
+	for (const word of text.split(/\s+/).filter(Boolean)) {
+		const joined = line ? `${line} ${word}` : word;
+		if (fits(joined)) line = joined;
+		else if (fits(word)) {
+			if (line) breakLine(word, " ");
+			else line = word;
+		} else {
+			const pieces = word.match(/[^\-/_·]+[\-/_·]?|[\-/_·]/g) ?? [word];
+			for (const [index, piece] of pieces.entries()) {
+				const joiner = index === 0 ? " " : "";
+				const candidate = line ? `${line}${joiner}${piece}` : piece;
+				if (fits(candidate) || !line) line = candidate;
+				else breakLine(piece, joiner);
+			}
+		}
+	}
+	if (line) lines.push(line);
+	if (lines.length <= maxLines && lines.every(fits)) return {
+		lines,
+		truncated: false
+	};
+	const kept = lines.slice(0, maxLines);
+	let last = lines.slice(maxLines - 1).reduce((acc, l, i) => i === 0 ? l : `${acc}${glue[maxLines - 2 + i]}${l}`, "");
+	while (last.length > 1 && !fits(`${last}…`)) last = last.slice(0, -1);
+	kept[maxLines - 1] = `${last.trimEnd()}…`;
+	return {
+		lines: kept,
+		truncated: true
+	};
+}
+/** One `<text>` element with a line per `<tspan>`. */
+function textBlock(lines, x, y, lineHeight, attrs) {
+	if (lines.length === 1) return `<text x="${x}" y="${y}" ${attrs}>${esc(lines[0])}</text>`;
+	return `<text x="${x}" y="${y}" ${attrs}>${lines.map((line, i) => `<tspan x="${x}" dy="${i === 0 ? 0 : lineHeight}">${esc(line)}</tspan>`).join("")}</text>`;
+}
+/** Joins `parts` with " · ", starting a new line wherever the next part would pass `width`. */
+function fitLines(parts, width, size, face = "sans") {
+	const lines = [];
+	for (const part of parts) {
+		const last = lines[lines.length - 1];
+		if (last !== void 0 && textWidth(`${last} · ${part}`, size, face) <= width) lines[lines.length - 1] = `${last} · ${part}`;
+		else lines.push(part);
+	}
+	return lines;
+}
+function plural(count, one, many = `${one}s`) {
+	return count === 1 ? one : many;
+}
+/** "a, b and c" */
+function listJoin(items) {
+	if (items.length <= 1) return items.join("");
+	return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+function capitalize(text) {
+	return text.charAt(0).toUpperCase() + text.slice(1);
+}
+//#endregion
+//#region src/svg.ts
+/**
+* SVG marks. Every mark carries a class and `figure.css` maps classes to the
+* `--chart-*` tokens, so a render holds no colour and follows the page theme.
+* Geometry stays in attributes, so an SVG shown without the stylesheet keeps
+* its layout.
+*/
+const r2 = (n) => Math.round(n * 100) / 100;
+function svgRoot(width, height, inner) {
+	const h = Math.ceil(height);
+	return `<svg class="tgc-svg" xmlns="http://www.w3.org/2000/svg" width="${width}" height="${h}" viewBox="0 0 ${width} ${h}" aria-hidden="true" focusable="false">${inner}</svg>`;
+}
+/** A horizontal bar anchored at `x`, square at the baseline, 4 px round at the data end. */
+function hbar(x, y, w, h, cls) {
+	if (w <= 0) return "";
+	const r = Math.min(4, h / 2, w);
+	return `<path class="${cls}" d="M${r2(x)} ${r2(y)}h${r2(w - r)}a${r} ${r} 0 0 1 ${r} ${r}v${r2(h - 2 * r)}a${r} ${r} 0 0 1 -${r} ${r}h-${r2(w - r)}z"/>`;
+}
+function rect(x, y, w, h, cls, extra = "") {
+	if (w <= 0 || h <= 0) return "";
+	return `<rect class="${cls}" x="${r2(x)}" y="${r2(y)}" width="${r2(w)}" height="${r2(h)}"${extra ? ` ${extra}` : ""}/>`;
+}
+/**
+* 45° hatch lines clipped to a rectangle, as one path `d`. Pure geometry with
+* no pattern id, so a hatch survives duplicate SVGs on one page and hidden
+* wide/narrow renders. Shared with the React renderers.
+*/
+function hatchPath(x, y, w, h, step = 6) {
+	if (!(w > 0) || !(h > 0)) return "";
+	let d = "";
+	for (let k = step / 2; k < w + h; k += step) {
+		const x0 = Math.max(0, k - h), x1 = Math.min(w, k);
+		d += `M${r2(x + x0)} ${r2(y + k - x0)}L${r2(x + x1)} ${r2(y + k - x1)}`;
+	}
+	return d;
+}
+/** A hatched rectangle: a neutral wash plus hatch lines. Missing data is hatched, never drawn as zero. */
+function hatch(x, y, w, h, cls) {
+	if (w <= 0 || h <= 0) return "";
+	return `<g class="${cls}" data-hatched="true">${rect(x, y, w, h, "tgc-hatch-bg")}<path class="tgc-hatch" d="${hatchPath(x, y, w, h)}"/></g>`;
+}
+function line(x1, y1, x2, y2, cls) {
+	return `<line class="${cls}" x1="${r2(x1)}" y1="${r2(y1)}" x2="${r2(x2)}" y2="${r2(y2)}"/>`;
+}
+function circle(cx, cy, r, cls) {
+	return `<circle class="${cls}" cx="${r2(cx)}" cy="${r2(cy)}" r="${r}"/>`;
+}
+const MARKER_SHAPES = [
+	"circle",
+	"square",
+	"triangle",
+	"diamond"
+];
+/** A marker outline as a path `d`, centred on (cx, cy) with radius-like size `r`. Shared with the React renderers. */
+function markerPath(shape, cx, cy, r) {
+	const [x, y] = [r2(cx), r2(cy)];
+	if (shape === "square") {
+		const s = r2(r * .9);
+		return `M${r2(x - s)} ${r2(y - s)}h${r2(2 * s)}v${r2(2 * s)}h${r2(-2 * s)}z`;
+	}
+	if (shape === "triangle") {
+		const s = r2(r * 1.2);
+		return `M${x} ${r2(y - s)}L${r2(x + s)} ${r2(y + s * .8)}L${r2(x - s)} ${r2(y + s * .8)}z`;
+	}
+	if (shape === "diamond") {
+		const s = r2(r * 1.3);
+		return `M${x} ${r2(y - s)}L${r2(x + s)} ${y}L${x} ${r2(y + s)}L${r2(x - s)} ${y}z`;
+	}
+	return `M${r2(x - r)} ${y}a${r} ${r} 0 1 0 ${r2(2 * r)} 0a${r} ${r} 0 1 0 ${r2(-2 * r)} 0`;
+}
+function polyline(points, cls) {
+	return `<polyline class="${cls}" points="${points.map(([x, y]) => `${r2(x)},${r2(y)}`).join(" ")}"/>`;
+}
+function text(x, y, value, o = {}) {
+	const anchor = o.anchor && o.anchor !== "start" ? ` text-anchor="${o.anchor}"` : "";
+	const weight = o.weight === 600 ? ` font-weight="600"` : "";
+	return `<text class="${o.cls ?? "tgc-ink"}" x="${r2(x)}" y="${r2(y)}" font-size="${o.size ?? 12}"${anchor}${weight}>${esc(value)}</text>`;
+}
+/** A group whose `<title>` is the hover text for everything inside it. */
+function titled(title, inner) {
+	return `<g><title>${esc(title)}</title>${inner}</g>`;
+}
+//#endregion
+//#region src/table.ts
+/** A plain HTML table: the accessible form of a figure and its phone view. */
+function table(caption, columns, rows) {
+	const head = columns.map((c) => `<th scope="col"${c.numeric ? " class=\"tgc-n\"" : ""}>${esc(c.label)}</th>`).join("");
+	const body = rows.map((row) => `<tr>${row.map((cell, i) => i === 0 ? `<th scope="row">${esc(cell)}</th>` : `<td${columns[i]?.numeric ? " class=\"tgc-n\"" : ""}>${esc(cell)}</td>`).join("")}</tr>`).join("");
+	return `<table class="tgc-table"><caption>${esc(caption)}</caption><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table>`;
+}
+//#endregion
+//#region src/types.ts
+function isRefusal(value) {
+	return "refused" in value;
+}
+//#endregion
+//#region src/events.ts
+/**
+* Recorded events and spans drawn over a continuous x axis: vertical marks
+* (first pass, deadline, death) and shaded bands (time after the first pass,
+* idle time, no data). The producer records every position; the library never
+* places an event.
+*/
+const MARK_KINDS = [
+	"pass",
+	"deadline",
+	"died",
+	"event"
+];
+const BAND_KINDS = [
+	"after-pass",
+	"idle",
+	"missing"
+];
+/** Why the marks or bands cannot be drawn on `domain` (null when they can). Omit `domain` to check shape only. */
+function eventsGap(marks = [], bands = [], domain) {
+	const inside = (value) => !domain || value >= domain[0] && value <= domain[1];
+	for (const mark of marks) {
+		if (!mark || typeof mark.label !== "string" || !mark.label.trim()) return "Every mark needs a label.";
+		if (!MARK_KINDS.includes(mark.kind)) return `${mark.label}: unknown mark kind.`;
+		if (!Number.isFinite(mark.at) || !inside(mark.at)) return `${mark.label}: mark position must be finite and inside the axis domain.`;
+	}
+	for (const band of bands) {
+		if (!band || typeof band.label !== "string" || !band.label.trim()) return "Every band needs a label.";
+		if (!BAND_KINDS.includes(band.kind)) return `${band.label}: unknown band kind.`;
+		if (!Number.isFinite(band.from) || !Number.isFinite(band.to) || band.from >= band.to || !inside(band.from) || !inside(band.to)) return `${band.label}: a band needs finite, increasing bounds inside the axis domain.`;
+	}
+	return null;
+}
+/** Bands sit under the data; a missing band is hatched over a neutral wash. */
+function drawBands(bands, px, top, bottom, format) {
+	return bands.map((band) => {
+		const x = px(band.from), w = px(band.to) - x, cls = `tgc-band tgc-band-${band.kind}`;
+		const mark = band.kind === "missing" ? hatch(x, top, w, bottom - top, cls) : rect(x, top, w, bottom - top, cls);
+		return titled(`${band.label}: ${format(band.from)} to ${format(band.to)}`, `<g data-band="${band.kind}">${mark}</g>`);
+	}).join("");
+}
+/** Marks sit over the data; labels stagger in three rows so adjacent events stay readable. */
+function drawMarks(marks, px, top, bottom, left, right, format) {
+	return [...marks].sort((a, b) => a.at - b.at).map((mark, i) => {
+		const x = px(mark.at), y = top + 12 + i % 3 * 14;
+		const flip = x > left + (right - left) * .62;
+		let glyph = line(x, top, x, bottom, `tgc-mark tgc-mark-${mark.kind}`);
+		if (mark.kind === "died") glyph += line(x - 4, bottom - 8, x + 4, bottom, "tgc-mark tgc-mark-died") + line(x - 4, bottom, x + 4, bottom - 8, "tgc-mark tgc-mark-died");
+		glyph += text(flip ? x - 4 : x + 4, y, mark.label, {
+			size: 11,
+			anchor: flip ? "end" : "start",
+			cls: "tgc-mark-label"
+		});
+		return titled(`${mark.label}: ${format(mark.at)}`, `<g data-mark="${mark.kind}">${glyph}</g>`);
+	}).join("");
+}
+/** The table form of marks and bands, in axis order. Empty when there are none. */
+function eventsTable(marks, bands, axisLabel, format) {
+	if (!marks.length && !bands.length) return "";
+	const rows = [...marks.map((mark) => ({
+		at: mark.at,
+		cells: [
+			mark.label,
+			mark.kind,
+			format(mark.at),
+			""
+		]
+	})), ...bands.map((band) => ({
+		at: band.from,
+		cells: [
+			band.label,
+			band.kind === "missing" ? "no data" : band.kind,
+			format(band.from),
+			format(band.to)
+		]
+	}))].sort((a, b) => a.at - b.at);
+	return table(`Recorded events by ${axisLabel}`, [
+		{ label: "Event" },
+		{ label: "Kind" },
+		{
+			label: `${axisLabel} from`,
+			numeric: true
+		},
+		{
+			label: `${axisLabel} to`,
+			numeric: true
+		}
+	], rows.map((row) => row.cells));
+}
+const EVENTS_READ = "Vertical rules mark recorded events (solid: pass, dashed: deadline, cross: died, dotted: other); tinted spans are recorded periods and hatched spans have no data.";
+//#endregion
+export { listJoin as C, wrap as D, textWidth as E, fitLines as S, textBlock as T, svgRoot as _, eventsTable as a, capitalize as b, MARKER_SHAPES as c, hatchPath as d, hbar as f, rect as g, polyline as h, eventsGap as i, circle as l, markerPath as m, drawBands as n, isRefusal as o, line as p, drawMarks as r, table as s, EVENTS_READ as t, hatch as u, text as v, plural as w, esc as x, titled as y };