@loreto-labs/skill-echarts 0.1.0

package/skill/scripts/lib/theme.mjs

@@ -0,0 +1,92 @@
+// theme.mjs — map a brand token object to an ECharts theme object.
+//
+// The theme carries everything that should look the same across every chart type:
+// the categorical colour list, background, typography, axis treatment, legend/title
+// styling, and per-series-type defaults (bar corner radius, line width, symbol size).
+// Per-chart builders then only supply data + type-specific tweaks.
+
+import { buildCategorical, withAlpha, mix } from './palette.mjs';
+
+const DEFAULT_SHAPE = { barRadius: 4, lineWidth: 2.5, symbolSize: 8, gridline: 'dashed' };
+
+export function buildTheme(brand) {
+  const c = brand.colors || {};
+  const f = brand.fonts || {};
+  const shape = { ...DEFAULT_SHAPE, ...(brand.shape || {}) };
+
+  const bg = c.background || (brand.mode === 'dark' ? '#0a0a0a' : '#ffffff');
+  const text = c.text || (brand.mode === 'dark' ? '#f5f4f1' : '#1a1d21');
+  const muted = c.textMuted || mix(text, bg, 0.45);
+  const axis = c.axis || mix(text, bg, 0.6);
+  const grid = c.grid || mix(text, bg, 0.86);
+  const family = f.family || 'system-ui, sans-serif';
+  const titleFamily = f.titleFamily || family;
+  const base = f.baseSize || 14;
+
+  // Expand the brand's categorical colours to a generous, distinct, contrast-safe set.
+  const color = buildCategorical(c.categorical || [], 12, bg);
+
+  const splitLineType = shape.gridline === 'none' ? 'solid' : shape.gridline;
+  const showSplit = shape.gridline !== 'none';
+
+  const axisCommon = {
+    axisLine: { lineStyle: { color: axis } },
+    axisTick: { show: false },
+    axisLabel: { color: muted, fontFamily: family, fontSize: base - 1 },
+    splitLine: { show: showSplit, lineStyle: { color: grid, type: splitLineType } },
+    nameTextStyle: { color: muted, fontFamily: family },
+  };
+
+  const theme = {
+    color,
+    backgroundColor: bg,
+    textStyle: { fontFamily: family, color: text, fontSize: base },
+
+    title: {
+      textStyle: { fontFamily: titleFamily, color: text, fontSize: Math.round(base * 1.55), fontWeight: 600 },
+      subtextStyle: { fontFamily: family, color: muted, fontSize: base },
+      left: 0,
+    },
+    legend: {
+      textStyle: { color: muted, fontFamily: family, fontSize: base - 1 },
+      icon: 'roundRect',
+      itemWidth: 12, itemHeight: 12, itemGap: 16,
+    },
+    tooltip: {
+      backgroundColor: c.surface || mix(bg, text, 0.06),
+      borderColor: grid,
+      textStyle: { color: text, fontFamily: family },
+    },
+
+    categoryAxis: { ...axisCommon, splitLine: { show: false } },
+    valueAxis: axisCommon,
+    logAxis: axisCommon,
+    timeAxis: axisCommon,
+
+    grid: { left: 48, right: 28, top: 76, bottom: 56, containLabel: true },
+
+    // Per-series-type defaults.
+    bar: { itemStyle: { borderRadius: [shape.barRadius, shape.barRadius, 0, 0] }, barMaxWidth: 46 },
+    line: {
+      lineStyle: { width: shape.lineWidth },
+      symbol: 'circle', symbolSize: shape.symbolSize, smooth: 0.35,
+      emphasis: { focus: 'series' },
+    },
+    scatter: { symbolSize: shape.symbolSize + 4, itemStyle: { opacity: 0.85 } },
+    pie: {
+      itemStyle: { borderColor: bg, borderWidth: 2 },
+      label: { color: text, fontFamily: family },
+      labelLine: { lineStyle: { color: axis } },
+    },
+    radar: {
+      // radar axis colours are set per-option (the radar component, not series)
+    },
+
+    // Carry the resolved tokens so chart builders can reach them without re-deriving.
+    _tokens: { bg, text, muted, axis, grid, family, titleFamily, base, color, shape,
+      surface: c.surface || mix(bg, text, 0.05),
+      positive: c.positive || '#16a34a', negative: c.negative || '#dc2626',
+      withAlpha },
+  };
+  return theme;
+}

package/skill/scripts/package-lock.json

@@ -0,0 +1,240 @@
+{
+  "name": "branded-echarts-scripts",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "branded-echarts-scripts",
+      "version": "0.1.0",
+      "dependencies": {
+        "@resvg/resvg-js": "^2.6.2",
+        "echarts": "^5.5.1"
+      }
+    },
+    "node_modules/@resvg/resvg-js": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/@resvg/resvg-js/-/resvg-js-2.6.2.tgz",
+      "integrity": "sha512-xBaJish5OeGmniDj9cW5PRa/PtmuVU3ziqrbr5xJj901ZDN4TosrVaNZpEiLZAxdfnhAe7uQ7QFWfjPe9d9K2Q==",
+      "engines": {
+        "node": ">= 10"
+      },
+      "optionalDependencies": {
+        "@resvg/resvg-js-android-arm-eabi": "2.6.2",
+        "@resvg/resvg-js-android-arm64": "2.6.2",
+        "@resvg/resvg-js-darwin-arm64": "2.6.2",
+        "@resvg/resvg-js-darwin-x64": "2.6.2",
+        "@resvg/resvg-js-linux-arm-gnueabihf": "2.6.2",
+        "@resvg/resvg-js-linux-arm64-gnu": "2.6.2",
+        "@resvg/resvg-js-linux-arm64-musl": "2.6.2",
+        "@resvg/resvg-js-linux-x64-gnu": "2.6.2",
+        "@resvg/resvg-js-linux-x64-musl": "2.6.2",
+        "@resvg/resvg-js-win32-arm64-msvc": "2.6.2",
+        "@resvg/resvg-js-win32-ia32-msvc": "2.6.2",
+        "@resvg/resvg-js-win32-x64-msvc": "2.6.2"
+      }
+    },
+    "node_modules/@resvg/resvg-js-android-arm-eabi": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/@resvg/resvg-js-android-arm-eabi/-/resvg-js-android-arm-eabi-2.6.2.tgz",
+      "integrity": "sha512-FrJibrAk6v29eabIPgcTUMPXiEz8ssrAk7TXxsiZzww9UTQ1Z5KAbFJs+Z0Ez+VZTYgnE5IQJqBcoSiMebtPHA==",
+      "cpu": [
+        "arm"
+      ],
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@resvg/resvg-js-android-arm64": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/@resvg/resvg-js-android-arm64/-/resvg-js-android-arm64-2.6.2.tgz",
+      "integrity": "sha512-VcOKezEhm2VqzXpcIJoITuvUS/fcjIw5NA/w3tjzWyzmvoCdd+QXIqy3FBGulWdClvp4g+IfUemigrkLThSjAQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@resvg/resvg-js-darwin-arm64": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/@resvg/resvg-js-darwin-arm64/-/resvg-js-darwin-arm64-2.6.2.tgz",
+      "integrity": "sha512-nmok2LnAd6nLUKI16aEB9ydMC6Lidiiq2m1nEBDR1LaaP7FGs4AJ90qDraxX+CWlVuRlvNjyYJTNv8qFjtL9+A==",
+      "cpu": [
+        "arm64"
+      ],
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@resvg/resvg-js-darwin-x64": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/@resvg/resvg-js-darwin-x64/-/resvg-js-darwin-x64-2.6.2.tgz",
+      "integrity": "sha512-GInyZLjgWDfsVT6+SHxQVRwNzV0AuA1uqGsOAW+0th56J7Nh6bHHKXHBWzUrihxMetcFDmQMAX1tZ1fZDYSRsw==",
+      "cpu": [
+        "x64"
+      ],
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@resvg/resvg-js-linux-arm-gnueabihf": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/@resvg/resvg-js-linux-arm-gnueabihf/-/resvg-js-linux-arm-gnueabihf-2.6.2.tgz",
+      "integrity": "sha512-YIV3u/R9zJbpqTTNwTZM5/ocWetDKGsro0SWp70eGEM9eV2MerWyBRZnQIgzU3YBnSBQ1RcxRZvY/UxwESfZIw==",
+      "cpu": [
+        "arm"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@resvg/resvg-js-linux-arm64-gnu": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/@resvg/resvg-js-linux-arm64-gnu/-/resvg-js-linux-arm64-gnu-2.6.2.tgz",
+      "integrity": "sha512-zc2BlJSim7YR4FZDQ8OUoJg5holYzdiYMeobb9pJuGDidGL9KZUv7SbiD4E8oZogtYY42UZEap7dqkkYuA91pg==",
+      "cpu": [
+        "arm64"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@resvg/resvg-js-linux-arm64-musl": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/@resvg/resvg-js-linux-arm64-musl/-/resvg-js-linux-arm64-musl-2.6.2.tgz",
+      "integrity": "sha512-3h3dLPWNgSsD4lQBJPb4f+kvdOSJHa5PjTYVsWHxLUzH4IFTJUAnmuWpw4KqyQ3NA5QCyhw4TWgxk3jRkQxEKg==",
+      "cpu": [
+        "arm64"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@resvg/resvg-js-linux-x64-gnu": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/@resvg/resvg-js-linux-x64-gnu/-/resvg-js-linux-x64-gnu-2.6.2.tgz",
+      "integrity": "sha512-IVUe+ckIerA7xMZ50duAZzwf1U7khQe2E0QpUxu5MBJNao5RqC0zwV/Zm965vw6D3gGFUl7j4m+oJjubBVoftw==",
+      "cpu": [
+        "x64"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@resvg/resvg-js-linux-x64-musl": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/@resvg/resvg-js-linux-x64-musl/-/resvg-js-linux-x64-musl-2.6.2.tgz",
+      "integrity": "sha512-UOf83vqTzoYQO9SZ0fPl2ZIFtNIz/Rr/y+7X8XRX1ZnBYsQ/tTb+cj9TE+KHOdmlTFBxhYzVkP2lRByCzqi4jQ==",
+      "cpu": [
+        "x64"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@resvg/resvg-js-win32-arm64-msvc": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/@resvg/resvg-js-win32-arm64-msvc/-/resvg-js-win32-arm64-msvc-2.6.2.tgz",
+      "integrity": "sha512-7C/RSgCa+7vqZ7qAbItfiaAWhyRSoD4l4BQAbVDqRRsRgY+S+hgS3in0Rxr7IorKUpGE69X48q6/nOAuTJQxeQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@resvg/resvg-js-win32-ia32-msvc": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/@resvg/resvg-js-win32-ia32-msvc/-/resvg-js-win32-ia32-msvc-2.6.2.tgz",
+      "integrity": "sha512-har4aPAlvjnLcil40AC77YDIk6loMawuJwFINEM7n0pZviwMkMvjb2W5ZirsNOZY4aDbo5tLx0wNMREp5Brk+w==",
+      "cpu": [
+        "ia32"
+      ],
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@resvg/resvg-js-win32-x64-msvc": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/@resvg/resvg-js-win32-x64-msvc/-/resvg-js-win32-x64-msvc-2.6.2.tgz",
+      "integrity": "sha512-ZXtYhtUr5SSaBrUDq7DiyjOFJqBVL/dOBN7N/qmi/pO0IgiWW/f/ue3nbvu9joWE5aAKDoIzy/CxsY0suwGosQ==",
+      "cpu": [
+        "x64"
+      ],
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/echarts": {
+      "version": "5.6.0",
+      "resolved": "https://registry.npmjs.org/echarts/-/echarts-5.6.0.tgz",
+      "integrity": "sha512-oTbVTsXfKuEhxftHqL5xprgLoc0k7uScAwtryCgWF6hPYFLRwOUHiFmHGCBKP5NPFNkDVopOieyUqYGH8Fa3kA==",
+      "dependencies": {
+        "tslib": "2.3.0",
+        "zrender": "5.6.1"
+      }
+    },
+    "node_modules/tslib": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.3.0.tgz",
+      "integrity": "sha512-N82ooyxVNm6h1riLCoyS9e3fuJ3AMG2zIZs2Gd1ATcSFjSA23Q0fzjjZeh0jbJvWVDZ0cJT8yaNNaaXHzueNjg=="
+    },
+    "node_modules/zrender": {
+      "version": "5.6.1",
+      "resolved": "https://registry.npmjs.org/zrender/-/zrender-5.6.1.tgz",
+      "integrity": "sha512-OFXkDJKcrlx5su2XbzJvj/34Q3m6PvyCZkVPHGYpcCJ52ek4U/ymZyfuV1nKE23AyBJ51E/6Yr0mhZ7xGTO4ag==",
+      "dependencies": {
+        "tslib": "2.3.0"
+      }
+    }
+  }
+}

package/skill/scripts/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "branded-echarts-scripts",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Render brand-styled Apache ECharts charts to SVG + PNG, server-side (no browser).",
+  "scripts": {
+    "render": "node render.mjs",
+    "all": "node render-all.mjs"
+  },
+  "dependencies": {
+    "echarts": "^5.5.1",
+    "@resvg/resvg-js": "^2.6.2"
+  }
+}

package/skill/scripts/render-all.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// render-all.mjs — render every chart spec in examples/ for every brand in brands/,
+// writing out/<brand>/<chart>.svg (+ .png) and an out/index.html gallery you can open.
+//
+//   node render-all.mjs
+//
+// This is the quickest way to eyeball the whole set and compare brands side by side.
+
+import { readdirSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, join, basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { renderChart } from './render.mjs';
+
+const SCRIPTS = dirname(fileURLToPath(import.meta.url));
+const PKG = resolve(SCRIPTS, '..');
+const BRANDS = join(PKG, 'brands');
+const EXAMPLES = join(PKG, 'examples');
+const OUT = join(PKG, 'out');
+
+const jsonFiles = (dir) => readdirSync(dir).filter((f) => f.endsWith('.json')).sort();
+
+async function main() {
+  const brands = jsonFiles(BRANDS).map((f) => ({
+    file: join(BRANDS, f), key: basename(f, '.json'), data: JSON.parse(readFileSync(join(BRANDS, f), 'utf8')),
+  }));
+  const specs = jsonFiles(EXAMPLES).map((f) => ({
+    key: basename(f, '.json'), data: JSON.parse(readFileSync(join(EXAMPLES, f), 'utf8')),
+  }));
+
+  const gallery = {}; // brandKey -> [{chart, svg, png}]
+  let n = 0;
+  for (const brand of brands) {
+    const dir = join(OUT, brand.key);
+    mkdirSync(dir, { recursive: true });
+    gallery[brand.key] = [];
+    for (const spec of specs) {
+      const { svg, png } = await renderChart({ brand: brand.data, brandPath: brand.file, spec: spec.data, png: true });
+      const svgPath = join(dir, `${spec.key}.svg`);
+      writeFileSync(svgPath, svg);
+      let pngName = null;
+      if (png) { pngName = `${spec.key}.png`; writeFileSync(join(dir, pngName), png); }
+      // Keep the inline SVG markup so the gallery can be a single self-contained file.
+      gallery[brand.key].push({ chart: spec.key, svg: `${spec.key}.svg`, png: pngName, markup: svg });
+      n++;
+    }
+    console.log(`✓ ${brand.data.name || brand.key}: ${specs.length} charts → out/${brand.key}/`);
+  }
+
+  // Two galleries:
+  //  • index.html        — lightweight, references out/<brand>/*.png (open it IN PLACE).
+  //  • gallery.html      — SINGLE self-contained file (SVGs inlined): save/share it anywhere.
+  writeFileSync(join(OUT, 'index.html'), galleryHtml(brands, gallery, false));
+  writeFileSync(join(OUT, 'gallery.html'), galleryHtml(brands, gallery, true));
+  console.log(`\nRendered ${n} charts across ${brands.length} brands.`);
+  console.log(`Open in place:  out/index.html`);
+  console.log(`Portable (save anywhere):  out/gallery.html`);
+}
+
+// Give every chart's SVG element ids a unique namespace so many inlined SVGs on one
+// page can't collide on clipPath/gradient ids (which are referenced by url(#id)).
+function namespaceSvg(markup, tag) {
+  return markup
+    .replace(/\bid="([^"]+)"/g, (_, id) => `id="${tag}__${id}"`)
+    .replace(/url\(#([^)]+)\)/g, (_, id) => `url(#${tag}__${id})`)
+    .replace(/(xlink:href|href)="#([^"]+)"/g, (_, attr, id) => `${attr}="#${tag}__${id}"`);
+}
+
+function galleryHtml(brands, gallery, inline) {
+  const sections = brands.map((b) => {
+    const cards = gallery[b.key].map((g, i) => {
+      const body = inline
+        ? namespaceSvg(g.markup, `${b.key}_${i}`)
+        : `<img src="${b.key}/${g.png || g.svg}" alt="${g.chart}"/>`;
+      return `<figure>${body}<figcaption>${g.chart}</figcaption></figure>`;
+    }).join('\n');
+    return `<section><h2>${(b.data.name || b.key)} <small>(${b.data.mode || 'light'})</small></h2>
+      <div class="grid">${cards}</div></section>`;
+  }).join('\n');
+  const note = inline
+    ? 'Self-contained — charts inlined as SVG (brand webfonts load from CDN). Works saved anywhere.'
+    : 'References the PNG files in this folder — open this file in place, do not move it.';
+  return `<!doctype html><meta charset="utf-8"><title>Branded ECharts — gallery</title>
+<style>
+  body{margin:0;background:#101114;color:#e7e6e3;font:15px/1.5 system-ui,sans-serif;padding:32px}
+  h1{font-weight:700;letter-spacing:-.02em} h2{margin:36px 0 12px;border-bottom:1px solid #2a2c31;padding-bottom:8px}
+  small{color:#8a8f98;font-weight:400}
+  .grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(360px,1fr));gap:18px;align-items:start}
+  figure{margin:0;background:#17181c;border:1px solid #25272d;border-radius:12px;overflow:hidden}
+  figure img, figure svg{width:100%;height:auto;display:block}
+  figcaption{padding:8px 12px;color:#9aa0a8;font-size:13px;text-transform:capitalize}
+</style>
+<h1>Branded ECharts — visualization gallery</h1>
+<p style="color:#9aa0a8">Same data, each brand's colours + fonts. ${note}</p>
+${sections}`;
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/skill/scripts/render.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// render.mjs — render one branded chart to SVG (+ PNG).
+//
+//   node render.mjs --brand brands/onyx.json --chart examples/bar.json --out out/onyx/bar.svg
+//   node render.mjs --brand brands/apricot.json --chart examples/line.json --no-png
+//
+// Reads a brand token file + a chart spec file, server-side renders ECharts to SVG
+// (no browser), embeds the brand @font-face, and writes SVG + a 2x PNG next to it.
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as echartsNS from 'echarts';
+import { buildTheme } from './lib/theme.mjs';
+import { buildOption } from './lib/charts.mjs';
+import { embedFontFaces, resvgFontOptions, hasLocalFonts } from './lib/fonts.mjs';
+
+const echarts = echartsNS.default || echartsNS;
+let _themeSeq = 0;
+
+// Render a chart. Returns { svg, png } where png is a Buffer or null.
+export async function renderChart({ brand, brandPath, spec, png = true }) {
+  const theme = buildTheme(brand);
+  const { _tokens, ...themeForEcharts } = theme; // keep functions out of the registered theme
+  const name = `brand_${_themeSeq++}`;
+  echarts.registerTheme(name, themeForEcharts);
+
+  const width = spec.width || 900;
+  const height = spec.height || 560;
+  const chart = echarts.init(null, name, { renderer: 'svg', ssr: true, width, height });
+  chart.setOption(buildOption(spec, theme));
+  let svg = chart.renderToSVGString();
+  chart.dispose();
+  // Add a viewBox so the SVG scales to its container (gallery cards, embeds) while
+  // keeping aspect ratio; ECharts SSR emits fixed width/height but no viewBox.
+  if (!/<svg\b[^>]*\bviewBox=/.test(svg)) {
+    svg = svg.replace(/<svg\b/, `<svg viewBox="0 0 ${width} ${height}"`);
+  }
+  svg = embedFontFaces(svg, brand);
+
+  let pngBuf = null;
+  if (png) {
+    try {
+      const { Resvg } = await import('@resvg/resvg-js');
+      const r = new Resvg(svg, {
+        font: resvgFontOptions(brand, brandPath),
+        fitTo: { mode: 'width', value: width * 2 }, // 2x for crisp raster
+        background: brand.colors?.background || (brand.mode === 'dark' ? '#0a0a0a' : '#ffffff'),
+      });
+      pngBuf = r.render().asPng();
+    } catch (e) {
+      pngBuf = null;
+      if (!renderChart._warned) {
+        console.warn(`  (PNG skipped: ${e.message}. SVG is unaffected.)`);
+        renderChart._warned = true;
+      }
+    }
+  }
+  return { svg, png: pngBuf };
+}
+
+function parseArgs(argv) {
+  const a = { png: true };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (k === '--brand') a.brand = argv[++i];
+    else if (k === '--chart') a.chart = argv[++i];
+    else if (k === '--out') a.out = argv[++i];
+    else if (k === '--no-png') a.png = false;
+  }
+  return a;
+}
+
+async function main() {
+  const a = parseArgs(process.argv.slice(2));
+  if (!a.brand || !a.chart) {
+    console.error('Usage: node render.mjs --brand <brand.json> --chart <spec.json> [--out file.svg] [--no-png]');
+    process.exit(2);
+  }
+  const brand = JSON.parse(readFileSync(a.brand, 'utf8'));
+  const spec = JSON.parse(readFileSync(a.chart, 'utf8'));
+  const out = a.out || resolve('out', `${spec.type}.svg`);
+  mkdirSync(dirname(out), { recursive: true });
+
+  const { svg, png } = await renderChart({ brand, brandPath: a.brand, spec, png: a.png });
+  writeFileSync(out, svg);
+  console.log(`SVG → ${out}`);
+  if (png) { const p = out.replace(/\.svg$/, '.png'); writeFileSync(p, png); console.log(`PNG → ${p}`); }
+  if (a.png && !hasLocalFonts(brand, a.brand)) {
+    console.log('  note: PNG used a system-font fallback (no local font file for this brand). ' +
+      'SVG is font-accurate via the embedded webfont; set fonts.faces[].file for pixel-accurate PNG.');
+  }
+}
+
+// Run as CLI only when invoked directly (not when imported by render-all.mjs).
+if (fileURLToPath(import.meta.url) === resolve(process.argv[1] || '')) {
+  main().catch((e) => { console.error(e); process.exit(1); });
+}

package/skill/tests/test_building_branded_echarts_visualizations.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""
+Functional test for the building-branded-echarts-visualizations skill.
+
+It renders a chart with each demo brand by invoking the skill's own bundled, readable
+render script (scripts/render.mjs) and asserts that the resulting SVG actually carries
+that brand's colour and font — i.e. the brand styling really landed in the output.
+
+  python3 tests/test_building_branded_echarts_visualizations.py
+
+Requires Node.js and `npm install` in scripts/. If either is missing the test SKIPS
+(exit 0) with a clear message rather than failing — it has no other dependencies and
+never touches the network or the environment.
+"""
+
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+PKG = Path(__file__).resolve().parent.parent
+SCRIPTS = PKG / "scripts"
+RENDER = SCRIPTS / "render.mjs"
+
+# (brand file, a hex from that brand's palette, a font-family that must appear)
+CASES = [
+    ("brands/onyx.json", "#f4f6f7", "Inter"),
+    ("brands/apricot.json", "#ffe0c2", "Inter"),
+]
+CHART = "examples/01_bar.json"
+
+
+def _skip(msg: str) -> None:
+    print(f"SKIPPED: {msg}")
+    sys.exit(0)
+
+
+def render_svg(brand_rel: str, out: Path) -> str:
+    """Run the skill's render script for one brand+chart; return the SVG text."""
+    cmd = [
+        "node", str(RENDER),
+        "--brand", str(PKG / brand_rel),
+        "--chart", str(PKG / CHART),
+        "--out", str(out),
+        "--no-png",  # SVG is the font-accurate output; PNG needs local fonts
+    ]
+    subprocess.run(cmd, cwd=str(SCRIPTS), check=True, capture_output=True, text=True, timeout=120)
+    return out.read_text(encoding="utf-8")
+
+
+def main() -> None:
+    if shutil.which("node") is None:
+        _skip("Node.js not found — install Node, then `cd scripts && npm install`.")
+    if not (SCRIPTS / "node_modules" / "echarts").exists():
+        _skip("dependencies not installed — run `cd scripts && npm install`.")
+
+    failures = []
+    with tempfile.TemporaryDirectory() as tmp:
+        for brand_rel, hex_code, font in CASES:
+            out = Path(tmp) / (Path(brand_rel).stem + ".svg")
+            try:
+                svg = render_svg(brand_rel, out)
+            except subprocess.CalledProcessError as e:
+                failures.append(f"{brand_rel}: render failed — {e.stderr.strip()[:200]}")
+                continue
+
+            brand = json.loads((PKG / brand_rel).read_text(encoding="utf-8"))
+            checks = {
+                "is an <svg>": svg.lstrip().startswith("<svg") or "<svg" in svg[:200],
+                f"contains brand colour {hex_code}": hex_code.lower() in svg.lower(),
+                f"references brand font '{font}'": font in svg,
+                "embeds @font-face": "@font-face" in svg,
+            }
+            missing = [name for name, ok in checks.items() if not ok]
+            label = brand.get("name", brand_rel)
+            if missing:
+                failures.append(f"{label}: missing → {', '.join(missing)}")
+            else:
+                print(f"  PASS  {label}: brand colour + font present in SVG")
+
+    if failures:
+        print("\nFAILED:")
+        for f in failures:
+            print(f"  - {f}")
+        sys.exit(1)
+    print("\nPASSED")
+
+
+if __name__ == "__main__":
+    main()