@jarenjs/charts 0.34.0

package/src/types/boxplot.js

@@ -0,0 +1,216 @@
+//@ts-check
+/**
+ * @file The boxplot chart type: five-number summaries per category with
+ * Tukey whiskers and outlier dots. Data shape (two forms per box):
+ *
+ *   data   = { boxes: [{ label, values: number[] }                       // raw samples
+ *                    | { label, min, q1, med, q3, max, outliers? }] }    // precomputed
+ *   config = { type:'boxplot', title?, catLabel?, valLabel? }
+ *
+ * Raw samples get the standard treatment: quartiles by linear
+ * interpolation over the sorted values, whiskers at the most extreme
+ * samples inside the 1.5·IQR fences, everything outside them an
+ * outlier. Precomputed summaries are trusted as given (their whiskers
+ * are the stated min/max). The AST is unit-space: `u` along the
+ * category axis, `v` along the value axis.
+ */
+
+import { svgRoot, line as svgLine, coord } from '@jarenjs/view/helpers';
+import { clamp01 } from '@jarenjs/core/math';
+import { scaleLinear, scaleBand } from '../core/scale.js';
+import { axisTicksLinear, formatTickValue } from '../core/axis.js';
+import { cartesianFrame, annotateChart } from '../core/cartesian.js';
+import { CATEGORICAL, seriesColor } from '../core/palette.js';
+import { normalizeTooltip, valueMark } from '../core/marks.js';
+
+/**
+ * @typedef {object} BoxAST
+ * @property {string} label
+ * @property {number} u0 @property {number} u1
+ * @property {number} loV whisker low @property {number} q1V
+ * @property {number} medV @property {number} q3V
+ * @property {number} hiV whisker high
+ * @property {number[]} outliersV
+ * @property {{min:number, q1:number, med:number, q3:number, max:number}} stats
+ */
+/**
+ * @typedef {object} BoxplotAST
+ * @property {'boxplot'} type
+ * @property {string|null} title
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} cat
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} val
+ * @property {BoxAST[]} boxes
+ * @property {number} count number of categories
+ */
+
+/**
+ * Quantile of an ascending-sorted sample by linear interpolation.
+ * @param {number[]} sorted - Ascending finite samples (non-empty)
+ * @param {number} p - Quantile in [0, 1]
+ * @returns {number}
+ */
+export function quantileSorted(sorted, p) {
+  const at = (sorted.length - 1) * p;
+  const lo = Math.floor(at);
+  const hi = Math.ceil(at);
+  return sorted[lo] + (sorted[hi] - sorted[lo]) * (at - lo);
+}
+
+/**
+ * Five-number summary + Tukey fences for one box.
+ * @param {any} box
+ * @returns {{min:number, q1:number, med:number, q3:number, max:number, lo:number, hi:number, outliers:number[]}|null}
+ */
+function summarize(box) {
+  if (Array.isArray(box?.values)) {
+    const sorted = box.values
+      .filter((v) => typeof v === 'number' && Number.isFinite(v))
+      .sort((a, b) => a - b);
+    if (sorted.length === 0) return null;
+    const q1 = quantileSorted(sorted, 0.25);
+    const med = quantileSorted(sorted, 0.5);
+    const q3 = quantileSorted(sorted, 0.75);
+    const iqr = q3 - q1;
+    const loFence = q1 - 1.5 * iqr;
+    const hiFence = q3 + 1.5 * iqr;
+    const inside = sorted.filter((v) => v >= loFence && v <= hiFence);
+    return {
+      min: sorted[0],
+      q1, med, q3,
+      max: sorted[sorted.length - 1],
+      lo: inside.length !== 0 ? inside[0] : q1,
+      hi: inside.length !== 0 ? inside[inside.length - 1] : q3,
+      outliers: sorted.filter((v) => v < loFence || v > hiFence),
+    };
+  }
+  const fields = [box?.min, box?.q1, box?.med, box?.q3, box?.max];
+  if (!fields.every((v) => typeof v === 'number' && Number.isFinite(v))) return null;
+  const outliers = (box.outliers ?? []).filter((v) => typeof v === 'number' && Number.isFinite(v));
+  return {
+    min: box.min, q1: box.q1, med: box.med, q3: box.q3, max: box.max,
+    lo: box.min, hi: box.max, outliers,
+  };
+}
+
+/**
+ * Build the geometry-free boxplot AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {BoxplotAST}
+ */
+export function buildBoxplotAST(data, config = {}) {
+  const input = (data?.boxes ?? [])
+    .map((box) => ({ label: String(box?.label ?? ''), stats: summarize(box) }))
+    .filter((box) => box.stats !== null);
+
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (const { stats } of input) {
+    const min = Math.min(stats.lo, ...stats.outliers);
+    const max = Math.max(stats.hi, ...stats.outliers);
+    if (min < lo) lo = min;
+    if (max > hi) hi = max;
+  }
+  if (!Number.isFinite(lo)) { lo = 0; hi = 1; }
+  const ticks = axisTicksLinear(lo, hi, 5);
+  const sLo = Math.min(lo, ticks[0] ?? lo);
+  const sHi = Math.max(hi, ticks[ticks.length - 1] ?? hi);
+  const scale = scaleLinear(sLo, sHi === sLo ? sLo + 1 : sHi);
+
+  const labels = input.map((box) => box.label);
+  const band = scaleBand(labels, 0.35);
+  const boxes = input.map((box, i) => {
+    const start = i * band.step + (band.step - band.bandwidth) / 2;
+    const s = box.stats;
+    return {
+      label: box.label,
+      u0: start,
+      u1: start + band.bandwidth,
+      loV: clamp01(scale(s.lo)),
+      q1V: clamp01(scale(s.q1)),
+      medV: clamp01(scale(s.med)),
+      q3V: clamp01(scale(s.q3)),
+      hiV: clamp01(scale(s.hi)),
+      outliersV: s.outliers.map((v) => clamp01(scale(v))),
+      stats: { min: s.min, q1: s.q1, med: s.med, q3: s.q3, max: s.max },
+    };
+  });
+
+  return {
+    type: 'boxplot',
+    title: config.title ?? null,
+    cat: {
+      ticks: labels.map((label, i) => ({ pos: (i + 0.5) * band.step, label })),
+      label: config.catLabel ?? null,
+    },
+    val: {
+      ticks: ticks.map((v) => ({ pos: clamp01(scale(v)), label: formatTickValue(v) })),
+      label: config.valLabel ?? null,
+    },
+    boxes,
+    count: boxes.length,
+  };
+}
+
+/**
+ * Render a boxplot AST to a pure-vnode SVG: capped whiskers, a
+ * translucent box with a full-strength median line, outlier dots, and
+ * a summary `<title>` per box.
+ * @param {BoxplotAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, palette?: readonly string[], width?: number,
+ *   tooltip?: import('../core/marks.js').ChartTooltipSpec}} [options]
+ * @returns {any}
+ */
+export function renderBoxplotAST(ast, theme, hash, options = {}) {
+  const t = theme.tokens;
+  const palette = options.palette ?? CATEGORICAL;
+  const tooltip = normalizeTooltip(options.tooltip);
+  const color = seriesColor(0, palette);
+  const frame = cartesianFrame({
+    title: ast.title,
+    legend: null,
+    xAxis: ast.cat,
+    yAxis: ast.val,
+    grid: 'y',
+    width: options.width,
+    palette,
+    theme,
+  });
+  const { plot } = frame;
+  const children = frame.children;
+  for (const box of ast.boxes) {
+    const x0 = plot.x + box.u0 * plot.w;
+    const x1 = plot.x + box.u1 * plot.w;
+    const cx = (x0 + x1) / 2;
+    const capW = (x1 - x0) * 0.5;
+    const y = (v) => plot.y + (1 - v) * plot.h;
+    const whisker = { stroke: t.axis, 'stroke-width': 1, class: 'chart-box-whisker' };
+    children.push(svgLine(coord(cx), coord(y(box.loV)), coord(cx), coord(y(box.q1V)), whisker));
+    children.push(svgLine(coord(cx), coord(y(box.q3V)), coord(cx), coord(y(box.hiV)), whisker));
+    children.push(svgLine(coord(cx - capW / 2), coord(y(box.loV)), coord(cx + capW / 2), coord(y(box.loV)), whisker));
+    children.push(svgLine(coord(cx - capW / 2), coord(y(box.hiV)), coord(cx + capW / 2), coord(y(box.hiV)), whisker));
+    const s = box.stats;
+    children.push(valueMark('rect', {
+      x: coord(x0), y: coord(y(box.q3V)),
+      width: coord(x1 - x0), height: coord(Math.max(1, y(box.q1V) - y(box.q3V))),
+      fill: color, 'fill-opacity': 0.35, stroke: color, 'stroke-width': 1.5,
+      class: 'chart-box',
+    }, tooltip,
+    `${box.label} — min ${formatTickValue(s.min)}, q1 ${formatTickValue(s.q1)}, `
+    + `median ${formatTickValue(s.med)}, q3 ${formatTickValue(s.q3)}, max ${formatTickValue(s.max)}`,
+    { type: 'boxplot', label: box.label, ...s }));
+    children.push(svgLine(coord(x0), coord(y(box.medV)), coord(x1), coord(y(box.medV)),
+      { stroke: color, 'stroke-width': 2, class: 'chart-box-median' }));
+    for (const v of box.outliersV) {
+      children.push(['circle', {
+        cx: coord(cx), cy: coord(y(v)), r: 2.5,
+        fill: color, 'fill-opacity': 0.75, class: 'chart-dot',
+      }]);
+    }
+  }
+  const svg = svgRoot(options.rootClass ?? 'chart chart-svg chart-boxplot-chart',
+    frame.width, frame.height, theme, children, (options.keyPrefix ?? 'box-') + hash);
+  return annotateChart(svg, ast.title);
+}

package/src/types/candlestick.js

@@ -0,0 +1,274 @@
+//@ts-check
+/**
+ * @file The candlestick chart type: OHLC records on a time x-scale and
+ * a linear y-scale. Up/down candles use the win/loss semantic pair —
+ * gain and loss are exactly what the tokens mean, and the pair is
+ * host-linked (`--ok`/`--fail`) like every semantic color. Data shape:
+ *
+ *   data   = { candles: [{t, open, high, low, close}] }
+ *   config = { type:'candlestick', title?, xLabel?, yLabel?, domain? }
+ *
+ * Candle width comes from the band-width math: an equal share of the
+ * axis per candle (klines arrive at a fixed interval, so equal bands
+ * and true time positions coincide).
+ *
+ * `config.domain` declares a domain-stability policy (`core/domain.js`):
+ * a quantized sliding `x` window (candles older than it are dropped —
+ * a clamped candle would misstate its prices), pinned or
+ * step-quantized `y` bounds. The AST records the resolved domain so a
+ * later build — or the incremental session — can detect "unchanged".
+ *
+ * The extremes scan, domain resolution and per-candle mapping are
+ * exported (`scanCandleExtremes` / `resolveCandleDomains` /
+ * `candleUnit`) because the session must make the same decisions from
+ * the same numbers. Each candle renders as one keyed
+ * `<g class="chart-candle">` (wick line, then body rect) — the candle
+ * is the replaceable unit a kline upsert patches; `buildCandlestickRender`
+ * is the render variant that also returns that geometry.
+ */
+
+import { svgRoot, line as svgLine, coord } from '@jarenjs/view/helpers';
+import { clamp01 } from '@jarenjs/core/math';
+import { scaleLinear, scaleTime } from '../core/scale.js';
+import {
+  axisTicksLinear, axisTicksTime, niceTimeStep, formatTickValue, formatTimeTick,
+} from '../core/axis.js';
+import { cartesianFrame, annotateChart } from '../core/cartesian.js';
+import { normalizeTooltip, markProps } from '../core/marks.js';
+import { numOf } from '../core/stream-adapter.js';
+import {
+  normalizeDomainPolicy, resolveWindowX, resolveStepY, resolvePinnedY,
+} from '../core/domain.js';
+
+/**
+ * @typedef {object} CandleAST
+ * @property {number} t open time (epoch ms — the candle's identity)
+ * @property {number} u center position (0..1)
+ * @property {number} w body width (0..1)
+ * @property {number} openV @property {number} closeV
+ * @property {number} highV @property {number} lowV
+ * @property {number} open @property {number} high
+ * @property {number} low @property {number} close raw prices, which the
+ *  hover text reports (a clamped unit value cannot be read back to one)
+ * @property {boolean} up close >= open
+ */
+/**
+ * @typedef {object} CandlestickAST
+ * @property {'candlestick'} type
+ * @property {string|null} title
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} x
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} y
+ * @property {{x: [number, number], y: [number, number]}} domain resolved scale bounds
+ * @property {CandleAST[]} candles
+ */
+
+/**
+ * Scan the candle extremes the domain resolution needs: t bounds over
+ * every well-formed candle, price bounds over the candles a window
+ * keeps — and the kept list itself (windowed-out candles are dropped
+ * entirely; a candle clamped to the edge would misstate its prices).
+ * @param {any[]} rawCandles
+ * @param {import('../core/domain.js').DomainPolicy} policy
+ * @returns {{t0:number, t1:number, lo:number, hi:number, kept: any[]}}
+ */
+export function scanCandleExtremes(rawCandles, policy) {
+  const all = (rawCandles ?? []).filter((c) =>
+    Number.isFinite(numOf(c?.t)) && [c?.open, c?.high, c?.low, c?.close].every(Number.isFinite));
+  let t0 = Infinity;
+  let t1 = -Infinity;
+  for (const c of all) {
+    const t = numOf(c.t);
+    if (t < t0) t0 = t;
+    if (t > t1) t1 = t;
+  }
+  let kept = all;
+  if (policy.window !== null) {
+    const [wLo] = resolveWindowX(t1, policy.window, policy.slide);
+    kept = all.filter((c) => numOf(c.t) >= wLo);
+  }
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (const c of kept) {
+    if (c.low < lo) lo = c.low;
+    if (c.high > hi) hi = c.high;
+  }
+  return { t0, t1, lo, hi, kept };
+}
+
+/**
+ * Resolve the scale domains (and their tick values) from the scanned
+ * extremes under the domain policy — the single place the candlestick
+ * type decides its bounds.
+ * @param {{t0:number, t1:number, lo:number, hi:number}} ext
+ * @param {import('../core/domain.js').DomainPolicy} policy
+ * @returns {{x: [number,number], y: [number,number],
+ *   xTickValues: number[], yTickValues: number[]}}
+ */
+export function resolveCandleDomains(ext, policy) {
+  let { t0, t1, lo, hi } = ext;
+  if (policy.window !== null)
+    [t0, t1] = resolveWindowX(ext.t1, policy.window, policy.slide);
+  if (!Number.isFinite(t0)) { t0 = 0; t1 = 1; }
+  if (!Number.isFinite(lo)) { lo = 0; hi = 1; }
+
+  const xHi = t1 === t0 ? t0 + 1 : t1;
+  let yTickValues;
+  let yLo;
+  let yHi;
+  if (policy.step || policy.pin !== null) {
+    [yLo, yHi] = policy.step ? resolveStepY(lo, hi) : resolvePinnedY(lo, hi, policy.pin, false);
+    if (yHi === yLo) yHi = yLo + 1;
+    yTickValues = axisTicksLinear(yLo, yHi, 5);
+  }
+  else {
+    yTickValues = axisTicksLinear(lo, hi, 5);
+    yLo = Math.min(lo, yTickValues[0] ?? lo);
+    const extended = Math.max(hi, yTickValues[yTickValues.length - 1] ?? hi);
+    yHi = extended === yLo ? yLo + 1 : extended;
+  }
+  return {
+    x: [t0, xHi],
+    y: [yLo, yHi],
+    xTickValues: axisTicksTime(t0, xHi, 4),
+    xTickStep: niceTimeStep(xHi - t0, 4),
+    yTickValues,
+  };
+}
+
+/**
+ * Map one OHLC record onto its unit-space candle — the per-candle half
+ * of the build, shared with the session.
+ * @param {any} c a well-formed `{t, open, high, low, close}` record
+ * @param {(v:number)=>number} xScale @param {(v:number)=>number} yScale
+ * @param {number} w candle width (0..1)
+ * @returns {CandleAST}
+ */
+export function candleUnit(c, xScale, yScale, w) {
+  const t = numOf(c.t);
+  return {
+    t,
+    u: clamp01(xScale(t)),
+    w,
+    openV: clamp01(yScale(c.open)),
+    closeV: clamp01(yScale(c.close)),
+    highV: clamp01(yScale(c.high)),
+    lowV: clamp01(yScale(c.low)),
+    open: c.open,
+    high: c.high,
+    low: c.low,
+    close: c.close,
+    up: c.close >= c.open,
+  };
+}
+
+/**
+ * Build the geometry-free candlestick AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {CandlestickAST}
+ */
+export function buildCandlestickAST(data, config = {}) {
+  const policy = normalizeDomainPolicy(config.domain);
+  const ext = scanCandleExtremes(data?.candles, policy);
+  const domains = resolveCandleDomains(ext, policy);
+  const xScale = scaleTime(domains.x[0], domains.x[1]);
+  const yScale = scaleLinear(domains.y[0], domains.y[1]);
+
+  const w = ext.kept.length === 0 ? 0.1 : (1 / ext.kept.length) * 0.7;
+  const candles = ext.kept.map((c) => candleUnit(c, xScale, yScale, w));
+
+  return {
+    type: 'candlestick',
+    title: config.title ?? null,
+    x: {
+      ticks: domains.xTickValues.map((v) => ({
+        pos: clamp01(xScale(v)), label: formatTimeTick(v, domains.xTickStep),
+      })),
+      label: config.xLabel ?? null,
+    },
+    y: {
+      ticks: domains.yTickValues.map((v) => ({ pos: clamp01(yScale(v)), label: formatTickValue(v) })),
+      label: config.yLabel ?? null,
+    },
+    domain: { x: domains.x, y: domains.y },
+    candles,
+  };
+}
+
+/**
+ * Render one candle as its keyed `<g>` group: an OHLC hover `<title>`,
+ * then the wick line under the body rect, up/down tones from the
+ * theme's win/loss pair.
+ * @param {CandleAST} c
+ * @param {{x:number,y:number,w:number,h:number}} plot
+ * @param {{tokens: Record<string,string>}} theme
+ * @param {import('../core/marks.js').ChartTooltip|null} [tooltip]
+ * @returns {any}
+ */
+export function candleRender(c, plot, theme, tooltip = null) {
+  const color = c.up ? theme.tokens.win : theme.tokens.loss;
+  const x = plot.x + c.u * plot.w;
+  const halfW = Math.max(1, (c.w * plot.w) / 2);
+  const yHigh = plot.y + (1 - c.highV) * plot.h;
+  const yLow = plot.y + (1 - c.lowV) * plot.h;
+  const yOpen = plot.y + (1 - c.openV) * plot.h;
+  const yClose = plot.y + (1 - c.closeV) * plot.h;
+  const bodyTop = Math.min(yOpen, yClose);
+  const bodyH = Math.max(1, Math.abs(yOpen - yClose));
+  const text = `${formatTimeTick(c.t)} O ${c.open} H ${c.high} L ${c.low} C ${c.close}`;
+  return ['g', markProps({ key: `c${c.t}`, class: 'chart-candle' }, tooltip, text,
+    { type: 'candlestick', t: c.t, open: c.open, high: c.high, low: c.low, close: c.close }),
+    ['title', {}, text],
+    svgLine(coord(x), coord(yHigh), coord(x), coord(yLow),
+      { stroke: color, 'stroke-width': 1, class: c.up ? 'chart-candle-up' : 'chart-candle-down' }),
+    ['rect', {
+      x: coord(x - halfW), y: coord(bodyTop),
+      width: coord(halfW * 2), height: coord(bodyH),
+      fill: color, class: c.up ? 'chart-candle-up' : 'chart-candle-down',
+    }],
+  ];
+}
+
+/**
+ * Render a candlestick AST and return the svg WITH the geometry a
+ * session needs to patch it per candle.
+ * @param {CandlestickAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, width?: number,
+ *   tooltip?: import('../core/marks.js').ChartTooltipSpec}} [options]
+ * @returns {{svg: any, plot: {x:number,y:number,w:number,h:number}, chromeLen: number}}
+ */
+export function buildCandlestickRender(ast, theme, hash, options = {}) {
+  const tooltip = normalizeTooltip(options.tooltip);
+  const frame = cartesianFrame({
+    title: ast.title,
+    legend: null,
+    xAxis: ast.x,
+    yAxis: ast.y,
+    grid: 'y',
+    width: options.width,
+    theme,
+  });
+  const { plot } = frame;
+  const chromeLen = frame.children.length;
+  const children = frame.children;
+  for (const c of ast.candles)
+    children.push(candleRender(c, plot, theme, tooltip));
+  const svg = svgRoot(options.rootClass ?? 'chart chart-svg chart-candlestick-chart',
+    frame.width, frame.height, theme, children, (options.keyPrefix ?? 'candle-') + hash);
+  annotateChart(svg, ast.title);
+  return { svg, plot, chromeLen };
+}
+
+/**
+ * Render a candlestick AST to a pure-vnode SVG.
+ * @param {CandlestickAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, width?: number}} [options]
+ * @returns {any}
+ */
+export function renderCandlestickAST(ast, theme, hash, options = {}) {
+  return buildCandlestickRender(ast, theme, hash, options).svg;
+}

package/src/types/gauge.js

@@ -0,0 +1,140 @@
+//@ts-check
+/**
+ * @file The gauge chart type: a single value on a semicircular dial —
+ * the "how full is it" headline mark. Data shape:
+ *
+ *   data   = { value: number }
+ *   config = { type:'gauge', title?, min?, max?, unit?, tone? }
+ *
+ * The domain is `[min, max]` (0..100 when unset); the AST carries the
+ * clamped fill fraction and tick fractions only — the dial radius and
+ * stroke widths are render decisions. `tone` colors the fill through
+ * the semantic win/loss pair; the default is the first categorical
+ * anchor (the brand blue).
+ */
+
+import {
+  svgRoot, path as svgPath, line as svgLine, textAt, coord, polarPoint, anchorForAngle,
+} from '@jarenjs/view/helpers';
+import { clamp01 } from '@jarenjs/core/math';
+import { axisTicksLinear, formatTickValue } from '../core/axis.js';
+import { FS_TICK, toneColor, annotateChart, chartTitle } from '../core/cartesian.js';
+import { CATEGORICAL } from '../core/palette.js';
+import { normalizeTooltip, markProps } from '../core/marks.js';
+
+/**
+ * @typedef {object} GaugeAST
+ * @property {'gauge'} type
+ * @property {string|null} title
+ * @property {number} value
+ * @property {string|null} unit
+ * @property {number} min @property {number} max
+ * @property {number} frac clamped fill fraction (0..1)
+ * @property {{frac: number, label: string}[]} ticks
+ * @property {'win'|'loss'|null} tone
+ */
+
+/**
+ * Build the geometry-free gauge AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {GaugeAST}
+ */
+export function buildGaugeAST(data, config = {}) {
+  const raw = data?.value;
+  const value = typeof raw === 'number' && Number.isFinite(raw) ? raw : 0;
+  let min = typeof config.min === 'number' && Number.isFinite(config.min) ? config.min : 0;
+  let max = typeof config.max === 'number' && Number.isFinite(config.max) ? config.max : 100;
+  if (max <= min) max = min + 1;
+  const frac = clamp01((value - min) / (max - min));
+  const ticks = axisTicksLinear(min, max, 4).map((v) => ({
+    frac: clamp01((v - min) / (max - min)),
+    label: formatTickValue(v),
+  }));
+  return {
+    type: 'gauge',
+    title: config.title ?? null,
+    value,
+    unit: config.unit ?? null,
+    min,
+    max,
+    frac,
+    ticks,
+    tone: config.tone === 'win' || config.tone === 'loss' ? config.tone : null,
+  };
+}
+
+/**
+ * Render a gauge AST to a pure-vnode SVG: a semicircular track, the
+ * value arc over it, outward tick marks with labels, and the value as
+ * the headline figure in the dial's mouth.
+ * @param {GaugeAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, palette?: readonly string[],
+ *   tooltip?: import('../core/marks.js').ChartTooltipSpec}} [options]
+ * @returns {any}
+ */
+export function renderGaugeAST(ast, theme, hash, options = {}) {
+  const t = theme.tokens;
+  const palette = options.palette ?? CATEGORICAL;
+  const tooltip = normalizeTooltip(options.tooltip);
+  const valueText = formatTickValue(ast.value) + (ast.unit ? ` ${ast.unit}` : '');
+  const R = 110;
+  const stroke = 18;
+  const pad = 46;
+  const cx = pad + R;
+  const top = ast.title ? 40 : 16;
+  const cy = top + R + stroke / 2;
+  const children = [];
+
+  if (ast.title) {
+    children.push(chartTitle(cx, 24, ast.title, 15, t));
+  }
+
+  // Dial angles run π (left) → 2π (right); the fill sweeps clockwise.
+  const angleAt = (frac) => Math.PI + frac * Math.PI;
+  const pointAt = (frac, r) => {
+    const p = polarPoint(cx, cy, r, angleAt(frac));
+    return [coord(p.x), coord(p.y)];
+  };
+  const arcPath = (f0, f1) => {
+    const [x0, y0] = pointAt(f0, R);
+    const [x1, y1] = pointAt(f1, R);
+    return `M${x0},${y0} A${R},${R} 0 0 1 ${x1},${y1}`;
+  };
+
+  children.push(svgPath(arcPath(0, 1),
+    { fill: 'none', stroke: t.grid, 'stroke-width': stroke, class: 'chart-gauge-track' }));
+  if (ast.frac > 0) {
+    // The fill arc takes the tooltip bindings but no `<title>`: this
+    // chart already spells its value out in 30px type below, and with
+    // no chart title the root's aria-label is that same value.
+    children.push(['path', markProps({
+      d: arcPath(0, ast.frac),
+      fill: 'none', stroke: toneColor(theme, ast.tone, 0, palette),
+      'stroke-width': stroke, class: 'chart-gauge-fill',
+    }, tooltip, valueText,
+    { type: 'gauge', value: ast.value, min: ast.min, max: ast.max, unit: ast.unit })]);
+  }
+
+  for (const tick of ast.ticks) {
+    const [x0, y0] = pointAt(tick.frac, R + stroke / 2 + 2);
+    const [x1, y1] = pointAt(tick.frac, R + stroke / 2 + 8);
+    children.push(svgLine(x0, y0, x1, y1, { stroke: t.axis, 'stroke-width': 1, class: 'chart-axis' }));
+    const [lx, ly] = pointAt(tick.frac, R + stroke / 2 + 12);
+    const anchor = anchorForAngle(angleAt(tick.frac));
+    children.push(textAt(lx, ly + (anchor === 'middle' ? -2 : 4), tick.label, FS_TICK,
+      { 'text-anchor': anchor, fill: t.muted, class: 'chart-tick' }));
+  }
+
+  // The headline figure inside the dial's mouth.
+  children.push(textAt(cx, cy - 8, valueText, 30,
+    { 'font-weight': 'bold', 'text-anchor': 'middle', fill: t.text, class: 'chart-gauge-value' }));
+
+  const width = 2 * (pad + R);
+  const height = cy + 24;
+  const svg = svgRoot(options.rootClass ?? 'chart chart-svg chart-gauge-chart',
+    width, height, theme, children, (options.keyPrefix ?? 'gauge-') + hash);
+  return annotateChart(svg, ast.title ?? valueText);
+}