graphein 0.12.0 → 0.13.0

package/dist/index.js

@@ -2349,6 +2349,15 @@ function aggregateValues(values, op) {
   }
   return null;
 }
+function resolveValueRef(ref, data) {
+  if (ref == null) return null;
+  if (typeof ref === "number") return Number.isFinite(ref) ? ref : null;
+  const read = accessor(ref.field);
+  return aggregateValues(
+    (data ?? []).map((d) => read(d)),
+    ref.aggregate ?? "sum"
+  );
+}
 function groupBy(rows, keyFields2) {
   const grouped = /* @__PURE__ */ new Map();
   for (const row of rows) {
@@ -2646,7 +2655,7 @@ function fieldTitle(f) {
   if (!f) return void 0;
   return f.title ?? f.field;
 }
-function resolveValueRef(ref, data) {
+function resolveValueRef2(ref, data) {
   if (ref == null) return null;
   if (typeof ref === "number") return Number.isFinite(ref) ? ref : null;
   return aggregateValues(data.map(accessor(ref.field)), ref.aggregate ?? "sum");
@@ -2747,9 +2756,9 @@ function analyzeChart(spec) {
   if (rows.length === 0 && !VALUE_TYPES.has(type)) return null;
   if (VALUE_TYPES.has(type)) {
     const s = spec;
-    const value = resolveValueRef(s.value, rows);
+    const value = resolveValueRef2(s.value, rows);
     if (value === null) return null;
-    const target = resolveValueRef(s.target, rows);
+    const target = resolveValueRef2(s.target, rows);
     const toTarget = target === null ? null : value - target;
     const pctOfTarget = target ? value / target : null;
     return {
@@ -4248,18 +4257,58 @@ function validateSpec(spec) {
     }
   }
   if (type === "kpi") {
-    const value = spec.value;
-    if (value === void 0) {
-      err("value", '"kpi" requires a "value" (a number or { field, aggregate? }).');
-    } else if (isObject3(value)) {
-      checkField("value.field", value.field);
-    } else if (typeof value !== "number") {
-      err("value", '"value" must be a number or an object with a "field".');
+    checkValueRef("value", spec.value, "kpi", true);
+    checkValueRef("delta", spec.delta, "delta", false);
+    if (spec.align !== void 0 && !["start", "center", "end"].includes(spec.align)) {
+      err("align", '"align" must be one of: start, center, end.');
+    }
+    if (spec.labelPosition !== void 0 && !["above", "below"].includes(spec.labelPosition)) {
+      err("labelPosition", '"labelPosition" must be one of: above, below.');
+    }
+    if (spec.unit !== void 0 && typeof spec.unit !== "string") {
+      err("unit", '"unit" must be a string.');
+    }
+    if (spec.color !== void 0 && typeof spec.color !== "string") {
+      err("color", '"color" must be a string (a CSS color).');
+    }
+    if (spec.sparkline !== void 0 && typeof spec.sparkline !== "boolean") {
+      if (!isObject3(spec.sparkline)) {
+        err("sparkline", '"sparkline" must be a boolean or an object with { field?, markers? }.');
+      } else {
+        if (spec.sparkline.field !== void 0) checkField("sparkline.field", spec.sparkline.field);
+        if (spec.sparkline.markers !== void 0 && typeof spec.sparkline.markers !== "boolean") {
+          err("sparkline.markers", '"sparkline.markers" must be a boolean.');
+        }
+      }
+    }
+    if (spec.comparisons !== void 0) {
+      if (!Array.isArray(spec.comparisons)) {
+        err("comparisons", '"comparisons" must be an array of { label, delta, amount? }.');
+      } else {
+        spec.comparisons.forEach((c, i) => {
+          if (!isObject3(c)) {
+            err(`comparisons[${i}]`, 'Each comparison must be an object with a "label" and "delta".');
+            return;
+          }
+          if (typeof c.label !== "string" || c.label === "") {
+            err(`comparisons[${i}].label`, 'Each comparison needs a non-empty "label".');
+          }
+          checkValueRef(`comparisons[${i}].delta`, c.delta, "comparison", true);
+          if (c.amount !== void 0) checkValueRef(`comparisons[${i}].amount`, c.amount, "comparison amount", false);
+          if (c.invert !== void 0 && typeof c.invert !== "boolean") {
+            err(`comparisons[${i}].invert`, '"invert" must be a boolean.');
+          }
+        });
+      }
     }
   }
   if (type === "gauge") {
     checkValueRef("value", spec.value, "gauge", true);
     checkValueRef("target", spec.target, "target", false);
+    checkValueRef("compare", spec.compare, "compare", false);
+    if (spec.legend !== void 0 && typeof spec.legend !== "boolean") {
+      err("legend", '"legend" must be a boolean.');
+    }
     const max = spec.max;
     if (max === void 0) {
       err("max", `"gauge" requires a numeric "max" (the scale's full-scale value).`);
@@ -5709,15 +5758,19 @@ function overlayTextToCanvasCmd(o, font) {
     const m = t.match(/rotate\((-?\d+(?:\.\d+)?)deg\)/);
     return m ? parseFloat(m[1]) * Math.PI / 180 : void 0;
   })();
+  const shiftX100 = t.includes("translateX(-100%)") || t.includes("translate(-100%");
+  const shiftX50 = t.includes("translateX(-50%)") || t.includes("translate(-50%");
   let align = "left";
   let x = o.left;
   const y = o.top;
   if (o.width != null) {
     align = o.align ?? "left";
     x = align === "right" ? o.left + o.width : align === "center" ? o.left + o.width / 2 : o.left;
-  } else if (t.includes("translateX(-100%)")) {
+    if (shiftX100) x -= o.width;
+    else if (shiftX50) x -= o.width / 2;
+  } else if (shiftX100) {
     align = "right";
-  } else if (t.includes("translateX(-50%)") || t.includes("translate(-50%")) {
+  } else if (shiftX50) {
     align = "center";
   }
   const baseline = t.includes("translateY(-50%)") || t.includes(",-50%") || t.includes(", -50%") ? "middle" : "top";
@@ -7080,13 +7133,13 @@ function rowAlpha(emphasis, row) {
   if (!emphasis) return 1;
   return emphasis.match(row) ? 1 : emphasis.dim;
 }
-function seriesMatches(emphasis, series) {
-  if (!emphasis) return true;
-  return series.rows.some((row) => emphasis.match(row));
-}
-function seriesAlpha(emphasis, series) {
-  if (!emphasis) return 1;
-  return seriesMatches(emphasis, series) ? 1 : emphasis.dim;
+function seriesEmphasisMode(emphasis, series) {
+  if (!emphasis) return "all";
+  let matched = 0;
+  for (const row of series.rows) if (emphasis.match(row)) matched++;
+  if (matched === 0) return "none";
+  if (matched === series.rows.length) return "all";
+  return "partial";
 }
 
 // src/charts/line.ts
@@ -7114,6 +7167,24 @@ function buildSeriesPoints(model, s) {
     gap: () => ({ x: NaN, y: NaN })
   });
 }
+function matchPointPixels(model, s) {
+  const emphasis = model.emphasis;
+  if (!emphasis) return [];
+  const readX = accessor(model.x.field);
+  const readY = accessor(model.y.field ?? "");
+  const out = [];
+  for (const d of s.rows) {
+    if (!emphasis.match(d)) continue;
+    const px = model.x.pixel(readX(d));
+    if (px == null) continue;
+    const yRaw = readY(d);
+    if (yRaw == null || yRaw === "") continue;
+    const py = model.y.pixel(yRaw);
+    if (Number.isNaN(py)) continue;
+    out.push({ x: px, y: py });
+  }
+  return out;
+}
 function finiteRuns(points) {
   const runs = [];
   let run = [];
@@ -7165,6 +7236,18 @@ function drawLineSketch(ctx, model, allSeries, pen, filled, showPoints) {
       if (alpha !== 1) ctx.globalAlpha = prev;
     }
   }
+  for (const { series, mode, matchPoints } of allSeries) {
+    if (mode !== "partial") continue;
+    ctx.globalAlpha = 1;
+    for (const p of matchPoints) {
+      pen.circle(p.x, p.y, 3.4, {
+        fill: series.color,
+        stroke: model.tokens.color.background,
+        strokeWidth: 1.5
+      });
+    }
+  }
+  ctx.globalAlpha = 1;
 }
 function drawLine(surface, model) {
   const ctx = surface.marks.ctx;
@@ -7173,11 +7256,16 @@ function drawLine(surface, model) {
   const curve = resolveCurve(spec.curve);
   const lineGen = line({ curve });
   const areaGen = spec.area ? area({ curve }) : null;
-  const allSeries = model.series.map((s) => ({
-    series: s,
-    points: buildSeriesPoints(model, s),
-    alpha: seriesAlpha(model.emphasis, s)
-  }));
+  const allSeries = model.series.map((s) => {
+    const mode = seriesEmphasisMode(model.emphasis, s);
+    return {
+      series: s,
+      points: buildSeriesPoints(model, s),
+      alpha: mode === "all" ? 1 : model.emphasis?.dim ?? 1,
+      mode,
+      matchPoints: matchPointPixels(model, s)
+    };
+  });
   const showPoints = spec.points || allSeries.some((s) => s.points.filter((p) => !Number.isNaN(p.x)).length === 1);
   ctx.save();
   ctx.beginPath();
@@ -7232,6 +7320,20 @@ function drawLine(surface, model) {
       ctx.globalAlpha = 1;
     }
   }
+  for (const { series, mode, matchPoints } of allSeries) {
+    if (mode !== "partial") continue;
+    ctx.fillStyle = series.color;
+    ctx.strokeStyle = tokens.color.background;
+    ctx.lineWidth = 1.5;
+    ctx.globalAlpha = 1;
+    for (const p of matchPoints) {
+      ctx.beginPath();
+      ctx.arc(p.x, p.y, 3, 0, Math.PI * 2);
+      ctx.fill();
+      ctx.stroke();
+    }
+  }
+  ctx.globalAlpha = 1;
   ctx.restore();
 }
 
@@ -7242,6 +7344,8 @@ function buildBands(model, stacked) {
   const cumulative = /* @__PURE__ */ new Map();
   const threshold = stacked ? Infinity : Math.max(2, Math.round(model.plot.width));
   return model.series.map((series) => {
+    const mode = seriesEmphasisMode(model.emphasis, series);
+    const matchPoints = [];
     const points = [];
     for (const row of series.rows) {
       const xv = readX(row);
@@ -7254,19 +7358,23 @@ function buildBands(model, stacked) {
         const base = cumulative.get(key) ?? 0;
         const top = base + (missing ? 0 : value);
         cumulative.set(key, top);
+        const y1 = missing ? NaN : model.y.pixel(top);
         points.push({
           x: px == null ? NaN : px,
           y0: model.y.pixel(base),
-          y1: missing ? NaN : model.y.pixel(top),
+          y1,
           sortKey: px == null ? Number.POSITIVE_INFINITY : px
         });
+        if (model.emphasis?.match(row) && px != null && !Number.isNaN(y1)) matchPoints.push({ x: px, y: y1 });
       } else {
+        const y1 = missing ? NaN : model.y.pixel(value);
         points.push({
           x: px == null ? NaN : px,
           y0: model.y.baseline,
-          y1: missing ? NaN : model.y.pixel(value),
+          y1,
           sortKey: px == null ? Number.POSITIVE_INFINITY : px
         });
+        if (model.emphasis?.match(row) && px != null && !Number.isNaN(y1)) matchPoints.push({ x: px, y: y1 });
       }
     }
     points.sort((a, b) => a.sortKey - b.sortKey);
@@ -7276,7 +7384,7 @@ function buildBands(model, stacked) {
       getY: (p) => p.y1,
       gap: () => ({ x: NaN, y0: NaN, y1: NaN })
     }) : band;
-    return { series, points: reduced, alpha: seriesAlpha(model.emphasis, series) };
+    return { series, points: reduced, alpha: mode === "all" ? 1 : model.emphasis?.dim ?? 1, mode, matchPoints };
   });
 }
 function drawAreaSketch(ctx, model, bands, pen, stacked) {
@@ -7311,6 +7419,18 @@ function drawAreaSketch(ctx, model, bands, pen, stacked) {
     );
     if (alpha !== 1) ctx.globalAlpha = prev;
   }
+  for (const { series, mode, matchPoints } of bands) {
+    if (mode !== "partial") continue;
+    ctx.globalAlpha = 1;
+    for (const p of matchPoints) {
+      pen.circle(p.x, p.y, 3.4, {
+        fill: series.color,
+        stroke: model.tokens.color.background,
+        strokeWidth: 1.5
+      });
+    }
+  }
+  ctx.globalAlpha = 1;
 }
 function drawArea(surface, model) {
   const ctx = surface.marks.ctx;
@@ -7360,6 +7480,20 @@ function drawArea(surface, model) {
     ctx.stroke();
     ctx.globalAlpha = 1;
   }
+  for (const { series, mode, matchPoints } of bands) {
+    if (mode !== "partial") continue;
+    ctx.fillStyle = series.color;
+    ctx.strokeStyle = tokens.color.background;
+    ctx.lineWidth = 1.5;
+    ctx.globalAlpha = 1;
+    for (const p of matchPoints) {
+      ctx.beginPath();
+      ctx.arc(p.x, p.y, 3, 0, Math.PI * 2);
+      ctx.fill();
+      ctx.stroke();
+    }
+  }
+  ctx.globalAlpha = 1;
   ctx.restore();
 }
 
@@ -7427,6 +7561,8 @@ function drawGroupedBars(ctx, model, radius, pen) {
   const subWidth = seriesCount > 1 ? bandWidth / seriesCount : bandWidth;
   const gap = seriesCount > 1 && subWidth > 3 ? Math.min(1, subWidth * 0.15) : 0;
   const barThick = Math.max(0, subWidth - gap);
+  const t = model.entranceProgress ?? 1;
+  const grow = (pixel) => model.y.baseline + (pixel - model.y.baseline) * t;
   model.series.forEach((series, seriesIndex) => {
     ctx.fillStyle = series.color;
     for (const row of series.rows) {
@@ -7436,7 +7572,7 @@ function drawGroupedBars(ctx, model, radius, pen) {
       const center2 = model.x.pixel(readX(row));
       if (center2 == null) continue;
       const catStart = center2 - bandWidth / 2 + seriesIndex * subWidth + gap / 2;
-      const rect = orientedRect(horizontal, catStart, barThick, model.y.baseline, model.y.pixel(value), series.color);
+      const rect = orientedRect(horizontal, catStart, barThick, grow(model.y.baseline), grow(model.y.pixel(value)), series.color);
       if (rect) drawRect(ctx, rect, radius, pen, rowAlpha(model.emphasis, row));
     }
   });
@@ -7450,6 +7586,8 @@ function drawStackedBars(ctx, model, radius, pen) {
   const segments = [];
   const roundedEnds = /* @__PURE__ */ new Map();
   const bandWidth = model.x.bandwidth;
+  const t = model.entranceProgress ?? 1;
+  const grow = (pixel) => model.y.baseline + (pixel - model.y.baseline) * t;
   for (const series of model.series) {
     for (const row of series.rows) {
       const xValue = readX(row);
@@ -7464,7 +7602,7 @@ function drawStackedBars(ctx, model, radius, pen) {
       const base = totals.get(categoryKey2) ?? 0;
       const top = base + value;
       totals.set(categoryKey2, top);
-      const rect = orientedRect(horizontal, center2 - bandWidth / 2, bandWidth, model.y.pixel(base), model.y.pixel(top), series.color);
+      const rect = orientedRect(horizontal, center2 - bandWidth / 2, bandWidth, grow(model.y.pixel(base)), grow(model.y.pixel(top)), series.color);
       if (!rect) continue;
       segments.push({ ...rect, stackEndKey, alpha: rowAlpha(model.emphasis, row) });
       roundedEnds.set(stackEndKey, segments.length - 1);
@@ -8597,6 +8735,8 @@ function drawPie(surface, spec, tokens, size, context) {
   const colorField = pie.encoding.color.field;
   const emphasis = context?.emphasis ?? null;
   const sliceAlpha = (slice) => emphasis ? emphasis.match({ [colorField]: slice.category }) ? 1 : emphasis.dim : 1;
+  const sweepT = context?.sweepProgress ?? 1;
+  const sweepEnd = TAU3 * sweepT;
   const content = drawTitleBlock(surface, tokens, size, pie.title);
   const slices = buildSlices(pie, tokens.color.palette);
   const legendPosition = resolveLegendPosition(pie, content.width, content.height);
@@ -8654,9 +8794,11 @@ function drawPie(surface, spec, tokens, size, context) {
   if (sketch) {
     const pen = new RoughPen(ctx, sketch);
     for (const slice of slices) {
+      const end = Math.min(slice.endAngle, sweepEnd);
+      if (end <= slice.startAngle) continue;
       const alpha = sliceAlpha(slice);
       if (alpha !== 1) ctx.globalAlpha = alpha;
-      pen.wedge(cx, cy, innerRadius, outerRadius, slice.startAngle, slice.endAngle, {
+      pen.wedge(cx, cy, innerRadius, outerRadius, slice.startAngle, end, {
         fill: slice.color,
         stroke: separator
       });
@@ -8665,11 +8807,13 @@ function drawPie(surface, spec, tokens, size, context) {
     ctx.restore();
   } else {
     for (const slice of slices) {
+      const end = Math.min(slice.endAngle, sweepEnd);
+      if (end <= slice.startAngle) continue;
       const wedge = arc({
         innerRadius,
         outerRadius,
         startAngle: slice.startAngle,
-        endAngle: slice.endAngle
+        endAngle: end
       });
       ctx.beginPath();
       wedge(ctx, cx, cy);
@@ -8681,7 +8825,7 @@ function drawPie(surface, spec, tokens, size, context) {
     }
     ctx.restore();
   }
-  if (labelPlan && labelCfg) {
+  if (sweepT >= 1 && labelPlan && labelCfg) {
     ctx.save();
     ctx.lineWidth = 1;
     ctx.lineJoin = "round";
@@ -8725,7 +8869,7 @@ function drawPie(surface, spec, tokens, size, context) {
       });
     }
   }
-  if (innerRadius >= 34) {
+  if (sweepT >= 1 && innerRadius >= 34) {
     addOverlayText(surface, tokens, {
       left: cx,
       top: cy - tokens.font.size.small - 2,
@@ -9010,19 +9154,9 @@ function drawFunnel(surface, spec, tokens, size, context) {
 
 // src/charts/kpi.ts
 var SVG_NS = "http://www.w3.org/2000/svg";
-var SKETCH_BORDER_RADIUS = "255px 15px 225px 15px / 15px 225px 15px 255px";
 function clamp5(value, min, max) {
   return Math.max(min, Math.min(max, value));
 }
-function resolveValue(ref, data) {
-  if (ref == null) return null;
-  if (typeof ref === "number") return Number.isFinite(ref) ? ref : null;
-  const read = accessor(ref.field);
-  return aggregateValues(
-    data.map((d) => read(d)),
-    ref.aggregate ?? "sum"
-  );
-}
 function valueField(ref) {
   return typeof ref === "number" ? null : ref.field;
 }
@@ -9033,6 +9167,12 @@ function formatDelta(delta, specFormat) {
   if (abs <= 1) return sign2 + formatNumber2(abs, ".1%");
   return sign2 + formatNumber2(abs, ",.0f");
 }
+function flexAlign(align) {
+  return align === "start" ? "flex-start" : align === "end" ? "flex-end" : "center";
+}
+function textAlignOf(align) {
+  return align === "start" ? "left" : align === "end" ? "right" : "center";
+}
 function cardRectFor(surface, tokens, size, spec) {
   if (spec.title) return drawTitleBlock(surface, tokens, size, spec.title);
   return {
@@ -9042,41 +9182,25 @@ function cardRectFor(surface, tokens, size, spec) {
     height: Math.max(0, size.height - CHROME_PAD.top - CHROME_PAD.bottom)
   };
 }
-function createCard(tokens, rect, hasSparkline, framed = false) {
-  const card = document.createElement("div");
-  const pad3 = tokens.spacing.lg;
-  const sparkReserve = hasSparkline ? Math.min(44, Math.max(28, rect.height * 0.18)) + tokens.spacing.sm : 0;
-  card.style.position = "absolute";
-  card.style.left = `${rect.x}px`;
-  card.style.top = `${rect.y}px`;
-  card.style.width = `${rect.width}px`;
-  card.style.height = `${rect.height}px`;
-  card.style.boxSizing = "border-box";
-  card.style.background = framed ? "transparent" : tokens.color.surface;
-  card.style.border = framed ? "none" : `1px solid ${tokens.color.border}`;
-  card.style.borderRadius = `${tokens.radius.lg}px`;
-  card.style.padding = framed ? `0 0 ${sparkReserve}px` : `${pad3}px ${pad3}px ${pad3 + sparkReserve}px`;
-  card.style.display = "flex";
-  card.style.flexDirection = "column";
-  card.style.justifyContent = "center";
-  card.style.alignItems = "flex-start";
-  card.style.gap = `${tokens.spacing.sm}px`;
-  card.style.overflow = "hidden";
-  card.style.pointerEvents = "none";
-  return card;
+function valueFontSize(rect, contentWidth, valueText, unit, isRich) {
+  const effectiveLen = valueText.length + (unit ? unit.length * 0.5 + 0.4 : 0);
+  const sizeByCard = Math.min(rect.width, rect.height) * (isRich ? 0.17 : 0.28);
+  const sizeByText = contentWidth / Math.max(1, effectiveLen * 0.58);
+  const lo = isRich ? 22 : 26;
+  const hi = isRich ? 52 : 76;
+  return clamp5(Math.min(sizeByCard, sizeByText), lo, hi);
 }
-function addText2(card, text, style) {
-  const el = document.createElement("div");
-  el.textContent = text;
-  Object.assign(el.style, style);
-  card.appendChild(el);
-  return el;
+function unitFontSize(valueSize) {
+  return Math.max(12, valueSize * 0.46);
 }
 function sparklineField(spec) {
   if (!spec.sparkline) return null;
-  if (typeof spec.sparkline === "object") return spec.sparkline.field;
+  if (typeof spec.sparkline === "object") return spec.sparkline.field ?? valueField(spec.value);
   return valueField(spec.value);
 }
+function sparklineMarkers(spec) {
+  return typeof spec.sparkline === "object" ? spec.sparkline.markers !== false : true;
+}
 function sparklineValues(data, field) {
   const read = accessor(field);
   const values = [];
@@ -9086,41 +9210,165 @@ function sparklineValues(data, field) {
   }
   return values;
 }
-function buildSparkline(tokens, width, height, values) {
+function kpiSparklineSeries(spec, data) {
+  const field = sparklineField(spec);
+  return field ? sparklineValues(data, field) : [];
+}
+function morphSparkline(to, from, progress) {
+  if (progress == null || progress >= 1 || to.length === 0) return to;
+  const t = progress;
+  if (from && from.length === to.length) return to.map((v, i) => from[i] + (v - from[i]) * t);
+  const base = to[0];
+  return to.map((v) => base + (v - base) * t);
+}
+function resolveComparison(cmp, data, parentFormat) {
+  const delta = resolveValueRef(cmp.delta, data);
+  if (delta == null) return null;
+  const rawPositive = delta >= 0;
+  const tri = rawPositive ? "\u25B2" : "\u25BC";
+  let text = `${tri} ${formatValue(delta, cmp.format ?? ".0%")}`;
+  if (cmp.amount !== void 0) {
+    const amount = resolveValueRef(cmp.amount, data);
+    if (amount != null) text += ` : ${formatValue(amount, cmp.amountFormat ?? parentFormat ?? ",.0f")}`;
+  }
+  return { label: cmp.label, text, positive: cmp.invert ? !rawPositive : rawPositive };
+}
+function layoutKpi(rect, tokens, framed, f) {
+  const font = tokens.font;
+  const pad3 = framed ? 0 : tokens.spacing.lg;
+  const left = rect.x + pad3;
+  const contentWidth = Math.max(1, rect.width - pad3 * 2);
+  const availTop = rect.y + pad3;
+  const availH = Math.max(0, rect.height - pad3 * 2);
+  const labelSize = Math.round(clamp5(f.valueSize * 0.4, font.size.small, font.size.title));
+  const labelH = f.hasLabel ? Math.round(labelSize * 1.35) : 0;
+  const valueH = Math.round(f.valueSize * 1.06);
+  const deltaSize = font.size.large;
+  const deltaH = f.hasDelta ? Math.round(deltaSize * 1.5) : 0;
+  const compSize = font.size.large;
+  const compRowH = Math.round(compSize * 1.55);
+  const gapLabel = Math.round(labelSize * 0.25);
+  const gapDelta = f.hasDelta ? tokens.spacing.xs : 0;
+  const gapSpark = tokens.spacing.sm;
+  const dividerPad = tokens.spacing.sm;
+  const headerH = (f.hasLabel && f.labelAbove ? labelH + gapLabel : 0) + valueH + (f.hasLabel && !f.labelAbove ? gapLabel + labelH : 0) + (f.hasDelta ? gapDelta + deltaH : 0);
+  const footerH = f.compCount > 0 ? dividerPad + 1 + dividerPad + f.compCount * compRowH : 0;
+  let headerTop;
+  let footerTop;
+  let spark = null;
+  if (f.hasSparkline) {
+    headerTop = availTop;
+    footerTop = availTop + availH - footerH;
+    const sparkTop = headerTop + headerH + gapSpark;
+    const sparkBottom = footerTop - (footerH > 0 ? gapSpark : 0);
+    spark = { x: left, y: sparkTop, width: contentWidth, height: Math.max(24, sparkBottom - sparkTop) };
+  } else {
+    const groupH = headerH + (footerH > 0 ? tokens.spacing.md + footerH : 0);
+    headerTop = availTop + Math.max(0, (availH - groupH) / 2);
+    footerTop = headerTop + headerH + (footerH > 0 ? tokens.spacing.md : 0);
+  }
+  let y = headerTop;
+  let labelY = -1;
+  if (f.hasLabel && f.labelAbove) {
+    labelY = y;
+    y += labelH + gapLabel;
+  }
+  const valueY = y;
+  y += valueH;
+  if (f.hasLabel && !f.labelAbove) {
+    y += gapLabel;
+    labelY = y;
+    y += labelH;
+  }
+  let deltaY = -1;
+  if (f.hasDelta) {
+    y += gapDelta;
+    deltaY = y;
+  }
+  let dividerY = -1;
+  let compStartY = -1;
+  if (f.compCount > 0) {
+    dividerY = footerTop + dividerPad;
+    compStartY = dividerY + 1 + dividerPad;
+  }
+  return {
+    left,
+    contentWidth,
+    labelSize,
+    labelY,
+    valueY,
+    valueH,
+    deltaSize,
+    deltaY,
+    spark,
+    compSize,
+    compRowH,
+    dividerY,
+    compStartY
+  };
+}
+function sparkMarkers(values, xAt, yAt, r, tokens) {
+  const n = values.length;
+  if (n < 2) return [];
+  let minIdx = 0;
+  let maxIdx = 0;
+  for (let i = 1; i < n; i++) {
+    if (values[i] < values[minIdx]) minIdx = i;
+    if (values[i] > values[maxIdx]) maxIdx = i;
+  }
+  const lastIdx = n - 1;
+  const out = [];
+  if (maxIdx !== lastIdx) out.push({ x: xAt(maxIdx), y: yAt(values[maxIdx]), r, fill: tokens.color.positive });
+  if (minIdx !== lastIdx) out.push({ x: xAt(minIdx), y: yAt(values[minIdx]), r, fill: tokens.color.negative });
+  const lastStroke = lastIdx === maxIdx ? tokens.color.positive : lastIdx === minIdx ? tokens.color.negative : tokens.color.text;
+  out.push({
+    x: xAt(lastIdx),
+    y: yAt(values[lastIdx]),
+    r,
+    fill: tokens.color.surface,
+    stroke: lastStroke,
+    strokeWidth: 1.75
+  });
+  return out;
+}
+function sparkScales(values, width, height, markers) {
+  const n = values.length;
+  const r = clamp5(Math.min(height, 40) * 0.12, 2.5, 4);
+  const padX = markers ? r + 1 : 1.75;
+  const padY = markers ? r + 1 : 1.75;
+  const innerW = Math.max(1, width - padX * 2);
+  const innerH = Math.max(1, height - padY * 2);
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const span = max - min;
+  const xAt = (i) => n === 1 ? width / 2 : padX + i / (n - 1) * innerW;
+  const yAt = (v) => padY + (1 - (span === 0 ? 0.5 : (v - min) / span)) * innerH;
+  return { xAt, yAt, r };
+}
+function buildSparkline(tokens, width, height, values, markers) {
   if (values.length === 0 || width <= 0 || height <= 0) return null;
   const svg = document.createElementNS(SVG_NS, "svg");
   svg.setAttribute("width", String(width));
   svg.setAttribute("height", String(height));
   svg.setAttribute("viewBox", `0 0 ${width} ${height}`);
-  svg.setAttribute("preserveAspectRatio", "none");
   svg.style.display = "block";
   svg.style.overflow = "visible";
   const stroke = 1.75;
-  const pad3 = stroke;
-  const innerH = Math.max(1, height - pad3 * 2);
+  const line2 = tokens.color.textMuted;
+  const { xAt, yAt, r } = sparkScales(values, width, height, markers);
   const n = values.length;
-  const min = Math.min(...values);
-  const max = Math.max(...values);
-  const span = max - min;
-  const xAt = (i) => n === 1 ? width / 2 : i / (n - 1) * width;
-  const yAt = (v) => {
-    const t = span === 0 ? 0.5 : (v - min) / span;
-    return pad3 + (1 - t) * innerH;
-  };
   if (n === 1) {
     const dot = document.createElementNS(SVG_NS, "circle");
     dot.setAttribute("cx", String(width / 2));
     dot.setAttribute("cy", String(yAt(values[0])));
-    dot.setAttribute("r", "2.25");
+    dot.setAttribute("r", "2.5");
     dot.setAttribute("fill", tokens.color.accent);
     svg.appendChild(dot);
     return svg;
   }
   let lineD = "";
-  for (let i = 0; i < n; i++) {
-    lineD += `${i === 0 ? "M" : "L"}${xAt(i).toFixed(2)} ${yAt(values[i]).toFixed(2)}`;
-  }
-  const areaD = `${lineD}L${width.toFixed(2)} ${height}L0 ${height}Z`;
+  for (let i = 0; i < n; i++) lineD += `${i === 0 ? "M" : "L"}${xAt(i).toFixed(2)} ${yAt(values[i]).toFixed(2)}`;
+  const areaD = `${lineD}L${xAt(n - 1).toFixed(2)} ${height}L${xAt(0).toFixed(2)} ${height}Z`;
   const gradId = `graphein-spark-${Math.random().toString(36).slice(2, 9)}`;
   const defs = document.createElementNS(SVG_NS, "defs");
   const grad = document.createElementNS(SVG_NS, "linearGradient");
@@ -9131,11 +9379,11 @@ function buildSparkline(tokens, width, height, values) {
   grad.setAttribute("y2", "1");
   const stopTop = document.createElementNS(SVG_NS, "stop");
   stopTop.setAttribute("offset", "0");
-  stopTop.setAttribute("stop-color", tokens.color.accent);
-  stopTop.setAttribute("stop-opacity", "0.24");
+  stopTop.setAttribute("stop-color", line2);
+  stopTop.setAttribute("stop-opacity", "0.18");
   const stopBottom = document.createElementNS(SVG_NS, "stop");
   stopBottom.setAttribute("offset", "1");
-  stopBottom.setAttribute("stop-color", tokens.color.accent);
+  stopBottom.setAttribute("stop-color", line2);
   stopBottom.setAttribute("stop-opacity", "0");
   grad.appendChild(stopTop);
   grad.appendChild(stopBottom);
@@ -9148,14 +9396,43 @@ function buildSparkline(tokens, width, height, values) {
   const path = document.createElementNS(SVG_NS, "path");
   path.setAttribute("d", lineD);
   path.setAttribute("fill", "none");
-  path.setAttribute("stroke", tokens.color.accent);
+  path.setAttribute("stroke", line2);
   path.setAttribute("stroke-width", String(stroke));
   path.setAttribute("stroke-linejoin", "round");
   path.setAttribute("stroke-linecap", "round");
   svg.appendChild(path);
+  if (markers) {
+    for (const m of sparkMarkers(values, xAt, yAt, r, tokens)) {
+      const c = document.createElementNS(SVG_NS, "circle");
+      c.setAttribute("cx", m.x.toFixed(2));
+      c.setAttribute("cy", m.y.toFixed(2));
+      c.setAttribute("r", String(m.r));
+      c.setAttribute("fill", m.fill ?? "none");
+      if (m.stroke) {
+        c.setAttribute("stroke", m.stroke);
+        c.setAttribute("stroke-width", String(m.strokeWidth ?? 1.75));
+      }
+      svg.appendChild(c);
+    }
+  }
   return svg;
 }
-function buildSparklineCanvas(tokens, width, height, values, sketch) {
+function paintSparkMarkers(ctx, values, xAt, yAt, r, tokens) {
+  for (const m of sparkMarkers(values, xAt, yAt, r, tokens)) {
+    ctx.beginPath();
+    ctx.arc(m.x, m.y, m.r, 0, Math.PI * 2);
+    if (m.fill) {
+      ctx.fillStyle = m.fill;
+      ctx.fill();
+    }
+    if (m.stroke) {
+      ctx.lineWidth = m.strokeWidth ?? 1.75;
+      ctx.strokeStyle = m.stroke;
+      ctx.stroke();
+    }
+  }
+}
+function buildSparklineCanvas(tokens, width, height, values, markers, sketch) {
   if (values.length === 0 || width <= 0 || height <= 0) return null;
   const dpr = getDevicePixelRatio();
   const canvas = document.createElement("canvas");
@@ -9167,207 +9444,339 @@ function buildSparklineCanvas(tokens, width, height, values, sketch) {
   const ctx = canvas.getContext("2d");
   if (!ctx) return null;
   ctx.scale(dpr, dpr);
-  const stroke = 1.75;
-  const pad3 = stroke;
-  const innerH = Math.max(1, height - pad3 * 2);
+  const { xAt, yAt, r } = sparkScales(values, width, height, markers);
   const n = values.length;
-  const min = Math.min(...values);
-  const max = Math.max(...values);
-  const span = max - min;
-  const xAt = (i) => n === 1 ? width / 2 : i / (n - 1) * width;
-  const yAt = (v) => pad3 + (1 - (span === 0 ? 0.5 : (v - min) / span)) * innerH;
   const pen = new RoughPen(ctx, sketch);
   if (n === 1) {
     pen.circle(width / 2, yAt(values[0]), 2.5, { fill: tokens.color.accent });
     return canvas;
   }
   const points = values.map((v, i) => ({ x: xAt(i), y: yAt(v) }));
-  pen.trendStroke(points, { stroke: tokens.color.accent, strokeWidth: stroke });
+  pen.trendStroke(points, { stroke: tokens.color.textMuted, strokeWidth: 1.75 });
+  if (markers) paintSparkMarkers(ctx, values, xAt, yAt, r, tokens);
   return canvas;
 }
-function drawKpi(surface, spec, tokens, size, context) {
-  const kpi = spec;
-  if (surface.headless) {
-    drawKpiCanvas(surface, kpi, tokens, size, context);
+function paintSparklineCanvas(ctx, tokens, box, values, markers) {
+  if (values.length === 0 || box.width <= 0 || box.height <= 0) return;
+  const { xAt: xAt0, yAt: yAt0, r } = sparkScales(values, box.width, box.height, markers);
+  const xAt = (i) => box.x + xAt0(i);
+  const yAt = (v) => box.y + yAt0(v);
+  const n = values.length;
+  ctx.save();
+  if (n === 1) {
+    ctx.beginPath();
+    ctx.arc(xAt(0), yAt(values[0]), 2.5, 0, Math.PI * 2);
+    ctx.fillStyle = tokens.color.accent;
+    ctx.fill();
+    ctx.restore();
     return;
   }
+  ctx.globalAlpha = 0.16;
+  ctx.beginPath();
+  ctx.moveTo(xAt(0), yAt(values[0]));
+  for (let i = 1; i < n; i++) ctx.lineTo(xAt(i), yAt(values[i]));
+  ctx.lineTo(xAt(n - 1), box.y + box.height);
+  ctx.lineTo(xAt(0), box.y + box.height);
+  ctx.closePath();
+  ctx.fillStyle = tokens.color.textMuted;
+  ctx.fill();
+  ctx.globalAlpha = 1;
+  ctx.beginPath();
+  for (let i = 0; i < n; i++) {
+    const px = xAt(i);
+    const py = yAt(values[i]);
+    if (i === 0) ctx.moveTo(px, py);
+    else ctx.lineTo(px, py);
+  }
+  ctx.strokeStyle = tokens.color.textMuted;
+  ctx.lineWidth = 1.75;
+  ctx.lineJoin = "round";
+  ctx.lineCap = "round";
+  ctx.stroke();
+  if (markers) paintSparkMarkers(ctx, values, xAt, yAt, r, tokens);
+  ctx.restore();
+}
+function drawKpi(surface, spec, tokens, size, context) {
+  const kpi = spec;
   const data = kpi.data ?? [];
-  const value = resolveValue(kpi.value, data);
-  const delta = resolveValue(kpi.delta, data);
+  const value = resolveValueRef(kpi.value, data);
+  const delta = resolveValueRef(kpi.delta, data);
   const sparkField = sparklineField(kpi);
   const sparkValues = sparkField ? sparklineValues(data, sparkField) : [];
   const hasSparkline = sparkValues.length > 0;
-  const sketch = resolveSketch(spec);
+  const markers = sparklineMarkers(kpi);
+  const comparisons = kpi.comparisons?.map((c) => resolveComparison(c, data, kpi.format)).filter((c) => c != null) ?? [];
+  const hasDelta = delta != null;
+  const isRich = hasDelta || hasSparkline || comparisons.length > 0;
+  const align = kpi.align ?? "center";
+  const labelAbove = kpi.labelPosition === "above" || kpi.labelPosition == null && isRich;
   const framed = context?.framed === true;
   const rect = cardRectFor(surface, tokens, size, kpi);
-  const card = createCard(tokens, rect, hasSparkline, framed);
-  if (sketch) card.style.borderRadius = SKETCH_BORDER_RADIUS;
-  if (kpi.label) {
-    addText2(card, kpi.label, {
+  const progress = context?.valueProgress;
+  const from = context?.valueFrom ?? 0;
+  const displayValue = value != null && progress != null && progress < 1 ? from + (value - from) * progress : value;
+  const displaySparkValues = morphSparkline(sparkValues, context?.sparklineFrom, progress);
+  const valueText = value == null ? "\u2014" : formatValue(value, kpi.format);
+  const displayText = displayValue == null ? "\u2014" : formatValue(displayValue, kpi.format);
+  const fromText = context?.valueFrom != null && value != null ? formatValue(context.valueFrom, kpi.format) : valueText;
+  const sizingText = fromText.length > valueText.length ? fromText : valueText;
+  const pad3 = framed ? 0 : tokens.spacing.lg;
+  const contentWidth = Math.max(1, rect.width - pad3 * 2);
+  const valueSize = valueFontSize(rect, contentWidth, sizingText, kpi.unit, isRich);
+  const geom = layoutKpi(rect, tokens, framed, {
+    hasLabel: !!kpi.label,
+    labelAbove,
+    hasDelta,
+    hasSparkline,
+    compCount: comparisons.length,
+    valueSize
+  });
+  const sketch = resolveSketch(spec);
+  if (surface.headless) {
+    drawKpiCanvas(surface, kpi, tokens, {
+      align,
+      valueSize,
+      displayText,
+      delta,
+      comparisons,
+      sparkValues: displaySparkValues,
+      markers,
+      geom
+    });
+    return;
+  }
+  const card = document.createElement("div");
+  card.style.position = "absolute";
+  card.style.left = `${rect.x}px`;
+  card.style.top = `${rect.y}px`;
+  card.style.width = `${rect.width}px`;
+  card.style.height = `${rect.height}px`;
+  card.style.boxSizing = "border-box";
+  card.style.overflow = "hidden";
+  card.style.pointerEvents = "none";
+  const ox = rect.x;
+  const oy = rect.y;
+  const addAt = (el, left, top, width) => {
+    el.style.position = "absolute";
+    el.style.left = `${left - ox}px`;
+    el.style.top = `${top - oy}px`;
+    el.style.width = `${width}px`;
+    card.appendChild(el);
+  };
+  if (kpi.label && geom.labelY >= 0) {
+    const el = document.createElement("div");
+    el.textContent = kpi.label;
+    Object.assign(el.style, {
       color: tokens.color.textMuted,
       fontFamily: tokens.font.family,
-      fontSize: `${tokens.font.size.base}px`,
+      fontSize: `${geom.labelSize}px`,
       fontWeight: String(tokens.font.weight.medium),
-      letterSpacing: "0.04em",
       lineHeight: "1.25",
-      textTransform: "uppercase",
-      maxWidth: "100%",
+      textAlign: align === "start" ? "left" : align === "end" ? "right" : "center",
       overflow: "hidden",
       textOverflow: "ellipsis",
       whiteSpace: "nowrap"
     });
-  }
-  const valueText = value == null ? "\u2014" : formatValue(value, kpi.format);
-  const contentWidth = Math.max(1, rect.width - tokens.spacing.lg * 2);
-  const sizeByCard = Math.min(rect.width, rect.height) * 0.22;
-  const sizeByText = contentWidth / Math.max(1, valueText.length * 0.58);
-  const valueSize = clamp5(Math.min(sizeByCard, sizeByText), 28, 64);
-  addText2(card, valueText, {
-    color: tokens.color.text,
+    addAt(el, geom.left, geom.labelY, geom.contentWidth);
+  }
+  const valueWrap = document.createElement("div");
+  valueWrap.style.display = "flex";
+  valueWrap.style.alignItems = "baseline";
+  valueWrap.style.justifyContent = flexAlign(align);
+  valueWrap.style.gap = "0.12em";
+  valueWrap.style.height = `${geom.valueH}px`;
+  valueWrap.style.overflow = "hidden";
+  const num2 = document.createElement("div");
+  num2.textContent = displayText;
+  Object.assign(num2.style, {
+    color: kpi.color ?? tokens.color.text,
     fontFamily: tokens.font.family,
     fontSize: `${valueSize}px`,
     fontWeight: String(tokens.font.weight.bold),
     letterSpacing: "-0.03em",
     lineHeight: "1.02",
-    maxWidth: "100%",
     overflow: "hidden",
     textOverflow: "ellipsis",
     whiteSpace: "nowrap"
   });
-  if (delta != null) {
+  valueWrap.appendChild(num2);
+  if (kpi.unit) {
+    const unit = document.createElement("div");
+    unit.textContent = kpi.unit;
+    Object.assign(unit.style, {
+      color: tokens.color.textMuted,
+      fontFamily: tokens.font.family,
+      fontSize: `${unitFontSize(valueSize)}px`,
+      fontWeight: String(tokens.font.weight.medium),
+      whiteSpace: "nowrap",
+      flex: "0 0 auto"
+    });
+    valueWrap.appendChild(unit);
+  }
+  addAt(valueWrap, geom.left, geom.valueY, geom.contentWidth);
+  if (hasDelta && geom.deltaY >= 0 && delta != null) {
     const positive = delta >= 0;
-    addText2(card, `${positive ? "\u25B2" : "\u25BC"} ${formatDelta(delta, kpi.format)}`, {
+    const el = document.createElement("div");
+    el.textContent = `${positive ? "\u25B2" : "\u25BC"} ${formatDelta(delta, kpi.format)}`;
+    Object.assign(el.style, {
       color: positive ? tokens.color.positive : tokens.color.negative,
       fontFamily: tokens.font.family,
-      fontSize: `${tokens.font.size.large}px`,
+      fontSize: `${geom.deltaSize}px`,
       fontWeight: String(tokens.font.weight.medium),
-      lineHeight: "1",
+      lineHeight: "1.2",
+      textAlign: align === "start" ? "left" : align === "end" ? "right" : "center",
       whiteSpace: "nowrap"
     });
+    addAt(el, geom.left, geom.deltaY, geom.contentWidth);
+  }
+  if (geom.spark) {
+    const node = sketch ? buildSparklineCanvas(tokens, geom.spark.width, geom.spark.height, displaySparkValues, markers, sketch) : buildSparkline(tokens, geom.spark.width, geom.spark.height, displaySparkValues, markers);
+    if (node) addAt(node, geom.spark.x, geom.spark.y, geom.spark.width);
+  }
+  if (comparisons.length > 0 && geom.dividerY >= 0) {
+    const divider = document.createElement("div");
+    divider.style.height = "1px";
+    divider.style.background = tokens.color.border;
+    addAt(divider, geom.left, geom.dividerY, geom.contentWidth);
+    comparisons.forEach((c, i) => {
+      const row = document.createElement("div");
+      row.style.display = "flex";
+      row.style.alignItems = "baseline";
+      row.style.gap = "0.5em";
+      row.style.height = `${geom.compRowH}px`;
+      row.style.overflow = "hidden";
+      const label = document.createElement("span");
+      label.textContent = c.label;
+      Object.assign(label.style, {
+        color: tokens.color.text,
+        fontFamily: tokens.font.family,
+        fontSize: `${geom.compSize}px`,
+        fontWeight: String(tokens.font.weight.medium),
+        whiteSpace: "nowrap",
+        flex: "0 0 auto"
+      });
+      const val = document.createElement("span");
+      val.textContent = c.text;
+      Object.assign(val.style, {
+        color: c.positive ? tokens.color.positive : tokens.color.negative,
+        fontFamily: tokens.font.family,
+        fontSize: `${geom.compSize}px`,
+        fontWeight: String(tokens.font.weight.medium),
+        whiteSpace: "nowrap"
+      });
+      row.appendChild(label);
+      row.appendChild(val);
+      addAt(row, geom.left, geom.compStartY + i * geom.compRowH, geom.contentWidth);
+    });
   }
   surface.overlay.appendChild(card);
-  if (hasSparkline) {
-    const pad3 = framed ? 0 : tokens.spacing.lg;
-    const sparkH = clamp5(rect.height * 0.18, 24, 40);
-    const sparkW = Math.max(0, rect.width - pad3 * 2);
-    const node = sketch ? buildSparklineCanvas(tokens, sparkW, sparkH, sparkValues, sketch) : buildSparkline(tokens, sparkW, sparkH, sparkValues);
-    if (node) {
-      node.style.position = "absolute";
-      node.style.left = `${pad3}px`;
-      node.style.bottom = `${pad3}px`;
-      card.appendChild(node);
-    }
-  }
 }
-function drawKpiCanvas(surface, kpi, tokens, size, context) {
+function drawKpiCanvas(surface, kpi, tokens, p) {
   const ctx = surface.marks.ctx;
-  const data = kpi.data ?? [];
-  const value = resolveValue(kpi.value, data);
-  const delta = resolveValue(kpi.delta, data);
-  const sparkField = sparklineField(kpi);
-  const sparkValues = sparkField ? sparklineValues(data, sparkField) : [];
-  const hasSparkline = sparkValues.length > 0;
-  const framed = context?.framed === true;
-  const rect = cardRectFor(surface, tokens, size, kpi);
-  const pad3 = tokens.spacing.lg;
-  const sparkReserve = hasSparkline ? Math.min(44, Math.max(28, rect.height * 0.18)) + tokens.spacing.sm : 0;
-  if (!framed) {
-    ctx.save();
-    ctx.beginPath();
-    roundedRect(ctx, rect.x, rect.y, rect.width, rect.height, tokens.radius.lg);
-    ctx.fillStyle = tokens.color.surface;
-    ctx.fill();
-    ctx.lineWidth = 1;
-    ctx.strokeStyle = tokens.color.border;
-    ctx.stroke();
-    ctx.restore();
-  }
-  const left = rect.x + (framed ? 0 : pad3);
-  const contentWidth = Math.max(1, rect.width - (framed ? 0 : pad3 * 2));
-  const valueText = value == null ? "\u2014" : formatValue(value, kpi.format);
-  const sizeByCard = Math.min(rect.width, rect.height) * 0.22;
-  const sizeByText = contentWidth / Math.max(1, valueText.length * 0.58);
-  const valueSize = clamp5(Math.min(sizeByCard, sizeByText), 28, 64);
-  const labelH = kpi.label ? tokens.font.size.base * 1.25 : 0;
-  const deltaH = delta != null ? tokens.font.size.large : 0;
-  const stackH = labelH + valueSize + deltaH + tokens.spacing.sm * 2;
-  const avail = rect.height - sparkReserve;
-  let y = rect.y + Math.max(framed ? 0 : pad3, (avail - stackH) / 2);
-  if (kpi.label) {
+  const { geom } = p;
+  const alignX = () => p.align === "start" ? geom.left : p.align === "end" ? geom.left + geom.contentWidth : geom.left + geom.contentWidth / 2;
+  const alignCanvas = textAlignOf(p.align);
+  if (kpi.label && geom.labelY >= 0) {
     paintCanvasText(ctx, {
-      x: left,
-      y,
-      text: kpi.label.toUpperCase(),
-      font: fontString(tokens.font.size.base, tokens.font.family, tokens.font.weight.medium),
+      x: alignX(),
+      y: geom.labelY,
+      text: kpi.label,
+      font: fontString(geom.labelSize, tokens.font.family, tokens.font.weight.medium),
       color: tokens.color.textMuted,
-      size: tokens.font.size.base,
+      size: geom.labelSize,
+      align: alignCanvas,
       baseline: "top"
     });
-    y += labelH + tokens.spacing.sm;
   }
+  const unitSize = kpi.unit ? unitFontSize(p.valueSize) : 0;
+  const numberFont = fontString(p.valueSize, tokens.font.family, tokens.font.weight.bold);
+  const unitFont = kpi.unit ? fontString(unitSize, tokens.font.family, tokens.font.weight.medium) : "";
+  ctx.save();
+  ctx.font = numberFont;
+  const numberW = ctx.measureText(p.displayText).width;
+  let unitW = 0;
+  if (kpi.unit) {
+    ctx.font = unitFont;
+    unitW = ctx.measureText(kpi.unit).width;
+  }
+  ctx.restore();
+  const unitGap = kpi.unit ? p.valueSize * 0.12 : 0;
+  const totalW = numberW + (kpi.unit ? unitGap + unitW : 0);
+  const groupX = p.align === "start" ? geom.left : p.align === "end" ? geom.left + geom.contentWidth - totalW : geom.left + (geom.contentWidth - totalW) / 2;
+  const baselineY = geom.valueY + p.valueSize * 0.82;
   paintCanvasText(ctx, {
-    x: left,
-    y,
-    text: valueText,
-    font: fontString(valueSize, tokens.font.family, tokens.font.weight.bold),
-    color: tokens.color.text,
-    size: valueSize,
-    baseline: "top"
+    x: groupX,
+    y: baselineY,
+    text: p.displayText,
+    font: numberFont,
+    color: kpi.color ?? tokens.color.text,
+    size: p.valueSize,
+    align: "left",
+    baseline: "alphabetic"
   });
-  y += valueSize + tokens.spacing.sm;
-  if (delta != null) {
-    const positive = delta >= 0;
+  if (kpi.unit) {
     paintCanvasText(ctx, {
-      x: left,
-      y,
-      text: `${positive ? "\u25B2" : "\u25BC"} ${formatDelta(delta, kpi.format)}`,
-      font: fontString(tokens.font.size.large, tokens.font.family, tokens.font.weight.medium),
+      x: groupX + numberW + unitGap,
+      y: baselineY,
+      text: kpi.unit,
+      font: unitFont,
+      color: tokens.color.textMuted,
+      size: unitSize,
+      align: "left",
+      baseline: "alphabetic"
+    });
+  }
+  if (p.delta != null && geom.deltaY >= 0) {
+    const positive = p.delta >= 0;
+    paintCanvasText(ctx, {
+      x: alignX(),
+      y: geom.deltaY,
+      text: `${positive ? "\u25B2" : "\u25BC"} ${formatDelta(p.delta, kpi.format)}`,
+      font: fontString(geom.deltaSize, tokens.font.family, tokens.font.weight.medium),
       color: positive ? tokens.color.positive : tokens.color.negative,
-      size: tokens.font.size.large,
+      size: geom.deltaSize,
+      align: alignCanvas,
       baseline: "top"
     });
   }
-  if (hasSparkline) {
-    const sparkH = clamp5(rect.height * 0.18, 24, 40);
-    const inset = framed ? 0 : pad3;
-    const sparkW = Math.max(0, rect.width - inset * 2);
-    const x0 = rect.x + inset;
-    const y1 = rect.y + rect.height - inset;
-    paintSparklineCanvas(ctx, tokens, x0, y1 - sparkH, sparkW, sparkH, sparkValues);
+  if (geom.spark && p.sparkValues.length > 0) {
+    paintSparklineCanvas(ctx, tokens, geom.spark, p.sparkValues, p.markers);
   }
-}
-function paintSparklineCanvas(ctx, tokens, x0, y0, width, height, values) {
-  if (values.length === 0 || width <= 0 || height <= 0) return;
-  const stroke = 1.75;
-  const pad3 = stroke;
-  const innerH = Math.max(1, height - pad3 * 2);
-  const n = values.length;
-  const min = Math.min(...values);
-  const max = Math.max(...values);
-  const span = max - min;
-  const xAt = (i) => x0 + (n === 1 ? width / 2 : i / (n - 1) * width);
-  const yAt = (v) => y0 + pad3 + (1 - (span === 0 ? 0.5 : (v - min) / span)) * innerH;
-  ctx.save();
-  if (n === 1) {
-    ctx.beginPath();
-    ctx.arc(xAt(0), yAt(values[0]), 2.25, 0, Math.PI * 2);
-    ctx.fillStyle = tokens.color.accent;
-    ctx.fill();
-  } else {
-    ctx.beginPath();
-    for (let i = 0; i < n; i++) {
-      const px = xAt(i);
-      const py = yAt(values[i]);
-      if (i === 0) ctx.moveTo(px, py);
-      else ctx.lineTo(px, py);
-    }
-    ctx.strokeStyle = tokens.color.accent;
-    ctx.lineWidth = stroke;
-    ctx.lineJoin = "round";
-    ctx.lineCap = "round";
-    ctx.stroke();
+  if (p.comparisons.length > 0 && geom.dividerY >= 0) {
+    ctx.save();
+    ctx.fillStyle = tokens.color.border;
+    ctx.fillRect(geom.left, geom.dividerY, geom.contentWidth, 1);
+    ctx.restore();
+    const compFont = fontString(geom.compSize, tokens.font.family, tokens.font.weight.medium);
+    const gap = geom.compSize * 0.5;
+    p.comparisons.forEach((c, i) => {
+      const rowY = geom.compStartY + i * geom.compRowH + geom.compRowH / 2;
+      ctx.save();
+      ctx.font = compFont;
+      const labelW = ctx.measureText(c.label).width;
+      ctx.restore();
+      paintCanvasText(ctx, {
+        x: geom.left,
+        y: rowY,
+        text: c.label,
+        font: compFont,
+        color: tokens.color.text,
+        size: geom.compSize,
+        align: "left",
+        baseline: "middle"
+      });
+      paintCanvasText(ctx, {
+        x: geom.left + labelW + gap,
+        y: rowY,
+        text: c.text,
+        font: compFont,
+        color: c.positive ? tokens.color.positive : tokens.color.negative,
+        size: geom.compSize,
+        align: "left",
+        baseline: "middle"
+      });
+    });
   }
-  ctx.restore();
 }
 
 // src/charts/sankey.ts
@@ -9834,18 +10243,24 @@ function drawLegend3(surface, tokens, legend, domain, scheme, format) {
     transform: "translateX(-100%)"
   });
 }
-function drawChoropleth(surface, spec, tokens, size) {
+function drawChoropleth(surface, spec, tokens, size, context) {
   const choropleth = spec;
+  const emphasis = context?.emphasis ?? null;
   const content = drawTitleBlock(surface, tokens, size, choropleth.title);
   const features = choropleth.geo?.features ?? [];
   if (features.length === 0 || content.width <= 0 || content.height <= 0) return;
   const readKey = accessor(choropleth.encoding.key.field);
   const readColor = accessor(choropleth.encoding.color.field);
   const valueByKey = /* @__PURE__ */ new Map();
+  const rowByKey = /* @__PURE__ */ new Map();
   for (const row of choropleth.data ?? []) {
-    const k = toKey(readKey(row));
-    const v = toNumber(readColor(row));
-    if (k !== "" && Number.isFinite(v)) valueByKey.set(k, v);
+    const datum = row;
+    const k = toKey(readKey(datum));
+    const v = toNumber(readColor(datum));
+    if (k !== "" && Number.isFinite(v)) {
+      valueByKey.set(k, v);
+      rowByKey.set(k, datum);
+    }
   }
   const projection = choropleth.projection ?? "mercator";
   const project = projector(
@@ -9863,6 +10278,7 @@ function drawChoropleth(surface, spec, tokens, size) {
   for (const feature of features) {
     const key = featureKey(feature, choropleth.featureId);
     const value = valueByKey.has(key) ? valueByKey.get(key) : null;
+    const row = rowByKey.get(key);
     if (value != null) {
       if (value < vMin) vMin = value;
       if (value > vMax) vMax = value;
@@ -9885,7 +10301,7 @@ function drawChoropleth(surface, spec, tokens, size) {
       }
       if (rings.length) polys.push(rings);
     }
-    projected.push({ key, name: featureName(feature, key), value, polys });
+    projected.push({ key, name: featureName(feature, key), value, row, polys });
   }
   const spanX = maxX - minX;
   const spanY = maxY - minY;
@@ -9932,6 +10348,7 @@ function drawChoropleth(surface, spec, tokens, size) {
       key: pf.key,
       name: pf.name,
       value: pf.value,
+      row: pf.row,
       color: pf.value == null ? noDataFill : rgbaToCss(cscale.map(pf.value)),
       polys,
       cx: count ? cx / count : 0,
@@ -9946,6 +10363,7 @@ function drawChoropleth(surface, spec, tokens, size) {
   ctx.strokeStyle = tokens.color.background;
   ctx.lineWidth = 0.75;
   for (const f of screen) {
+    ctx.globalAlpha = rowAlpha(emphasis, f.row ?? { [choropleth.encoding.key.field]: f.key });
     ctx.fillStyle = f.color;
     for (const polygon of f.polys) {
       ctx.beginPath();
@@ -9966,6 +10384,7 @@ function drawChoropleth(surface, spec, tokens, size) {
         }
       }
     }
+    ctx.globalAlpha = 1;
   }
   ctx.restore();
   if (legendHeight > 0) {
@@ -10120,7 +10539,7 @@ function colorToTone(color) {
 var HEADER_ROW_HEIGHT = 32;
 var MIN_COL_WIDTH = 72;
 var DEFAULT_BODY_ROW_HEIGHT = 30;
-var SKETCH_BORDER_RADIUS2 = "14px 6px 16px 7px / 7px 15px 6px 14px";
+var SKETCH_BORDER_RADIUS = "14px 6px 16px 7px / 7px 15px 6px 14px";
 function formatCellValue(value, column) {
   return formatValue(value, column.format);
 }
@@ -10160,7 +10579,7 @@ function buildTable(opts) {
     pointerEvents: "auto",
     boxSizing: "border-box",
     border: `1px solid ${opts.sketch ? "transparent" : tokens.color.border}`,
-    borderRadius: opts.sketch ? SKETCH_BORDER_RADIUS2 : `${tokens.radius.sm}px`,
+    borderRadius: opts.sketch ? SKETCH_BORDER_RADIUS : `${tokens.radius.sm}px`,
     background: tokens.color.background
   });
   container.replaceChildren();
@@ -13921,11 +14340,6 @@ function drawTreemap(surface, spec, tokens, size, context) {
 function clamp8(value, min, max) {
   return Math.max(min, Math.min(max, value));
 }
-function resolveValue2(ref, data) {
-  if (ref == null) return null;
-  if (typeof ref === "number") return Number.isFinite(ref) ? ref : null;
-  return aggregateValues((data ?? []).map(accessor(ref.field)), ref.aggregate ?? "sum");
-}
 function valueField2(ref) {
   return typeof ref === "number" ? null : ref.field;
 }
@@ -13949,7 +14363,7 @@ function arcPoints(cx, cy, radius, startAngle, endAngle) {
   }
   return points;
 }
-function strokePoints(ctx, pen, points, color, width) {
+function strokePoints(ctx, pen, points, color, width, cap2 = "butt") {
   if (points.length < 2) return;
   if (pen) {
     pen.polyline(points, { stroke: color, strokeWidth: width });
@@ -13960,29 +14374,12 @@ function strokePoints(ctx, pen, points, color, width) {
   ctx.moveTo(points[0].x, points[0].y);
   for (let i = 1; i < points.length; i++) ctx.lineTo(points[i].x, points[i].y);
   ctx.lineWidth = width;
-  ctx.lineCap = "round";
+  ctx.lineCap = cap2;
   ctx.lineJoin = "round";
   ctx.strokeStyle = color;
   ctx.stroke();
   ctx.restore();
 }
-function drawCircle(ctx, pen, cx, cy, radius, fill, stroke) {
-  if (pen) {
-    pen.circle(cx, cy, radius, { fill, stroke: stroke ?? fill, strokeWidth: 1 });
-    return;
-  }
-  ctx.save();
-  ctx.beginPath();
-  ctx.arc(cx, cy, radius, 0, Math.PI * 2);
-  ctx.fillStyle = fill;
-  ctx.fill();
-  if (stroke) {
-    ctx.strokeStyle = stroke;
-    ctx.lineWidth = 1;
-    ctx.stroke();
-  }
-  ctx.restore();
-}
 function drawCenteredMessage(surface, tokens, rect, text) {
   addOverlayText(surface, tokens, {
     left: rect.x,
@@ -13994,86 +14391,158 @@ function drawCenteredMessage(surface, tokens, rect, text) {
     align: "center"
   });
 }
+var LEGEND_SWATCH3 = 11;
+function measureLegendWidth(entries, font) {
+  let maxLabel = 0;
+  for (const e of entries) maxLabel = Math.max(maxLabel, measureText(e.label, font).width);
+  return Math.ceil(LEGEND_SWATCH3 + 6 + maxLabel + 4);
+}
+function drawGaugeLegend(surface, tokens, area2, entries) {
+  if (entries.length === 0) return;
+  const labelSize = tokens.font.size.small;
+  const rowH = Math.round(labelSize * 1.7);
+  const font = fontString(labelSize, tokens.font.family, tokens.font.weight.normal);
+  const colW = measureLegendWidth(entries, font);
+  const x = area2.x + area2.width - colW;
+  let y = area2.y;
+  if (surface.headless) {
+    const ctx = surface.marks.ctx;
+    for (const e of entries) {
+      const midY = y + rowH / 2;
+      paintLegendSwatch(ctx, x, midY, "square", e.color, LEGEND_SWATCH3);
+      paintCanvasText(ctx, {
+        x: x + LEGEND_SWATCH3 + 6,
+        y: midY,
+        text: e.label,
+        font,
+        color: tokens.color.text,
+        size: labelSize,
+        baseline: "middle"
+      });
+      y += rowH;
+    }
+    return;
+  }
+  for (const e of entries) {
+    const row = document.createElement("div");
+    row.style.position = "absolute";
+    row.style.left = `${x}px`;
+    row.style.top = `${y}px`;
+    row.style.display = "flex";
+    row.style.alignItems = "center";
+    row.style.gap = "6px";
+    row.style.pointerEvents = "none";
+    const swatch = document.createElement("span");
+    swatch.style.flex = "0 0 auto";
+    swatch.style.width = `${LEGEND_SWATCH3}px`;
+    swatch.style.height = `${LEGEND_SWATCH3}px`;
+    swatch.style.borderRadius = "2px";
+    swatch.style.background = e.color;
+    const label = document.createElement("span");
+    label.textContent = e.label;
+    label.style.font = font;
+    label.style.color = tokens.color.text;
+    label.style.whiteSpace = "nowrap";
+    row.appendChild(swatch);
+    row.appendChild(label);
+    surface.overlay.appendChild(row);
+    y += rowH;
+  }
+}
+function bandFillColor(gauge, value, tokens, accent) {
+  const bands = gauge.bands;
+  if (!bands?.length) return accent;
+  const palette = tokens.color.palette;
+  for (let i = 0; i < bands.length; i++) {
+    if (value <= bands[i].to) return bands[i].color ?? palette[i % palette.length] ?? accent;
+  }
+  const last = bands.length - 1;
+  return bands[last].color ?? palette[last % palette.length] ?? accent;
+}
 function drawGauge(surface, spec, tokens, size, context) {
   const gauge = spec;
   const ctx = surface.marks.ctx;
   const content = drawTitleBlock(surface, tokens, size, gauge.title);
   const data = gauge.data ?? [];
-  const value = resolveValue2(gauge.value, data);
-  const target = resolveValue2(gauge.target, data);
+  const value = resolveValueRef(gauge.value, data);
+  const target = resolveValueRef(gauge.target, data);
+  const compare2 = resolveValueRef(gauge.compare, data);
   const min = gauge.min ?? 0;
   const max = gauge.max;
   if (value == null || !Number.isFinite(min) || !Number.isFinite(max) || max <= min || content.width <= 0 || content.height <= 0) {
     drawCenteredMessage(surface, tokens, content, "No value");
     return;
   }
+  const sketch = resolveSketch(spec);
+  const pen = sketch ? new RoughPen(ctx, sketch) : null;
+  const accent = tokens.color.palette[0] ?? tokens.color.accent;
+  const fill = bandFillColor(gauge, value, tokens, accent);
+  const track = tokens.dark ? withAlpha3(tokens.color.textMuted, 0.3) : tokens.color.border;
+  const compareColor = tokens.color.textMuted;
+  const markColor = tokens.dark ? withAlpha3("#ffffff", 0.92) : withAlpha3(tokens.color.text, 0.82);
+  const targetMark = target != null && target >= min && target <= max ? target : null;
   const valueText = formatValue(value, gauge.format);
   const caption = gauge.label ?? titleText(gauge.title) ?? valueField2(gauge.value) ?? "Value";
-  const valueSize = clamp8(Math.min(content.width / Math.max(6, valueText.length * 0.55), tokens.font.size.title * 2.4), 24, 42);
   const captionSize = tokens.font.size.small;
-  const readoutReserve = valueSize + captionSize + 24;
-  const radius = Math.max(18, Math.min((content.width - 48) / 2, content.height - readoutReserve - 18));
-  const cx = content.x + content.width / 2;
-  const cy = content.y + Math.max(radius + 8, (content.height - readoutReserve + radius) / 2);
-  const trackWidth = clamp8(radius * 0.17, 10, 22);
-  const accent = tokens.color.palette[0] ?? tokens.color.accent;
-  const track = withAlpha3(tokens.color.border || tokens.color.textMuted, tokens.dark ? 0.75 : 0.9);
-  const needleColor = tokens.color.text;
+  const captionReserve = captionSize + 16;
+  const showLegend = gauge.legend ?? compare2 != null;
+  const legendEntries = [];
+  if (showLegend) {
+    legendEntries.push({ label: gauge.valueLabel ?? "Actual", color: fill, symbol: "square" });
+    if (compare2 != null) {
+      legendEntries.push({ label: gauge.compareLabel ?? "Prior period", color: compareColor, symbol: "square" });
+    }
+    legendEntries.push({ label: gauge.trackLabel ?? "Target", color: targetMark != null ? markColor : track, symbol: "square" });
+  }
+  const legendFont = fontString(tokens.font.size.small, tokens.font.family, tokens.font.weight.normal);
+  const legendW = legendEntries.length ? measureLegendWidth(legendEntries, legendFont) + 12 : 0;
+  const dialW = Math.max(40, content.width - legendW);
+  const radius = clamp8(
+    Math.min((dialW - 16) / 2, content.height - captionReserve - 16),
+    18,
+    Math.min(dialW, content.height * 2)
+  );
+  const trackWidth = clamp8(radius * 0.17, 14, 54);
+  const cx = content.x + dialW / 2;
+  const blockH = radius + trackWidth / 2 + captionReserve;
+  const topMargin = Math.max(0, (content.height - blockH) / 2);
+  const cy = content.y + topMargin + radius + trackWidth / 2;
   const toAngle = (v) => Math.PI - clamp8((v - min) / (max - min), 0, 1) * Math.PI;
-  const valueAngle = toAngle(value);
-  const sketch = resolveSketch(spec);
-  const pen = sketch ? new RoughPen(ctx, sketch) : null;
+  const sweepT = context?.sweepProgress ?? 1;
+  const from = context?.valueFrom ?? min;
+  const displayValue = from + (value - from) * sweepT;
+  const shownText = formatValue(displayValue, gauge.format);
+  const valueAngle = toAngle(displayValue);
   strokePoints(ctx, pen, arcPoints(cx, cy, radius, Math.PI, 0), track, trackWidth);
-  if (gauge.bands?.length) {
-    let prev = min;
-    gauge.bands.forEach((band, i) => {
-      const to = clamp8(band.to, min, max);
-      if (to <= prev) return;
-      const color = band.color ?? tokens.color.palette[i % tokens.color.palette.length] ?? accent;
-      strokePoints(ctx, pen, arcPoints(cx, cy, radius, toAngle(prev), toAngle(to)), color, trackWidth);
-      prev = to;
-    });
-    if (prev < max) {
-      strokePoints(ctx, pen, arcPoints(cx, cy, radius, toAngle(prev), 0), withAlpha3(tokens.color.border, 0.6), trackWidth);
-    }
-  } else {
-    strokePoints(ctx, pen, arcPoints(cx, cy, radius, Math.PI, valueAngle), accent, trackWidth);
-  }
-  const needleEnd = pointOnArc(cx, cy, radius - trackWidth * 0.45, valueAngle);
-  strokePoints(ctx, pen, [{ x: cx, y: cy }, needleEnd], needleColor, Math.max(1.5, tokens.stroke.thick));
-  drawCircle(ctx, pen, cx, cy, Math.max(3, trackWidth * 0.22), tokens.color.surface, needleColor);
-  if (target != null) {
-    const a = toAngle(target);
-    const outer = pointOnArc(cx, cy, radius + trackWidth * 0.55, a);
-    const inner = pointOnArc(cx, cy, radius - trackWidth * 0.7, a);
-    strokePoints(ctx, pen, [outer, inner], tokens.color.negative ?? tokens.color.text, Math.max(2, tokens.stroke.thick));
-  }
-  const leftTick = pointOnArc(cx, cy, radius, Math.PI);
-  const rightTick = pointOnArc(cx, cy, radius, 0);
-  addOverlayText(surface, tokens, {
-    left: leftTick.x - 32,
-    top: leftTick.y + 6,
-    width: 64,
-    text: formatValue(min, gauge.format),
-    color: tokens.color.textMuted,
-    size: tokens.font.size.tiny,
-    align: "center"
-  });
-  addOverlayText(surface, tokens, {
-    left: rightTick.x - 32,
-    top: rightTick.y + 6,
-    width: 64,
-    text: formatValue(max, gauge.format),
-    color: tokens.color.textMuted,
-    size: tokens.font.size.tiny,
-    align: "center"
-  });
-  const readoutTop = Math.min(content.y + content.height - valueSize - captionSize - 8, cy + 14);
+  if (valueAngle < Math.PI) {
+    strokePoints(ctx, pen, arcPoints(cx, cy, radius, Math.PI, valueAngle), fill, trackWidth);
+  }
+  if (compare2 != null) {
+    const innerWidth = clamp8(trackWidth * 0.42, 6, 22);
+    const innerRadius = Math.max(radius * 0.35, radius - trackWidth / 2 - 2 - innerWidth / 2);
+    const compareFrom = context?.compareFrom ?? min;
+    const displayCompare = compareFrom + (compare2 - compareFrom) * sweepT;
+    const compareAngle = toAngle(displayCompare);
+    if (compareAngle < Math.PI) {
+      strokePoints(ctx, pen, arcPoints(cx, cy, innerRadius, Math.PI, compareAngle), compareColor, innerWidth);
+    }
+  }
+  if (targetMark != null) {
+    const a = toAngle(targetMark);
+    const overhang = clamp8(trackWidth * 0.3, 4, 10);
+    const outer = pointOnArc(cx, cy, radius + trackWidth / 2 + overhang, a);
+    const inner = pointOnArc(cx, cy, radius - trackWidth / 2 - overhang, a);
+    strokePoints(ctx, pen, [outer, inner], markColor, 3, "round");
+  }
+  if (legendEntries.length) {
+    drawGaugeLegend(surface, tokens, { x: content.x, y: content.y, width: content.width, height: content.height }, legendEntries);
+  }
+  const valueSize = clamp8(radius * 0.5, 22, 72);
   addOverlayText(surface, tokens, {
     left: content.x,
-    top: readoutTop,
-    width: content.width,
-    text: valueText,
+    top: cy - radius * 0.32 - valueSize / 2,
+    width: dialW,
+    text: shownText,
     color: tokens.color.text,
     size: valueSize,
     weight: tokens.font.weight.bold,
@@ -14081,20 +14550,20 @@ function drawGauge(surface, spec, tokens, size, context) {
   });
   addOverlayText(surface, tokens, {
     left: content.x,
-    top: readoutTop + valueSize + 4,
-    width: content.width,
+    top: cy + 8,
+    width: dialW,
     text: caption,
     color: tokens.color.textMuted,
     size: captionSize,
     align: "center"
   });
   const hitTest = (px, py) => {
-    const dx = px - cx;
-    const dy = py - cy;
-    const distance = Math.hypot(dx, dy);
-    const withinDial = distance <= radius + trackWidth * 2 && py >= cy - radius - trackWidth * 2 && py <= cy + readoutReserve;
+    const withinDial = px >= cx - radius - trackWidth && px <= cx + radius + trackWidth && py >= cy - radius - trackWidth && py <= cy + captionReserve + 4;
     if (!withinDial) return null;
-    const rows = [{ label: "value", value: valueText }];
+    const rows = [{ label: gauge.valueLabel ?? "value", value: valueText }];
+    if (compare2 != null) {
+      rows.push({ label: gauge.compareLabel ?? "prior period", value: formatValue(compare2, gauge.format), muted: true });
+    }
     if (target != null) rows.push({ label: "target", value: formatValue(target, gauge.format), muted: true });
     return {
       key: "value",
@@ -14122,7 +14591,7 @@ function titleText2(title2) {
 function valueField3(ref) {
   return typeof ref === "number" ? null : ref.field;
 }
-function resolveValue3(ref, data) {
+function resolveValue(ref, data) {
   if (ref == null) return null;
   if (typeof ref === "number") return Number.isFinite(ref) ? ref : null;
   return aggregateValues((data ?? []).map(accessor(ref.field)), ref.aggregate ?? "sum");
@@ -14154,8 +14623,8 @@ function drawBullet(surface, spec, tokens, size, context) {
   const ctx = surface.marks.ctx;
   const content = drawTitleBlock(surface, tokens, size, bullet.title);
   const data = bullet.data ?? [];
-  const value = resolveValue3(bullet.value, data);
-  const target = resolveValue3(bullet.target, data);
+  const value = resolveValue(bullet.value, data);
+  const target = resolveValue(bullet.target, data);
   const caption = bullet.label ?? titleText2(bullet.title) ?? valueField3(bullet.value) ?? "Value";
   const fmt = bullet.format;
   const finiteRanges = (bullet.ranges ?? []).filter((r) => Number.isFinite(r)).sort((a, b) => a - b);
@@ -14338,7 +14807,7 @@ function noData(surface, tokens, content) {
 }
 function normalizeDays(days) {
   if (Array.isArray(days)) {
-    return days.filter((d) => Number.isFinite(d.value)).map((d) => ({ isoDate: isoDay(d.date), date: startOfLocalDay(d.date), value: d.value }));
+    return days.filter((d) => Number.isFinite(d.value)).map((d) => ({ isoDate: isoDay(d.date), date: startOfLocalDay(d.date), value: d.value, row: d.row }));
   }
   const out = [];
   const dayMap = days;
@@ -14360,19 +14829,20 @@ function buildCalendarGrid(days) {
   const start = addDays(minDay, -minDay.getDay());
   const end = addDays(maxDay, 6 - maxDay.getDay());
   const weeks = Math.floor(diffDays(end, start) / 7) + 1;
-  const byValue = new Map(values.map((d) => [d.isoDate, d.value]));
+  const byValue = new Map(values.map((d) => [d.isoDate, { value: d.value, row: d.row }]));
   const cells = [];
   const byIsoDate = /* @__PURE__ */ new Map();
   for (let d = start; diffDays(end, d) >= 0; d = addDays(d, 1)) {
     const isoDate = isoDay(d);
-    const value = byValue.get(isoDate);
+    const dayValue = byValue.get(isoDate);
     const cell = {
       isoDate,
       date: d,
       week: Math.floor(diffDays(d, start) / 7),
       weekday: d.getDay(),
-      value,
-      present: value !== void 0
+      value: dayValue?.value,
+      row: dayValue?.row,
+      present: dayValue !== void 0
     };
     cells.push(cell);
     byIsoDate.set(isoDate, cell);
@@ -14391,9 +14861,9 @@ function collectDays(spec) {
     const isoDate = isoDay(day);
     const current = totals.get(isoDate);
     if (current) current.value += value;
-    else totals.set(isoDate, { date: day, value });
+    else totals.set(isoDate, { date: day, value, row });
   }
-  return [...totals.entries()].map(([isoDate, { date, value }]) => ({ isoDate, date, value }));
+  return [...totals.entries()].map(([isoDate, { date, value, row }]) => ({ isoDate, date, value, row }));
 }
 function monthAnchors(grid) {
   const seen = /* @__PURE__ */ new Set();
@@ -14417,6 +14887,8 @@ function humanDate(date) {
 function drawCalendarHeatmap(surface, spec, tokens, size, context) {
   const cal = spec;
   const ctx = surface.marks.ctx;
+  const emphasis = context?.emphasis ?? null;
+  const dateField = cal.encoding.date.field;
   const content = drawTitleBlock(surface, tokens, size, cal.title);
   const days = collectDays(cal);
   const grid = buildCalendarGrid(days);
@@ -14456,6 +14928,7 @@ function drawCalendarHeatmap(surface, spec, tokens, size, context) {
     const y = gridRect.y + c.weekday * (cell + GAP2);
     const fill = c.present && c.value !== void 0 ? rgbaToCss(cscale.map(c.value)) : tokens.color.surface;
     laidOut.set(c.isoDate, { ...c, x, y, size: cell, fill });
+    ctx.globalAlpha = c.present ? rowAlpha(emphasis, c.row ?? { [dateField]: c.isoDate }) : 1;
     if (pen) {
       pen.rect(x, y, cell, cell, {
         fill,
@@ -14469,6 +14942,7 @@ function drawCalendarHeatmap(surface, spec, tokens, size, context) {
       ctx.lineWidth = 1;
       ctx.strokeRect(x + 0.5, y + 0.5, Math.max(0, cell - 1), Math.max(0, cell - 1));
     }
+    ctx.globalAlpha = 1;
   }
   ctx.restore();
   for (const m of monthAnchors(grid)) {
@@ -14746,13 +15220,15 @@ function buildWaterfallModel(spec, tokens, opts) {
 }
 
 // src/charts/waterfall.ts
-function drawConnectors(surface, model) {
+function drawConnectors(surface, model, alphaOf) {
   if (model.connectors.length === 0) return;
   const ctx = surface.marks.ctx;
   const color = model.tokens.color.axis;
   if (model.sketch) {
     const pen = new RoughPen(ctx, model.sketch);
-    for (const c of model.connectors) {
+    for (let i = 0; i < model.connectors.length; i += 1) {
+      const c = model.connectors[i];
+      ctx.globalAlpha = alphaOf(model.bars[i]);
       pen.polyline(
         [
           { x: c.x1, y: c.y },
@@ -14760,6 +15236,7 @@ function drawConnectors(surface, model) {
         ],
         { stroke: color }
       );
+      ctx.globalAlpha = 1;
     }
     return;
   }
@@ -14767,23 +15244,28 @@ function drawConnectors(surface, model) {
   ctx.strokeStyle = color;
   ctx.lineWidth = 1;
   ctx.setLineDash([2, 2]);
-  ctx.beginPath();
-  for (const c of model.connectors) {
+  for (let i = 0; i < model.connectors.length; i += 1) {
+    const c = model.connectors[i];
     const y = Math.round(c.y) + 0.5;
+    ctx.globalAlpha = alphaOf(model.bars[i]);
+    ctx.beginPath();
     ctx.moveTo(c.x1, y);
     ctx.lineTo(c.x2, y);
+    ctx.stroke();
+    ctx.globalAlpha = 1;
   }
-  ctx.stroke();
   ctx.restore();
 }
-function drawBars2(surface, model) {
+function drawBars2(surface, model, alphaOf) {
   const ctx = surface.marks.ctx;
   const pen = model.sketch ? new RoughPen(ctx, model.sketch) : null;
   for (const bar of model.bars) {
     const { rect } = bar;
     if (rect.width <= 0 || rect.height <= 0) continue;
+    ctx.globalAlpha = alphaOf(bar);
     if (pen) {
       pen.rect(rect.x, rect.y, rect.width, rect.height, { stroke: bar.color, fill: bar.color });
+      ctx.globalAlpha = 1;
       continue;
     }
     const r = Math.min(model.cornerRadius, rect.width / 2, rect.height / 2);
@@ -14791,6 +15273,7 @@ function drawBars2(surface, model) {
     roundedRect(ctx, rect.x, rect.y, rect.width, rect.height, [r, r, r, r]);
     ctx.fillStyle = bar.color;
     ctx.fill();
+    ctx.globalAlpha = 1;
   }
 }
 function barLabelText(bar, format) {
@@ -14820,17 +15303,19 @@ function drawLabels(surface, model) {
     });
   }
 }
-function drawWaterfall(surface, spec, tokens, size, _context) {
+function drawWaterfall(surface, spec, tokens, size, context) {
   const waterfall = spec;
   const model = buildWaterfallModel(waterfall, tokens, size);
+  const emphasis = context?.emphasis ?? null;
+  const stageField = waterfall.encoding.stage.field;
+  const alphaOf = (bar) => bar.stageValue === void 0 ? 1 : rowAlpha(emphasis, { [stageField]: bar.stageValue });
   drawAxesUnderlay(surface, model.base);
-  drawConnectors(surface, model);
-  drawBars2(surface, model);
+  drawConnectors(surface, model, alphaOf);
+  drawBars2(surface, model, alphaOf);
   drawLabels(surface, model);
   drawOverlay(surface, model.base);
   if (model.bars.length === 0) return;
   const { plot, format } = model;
-  const stageField = waterfall.encoding.stage.field;
   const valueLabel2 = waterfall.encoding.value.title ?? waterfall.encoding.value.field;
   const fmtNum = (v) => format ? formatValue(v, format) : formatNumber2(v, ",");
   const hitBar = (px, py) => {
@@ -15013,7 +15498,7 @@ var LABEL_WIDTH = 68;
 function fmtValue(v, format) {
   return format ? formatValue(v, format) : formatNumber2(v, ",");
 }
-function drawLines(surface, model) {
+function drawLines(surface, model, alphaOf) {
   const ctx = surface.marks.ctx;
   const pen = model.sketch ? new RoughPen(ctx, model.sketch) : null;
   ctx.save();
@@ -15023,6 +15508,7 @@ function drawLines(surface, model) {
   for (const series of model.series) {
     const points = series.points;
     if (points.length === 0) continue;
+    ctx.globalAlpha = alphaOf(series);
     if (pen && points.length >= 2) {
       pen.polyline(points, { stroke: series.color });
     } else if (points.length >= 2) {
@@ -15048,16 +15534,18 @@ function drawLines(surface, model) {
         ctx.stroke();
       }
     }
+    ctx.globalAlpha = 1;
   }
   ctx.restore();
 }
-function drawEndLabels(surface, model) {
+function drawEndLabels(surface, model, alphaOf) {
   if (!model.showLabels) return;
   const { tokens } = model;
   const labelSize = tokens.font.size.tiny;
   const valueSize = tokens.font.size.tiny;
   for (const series of model.series) {
     if (series.points.length === 0) continue;
+    const opacity = alphaOf(series) === 1 ? 1 : 0.5;
     const first = series.points[0];
     const last = series.points[series.points.length - 1];
     addOverlayText(surface, tokens, {
@@ -15068,7 +15556,8 @@ function drawEndLabels(surface, model) {
       color: series.color,
       size: labelSize,
       weight: tokens.font.weight.bold,
-      align: "right"
+      align: "right",
+      opacity
     });
     addOverlayText(surface, tokens, {
       left: first.x - 8 - LABEL_WIDTH,
@@ -15077,7 +15566,8 @@ function drawEndLabels(surface, model) {
       text: fmtValue(first.value, model.format),
       color: tokens.color.textMuted,
       size: valueSize,
-      align: "right"
+      align: "right",
+      opacity
     });
     if (last !== first) {
       addOverlayText(surface, tokens, {
@@ -15088,7 +15578,8 @@ function drawEndLabels(surface, model) {
         color: series.color,
         size: valueSize,
         weight: tokens.font.weight.medium,
-        align: "left"
+        align: "left",
+        opacity
       });
     }
   }
@@ -15106,16 +15597,18 @@ function nearestPoint(model, px, py) {
   }
   return best ? { series: best.series, point: best.point } : null;
 }
-function drawSlope(surface, spec, tokens, size, _context) {
+function drawSlope(surface, spec, tokens, size, context) {
   const slope = spec;
   const model = buildSlopeModel(slope, tokens, size);
+  const emphasis = context?.emphasis ?? null;
+  const seriesField = slope.encoding.series.field;
+  const alphaOf = (series) => emphasis ? emphasis.match({ [seriesField]: series.value }) ? 1 : emphasis.dim : 1;
   drawAxesUnderlay(surface, model.base);
-  drawLines(surface, model);
+  drawLines(surface, model, alphaOf);
   drawOverlay(surface, model.base);
-  drawEndLabels(surface, model);
+  drawEndLabels(surface, model, alphaOf);
   if (model.series.length === 0) return;
   const { plot } = model;
-  const seriesField = slope.encoding.series.field;
   return {
     region: { x: plot.x, y: plot.y, width: plot.width, height: plot.height },
     hitTest: (px, py) => {
@@ -15308,10 +15801,12 @@ function layoutPlot(content, labelWidth, tokens) {
     }
   };
 }
-function drawDumbbell(surface, spec, tokens, size, _context) {
+function drawDumbbell(surface, spec, tokens, size, context) {
   const dumbbell = spec;
   const model = buildDumbbellModel(dumbbell, tokens);
   const ctx = surface.marks.ctx;
+  const emphasis = context?.emphasis ?? null;
+  const categoryField = dumbbell.encoding.category.field;
   let content = drawTitleBlock(surface, tokens, size, dumbbell.title);
   const legendEntries = model.groups.map((group) => ({ label: group.label, color: group.color, symbol: "circle" }));
   content = drawCategoricalLegend(surface, tokens, content, legendEntries, "top");
@@ -15372,8 +15867,10 @@ function drawDumbbell(surface, spec, tokens, size, _context) {
     }).sort((a, b) => a.x - b.x);
     if (pixelDots.length === 0) continue;
     pixelRows.push({ ...row, y: cy, pixelDots });
+    ctx.globalAlpha = rowAlpha(emphasis, { [categoryField]: row.catRawValue });
     drawConnector(ctx, pen, pixelDots[0].x, pixelDots[pixelDots.length - 1].x, cy, tokens);
     for (const dot of pixelDots) drawDot(ctx, pen, dot.x, cy, dot.color, tokens);
+    ctx.globalAlpha = 1;
     addOverlayText(surface, tokens, {
       left: content.x,
       top: cy,
@@ -15401,7 +15898,6 @@ function drawDumbbell(surface, spec, tokens, size, _context) {
       }
     }
   }
-  const categoryField = dumbbell.encoding.category.field;
   const nearestDot = (px, py) => {
     let best = null;
     for (const row of pixelRows) {
@@ -16737,6 +17233,8 @@ var CANVAS_MARK_TYPES = /* @__PURE__ */ new Set([
   "sankey",
   "choropleth"
 ]);
+var COUNT_UP_TYPES = /* @__PURE__ */ new Set(["kpi"]);
+var SWEEP_TYPES = /* @__PURE__ */ new Set(["pie", "gauge"]);
 var EMPTY_DATA = [];
 function legendConfigFor(model) {
   const legend = model.spec.legend;
@@ -16832,6 +17330,9 @@ function render(target, spec, options) {
   let interaction;
   let entrance;
   let updateTransition;
+  let lastValue = null;
+  let lastCompare = null;
+  let lastSparkline = null;
   let destroyed = false;
   let lastDrawnW = -1;
   let lastDrawnH = -1;
@@ -16859,7 +17360,7 @@ function render(target, spec, options) {
     }
   }
   const hostListeners = /* @__PURE__ */ new Set();
-  const draw = (animateEntrance) => {
+  const draw = (animateEntrance, valueTweenFrom, compareTweenFrom, sparklineTweenFrom) => {
     entrance?.cancel();
     entrance = void 0;
     updateTransition?.cancel();
@@ -16889,6 +17390,11 @@ function render(target, spec, options) {
     let facetRpt;
     let legendSelect = null;
     const type = currentSpec.type;
+    if (COUNT_UP_TYPES.has(type) || SWEEP_TYPES.has(type)) {
+      lastValue = resolveValueRef(effectiveSpec.value, effectiveSpec.data ?? EMPTY_DATA);
+      lastCompare = SWEEP_TYPES.has(type) ? resolveValueRef(effectiveSpec.compare, effectiveSpec.data ?? EMPTY_DATA) : null;
+      lastSparkline = type === "kpi" ? kpiSparklineSeries(effectiveSpec, effectiveSpec.data ?? EMPTY_DATA) : null;
+    }
     const facetLayout = isFaceted(effectiveSpec) ? buildFacetModels(effectiveSpec, tokens, size) : null;
     if (facetLayout) {
       drawFacet(surface, effectiveSpec, facetLayout, tokens);
@@ -16919,7 +17425,8 @@ function render(target, spec, options) {
           tokens,
           currentSpec.background,
           anim,
-          finishEntrance
+          finishEntrance,
+          type === "bar" ? "grow" : "wipe"
         );
       }
     } else {
@@ -16937,11 +17444,44 @@ function render(target, spec, options) {
           }
         };
         interactionModel = renderer(surface, effectiveSpec, tokens, size, ctx) ?? null;
+        if (anim.enabled) {
+          if (COUNT_UP_TYPES.has(type) || SWEEP_TYPES.has(type)) {
+            const key = COUNT_UP_TYPES.has(type) ? "valueProgress" : "sweepProgress";
+            entrance = runCustomProgress(anim, finishEntrance, (t) => {
+              surface.overlay.replaceChildren();
+              surface.marks.clear();
+              paintBackground(surface, tokens, currentSpec.background);
+              renderer(surface, effectiveSpec, tokens, size, { ...ctx, [key]: t });
+            });
+          } else {
+            entrance = runFadeEntrance(surface, anim, finishEntrance);
+          }
+        } else if ((valueTweenFrom !== void 0 || sparklineTweenFrom !== void 0) && (COUNT_UP_TYPES.has(type) || SWEEP_TYPES.has(type))) {
+          const tween = resolveUpdate(currentSpec.animation, {
+            reducedMotion: prefersReducedMotion(),
+            disabled: globalThis.__GRAPHEIN_DISABLE_ANIM === true
+          });
+          if (tween.enabled) {
+            const key = COUNT_UP_TYPES.has(type) ? "valueProgress" : "sweepProgress";
+            entrance = runCustomProgress(tween, finishEntrance, (t) => {
+              surface.overlay.replaceChildren();
+              surface.marks.clear();
+              paintBackground(surface, tokens, currentSpec.background);
+              renderer(surface, effectiveSpec, tokens, size, {
+                ...ctx,
+                valueFrom: valueTweenFrom,
+                compareFrom: compareTweenFrom,
+                sparklineFrom: sparklineTweenFrom,
+                [key]: t
+              });
+            });
+          }
+        }
       } else {
         drawPlaceholder(surface, tokens, `\u201C${type}\u201D renderer not yet registered`);
-      }
-      if (anim.enabled) {
-        entrance = runFadeEntrance(surface, anim, finishEntrance);
+        if (anim.enabled) {
+          entrance = runFadeEntrance(surface, anim, finishEntrance);
+        }
       }
     }
     if (!interaction) interaction = new InteractionController(surface, tokens);
@@ -17065,8 +17605,18 @@ function render(target, spec, options) {
       });
       const wantFade = anim.enabled && CANVAS_MARK_TYPES.has(prevType) && CANVAS_MARK_TYPES.has(next.type);
       const before = wantFade ? snapshotLayer(surface.marks) : void 0;
+      const prevValue = lastValue;
+      const prevCompare = lastCompare;
+      const prevSparkline = lastSparkline;
+      const wantValueTween = prevType === next.type && (COUNT_UP_TYPES.has(next.type) || SWEEP_TYPES.has(next.type)) && prevValue != null;
+      const wantSparklineTween = prevType === next.type && next.type === "kpi" && prevSparkline != null && prevSparkline.length > 0;
       currentSpec = next;
-      draw(false);
+      draw(
+        false,
+        wantValueTween ? prevValue ?? void 0 : void 0,
+        wantValueTween ? prevCompare ?? void 0 : void 0,
+        wantValueTween || wantSparklineTween ? prevSparkline ?? void 0 : void 0
+      );
       if (before && surface.width === prevW && surface.height === prevH && surface.marks.canvas.width === before.width && surface.marks.canvas.height === before.height) {
         updateTransition = runUpdateCrossfade(surface, before, anim);
       }
@@ -17086,7 +17636,7 @@ function render(target, spec, options) {
     }
   };
 }
-function runCartesianEntrance(surface, model, renderer, tokens, background, anim, onDone) {
+function runCartesianEntrance(surface, model, renderer, tokens, background, anim, onDone, mode = "wipe") {
   const ctx = surface.marks.ctx;
   const { plot } = model;
   const bg = background ?? tokens.color.background;
@@ -17097,6 +17647,14 @@ function runCartesianEntrance(surface, model, renderer, tokens, background, anim
     ctx.fillRect(0, 0, surface.width, surface.height);
     ctx.restore();
     drawAxesUnderlay(surface, model);
+    if (mode === "grow") {
+      model.entranceProgress = t;
+      renderer(surface, model);
+      model.entranceProgress = void 0;
+      drawTrendlines(surface, model);
+      drawAnnotations(surface, model);
+      return;
+    }
     if (t <= 0) return;
     ctx.save();
     ctx.globalAlpha = Math.min(1, 0.2 + 0.8 * t);
@@ -17119,6 +17677,17 @@ function runCartesianEntrance(surface, model, renderer, tokens, background, anim
     }
   });
 }
+function runCustomProgress(anim, onDone, paint) {
+  return animate({
+    duration: anim.duration,
+    easing: anim.easing,
+    onUpdate: paint,
+    onComplete: () => {
+      paint(1);
+      onDone();
+    }
+  });
+}
 function runFadeEntrance(surface, anim, onDone) {
   const root = surface.root;
   const apply = (t) => {
@@ -17270,12 +17839,17 @@ function autoParamName(view) {
   const existing = view.spec.params?.[0]?.name;
   return existing ?? `__sel__${view.id}`;
 }
+function roleOf(view) {
+  return view.interact ?? "auto";
+}
 function wireViews(views, interactions) {
   const out = views.map((v) => ({ ...v, spec: v.spec }));
   if (interactions === "none") return out;
   const sources = [];
   out.forEach((v, i) => {
     const type = v.spec.type;
+    const role = roleOf(v);
+    if (role === "none" || role === "target") return;
     if (isSlicerType(type)) {
       const s = v.spec;
       sources.push({
@@ -17306,11 +17880,15 @@ function wireViews(views, interactions) {
           name: src.param,
           select: { type: "point", on: "click", fields: src.fields }
         });
-        out[src.view].spec = addHighlight(out[src.view].spec, src.param);
+        if (roleOf(out[src.view]) !== "source") {
+          out[src.view].spec = addHighlight(out[src.view].spec, src.param);
+        }
       }
       out.forEach((v, j) => {
         if (isSlicerType(v.spec.type)) return;
         if (j === src.view) return;
+        const trole = roleOf(v);
+        if (trole === "none" || trole === "source") return;
         out[j].spec = addFilterParam(out[j].spec, src.param);
       });
     }
@@ -17360,6 +17938,41 @@ var DEFAULT_BREAKPOINTS = [
   { maxWidth: 960, cols: 6 }
 ];
 var STRIP_SLICERS = /* @__PURE__ */ new Set(["dropdown", "search", "dateRange", "range"]);
+var DASHBOARD_CLASS = "graphein-dashboard";
+var DASHBOARD_CELL_CLASS = "graphein-dashboard-cell";
+var DASHBOARD_SOURCE_CLASS = "is-source";
+function dashboardStyles(tokens) {
+  const accent = tokens.color.accent;
+  const surface = tokens.color.surface;
+  return `
+.${DASHBOARD_CLASS} .${DASHBOARD_CELL_CLASS}[data-framed="true"] {
+  transition: border-color 120ms ease, background-color 120ms ease;
+}
+.${DASHBOARD_CLASS} .${DASHBOARD_CELL_CLASS}[data-framed="true"]:hover {
+  border-color: ${accent};
+  background-color: ${surface};
+}
+.${DASHBOARD_CLASS} .${DASHBOARD_CELL_CLASS}:focus-visible {
+  outline: 2px solid ${accent};
+  outline-offset: 2px;
+}
+.${DASHBOARD_CLASS} .${DASHBOARD_CELL_CLASS}.${DASHBOARD_SOURCE_CLASS} {
+  border-color: ${accent};
+  box-shadow: inset 0 0 0 1px ${accent};
+}
+`;
+}
+function selectionIsActive(value) {
+  if (value == null) return false;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value !== "object") return true;
+  const v = value;
+  if (v.kind === "point") return Array.isArray(v.tuples) && v.tuples.length > 0;
+  if (v.kind === "set") return Array.isArray(v.values) && v.values.length > 0;
+  if (v.kind === "range") return v.min != null || v.max != null;
+  if (v.kind === "text") return typeof v.query === "string" && v.query.length > 0;
+  return true;
+}
 function stripCellHeight(view, rowHeight) {
   const titled = !!(view.title || view.subtitle);
   const titlePad = titled ? 30 : 0;
@@ -17502,6 +18115,12 @@ function renderDashboard(target, spec, options) {
   let root;
   let resizeObs;
   let destroyed = false;
+  let sourceCells = /* @__PURE__ */ new Map();
+  const syncSourceCell = (name, value) => {
+    const cell = sourceCells.get(name);
+    if (!cell) return;
+    cell.classList.toggle(DASHBOARD_SOURCE_CLASS, selectionIsActive(value));
+  };
   const build = () => {
     const tokens = resolveTheme(currentSpec.theme);
     const layout2 = resolveDashboardLayout(currentSpec.layout);
@@ -17514,8 +18133,9 @@ function renderDashboard(target, spec, options) {
         store.set(param.name, param.value ?? null);
       }
     }
+    sourceCells = /* @__PURE__ */ new Map();
     root = document.createElement("div");
-    root.className = "graphein-dashboard";
+    root.className = DASHBOARD_CLASS;
     Object.assign(root.style, {
       boxSizing: "border-box",
       width: currentSpec.dimensions?.width ? `${currentSpec.dimensions.width}px` : "100%",
@@ -17529,6 +18149,10 @@ function renderDashboard(target, spec, options) {
       flexDirection: "column",
       gap: `${layout2.gap}px`
     });
+    const style = document.createElement("style");
+    style.setAttribute("data-graphein-dashboard-style", "");
+    style.textContent = dashboardStyles(tokens);
+    root.appendChild(style);
     const titleText3 = typeof currentSpec.title === "string" ? currentSpec.title : currentSpec.title?.text;
     if (titleText3 || currentSpec.subtitle) {
       const header = document.createElement("div");
@@ -17588,6 +18212,7 @@ function renderDashboard(target, spec, options) {
     };
     const cellChrome = (cell, view) => {
       const framed = view?.frame ?? true;
+      cell.dataset.framed = framed ? "true" : "false";
       Object.assign(cell.style, {
         minWidth: "0",
         minHeight: "0",
@@ -17599,9 +18224,10 @@ function renderDashboard(target, spec, options) {
         background: view?.background ?? (framed ? tokens.color.surface : "transparent")
       });
     };
-    const createCard2 = (view) => {
+    const createCard = (view) => {
       const cell = document.createElement("div");
       cellChrome(cell, view);
+      cell.classList.add(DASHBOARD_CELL_CLASS);
       cell.setAttribute("data-view-id", view.id);
       const hasCardChrome = !!(view.title || view.subtitle || view.accent || view.background || view.frame === false || view.padding === "none");
       if (!hasCardChrome) return { cell, host: cell };
@@ -17628,13 +18254,14 @@ function renderDashboard(target, spec, options) {
           padding: `${tokens.spacing.sm}px ${tokens.spacing.md}px ${tokens.spacing.xs}px ${tokens.spacing.md}px`,
           display: "flex",
           flexDirection: "column",
-          gap: "2px"
+          gap: "2px",
+          borderBottom: `1px solid ${tokens.color.border}`
         });
         if (view.title) {
           const title2 = document.createElement("div");
           title2.textContent = view.title;
           Object.assign(title2.style, {
-            font: `${tokens.font.weight.bold} ${tokens.font.size.base}px ${tokens.font.family}`,
+            font: `${tokens.font.weight.medium} ${tokens.font.size.base}px ${tokens.font.family}`,
             color: tokens.color.text,
             letterSpacing: "-0.01em"
           });
@@ -17662,6 +18289,24 @@ function renderDashboard(target, spec, options) {
       cell.appendChild(host);
       return { cell, host };
     };
+    const publishingParams = (view) => {
+      const names = /* @__PURE__ */ new Set();
+      for (const param of view.spec.params ?? []) {
+        if (param?.name) names.add(param.name);
+      }
+      if (isSlicerType(view.spec.type)) {
+        const slicer = view.spec;
+        const name = typeof slicer.param === "string" ? slicer.param : typeof slicer.field === "string" ? slicer.field : void 0;
+        if (name) names.add(name);
+      }
+      return [...names];
+    };
+    const registerSourceCell = (view, cell) => {
+      for (const name of publishingParams(view)) {
+        sourceCells.set(name, cell);
+        syncSourceCell(name, store.get(name));
+      }
+    };
     const sectionPlans = resolveDashboardSections(gridViews, layout2);
     const layoutGroups = [];
     const deferredMounts = [];
@@ -17674,7 +18319,8 @@ function renderDashboard(target, spec, options) {
         gap: `${layout2.gap}px`
       });
       for (const view of stripViews) {
-        const { cell, host } = createCard2(view);
+        const { cell, host } = createCard(view);
+        registerSourceCell(view, cell);
         Object.assign(cell.style, {
           flex: "1 1 220px",
           minWidth: "200px",
@@ -17720,7 +18366,13 @@ function renderDashboard(target, spec, options) {
         if (plan.section?.title) {
           const title2 = document.createElement("span");
           title2.textContent = plan.section.title;
-          Object.assign(title2.style, { fontWeight: String(tokens.font.weight.bold), fontSize: `${tokens.font.size.large}px` });
+          Object.assign(title2.style, {
+            color: tokens.color.textMuted,
+            fontWeight: String(tokens.font.weight.medium),
+            fontSize: `${tokens.font.size.small}px`,
+            letterSpacing: "0.06em",
+            textTransform: "uppercase"
+          });
           titles.appendChild(title2);
         }
         if (plan.section?.subtitle) {
@@ -17772,7 +18424,8 @@ function renderDashboard(target, spec, options) {
       parent.appendChild(grid);
       const cells = placeViews(plan.views, plan.cols, layout2.preset ?? "auto");
       for (const cellInfo of cells) {
-        const { cell, host } = createCard2(cellInfo.view);
+        const { cell, host } = createCard(cellInfo.view);
+        registerSourceCell(cellInfo.view, cell);
         grid.appendChild(cell);
         cellInfo.el = cell;
         deferredMounts.push({ el: host, view: cellInfo.view, mounted: false });
@@ -17845,8 +18498,10 @@ function renderDashboard(target, spec, options) {
     instances.length = 0;
     if (root && root.parentNode) root.parentNode.removeChild(root);
     root = void 0;
+    sourceCells = /* @__PURE__ */ new Map();
   };
   const unsubscribe = store.subscribe((name, value) => {
+    syncSourceCell(name, value);
     for (const listener of [...hostListeners]) listener(name, value);
   });
   build();
@@ -18064,6 +18719,6 @@ function renderToContext(target, spec) {
 // src/index.ts
 var VERSION = "0.1.0";
 
-export { CARTESIAN_TYPES, CHART_TYPES, CanvasLayer, DEFAULT_ENTRANCE_DURATION, DEFAULT_ROUGH_STYLE, DEFAULT_UPDATE_DURATION, DIM_ALPHA, ExpressionError, FACETABLE_TYPES2 as FACETABLE_TYPES, FUNCTION_NAMES, InteractionController, RoughPen, SKETCH_FONT_FAMILY, SKETCH_FONT_NAME, SLICER_TYPES, SR_ONLY_STYLE, Surface, TICK_SIZE, TIME_UNITS, TRANSFORM_KINDS, Tooltip, VERSION, aggregateValues, analyzeChart, animate, applyA11y, applyAggregate, applyBin, applyCalculate, applyFilter, applyFold, applyPatch, applyPick, applyTimeUnit, applyTransform, applyTransforms, arc, area, assertValidSpec, autoInsightAnnotations, backOut, bandScale, bounceOut, buildCartesianInteraction, buildCartesianModel, buildComboModel, buildDataTableFallback, buildFacetModels, buildHistogramModel, buildRenderReport, cartesianInteractionBuilders, cartesianRenderers, categorical, categoricalSchemes, chartTitleText, chartTypeLabel, checkExpression, clamp012 as clamp01, clamp255, compileExpression, compilePredicate, computeBackingSize, computeBins, computeFrame, computeSeriesInsights, contrastRatio, createDiv, createRoughPen, createSelectionStore, cubicIn, cubicInOut, cubicOut, curveCatmullRom, curveLinear, curveMonotoneX, curveStep, curveStepAfter, curveStepBefore, customRenderers, darkTheme, decimate, defaultSpan, dependentParams, diverging, divergingColorScale, divergingSchemes, drawAnnotationLabels, drawAnnotations, drawAxesUnderlay, drawFacet, drawLegend, drawOverlay, drawTitle, drawTrendlineLabels, drawTrendlines, easings, elasticOut, ellipsize, ensureSketchFont, expoInOut, expoOut, facetReport, fillParentStyle, filterRows, fontString, formatDate, formatNumber2 as formatNumber, formatValue, getDevicePixelRatio, groupBy, hashString, inferFieldType, inferFieldTypes, inferValueType, inheritInto, interpolateArray, interpolateNumber, interpolateNumberArray, interpolateObject, interpolateOklab, interpolateRgb, isBrowser, isEmptyValue, isFaceted, isParamClause, isSlicerType, keyFields, legendSwatchWidth, lightTheme, line, linear, linearRegression, linearScale, linearToSrgb, lintSpec, literalToValue, logScale, lttbRun, makeMatcher, matchesValue, measureText, monotoneXTangents, mulberry32, niceDomain, oklabToOklch, oklabToRgb, oklchToOklab, ordinalColorScale, overlayTextToCanvasCmd, paintCanvasText, paintLegendSwatch, parseColor, parseNumberFormat, pivot, placeViews, pointScale, polygonHachureLines, prefersReducedMotion, prettyDate, profileColumns, quadIn, quadInOut, quadOut, rampFromStops, readableTextColor, recommendChart, relativeLuminance, render, renderDashboard, renderToContext, repairReport, repairSpec, resolveCurve, resolveDashboardLayout, resolveDashboardSections, resolveEmphasis, resolveEntrance, resolveFilterValues, resolveInsightOptions, resolveSketch, resolveTheme, resolveUpdate, rgbToOklab, rgbaToCss, rotatePoint, roundedRect, sampleArc, sequential, sequentialColorScale, sequentialSchemes, setMeasureContext, setStyle, sinInOut, slicerParamName, smartDate, specFields, srgbToLinear, summarize, summarizeChart, themes, tickIncrement, tickStep, ticks, timeScale, timeTickFormat, timeTicks, toHex, toPointer, tooltipEnabled, truncateTo, validateDashboard, validateSpec, wireViews, withAlpha, withSketchFont };
+export { CARTESIAN_TYPES, CHART_TYPES, CanvasLayer, DEFAULT_ENTRANCE_DURATION, DEFAULT_ROUGH_STYLE, DEFAULT_UPDATE_DURATION, DIM_ALPHA, ExpressionError, FACETABLE_TYPES2 as FACETABLE_TYPES, FUNCTION_NAMES, InteractionController, RoughPen, SKETCH_FONT_FAMILY, SKETCH_FONT_NAME, SLICER_TYPES, SR_ONLY_STYLE, Surface, TICK_SIZE, TIME_UNITS, TRANSFORM_KINDS, Tooltip, VERSION, aggregateValues, analyzeChart, animate, applyA11y, applyAggregate, applyBin, applyCalculate, applyFilter, applyFold, applyPatch, applyPick, applyTimeUnit, applyTransform, applyTransforms, arc, area, assertValidSpec, autoInsightAnnotations, backOut, bandScale, bounceOut, buildCartesianInteraction, buildCartesianModel, buildComboModel, buildDataTableFallback, buildFacetModels, buildHistogramModel, buildRenderReport, cartesianInteractionBuilders, cartesianRenderers, categorical, categoricalSchemes, chartTitleText, chartTypeLabel, checkExpression, clamp012 as clamp01, clamp255, compileExpression, compilePredicate, computeBackingSize, computeBins, computeFrame, computeSeriesInsights, contrastRatio, createDiv, createRoughPen, createSelectionStore, cubicIn, cubicInOut, cubicOut, curveCatmullRom, curveLinear, curveMonotoneX, curveStep, curveStepAfter, curveStepBefore, customRenderers, darkTheme, decimate, defaultSpan, dependentParams, diverging, divergingColorScale, divergingSchemes, drawAnnotationLabels, drawAnnotations, drawAxesUnderlay, drawFacet, drawLegend, drawOverlay, drawTitle, drawTrendlineLabels, drawTrendlines, easings, elasticOut, ellipsize, ensureSketchFont, expoInOut, expoOut, facetReport, fillParentStyle, filterRows, fontString, formatDate, formatNumber2 as formatNumber, formatValue, getDevicePixelRatio, groupBy, hashString, inferFieldType, inferFieldTypes, inferValueType, inheritInto, interpolateArray, interpolateNumber, interpolateNumberArray, interpolateObject, interpolateOklab, interpolateRgb, isBrowser, isEmptyValue, isFaceted, isParamClause, isSlicerType, keyFields, legendSwatchWidth, lightTheme, line, linear, linearRegression, linearScale, linearToSrgb, lintSpec, literalToValue, logScale, lttbRun, makeMatcher, matchesValue, measureText, monotoneXTangents, mulberry32, niceDomain, oklabToOklch, oklabToRgb, oklchToOklab, ordinalColorScale, overlayTextToCanvasCmd, paintCanvasText, paintLegendSwatch, parseColor, parseNumberFormat, pivot, placeViews, pointScale, polygonHachureLines, prefersReducedMotion, prettyDate, profileColumns, quadIn, quadInOut, quadOut, rampFromStops, readableTextColor, recommendChart, relativeLuminance, render, renderDashboard, renderToContext, repairReport, repairSpec, resolveCurve, resolveDashboardLayout, resolveDashboardSections, resolveEmphasis, resolveEntrance, resolveFilterValues, resolveInsightOptions, resolveSketch, resolveTheme, resolveUpdate, resolveValueRef, rgbToOklab, rgbaToCss, rotatePoint, roundedRect, sampleArc, sequential, sequentialColorScale, sequentialSchemes, setMeasureContext, setStyle, sinInOut, slicerParamName, smartDate, specFields, srgbToLinear, summarize, summarizeChart, themes, tickIncrement, tickStep, ticks, timeScale, timeTickFormat, timeTicks, toHex, toPointer, tooltipEnabled, truncateTo, validateDashboard, validateSpec, wireViews, withAlpha, withSketchFont };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map