@loreto-labs/skill-echarts 0.1.0

package/skill/references/chart-type-recipes.md

@@ -0,0 +1,66 @@
+# Chart-type recipes
+
+Each chart spec is `{ "type": <builder>, "title", "subtitle", "width", "height", "data": {…} }`.
+Builders live in `scripts/lib/charts.mjs`. Below: the `data` shape and the brand tokens each type
+leans on. See `examples/*.json` for a runnable spec of every type.
+
+## Categories × values
+
+**`bar` / `groupedBar` / `stackedBar`** — `data: { categories: [], series: [{ name, data: [] }] }`
+- One series → `bar`; many → grouped; `stackedBar` stacks them (`stack:'total'`), rounding only the top.
+- Tokens: `categorical` (series), `bar.itemStyle.borderRadius` (`shape.barRadius`), value axis grid.
+
+**`hbar`** — same `data`; bars run horizontal (category on Y). Good for ranked lists / long labels.
+
+## Trends
+
+**`line`** — `data: { categories: [], series: [{ name, data: [] }] }`. Smooth, `shape.lineWidth`, markers `shape.symbolSize`.
+
+**`area`** — same `data`; adds a vertical gradient fill per series (series color → transparent).
+Use for volume/cumulative; cap at ~3 series so fills don't muddy.
+
+## Parts of a whole
+
+**`pie`** — `data: { items: [{ name, value }] }`. Radius ~66%, legend on the right.
+
+**`donut`** — same `data` + optional `centerLabel` (e.g. a total). Inner/outer radius ring with a
+centered figure. Prefer over pie when you want a headline number in the middle.
+
+## Relationships
+
+**`scatter`** — `data: { series: [{ name, points: [[x, y] | [x, y, size]] }] }, xName, yName`.
+A 3rd value per point drives bubble size. Tokens: `categorical`, `scatter` symbol defaults.
+
+## Single numbers
+
+**`kpi`** — `data: { cards: [{ label, value, delta, deltaDir: 'up'|'down' }] }`. Renders graphic
+number cards (surface panel, big value in the title font, ▲/▼ delta colored by `positive`/`negative`).
+Set a wide-ish `width`, short `height` (~280). 3–5 cards reads best.
+
+## Matrices
+
+**`heatmap`** — `data: { x: [], y: [], values: [[xi, yi, v]] }, showValues?`. **Magnitude uses a
+sequential single-hue ramp** built from the primary brand color (`seqRamp`), *not* the categorical
+palette — that keeps it readable. `visualMap` legend sits below.
+
+## Multi-dimensional
+
+**`radar`** — `data: { indicators: [{ name, max }], series: [{ name, value: [] }] }`. Translucent
+fills per series; axis/split lines use brand grid color. Keep to 2–3 series.
+
+**`treemap`** — `data: { nodes: [{ name, value, children? }] }`. Nested rectangles sized by value;
+gaps/borders use the background color so it reads on light or dark.
+
+## Composite
+
+**`dashboard`** — `data: { cards: [...], bar: { categories, series }, line: { categories, series } }`.
+A KPI strip across the top (graphic) + a grouped bar (left grid) and a line (right grid) side by
+side. Use a large canvas (e.g. 1200×760). This is the "one image, whole story" board.
+
+---
+
+### General tips
+
+- Width/height: wide for time series and dashboards; squarer for pie/radar/treemap.
+- Titles: short `title` + a `subtitle` carrying units ("$M", "thousands", date range).
+- Series count: beyond ~6, the palette auto-extends, but consider grouping or small multiples.

package/skill/references/echarts-theming-model.md

@@ -0,0 +1,62 @@
+# ECharts theming model + server-side rendering
+
+How Apache ECharts theming and headless rendering work, and how this skill uses them.
+
+## The theme object
+
+ECharts merges a **theme object** under every option you set. Register it once, then init charts
+with its name:
+
+```js
+import * as echarts from 'echarts';
+echarts.registerTheme('brand', themeObject);
+const chart = echarts.init(null, 'brand', { renderer: 'svg', ssr: true, width, height });
+```
+
+A theme object is plain data. The keys this skill sets (`lib/theme.mjs`):
+
+| Key | Controls |
+|---|---|
+| `color: []` | The categorical series palette (cycled across series). |
+| `backgroundColor` | Canvas background. |
+| `textStyle` | Global font family / color / size — the base every text inherits. |
+| `title`, `legend`, `tooltip` | Component typography + colors. |
+| `categoryAxis`, `valueAxis`, `timeAxis`, `logAxis` | Axis line, ticks, labels, and `splitLine` per axis kind. |
+| `bar`, `line`, `scatter`, `pie`, `radar`, … | Per-series-type defaults (e.g. `bar.itemStyle.borderRadius`, `line.lineStyle.width`, `line.symbolSize`). |
+
+Anything not in the theme falls back to ECharts defaults; anything an option sets overrides the
+theme. So builders only set **data + type-specific tweaks**; the brand look lives entirely in the theme.
+
+Reference: <https://echarts.apache.org/en/option.html> (every property), and the built-in `dark`
+theme is a good shape reference for the keys above.
+
+## Server-side rendering to SVG (no browser)
+
+ECharts supports SSR with the SVG renderer — no DOM, no canvas, no headless browser:
+
+```js
+const chart = echarts.init(null, theme, { renderer: 'svg', ssr: true, width: 900, height: 540 });
+chart.setOption(option);
+const svg = chart.renderToSVGString();   // a complete <svg>…</svg> string
+chart.dispose();
+```
+
+Notes:
+- Set `option.animation = false` for static output (no transition artifacts).
+- `width`/`height` are required in SSR (there's no element to measure).
+- Output is a self-contained SVG; this skill then injects `@font-face` so the brand font renders
+  (SVG references fonts by name only — see `fonts-and-svg-embedding.md`).
+
+Reference: <https://echarts.apache.org/handbook/en/how-to/cross-platform/server/>
+
+## Gradients & visual encodings in pure option JSON
+
+You don't need the `echarts.graphic.*` classes — the option accepts the object forms:
+
+```js
+areaStyle: { color: { type: 'linear', x: 0, y: 0, x2: 0, y2: 1,
+  colorStops: [ { offset: 0, color: 'rgba(37,99,235,.35)' }, { offset: 1, color: 'rgba(37,99,235,.02)' } ] } }
+```
+
+Heatmaps/treemaps encode magnitude with `visualMap.inRange.color` — use a **sequential single-hue
+ramp**, not the categorical palette (see `chart-type-recipes.md`).

package/skill/references/fonts-and-svg-embedding.md

@@ -0,0 +1,60 @@
+# Fonts: SVG embedding + PNG rasterization
+
+The trickiest part of "branded" charts is making the brand **font** actually appear. ECharts
+writes `font-family="Inter"` onto text nodes, but neither the SVG nor a rasterizer has the font
+data. Handled in `scripts/lib/fonts.mjs`.
+
+## Why we never bundle font binaries
+
+The Loreto marketplace strips binary fonts (`.ttf`, `.otf`, `.woff`, `.woff2`) from published
+packages, and they bloat the bundle. So fonts are **referenced**, not shipped:
+- `fonts.faces[].url` — a webfont URL (woff2) for the SVG.
+- `fonts.faces[].file` — an *optional* local font path for pixel-accurate PNG (not committed).
+
+## SVG → font-accurate (the source of truth)
+
+After ECharts produces the SVG, we inject an `@font-face` block built from the brand's `faces[]`
+URLs, right after the opening `<svg>` tag:
+
+```xml
+<svg …><defs><style type="text/css"><![CDATA[
+@font-face{font-family:'Inter';font-weight:400;src:url('https://…/inter-400.woff2') format('woff2');}
+@font-face{font-family:'Space Grotesk';font-weight:600;src:url('https://…/space-grotesk-600.woff2') format('woff2');}
+]]></style></defs> … </svg>
+```
+
+When the `.svg` is opened in any browser (or embedded in a page), the browser fetches the woff2 and
+renders the real brand typeface. Good webfont sources: **fontsource via jsDelivr**
+(`https://cdn.jsdelivr.net/fontsource/fonts/<family>@latest/latin-<weight>-normal.woff2`) or Google Fonts.
+
+## PNG → resvg
+
+PNG is produced from the SVG by `@resvg/resvg-js` (prebuilt native, no system toolchain). resvg
+**cannot fetch remote `@font-face` URLs** — it renders with locally available fonts:
+
+```js
+new Resvg(svg, { font: {
+  fontFiles: [ /* faces[].file paths that exist on disk */ ],
+  loadSystemFonts: true,
+  defaultFontFamily: brand.fonts.family,
+}}).render().asPng();
+```
+
+So PNG font behavior:
+- If the brand font is **installed on the machine** or a `faces[].file` path is provided → pixel-accurate.
+- Otherwise → resvg falls back to a system font. **Colors, layout, and sizing stay correct**; only the
+  typeface differs. The SVG remains font-accurate.
+
+To make PNGs font-accurate for a brand, either install the font locally or add a `file` to its faces:
+
+```json
+{ "family": "Inter", "weight": 400, "url": "https://…/inter-400.woff2", "file": "fonts/Inter-Regular.ttf" }
+```
+
+(resvg wants `.ttf`/`.otf` for `fontFiles`; `.woff2` is for the SVG `@font-face`.)
+
+## Rule of thumb
+
+- Need crisp, scalable, font-accurate output for web/print → **use the SVG**.
+- Need a raster for slides/email and you have the font installed or as a local file → **PNG is accurate**.
+- PNG without the font locally → still fine for a quick look; ship the SVG for the final brand-perfect asset.

package/skill/scripts/lib/charts.mjs

@@ -0,0 +1,298 @@
+// charts.mjs — per-type ECharts `option` builders.
+//
+// Each builder takes (spec, theme) and returns an ECharts option. All shared styling
+// (colours, fonts, axes, legend) comes from the registered theme, so builders only set
+// data + type-specific touches. `spec.data` shape is documented per builder below.
+
+import { withAlpha, mix, contrastRatio } from './palette.mjs';
+
+// A readable sequential single-hue ramp (low→high) from a base brand colour, so a
+// heatmap encodes magnitude monotonically instead of as an unreadable rainbow.
+function seqRamp(base, bg) {
+  return [mix(base, bg, 0.88), mix(base, bg, 0.5), base, mix(base, '#ffffff', 0.22)];
+}
+
+// Pick black or white for a label so it stays legible on any tile fill.
+function labelOn(fill) {
+  return contrastRatio('#ffffff', fill) >= contrastRatio('#10100f', fill) ? '#ffffff' : '#10100f';
+}
+
+// Recursively colour a treemap: each top segment gets a brand colour; children get a
+// shade of their parent (same hue, nudged toward the background) so the segment reads
+// as a family — and every node's label auto-contrasts against its own fill.
+function colorizeTree(nodes, theme, depth = 0, parentColor = null) {
+  return (nodes || []).map((n, i) => {
+    const fill = parentColor ? mix(parentColor, theme._tokens.bg, 0.16 * depth) : theme.color[i % theme.color.length];
+    const node = { ...n, itemStyle: { color: fill }, label: { color: labelOn(fill) } };
+    if (n.children) node.children = colorizeTree(n.children, theme, depth + 1, fill);
+    return node;
+  });
+}
+
+const titleBlock = (spec) => ({
+  title: { text: spec.title || '', subtext: spec.subtitle || '', left: 0, top: 14 },
+});
+const legendTop = (show) => (show ? { legend: { top: 18, right: 0 } } : {});
+const axisTrigger = { tooltip: { trigger: 'axis' } };
+
+// ── Bars ────────────────────────────────────────────────────────────────────
+// spec.data = { categories: [...], series: [{ name, data: [...] }] }
+function bar(spec, theme) {
+  const d = spec.data;
+  const multi = d.series.length > 1;
+  return {
+    ...titleBlock(spec), ...legendTop(multi), ...axisTrigger,
+    xAxis: { type: 'category', data: d.categories },
+    yAxis: { type: 'value', name: spec.yName || '' },
+    series: d.series.map((s) => ({ type: 'bar', name: s.name, data: s.data })),
+  };
+}
+function groupedBar(spec, theme) { return bar(spec, theme); }
+function stackedBar(spec, theme) {
+  const opt = bar(spec, theme);
+  opt.series = opt.series.map((s) => ({ ...s, stack: 'total', itemStyle: { borderRadius: 0 } }));
+  if (opt.series.length) {
+    const r = theme._tokens.shape.barRadius;
+    const top = opt.series[opt.series.length - 1];
+    top.itemStyle = { borderRadius: [r, r, 0, 0] };
+  }
+  return opt;
+}
+function hbar(spec, theme) {
+  const d = spec.data;
+  const multi = d.series.length > 1;
+  return {
+    ...titleBlock(spec), ...legendTop(multi), ...axisTrigger,
+    xAxis: { type: 'value', name: spec.xName || '' },
+    yAxis: { type: 'category', data: d.categories, axisLabel: { color: theme._tokens.muted } },
+    series: d.series.map((s) => ({
+      type: 'bar', name: s.name, data: s.data,
+      itemStyle: { borderRadius: [0, theme._tokens.shape.barRadius, theme._tokens.shape.barRadius, 0] },
+    })),
+  };
+}
+
+// ── Lines / area ──────────────────────────────────────────────────────────────
+// spec.data = { categories: [...], series: [{ name, data: [...] }] }
+function line(spec, theme) {
+  const d = spec.data;
+  const multi = d.series.length > 1;
+  return {
+    ...titleBlock(spec), ...legendTop(multi), ...axisTrigger,
+    xAxis: { type: 'category', boundaryGap: false, data: d.categories },
+    yAxis: { type: 'value', name: spec.yName || '' },
+    series: d.series.map((s) => ({ type: 'line', name: s.name, data: s.data })),
+  };
+}
+function area(spec, theme) {
+  const opt = line(spec, theme);
+  opt.series = opt.series.map((s, i) => ({
+    ...s,
+    areaStyle: {
+      opacity: 0.9,
+      color: {
+        type: 'linear', x: 0, y: 0, x2: 0, y2: 1,
+        colorStops: [
+          { offset: 0, color: withAlpha(theme.color[i % theme.color.length], 0.35) },
+          { offset: 1, color: withAlpha(theme.color[i % theme.color.length], 0.02) },
+        ],
+      },
+    },
+  }));
+  return opt;
+}
+
+// ── Pie / donut ───────────────────────────────────────────────────────────────
+// spec.data = { items: [{ name, value }] }
+function pie(spec, theme) {
+  return {
+    ...titleBlock(spec),
+    tooltip: { trigger: 'item' },
+    legend: { top: 'middle', right: 0, orient: 'vertical' },
+    series: [{
+      type: 'pie', radius: '66%', center: ['42%', '56%'],
+      data: spec.data.items, avoidLabelOverlap: true,
+      label: { formatter: '{b}\n{d}%' },
+    }],
+  };
+}
+function donut(spec, theme) {
+  const total = spec.data.items.reduce((a, x) => a + (x.value || 0), 0);
+  return {
+    ...titleBlock(spec),
+    tooltip: { trigger: 'item' },
+    legend: { top: 'middle', right: 0, orient: 'vertical' },
+    graphic: {
+      type: 'text', left: '40%', top: '52%',
+      style: {
+        text: spec.centerLabel || total.toLocaleString(),
+        fill: theme._tokens.text, font: `600 26px ${theme._tokens.titleFamily}`,
+        textAlign: 'center',
+      },
+    },
+    series: [{
+      type: 'pie', radius: ['46%', '70%'], center: ['42%', '56%'],
+      data: spec.data.items, avoidLabelOverlap: true,
+      label: { formatter: '{b}\n{d}%' },
+    }],
+  };
+}
+
+// ── Scatter ───────────────────────────────────────────────────────────────────
+// spec.data = { series: [{ name, points: [[x,y],[x,y,size]...] }], xName, yName }
+function scatter(spec, theme) {
+  const d = spec.data;
+  return {
+    ...titleBlock(spec), ...legendTop(d.series.length > 1),
+    tooltip: { trigger: 'item' },
+    xAxis: { type: 'value', name: spec.xName || '', scale: true },
+    yAxis: { type: 'value', name: spec.yName || '', scale: true },
+    series: d.series.map((s) => ({
+      type: 'scatter', name: s.name,
+      symbolSize: (p) => (p[2] ? Math.max(6, Math.sqrt(p[2]) * 2.2) : theme._tokens.shape.symbolSize + 4),
+      data: s.points,
+    })),
+  };
+}
+
+// ── KPI number cards (graphic-based) ────────────────────────────────────────────
+// spec.data = { cards: [{ label, value, delta, deltaDir: 'up'|'down' }] }
+function kpi(spec, theme) {
+  const t = theme._tokens;
+  const W = spec.width || 1000, H = spec.height || 280;
+  const top = (spec.title ? 86 : 28), bottom = 24, gap = 20, padX = 2;
+  const cards = spec.data.cards || [];
+  const cardW = (W - padX * 2 - gap * (cards.length - 1)) / Math.max(1, cards.length);
+  const cardH = H - top - bottom;
+  const txt = (text, x, y, font, fill, align = 'left') =>
+    ({ type: 'text', x, y, style: { text, font, fill, textAlign: align, textVerticalAlign: 'top' } });
+  const els = [];
+  cards.forEach((card, i) => {
+    const x = padX + i * (cardW + gap);
+    els.push({ type: 'rect', x, y: top, shape: { x: 0, y: 0, width: cardW, height: cardH, r: 12 },
+      style: { fill: t.surface, stroke: t.grid, lineWidth: 1 } });
+    els.push(txt(String(card.label || '').toUpperCase(), x + 22, top + 22,
+      `600 ${t.base - 2}px ${t.family}`, t.muted));
+    els.push(txt(String(card.value ?? ''), x + 22, top + 46,
+      `700 ${Math.round(t.base * 2.6)}px ${t.titleFamily}`, t.text));
+    if (card.delta != null) {
+      const up = card.deltaDir ? card.deltaDir === 'up' : Number(String(card.delta).replace(/[^\-0-9.]/g, '')) >= 0;
+      els.push(txt(`${up ? '▲' : '▼'} ${card.delta}`, x + 22, top + 46 + Math.round(t.base * 2.6) + 12,
+        `600 ${t.base}px ${t.family}`, up ? t.positive : t.negative));
+    }
+  });
+  return { ...titleBlock(spec), graphic: { elements: els } };
+}
+
+// ── Heatmap ─────────────────────────────────────────────────────────────────────
+// spec.data = { x: [...], y: [...], values: [[xi, yi, v], ...] }
+function heatmap(spec, theme) {
+  const d = spec.data;
+  const vals = d.values.map((v) => v[2]);
+  return {
+    ...titleBlock(spec),
+    tooltip: { position: 'top' },
+    grid: { top: 84, bottom: 90, left: 60, right: 28, containLabel: true },
+    xAxis: { type: 'category', data: d.x, splitArea: { show: true } },
+    yAxis: { type: 'category', data: d.y, splitArea: { show: true } },
+    visualMap: {
+      min: Math.min(...vals), max: Math.max(...vals), calculable: true,
+      orient: 'horizontal', left: 'center', bottom: 10,
+      inRange: { color: seqRamp(theme._tokens.color[0], theme._tokens.bg) },
+      textStyle: { color: theme._tokens.muted },
+    },
+    series: [{
+      type: 'heatmap', data: d.values,
+      label: { show: !!spec.showValues, color: theme._tokens.text },
+      itemStyle: { borderColor: theme._tokens.bg, borderWidth: 2 },
+      emphasis: { itemStyle: { shadowBlur: 8, shadowColor: withAlpha(theme._tokens.text, 0.3) } },
+    }],
+  };
+}
+
+// ── Radar ───────────────────────────────────────────────────────────────────────
+// spec.data = { indicators: [{ name, max }], series: [{ name, value: [...] }] }
+function radar(spec, theme) {
+  const t = theme._tokens;
+  return {
+    ...titleBlock(spec), ...legendTop(spec.data.series.length > 1),
+    tooltip: {},
+    radar: {
+      indicator: spec.data.indicators, center: ['50%', '56%'], radius: '64%',
+      axisName: { color: t.muted, fontFamily: t.family },
+      axisLine: { lineStyle: { color: t.grid } },
+      splitLine: { lineStyle: { color: t.grid } },
+      splitArea: { areaStyle: { color: [withAlpha(t.text, 0.02), withAlpha(t.text, 0.05)] } },
+    },
+    series: [{
+      type: 'radar',
+      data: spec.data.series.map((s) => ({
+        name: s.name, value: s.value, areaStyle: { opacity: 0.18 }, lineStyle: { width: t.shape.lineWidth },
+      })),
+    }],
+  };
+}
+
+// ── Treemap ─────────────────────────────────────────────────────────────────────
+// spec.data = { nodes: [{ name, value, children? }] }
+function treemap(spec, theme) {
+  const t = theme._tokens;
+  return {
+    ...titleBlock(spec),
+    tooltip: {},
+    series: [{
+      type: 'treemap', top: 78, roam: false, nodeClick: false,
+      breadcrumb: { show: false },
+      itemStyle: { borderColor: t.bg, borderWidth: 2, gapWidth: 2 },
+      label: { fontFamily: t.family, fontSize: t.base },
+      upperLabel: { show: false },
+      levels: [{ itemStyle: { borderWidth: 0, gapWidth: 2 } }],
+      data: colorizeTree(spec.data.nodes, theme),
+    }],
+  };
+}
+
+// ── Dashboard (composite: KPI strip + grouped bar + line, side by side) ──────────
+// spec.data = { cards: [...], bar: {categories, series}, line: {categories, series} }
+function dashboard(spec, theme) {
+  const t = theme._tokens;
+  const W = spec.width || 1200, H = spec.height || 720;
+  const kpiOpt = kpi({ ...spec, title: spec.title, subtitle: spec.subtitle, width: W, height: 200,
+    data: { cards: spec.data.cards || [] } }, theme);
+  const stripH = 200;
+  return {
+    ...titleBlock(spec),
+    graphic: kpiOpt.graphic,
+    tooltip: { trigger: 'axis' },
+    legend: [
+      { top: stripH + 6, left: '2%', data: (spec.data.bar.series || []).map((s) => s.name) },
+      { top: stripH + 6, left: '54%', data: (spec.data.line.series || []).map((s) => s.name) },
+    ],
+    grid: [
+      { left: '2%', right: '52%', top: stripH + 48, bottom: 36, containLabel: true },
+      { left: '52%', right: '2%', top: stripH + 48, bottom: 36, containLabel: true },
+    ],
+    xAxis: [
+      { gridIndex: 0, type: 'category', data: spec.data.bar.categories },
+      { gridIndex: 1, type: 'category', boundaryGap: false, data: spec.data.line.categories },
+    ],
+    yAxis: [{ gridIndex: 0, type: 'value' }, { gridIndex: 1, type: 'value' }],
+    series: [
+      ...spec.data.bar.series.map((s) => ({ type: 'bar', name: s.name, data: s.data, xAxisIndex: 0, yAxisIndex: 0 })),
+      ...spec.data.line.series.map((s) => ({ type: 'line', name: s.name, data: s.data, xAxisIndex: 1, yAxisIndex: 1 })),
+    ],
+  };
+}
+
+export const builders = {
+  bar, groupedBar, stackedBar, hbar, line, area, pie, donut, scatter, kpi, heatmap, radar, treemap, dashboard,
+};
+
+export function buildOption(spec, theme) {
+  const b = builders[spec.type];
+  if (!b) throw new Error(`Unknown chart type "${spec.type}". Known: ${Object.keys(builders).join(', ')}`);
+  const option = b(spec, theme);
+  option.animation = false; // static render
+  if (option.backgroundColor === undefined) option.backgroundColor = theme.backgroundColor;
+  return option;
+}

package/skill/scripts/lib/fonts.mjs

@@ -0,0 +1,66 @@
+// fonts.mjs — make brand fonts actually render in the output.
+//
+// SVG: ECharts writes `font-family="…"` onto text nodes, but the file has no font data.
+// We inject an @font-face <style> (pointing at each face's webfont URL) so a browser
+// fetches and uses the real brand font when the .svg is opened.
+//
+// PNG: resvg cannot fetch remote @font-face URLs. It uses locally-available fonts — any
+// `file` paths declared on the brand's faces, plus the system fonts. If the brand font
+// isn't installed and no local file is given, PNG falls back to a system font (colours
+// and layout stay correct; only the typeface differs). SVG is the font-accurate output.
+//
+// We never bundle binary font files in the package (the marketplace skips them); fonts
+// are referenced by URL (for SVG) and optionally by a local path (for pixel-accurate PNG).
+
+import { existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+
+function faces(brand) {
+  const f = brand.fonts || {};
+  if (Array.isArray(f.faces) && f.faces.length) return f.faces;
+  // Minimal fallback: one face from the primary family with an optional single URL.
+  if (f.family && f.url) return [{ family: f.family, weight: f.weights?.regular || 400, url: f.url }];
+  return [];
+}
+
+// Build the @font-face CSS block from the brand's declared webfont URLs.
+export function fontFaceCss(brand) {
+  const rules = faces(brand)
+    .filter((x) => x.url)
+    .map((x) => {
+      const fmt = x.url.endsWith('.woff2') ? 'woff2' : x.url.endsWith('.woff') ? 'woff'
+        : x.url.endsWith('.otf') ? 'opentype' : 'truetype';
+      return `@font-face{font-family:'${x.family}';font-style:${x.style || 'normal'};` +
+        `font-weight:${x.weight || 400};font-display:swap;src:url('${x.url}') format('${fmt}');}`;
+    });
+  return rules.join('\n');
+}
+
+// Inject the @font-face rules (and a default text fill) into an ECharts SVG string.
+export function embedFontFaces(svg, brand) {
+  const css = fontFaceCss(brand);
+  if (!css) return svg;
+  const styleEl = `<defs><style type="text/css"><![CDATA[\n${css}\n]]></style></defs>`;
+  // Insert right after the opening <svg ...> tag.
+  return svg.replace(/(<svg\b[^>]*>)/, `$1${styleEl}`);
+}
+
+// Font options for @resvg/resvg-js: local font files that exist on disk + system fonts.
+export function resvgFontOptions(brand, brandPath) {
+  const dir = brandPath ? dirname(resolve(brandPath)) : process.cwd();
+  const fontFiles = faces(brand)
+    .map((x) => x.file)
+    .filter(Boolean)
+    .map((p) => (p.startsWith('/') ? p : resolve(dir, p)))
+    .filter((p) => existsSync(p));
+  return {
+    fontFiles,
+    loadSystemFonts: true,
+    defaultFontFamily: (brand.fonts && brand.fonts.family) || 'sans-serif',
+  };
+}
+
+// True if PNG output will be font-accurate (a local file exists for the brand family).
+export function hasLocalFonts(brand, brandPath) {
+  return resvgFontOptions(brand, brandPath).fontFiles.length > 0;
+}

package/skill/scripts/lib/palette.mjs

@@ -0,0 +1,119 @@
+// palette.mjs — colour math + brand palette derivation.
+//
+// Pure functions, no I/O. Given a brand's (often short) list of categorical colours,
+// derive a longer, visually-distinct, contrast-safe palette so charts with many series
+// still read as on-brand. Also exposes the colour helpers the theme/chart builders use.
+
+export function clamp(n, lo, hi) { return Math.min(hi, Math.max(lo, n)); }
+
+export function hexToRgb(hex) {
+  let h = String(hex).trim().replace('#', '');
+  if (h.length === 3) h = h.split('').map((c) => c + c).join('');
+  const num = parseInt(h, 16);
+  return { r: (num >> 16) & 255, g: (num >> 8) & 255, b: num & 255 };
+}
+
+export function rgbToHex({ r, g, b }) {
+  const to = (v) => clamp(Math.round(v), 0, 255).toString(16).padStart(2, '0');
+  return `#${to(r)}${to(g)}${to(b)}`;
+}
+
+export function withAlpha(hex, a) {
+  const { r, g, b } = hexToRgb(hex);
+  return `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+
+// Linear-blend two hex colours; t=0 → a, t=1 → b.
+export function mix(a, b, t) {
+  const A = hexToRgb(a), B = hexToRgb(b);
+  return rgbToHex({ r: A.r + (B.r - A.r) * t, g: A.g + (B.g - A.g) * t, b: A.b + (B.b - A.b) * t });
+}
+
+export function rgbToHsl({ r, g, b }) {
+  r /= 255; g /= 255; b /= 255;
+  const max = Math.max(r, g, b), min = Math.min(r, g, b);
+  let h = 0, s = 0; const l = (max + min) / 2;
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    if (max === r) h = (g - b) / d + (g < b ? 6 : 0);
+    else if (max === g) h = (b - r) / d + 2;
+    else h = (r - g) / d + 4;
+    h /= 6;
+  }
+  return { h: h * 360, s, l };
+}
+
+export function hslToRgb({ h, s, l }) {
+  h = ((h % 360) + 360) % 360 / 360;
+  if (s === 0) { const v = l * 255; return { r: v, g: v, b: v }; }
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  const hue = (t) => {
+    if (t < 0) t += 1; if (t > 1) t -= 1;
+    if (t < 1 / 6) return p + (q - p) * 6 * t;
+    if (t < 1 / 2) return q;
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+  };
+  return { r: hue(h + 1 / 3) * 255, g: hue(h) * 255, b: hue(h - 1 / 3) * 255 };
+}
+
+// WCAG relative luminance + contrast ratio (1..21).
+function luminance(hex) {
+  const { r, g, b } = hexToRgb(hex);
+  const ch = (v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; };
+  return 0.2126 * ch(r) + 0.7152 * ch(g) + 0.0722 * ch(b);
+}
+
+export function contrastRatio(a, b) {
+  const la = luminance(a), lb = luminance(b);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+// Nudge a colour's lightness until it clears `min` contrast against `bg` (so series
+// colours never disappear into a dark or light background). Direction is away from bg.
+export function ensureContrast(hex, bg, min = 1.9) {
+  if (contrastRatio(hex, bg) >= min) return hex;
+  const goLighter = luminance(bg) < 0.4;
+  let { h, s, l } = rgbToHsl(hexToRgb(hex));
+  for (let i = 0; i < 24 && contrastRatio(rgbToHex(hslToRgb({ h, s, l })), bg) < min; i++) {
+    l = clamp(l + (goLighter ? 0.03 : -0.03), 0.06, 0.96);
+  }
+  return rgbToHex(hslToRgb({ h, s, l }));
+}
+
+// Build a categorical palette of length `n` from the brand's base colours. Re-uses the
+// brand colours first, then fills by rotating hue around the brand's average hue and
+// alternating lightness — every entry contrast-checked against the background.
+export function buildCategorical(base, n, bg) {
+  const out = [];
+  const seen = new Set();
+  for (const c of base || []) {
+    const fixed = ensureContrast(c, bg);
+    if (!seen.has(fixed.toLowerCase())) { out.push(fixed); seen.add(fixed.toLowerCase()); }
+    if (out.length >= n) return out;
+  }
+  if (out.length === 0) out.push(ensureContrast('#4e79a7', bg));
+  // Derive extra hues spread around the colour wheel from the seed colours.
+  const seeds = out.map((c) => rgbToHsl(hexToRgb(c)));
+  const avgS = seeds.reduce((a, x) => a + x.s, 0) / seeds.length;
+  const avgL = seeds.reduce((a, x) => a + x.l, 0) / seeds.length;
+  let k = 0;
+  const golden = 137.508; // golden-angle hue stepping → well-separated hues
+  let hue = seeds[0].h;
+  while (out.length < n && k < n * 4) {
+    hue = (hue + golden) % 360;
+    const l = clamp(avgL + (k % 2 ? 0.1 : -0.08), 0.32, 0.72);
+    const cand = ensureContrast(rgbToHex(hslToRgb({ h: hue, s: clamp(avgS, 0.35, 0.85), l })), bg);
+    if (!seen.has(cand.toLowerCase())) { out.push(cand); seen.add(cand.toLowerCase()); }
+    k++;
+  }
+  return out.slice(0, n);
+}
+
+// A gradient stop list across the brand palette — used by heatmap/treemap visualMaps.
+export function gradientStops(base, bg) {
+  const cats = buildCategorical(base, Math.max(3, (base || []).length), bg);
+  return cats.length >= 2 ? cats : [mix(cats[0], bg, 0.6), cats[0]];
+}