visuals
HTML pages (html_preview, html_render) and native inline charts, positioned diagrams and sortable tables in agent replies.
The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install divergence/visuals@0.2.2
Visuals — official plugin
divergence/visuals provides publish_visual for interactive, native visual replies. It ships enabled on a fresh install; an existing install keeps the choice it has, and users can turn it off or on in Settings → Plugins. It starts only when a reply first contains one of its fences and loads Pele only on the first Mermaid fence, so a chat without fences pays nothing. Its only requested permission is tools.provide.
HTML pages (T3 Code's html_preview and html_render)
html.ts holds T3's contract (pingdotgg/t3code b24f0fbb): the tool names, descriptions, limits (HTML 1–512000 UTF-16 units, title 1–200, preview width 240–1600 with 728 by default, frame height 80–2000), the result shapes and messages, and the theme bootstrap with Divergence's colours. Both tools are direct, so in code mode they stay tools of their own and the preview's PNG reaches the agent as an MCP image part.
html_previewsends the themed page tohost/web.preview. With a web view it answers T3's metadata as text and structured content plus the PNG. Without one it is an error,HtmlBackendUnavailable: <raw reason>, with no image, and no screenshot is made up.html_rendersaves the agent's page unchanged as ahtmlv1 transcript artifact (the host stamps the owner) and answers T3'shtmlRenderreference and message. Measuredheightsare not supplied: the frame follows the live page's own height, and the agent's height shows only until the page has measured itself.- Inline (
html-view.ts) the page is live (ui.webDocument): borderless in the reply, as wide as the column and as tall as the page, with one small glass Open in panel control. The panel is a detail-pane tab (thedivergence/tabsservice): the page live again, its Source, Copy and Save (kernel/copy_text,kernel/save_text, both after a click).
The renderer is the system's web view (crates/host/src/web): WKWebView on macOS, so a page behaves as it would in Safari, WebView2 on Windows, as in Edge, and WebKitGTK on Linux, which the app draws itself. The difference from T3 is that pages are offline: remote URLs and local image paths never load (missingImages lists the paths a page names). Where the web view cannot start, the page says why and its source, copy and save still work.
Version 2 supports responsive multi-panel compositions: bar (grouped/stacked/ percent; horizontal/vertical), line, area, scatter/bubble, pie/donut, heatmap, histogram, range/timeline, waterfall and boxplot, plus metrics, text, typed tables and positioned diagrams. document.ts defines the strict, bounded JSON schema; rules.md is the agent-facing reference. Version 1 documents still replay.
Rendering and interaction
Rust/GPUI draws every shape, label, control and floating tooltip. A pinned, DOM-free D3 math subset computes scales, numeric/UTC ticks and paths inside QuickJS; there is no browser, JavaScript UI execution, graph auto-layout, network, file, process or plugin-storage access. math.LICENSES.txt includes provenance and licenses; scripts/bundle-visuals-math.mjs reproduces the readable bundle.
Charts use the native canvas's onResize({width,height}) logical-pixel measurement, not a scaled viewBox. Text remains readable as panels grow or wrap. Compact legends keep original domains, colors and percentage denominators when hidden. Null breaks paths and stays explicitly missing in shared bar inspection.
Hover opens a clamped floating tooltip; click pins/unpins. Arrow keys, Home/End traverse observations, Enter/Space pin, Escape clears inspection. In the expanded overlay Escape unpins first, then closes. Tables retain stable raw row identity, sort nulls last in either direction, paginate and expose full selected values. Diagram node details remain accessible through a native picker.
State and cached geometry belong to each artifact's ctx.state, with separate panels and inline/expanded inspection. Hover does not recompute paths. Native resize reports are change-only and coalesced off-paint. No JavaScript frame loop or render-time notification runs.
Persistence and compatibility
The host owns immutable transcript artifacts. ctx.artifacts.publish persists the complete document independently of the surrounding tool result, including discarded acknowledgements and later code-mode errors. The plugin registers removable visual renderers for versions 1 and 2; Source retains original input and Data retains all raw values, including hidden series and nulls.
This plugin requires the updated native host and canvas resize API. Older hosts without artifact support fail with an explicit update message. Invalid persisted documents keep their readable summary and expose a validation error.
Verification
node --import ./plugins/testing/register.mjs --test plugins/visuals/*.test.ts
pnpm -C plugins typecheck
pnpm -C plugins exec prettier --check 'visuals/**/*.{ts,json,md}'
Geometry tests use asymmetric data and independent numeric expectations; view tests exercise real native element factories and handlers. Native desktop checks and app-owned Metal captures supplement these tests; they do not use a browser.
Permissions in 0.2.2
Files
// Pure pixel geometry. No viewBox, DOM, resources, or mutation of the inert source document.
import type { CanvasCommand, Color, HexColor, PathStep } from "divergence";
import type { Cell, NumberFormat, RichChart, Table } from "./document.ts";
import { arc, area, curveLinear, curveStepAfter, interpolateRgb, line, pie, scaleLinear, scaleUtc } from "./math.js";
import type { PathContext, Sector } from "./math.js";
// Mid-luminance categorical colors, independent of semantic/focus tokens in either theme.
export const PALETTE: readonly string[] = [
"#7299E6",
"#38AAA0",
"#A38ADB",
"#D5A34A",
"#599EBB",
"#C186B2",
"#8499CB",
"#91AA62",
];
const colorOf = (index: number) => PALETTE[index % PALETTE.length]! as HexColor;
const alpha = (color: HexColor, opacity: number): HexColor =>
`${color}${Math.round(opacity * 255)
.toString(16)
.padStart(2, "0")}`;
// D3 emits rgb(r, g, b), while native canvas accepts hex, not CSS color syntax.
const nativeRgb = (rgb: string): HexColor =>
`#${rgb
.match(/\d+/g)!
.map((v) => Number(v).toString(16).padStart(2, "0"))
.join("")}`;
const TAU = Math.PI * 2;
const GRID = "mutedForeground/14";
const INK = "mutedForeground";
export type Hit =
| { kind: "x"; left: number; right: number; top: number; bottom: number }
| { kind: "point"; x: number; y: number; radius: number }
| { kind: "rect"; x: number; y: number; width: number; height: number }
// Radians clockwise from twelve o'clock, in [0, 2π]. Start inclusive, end exclusive;
// the outer radius is inclusive and the inner radius exclusive (a pie includes its center).
| {
kind: "sector";
cx: number;
cy: number;
innerRadius: number;
outerRadius: number;
startAngle: number;
endAngle: number;
};
export interface InspectItem {
// Exact source array indices, not labels, values, sorted positions, or visible-series indices.
id: string;
label: string;
x: number;
y: number;
rows: { label: string; value: string; color?: string }[];
hit: Hit;
}
export interface ChartScene {
width: number;
height: number;
commands: CanvasCommand[];
// Items follow paint order; inspection resolves equal-distance/shape overlaps from the end.
items: InspectItem[];
legend: { index: number; label: string; color: string }[];
plot: { left: number; top: number; width: number; height: number };
empty?: string;
}
export function formatValue(value: number, format?: NumberFormat): string {
const style = format?.style ?? "number";
const precision = format?.precision ?? (style === "currency" ? 2 : style === "percent" ? 1 : 2);
let scaled = style === "percent" ? value * 100 : value;
let suffix = style === "percent" ? "%" : "";
if (style === "compact") {
const magnitude = Math.abs(value);
const [divisor, symbol] =
magnitude >= 1e12
? [1e12, "T"]
: magnitude >= 1e9
? [1e9, "B"]
: magnitude >= 1e6
? [1e6, "M"]
: magnitude >= 1e3
? [1e3, "K"]
: [1, ""];
scaled /= divisor;
suffix = symbol;
}
// Tiny nonzero observations must not masquerade as zero. Significant digits stay bounded.
let number =
scaled !== 0 && Math.abs(scaled) < 0.5 * 10 ** -precision
? scaled.toExponential(precision)
: scaled.toFixed(precision);
if (style === "number" && format?.precision === undefined)
number = Math.abs(value) >= 1e9 ? value.toExponential(5) : String(Number(value.toPrecision(6)));
if (style !== "currency" && format?.precision === undefined)
number = number.replace(/(\.\d*?[1-9])0+(e|$)|\.0+(e|$)/, "$1$2$3");
if (Number(number) === 0) number = number.replace(/^-/, "");
return `${style === "currency" ? `${format!.currency} ` : ""}${number}${suffix}${format?.unit ? ` ${format.unit}` : ""}`;
}
function text(
scene: ChartScene,
x: number,
y: number,
value: string,
align: "left" | "center" | "right" = "center",
max = 20,
) {
const label = value.length > max ? `${value.slice(0, Math.max(1, max - 1))}…` : value;
scene.commands.push({ op: "text", x, y, text: label, size: 11, color: INK, align, baseline: "middle" });
}
function rect(scene: ChartScene, x: number, y: number, width: number, height: number, fill: Color) {
scene.commands.push({ op: "rect", x, y, width, height, fill });
}
function itemRect(
scene: ChartScene,
id: string,
label: string,
x: number,
y: number,
width: number,
height: number,
rows: InspectItem["rows"],
color: Color,
) {
rect(scene, x, y, width, height, color);
scene.items.push({
id,
label,
x: x + width / 2,
y: y + height / 2,
rows,
hit: { kind: "rect", x, y, width, height },
});
}
function dot(scene: ChartScene, x: number, y: number, radius: number, color: Color) {
scene.commands.push({
op: "roundRect",
x: x - radius,
y: y - radius,
width: radius * 2,
height: radius * 2,
radius,
fill: color,
});
}
function sampled<T>(values: readonly T[], max: number): T[] {
if (values.length <= max) return [...values];
return Array.from({ length: max }, (_, i) => values[Math.round((i * (values.length - 1)) / (max - 1))]!);
}
function extent(values: readonly number[], zero = false): [number, number] {
let min = zero ? 0 : Infinity,
max = zero ? 0 : -Infinity;
for (const value of values) {
min = Math.min(min, value);
max = Math.max(max, value);
}
if (values.length === 0) return [0, 1];
if (min === max) {
const padding = Math.max(Math.abs(min) * 0.05, 1);
return [min - padding, max + padding];
}
return [min, max];
}
interface NumericScale {
(value: number): number;
ticks(count: number): number[];
range(values: readonly number[]): NumericScale;
}
function numericScale(domain: readonly number[], range: readonly number[], nice = false): NumericScale {
// D3's reciprocal tick increments can overflow for tiny spans, even between
// normal values. Shift narrow normal domains to zero before scaling so rounded
// ticks cannot fall outside adjacent endpoints; retain the subnormal normalization.
const magnitude = Math.max(Math.abs(domain[0]!), Math.abs(domain[1]!));
const span = Math.abs(domain[1]! - domain[0]!);
const narrow = magnitude >= 1e-300 && span < 1e-300;
const offset = narrow ? domain[0]! : 0;
const divisor = narrow ? span : magnitude < 1e-300 ? magnitude : 1;
const math = scaleLinear()
.domain(domain.map((v) => (v - offset) / divisor))
.range(range);
if (nice) math.nice(4);
const scale: NumericScale = Object.assign((value: number) => math((value - offset) / divisor), {
ticks: (count: number) => [...new Set(math.ticks(count).map((v) => v * divisor + offset))],
range: (values: readonly number[]) => {
math.range(values);
return scale;
},
});
return scale;
}
function valueScale(scene: ChartScene, values: readonly number[], zero = false, horizontal = false, percent = false) {
const p = scene.plot;
return numericScale(
percent ? [0, 1] : extent(values, zero),
horizontal ? [p.left, p.left + p.width] : [p.top + p.height, p.top],
true,
);
}
function valueAxis(scene: ChartScene, scale: NumericScale, format?: NumberFormat, horizontal = false) {
const p = scene.plot;
const count = horizontal
? Math.max(2, Math.min(5, Math.floor(p.width / 90)))
: Math.max(2, Math.min(4, Math.floor(p.height / 48)));
// Tick count is a density target, not a hard limit. Sampling an evenly spaced
// sequence drops arbitrary middle ticks and makes its intervals irregular.
for (const value of scale.ticks(count)) {
const v = scale(value);
if (horizontal) {
rect(scene, v, p.top, Math.min(1, p.left + p.width - v), p.height, GRID);
text(scene, v, p.top + p.height + 13, formatValue(value, format));
} else {
rect(scene, p.left, v, p.width, Math.min(1, p.top + p.height - v), GRID);
text(scene, p.left - 7, v, formatValue(value, format), "right", Math.max(2, Math.floor((p.left - 8) / 6)));
}
}
}
function categories(scene: ChartScene, labels: readonly string[], horizontal = false) {
const p = scene.plot;
const length = horizontal ? p.height : p.width;
const labelWidth = Math.max(48, Math.min(120, labels.reduce((max, label) => Math.max(max, label.length), 0) * 6 + 6));
const max = Math.max(2, Math.min(horizontal ? 4 : 5, Math.floor(length / (horizontal ? 32 : labelWidth))));
const indices = sampled(
labels.map((_, i) => i),
max,
);
for (const i of indices) {
const v = ((i + 0.5) * length) / labels.length;
if (horizontal) text(scene, p.left - 7, p.top + v, labels[i]!, "right", Math.max(2, Math.floor((p.left - 8) / 6)));
else
text(
scene,
p.left + v,
p.top + p.height + 13,
labels[i]!,
"center",
Math.max(2, Math.min(20, Math.floor(length / indices.length / 6))),
);
}
}
function utc(value: number): string {
return new Date(value).toISOString();
}
function coordinateScale(scene: ChartScene, values: readonly number[], time: boolean) {
const p = scene.plot;
// No nice expansion here: irregular numeric/time coordinates occupy the full available width.
const domain =
values[0] === values[values.length - 1]
? [Math.max(-8_640_000_000_000_000, values[0]! - 1), Math.min(8_640_000_000_000_000, values[0]! + 1)]
: [values[0]!, values[values.length - 1]!];
const scale = time
? scaleUtc()
.domain(domain)
.range([p.left, p.left + p.width])
: numericScale(domain, [p.left, p.left + p.width]);
const span = domain[1]! - domain[0]!;
const count = Math.max(2, Math.min(5, Math.floor(p.width / (time ? 125 : 90))));
for (const tick of scale.ticks(count)) {
const value = +tick;
const x = scale(value);
rect(scene, x, p.top, Math.min(1, p.left + p.width - x), p.height, GRID);
const label = time
? span < 1000
? utc(value).slice(11, 23)
: span < 86_400_000
? utc(value).slice(11, 19)
: span < 31_536_000_000
? utc(value).slice(5, 10)
: utc(value).split("T")[0]!
: formatValue(value);
text(scene, x, p.top + p.height + 13, label);
}
return (value: number) => scale(value);
}
function labels(scene: ChartScene, chart: RichChart) {
const p = scene.plot;
if ("xLabel" in chart && chart.xLabel)
text(scene, p.left + p.width / 2, scene.height - 9, chart.xLabel, "center", Math.floor(p.width / 6));
// Native text is never scaled/rotated; the y title stays a small horizontal caption.
if ("yLabel" in chart && chart.yLabel) text(scene, p.left, 6, chart.yLabel, "left", Math.floor(p.width / 6));
}
// D3's Canvas-like contexts are math only. Arcs split at quadrants into bounded cubics.
// The sign of the sweep is preserved, including the reverse inner donut subpath.
function pathContext(dx = 0, dy = 0): PathContext & { steps: PathStep[] } {
const steps: PathStep[] = [];
let px = NaN,
py = NaN,
sx = NaN,
sy = NaN;
return {
steps,
moveTo(x, y) {
steps.push(["moveTo", x + dx, y + dy]);
px = sx = x;
py = sy = y;
},
lineTo(x, y) {
steps.push(["lineTo", x + dx, y + dy]);
px = x;
py = y;
},
closePath() {
steps.push(["close"]);
px = sx;
py = sy;
},
arc(cx, cy, r, start, end, ccw) {
const ax = cx + r * Math.cos(start),
ay = cy + r * Math.sin(start);
if (Number.isNaN(px)) this.moveTo(ax, ay);
else if (Math.abs(px - ax) + Math.abs(py - ay) > 1e-8) this.lineTo(ax, ay);
let sweep = end - start;
if (Math.abs(sweep) >= TAU) sweep = ccw ? -TAU : TAU;
else if (ccw && sweep > 0) sweep -= TAU;
else if (!ccw && sweep < 0) sweep += TAU;
const stop = sweep === end - start ? end : start + sweep,
quarter = Math.PI / 2;
// Quadrant splits keep every control point inside the circle's native pixel bounds.
for (let a = start; a !== stop;) {
const boundary = (sweep > 0 ? Math.floor(a / quarter) + 1 : Math.ceil(a / quarter) - 1) * quarter;
const b = sweep > 0 ? Math.min(boundary, stop) : Math.max(boundary, stop);
const k = (4 / 3) * Math.tan((b - a) / 4);
const x0 = cx + r * Math.cos(a),
y0 = cy + r * Math.sin(a);
const x1 = cx + r * Math.cos(b),
y1 = cy + r * Math.sin(b);
steps.push([
"cubicTo",
x0 - r * Math.sin(a) * k + dx,
y0 + r * Math.cos(a) * k + dy,
x1 + r * Math.sin(b) * k + dx,
y1 - r * Math.cos(b) * k + dy,
x1 + dx,
y1 + dy,
]);
px = x1;
py = y1;
a = b;
}
},
};
}
function sectorSteps(hit: Extract<Hit, { kind: "sector" }>): PathStep[] {
const context = pathContext(hit.cx, hit.cy);
arc().innerRadius(hit.innerRadius).outerRadius(hit.outerRadius).context(context)({
value: 1,
startAngle: hit.startAngle,
endAngle: hit.endAngle,
padAngle: 0,
});
return context.steps;
}
type SeriesChart = Extract<RichChart, { chart: "bar" | "line" | "area" }>;
type Span = { low: number; high: number; raw: number } | null;
function stacked(chart: SeriesChart): { spans: Span[][]; totals: number[]; observed: boolean[]; percent: boolean } {
const mode = chart.chart === "line" ? "none" : chart.stack;
const totals = chart.x.values.map((_, i) =>
chart.series.reduce((sum, s) => (s.values[i] === null ? sum : sum + s.values[i]!), 0),
);
const observed = chart.x.values.map((_, i) => chart.series.some((s) => s.values[i] !== null));
const positive = chart.x.values.map(() => 0),
negative = [...positive];
const spans = chart.series.map((s) =>
s.values.map((raw, i) => {
if (raw === null || (mode === "percent" && totals[i] === 0)) return null;
const value = mode === "percent" ? raw / totals[i]! : raw;
const offsets = value < 0 ? negative : positive;
const low = mode === "none" ? 0 : offsets[i]!;
const high = low + value;
offsets[i] = high;
return { low, high, raw };
}),
);
return { spans, totals, observed, percent: mode === "percent" };
}
function overlays(scene: ChartScene, chart: SeriesChart, scale: NumericScale, horizontal: boolean) {
const p = scene.plot;
// Typed overlays expand the original value domain, and are painted behind the data.
// Labels/ranges are inspection rows rather than N extra native text commands.
chart.bands?.forEach((band, index) => {
const a = scale(band.from),
b = scale(band.to);
itemRect(
scene,
`band:${index}`,
band.label,
horizontal ? a : p.left,
horizontal ? p.top : b,
horizontal ? b - a : p.width,
horizontal ? p.height : a - b,
[
{ label: "From", value: formatValue(band.from, chart.format) },
{ label: "To", value: formatValue(band.to, chart.format) },
],
"mutedForeground/7",
);
});
chart.references?.forEach((reference, index) => {
const v = scale(reference.value);
const thickness = Math.min(1, horizontal ? p.width : p.height);
itemRect(
scene,
`reference:${index}`,
reference.label,
horizontal ? Math.min(v, p.left + p.width - thickness) : p.left,
horizontal ? p.top : Math.min(v, p.top + p.height - thickness),
horizontal ? thickness : p.width,
horizontal ? p.height : thickness,
[{ label: reference.label, value: formatValue(reference.value, chart.format) }],
"mutedForeground/40",
);
});
}
function seriesScene(scene: ChartScene, chart: SeriesChart, hidden: readonly number[]) {
const p = scene.plot,
n = chart.x.values.length;
const { spans, totals, observed, percent } = stacked(chart);
const horizontal = chart.chart === "bar" && chart.orientation === "horizontal";
const domain = spans.flatMap((s) =>
s.flatMap((v) => (v === null ? [] : chart.chart === "line" ? [v.high] : [v.low, v.high])),
);
for (const band of chart.bands ?? []) domain.push(band.from, band.to);
for (const ref of chart.references ?? []) domain.push(ref.value);
const scale = valueScale(scene, domain, chart.chart !== "line", horizontal, percent);
valueAxis(scene, scale, percent ? { style: "percent" } : chart.format, horizontal);
overlays(scene, chart, scale, horizontal);
scene.legend = chart.series.map((s, index) => ({ index, label: s.name, color: colorOf(index) }));
if (chart.chart === "bar") {
categories(scene, chart.x.values, horizontal);
const band = (horizontal ? p.height : p.width) / n;
const grouped = chart.stack === "none",
count = grouped ? chart.series.length : 1;
const thickness = (band * 0.8) / count;
chart.series.forEach((s, si) => {
if (hidden.includes(si)) return;
spans[si]!.forEach((v, i) => {
if (v === null) return;
const a = scale(v.low),
b = scale(v.high);
const offset = i * band + band * 0.1 + (grouped ? si * thickness : 0);
const rows = [{ label: s.name, value: formatValue(v.raw, chart.format), color: colorOf(si) }];
if (percent)
rows.push({
label: "Share of original total",
value: formatValue(v.raw / totals[i]!, { style: "percent" }),
color: colorOf(si),
});
itemRect(
scene,
`series:${si}:value:${i}`,
chart.x.values[i]!,
horizontal ? Math.min(a, b) : p.left + offset,
horizontal ? p.top + offset : Math.min(a, b),
horizontal ? Math.abs(a - b) : thickness,
horizontal ? thickness : Math.abs(a - b),
rows,
colorOf(si),
);
});
});
} else {
const positions =
chart.x.type === "category"
? (categories(scene, chart.x.values), chart.x.values.map((_, i) => p.left + ((i + 0.5) * p.width) / n))
: (() => {
const x = coordinateScale(scene, chart.x.values, chart.x.type === "time");
return chart.x.values.map(x);
})();
const curve = chart.interpolation === "step" ? curveStepAfter : curveLinear;
chart.series.forEach((_, si) => {
if (hidden.includes(si)) return;
const context = pathContext();
const data = spans[si]!;
if (chart.chart === "line")
line<Span>()
.defined((v) => v !== null)
.x((_, i) => positions[i]!)
.y((v) => scale(v!.high))
.curve(curve)
.context(context)(data);
else
area<Span>()
.defined((v) => v !== null)
.x((_, i) => positions[i]!)
.y0((v) => scale(v!.low))
.y1((v) => scale(v!.high))
.curve(curve)
.context(context)(data);
if (context.steps.length)
scene.commands.push({
op: "path",
d: context.steps,
...(chart.chart === "line" ? { stroke: colorOf(si), lineWidth: 2 } : { fill: alpha(colorOf(si), 0.45) }),
});
// Dense plots retain every path vertex and observation; only optional point decoration goes away.
if (n <= p.width / 8)
data.forEach((v, i) => {
if (v !== null) dot(scene, positions[i]!, scale(v.high), 2.5, colorOf(si));
});
});
positions.forEach((x, i) => {
const visible = chart.series.map((s, si) => ({ s, si })).filter(({ si }) => !hidden.includes(si));
if (!visible.length) return;
const rows: InspectItem["rows"] = visible.map(({ s, si }) => ({
label: s.name,
value: s.values[i] === null ? "Missing" : formatValue(s.values[i]!, chart.format),
color: colorOf(si),
}));
if (percent)
rows.push({
label: "Original total",
value: !observed[i]
? "Missing (no observations)"
: totals[i] === 0
? "No total (empty)"
: formatValue(totals[i]!, chart.format),
});
const last = visible
.map(({ si }) => spans[si]![i])
.filter((v) => v !== null)
.at(-1);
if (!last && !percent) return; // A null gap has no observation to inspect.
scene.items.push({
id: `x:${i}`,
label: chart.x.type === "time" ? utc(chart.x.values[i] as number) : String(chart.x.values[i]),
x,
y: last ? scale(last.high) : p.top + p.height,
rows,
hit: {
kind: "x",
left: i === 0 ? p.left : (positions[i - 1]! + x) / 2,
right: i === n - 1 ? p.left + p.width : (x + positions[i + 1]!) / 2,
top: p.top,
bottom: p.top + p.height,
},
});
});
}
if (hidden.length && chart.series.every((_, i) => hidden.includes(i))) scene.empty = "All series hidden";
else if (observed.every((v) => !v)) scene.empty = "No observations";
else if (percent && totals.every((t) => t === 0)) scene.empty = "No total — percentages are undefined";
// Explicit per-category zero-total states, also in partially populated percent charts.
if (chart.chart === "bar" && percent && !scene.empty)
totals.forEach((total, i) => {
if (total === 0)
text(
scene,
horizontal ? p.left + p.width / 2 : p.left + ((i + 0.5) * p.width) / n,
horizontal ? p.top + ((i + 0.5) * p.height) / n : p.top + p.height / 2,
observed[i] ? "No total" : "Missing",
);
});
}
function scatterScene(scene: ChartScene, chart: Extract<RichChart, { chart: "scatter" }>, hidden: readonly number[]) {
const p = scene.plot,
all = chart.series.flatMap((s) => s.points);
const xs = extent(all.map((v) => v.x)),
ys = valueScale(
scene,
all.map((v) => v.y),
);
const maxSize = Math.max(...all.map((v) => v.size ?? 0));
// Reserve the largest bubble at every edge, without changing the numerical domain on hiding.
const radiusMax = Math.min(maxSize > 0 ? 20 : 4, p.width / 8, p.height / 8),
minRadius = Math.min(4, radiusMax);
const x = numericScale(xs, [p.left + radiusMax, p.left + p.width - radiusMax]);
const y = ys.range([p.top + p.height - radiusMax, p.top + radiusMax]);
valueAxis(scene, x, chart.xFormat, true);
valueAxis(scene, y, chart.format);
scene.legend = chart.series.map((s, index) => ({ index, label: s.name, color: colorOf(index) }));
chart.series.forEach((s, si) => {
if (hidden.includes(si)) return;
s.points.forEach((point, i) => {
const px = x(point.x),
py = y(point.y);
const radius =
point.size === undefined ? minRadius : maxSize === 0 ? 0 : radiusMax * Math.sqrt(point.size / maxSize);
dot(scene, px, py, radius, alpha(colorOf(si), 0.8));
const rows: InspectItem["rows"] = [
{ label: chart.xLabel ?? "X", value: formatValue(point.x, chart.xFormat) },
{ label: chart.yLabel ?? "Y", value: formatValue(point.y, chart.format), color: colorOf(si) },
];
if (point.size !== undefined) rows.push({ label: chart.sizeLabel ?? "Size", value: formatValue(point.size) });
scene.items.push({
id: `series:${si}:point:${i}`,
label: point.label ?? s.name,
x: px,
y: py,
rows,
hit: { kind: "point", x: px, y: py, radius: Math.max(radius, minRadius) },
});
});
});
if (chart.series.every((_, i) => hidden.includes(i))) scene.empty = "All series hidden";
}
function pieScene(scene: ChartScene, chart: Extract<RichChart, { chart: "pie" | "donut" }>, hidden: readonly number[]) {
const p = scene.plot,
total = chart.parts.reduce((sum, part) => sum + part.value, 0);
scene.legend = chart.parts.map((part, index) => ({ index, label: part.label, color: colorOf(index) }));
if (total === 0) {
scene.empty = "No total — percentages are undefined";
return;
}
const radius = Math.min(p.width, p.height) / 2,
inner = chart.chart === "donut" ? radius * 0.6 : 0;
const cx = p.left + p.width / 2,
cy = p.top + p.height / 2;
const divisor = total < 1e-300 ? Math.max(...chart.parts.map((p) => p.value)) : 1;
const wedges: Sector[] = pie<(typeof chart.parts)[number]>()
.sort(null)
.value((p) => p.value / divisor)(chart.parts);
const singlePart = chart.parts.filter((p) => p.value > 0).length === 1;
wedges.forEach((wedge, index) => {
if (hidden.includes(index) || chart.parts[index]!.value === 0) return;
// D3's accumulated last angle can exceed 2π by one ulp. Bound the generated
// geometry, not the observations, so it cannot create a spurious fifth quadrant.
const hit: Extract<Hit, { kind: "sector" }> = {
kind: "sector",
cx,
cy,
innerRadius: inner,
outerRadius: radius,
startAngle: Math.min(TAU, wedge.startAngle),
endAngle: Math.min(TAU, wedge.endAngle),
};
if (singlePart) {
// An exact native circle/ring avoids 54 duplicated donut path points for one part
// (the schema reserves 40), and does not fake a hole using an opaque surface mask.
// Native quad strokes are inset borders, not centered path strokes.
const r = radius;
scene.commands.push({
op: "roundRect",
x: cx - r,
y: cy - r,
width: r * 2,
height: r * 2,
radius: r,
...(inner ? { stroke: colorOf(index), lineWidth: radius - inner } : { fill: colorOf(index) }),
});
} else scene.commands.push({ op: "path", d: sectorSteps(hit), fill: colorOf(index) });
const mid = (hit.startAngle + hit.endAngle) / 2,
r = (inner + radius) / 2;
const part = chart.parts[index]!;
scene.items.push({
id: `part:${index}`,
label: part.label,
x: cx + Math.sin(mid) * r,
y: cy - Math.cos(mid) * r,
rows: [
{ label: part.label, value: formatValue(part.value, chart.format), color: colorOf(index) },
{ label: "Share of original total", value: formatValue(part.value / total, { style: "percent" }) },
],
hit,
});
});
if (chart.chart === "donut") {
const value = formatValue(total, chart.format);
scene.commands.push({
op: "text",
x: cx,
y: cy + (chart.centerLabel ? 10 : 0),
text: value,
size: Math.min(26, Math.max(11, (inner * 3) / Math.max(1, value.length))),
color: "foreground",
align: "center",
baseline: "middle",
});
if (chart.centerLabel)
text(scene, cx, cy - 15, chart.centerLabel, "center", Math.max(2, Math.floor((inner * 2) / 6)));
}
if (!scene.items.length) scene.empty = "All parts hidden";
}
function heatmapScene(scene: ChartScene, chart: Extract<RichChart, { chart: "heatmap" }>) {
const p = scene.plot,
values = chart.cells.flatMap((c) => (c.value === null ? [] : [c.value]));
categories(scene, chart.x);
categories(scene, chart.y, true);
const [min, max] = extent(values),
magnitude = Math.max(Math.abs(min), Math.abs(max));
const sequential = interpolateRgb("#B4C5DA", PALETTE[0]!);
const low = interpolateRgb("#B4C5DA", PALETTE[1]!),
high = interpolateRgb("#B4C5DA", PALETTE[2]!);
chart.cells.forEach((cell, index) => {
const x = p.left + (cell.x * p.width) / chart.x.length,
y = p.top + (cell.y * p.height) / chart.y.length;
const width = p.width / chart.x.length,
height = p.height / chart.y.length;
const color: Color =
cell.value === null
? "mutedForeground/6"
: nativeRgb(
chart.scale === "sequential"
? sequential((cell.value - min) / (max - min))
: (cell.value < 0 ? low : high)(Math.abs(cell.value) / magnitude),
);
itemRect(
scene,
`cell:${index}`,
`${chart.y[cell.y]} · ${chart.x[cell.x]}`,
x,
y,
width,
height,
[
{ label: chart.xLabel ?? "X", value: chart.x[cell.x]! },
{ label: chart.yLabel ?? "Y", value: chart.y[cell.y]! },
{ label: "Value", value: cell.value === null ? "Missing" : formatValue(cell.value, chart.format), color },
],
color,
);
});
if (values.length && scene.height >= 160 && scene.width >= 100) {
const width = Math.min(160, p.width),
x = p.left + p.width - width,
y = p.top + p.height + 32;
for (let i = 0; i < 24; i++) {
const t = i / 23;
const color = chart.scale === "sequential" ? sequential(t) : t < 0.5 ? low(1 - t * 2) : high(t * 2 - 1);
rect(scene, x + (i * width) / 24, y, width / 24, 6, nativeRgb(color));
}
text(scene, x, y + 18, formatValue(chart.scale === "sequential" ? min : -magnitude, chart.format), "left");
text(scene, x + width, y + 18, formatValue(chart.scale === "sequential" ? max : magnitude, chart.format), "right");
}
if (!values.length) scene.empty = "No observations — all cells are missing";
}
function histogramScene(scene: ChartScene, chart: Extract<RichChart, { chart: "histogram" }>) {
const p = scene.plot,
x = coordinateScale(scene, [chart.bins[0]!.from, chart.bins.at(-1)!.to], false);
const y = valueScale(
scene,
chart.bins.map((b) => b.count),
true,
);
valueAxis(scene, y, chart.format);
chart.bins.forEach((bin, index) => {
const left = x(bin.from),
right = x(bin.to),
top = y(bin.count),
bottom = y(0);
itemRect(
scene,
`bin:${index}`,
`${bin.from}–${bin.to}`,
left,
top,
right - left,
bottom - top,
[
{ label: "From (inclusive)", value: formatValue(bin.from) },
{ label: "To (exclusive)", value: formatValue(bin.to) },
{ label: "Count", value: formatValue(bin.count, chart.format), color: colorOf(0) },
],
colorOf(0),
);
});
}
function rangeScene(scene: ChartScene, chart: Extract<RichChart, { chart: "range" }>, hidden: readonly number[]) {
const p = scene.plot;
// Only an explicit lane groups intervals. Equal display labels never merge source identities.
const keys = chart.items.map((item, index) => (item.lane === undefined ? `item:${index}` : `lane:${item.lane}`));
const lanes = [...new Set(keys)];
const laneLabels = lanes.map((key) => {
const item = chart.items[keys.indexOf(key)]!;
return item.lane ?? item.label;
});
const bounds = extent(chart.items.flatMap((i) => [i.start, i.end]));
const x = coordinateScale(scene, bounds, chart.axis === "time");
categories(scene, laneLabels, true);
scene.legend = laneLabels.map((label, index) => ({ index, label, color: colorOf(index) }));
const height = p.height / lanes.length;
chart.items.forEach((item, index) => {
const lane = lanes.indexOf(keys[index]!);
if (hidden.includes(lane)) return;
itemRect(
scene,
`interval:${index}`,
item.label,
x(item.start),
p.top + (lane + 0.2) * height,
x(item.end) - x(item.start),
height * 0.6,
[
{ label: "Lane", value: item.lane ?? item.label },
{ label: "Start", value: chart.axis === "time" ? utc(item.start) : formatValue(item.start, chart.format) },
{ label: "End", value: chart.axis === "time" ? utc(item.end) : formatValue(item.end, chart.format) },
],
colorOf(lane),
);
});
if (!scene.items.length) scene.empty = "All lanes hidden";
}
function waterfallScene(scene: ChartScene, chart: Extract<RichChart, { chart: "waterfall" }>) {
const p = scene.plot;
let running = 0;
const spans = chart.entries.map((e) => {
const from = e.role === "total" ? 0 : running;
running = e.role === "total" ? e.value : running + e.value;
return { from, to: running };
});
const y = valueScale(
scene,
spans.flatMap((s) => [s.from, s.to]),
true,
);
valueAxis(scene, y, chart.format);
categories(
scene,
chart.entries.map((e) => e.label),
);
const band = p.width / spans.length;
chart.entries.forEach((entry, index) => {
const s = spans[index]!,
color = colorOf(entry.role === "total" ? 2 : entry.value >= 0 ? 0 : 1);
const a = y(s.from),
b = y(s.to),
x = p.left + (index + 0.1) * band;
// Connector decoration is sparse in dense waterfalls; every delta/total remains
// drawn and inspectable. This fits 3 commands/observation across two retained scenes.
if (index < spans.length - 1 && (spans.length <= 32 || index % 2 === 0))
rect(scene, x + band * 0.8, b, band * 0.2, Math.min(1, p.top + p.height - b), "mutedForeground/30");
itemRect(
scene,
`entry:${index}`,
entry.label,
x,
Math.min(a, b),
band * 0.8,
Math.abs(a - b),
[
{
label: entry.role === "total" ? "Absolute total" : "Delta",
value: formatValue(entry.value, chart.format),
color,
},
{ label: "Running total", value: formatValue(s.to, chart.format) },
],
color,
);
});
}
function boxScene(scene: ChartScene, chart: Extract<RichChart, { chart: "box" }>, hidden: readonly number[]) {
const p = scene.plot,
values = chart.items.flatMap((i) => [i.min, i.max, ...(i.outliers ?? [])]);
const y = valueScale(scene, values);
valueAxis(scene, y, chart.format);
categories(
scene,
chart.items.map((i) => i.label),
);
scene.legend = chart.items.map((item, index) => ({ index, label: item.label, color: colorOf(index) }));
const band = p.width / chart.items.length;
chart.items.forEach((box, index) => {
if (hidden.includes(index)) return;
const x = p.left + (index + 0.5) * band,
width = band * 0.55,
cap = width * 0.6,
color = colorOf(index);
rect(scene, x - 0.5, y(box.max), 1, y(box.min) - y(box.max), color);
rect(scene, x - cap / 2, y(box.max), cap, Math.min(1, p.top + p.height - y(box.max)), color);
rect(scene, x - cap / 2, y(box.min), cap, Math.min(1, p.top + p.height - y(box.min)), color);
const rows = (["min", "q1", "median", "q3", "max"] as const).map((key) => ({
label: key,
value: formatValue(box[key], chart.format),
color,
}));
scene.items.push({
id: `box:${index}:whisker`,
label: box.label,
x,
y: (y(box.min) + y(box.max)) / 2,
rows,
hit: { kind: "rect", x: x - 0.5, y: y(box.max), width: 1, height: y(box.min) - y(box.max) },
});
itemRect(
scene,
`box:${index}`,
box.label,
x - width / 2,
y(box.q3),
width,
y(box.q1) - y(box.q3),
rows,
alpha(color, 0.45),
);
const medianHeight = Math.min(2, p.top + p.height - y(box.median));
rect(scene, x - width / 2, y(box.median), width, medianHeight, color);
if (box.q1 === box.q3)
scene.items[scene.items.length - 1]!.hit = {
kind: "rect",
x: x - width / 2,
y: y(box.median),
width,
height: medianHeight,
};
box.outliers?.forEach((value, oi) => {
const py = y(value),
radius = Math.min(3, band / 6, p.height / 20);
dot(scene, x, py, radius, color);
scene.items.push({
id: `box:${index}:outlier:${oi}`,
label: box.label,
x,
y: py,
rows: [{ label: "Outlier", value: formatValue(value, chart.format), color }],
hit: { kind: "point", x, y: py, radius: Math.max(radius, 4) },
});
});
});
if (!scene.items.length) scene.empty = "All boxes hidden";
}
export function chartScene(
chart: RichChart,
width: number,
height: number,
hidden: readonly number[] = [],
): ChartScene {
const radial = chart.chart === "pie" || chart.chart === "donut";
const left = Math.min(radial ? 12 : 82, width * (radial ? 0.04 : 0.25)),
top = Math.min(14, height * 0.08);
const scene: ChartScene = {
width,
height,
commands: [],
items: [],
legend: [],
plot: {
left,
top,
width: width - left - Math.min(18, width * 0.08),
height:
height -
top -
Math.min(chart.chart === "heatmap" ? 85 : radial ? 14 : 42, height * (chart.chart === "heatmap" ? 0.35 : 0.2)),
},
};
switch (chart.chart) {
case "bar":
case "line":
case "area":
seriesScene(scene, chart, hidden);
break;
case "scatter":
scatterScene(scene, chart, hidden);
break;
case "pie":
case "donut":
pieScene(scene, chart, hidden);
break;
case "heatmap":
heatmapScene(scene, chart);
break;
case "histogram":
histogramScene(scene, chart);
break;
case "range":
rangeScene(scene, chart, hidden);
break;
case "waterfall":
waterfallScene(scene, chart);
break;
case "box":
boxScene(scene, chart, hidden);
break;
}
labels(scene, chart);
return scene;
}
export function inspectAt(scene: ChartScene, x: number, y: number): InspectItem | null {
let closest: InspectItem | null = null,
distance = Infinity;
for (let i = scene.items.length - 1; i >= 0; i--) {
const item = scene.items[i]!,
h = item.hit;
if (h.kind === "point") {
const d = Math.hypot(x - h.x, y - h.y);
if (d <= h.radius && d < distance) {
closest = item;
distance = d;
}
} else {
let inside = false;
if (h.kind === "x") inside = x >= h.left && x <= h.right && y >= h.top && y <= h.bottom;
else if (h.kind === "rect")
inside = h.width > 0 && h.height > 0 && x >= h.x && x <= h.x + h.width && y >= h.y && y <= h.y + h.height;
else {
const radius = Math.hypot(x - h.cx, y - h.cy);
const angle = (Math.atan2(x - h.cx, -(y - h.cy)) + TAU) % TAU;
inside =
(h.innerRadius === 0 || radius > h.innerRadius) &&
radius <= h.outerRadius &&
(radius === 0 || (angle >= h.startAngle && angle < h.endAngle));
}
if (inside) return closest ?? item;
}
}
return closest;
}
export function inspectionCommands(scene: ChartScene, item: InspectItem): CanvasCommand[] {
const h = item.hit,
p = scene.plot,
paint = { stroke: "foreground/60" as const, lineWidth: 1.5 };
if (h.kind === "rect") return [{ op: "rect", x: h.x, y: h.y, width: h.width, height: h.height, ...paint }];
if (h.kind === "sector") {
// A small ring at the wedge's actual centroid identifies it without duplicating
// arc paths atop two retained scenes (including two-part near-full donuts).
return [{ op: "roundRect", x: item.x - 5, y: item.y - 5, width: 10, height: 10, radius: 5, ...paint }];
}
if (h.kind === "point")
return [
{
op: "roundRect",
x: h.x - h.radius,
y: h.y - h.radius,
width: h.radius * 2,
height: h.radius * 2,
radius: h.radius,
...paint,
},
];
const thickness = Math.min(1, p.width);
return [
{
op: "rect",
x: Math.min(item.x, p.left + p.width - thickness),
y: p.top,
width: thickness,
height: p.height,
fill: "foreground/30",
},
{ op: "roundRect", x: item.x - 3, y: item.y - 3, width: 6, height: 6, radius: 3, fill: "foreground/60" },
];
}
// Complete raw data, never the visible/normalized/rounded geometry. The UI pages this
// table; a chart-derived table can exceed the publication limit of a standalone v1 table.
export function chartDataTable(chart: RichChart): Table {
const column = (key: string, label: string, type: "text" | "number" = "number") => ({ key, label, type });
let columns: Table["columns"], rows: Cell[][];
switch (chart.chart) {
case "bar":
case "line":
case "area":
columns = [
column(
"x",
chart.xLabel ?? (chart.x.type === "time" ? "X (UTC epoch ms)" : "X"),
chart.x.type === "category" ? "text" : "number",
),
...chart.series.map((s, i) => column(`series_${i}`, s.name)),
];
rows = chart.x.values.map((x, i) => [x, ...chart.series.map((s) => s.values[i]!)]);
break;
case "scatter":
columns = [
column("series_index", "Series index"),
column("series", "Series", "text"),
column("point_index", "Point index"),
column("label", "Label", "text"),
column("x", chart.xLabel ?? "X"),
column("y", chart.yLabel ?? "Y"),
column("size", chart.sizeLabel ?? "Size"),
];
rows = chart.series.flatMap((s, si) =>
s.points.map((p, pi) => [si, s.name, pi, p.label ?? null, p.x, p.y, p.size ?? null]),
);
break;
case "pie":
case "donut":
columns = [column("label", "Part", "text"), column("value", "Value")];
rows = chart.parts.map((p) => [p.label, p.value]);
break;
case "heatmap":
columns = [
column("x_index", "X index"),
column("y_index", "Y index"),
column("x", "X", "text"),
column("y", "Y", "text"),
column("value", "Value"),
];
rows = chart.cells.map((c) => [c.x, c.y, chart.x[c.x]!, chart.y[c.y]!, c.value]);
break;
case "histogram":
columns = [column("from", "From (inclusive)"), column("to", "To (exclusive)"), column("count", "Count")];
rows = chart.bins.map((b) => [b.from, b.to, b.count]);
break;
case "range":
columns = [
column("label", "Interval", "text"),
column("lane", "Lane", "text"),
column("start", chart.axis === "time" ? "Start (UTC epoch ms)" : "Start"),
column("end", chart.axis === "time" ? "End (UTC epoch ms)" : "End"),
];
rows = chart.items.map((i) => [i.label, i.lane ?? null, i.start, i.end]);
break;
case "waterfall":
columns = [column("label", "Entry", "text"), column("role", "Role", "text"), column("value", "Value")];
rows = chart.entries.map((e) => [e.label, e.role, e.value]);
break;
case "box":
columns = [
column("index", "Box index"),
column("label", "Box", "text"),
...["min", "q1", "median", "q3", "max"].map((k) => column(k, k)),
column("outlier_index", "Outlier index"),
column("outlier", "Outlier"),
];
rows = chart.items.flatMap((i, index) => {
const summary: Cell[] = [index, i.label, i.min, i.q1, i.median, i.q3, i.max];
return [[...summary, null, null], ...(i.outliers ?? []).map((v, oi) => [...summary, oi, v])];
});
break;
}
if ("references" in chart && (chart.references?.length || chart.bands?.length)) {
const prefix: Cell[] = columns.map(() => null);
columns.push(
column("reference_label", "Reference", "text"),
column("reference_value", "Reference value"),
column("band_label", "Band", "text"),
column("band_from", "Band from"),
column("band_to", "Band to"),
);
rows = rows.map((row) => [...row, null, null, null, null, null]);
rows.push(
...(chart.references ?? []).map((r) => [...prefix, r.label, r.value, null, null, null]),
...(chart.bands ?? []).map((b) => [...prefix, null, null, b.label, b.from, b.to]),
);
}
return { kind: "table", columns, rows };
}
No comments yet.