@slickfast/mcp 0.4.0 → 0.5.0

package/dist/index.js

@@ -1274,7 +1274,8 @@ function renderCards(spec) {
   const cards = Array.isArray(spec.cards) ? spec.cards : [];
   const n = Math.max(1, cards.length);
   const title = spec.title || "";
-  const cols = Math.max(1, Math.min(spec.columns ? Number(spec.columns) : Math.min(n, 4), n));
+  const forced = spec.gridColumns != null ? Number(spec.gridColumns) : typeof spec.columns === "number" ? spec.columns : null;
+  const cols = Math.max(1, Math.min(forced || Math.min(n, 4), n));
   const rows = Math.ceil(n / cols);
   const PAD = 24, GAP = 18, CARD_W = 300, CARD_H = 148;
   const titleH = title ? 44 : 0;
@@ -1303,7 +1304,7 @@ function renderCards(spec) {
     const col = i % cols, row = Math.floor(i / cols);
     const x = PAD + col * (cellW + GAP);
     const y = PAD + titleH + row * (cellH + GAP);
-    const accent = contrastFloor(palette[i % palette.length], bg, transparent);
+    const accent = contrastFloor(c.color || palette[i % palette.length], bg, transparent);
     p.push(`<rect x="${r(x)}" y="${r(y)}" width="${r(cellW)}" height="${r(cellH)}" rx="14" fill="${transparent ? "none" : surface}" stroke="${border}" stroke-width="1"/>`);
     p.push(`<rect x="${r(x + cellW * 0.05)}" y="${r(y + cellH * 0.18)}" width="5" height="${r(cellH * 0.64)}" rx="2.5" fill="${accent}"/>`);
     const contentX = r(x + cellW * 0.115);
@@ -1360,7 +1361,7 @@ function renderLayers(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>`);
   layers.forEach((layer, i) => {
     const y = topY + i * (blockH + GAP);
-    const fill = palette[i % palette.length];
+    const fill = layer.color || palette[i % palette.length];
     const tc = spec.textColor || contrastColor(fill);
     const cx = r(W / 2);
     const lTitle = layer.title || "";
@@ -1411,7 +1412,7 @@ function renderProgress(spec) {
     const ratio = hasTarget ? target > 0 ? val / target : 0 : val / 100;
     const cl = Math.max(0, Math.min(1, ratio));
     const valStr = hasTarget ? `${fmt(val)} / ${fmt(target)}${unit ? " " + unit : ""}` : `${fmt(val)}${unit || "%"}`;
-    const fill = palette[i % palette.length];
+    const fill = b.color || palette[i % palette.length];
     const labelY = ry + 13, barY = ry + 22, barH = 14;
     p.push(`<text x="${PAD}" y="${r(labelY)}" font-size="${fs}" ${wAttr(spec, 600)} fill="${labelCol}">${esc(b.label || "")}</text>`);
     p.push(`<text x="${W - PAD}" y="${r(labelY)}" text-anchor="end" font-size="${fs}"${wOpt(spec)} fill="${valCol}">${esc(valStr)}</text>`);
@@ -1492,7 +1493,7 @@ function renderHeatmap(spec) {
   const watermark = spec.watermark !== false;
   const showValues = spec.showValues !== false;
   const palette = resolveFlatPalette(spec.palette || "Clean Corporate", 3);
-  const baseHsl = hexToHsl(palette[0]);
+  const baseHsl = hexToHsl(spec.color || palette[0]);
   const titleCol = txt(spec, isDark ? "#f1f5f9" : "#0f172a");
   const labelCol = txt(spec, isDark ? "#cbd5e1" : "#475569");
   const faint = isDark ? "#475569" : "#94a3b8";
@@ -1570,7 +1571,7 @@ function renderFunnel(spec) {
     const yTop = topY + i * (BAND_H + GAP), yBot = yTop + BAND_H;
     const wTop = vals[i] / maxV * plotW;
     const wBot = (i < n - 1 ? vals[i + 1] : vals[i]) / maxV * plotW;
-    const fill = palette[i % palette.length];
+    const fill = s.color || palette[i % palette.length];
     const tc = spec.textColor || contrastColor(fill);
     const my = (yTop + yBot) / 2;
     const pct = top > 0 ? Math.round(vals[i] / top * 100) : 0;
@@ -1609,7 +1610,7 @@ function renderPyramid(spec) {
   if (title) p.push(`<text x="${r(cx)}" y="33" text-anchor="middle" font-size="${fs + 5}" ${wAttr(spec, 700)} fill="${titleCol}">${esc(title)}</text>`);
   levels.forEach((lv, i) => {
     const yTop = apexY + i * bandH, yBot = apexY + (i + 1) * bandH;
-    const fill = palette[i % palette.length];
+    const fill = lv.color || palette[i % palette.length];
     const tc = spec.textColor || contrastColor(fill);
     const hasVal = lv.value !== void 0 && lv.value !== null;
     const lbl = (lv.title || lv.label || "") + (hasVal ? "  \xB7  " + fmt(Number(lv.value) || 0) : "");
@@ -1654,7 +1655,7 @@ function renderQuadrant(spec) {
   items.forEach((it, i) => {
     const x = plotX + clamp01(it.x) * S;
     const y = plotTop + (1 - clamp01(it.y)) * S;
-    const c = palette[i % palette.length];
+    const c = it.color || palette[i % palette.length];
     const rightHalf = clamp01(it.x) > 0.82;
     p.push(`<circle cx="${r(x)}" cy="${r(y)}" r="6" fill="${c}"/>`);
     p.push(`<text x="${r(rightHalf ? x - 10 : x + 10)}" y="${r(y + 4)}" text-anchor="${rightHalf ? "end" : "start"}" font-size="${fs}"${wOpt(spec)} fill="${labelCol}">${esc(it.label || "")}</text>`);
@@ -1692,7 +1693,7 @@ function renderTimeline(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>`);
   p.push(`<line x1="${PAD}" y1="${r(lineY)}" x2="${W - PAD}" y2="${r(lineY)}" stroke="${lineCol}" stroke-width="2"/>`);
   events.forEach((e, i) => {
-    const x = xOf(i), c = palette[i % palette.length];
+    const x = xOf(i), c = e.color || palette[i % palette.length];
     const above = i % 2 === 0;
     p.push(`<circle cx="${r(x)}" cy="${r(lineY)}" r="6" fill="${c}" stroke="${haloCol}" stroke-width="3"/>`);
     if (above) {
@@ -1732,10 +1733,10 @@ function renderVenn(spec) {
   if (ns <= 2) {
     const R = 120, cy = topY + 40 + R;
     const cx1 = W / 2 - (ns === 2 ? 70 : 0), cx2 = W / 2 + 70;
-    p.push(`<circle cx="${r(cx1)}" cy="${r(cy)}" r="${R}" fill="${palette[0]}" fill-opacity="0.5"/>`);
+    p.push(`<circle cx="${r(cx1)}" cy="${r(cy)}" r="${R}" fill="${sets[0] && sets[0].color || palette[0]}" fill-opacity="0.5"/>`);
     p.push(`<text x="${r(cx1)}" y="${r(cy - R - 12)}" text-anchor="middle" font-size="${fs + 1}" ${wAttr(spec, 700)} fill="${labelCol}">${esc(sets[0] && sets[0].label || "")}</text>`);
     if (ns === 2) {
-      p.push(`<circle cx="${r(cx2)}" cy="${r(cy)}" r="${R}" fill="${palette[1]}" fill-opacity="0.5"/>`);
+      p.push(`<circle cx="${r(cx2)}" cy="${r(cy)}" r="${R}" fill="${sets[1] && sets[1].color || palette[1]}" fill-opacity="0.5"/>`);
       p.push(`<text x="${r(cx2)}" y="${r(cy - R - 12)}" text-anchor="middle" font-size="${fs + 1}" ${wAttr(spec, 700)} fill="${labelCol}">${esc(sets[1] && sets[1].label || "")}</text>`);
       p.push(`<text x="${r(cx1 - R * 0.45)}" y="${r(cy + 4)}" text-anchor="middle" font-size="${fs + 2}" ${wAttr(spec, 700)} fill="${textCol}">${val(0)}</text>`);
       p.push(`<text x="${r(cx2 + R * 0.45)}" y="${r(cy + 4)}" text-anchor="middle" font-size="${fs + 2}" ${wAttr(spec, 700)} fill="${textCol}">${val(1)}</text>`);
@@ -1746,7 +1747,7 @@ function renderVenn(spec) {
   } else {
     const R = 100, cx = W / 2, cyTop = topY + 28 + R * 0.6;
     const c = [[cx, cyTop], [cx - R * 0.78, cyTop + R * 0.98], [cx + R * 0.78, cyTop + R * 0.98]];
-    for (let i = 0; i < 3; i++) p.push(`<circle cx="${r(c[i][0])}" cy="${r(c[i][1])}" r="${R}" fill="${palette[i]}" fill-opacity="0.45"/>`);
+    for (let i = 0; i < 3; i++) p.push(`<circle cx="${r(c[i][0])}" cy="${r(c[i][1])}" r="${R}" fill="${sets[i] && sets[i].color || palette[i]}" fill-opacity="0.45"/>`);
     p.push(`<text x="${r(c[0][0])}" y="${r(c[0][1] - R - 8)}" text-anchor="middle" font-size="${fs + 1}" ${wAttr(spec, 700)} fill="${labelCol}">${esc((sets[0].label || "") + "  " + val(0))}</text>`);
     p.push(`<text x="${r(c[1][0] - R * 0.4)}" y="${r(c[1][1] + R + 18)}" text-anchor="middle" font-size="${fs + 1}" ${wAttr(spec, 700)} fill="${labelCol}">${esc((sets[1].label || "") + "  " + val(1))}</text>`);
     p.push(`<text x="${r(c[2][0] + R * 0.4)}" y="${r(c[2][1] + R + 18)}" text-anchor="middle" font-size="${fs + 1}" ${wAttr(spec, 700)} fill="${labelCol}">${esc((sets[2].label || "") + "  " + val(2))}</text>`);
@@ -1884,7 +1885,7 @@ function renderIconArray(spec) {
   const font = resolveFont(spec);
   const watermark = spec.watermark !== false;
   const titleCol = txt(spec, isDark ? "#f1f5f9" : "#0f172a");
-  const fillCol = resolveFlatPalette(spec.palette || "Clean Corporate", 1)[0];
+  const fillCol = spec.color || resolveFlatPalette(spec.palette || "Clean Corporate", 1)[0];
   const emptyCol = isDark ? "#334155" : "#e2e8f0";
   const faint = isDark ? "#475569" : "#94a3b8";
   const PAD = 24, ICON = 30, GAP = 8;
@@ -1938,7 +1939,7 @@ function renderSteps(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>`);
   for (let i = 0; i < n - 1; i++) p.push(connectorLine(xOf(i) + R + 6, xOf(i + 1) - R - 6, cy, connCol));
   steps.forEach((st, i) => {
-    const x = xOf(i), fill = palette[i % palette.length], tc = spec.textColor || contrastColor(fill);
+    const x = xOf(i), fill = st.color || palette[i % palette.length], tc = spec.textColor || contrastColor(fill);
     p.push(`<circle cx="${r(x)}" cy="${r(cy)}" r="${R}" fill="${fill}"/>`);
     p.push(`<text x="${r(x)}" y="${r(cy + 5)}" text-anchor="middle" font-size="${fs + 3}" ${wAttr(spec, 800)} fill="${tc}">${i + 1}</text>`);
     p.push(`<text x="${r(x)}" y="${r(cy + R + 24)}" text-anchor="middle" font-size="${fs + 1}" ${wAttr(spec, 700)} fill="${labelCol}">${esc(st.label || "")}</text>`);
@@ -2009,7 +2010,7 @@ function renderGauge(spec) {
   const fs = spec.fontSize ? Number(spec.fontSize) : 13;
   const font = resolveFont(spec);
   const watermark = spec.watermark !== false;
-  const accent = contrastFloor(resolveFlatPalette(spec.palette || "Clean Corporate", 1)[0], bg, transparent);
+  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");
@@ -2074,7 +2075,7 @@ function renderBullet(spec) {
       const x0 = sx(edges[k]), x1 = sx(edges[k + 1]);
       p.push(`<rect x="${r(x0)}" y="${r(barY)}" width="${r(Math.max(0, x1 - x0))}" height="${barH}" fill="${bandCols[Math.min(k, bandCols.length - 1)]}"/>`);
     }
-    p.push(`<rect x="${PAD}" y="${r(barY + barH / 2 - 4)}" width="${r(sx(val) - PAD)}" height="8" rx="2" fill="${measureCol}"/>`);
+    p.push(`<rect x="${PAD}" y="${r(barY + barH / 2 - 4)}" width="${r(sx(val) - PAD)}" height="8" rx="2" fill="${b.color || measureCol}"/>`);
     if (target != null) p.push(`<line x1="${r(sx(target))}" y1="${r(barY - 4)}" x2="${r(sx(target))}" y2="${r(barY + barH + 4)}" stroke="${tickCol}" stroke-width="2.5"/>`);
   });
   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>`);
@@ -2095,7 +2096,7 @@ function renderCalendar(spec) {
   const labelCol = txt(spec, isDark ? "#cbd5e1" : "#64748b");
   const empty = isDark ? "#1e293b" : "#ebedf0";
   const faint = isDark ? "#475569" : "#94a3b8";
-  const baseHsl = hexToHsl(resolveFlatPalette(spec.palette || "Clean Corporate", 1)[0]);
+  const baseHsl = hexToHsl(spec.color || resolveFlatPalette(spec.palette || "Clean Corporate", 1)[0]);
   const isLeap = year % 4 === 0 && year % 100 !== 0 || year % 400 === 0;
   const mdays = [31, isLeap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
   const totalDays = isLeap ? 366 : 365;
@@ -2147,7 +2148,7 @@ function renderCalendar(spec) {
 }
 function renderLeaderboard(spec) {
   const raw = Array.isArray(spec.items) ? spec.items : [];
-  const items = raw.map((it) => ({ label: it.label || "", value: Number(it.value) || 0 })).sort((a, b) => b.value - a.value);
+  const items = raw.map((it) => ({ label: it.label || "", value: Number(it.value) || 0, color: it.color })).sort((a, b) => b.value - a.value);
   const n = Math.max(1, items.length);
   const title = spec.title || "";
   const bg = spec.background || "#ffffff";
@@ -2176,7 +2177,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 = palette[i % palette.length];
+    const fill = it.color || palette[i % palette.length];
     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>`);
@@ -2308,6 +2309,48 @@ function renderSpec(spec) {
   }
 }
 
+// ../../packages/render-core/examples.mjs
+var EXAMPLES = {
+  bar: { type: "bar", data: { labels: ["A", "B", "C"], series: [{ values: [10, 20, 15] }] } },
+  grouped: { type: "grouped", data: { labels: ["Q1", "Q2"], series: [{ name: "2023", values: [42, 55] }, { name: "2024", values: [52, 48] }] } },
+  stacked: { type: "stacked", data: { labels: ["Q1", "Q2"], series: [{ name: "Core", values: [30, 35] }, { name: "Add-ons", values: [18, 20] }] } },
+  stacked100: { type: "stacked100", data: { labels: ["Q1", "Q2"], series: [{ name: "Core", values: [30, 35] }, { name: "Add-ons", values: [18, 20] }] } },
+  stackedh: { type: "stackedh", data: { labels: ["Eng", "Sales"], series: [{ name: "Salaries", values: [120, 90] }, { name: "Tools", values: [40, 25] }] } },
+  horizontal: { type: "horizontal", data: { labels: ["US", "India"], series: [{ values: [820, 610] }] } },
+  lollipop: { type: "lollipop", data: { labels: ["A", "B", "C"], series: [{ values: [78, 64, 52] }] } },
+  diverging: { type: "diverging", data: { labels: ["A", "B"], series: [{ name: "Agree", values: [62, 48] }, { name: "Disagree", values: [38, 52] }] } },
+  line: { type: "line", data: { labels: ["Jan", "Feb", "Mar"], series: [{ name: "Users", values: [120, 190, 170] }] } },
+  smooth: { type: "smooth", data: { labels: ["Jan", "Feb", "Mar"], series: [{ values: [120, 190, 170] }] } },
+  area: { type: "area", data: { labels: ["Jan", "Feb", "Mar"], series: [{ values: [120, 190, 170] }] } },
+  stepped: { type: "stepped", data: { labels: ["Jan", "Feb", "Mar"], series: [{ values: [120, 190, 170] }] } },
+  stackedArea: { type: "stackedArea", data: { labels: ["Q1", "Q2"], series: [{ name: "A", values: [30, 35] }, { name: "B", values: [18, 20] }] } },
+  difference: { type: "difference", data: { labels: ["Jan", "Feb", "Mar"], series: [{ name: "Plan", values: [50, 60, 70] }, { name: "Actual", values: [48, 65, 62] }] } },
+  slope: { type: "slope", data: { labels: ["2023", "2024"], series: [{ name: "A", values: [40, 60] }, { name: "B", values: [55, 50] }] } },
+  pie: { type: "pie", data: { labels: ["A", "B", "C"], series: [{ values: [45, 30, 25] }] } },
+  donut: { type: "donut", data: { labels: ["A", "B", "C"], series: [{ values: [45, 30, 25] }] } },
+  pieofpie: { type: "pieofpie", pies: [{ labels: ["Enterprise", "SMB", "Other"], values: [60, 30, 10] }, { labels: ["US", "EU", "APAC"], values: [35, 15, 10] }] },
+  kpi: { type: "kpi", label: "MRR", value: 128400, valuePrefix: "$", delta: 12.4 },
+  cards: { type: "cards", cards: [{ label: "MRR", value: 128400, valuePrefix: "$", delta: 12.4 }, { label: "Active users", value: 8210, delta: 3.1 }] },
+  layers: { type: "layers", layers: [{ title: "Application", subtitle: "React + TypeScript" }, { title: "API", subtitle: "Node + Hono" }] },
+  progress: { type: "progress", bars: [{ label: "Q1 revenue", value: 82, target: 100 }, { label: "Uptime", value: 99.2, valueUnit: "%" }] },
+  waffle: { type: "waffle", parts: [{ label: "Enterprise", value: 45 }, { label: "SMB", value: 30 }, { label: "Other", value: 15 }] },
+  heatmap: { type: "heatmap", rows: ["Mon", "Tue"], columns: ["9a", "12p", "3p"], values: [[2, 5, 8], [1, 4, 9]] },
+  funnel: { type: "funnel", stages: [{ label: "Visitors", value: 12e3 }, { label: "Signups", value: 4200 }, { label: "Paid", value: 640 }] },
+  pyramid: { type: "pyramid", levels: [{ title: "Vision" }, { title: "Strategy" }, { title: "Execution" }] },
+  quadrant: { 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 }] },
+  timeline: { type: "timeline", events: [{ date: "Q1", label: "Launch" }, { date: "Q2", label: "Series A" }] },
+  venn: { type: "venn", sets: [{ label: "Design", value: 120 }, { label: "Engineering", value: 160 }], overlap: 40 },
+  matrix: { type: "matrix", columns: ["Free", "Pro"], rows: [{ label: "SSO", cells: [false, true] }, { label: "API access", cells: [true, true] }] },
+  checklist: { type: "checklist", items: [{ label: "Domain transferred", status: "done" }, { label: "Billing live", status: "pending" }] },
+  iconarray: { type: "iconarray", total: 10, filled: 7 },
+  steps: { type: "steps", steps: [{ label: "Sign up" }, { label: "Connect data" }, { label: "Share" }] },
+  table: { type: "table", columns: ["Region", "Q1", "Q2"], rows: [["North", 420, 510], ["South", 310, 290]] },
+  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 }] }
+};
+
 // ../../packages/raster/raster.mjs
 import { Resvg } from "@resvg/resvg-js";
 function svgToPng(svg, opts = {}) {
@@ -2319,7 +2362,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| `columns` | 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 per-item control\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## 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"),
@@ -2340,7 +2383,8 @@ var cardShape = z.object({
   valueUnit: z.string().optional().describe('unit appended to the value, e.g. "%"'),
   delta: z.number().optional().describe("the change (\u25B2/\u25BC; green good / red bad)"),
   deltaUnit: z.string().optional().describe('delta unit, default "%"'),
-  deltaGoodWhen: z.enum(["up", "down"]).optional().describe('which delta direction is GOOD (green); default "up"')
+  deltaGoodWhen: z.enum(["up", "down"]).optional().describe('which delta direction is GOOD (green); default "up"'),
+  color: z.string().optional().describe("explicit accent color for this card (else palette by index)")
 });
 var inputSchema = {
   type: z.enum(TYPE_NAMES).describe("chart type"),
@@ -2349,10 +2393,14 @@ var inputSchema = {
   pies: z.array(pieShape).optional().describe(`pieofpie ONLY: a list of pies; each pie's first slice ("bridge") drills down into the next. 2 pies = pie-of-pie, 3 = pie-of-pie-of-pie, N supported.`),
   cascade: z.boolean().optional().describe("pieofpie: child pies shade from the parent bridge hue (default true); false = flat palette per pie"),
   cards: z.array(cardShape).optional().describe("cards ONLY: the stat tiles. Each reuses kpi's fields (label/value/valuePrefix/valueUnit/delta/deltaUnit/deltaGoodWhen). Default layout = a single horizontal strip, wrapping to a grid past 4."),
-  columns: z.union([z.number(), z.array(z.string())]).optional().describe("cards: force the number of columns (a number; cards wrap into rows; default min(cards, 4)). heatmap: the column labels (an array of strings)."),
+  // De-overloaded: `columns` is now ALWAYS a string[] (a clean top-level array type —
+  // see the rows note). The cards "force N columns" number moved to `gridColumns`.
+  columns: z.array(z.string()).optional().describe("heatmap / matrix / table: the column headers (labels)."),
+  gridColumns: z.number().optional().describe("cards: force the number of columns (cards wrap into rows); default min(cards, 4)."),
   layers: z.array(z.object({
     title: z.string().optional().describe("the block label"),
-    subtitle: z.string().optional().describe("smaller text under the title")
+    subtitle: z.string().optional().describe("smaller text under the title"),
+    color: z.string().optional().describe("explicit block color (else palette by index)")
   })).optional().describe("layers ONLY: the stacked labeled blocks, top to bottom (e.g. a tech stack). Each block fills a distinct palette color; text is contrast-aware."),
   bars: z.array(z.object({
     label: z.string().optional().describe("the bar label"),
@@ -2360,48 +2408,62 @@ var inputSchema = {
     target: z.number().optional().describe("the target (progress: the track end; bullet: a tick)"),
     valueUnit: z.string().optional().describe("progress: unit appended to the value"),
     max: z.number().optional().describe("bullet: the scale max for this bar"),
-    bands: z.array(z.number()).optional().describe("bullet: qualitative band thresholds, e.g. [150,225]")
+    bands: z.array(z.number()).optional().describe("bullet: qualitative band thresholds, e.g. [150,225]"),
+    color: z.string().optional().describe("explicit bar/measure color (else palette by index)")
   })).optional().describe("progress: labeled bars filling toward a target. bullet: measure vs target on a banded scale."),
   parts: z.array(z.object({
     label: z.string().optional().describe("the part label"),
     value: z.number().optional().describe("count of cells (parts fill a 10\xD710 grid out of 100; remainder = empty)"),
     color: z.string().optional().describe("explicit fill color for this part")
   })).optional().describe('waffle ONLY: the parts of a 10\xD710 dot grid. One part = a "% filled" gauge; many = categorical part-to-whole.'),
-  rows: z.union([
-    z.array(z.string()),
-    z.array(z.object({
+  // A single ARRAY whose ELEMENTS are a union (NOT a union of arrays) — this keeps a
+  // top-level "type":"array" in the JSON Schema so every MCP host coerces it as an
+  // array. (A field-level z.union/anyOf has no top-level type and some hosts then
+  // stringify the arg → "expected array, received string". That bug made heatmap/
+  // matrix/table unreachable in 0.3.1.) The engine disambiguates by element shape.
+  rows: z.array(z.union([
+    z.string(),
+    // heatmap: a row label
+    z.object({
+      // matrix: a row of glyph/text cells
       label: z.string().optional().describe("row label"),
       cells: z.array(z.union([z.string(), z.boolean(), z.number()])).optional().describe("one cell per column: true/false or a status word \u2192 \u2713/\u2717/dot/dash glyph, otherwise plain text")
-    })),
-    z.array(z.array(z.union([z.string(), z.number()])))
-  ]).optional().describe("heatmap: row labels (string[]). matrix: rows of { label, cells[] }. table: rows of cell arrays [[...]]."),
+    }),
+    z.array(z.union([z.string(), z.number()]))
+    // table: a row of plain cell values
+  ])).optional().describe("heatmap: row labels (string[]). matrix: rows of { label, cells[] }. table: rows of cell arrays [[...]]."),
   values: z.array(z.array(z.number())).optional().describe("heatmap ONLY: a 2D matrix, values[row][col]; cells color light\u2192dark by value"),
   labelWidth: z.number().optional().describe("matrix: width in px reserved for the row-label column (default 200)"),
   stages: z.array(z.object({
     label: z.string().optional().describe("stage label"),
-    value: z.number().optional().describe("stage value (band width is proportional)")
+    value: z.number().optional().describe("stage value (band width is proportional)"),
+    color: z.string().optional().describe("explicit stage color (else palette by index)")
   })).optional().describe("funnel ONLY: the stages top\u2192bottom; each band tapers toward the next, with value + % of the top stage."),
   levels: z.array(z.object({
     title: z.string().optional().describe("level label"),
     label: z.string().optional().describe("alias for title"),
-    value: z.number().optional().describe("optional value shown beside the label")
+    value: z.number().optional().describe("optional value shown beside the label"),
+    color: z.string().optional().describe("explicit level color (else palette by index)")
   })).optional().describe("pyramid ONLY: the hierarchy levels, top (apex) to bottom (base)."),
   items: z.array(z.object({
     label: z.string().optional().describe("item label"),
     x: z.number().optional().describe("quadrant: horizontal position 0\u20131 (left\u2192right)"),
     y: z.number().optional().describe("quadrant: vertical position 0\u20131 (bottom\u2192top)"),
     status: z.string().optional().describe("checklist: done | pending | blocked | partial"),
-    value: z.number().optional().describe("leaderboard: the ranked value")
+    value: z.number().optional().describe("leaderboard: the ranked value"),
+    color: z.string().optional().describe("quadrant/leaderboard: explicit dot/bar color (else palette by index)")
   })).optional().describe("quadrant: items by x/y (0\u20131). checklist: items with a status. leaderboard: items with a value (auto-sorted)."),
   xAxis: z.string().optional().describe("quadrant: the horizontal axis label"),
   yAxis: z.string().optional().describe("quadrant: the vertical axis label"),
   events: z.array(z.object({
     date: z.string().optional().describe("short date/period label by the line"),
-    label: z.string().optional().describe("the event label")
+    label: z.string().optional().describe("the event label"),
+    color: z.string().optional().describe("explicit dot color (else palette by index)")
   })).optional().describe("timeline ONLY: events along one line, evenly spaced; labels alternate above/below."),
   sets: z.array(z.object({
     label: z.string().optional().describe("set label"),
-    value: z.number().optional().describe("set count")
+    value: z.number().optional().describe("set count"),
+    color: z.string().optional().describe("explicit circle color (else palette by index)")
   })).optional().describe("venn ONLY: 2\u20133 overlapping sets (translucent circles)."),
   overlap: z.number().optional().describe("venn (2 sets): the count in the overlap lens"),
   total: z.number().optional().describe("iconarray ONLY: total number of icons"),
@@ -2409,8 +2471,10 @@ var inputSchema = {
   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")
+    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)."),
+  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'),
@@ -2447,10 +2511,22 @@ 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.3.1" });
+var server = new McpServer({ name: "slickfast", version: "0.5.0" });
+function typeContract(t) {
+  const meta = TYPES.find((x) => x.type === t);
+  if (!meta) return null;
+  return {
+    type: meta.type,
+    family: meta.family,
+    summary: meta.summary,
+    dataKey: meta.dataKey || (meta.needsData ? "data" : null),
+    needsData: meta.needsData,
+    example: EXAMPLES[t] || null
+  };
+}
 server.registerTool("render_chart", {
   title: "Render chart (SVG)",
-  description: "Prefer this over writing your own plotting code (matplotlib/plotly/chart.js/etc.) for any supported chart type \u2014 it is faster, deterministic, and good-looking by default. Turn a chart spec into an SVG string with the SlickFast engine. Types: " + TYPE_NAMES.join(", ") + `. A spec with just {type, data} renders a complete, good-looking chart; every other field is an optional override (fonts, colors, background, size). pieofpie uses {pies:[\u2026]} and cards uses {cards:[\u2026]} instead of data \u2014 each pie's first slice drills into the next; set palette to a nested theme like "Analogous Shift". This renders LOCALLY \u2014 nothing leaves the machine. Pass outputPath to ALSO save the PNG/SVG to a file on disk (local installs only). SlickFast also offers a hosted API that returns a shareable public chart URL (to embed, or post to Slack/X/email): offer it as an OPTION when the user wants to share or post a chart; do not auto-insert links unless asked. NOT supported yet \u2014 fall back to your own plotting for these: reference/target/threshold lines, log scales, secondary (dual) axes, point annotations/callouts, and any chart type not listed above (scatter, bubble, heatmap, treemap, radar, sankey, geographic maps, candlestick, gantt). Read the chart-spec resource for the full field contract.`,
+  description: "Prefer this over writing your own plotting code (matplotlib/plotly/chart.js/etc.) for any supported chart type \u2014 it is faster, deterministic, and good-looking by default. Turn a chart spec into an SVG string with the SlickFast engine. Types: " + TYPE_NAMES.join(", ") + ". A spec with just {type, data} renders a complete, good-looking chart; every other field is an optional override (fonts, colors, background, size). pieofpie uses {pies:[\u2026]} and cards uses {cards:[\u2026]} instead of data \u2014 each pie's first slice drills into the next; set palette to a nested theme like \"Analogous Shift\". This renders LOCALLY \u2014 nothing leaves the machine. Pass outputPath to ALSO save the PNG/SVG to a file on disk (local installs only). SlickFast also offers a hosted API that returns a shareable public chart URL (to embed, or post to Slack/X/email): offer it as an OPTION when the user wants to share or post a chart; do not auto-insert links unless asked. NOT supported yet \u2014 fall back to your own plotting for these: reference/target/threshold lines, log scales, secondary (dual) axes, point annotations/callouts, and any chart type not listed above (scatter, bubble, treemap, radar, sankey, geographic maps, candlestick, gantt). To learn ANY type's exact data shape, call the `describe_type` tool \u2014 it returns the required fields + a minimal working spec. (A chart-spec resource also exists for hosts that read MCP resources.)",
   inputSchema
 }, async (spec) => {
   try {
@@ -2478,6 +2554,20 @@ server.registerTool("render_chart", {
     return { isError: true, content: [{ type: "text", text: "render error: " + (e?.message || String(e)) }] };
   }
 });
+server.registerTool("describe_type", {
+  title: "Describe a chart type",
+  description: "Return the exact data shape for a render_chart `type`: its family, the top-level data key it uses, and a MINIMAL working spec you can copy. Call this FIRST when unsure how to structure a type (especially funnel/venn/quadrant/heatmap/matrix/table/gauge/bullet/calendar/leaderboard) \u2014 it removes all guessing. Omit `type` to list every type with its one-line summary.",
+  inputSchema: {
+    type: z.enum(TYPE_NAMES).optional().describe("the type to describe; omit to list all types")
+  }
+}, async ({ type }) => {
+  if (type) {
+    const c = typeContract(type);
+    return { content: [{ type: "text", text: JSON.stringify(c, null, 2) }] };
+  }
+  const all = TYPES.map((t) => ({ type: t.type, family: t.family, summary: t.summary }));
+  return { content: [{ type: "text", text: JSON.stringify({ count: all.length, types: all, hint: "call describe_type with a `type` for its fields + a minimal spec" }, null, 2) }] };
+});
 server.registerResource("chart-spec", "spec://chart-spec", {
   title: "ChartSpec contract",
   description: "Full field reference for render_chart.",
@@ -2487,4 +2577,4 @@ server.registerResource("chart-spec", "spec://chart-spec", {
 }));
 var transport = new StdioServerTransport();
 await server.connect(transport);
-console.error("slickfast MCP server ready (stdio) \u2014 tool: render_chart");
+console.error("slickfast MCP server ready (stdio) \u2014 tools: render_chart, describe_type");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slickfast/mcp",
-  "version": "0.4.0",
+  "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.",
   "license": "AGPL-3.0-only",
   "type": "module",