@slickfast/mcp 0.5.0 → 0.6.0

package/dist/index.js

@@ -217,6 +217,11 @@ var wOpt = (spec) => {
   if (spec.bold === true) return ' font-weight="700"';
   return "";
 };
+function safeData(spec) {
+  const d = spec.data || {};
+  if (Array.isArray(d.series) && d.series.length) return spec;
+  return { ...spec, data: { labels: Array.isArray(d.labels) ? d.labels : [], series: [{ name: "", values: [] }, { name: "", values: [] }] } };
+}
 function niceNum(x, round) {
   const v = x > 0 ? x : 1;
   const exp = Math.floor(Math.log10(v));
@@ -272,6 +277,7 @@ function arcPath(cx, cy, rad, a0, a1, innerR) {
   return `M${r(cx)},${r(cy)} L${x0},${y0} A${rad},${rad} 0 ${large} 1 ${x1},${y1} Z`;
 }
 function renderBar(spec) {
+  spec = safeData(spec);
   const W = spec.width || 800, H = spec.height || 450;
   const bg = spec.background || "#ffffff";
   const transparent = bg === "transparent" || bg === "none";
@@ -562,6 +568,7 @@ function renderBarStackedH(spec) {
   return p.join("\n");
 }
 function renderBarH(spec) {
+  spec = safeData(spec);
   const W = spec.width || 800, H = spec.height || 450;
   const bg = spec.background || "#ffffff";
   const transparent = bg === "transparent" || bg === "none";
@@ -621,6 +628,7 @@ function renderBarH(spec) {
   return p.join("\n");
 }
 function renderDiverging(spec) {
+  spec = safeData(spec);
   const W = spec.width || 800, H = spec.height || 450;
   const bg = spec.background || "#ffffff";
   const transparent = bg === "transparent" || bg === "none";
@@ -714,6 +722,7 @@ function renderDiverging(spec) {
   return p.join("\n");
 }
 function renderLollipop(spec) {
+  spec = safeData(spec);
   const W = spec.width || 800, H = spec.height || 450;
   const bg = spec.background || "#ffffff";
   const transparent = bg === "transparent" || bg === "none";
@@ -849,6 +858,7 @@ function renderKpi(spec) {
   return p.join("\n");
 }
 function renderLine(spec) {
+  spec = safeData(spec);
   const W = spec.width || 800, H = spec.height || 450;
   const bg = spec.background || "#ffffff";
   const transparent = bg === "transparent" || bg === "none";
@@ -937,6 +947,7 @@ function renderLine(spec) {
       const col = colorOf(s, si);
       const vals = s.values.slice(0, n).map((v) => Number(v) || 0);
       const pts = vals.map((v, i) => [r(xPix(i)), r(yPix(v))]);
+      if (!pts.length) return;
       const d = smooth ? smoothPath(pts) : stepped ? steppedPath(pts) : straightPath(pts);
       if (area) {
         const baseY = r(M.top + plotH);
@@ -1026,6 +1037,7 @@ function renderSlope(spec) {
   return p.join("\n");
 }
 function renderPie(spec) {
+  spec = safeData(spec);
   const W = spec.width || 640, H = spec.height || 420;
   const bg = spec.background || "#ffffff";
   const transparent = bg === "transparent" || bg === "none";
@@ -2177,7 +2189,7 @@ function renderLeaderboard(spec) {
   if (title) p.push(`<text x="${r(W / 2)}" y="33" text-anchor="middle" font-size="${fs + 5}" ${wAttr(spec, 700)} fill="${titleCol}">${esc(title)}</text>`);
   items.forEach((it, i) => {
     const cy = topY + i * ROW_H + ROW_H / 2;
-    const fill = it.color || palette[i % palette.length];
+    const fill = it.color || palette[0];
     const bw = it.value / maxV * (barRight - barLeft);
     p.push(`<text x="${PAD}" y="${r(cy + 5)}" font-size="${fs + 1}" ${wAttr(spec, 800)} fill="${rankCol}">${i + 1}</text>`);
     p.push(`<text x="${r(PAD + RANKW)}" y="${r(cy + 5)}" font-size="${fs}" ${wAttr(spec, 600)} fill="${labelCol}">${esc(it.label)}</text>`);
@@ -2189,6 +2201,325 @@ function renderLeaderboard(spec) {
   p.push(`</svg>`);
   return p.join("\n");
 }
+function renderCallout(spec) {
+  const bg = spec.background || "#ffffff";
+  const transparent = bg === "transparent" || bg === "none";
+  const isDark = !transparent && getLuminance(bg) < 0.35;
+  const fs = spec.fontSize ? Number(spec.fontSize) : 13;
+  const font = resolveFont(spec);
+  const watermark = spec.watermark !== false;
+  const title = spec.title || "";
+  const accent = contrastFloor(spec.color || resolveFlatPalette(spec.palette || "Clean Corporate", 1)[0], bg, transparent);
+  const titleCol = txt(spec, isDark ? "#f1f5f9" : "#0f172a");
+  const capCol = txt(spec, isDark ? "#cbd5e1" : "#5b6270");
+  const faint = isDark ? "#475569" : "#94a3b8";
+  const PAD = 28, W = spec.width || 620, H = spec.height || 220;
+  const topY = title ? 50 : 20;
+  const valueStr = (spec.valuePrefix || "") + (spec.value != null ? fmt(spec.value) : "") + (spec.valueUnit || "");
+  const p = [];
+  p.push(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}" font-family="${esc(font)}">`);
+  if (!transparent) p.push(`<rect x="0" y="0" width="${W}" height="${H}" fill="${bg}"/>`);
+  if (title) p.push(`<text x="${PAD}" y="33" font-size="${fs + 5}" ${wAttr(spec, 700)} fill="${titleCol}">${esc(title)}</text>`);
+  const by = topY + (H - topY) * 0.5;
+  p.push(`<text x="${PAD}" y="${r(by)}" font-size="${r((H - topY) * 0.42)}" ${wAttr(spec, 800)} fill="${accent}">${esc(valueStr)}</text>`);
+  if (spec.caption) p.push(`<text x="${PAD}" y="${r(by + (H - topY) * 0.22)}" font-size="${fs + 2}"${wOpt(spec)} fill="${capCol}">${esc(spec.caption)}</text>`);
+  if (spec.note) {
+    const nw = Math.round(String(spec.note).length * (fs * 0.62) + 22);
+    const nx = W - PAD - nw, ny = topY + 12;
+    p.push(`<line x1="${r(nx - 14)}" y1="${r(topY + 6)}" x2="${r(nx - 14)}" y2="${H - 20}" stroke="${faint}" stroke-opacity="0.5"/>`);
+    p.push(`<rect x="${r(nx)}" y="${r(ny)}" width="${nw}" height="26" rx="8" fill="${accent}" fill-opacity="0.14"/>`);
+    p.push(`<text x="${r(nx + nw / 2)}" y="${r(ny + 17)}" text-anchor="middle" font-size="${fs}" ${wAttr(spec, 600)} fill="${accent}">${esc(spec.note)}</text>`);
+  }
+  if (watermark) p.push(`<text x="${W - 10}" y="${H - 9}" text-anchor="end" font-size="9" fill="${faint}" opacity="0.6">slickfast.com</text>`);
+  p.push(`</svg>`);
+  return p.join("\n");
+}
+function renderRing(spec) {
+  const value = Number(spec.value) || 0;
+  const target = spec.target != null ? Number(spec.target) : 100;
+  const frac = Math.max(0, Math.min(1, target > 0 ? value / target : 0));
+  const bg = spec.background || "#ffffff";
+  const transparent = bg === "transparent" || bg === "none";
+  const isDark = !transparent && getLuminance(bg) < 0.35;
+  const fs = spec.fontSize ? Number(spec.fontSize) : 13;
+  const font = resolveFont(spec);
+  const watermark = spec.watermark !== false;
+  const title = spec.title || "";
+  const accent = contrastFloor(spec.color || resolveFlatPalette(spec.palette || "Clean Corporate", 1)[0], bg, transparent);
+  const track = isDark ? "#334155" : "#e2e8f0";
+  const valueCol = txt(spec, isDark ? "#f1f5f9" : "#0f172a");
+  const labelCol = txt(spec, isDark ? "#cbd5e1" : "#475569");
+  const faint = isDark ? "#475569" : "#94a3b8";
+  const W = spec.width || 260, H = spec.height || 240;
+  const topY = title ? 50 : 20;
+  const cx = W / 2, cy = topY + (H - topY - 16) / 2;
+  const R = Math.min(W - 40, H - topY - 40) / 2;
+  const sw = Math.max(8, R * 0.26);
+  const circ = 2 * Math.PI * R;
+  const dash = frac * circ;
+  const p = [];
+  p.push(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}" font-family="${esc(font)}">`);
+  if (!transparent) p.push(`<rect x="0" y="0" width="${W}" height="${H}" fill="${bg}"/>`);
+  if (title) p.push(`<text x="${r(cx)}" y="33" text-anchor="middle" font-size="${fs + 5}" ${wAttr(spec, 700)} fill="${valueCol}">${esc(title)}</text>`);
+  p.push(`<circle cx="${r(cx)}" cy="${r(cy)}" r="${r(R)}" fill="none" stroke="${track}" stroke-width="${r(sw)}"/>`);
+  if (dash > 0) p.push(`<circle cx="${r(cx)}" cy="${r(cy)}" r="${r(R)}" fill="none" stroke="${accent}" stroke-width="${r(sw)}" stroke-linecap="round" stroke-dasharray="${r(dash)} ${r(circ - dash)}" transform="rotate(-90 ${r(cx)} ${r(cy)})"/>`);
+  p.push(`<text x="${r(cx)}" y="${r(cy + R * 0.18)}" text-anchor="middle" font-size="${r(R * 0.5)}" ${wAttr(spec, 800)} fill="${valueCol}">${Math.round(frac * 100)}%</text>`);
+  if (spec.label) p.push(`<text x="${r(cx)}" y="${r(cy + R + sw / 2 + 16)}" text-anchor="middle" font-size="${fs}"${wOpt(spec)} fill="${labelCol}">${esc(spec.label)}</text>`);
+  if (watermark) p.push(`<text x="${W - 10}" y="${H - 9}" text-anchor="end" font-size="9" fill="${faint}" opacity="0.6">slickfast.com</text>`);
+  p.push(`</svg>`);
+  return p.join("\n");
+}
+function renderVersus(spec) {
+  const sides = Array.isArray(spec.sides) ? spec.sides.slice(0, 2) : [];
+  const bg = spec.background || "#ffffff";
+  const transparent = bg === "transparent" || bg === "none";
+  const isDark = !transparent && getLuminance(bg) < 0.35;
+  const fs = spec.fontSize ? Number(spec.fontSize) : 13;
+  const font = resolveFont(spec);
+  const watermark = spec.watermark !== false;
+  const title = spec.title || "";
+  const palette = resolveFlatPalette(spec.palette || "Clean Corporate", 3);
+  const titleCol = txt(spec, isDark ? "#f1f5f9" : "#0f172a");
+  const labelCol = txt(spec, isDark ? "#e2e8f0" : "#334155");
+  const faint = isDark ? "#475569" : "#94a3b8";
+  const PAD = 24, GAP = 44, W = spec.width || 620, H = spec.height || 320;
+  const topY = title ? 54 : 24;
+  const colW = (W - PAD * 2 - GAP) / 2;
+  const cols = [PAD, PAD + colW + GAP];
+  const p = [];
+  p.push(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}" font-family="${esc(font)}">`);
+  if (!transparent) p.push(`<rect x="0" y="0" width="${W}" height="${H}" fill="${bg}"/>`);
+  if (title) p.push(`<text x="${r(W / 2)}" y="33" text-anchor="middle" font-size="${fs + 5}" ${wAttr(spec, 700)} fill="${titleCol}">${esc(title)}</text>`);
+  [0, 1].forEach((si) => {
+    const side = sides[si] || {};
+    const col = side.color || palette[si === 0 ? 0 : palette.length - 1];
+    const x = cols[si];
+    p.push(`<rect x="${r(x)}" y="${r(topY)}" width="${r(colW)}" height="${r(H - topY - 16)}" rx="12" fill="${col}" fill-opacity="0.10"/>`);
+    p.push(`<text x="${r(x + colW / 2)}" y="${r(topY + 26)}" text-anchor="middle" font-size="${fs + 2}" ${wAttr(spec, 700)} fill="${col}">${esc(side.title || "")}</text>`);
+    const items = Array.isArray(side.items) ? side.items : [];
+    items.forEach((it, i) => {
+      const iy = topY + 52 + i * 28;
+      p.push(`<text x="${r(x + 16)}" y="${r(iy)}" font-size="${fs}"${wOpt(spec)} fill="${labelCol}">${esc(it.label || "")}</text>`);
+      if (it.value != null) p.push(`<text x="${r(x + colW - 14)}" y="${r(iy)}" text-anchor="end" font-size="${fs}" ${wAttr(spec, 700)} fill="${col}">${esc(fmt(it.value))}</text>`);
+    });
+  });
+  const mx = PAD + colW + GAP / 2, my = topY + (H - topY) / 2;
+  p.push(`<circle cx="${r(mx)}" cy="${r(my)}" r="20" fill="${transparent ? "#ffffff" : bg}" stroke="${faint}" stroke-opacity="0.5"/>`);
+  p.push(`<text x="${r(mx)}" y="${r(my + 5)}" text-anchor="middle" font-size="${fs}" ${wAttr(spec, 800)} fill="${faint}">VS</text>`);
+  if (watermark) p.push(`<text x="${W - 10}" y="${H - 9}" text-anchor="end" font-size="9" fill="${faint}" opacity="0.6">slickfast.com</text>`);
+  p.push(`</svg>`);
+  return p.join("\n");
+}
+function renderGantt(spec) {
+  const tasks = Array.isArray(spec.tasks) ? spec.tasks : [];
+  const n = Math.max(1, tasks.length);
+  const bg = spec.background || "#ffffff";
+  const transparent = bg === "transparent" || bg === "none";
+  const isDark = !transparent && getLuminance(bg) < 0.35;
+  const fs = spec.fontSize ? Number(spec.fontSize) : 13;
+  const font = resolveFont(spec);
+  const watermark = spec.watermark !== false;
+  const title = spec.title || "";
+  const palette = resolveFlatPalette(spec.palette || "Clean Corporate", Math.max(n, 3));
+  const titleCol = txt(spec, isDark ? "#f1f5f9" : "#0f172a");
+  const labelCol = txt(spec, isDark ? "#cbd5e1" : "#475569");
+  const gridCol = isDark ? "#1e293b" : "#eceef3";
+  const faint = isDark ? "#475569" : "#94a3b8";
+  const starts = tasks.map((t) => Number(t.start) || 0);
+  const ends = tasks.map((t) => Number(t.end) || 0);
+  const lo = Math.min(0, ...starts), hi = Math.max(1, ...ends);
+  const PAD = 24, LABELW = spec.labelWidth ? Number(spec.labelWidth) : 110, HEAD = 18, ROWH = 32;
+  const topY = title ? 54 : 22;
+  const W = spec.width || 660, H = spec.height || topY + HEAD + n * ROWH + 16;
+  const plotLeft = PAD + LABELW, plotW = W - PAD - plotLeft, gridTop = topY + HEAD;
+  const xOf = (v) => plotLeft + (v - lo) / (hi - lo || 1) * plotW;
+  const p = [];
+  p.push(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}" font-family="${esc(font)}">`);
+  if (!transparent) p.push(`<rect x="0" y="0" width="${W}" height="${H}" fill="${bg}"/>`);
+  if (title) p.push(`<text x="${r(W / 2)}" y="33" text-anchor="middle" font-size="${fs + 5}" ${wAttr(spec, 700)} fill="${titleCol}">${esc(title)}</text>`);
+  for (let k = 0; k <= 4; k++) {
+    const gx = plotLeft + k / 4 * plotW;
+    p.push(`<line x1="${r(gx)}" y1="${r(gridTop)}" x2="${r(gx)}" y2="${r(gridTop + n * ROWH)}" stroke="${gridCol}" stroke-width="1"/>`);
+  }
+  tasks.forEach((t, i) => {
+    const y = gridTop + i * ROWH;
+    const fill = t.color || palette[i % palette.length];
+    p.push(`<text x="${PAD}" y="${r(y + ROWH / 2 + 4)}" font-size="${fs}"${wOpt(spec)} fill="${labelCol}">${esc(t.label || "")}</text>`);
+    p.push(`<rect x="${r(xOf(Number(t.start) || 0))}" y="${r(y + 6)}" width="${r(Math.max(3, xOf(Number(t.end) || 0) - xOf(Number(t.start) || 0)))}" height="${ROWH - 12}" rx="5" fill="${fill}"/>`);
+  });
+  if (watermark) p.push(`<text x="${W - 10}" y="${H - 9}" text-anchor="end" font-size="9" fill="${faint}" opacity="0.6">slickfast.com</text>`);
+  p.push(`</svg>`);
+  return p.join("\n");
+}
+function renderWaterfall(spec) {
+  const steps = Array.isArray(spec.steps) ? spec.steps : [];
+  const start = Number(spec.start) || 0;
+  const bg = spec.background || "#ffffff";
+  const transparent = bg === "transparent" || bg === "none";
+  const isDark = !transparent && getLuminance(bg) < 0.35;
+  const fs = spec.fontSize ? Number(spec.fontSize) : 13;
+  const font = resolveFont(spec);
+  const watermark = spec.watermark !== false;
+  const title = spec.title || "";
+  const titleCol = txt(spec, isDark ? "#f1f5f9" : "#0f172a");
+  const catText = txt(spec, isDark ? "#cbd5e1" : "#475569");
+  const totalCol = isDark ? "#94a3b8" : "#1c2230";
+  const faint = isDark ? "#475569" : "#94a3b8";
+  let run = start;
+  const segs = steps.map((s) => {
+    const d = Number(s.value) || 0;
+    const from = run;
+    run += d;
+    return { label: s.label || "", from, to: run, delta: d, color: s.color };
+  });
+  segs.push({ label: spec.totalLabel || "Total", from: 0, to: run, delta: run, isTotal: true });
+  const N = Math.max(1, segs.length);
+  const vals = segs.flatMap((s) => [s.from, s.to]).concat(0);
+  const lo = Math.min(...vals), hi = Math.max(...vals, 1);
+  const PAD = 24, GAP = 14, HEAD = title ? 54 : 24;
+  const W = spec.width || 640, H = spec.height || 360;
+  const plotW = W - PAD * 2, plotBottom = H - 44, plotTop = HEAD;
+  const bandW = (plotW - GAP * (N - 1)) / N;
+  const yOf = (v) => plotBottom - (v - lo) / (hi - lo || 1) * (plotBottom - plotTop);
+  const p = [];
+  p.push(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}" font-family="${esc(font)}">`);
+  if (!transparent) p.push(`<rect x="0" y="0" width="${W}" height="${H}" fill="${bg}"/>`);
+  if (title) p.push(`<text x="${r(W / 2)}" y="33" text-anchor="middle" font-size="${fs + 5}" ${wAttr(spec, 700)} fill="${titleCol}">${esc(title)}</text>`);
+  segs.forEach((s, i) => {
+    const x = PAD + i * (bandW + GAP);
+    const yTop = yOf(Math.max(s.from, s.to)), yBot = yOf(Math.min(s.from, s.to));
+    const fill = s.isTotal ? totalCol : s.color || (s.delta >= 0 ? "#059669" : "#dc2626");
+    p.push(`<rect x="${r(x)}" y="${r(yTop)}" width="${r(bandW)}" height="${r(Math.max(2, yBot - yTop))}" rx="3" fill="${fill}"/>`);
+    if (i < segs.length - 1) {
+      const yc = r(yOf(s.to));
+      p.push(`<line x1="${r(x + bandW)}" y1="${yc}" x2="${r(x + bandW + GAP)}" y2="${yc}" stroke="${faint}" stroke-dasharray="3 3"/>`);
+    }
+    p.push(`<text x="${r(x + bandW / 2)}" y="${H - 26}" text-anchor="middle" font-size="${fs - 2}"${wOpt(spec)} fill="${catText}">${esc(s.label)}</text>`);
+  });
+  if (watermark) p.push(`<text x="${W - 10}" y="${H - 9}" text-anchor="end" font-size="9" fill="${faint}" opacity="0.6">slickfast.com</text>`);
+  p.push(`</svg>`);
+  return p.join("\n");
+}
+function renderSwimlane(spec) {
+  const lanes = Array.isArray(spec.lanes) ? spec.lanes : [];
+  const phases = Array.isArray(spec.phases) ? spec.phases : [];
+  const nl = Math.max(1, lanes.length), np = Math.max(1, phases.length);
+  const bg = spec.background || "#ffffff";
+  const transparent = bg === "transparent" || bg === "none";
+  const isDark = !transparent && getLuminance(bg) < 0.35;
+  const fs = spec.fontSize ? Number(spec.fontSize) : 13;
+  const font = resolveFont(spec);
+  const watermark = spec.watermark !== false;
+  const title = spec.title || "";
+  const palette = resolveFlatPalette(spec.palette || "Clean Corporate", Math.max(nl, 3));
+  const titleCol = txt(spec, isDark ? "#f1f5f9" : "#0f172a");
+  const labelCol = txt(spec, isDark ? "#cbd5e1" : "#475569");
+  const faint = isDark ? "#475569" : "#94a3b8";
+  const PAD = 24, LABELW = 100, HEAD = 22, LANEH = 50;
+  const topY = title ? 54 : 22;
+  const W = spec.width || 680, H = spec.height || topY + HEAD + nl * LANEH + 16;
+  const plotLeft = PAD + LABELW, colW = (W - PAD - plotLeft) / np, gridTop = topY + HEAD;
+  const p = [];
+  p.push(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}" font-family="${esc(font)}">`);
+  if (!transparent) p.push(`<rect x="0" y="0" width="${W}" height="${H}" fill="${bg}"/>`);
+  if (title) p.push(`<text x="${r(W / 2)}" y="33" text-anchor="middle" font-size="${fs + 5}" ${wAttr(spec, 700)} fill="${titleCol}">${esc(title)}</text>`);
+  phases.forEach((ph, ci) => p.push(`<text x="${r(plotLeft + ci * colW + colW / 2)}" y="${r(topY + HEAD - 7)}" text-anchor="middle" font-size="${fs - 1}" ${wAttr(spec, 600)} fill="${labelCol}">${esc(ph)}</text>`));
+  lanes.forEach((lane, li) => {
+    const y = gridTop + li * LANEH;
+    const col = lane.color || palette[li % palette.length];
+    p.push(`<rect x="${PAD}" y="${r(y + 4)}" width="${r(W - PAD * 2)}" height="${LANEH - 8}" rx="6" fill="${col}" fill-opacity="0.07"/>`);
+    p.push(`<text x="${PAD + 8}" y="${r(y + LANEH / 2 + 4)}" font-size="${fs}" ${wAttr(spec, 600)} fill="${labelCol}">${esc(lane.label || "")}</text>`);
+    (Array.isArray(lane.items) ? lane.items : []).forEach((it) => {
+      const ci = Math.max(0, Math.min(np - 1, Number(it.phase) || 0));
+      const bx = plotLeft + ci * colW;
+      p.push(`<rect x="${r(bx + 6)}" y="${r(y + 12)}" width="${r(colW - 12)}" height="${LANEH - 24}" rx="5" fill="${it.color || col}"/>`);
+      p.push(`<text x="${r(bx + colW / 2)}" y="${r(y + LANEH / 2 + 4)}" text-anchor="middle" font-size="${fs - 2}" fill="${contrastColor(it.color || col)}">${esc(it.label || "")}</text>`);
+    });
+  });
+  if (watermark) p.push(`<text x="${W - 10}" y="${H - 9}" text-anchor="end" font-size="9" fill="${faint}" opacity="0.6">slickfast.com</text>`);
+  p.push(`</svg>`);
+  return p.join("\n");
+}
+function renderTierList(spec) {
+  const tiers = Array.isArray(spec.tiers) ? spec.tiers : [];
+  const n = Math.max(1, tiers.length);
+  const bg = spec.background || "#ffffff";
+  const transparent = bg === "transparent" || bg === "none";
+  const isDark = !transparent && getLuminance(bg) < 0.35;
+  const fs = spec.fontSize ? Number(spec.fontSize) : 13;
+  const font = resolveFont(spec);
+  const watermark = spec.watermark !== false;
+  const title = spec.title || "";
+  const palette = resolveFlatPalette(spec.palette || "Clean Corporate", Math.max(n, 3));
+  const titleCol = txt(spec, isDark ? "#f1f5f9" : "#0f172a");
+  const chipBg = isDark ? "#334155" : "#e2e8f0";
+  const chipTx = isDark ? "#e2e8f0" : "#334155";
+  const faint = isDark ? "#475569" : "#94a3b8";
+  const PAD = 16, LABELW = 56, ROWH = 48, GAP = 6;
+  const topY = title ? 50 : 14;
+  const W = spec.width || 560, H = spec.height || topY + n * (ROWH + GAP) + 12;
+  const p = [];
+  p.push(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}" font-family="${esc(font)}">`);
+  if (!transparent) p.push(`<rect x="0" y="0" width="${W}" height="${H}" fill="${bg}"/>`);
+  if (title) p.push(`<text x="${PAD}" y="31" font-size="${fs + 5}" ${wAttr(spec, 700)} fill="${titleCol}">${esc(title)}</text>`);
+  tiers.forEach((t, i) => {
+    const y = topY + i * (ROWH + GAP);
+    const col = t.color || palette[i % palette.length];
+    p.push(`<rect x="${PAD}" y="${r(y)}" width="${LABELW}" height="${ROWH}" rx="6" fill="${col}"/>`);
+    p.push(`<text x="${r(PAD + LABELW / 2)}" y="${r(y + ROWH / 2 + 6)}" text-anchor="middle" font-size="${fs + 4}" ${wAttr(spec, 800)} fill="${contrastColor(col)}">${esc(t.label || "")}</text>`);
+    let cx = PAD + LABELW + 10;
+    (Array.isArray(t.items) ? t.items : []).forEach((it) => {
+      const label = typeof it === "string" ? it : it && it.label || "";
+      const cw = Math.round(label.length * (fs * 0.6) + 18);
+      if (cx + cw > W - PAD) return;
+      p.push(`<rect x="${r(cx)}" y="${r(y + ROWH / 2 - 13)}" width="${cw}" height="26" rx="6" fill="${chipBg}"/>`);
+      p.push(`<text x="${r(cx + cw / 2)}" y="${r(y + ROWH / 2 + 5)}" text-anchor="middle" font-size="${fs}"${wOpt(spec)} fill="${chipTx}">${esc(label)}</text>`);
+      cx += cw + 8;
+    });
+  });
+  if (watermark) p.push(`<text x="${W - 10}" y="${H - 9}" text-anchor="end" font-size="9" fill="${faint}" opacity="0.6">slickfast.com</text>`);
+  p.push(`</svg>`);
+  return p.join("\n");
+}
+function renderSwot(spec) {
+  const cells = Array.isArray(spec.cells) ? spec.cells.slice(0, 4) : [];
+  const bg = spec.background || "#ffffff";
+  const transparent = bg === "transparent" || bg === "none";
+  const isDark = !transparent && getLuminance(bg) < 0.35;
+  const fs = spec.fontSize ? Number(spec.fontSize) : 13;
+  const font = resolveFont(spec);
+  const watermark = spec.watermark !== false;
+  const title = spec.title || "";
+  const titleCol = txt(spec, isDark ? "#f1f5f9" : "#0f172a");
+  const bodyCol = txt(spec, isDark ? "#cbd5e1" : "#5b6270");
+  const faint = isDark ? "#475569" : "#94a3b8";
+  const tints = ["#2e9e6b", "#d6543a", "#2563eb", "#C17817"];
+  const PAD = 22, GAP = 14;
+  const topY = title ? 52 : 20;
+  const W = spec.width || 640, H = spec.height || 440;
+  const cellW = (W - PAD * 2 - GAP) / 2, cellH = (H - topY - PAD - GAP) / 2;
+  const p = [];
+  p.push(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}" font-family="${esc(font)}">`);
+  if (!transparent) p.push(`<rect x="0" y="0" width="${W}" height="${H}" fill="${bg}"/>`);
+  if (title) p.push(`<text x="${r(W / 2)}" y="33" text-anchor="middle" font-size="${fs + 5}" ${wAttr(spec, 700)} fill="${titleCol}">${esc(title)}</text>`);
+  for (let i = 0; i < 4; i++) {
+    const cell = cells[i] || {};
+    const col = i % 2, row = Math.floor(i / 2);
+    const x = PAD + col * (cellW + GAP), y = topY + row * (cellH + GAP);
+    const tint = cell.color || tints[i];
+    p.push(`<rect x="${r(x)}" y="${r(y)}" width="${r(cellW)}" height="${r(cellH)}" rx="10" fill="${tint}" fill-opacity="0.12"/>`);
+    p.push(`<text x="${r(x + 16)}" y="${r(y + 26)}" font-size="${fs + 1}" ${wAttr(spec, 700)} fill="${tint}">${esc(cell.title || "")}</text>`);
+    (Array.isArray(cell.items) ? cell.items : []).forEach((it, k) => {
+      const ly = y + 50 + k * 22;
+      if (ly > y + cellH - 8) return;
+      p.push(`<circle cx="${r(x + 20)}" cy="${r(ly - 4)}" r="2.5" fill="${tint}"/>`);
+      p.push(`<text x="${r(x + 30)}" y="${r(ly)}" font-size="${fs}"${wOpt(spec)} fill="${bodyCol}">${esc(typeof it === "string" ? it : it && it.label || "")}</text>`);
+    });
+  }
+  if (watermark) p.push(`<text x="${W - 10}" y="${H - 9}" text-anchor="end" font-size="9" fill="${faint}" opacity="0.6">slickfast.com</text>`);
+  p.push(`</svg>`);
+  return p.join("\n");
+}
 var TYPES = [
   { type: "bar", family: "comparison", needsData: true, summary: "vertical bar chart" },
   { type: "grouped", family: "comparison", needsData: true, summary: "clustered bars (one per series per category)" },
@@ -2227,7 +2558,15 @@ var TYPES = [
   { type: "gauge", family: "layout", needsData: false, summary: "radial gauge / dial (single value on a scale)" },
   { type: "bullet", family: "layout", needsData: false, dataKey: "bars", summary: "bullet graph (measure vs target on banded scale)" },
   { type: "calendar", family: "layout", needsData: false, dataKey: "days", summary: "calendar heatmap (year contribution grid)" },
-  { type: "leaderboard", family: "layout", needsData: false, dataKey: "items", summary: "leaderboard (ranked rows: rank + bar + value)" }
+  { type: "leaderboard", family: "layout", needsData: false, dataKey: "items", summary: "leaderboard (ranked rows: rank + bar + value)" },
+  { type: "callout", family: "layout", needsData: false, summary: "stat callout \u2014 hero number + caption + annotation" },
+  { type: "ring", family: "layout", needsData: false, summary: "progress ring \u2014 radial % toward a target" },
+  { type: "versus", family: "layout", needsData: false, dataKey: "sides", summary: "versus \u2014 two options compared side by side" },
+  { type: "gantt", family: "layout", needsData: false, dataKey: "tasks", summary: "gantt \u2014 tasks across a time row" },
+  { type: "waterfall", family: "layout", needsData: false, dataKey: "steps", summary: "waterfall \u2014 running total, step by step" },
+  { type: "swimlane", family: "layout", needsData: false, dataKey: "lanes", summary: "swimlane roadmap \u2014 lanes \xD7 phases grid" },
+  { type: "tierlist", family: "layout", needsData: false, dataKey: "tiers", summary: "tier list \u2014 ranked buckets (S/A/B) of chips" },
+  { type: "swot", family: "layout", needsData: false, dataKey: "cells", summary: "swot \u2014 four labeled 2\xD72 cells with bullet lists" }
 ];
 var TYPE_NAMES = TYPES.map((t) => t.type);
 function renderSpec(spec) {
@@ -2304,6 +2643,22 @@ function renderSpec(spec) {
       return renderCalendar(spec);
     case "leaderboard":
       return renderLeaderboard(spec);
+    case "callout":
+      return renderCallout(spec);
+    case "ring":
+      return renderRing(spec);
+    case "versus":
+      return renderVersus(spec);
+    case "gantt":
+      return renderGantt(spec);
+    case "waterfall":
+      return renderWaterfall(spec);
+    case "swimlane":
+      return renderSwimlane(spec);
+    case "tierlist":
+      return renderTierList(spec);
+    case "swot":
+      return renderSwot(spec);
     default:
       throw new Error('render-core: unknown chart type "' + spec.type + '"');
   }
@@ -2348,7 +2703,15 @@ var EXAMPLES = {
   gauge: { type: "gauge", label: "CPU load", value: 72, valueUnit: "%" },
   bullet: { type: "bullet", bars: [{ label: "Revenue", value: 275, target: 250, max: 300, bands: [150, 225] }] },
   calendar: { type: "calendar", year: 2025, days: { "2025-01-06": 3, "2025-07-21": 8 } },
-  leaderboard: { type: "leaderboard", items: [{ label: "North", value: 530 }, { label: "East", value: 610 }] }
+  leaderboard: { type: "leaderboard", items: [{ label: "North", value: 530 }, { label: "East", value: 610 }] },
+  callout: { type: "callout", value: 3.4, valueUnit: "\xD7", caption: "faster than last quarter", note: "vs Q1" },
+  ring: { type: "ring", value: 70, target: 100, label: "Goal completion" },
+  versus: { type: "versus", sides: [{ title: "Plan A", items: [{ label: "Price", value: 9 }, { label: "Seats", value: 3 }] }, { title: "Plan B", items: [{ label: "Price", value: 29 }, { label: "Seats", value: 10 }] }] },
+  gantt: { type: "gantt", tasks: [{ label: "Design", start: 0, end: 3 }, { label: "Build", start: 2, end: 7 }, { label: "Launch", start: 7, end: 9 }] },
+  waterfall: { type: "waterfall", start: 0, steps: [{ label: "Q1", value: 50 }, { label: "Q2", value: 30 }, { label: "Q3", value: -20 }, { label: "Q4", value: 40 }] },
+  swimlane: { type: "swimlane", phases: ["Q1", "Q2", "Q3"], lanes: [{ label: "Eng", items: [{ phase: 0, label: "API" }, { phase: 2, label: "v2" }] }, { label: "Design", items: [{ phase: 1, label: "Rebrand" }] }] },
+  tierlist: { type: "tierlist", tiers: [{ label: "S", items: ["Bar", "Line"] }, { label: "A", items: ["Pie", "Area"] }, { label: "B", items: ["Radar"] }] },
+  swot: { type: "swot", cells: [{ title: "Strengths", items: ["Fast", "Cheap"] }, { title: "Weaknesses", items: ["New brand"] }, { title: "Opportunities", items: ["AI demand"] }, { title: "Threats", items: ["Incumbents"] }] }
 };
 
 // ../../packages/raster/raster.mjs
@@ -2362,7 +2725,7 @@ function svgToPng(svg, opts = {}) {
 // server.mjs
 var NO_DATA_TYPES = TYPES.filter((t) => !t.needsData).map((t) => t.type);
 var here = dirname(fileURLToPath(import.meta.url));
-var CHART_SPEC_MD = true ? '# ChartSpec \u2014 the render-core contract (the API/MCP input)\n\nOne JSON object (a **spec**) goes in; one **SVG string** comes out, via\n`renderSpec(spec)`. This document is the contract an agent (or the MCP tool) follows\nto produce a chart. It is written agent-first: **a spec with only `type` + `data`\nrenders a complete, good-looking chart** \u2014 every other field is an optional override.\n\n```js\nimport { renderSpec } from \'./render-core.mjs\';\nconst svg = renderSpec({ type: \'bar\', data: { labels: [\'A\',\'B\',\'C\'], series: [{ values: [10, 20, 15] }] } });\n```\n\n## When to use this \u2014 and when to fall back\n\n**Prefer `render_chart` for any supported type** (see "Chart types" below) over\nhand-writing plotting code (matplotlib, plotly, chart.js). It\'s faster, deterministic,\nand good-looking with just `{type, data}`. Pass `outputPath` when the user wants the\nfile saved to disk.\n\n**Fall back to your own plotting only for what this engine does not do yet:**\n- **Chart types not listed below** \u2014 scatter, bubble, heatmap, treemap, radar, sankey,\n  geographic maps, candlestick, gantt.\n- **Reference / target / threshold lines, log scales, secondary (dual) axes, and point\n  annotations / callouts** \u2014 on the roadmap, not available today.\n- **Interactivity, animation, hover tooltips** \u2014 output is a static SVG/PNG.\n\n## Universal fields (every chart type honors these)\n\n| field | type | default | what it does |\n|---|---|---|---|\n| `type` | string | \u2014 (required) | which chart: `"bar"`, `"line"`, `"kpi"` (more coming) |\n| `title` | string | `""` | heading drawn at the top |\n| `width` | number | per type | SVG width in px |\n| `height` | number | per type | SVG height in px |\n| `preset` / `ratio` | string | \u2014 | aspect-ratio preset \u2192 sets width/height (explicit `width`/`height` win). `Share Card` 1.91:1 (1200\xD7630, link/OG cards), `Wide` 16:9 (1280\xD7720), `Square` 1:1 (1080\xD71080), `Portrait` 4:5 (1080\xD71350), `Tall` 9:16 (1080\xD71920), `Classic` 4:3 (1200\xD7900). `ratio` also accepts the bare ratio string (`"16:9"`, `"9:16"`, \u2026) |\n| `background` | string | `"#ffffff"` | any hex color, or `"transparent"` for no fill (overlays/exports) |\n| `palette` | string | `"Clean Corporate"` | named palette: `Clean Corporate`, `Pastel`, `Vibrant`, `Monochrome`, `Cyberpunk`, `Analogous Shift`. Pick **`Monochrome`** when the chart will be **printed in black & white / on a laser printer** \u2014 it\'s a single-hue grey ramp that stays legible without color (other palettes can render as indistinct greys when printed). |\n| `font` | string | `"Inter"` | a named font: `Inter`, `System`, `Serif`, `Mono`, `Rounded`, `Condensed` |\n| `fontFamily` | string | \u2014 | a raw CSS font stack (overrides `font`; full control / future custom fonts) |\n| `fontSize` | number | `13` | base text size; other text scales from it |\n| `textColor` | string | auto | force a color for the **neutral** text (title, axis, category, value, legend, pie slice labels). Omit it and the engine auto-picks black/white for contrast. Semantic colors (green \u25B2 / red \u25BC deltas & gaps) stay meaningful. |\n| `bold` | boolean | `false` | thicken every text element |\n| `fontWeight` | string | \u2014 | exact weight for all text (`"400"`\u2013`"900"` or `"bold"`); overrides `bold` |\n| `valueUnit` | string | `""` | appended to values, e.g. `"$"`, `"%"`, `"ms"` |\n| `showValues` | boolean | `true` | draw the numeric labels |\n| `watermark` | boolean | `true` | tasteful "slickfast.com" mark. **Set `false` for the chart sites / paid output.** |\n\n**Readability is automatic:** text colors are chosen from the background\'s luminance\n(via palette-core), so labels stay legible on light *or* dark backgrounds.\n\n## Data shape\n\n```json\n"data": {\n  "labels": ["North", "South", "East"],\n  "series": [\n    { "name": "Revenue", "values": [420, 310, 530], "colors": ["#2563eb", "#7c3aed", "#059669"] }\n  ]\n}\n```\n\n- `labels` \u2014 the categories (x-axis).\n- `series[].values` \u2014 the numbers, aligned to `labels`.\n- `series[].colors` \u2014 **optional** explicit per-item colors. If omitted, colors come\n  from `palette`. (Used when a user has customized individual bars.)\n- `series[].name` \u2014 optional label for the series.\n\n## Chart types\n\n### `bar` \u2014 vertical bar chart\nDefault size `800 \xD7 450`. Uses `data.series[0]`. Each bar a palette color (or its\nexplicit `colors[i]`), top-rounded, with value + category labels and "nice" axis numbers.\n\n| extra field | type | default | does |\n|---|---|---|---|\n| `showTotal` | boolean | `true` | "Total: N" badge, top-right |\n\nMinimal: `{ "type": "bar", "data": { "labels": ["A","B"], "series": [{ "values": [10,20] }] } }`\n\n### `grouped` \u2014 clustered bar chart (one bar per series in each category)\nDefault size `800 \xD7 450`. The `data.labels` are the **groups** (categories); each\n`data.series` entry is a bar that repeats inside every group. **Color = series\nidentity:** one solid palette color per series (A=palette[0], B=palette[mid], extras\nspread), the same color in every group \u2014 never rainbow-within-a-series. A centered\nlegend names the series. Best read with \u2264 4 series.\n\nMinimal: `{ "type": "grouped", "data": { "labels": ["Q1","Q2"], "series": [{ "name":"2023","values":[42,55] }, { "name":"2024","values":[52,48] }] } }`\n\n### `stacked` \u2014 stacked bar chart (segments stack within each category)\nDefault size `800 \xD7 450`. Each `data.labels` entry is a bar; each `data.series` entry\nis a **segment** stacked inside every bar, with a distinct palette color used\nconsistently across all bars. Inside each segment, two labels: the **name pinned to the\ntop**, the **value to the bottom** (contrast-aware text \u2014 dark on light fills, white on\ndark). Thin segments hide the name but keep the value. Only the top segment\'s outer edge\nis rounded; joins stay flush. A centered legend names the segments.\n\nMinimal: `{ "type": "stacked", "data": { "labels": ["Q1","Q2"], "series": [{ "name":"Core","values":[30,35] }, { "name":"Add-ons","values":[18,20] }] } }`\n\n### `stacked100` \u2014 100% stacked bar (each bar normalized to 100%)\nSame as `stacked`, but every bar fills the full height and each segment shows its\n**share of that bar** as an integer percent. Percentages use largest-remainder\nrounding so every bar sums to **exactly 100** (never 99/101). Best for comparing\n*mix* across categories rather than absolute totals.\n\nMinimal: `{ "type": "stacked100", "data": { "labels": ["Q1","Q2"], "series": [{ "name":"Core","values":[30,35] }, { "name":"Add-ons","values":[18,20] }] } }`\n\n### `stackedh` \u2014 horizontal stacked bar\nSame data model as `stacked`, transposed: bars run left\u2192right, one row per\n`data.labels` entry, segments stack horizontally. The last segment rounds its right\nedge; joins stay flush. Segment name + value sit centered in each segment (value-only\nwhen narrow); a centered legend names the segments. Good when category labels are long.\n\nMinimal: `{ "type": "stackedh", "data": { "labels": ["Eng","Sales"], "series": [{ "name":"Salaries","values":[120,90] }, { "name":"Tools","values":[40,25] }] } }`\n\n### `horizontal` \u2014 horizontal bar (single series)\nDefault size `800 \xD7 450`. One row per `data.labels` entry; each bar its own palette\ncolor by index (or its explicit `colors[i]`), value at the bar end, "Total: N" badge\ntop-right. Best when labels are long or there are many categories.\n\nMinimal: `{ "type": "horizontal", "data": { "labels": ["US","India"], "series": [{ "values": [820,610] }] } }`\n\n### `diverging` \u2014 diverging bar (around a zero line)\nDefault size `800 \xD7 450`. **Two modes, chosen by series count:**\n- **Two series** \u2192 opposing bars: **Series A forced up, Series B forced down** (both\n  abs-valued), one solid color each (A=palette[0], B=palette[mid]); a centered legend\n  names both. Great for sentiment (agree/disagree), inflow/outflow.\n- **One series** \u2192 classic **signed** diverging: each value plotted by its own sign\n  (**positive up, negative down**), a single color, a single-name legend, and signed\n  value labels (e.g. `-3` below the zero line).\n\nThe zero line is emphasized; down-bar labels sit below their bars.\n\nMinimal (two-series): `{ "type": "diverging", "data": { "labels": ["A","B"], "series": [{ "name":"Agree","values":[62,48] }, { "name":"Disagree","values":[38,52] }] } }`\n\nMinimal (signed): `{ "type": "diverging", "data": { "labels": ["Q1","Q2","Q3"], "series": [{ "name":"Net flow","values":[5,-3,8] }] } }`\n\n### `lollipop` \u2014 lollipop chart (single series)\nDefault size `800 \xD7 450`. One stem + dot per `data.labels` entry, each its own palette\ncolor by index (or explicit `colors[i]`), value above the dot, category below, "Total: N"\nbadge top-right. A lighter-weight alternative to `bar` when the bars would feel heavy.\n\nMinimal: `{ "type": "lollipop", "data": { "labels": ["A","B","C"], "series": [{ "values": [78,64,52] }] } }`\n\n### `line` \u2014 line chart (single or multi-series)\nDefault size `800 \xD7 450`. One line per `data.series` entry, each a palette color\n(or its own `color`), with points and a centered legend when there\'s more than one\nseries. "Nice" axis numbers; points span edge-to-edge.\n\n| extra field | type | default | does |\n|---|---|---|---|\n| `curve` | string | `"straight"` | line shape: `"straight"`, `"smooth"` (curved), `"stepped"` |\n| `area` | boolean | `false` | fill the region under each line (translucent) |\n| `showPoints` | boolean | `true` | dots at each data point |\n| `showValues` | boolean | `false` | numbers above each point (off by default \u2014 lines get crowded) |\n| series `color` | string | palette | per-line color override |\n\n**Type shortcuts:** `type: "smooth"`, `"area"`, `"stepped"` map to `line` with the\nmatching option set \u2014 `{type:"area"}` \u2261 `{type:"line", area:true}`. Also:\n- `type: "stackedArea"` \u2014 every series stacks cumulatively, filled bands + legend.\n- `type: "difference"` \u2014 exactly two series; shades the gap between them and labels\n  the gap value at each point (green where series 1 leads, red where it trails).\n- `type: "slope"` \u2014 a slopegraph: each series\' first vs last value, connected by a\n  straight line, with the end value + change labeled (green up / red down).\n\nMinimal: `{ "type": "line", "data": { "labels": ["Jan","Feb","Mar"], "series": [{ "name": "Users", "values": [120,190,170] }] } }`\n\n### `pie` / `donut` \u2014 proportion of a whole\nDefault size `640 \xD7 420`. One series; each label+value is a slice, colored from the\npalette (or explicit `colors`). Percentage labels sit inside slices \u2265 6%; a legend\n(label \xB7 value) runs down the right. `donut` adds a center hole with the **total** in\nthe middle.\n\nMinimal: `{ "type": "pie", "data": { "labels": ["A","B","C"], "series": [{ "values": [45,30,25] }] } }`\n\n### `pieofpie` \u2014 nested drill-down pies (pie-of-pie, pie-of-pie-of-pie, N-tier)\nDefault size `920 \xD7 460`. A row of pies where each pie\'s **first slice (the "bridge")**\nexplodes toward the next pie and breaks down into it, joined by two connector lines.\n2 pies = pie-of-pie, 3 = pie-of-pie-of-pie, N supported; each pie is 75% the size of the\none before. Donut by default. Each pie gets a **`name \xB7 value` legend beneath it**\n(honoring `valuePrefix`/`valueUnit`) so slices are identifiable; the slices themselves\nkeep their `%` labels.\n\nUses **`pies`** (not `data`): an array of `{ title?, labels[], values[], colors?, palette? }`.\nSlice index 0 of each pie is the bridge into the next pie.\n\n| extra field | type | default | does |\n|---|---|---|---|\n| `pies` | array | \u2014 (required) | the pies; pie[i] slice 0 drills into pie[i+1] |\n| `donut` | boolean | `true` | center hole on each pie (`false` = solid pies) |\n| `cascade` | boolean | `true` | child pies shade from the parent bridge hue; `false` = flat palette per pie |\n| `palette` | string | `"Clean Corporate"` | a **nested theme** (below) \u2014 drives the whole cascade |\n\n**Nested themes** (premium color cascades, set via `palette`):\n- *Inspired tiers* (hand-tuned per-pie triads): `Analogous Shift` (showcase \u2014 a spectrum\n  walk), `Retro Editorial`, `Classic Triadic`, `Sorbet Pastel`.\n- *Generative* (children derived from the root hue): `Modern Corporate`, `Nordic Earth`,\n  `Cyberpunk Glow`, `Sequential Rainbow`, plus classics `Clean Corporate`, `Pastel`,\n  `Vibrant`, `Monochrome`. (Authoring new ones: `palette-core/AUTHORING-PALETTES.md`.)\n\nMinimal: `{ "type": "pieofpie", "palette": "Analogous Shift", "pies": [ { "labels": ["Enterprise","SMB","Other"], "values": [60,30,10] }, { "labels": ["US","EU","APAC"], "values": [35,15,10] } ] }`\n\n### `kpi` \u2014 single metric tile (the exec-snapshot building block)\nDefault size `340 \xD7 180`. A card: label + big value + colored delta pill + palette accent.\n\n| extra field | type | default | does |\n|---|---|---|---|\n| `label` | string | `""` | the metric name (top) |\n| `value` | number | \u2014 | the big number |\n| `valuePrefix` | string | `""` | e.g. `"$"` before the value |\n| `delta` | number | none | the change; renders a pill \u2014 \u25B2 if positive, \u25BC if negative |\n| `deltaUnit` | string | `"%"` | unit on the delta |\n| `deltaGoodWhen` | string | `"up"` | which direction is GOOD (green). Set `"down"` for lower-is-better metrics (churn, latency, cost) \u2014 the arrow still shows real direction, only the color flips |\n| `sparkline` | number[] | none | a minimalist trend line along the bottom (e.g. the last N periods) \u2014 no axes/labels, colored to match the delta (green good / red bad). Needs \u2265 2 points; **landscape tile only**. Omit it and the tile is byte-identical. |\n\nMinimal: `{ "type": "kpi", "label": "MRR", "value": 128400, "valuePrefix": "$", "delta": 12.4 }`\n\nWith a sparkline: `{ "type": "kpi", "label": "MRR", "value": 128400, "valuePrefix": "$", "delta": 12.4, "sparkline": [98,104,101,112,118,121,128] }`\n\n### `cards` \u2014 a row/grid of stat cards (the multi-KPI dashboard strip)\nA set of KPI tiles in one image \u2014 for an exec snapshot of several metrics at once.\nUses its own **`cards`** array (not `data`): each entry is one card, reusing the **same\nfields as `kpi`**. Each card\'s accent cycles the palette by index; the delta pill follows\nthe same good/bad coloring (\u25B2/\u25BC shows real direction, color shows good-or-bad). Layout is a\n**bounded computed grid**: by default a single horizontal strip, wrapping to a grid once there\nare more than 4 cards. Size auto-fits the grid unless you set `width`/`height`.\n\n| field | type | default | does |\n|---|---|---|---|\n| `cards` | array | \u2014 (required) | the tiles; each: `label`, `value`, `valuePrefix`, `valueUnit`, `delta`, `deltaUnit`, `deltaGoodWhen` (same meaning as `kpi`) |\n| `gridColumns` | number | min(cards, 4) | force the number of columns; cards wrap into rows |\n\nMinimal: `{ "type": "cards", "cards": [ { "label": "MRR", "value": 128400, "valuePrefix": "$", "delta": 12.4 }, { "label": "Active users", "value": 8210, "delta": 3.1 }, { "label": "Churn", "value": 2.4, "valueUnit": "%", "delta": 0.6, "deltaGoodWhen": "down" } ] }`\n\n### `layers` \u2014 labeled box-stack / layer diagram\nA vertical stack of labeled blocks \u2014 a structure/architecture picture (e.g. a tech\nstack, a hierarchy of tiers), **not** a stacked bar (no values, no axis). Uses its own\n**`layers`** array (not `data`): each entry is `{ title, subtitle? }`, drawn top\u2192bottom\nas an equal-height rounded block. Each block fills a distinct palette color, cycling the\npalette; the title (and optional subtitle) sit centered with **contrast-aware text**\n(dark on light fills, white on dark). Inherits every universal field.\n\n| field | type | default | does |\n|---|---|---|---|\n| `layers` | array | \u2014 (required) | the blocks, top to bottom; each: `title`, optional `subtitle` |\n\nMinimal: `{ "type": "layers", "layers": [ { "title": "Application", "subtitle": "React + TypeScript" }, { "title": "API", "subtitle": "Node + Hono" }, { "title": "Engine", "subtitle": "render-core (pure SVG)" }, { "title": "Infra", "subtitle": "Railway + Docker" } ] }`\n\n### `progress` \u2014 labeled progress / bullet bars\nLabeled horizontal bars filling toward a target \u2014 for "how far along" readouts. Uses\nits own **`bars`** array: each `{ label, value, target?, valueUnit? }`. The track end IS\nthe target, so the fill = `value / target`; the label shows `value / target`. With **no\n`target`**, `value` is read as a percent (0\u2013100) and the track end is 100%. Each bar a\npalette color by index. Inherits every universal field.\n\n| field | type | default | does |\n|---|---|---|---|\n| `bars` | array | \u2014 (required) | the bars; each: `label`, `value`, optional `target`, optional `valueUnit` |\n\nMinimal: `{ "type": "progress", "bars": [ { "label": "Q1 revenue", "value": 82, "target": 100 }, { "label": "Signups", "value": 1240, "target": 2000 }, { "label": "Uptime", "value": 99.2, "valueUnit": "%" } ] }`\n\n### `waffle` \u2014 waffle / dot grid\nA 10\xD710 grid of cells showing part-of-whole \u2014 friendlier than a pie for "% complete" or\na simple mix. Uses its own **`parts`** array `{ label, value, color? }`: parts fill the\n100 cells proportionally (largest-remainder rounding keeps the count exact). If the parts\nsum to **less than 100**, the remainder are **empty track cells** \u2014 so **one part** is a\n"% filled" gauge, and **several parts** is categorical part-to-whole. A `label \xB7 value`\nlegend sits beside the grid.\n\n| field | type | default | does |\n|---|---|---|---|\n| `parts` | array | \u2014 (required) | the filled groups; each: `label`, `value` (cell count), optional `color` |\n\nMinimal: `{ "type": "waffle", "parts": [ { "label": "Enterprise", "value": 45 }, { "label": "SMB", "value": 30 }, { "label": "Other", "value": 15 } ] }`\n\n### `heatmap` \u2014 colored grid (rows \xD7 columns)\nA grid of cells colored by value (light \u2192 dark on a single palette hue) \u2014 for "intensity\nacross two dimensions" (e.g. activity by day \xD7 hour). Uses its own 2D shape: **`rows`**\n(row labels), **`columns`** (column labels), and **`values`** \u2014 a matrix where\n`values[row][col]` is the cell value. Cell value text is contrast-aware; `showValues:false`\nhides the numbers.\n\n| field | type | default | does |\n|---|---|---|---|\n| `rows` | string[] | \u2014 (required) | row labels (one per matrix row) |\n| `columns` | string[] | \u2014 (required) | column labels (one per matrix column) |\n| `values` | number[][] | \u2014 (required) | the matrix, `values[row][col]` |\n\nMinimal: `{ "type": "heatmap", "rows": ["Mon","Tue","Wed"], "columns": ["9a","12p","3p","6p"], "values": [[2,5,8,3],[1,4,9,6],[0,3,7,2]] }`\n\n### `funnel` \u2014 stages narrowing top\u2192bottom\nA conversion/drop-off funnel. Uses its own **`stages`** array `{ label, value }`: each\nstage is a centered band whose width is proportional to its value, tapering into the\nnext. Each band shows the label, the value, and its **% of the top stage**. Palette\ncolor per stage; band text is contrast-aware.\n\n| field | type | default | does |\n|---|---|---|---|\n| `stages` | array | \u2014 (required) | the stages top\u2192bottom; each: `label`, `value` |\n\nMinimal: `{ "type": "funnel", "stages": [ { "label": "Visitors", "value": 12000 }, { "label": "Signups", "value": 4200 }, { "label": "Trials", "value": 1800 }, { "label": "Paid", "value": 640 } ] }`\n\n### `pyramid` \u2014 hierarchy levels\nA triangle (apex on top) split into equal-height bands \u2014 for layered hierarchies\n(Maslow-style, org tiers, strategy levels). Uses its own **`levels`** array\n`{ title, value? }` (`label` is accepted as an alias for `title`). Each level a palette\ncolor, label centered with contrast-aware text; `value` is shown beside the label if set.\n\n| field | type | default | does |\n|---|---|---|---|\n| `levels` | array | \u2014 (required) | the levels, apex\u2192base; each: `title`, optional `value` |\n\nMinimal: `{ "type": "pyramid", "levels": [ { "title": "Vision" }, { "title": "Strategy" }, { "title": "Execution" }, { "title": "Operations" } ] }`\n\n### `quadrant` \u2014 2\xD72 matrix\nItems placed by two dimensions (effort/impact, reach/ease, etc.). Uses its own **`items`**\narray `{ label, x, y }` with `x`/`y` in **0\u20131** (x left\u2192right, y bottom\u2192top), plus\n**`xAxis`** and **`yAxis`** labels. A square plot is split by a crosshair into four\nquadrants; each item is a labeled dot (palette color by index).\n\n| field | type | default | does |\n|---|---|---|---|\n| `items` | array | \u2014 (required) | the items; each: `label`, `x` (0\u20131), `y` (0\u20131) |\n| `xAxis` | string | `""` | horizontal axis label |\n| `yAxis` | string | `""` | vertical axis label |\n\nMinimal: `{ "type": "quadrant", "xAxis": "Effort", "yAxis": "Impact", "items": [ { "label": "Quick win", "x": 0.2, "y": 0.8 }, { "label": "Big bet", "x": 0.8, "y": 0.9 }, { "label": "Time sink", "x": 0.8, "y": 0.2 } ] }`\n\n### `timeline` \u2014 events along one line\nA linear timeline. Uses its own **`events`** array `{ date?, label }`: events sit evenly\nspaced along a horizontal line, the date by the line and the label **alternating\nabove/below** so they don\'t crowd. Keep labels short.\n\n| field | type | default | does |\n|---|---|---|---|\n| `events` | array | \u2014 (required) | the events in order; each: optional `date`, `label` |\n\nMinimal: `{ "type": "timeline", "events": [ { "date": "Q1", "label": "Launch" }, { "date": "Q2", "label": "Series A" }, { "date": "Q3", "label": "100k users" }, { "date": "Q4", "label": "Profitable" } ] }`\n\n### `venn` \u2014 2\u20133 overlapping sets\nOverlapping translucent circles for set relationships. Uses its own **`sets`** array\n`{ label, value }` (2 or 3 sets; fixed layout \u2014 2 side-by-side, 3 in a triangle) plus an\noptional **`overlap`** count (2-set), shown in the lens. Each circle is labeled with its\nvalue.\n\n| field | type | default | does |\n|---|---|---|---|\n| `sets` | array | \u2014 (required) | 2\u20133 sets; each: `label`, `value` |\n| `overlap` | number | \u2014 | (2 sets) the count shared by both, drawn in the overlap |\n\nMinimal: `{ "type": "venn", "sets": [ { "label": "Design", "value": 120 }, { "label": "Engineering", "value": 160 } ], "overlap": 40 }`\n\n### `matrix` \u2014 comparison / feature matrix\nA rows \xD7 columns table of \u2713/\u2717 (the pricing/feature-comparison look). Uses its own shape:\n**`columns`** (string[]) + **`rows`** `{ label, cells[] }` (one cell per column). Each cell is\na **boolean** or **status word** \u2192 a glyph (`true`/`"yes"` \u2713 green, `false`/`"no"` \u2717 grey,\n`"partial"` \u2022 amber, `""`/`"-"` dash), or any other string \u2192 rendered as **text** (e.g. a\nplan limit). Rows zebra-stripe for readability. `labelWidth` sets the row-label column width.\n\n| field | type | default | does |\n|---|---|---|---|\n| `columns` | string[] | \u2014 (required) | the column headers |\n| `rows` | array | \u2014 (required) | each: `label`, `cells[]` (boolean / status word / text, aligned to columns) |\n| `labelWidth` | number | `200` | px reserved for the row-label column |\n\nMinimal: `{ "type": "matrix", "columns": ["Free","Pro","Enterprise"], "rows": [ { "label": "SSO / SAML", "cells": [false,false,true] }, { "label": "API access", "cells": [false,true,true] }, { "label": "Priority support", "cells": [false,"partial",true] }, { "label": "Seats", "cells": ["1","10","Unlimited"] } ] }`\n\n### `checklist` \u2014 checklist / status list\nA vertical list of items each with a status glyph \u2014 for run-of-show / readiness lists. Uses\nits own **`items`** array `{ label, status }`: **`done`** \u2713 (green, label mutes), **`blocked`**\n\u2717 (red), **`partial`** \u2022 (amber), anything else (or `pending`) \u2192 an empty ring.\n\n| field | type | default | does |\n|---|---|---|---|\n| `items` | array | \u2014 (required) | each: `label`, `status` (`done`/`pending`/`blocked`/`partial`) |\n\nMinimal: `{ "type": "checklist", "title": "Launch checklist", "items": [ { "label": "Domain transferred", "status": "done" }, { "label": "API deployed", "status": "done" }, { "label": "Load testing", "status": "pending" }, { "label": "Billing live", "status": "blocked" } ] }`\n\n### `iconarray` \u2014 icon array / pictogram\n`total` person icons with the first `filled` colored and the rest faint \u2014 a friendly\npart-of-whole ("7 of 10 teams onboarded"). `perRow` controls wrapping.\n\n| field | type | default | does |\n|---|---|---|---|\n| `total` | number | `10` | total icons |\n| `filled` | number | `0` | how many are filled (the rest faint) |\n| `perRow` | number | `min(total,10)` | icons per row before wrapping |\n\nMinimal: `{ "type": "iconarray", "title": "Teams onboarded (7/10)", "total": 10, "filled": 7 }`\n\n### `steps` \u2014 step / process row\nNumbered nodes left\u2192right joined by connector arrows \u2014 a **linear** process flow (not a\nbranching graph). Uses its own **`steps`** array `{ label, description? }`: each step is a\nnumbered palette circle with its label (and optional description) beneath. Positions are\ncomputed directly; no graph layout.\n\n| field | type | default | does |\n|---|---|---|---|\n| `steps` | array | \u2014 (required) | the steps in order; each: `label`, optional `description` |\n\nMinimal: `{ "type": "steps", "steps": [ { "label": "Sign up" }, { "label": "Connect data" }, { "label": "Build chart" }, { "label": "Share" } ] }`\n\n### `table` \u2014 data table (rows \xD7 columns)\nA plain tabular grid of text/values (the general tabular type; `matrix` is the \u2713/\u2717 variant).\nUses its own shape: **`columns`** (string[] header) + **`rows`** (an array of **cell arrays**).\nNumbers right-align and format with thousands separators; text left-aligns. Header rule +\nzebra rows.\n\n| field | type | default | does |\n|---|---|---|---|\n| `columns` | string[] | \u2014 (required) | the header cells |\n| `rows` | array | \u2014 (required) | each row is an array of cells (string or number), aligned to columns |\n\nMinimal: `{ "type": "table", "columns": ["Region","Q1","Q2","Q3"], "rows": [ ["North",420,510,480], ["South",310,290,350], ["East",530,560,600] ] }`\n\n### `gauge` \u2014 radial dial (single value)\nA 180\xB0 dial showing one value on a `min`..`max` scale \u2014 for "how full / how far" readouts. The\narc band fills to the value; the number sits in the center with `min`/`max` at the ends.\n\n| field | type | default | does |\n|---|---|---|---|\n| `value` | number | \u2014 (required) | the value to show |\n| `min` | number | `0` | scale minimum |\n| `max` | number | `100` | scale maximum |\n| `label` | string | `""` | caption under the value |\n| `valueUnit` | string | `""` | appended to the value |\n\nMinimal: `{ "type": "gauge", "label": "CPU load", "value": 72, "valueUnit": "%" }`\n\n### `bullet` \u2014 bullet graph\nA compact measure-vs-target gauge (Stephen Few style): a thin measure bar over grey\nqualitative bands, with a target tick \u2014 richer than `progress`. Uses its own **`bars`** array\n`{ label, value, target, max, bands }`, where `bands` are the threshold edges (e.g. `[150,225]`)\nthat shade the background into qualitative ranges.\n\n| field | type | default | does |\n|---|---|---|---|\n| `bars` | array | \u2014 (required) | each: `label`, `value`, optional `target` (tick), `max` (scale), `bands` (range edges) |\n\nMinimal: `{ "type": "bullet", "bars": [ { "label": "Revenue", "value": 275, "target": 250, "max": 300, "bands": [150,225] }, { "label": "Profit", "value": 82, "target": 100, "max": 120, "bands": [60,90] } ] }`\n\n### `calendar` \u2014 calendar heatmap (year grid)\nA GitHub-style contribution grid: weeks across, days down, each day a cell colored light\u2192dark by\nvalue on one palette hue. Uses **`days`** \u2014 a map of `"YYYY-MM-DD" \u2192 value` \u2014 plus **`year`**.\nWeekday placement is computed arithmetically (no clock), so it\'s fully deterministic.\n\n| field | type | default | does |\n|---|---|---|---|\n| `days` | object | \u2014 (required) | `"YYYY-MM-DD"` \u2192 number (the value for that day) |\n| `year` | number | `2025` | which year the grid covers (sets leap year + start weekday) |\n\nMinimal: `{ "type": "calendar", "title": "Activity", "year": 2025, "days": { "2025-01-06": 3, "2025-03-14": 8, "2025-07-21": 5 } }`\n\n### `leaderboard` \u2014 ranked rows\nA ranked list: each row is rank # + label + a bar (\u221D value) + the value, **auto-sorted\ndescending**. Uses its own **`items`** array `{ label, value }`.\n\n| field | type | default | does |\n|---|---|---|---|\n| `items` | array | \u2014 (required) | each: `label`, `value` (sorted high\u2192low, numbered) |\n\nMinimal: `{ "type": "leaderboard", "title": "Top regions", "items": [ { "label": "North", "value": 530 }, { "label": "South", "value": 480 }, { "label": "East", "value": 610 }, { "label": "West", "value": 390 } ] }`\n\n## What an agent can change (the levers)\n\n- **Fonts** \u2192 `fontFamily`, `fontSize`\n- **Colors** \u2192 `palette` (a named set) for the whole chart, or `data.series[].colors` for exact\n  per-item control. The info-design types take **explicit per-element color** the same way: add a\n  `color` to any element object \u2014 `cards[].color`, `layers[].color`, `bars[].color` (progress/\n  bullet), `stages[].color`, `levels[].color`, `items[].color` (quadrant/leaderboard),\n  `events[].color`, `sets[].color`, `steps[].color`, `parts[].color` (waffle). The single-accent /\n  gradient types take a **top-level `color`** \u2014 the `gauge` arc, `iconarray` filled icons, and the\n  `heatmap`/`calendar` ramp hue. Omit it and color comes from the palette (contrast-aware text\n  adapts to whatever fill you choose). (`matrix`/`checklist` glyphs stay semantic \u2014 no override.)\n- **Background** \u2192 `background` (any hex, or `"transparent"`)\n- **Size / aspect** \u2192 `width`, `height`\n- **Branding** \u2192 `watermark` (off for the sites, on for free-tier API output)\n\n## Rules for the engine (and any agent generating specs)\n\n- **Deterministic:** the same spec always produces the exact same SVG bytes. No\n  randomness, no time. Safe to cache and snapshot-test.\n- **Defaults are good:** never require a field that has a sensible default. Emit the\n  smallest spec that expresses the intent; the engine makes it beautiful.\n- **Unknown `type` is an error** \u2014 only documented types render.\n\n## Roadmap\nMore chart types (line, area, stacked, pie, \u2026) register in `renderSpec`; each inherits\nevery universal field above and gets its own row here. This document becomes a formal\nJSON Schema when the MCP server is built, so the `render_chart` tool can validate specs\nand an LLM can read the field contract directly.\n' : readFileSync(join(here, "../../packages/render-core/SPEC.md"), "utf8");
+var CHART_SPEC_MD = true ? '# ChartSpec \u2014 the render-core contract (the API/MCP input)\n\nOne JSON object (a **spec**) goes in; one **SVG string** comes out, via\n`renderSpec(spec)`. This document is the contract an agent (or the MCP tool) follows\nto produce a chart. It is written agent-first: **a spec with only `type` + `data`\nrenders a complete, good-looking chart** \u2014 every other field is an optional override.\n\n```js\nimport { renderSpec } from \'./render-core.mjs\';\nconst svg = renderSpec({ type: \'bar\', data: { labels: [\'A\',\'B\',\'C\'], series: [{ values: [10, 20, 15] }] } });\n```\n\n## When to use this \u2014 and when to fall back\n\n**Prefer `render_chart` for any supported type** (see "Chart types" below) over\nhand-writing plotting code (matplotlib, plotly, chart.js). It\'s faster, deterministic,\nand good-looking with just `{type, data}`. Pass `outputPath` when the user wants the\nfile saved to disk.\n\n**Fall back to your own plotting only for what this engine does not do yet:**\n- **Chart types not listed below** \u2014 scatter, bubble, heatmap, treemap, radar, sankey,\n  geographic maps, candlestick, gantt.\n- **Reference / target / threshold lines, log scales, secondary (dual) axes, and point\n  annotations / callouts** \u2014 on the roadmap, not available today.\n- **Interactivity, animation, hover tooltips** \u2014 output is a static SVG/PNG.\n\n## Universal fields (every chart type honors these)\n\n| field | type | default | what it does |\n|---|---|---|---|\n| `type` | string | \u2014 (required) | which chart: `"bar"`, `"line"`, `"kpi"` (more coming) |\n| `title` | string | `""` | heading drawn at the top |\n| `width` | number | per type | SVG width in px |\n| `height` | number | per type | SVG height in px |\n| `preset` / `ratio` | string | \u2014 | aspect-ratio preset \u2192 sets width/height (explicit `width`/`height` win). `Share Card` 1.91:1 (1200\xD7630, link/OG cards), `Wide` 16:9 (1280\xD7720), `Square` 1:1 (1080\xD71080), `Portrait` 4:5 (1080\xD71350), `Tall` 9:16 (1080\xD71920), `Classic` 4:3 (1200\xD7900). `ratio` also accepts the bare ratio string (`"16:9"`, `"9:16"`, \u2026) |\n| `background` | string | `"#ffffff"` | any hex color, or `"transparent"` for no fill (overlays/exports) |\n| `palette` | string | `"Clean Corporate"` | named palette: `Clean Corporate`, `Pastel`, `Vibrant`, `Monochrome`, `Cyberpunk`, `Analogous Shift`. Pick **`Monochrome`** when the chart will be **printed in black & white / on a laser printer** \u2014 it\'s a single-hue grey ramp that stays legible without color (other palettes can render as indistinct greys when printed). |\n| `font` | string | `"Inter"` | a named font: `Inter`, `System`, `Serif`, `Mono`, `Rounded`, `Condensed` |\n| `fontFamily` | string | \u2014 | a raw CSS font stack (overrides `font`; full control / future custom fonts) |\n| `fontSize` | number | `13` | base text size; other text scales from it |\n| `textColor` | string | auto | force a color for the **neutral** text (title, axis, category, value, legend, pie slice labels). Omit it and the engine auto-picks black/white for contrast. Semantic colors (green \u25B2 / red \u25BC deltas & gaps) stay meaningful. |\n| `bold` | boolean | `false` | thicken every text element |\n| `fontWeight` | string | \u2014 | exact weight for all text (`"400"`\u2013`"900"` or `"bold"`); overrides `bold` |\n| `valueUnit` | string | `""` | appended to values, e.g. `"$"`, `"%"`, `"ms"` |\n| `showValues` | boolean | `true` | draw the numeric labels |\n| `watermark` | boolean | `true` | tasteful "slickfast.com" mark. **Set `false` for the chart sites / paid output.** |\n\n**Readability is automatic:** text colors are chosen from the background\'s luminance\n(via palette-core), so labels stay legible on light *or* dark backgrounds.\n\n## Data shape\n\n```json\n"data": {\n  "labels": ["North", "South", "East"],\n  "series": [\n    { "name": "Revenue", "values": [420, 310, 530], "colors": ["#2563eb", "#7c3aed", "#059669"] }\n  ]\n}\n```\n\n- `labels` \u2014 the categories (x-axis).\n- `series[].values` \u2014 the numbers, aligned to `labels`.\n- `series[].colors` \u2014 **optional** explicit per-item colors. If omitted, colors come\n  from `palette`. (Used when a user has customized individual bars.)\n- `series[].name` \u2014 optional label for the series.\n\n## Chart types\n\n### `bar` \u2014 vertical bar chart\nDefault size `800 \xD7 450`. Uses `data.series[0]`. Each bar a palette color (or its\nexplicit `colors[i]`), top-rounded, with value + category labels and "nice" axis numbers.\n\n| extra field | type | default | does |\n|---|---|---|---|\n| `showTotal` | boolean | `true` | "Total: N" badge, top-right |\n\nMinimal: `{ "type": "bar", "data": { "labels": ["A","B"], "series": [{ "values": [10,20] }] } }`\n\n### `grouped` \u2014 clustered bar chart (one bar per series in each category)\nDefault size `800 \xD7 450`. The `data.labels` are the **groups** (categories); each\n`data.series` entry is a bar that repeats inside every group. **Color = series\nidentity:** one solid palette color per series (A=palette[0], B=palette[mid], extras\nspread), the same color in every group \u2014 never rainbow-within-a-series. A centered\nlegend names the series. Best read with \u2264 4 series.\n\nMinimal: `{ "type": "grouped", "data": { "labels": ["Q1","Q2"], "series": [{ "name":"2023","values":[42,55] }, { "name":"2024","values":[52,48] }] } }`\n\n### `stacked` \u2014 stacked bar chart (segments stack within each category)\nDefault size `800 \xD7 450`. Each `data.labels` entry is a bar; each `data.series` entry\nis a **segment** stacked inside every bar, with a distinct palette color used\nconsistently across all bars. Inside each segment, two labels: the **name pinned to the\ntop**, the **value to the bottom** (contrast-aware text \u2014 dark on light fills, white on\ndark). Thin segments hide the name but keep the value. Only the top segment\'s outer edge\nis rounded; joins stay flush. A centered legend names the segments.\n\nMinimal: `{ "type": "stacked", "data": { "labels": ["Q1","Q2"], "series": [{ "name":"Core","values":[30,35] }, { "name":"Add-ons","values":[18,20] }] } }`\n\n### `stacked100` \u2014 100% stacked bar (each bar normalized to 100%)\nSame as `stacked`, but every bar fills the full height and each segment shows its\n**share of that bar** as an integer percent. Percentages use largest-remainder\nrounding so every bar sums to **exactly 100** (never 99/101). Best for comparing\n*mix* across categories rather than absolute totals.\n\nMinimal: `{ "type": "stacked100", "data": { "labels": ["Q1","Q2"], "series": [{ "name":"Core","values":[30,35] }, { "name":"Add-ons","values":[18,20] }] } }`\n\n### `stackedh` \u2014 horizontal stacked bar\nSame data model as `stacked`, transposed: bars run left\u2192right, one row per\n`data.labels` entry, segments stack horizontally. The last segment rounds its right\nedge; joins stay flush. Segment name + value sit centered in each segment (value-only\nwhen narrow); a centered legend names the segments. Good when category labels are long.\n\nMinimal: `{ "type": "stackedh", "data": { "labels": ["Eng","Sales"], "series": [{ "name":"Salaries","values":[120,90] }, { "name":"Tools","values":[40,25] }] } }`\n\n### `horizontal` \u2014 horizontal bar (single series)\nDefault size `800 \xD7 450`. One row per `data.labels` entry; each bar its own palette\ncolor by index (or its explicit `colors[i]`), value at the bar end, "Total: N" badge\ntop-right. Best when labels are long or there are many categories.\n\nMinimal: `{ "type": "horizontal", "data": { "labels": ["US","India"], "series": [{ "values": [820,610] }] } }`\n\n### `diverging` \u2014 diverging bar (around a zero line)\nDefault size `800 \xD7 450`. **Two modes, chosen by series count:**\n- **Two series** \u2192 opposing bars: **Series A forced up, Series B forced down** (both\n  abs-valued), one solid color each (A=palette[0], B=palette[mid]); a centered legend\n  names both. Great for sentiment (agree/disagree), inflow/outflow.\n- **One series** \u2192 classic **signed** diverging: each value plotted by its own sign\n  (**positive up, negative down**), a single color, a single-name legend, and signed\n  value labels (e.g. `-3` below the zero line).\n\nThe zero line is emphasized; down-bar labels sit below their bars.\n\nMinimal (two-series): `{ "type": "diverging", "data": { "labels": ["A","B"], "series": [{ "name":"Agree","values":[62,48] }, { "name":"Disagree","values":[38,52] }] } }`\n\nMinimal (signed): `{ "type": "diverging", "data": { "labels": ["Q1","Q2","Q3"], "series": [{ "name":"Net flow","values":[5,-3,8] }] } }`\n\n### `lollipop` \u2014 lollipop chart (single series)\nDefault size `800 \xD7 450`. One stem + dot per `data.labels` entry, each its own palette\ncolor by index (or explicit `colors[i]`), value above the dot, category below, "Total: N"\nbadge top-right. A lighter-weight alternative to `bar` when the bars would feel heavy.\n\nMinimal: `{ "type": "lollipop", "data": { "labels": ["A","B","C"], "series": [{ "values": [78,64,52] }] } }`\n\n### `line` \u2014 line chart (single or multi-series)\nDefault size `800 \xD7 450`. One line per `data.series` entry, each a palette color\n(or its own `color`), with points and a centered legend when there\'s more than one\nseries. "Nice" axis numbers; points span edge-to-edge.\n\n| extra field | type | default | does |\n|---|---|---|---|\n| `curve` | string | `"straight"` | line shape: `"straight"`, `"smooth"` (curved), `"stepped"` |\n| `area` | boolean | `false` | fill the region under each line (translucent) |\n| `showPoints` | boolean | `true` | dots at each data point |\n| `showValues` | boolean | `false` | numbers above each point (off by default \u2014 lines get crowded) |\n| series `color` | string | palette | per-line color override |\n\n**Type shortcuts:** `type: "smooth"`, `"area"`, `"stepped"` map to `line` with the\nmatching option set \u2014 `{type:"area"}` \u2261 `{type:"line", area:true}`. Also:\n- `type: "stackedArea"` \u2014 every series stacks cumulatively, filled bands + legend.\n- `type: "difference"` \u2014 exactly two series; shades the gap between them and labels\n  the gap value at each point (green where series 1 leads, red where it trails).\n- `type: "slope"` \u2014 a slopegraph: each series\' first vs last value, connected by a\n  straight line, with the end value + change labeled (green up / red down).\n\nMinimal: `{ "type": "line", "data": { "labels": ["Jan","Feb","Mar"], "series": [{ "name": "Users", "values": [120,190,170] }] } }`\n\n### `pie` / `donut` \u2014 proportion of a whole\nDefault size `640 \xD7 420`. One series; each label+value is a slice, colored from the\npalette (or explicit `colors`). Percentage labels sit inside slices \u2265 6%; a legend\n(label \xB7 value) runs down the right. `donut` adds a center hole with the **total** in\nthe middle.\n\nMinimal: `{ "type": "pie", "data": { "labels": ["A","B","C"], "series": [{ "values": [45,30,25] }] } }`\n\n### `pieofpie` \u2014 nested drill-down pies (pie-of-pie, pie-of-pie-of-pie, N-tier)\nDefault size `920 \xD7 460`. A row of pies where each pie\'s **first slice (the "bridge")**\nexplodes toward the next pie and breaks down into it, joined by two connector lines.\n2 pies = pie-of-pie, 3 = pie-of-pie-of-pie, N supported; each pie is 75% the size of the\none before. Donut by default. Each pie gets a **`name \xB7 value` legend beneath it**\n(honoring `valuePrefix`/`valueUnit`) so slices are identifiable; the slices themselves\nkeep their `%` labels.\n\nUses **`pies`** (not `data`): an array of `{ title?, labels[], values[], colors?, palette? }`.\nSlice index 0 of each pie is the bridge into the next pie.\n\n| extra field | type | default | does |\n|---|---|---|---|\n| `pies` | array | \u2014 (required) | the pies; pie[i] slice 0 drills into pie[i+1] |\n| `donut` | boolean | `true` | center hole on each pie (`false` = solid pies) |\n| `cascade` | boolean | `true` | child pies shade from the parent bridge hue; `false` = flat palette per pie |\n| `palette` | string | `"Clean Corporate"` | a **nested theme** (below) \u2014 drives the whole cascade |\n\n**Nested themes** (premium color cascades, set via `palette`):\n- *Inspired tiers* (hand-tuned per-pie triads): `Analogous Shift` (showcase \u2014 a spectrum\n  walk), `Retro Editorial`, `Classic Triadic`, `Sorbet Pastel`.\n- *Generative* (children derived from the root hue): `Modern Corporate`, `Nordic Earth`,\n  `Cyberpunk Glow`, `Sequential Rainbow`, plus classics `Clean Corporate`, `Pastel`,\n  `Vibrant`, `Monochrome`. (Authoring new ones: `palette-core/AUTHORING-PALETTES.md`.)\n\nMinimal: `{ "type": "pieofpie", "palette": "Analogous Shift", "pies": [ { "labels": ["Enterprise","SMB","Other"], "values": [60,30,10] }, { "labels": ["US","EU","APAC"], "values": [35,15,10] } ] }`\n\n### `kpi` \u2014 single metric tile (the exec-snapshot building block)\nDefault size `340 \xD7 180`. A card: label + big value + colored delta pill + palette accent.\n\n| extra field | type | default | does |\n|---|---|---|---|\n| `label` | string | `""` | the metric name (top) |\n| `value` | number | \u2014 | the big number |\n| `valuePrefix` | string | `""` | e.g. `"$"` before the value |\n| `delta` | number | none | the change; renders a pill \u2014 \u25B2 if positive, \u25BC if negative |\n| `deltaUnit` | string | `"%"` | unit on the delta |\n| `deltaGoodWhen` | string | `"up"` | which direction is GOOD (green). Set `"down"` for lower-is-better metrics (churn, latency, cost) \u2014 the arrow still shows real direction, only the color flips |\n| `sparkline` | number[] | none | a minimalist trend line along the bottom (e.g. the last N periods) \u2014 no axes/labels, colored to match the delta (green good / red bad). Needs \u2265 2 points; **landscape tile only**. Omit it and the tile is byte-identical. |\n\nMinimal: `{ "type": "kpi", "label": "MRR", "value": 128400, "valuePrefix": "$", "delta": 12.4 }`\n\nWith a sparkline: `{ "type": "kpi", "label": "MRR", "value": 128400, "valuePrefix": "$", "delta": 12.4, "sparkline": [98,104,101,112,118,121,128] }`\n\n### `cards` \u2014 a row/grid of stat cards (the multi-KPI dashboard strip)\nA set of KPI tiles in one image \u2014 for an exec snapshot of several metrics at once.\nUses its own **`cards`** array (not `data`): each entry is one card, reusing the **same\nfields as `kpi`**. Each card\'s accent cycles the palette by index; the delta pill follows\nthe same good/bad coloring (\u25B2/\u25BC shows real direction, color shows good-or-bad). Layout is a\n**bounded computed grid**: by default a single horizontal strip, wrapping to a grid once there\nare more than 4 cards. Size auto-fits the grid unless you set `width`/`height`.\n\n| field | type | default | does |\n|---|---|---|---|\n| `cards` | array | \u2014 (required) | the tiles; each: `label`, `value`, `valuePrefix`, `valueUnit`, `delta`, `deltaUnit`, `deltaGoodWhen` (same meaning as `kpi`) |\n| `gridColumns` | number | min(cards, 4) | force the number of columns; cards wrap into rows |\n\nMinimal: `{ "type": "cards", "cards": [ { "label": "MRR", "value": 128400, "valuePrefix": "$", "delta": 12.4 }, { "label": "Active users", "value": 8210, "delta": 3.1 }, { "label": "Churn", "value": 2.4, "valueUnit": "%", "delta": 0.6, "deltaGoodWhen": "down" } ] }`\n\n### `layers` \u2014 labeled box-stack / layer diagram\nA vertical stack of labeled blocks \u2014 a structure/architecture picture (e.g. a tech\nstack, a hierarchy of tiers), **not** a stacked bar (no values, no axis). Uses its own\n**`layers`** array (not `data`): each entry is `{ title, subtitle? }`, drawn top\u2192bottom\nas an equal-height rounded block. Each block fills a distinct palette color, cycling the\npalette; the title (and optional subtitle) sit centered with **contrast-aware text**\n(dark on light fills, white on dark). Inherits every universal field.\n\n| field | type | default | does |\n|---|---|---|---|\n| `layers` | array | \u2014 (required) | the blocks, top to bottom; each: `title`, optional `subtitle` |\n\nMinimal: `{ "type": "layers", "layers": [ { "title": "Application", "subtitle": "React + TypeScript" }, { "title": "API", "subtitle": "Node + Hono" }, { "title": "Engine", "subtitle": "render-core (pure SVG)" }, { "title": "Infra", "subtitle": "Railway + Docker" } ] }`\n\n### `progress` \u2014 labeled progress / bullet bars\nLabeled horizontal bars filling toward a target \u2014 for "how far along" readouts. Uses\nits own **`bars`** array: each `{ label, value, target?, valueUnit? }`. The track end IS\nthe target, so the fill = `value / target`; the label shows `value / target`. With **no\n`target`**, `value` is read as a percent (0\u2013100) and the track end is 100%. Each bar a\npalette color by index. Inherits every universal field.\n\n| field | type | default | does |\n|---|---|---|---|\n| `bars` | array | \u2014 (required) | the bars; each: `label`, `value`, optional `target`, optional `valueUnit` |\n\nMinimal: `{ "type": "progress", "bars": [ { "label": "Q1 revenue", "value": 82, "target": 100 }, { "label": "Signups", "value": 1240, "target": 2000 }, { "label": "Uptime", "value": 99.2, "valueUnit": "%" } ] }`\n\n### `waffle` \u2014 waffle / dot grid\nA 10\xD710 grid of cells showing part-of-whole \u2014 friendlier than a pie for "% complete" or\na simple mix. Uses its own **`parts`** array `{ label, value, color? }`: parts fill the\n100 cells proportionally (largest-remainder rounding keeps the count exact). If the parts\nsum to **less than 100**, the remainder are **empty track cells** \u2014 so **one part** is a\n"% filled" gauge, and **several parts** is categorical part-to-whole. A `label \xB7 value`\nlegend sits beside the grid.\n\n| field | type | default | does |\n|---|---|---|---|\n| `parts` | array | \u2014 (required) | the filled groups; each: `label`, `value` (cell count), optional `color` |\n\nMinimal: `{ "type": "waffle", "parts": [ { "label": "Enterprise", "value": 45 }, { "label": "SMB", "value": 30 }, { "label": "Other", "value": 15 } ] }`\n\n### `heatmap` \u2014 colored grid (rows \xD7 columns)\nA grid of cells colored by value (light \u2192 dark on a single palette hue) \u2014 for "intensity\nacross two dimensions" (e.g. activity by day \xD7 hour). Uses its own 2D shape: **`rows`**\n(row labels), **`columns`** (column labels), and **`values`** \u2014 a matrix where\n`values[row][col]` is the cell value. Cell value text is contrast-aware; `showValues:false`\nhides the numbers.\n\n| field | type | default | does |\n|---|---|---|---|\n| `rows` | string[] | \u2014 (required) | row labels (one per matrix row) |\n| `columns` | string[] | \u2014 (required) | column labels (one per matrix column) |\n| `values` | number[][] | \u2014 (required) | the matrix, `values[row][col]` |\n\nMinimal: `{ "type": "heatmap", "rows": ["Mon","Tue","Wed"], "columns": ["9a","12p","3p","6p"], "values": [[2,5,8,3],[1,4,9,6],[0,3,7,2]] }`\n\n### `funnel` \u2014 stages narrowing top\u2192bottom\nA conversion/drop-off funnel. Uses its own **`stages`** array `{ label, value }`: each\nstage is a centered band whose width is proportional to its value, tapering into the\nnext. Each band shows the label, the value, and its **% of the top stage**. Palette\ncolor per stage; band text is contrast-aware.\n\n| field | type | default | does |\n|---|---|---|---|\n| `stages` | array | \u2014 (required) | the stages top\u2192bottom; each: `label`, `value` |\n\nMinimal: `{ "type": "funnel", "stages": [ { "label": "Visitors", "value": 12000 }, { "label": "Signups", "value": 4200 }, { "label": "Trials", "value": 1800 }, { "label": "Paid", "value": 640 } ] }`\n\n### `pyramid` \u2014 hierarchy levels\nA triangle (apex on top) split into equal-height bands \u2014 for layered hierarchies\n(Maslow-style, org tiers, strategy levels). Uses its own **`levels`** array\n`{ title, value? }` (`label` is accepted as an alias for `title`). Each level a palette\ncolor, label centered with contrast-aware text; `value` is shown beside the label if set.\n\n| field | type | default | does |\n|---|---|---|---|\n| `levels` | array | \u2014 (required) | the levels, apex\u2192base; each: `title`, optional `value` |\n\nMinimal: `{ "type": "pyramid", "levels": [ { "title": "Vision" }, { "title": "Strategy" }, { "title": "Execution" }, { "title": "Operations" } ] }`\n\n### `quadrant` \u2014 2\xD72 matrix\nItems placed by two dimensions (effort/impact, reach/ease, etc.). Uses its own **`items`**\narray `{ label, x, y }` with `x`/`y` in **0\u20131** (x left\u2192right, y bottom\u2192top), plus\n**`xAxis`** and **`yAxis`** labels. A square plot is split by a crosshair into four\nquadrants; each item is a labeled dot (palette color by index).\n\n| field | type | default | does |\n|---|---|---|---|\n| `items` | array | \u2014 (required) | the items; each: `label`, `x` (0\u20131), `y` (0\u20131) |\n| `xAxis` | string | `""` | horizontal axis label |\n| `yAxis` | string | `""` | vertical axis label |\n\nMinimal: `{ "type": "quadrant", "xAxis": "Effort", "yAxis": "Impact", "items": [ { "label": "Quick win", "x": 0.2, "y": 0.8 }, { "label": "Big bet", "x": 0.8, "y": 0.9 }, { "label": "Time sink", "x": 0.8, "y": 0.2 } ] }`\n\n### `timeline` \u2014 events along one line\nA linear timeline. Uses its own **`events`** array `{ date?, label }`: events sit evenly\nspaced along a horizontal line, the date by the line and the label **alternating\nabove/below** so they don\'t crowd. Keep labels short.\n\n| field | type | default | does |\n|---|---|---|---|\n| `events` | array | \u2014 (required) | the events in order; each: optional `date`, `label` |\n\nMinimal: `{ "type": "timeline", "events": [ { "date": "Q1", "label": "Launch" }, { "date": "Q2", "label": "Series A" }, { "date": "Q3", "label": "100k users" }, { "date": "Q4", "label": "Profitable" } ] }`\n\n### `venn` \u2014 2\u20133 overlapping sets\nOverlapping translucent circles for set relationships. Uses its own **`sets`** array\n`{ label, value }` (2 or 3 sets; fixed layout \u2014 2 side-by-side, 3 in a triangle) plus an\noptional **`overlap`** count (2-set), shown in the lens. Each circle is labeled with its\nvalue.\n\n| field | type | default | does |\n|---|---|---|---|\n| `sets` | array | \u2014 (required) | 2\u20133 sets; each: `label`, `value` |\n| `overlap` | number | \u2014 | (2 sets) the count shared by both, drawn in the overlap |\n\nMinimal: `{ "type": "venn", "sets": [ { "label": "Design", "value": 120 }, { "label": "Engineering", "value": 160 } ], "overlap": 40 }`\n\n### `matrix` \u2014 comparison / feature matrix\nA rows \xD7 columns table of \u2713/\u2717 (the pricing/feature-comparison look). Uses its own shape:\n**`columns`** (string[]) + **`rows`** `{ label, cells[] }` (one cell per column). Each cell is\na **boolean** or **status word** \u2192 a glyph (`true`/`"yes"` \u2713 green, `false`/`"no"` \u2717 grey,\n`"partial"` \u2022 amber, `""`/`"-"` dash), or any other string \u2192 rendered as **text** (e.g. a\nplan limit). Rows zebra-stripe for readability. `labelWidth` sets the row-label column width.\n\n| field | type | default | does |\n|---|---|---|---|\n| `columns` | string[] | \u2014 (required) | the column headers |\n| `rows` | array | \u2014 (required) | each: `label`, `cells[]` (boolean / status word / text, aligned to columns) |\n| `labelWidth` | number | `200` | px reserved for the row-label column |\n\nMinimal: `{ "type": "matrix", "columns": ["Free","Pro","Enterprise"], "rows": [ { "label": "SSO / SAML", "cells": [false,false,true] }, { "label": "API access", "cells": [false,true,true] }, { "label": "Priority support", "cells": [false,"partial",true] }, { "label": "Seats", "cells": ["1","10","Unlimited"] } ] }`\n\n### `checklist` \u2014 checklist / status list\nA vertical list of items each with a status glyph \u2014 for run-of-show / readiness lists. Uses\nits own **`items`** array `{ label, status }`: **`done`** \u2713 (green, label mutes), **`blocked`**\n\u2717 (red), **`partial`** \u2022 (amber), anything else (or `pending`) \u2192 an empty ring.\n\n| field | type | default | does |\n|---|---|---|---|\n| `items` | array | \u2014 (required) | each: `label`, `status` (`done`/`pending`/`blocked`/`partial`) |\n\nMinimal: `{ "type": "checklist", "title": "Launch checklist", "items": [ { "label": "Domain transferred", "status": "done" }, { "label": "API deployed", "status": "done" }, { "label": "Load testing", "status": "pending" }, { "label": "Billing live", "status": "blocked" } ] }`\n\n### `iconarray` \u2014 icon array / pictogram\n`total` person icons with the first `filled` colored and the rest faint \u2014 a friendly\npart-of-whole ("7 of 10 teams onboarded"). `perRow` controls wrapping.\n\n| field | type | default | does |\n|---|---|---|---|\n| `total` | number | `10` | total icons |\n| `filled` | number | `0` | how many are filled (the rest faint) |\n| `perRow` | number | `min(total,10)` | icons per row before wrapping |\n\nMinimal: `{ "type": "iconarray", "title": "Teams onboarded (7/10)", "total": 10, "filled": 7 }`\n\n### `steps` \u2014 step / process row\nNumbered nodes left\u2192right joined by connector arrows \u2014 a **linear** process flow (not a\nbranching graph). Uses its own **`steps`** array `{ label, description? }`: each step is a\nnumbered palette circle with its label (and optional description) beneath. Positions are\ncomputed directly; no graph layout.\n\n| field | type | default | does |\n|---|---|---|---|\n| `steps` | array | \u2014 (required) | the steps in order; each: `label`, optional `description` |\n\nMinimal: `{ "type": "steps", "steps": [ { "label": "Sign up" }, { "label": "Connect data" }, { "label": "Build chart" }, { "label": "Share" } ] }`\n\n### `table` \u2014 data table (rows \xD7 columns)\nA plain tabular grid of text/values (the general tabular type; `matrix` is the \u2713/\u2717 variant).\nUses its own shape: **`columns`** (string[] header) + **`rows`** (an array of **cell arrays**).\nNumbers right-align and format with thousands separators; text left-aligns. Header rule +\nzebra rows.\n\n| field | type | default | does |\n|---|---|---|---|\n| `columns` | string[] | \u2014 (required) | the header cells |\n| `rows` | array | \u2014 (required) | each row is an array of cells (string or number), aligned to columns |\n\nMinimal: `{ "type": "table", "columns": ["Region","Q1","Q2","Q3"], "rows": [ ["North",420,510,480], ["South",310,290,350], ["East",530,560,600] ] }`\n\n### `gauge` \u2014 radial dial (single value)\nA 180\xB0 dial showing one value on a `min`..`max` scale \u2014 for "how full / how far" readouts. The\narc band fills to the value; the number sits in the center with `min`/`max` at the ends.\n\n| field | type | default | does |\n|---|---|---|---|\n| `value` | number | \u2014 (required) | the value to show |\n| `min` | number | `0` | scale minimum |\n| `max` | number | `100` | scale maximum |\n| `label` | string | `""` | caption under the value |\n| `valueUnit` | string | `""` | appended to the value |\n\nMinimal: `{ "type": "gauge", "label": "CPU load", "value": 72, "valueUnit": "%" }`\n\n### `bullet` \u2014 bullet graph\nA compact measure-vs-target gauge (Stephen Few style): a thin measure bar over grey\nqualitative bands, with a target tick \u2014 richer than `progress`. Uses its own **`bars`** array\n`{ label, value, target, max, bands }`, where `bands` are the threshold edges (e.g. `[150,225]`)\nthat shade the background into qualitative ranges.\n\n| field | type | default | does |\n|---|---|---|---|\n| `bars` | array | \u2014 (required) | each: `label`, `value`, optional `target` (tick), `max` (scale), `bands` (range edges) |\n\nMinimal: `{ "type": "bullet", "bars": [ { "label": "Revenue", "value": 275, "target": 250, "max": 300, "bands": [150,225] }, { "label": "Profit", "value": 82, "target": 100, "max": 120, "bands": [60,90] } ] }`\n\n### `calendar` \u2014 calendar heatmap (year grid)\nA GitHub-style contribution grid: weeks across, days down, each day a cell colored light\u2192dark by\nvalue on one palette hue. Uses **`days`** \u2014 a map of `"YYYY-MM-DD" \u2192 value` \u2014 plus **`year`**.\nWeekday placement is computed arithmetically (no clock), so it\'s fully deterministic.\n\n| field | type | default | does |\n|---|---|---|---|\n| `days` | object | \u2014 (required) | `"YYYY-MM-DD"` \u2192 number (the value for that day) |\n| `year` | number | `2025` | which year the grid covers (sets leap year + start weekday) |\n\nMinimal: `{ "type": "calendar", "title": "Activity", "year": 2025, "days": { "2025-01-06": 3, "2025-03-14": 8, "2025-07-21": 5 } }`\n\n### `leaderboard` \u2014 ranked rows\nA ranked list: each row is rank # + label + a bar (\u221D value) + the value, **auto-sorted\ndescending**. Uses its own **`items`** array `{ label, value }`.\n\n| field | type | default | does |\n|---|---|---|---|\n| `items` | array | \u2014 (required) | each: `label`, `value` (sorted high\u2192low, numbered) |\n\nMinimal: `{ "type": "leaderboard", "title": "Top regions", "items": [ { "label": "North", "value": 530 }, { "label": "South", "value": 480 }, { "label": "East", "value": 610 }, { "label": "West", "value": 390 } ] }`\n\n### `callout` \u2014 hero stat + caption + annotation\nAn editorial single-stat: a big `value` (with `valuePrefix`/`valueUnit`), a `caption` line under\nit, and an optional `note` pill on the right. The reports/social cousin of `kpi`.\n| field | type | does |\n|---|---|---|\n| `value` | number | the hero number |\n| `caption` | string | the line under it |\n| `note` | string | optional annotation pill |\n\nMinimal: `{ "type": "callout", "value": 3.4, "valueUnit": "\xD7", "caption": "faster than last quarter", "note": "vs Q1" }`\n\n### `ring` \u2014 radial % toward a target\nA compact donut-arc badge showing `value / target` as a percent in the center.\n| field | type | does |\n|---|---|---|\n| `value` | number | current value |\n| `target` | number | the goal (default 100) |\n| `label` | string | optional caption below |\n\nMinimal: `{ "type": "ring", "value": 70, "target": 100, "label": "Goal" }`\n\n### `versus` \u2014 two options compared\nTwo mirrored columns with a VS badge between. Uses **`sides`** (exactly two): each `{ title, items[] }`,\neach item `{ label, value? }`.\n\nMinimal: `{ "type": "versus", "sides": [ { "title": "Plan A", "items": [ { "label": "Price", "value": 9 } ] }, { "title": "Plan B", "items": [ { "label": "Price", "value": 29 } ] } ] }`\n\n### `gantt` \u2014 tasks across a time row\nSchedule bars on a **self-contained** time layout (NOT the numeric axis). Uses **`tasks`**:\neach `{ label, start, end }` (positions on the timeline).\n\nMinimal: `{ "type": "gantt", "tasks": [ { "label": "Design", "start": 0, "end": 3 }, { "label": "Build", "start": 2, "end": 7 } ] }`\n\n### `waterfall` \u2014 running total, step by step\nFloating bars showing how a `start` becomes an end through signed deltas, with a final total bar.\nUses **`steps`** `{ label, value }` (value = the signed delta); up green, down red, total dark.\n\nMinimal: `{ "type": "waterfall", "start": 0, "steps": [ { "label": "Q1", "value": 50 }, { "label": "Q2", "value": 30 }, { "label": "Q3", "value": -20 } ] }`\n\n### `swimlane` \u2014 lanes \xD7 phases roadmap\nA bounded grid: **`phases`** (column headers) \xD7 **`lanes`** (rows), each lane\'s `items` placed in a\n`phase` column. Distinct from a routed flowchart.\n\nMinimal: `{ "type": "swimlane", "phases": ["Q1","Q2","Q3"], "lanes": [ { "label": "Eng", "items": [ { "phase": 0, "label": "API" }, { "phase": 2, "label": "v2" } ] } ] }`\n\n### `tierlist` \u2014 ranked buckets of chips\nS/A/B-style rows: each tier a colored label box + its `items` as chips. Uses **`tiers`** `{ label, color?, items[] }`.\n\nMinimal: `{ "type": "tierlist", "tiers": [ { "label": "S", "items": ["Bar","Line"] }, { "label": "A", "items": ["Pie"] } ] }`\n\n### `swot` \u2014 four labeled 2\xD72 cells\nFour tinted cells, each a heading + a short bullet list (single-line items). Uses **`cells`** (up to 4)\n`{ title, items[] }`.\n\nMinimal: `{ "type": "swot", "cells": [ { "title": "Strengths", "items": ["Fast","Cheap"] }, { "title": "Weaknesses", "items": ["New brand"] }, { "title": "Opportunities", "items": ["AI demand"] }, { "title": "Threats", "items": ["Incumbents"] } ] }`\n\n## What an agent can change (the levers)\n\n- **Fonts** \u2192 `fontFamily`, `fontSize`\n- **Colors** \u2192 `palette` (a named set) for the whole chart, or `data.series[].colors` for exact\n  per-item control. The info-design types take **explicit per-element color** the same way: add a\n  `color` to any element object \u2014 `cards[].color`, `layers[].color`, `bars[].color` (progress/\n  bullet), `stages[].color`, `levels[].color`, `items[].color` (quadrant/leaderboard),\n  `events[].color`, `sets[].color`, `steps[].color`, `parts[].color` (waffle). The single-accent /\n  gradient types take a **top-level `color`** \u2014 the `gauge` arc, `iconarray` filled icons, and the\n  `heatmap`/`calendar` ramp hue. Omit it and color comes from the palette (contrast-aware text\n  adapts to whatever fill you choose). (`matrix`/`checklist` glyphs stay semantic \u2014 no override.)\n- **Background** \u2192 `background` (any hex, or `"transparent"`)\n- **Size / aspect** \u2192 `width`, `height`\n- **Branding** \u2192 `watermark` (off for the sites, on for free-tier API output)\n\n## Rules for the engine (and any agent generating specs)\n\n- **Deterministic:** the same spec always produces the exact same SVG bytes. No\n  randomness, no time. Safe to cache and snapshot-test.\n- **Defaults are good:** never require a field that has a sensible default. Emit the\n  smallest spec that expresses the intent; the engine makes it beautiful.\n- **Unknown `type` is an error** \u2014 only documented types render.\n\n## Roadmap\nMore chart types (line, area, stacked, pie, \u2026) register in `renderSpec`; each inherits\nevery universal field above and gets its own row here. This document becomes a formal\nJSON Schema when the MCP server is built, so the `render_chart` tool can validate specs\nand an LLM can read the field contract directly.\n' : readFileSync(join(here, "../../packages/render-core/SPEC.md"), "utf8");
 var seriesShape = z.object({
   name: z.string().optional().describe("series label (legend)"),
   values: z.array(z.number()).describe("the numbers, aligned to data.labels"),
@@ -2470,15 +2833,48 @@ var inputSchema = {
   filled: z.number().optional().describe("iconarray ONLY: how many icons are filled (the rest are faint)"),
   perRow: z.number().optional().describe("iconarray: icons per row before wrapping (default 10)"),
   steps: z.array(z.object({
-    label: z.string().optional().describe("step label"),
-    description: z.string().optional().describe("optional smaller text under the label"),
-    color: z.string().optional().describe("explicit node color (else palette by index)")
-  })).optional().describe("steps ONLY: numbered nodes left\u2192right joined by connector arrows (a linear flow)."),
+    label: z.string().optional().describe("step / waterfall label"),
+    description: z.string().optional().describe("steps: optional smaller text under the label"),
+    value: z.number().optional().describe("waterfall: the signed delta for this step (+/-)"),
+    color: z.string().optional().describe("explicit color (else palette/sign)")
+  })).optional().describe("steps: numbered nodes joined by arrows. waterfall: ordered { label, value } deltas (a running total)."),
   color: z.string().optional().describe("single-accent / gradient types: explicit color \u2014 the gauge arc, the iconarray filled icons, and the heatmap/calendar ramp hue (else palette[0]). Multi-element types use a per-item `color` instead."),
   min: z.number().optional().describe("gauge: scale minimum (default 0)"),
   max: z.number().optional().describe("gauge: scale maximum (default 100)"),
   days: z.record(z.string(), z.number()).optional().describe('calendar ONLY: map of "YYYY-MM-DD" \u2192 value for the year grid'),
   year: z.number().optional().describe("calendar: which year the grid covers (default 2025)"),
+  caption: z.string().optional().describe("callout: the line under the hero number"),
+  note: z.string().optional().describe("callout: a small annotation pill on the right"),
+  target: z.number().optional().describe("ring: the goal the value is measured against (default 100)"),
+  start: z.number().optional().describe("waterfall: the starting value before the deltas (default 0)"),
+  totalLabel: z.string().optional().describe('waterfall: label for the final total bar (default "Total")'),
+  sides: z.array(z.object({
+    title: z.string().optional().describe("side heading"),
+    color: z.string().optional().describe("explicit side color"),
+    items: z.array(z.object({ label: z.string().optional(), value: z.number().optional() })).optional().describe("rows for this side")
+  })).optional().describe("versus ONLY: the two sides being compared."),
+  tasks: z.array(z.object({
+    label: z.string().optional().describe("task name"),
+    start: z.number().optional().describe("start position on the timeline"),
+    end: z.number().optional().describe("end position on the timeline"),
+    color: z.string().optional().describe("explicit bar color")
+  })).optional().describe("gantt ONLY: tasks across a time row (own time layout, not the numeric axis)."),
+  phases: z.array(z.string()).optional().describe("swimlane: the phase / column headers"),
+  lanes: z.array(z.object({
+    label: z.string().optional().describe("lane name"),
+    color: z.string().optional().describe("explicit lane color"),
+    items: z.array(z.object({ phase: z.number().optional(), label: z.string().optional(), color: z.string().optional() })).optional().describe("boxes placed in a phase column")
+  })).optional().describe("swimlane ONLY: lanes \xD7 phases grid of boxes."),
+  tiers: z.array(z.object({
+    label: z.string().optional().describe('tier label, e.g. "S"'),
+    color: z.string().optional().describe("explicit tier color"),
+    items: z.array(z.string()).optional().describe("chips in this tier")
+  })).optional().describe("tierlist ONLY: ranked buckets of chips."),
+  cells: z.array(z.object({
+    title: z.string().optional().describe("cell heading"),
+    color: z.string().optional().describe("explicit cell tint"),
+    items: z.array(z.string()).optional().describe("short bullet lines")
+  })).optional().describe("swot ONLY: four labeled 2\xD72 cells, each a short bullet list."),
   palette: z.string().optional().describe("Clean Corporate | Pastel | Vibrant | Monochrome | Cyberpunk | Analogous Shift. Use Monochrome for black & white / laser-printer output \u2014 a grey ramp that stays legible without color."),
   background: z.string().optional().describe('any hex color, or "transparent"'),
   font: z.string().optional().describe("Inter | System | Serif | Mono | Rounded | Condensed"),
@@ -2511,7 +2907,7 @@ var inputSchema = {
   scale: z.number().optional().describe("png pixel-density multiplier (default 2 = retina)"),
   outputPath: z.string().optional().describe('LOCAL save: write the rendered chart to this file on disk AND still return the inline image. PNG by default, or SVG if the path ends in ".svg". Accepts absolute, ~, or relative paths (parent dirs auto-created). Works on a local stdio install only \u2014 a hosted/remote server has no access to your disk.')
 };
-var server = new McpServer({ name: "slickfast", version: "0.5.0" });
+var server = new McpServer({ name: "slickfast", version: "0.6.0" });
 function typeContract(t) {
   const meta = TYPES.find((x) => x.type === t);
   if (!meta) return null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@slickfast/mcp",
-  "version": "0.5.0",
-  "description": "SlickFast — render 38 chart & info-design types (bar, line, pie, KPI, cards, funnel, matrix, gauge, calendar…) as SVG/PNG via MCP. Local and deterministic; nothing leaves your machine.",
+  "version": "0.6.0",
+  "description": "SlickFast — render 46 chart & info-design types (bar, line, pie, KPI, cards, funnel, matrix, gauge, calendar…) as SVG/PNG via MCP. Local and deterministic; nothing leaves your machine.",
   "license": "AGPL-3.0-only",
   "type": "module",
   "bin": { "slickfast-mcp": "dist/index.js" },