@pepperui/charts 1.1.0

package/dist/pepper-charts.mjs

@@ -0,0 +1,1236 @@
+/**
+ * pepper-charts.mjs — the ES module. Nothing runs on import; call renderAll yourself.
+ * @pepperui/charts 1.1.0 — the Mobupps design system's chart theme: one palette, four renderers (DL-10).
+ * GENERATED by `npm run build` from packages/charts/src and the token source — do not edit by hand; edit the
+ * part named in each section's header, or tokens/*.json for a value. THEME below is generated from
+ * @pepperui/tokens 1.2.0; every entry's token path is in THEME.$sources.
+ * Source of truth: bitbucket.org/rashidmobupps/pepper-ui — 6 parts.
+ */
+const VERSION = "1.1.0";
+const THEME = {
+  "font": "Poppins, sans-serif",
+  "text": {
+    "slide": {
+      "size": 15,
+      "weight": 400
+    },
+    "web-desktop": {
+      "size": 12,
+      "weight": 500
+    }
+  },
+  "weightStrong": 600,
+  "ink": "#0b0202",
+  "grid": "#00000012",
+  "rest": "#dad9d9",
+  "onFill": "#ffffff",
+  "labelOn": {
+    "blue": {
+      "fill": "#2b25d9",
+      "ink": "#ffffff"
+    },
+    "red": {
+      "fill": "#e42521",
+      "ink": "#ffffff"
+    },
+    "yellow": {
+      "fill": "#f9c426",
+      "ink": "#0b0202"
+    }
+  },
+  "page": "#ffffff",
+  "series": {
+    "blue": [
+      "#2b25d9",
+      "#6a66e4",
+      "#d4d3f7",
+      "#b5b3b3",
+      "#dad9d9"
+    ],
+    "red": [
+      "#e42521",
+      "#ec6663",
+      "#f9d3d2",
+      "#b5b3b3",
+      "#dad9d9"
+    ],
+    "yellow": [
+      "#f9c426",
+      "#858080",
+      "#dad9d9",
+      "#fad567",
+      "#b5b3b3"
+    ],
+    "multicolor": [
+      "#e42521",
+      "#f9c426",
+      "#2b25d9",
+      "#b5b3b3",
+      "#ec6663",
+      "#6a66e4",
+      "#fad567",
+      "#858080"
+    ]
+  },
+  "$sources": {
+    "series.blue.0": "accent.blue.chart.1",
+    "series.blue.1": "accent.blue.chart.2",
+    "series.blue.2": "accent.blue.chart.3",
+    "series.blue.3": "accent.blue.chart.4",
+    "series.blue.4": "accent.blue.chart.5",
+    "series.red.0": "accent.red.chart.1",
+    "series.red.1": "accent.red.chart.2",
+    "series.red.2": "accent.red.chart.3",
+    "series.red.3": "accent.red.chart.4",
+    "series.red.4": "accent.red.chart.5",
+    "series.yellow.0": "accent.yellow.chart.1",
+    "series.yellow.1": "accent.yellow.chart.2",
+    "series.yellow.2": "accent.yellow.chart.3",
+    "series.yellow.3": "accent.yellow.chart.4",
+    "series.yellow.4": "accent.yellow.chart.5",
+    "series.multicolor.0": "accent.multicolor.chart.1",
+    "series.multicolor.1": "accent.multicolor.chart.2",
+    "series.multicolor.2": "accent.multicolor.chart.3",
+    "series.multicolor.3": "accent.multicolor.chart.4",
+    "series.multicolor.4": "accent.multicolor.chart.5",
+    "series.multicolor.5": "accent.blue.chart.2",
+    "series.multicolor.6": "accent.yellow.chart.4",
+    "series.multicolor.7": "accent.yellow.chart.2",
+    "labelOn.blue.fill": "accent.blue.chart.1",
+    "labelOn.blue.ink": "accent.blue.on-accent",
+    "labelOn.red.fill": "accent.red.chart.1",
+    "labelOn.red.ink": "accent.red.on-accent",
+    "labelOn.yellow.fill": "accent.yellow.chart.1",
+    "labelOn.yellow.ink": "accent.yellow.on-accent",
+    "text.slide": "type.slide.label.medium",
+    "text.web-desktop": "type.web-desktop.label.medium",
+    "font": "type.slide.label.medium",
+    "weightStrong": "font.weight.600",
+    "ink": "chart.text",
+    "grid": "chart.grid",
+    "rest": "chart.rest",
+    "onFill": "chart.on-fill",
+    "page": "surface.page"
+  }
+};
+
+/* ============================================================================
+   format — the number-format OBJECT and the legacy readers.
+
+   DL-10 names this as part of the package because three renderers have to agree
+   on it: the ECharts option below, Chart.js (3.1.2) and `pptx_export.py`, which
+   mirrors the same resolution order and the same compact magnitude as an Excel
+   number-format code. Moved here from Paggy's `charts.js` unchanged — the comments
+   are its own, and every one of them records a bug this code is the fix for.
+   ============================================================================ */
+
+/* ---------- the legacy strings, kept forever as READERS ----------
+   Retired as PRODUCED (Fedor 2026-08-14): nothing mints a `currency_*` any more,
+   because a dollar sign baked into the renderer shipped dollar labels on a euro
+   column. A deck built before the format object still has to render the way it
+   was drawn, so the readers stay. */
+function fmtCurrencyM(v) {
+  if (v == null) return '';
+  const n = Number(v);
+  if (Math.abs(n) >= 1e6) return '$' + (n / 1e6).toFixed(2).replace(/\.?0+$/, '') + 'M';
+  if (Math.abs(n) >= 1e3) return '$' + Math.round(n / 1e3) + 'K';
+  return '$' + n;
+}
+function fmtCurrencyK(v) {
+  if (v == null) return '';
+  const n = Number(v);
+  if (Math.abs(n) >= 1e3) {
+    const k = n / 1e3;
+    // sub-10K keeps decimals so $1,000 / $1,040 / $1,215 don't ALL collapse
+    // to "$1K" (stress-test T04, 2026-07-09)
+    const s = Math.abs(k) < 10 ? k.toFixed(2).replace(/\.?0+$/, '')
+                               : Math.round(k).toLocaleString('en-US');
+    return '$' + s + 'K';
+  }
+  return '$' + n;
+}
+function fmtPlain(v) { return v == null ? '' : Number(v).toLocaleString('en-US'); }
+function fmtPercent(v) { return v == null ? '' : Number(v).toLocaleString('en-US') + '%'; }
+
+function formatter(kind) {
+  switch (kind) {
+    case 'currency_M': return fmtCurrencyM;
+    case 'currency_K': return fmtCurrencyK;
+    case 'percent': return fmtPercent;
+    default: return fmtPlain;
+  }
+}
+
+/* ---------- the number FORMAT object (Fedor 2026-08-14) ----------
+   The old $K/$M pills baked a DOLLAR sign into the renderer, so a euro column
+   shipped dollar labels ("what if the user has euros, K euros, millions or
+   pounds?"). The format is currency-neutral instead: a style, a VERBATIM
+   prefix/suffix and an optional decimals override.
+     fmt = { style: auto|group|group2|compact, prefix, suffix, decimals }
+     auto    today's plain number      group   1,000        (0 decimals)
+     group2  1,000.00 (2 decimals)     compact 1.2K / 1.2M  (1 decimal)
+     decimals: null = follow the style, otherwise 0..4 and it wins
+   prefix/suffix are cosmetic TEXT, never a unit conversion. */
+// PER VALUE, not one unit for the whole chart (Fedor 2026-08-14). A shared
+// magnitude turns 820,000 into "$0.8M" and 310,000 into "$0.3M" — a lost
+// significant digit and a label nobody writes by hand. The retired
+// currency_K/currency_M readers always shortened per value ($820K beside
+// $1.04M) and that is the look every existing deck has; `compact` is their
+// currency-NEUTRAL twin, so it must shorten the same way. Verified against
+// the T04_table_kpis golden, which is exactly this chart.
+function compactUnit(v) {
+  const m = Math.abs(Number(v) || 0);
+  if (m >= 1e6) return { div: 1e6, tag: 'M' };
+  if (m >= 1e3) return { div: 1e3, tag: 'K' };
+  return { div: 1, tag: '' };
+}
+
+function fmtObject(f, vals) {
+  const style = f.style || 'auto';
+  const pre = f.prefix == null ? '' : String(f.prefix);
+  const suf = f.suffix == null ? '' : String(f.suffix);
+  const dec = (f.decimals == null || f.decimals === '')
+    ? null : Math.max(0, Math.min(4, Math.round(Number(f.decimals)) || 0));
+  const compact = style === 'compact';
+  return function (v) {
+    if (v == null || v === '') return '';
+    let n = Number(v);
+    if (!isFinite(n)) return '';
+    let d = dec;
+    let unit = compact ? compactUnit(n) : null;
+    // 3 significant digits is what the retired currency readers actually did
+    // ($820K, $1.04M, $1.22K) — a fixed decimal count cannot do both, and it
+    // is the rule that keeps a shortened label as informative as the number.
+    if (unit) {
+      // ...but the rounding can push a value INTO the next band: 999.5 with
+      // 0 decimals prints "1,000" while 1000 prints "1K", so two bars a half
+      // apart would wear different units. Re-pick the unit from the ROUNDED
+      // value (once is enough — 999.5 → 1000 → K → 1.0 is already stable).
+      const dOf = (x) => Math.max(0, 3 - String(Math.floor(Math.abs(x))).length);
+      if (dec == null) {
+        const r = Math.round(Math.abs(n / unit.div) * 10 ** dOf(n / unit.div)) /
+                  10 ** dOf(n / unit.div);
+        if (r >= 1000) unit = compactUnit(Math.sign(n) * r * unit.div);
+      }
+      n = n / unit.div;
+      if (d == null) d = dOf(n);
+    } else if (d == null && style === 'group') d = 0;
+    else if (d == null && style === 'group2') d = 2;
+    let s = d == null ? n.toLocaleString('en-US')
+      : n.toLocaleString('en-US', { minimumFractionDigits: d, maximumFractionDigits: d });
+    // "2.0K"/"1.00M" read as 2K/1M — but a decimals setting typed by hand
+    // is honoured exactly as typed
+    if (unit) s = (dec == null ? s.replace(/\.(\d*?)0+$/, (m, k) => (k ? '.' + k : '')) : s) + unit.tag;
+    return pre + s + suf;
+  };
+}
+
+/* THE resolution order (locked with the panel, 2026-08-14): the fmt object if
+   the chart carries one → else its legacy string → else plain. Nothing ever
+   silently repaints a deck built before the panel existed. Shared with the
+   editor's chart modal (its live preview IS this function). */
+function valueFormatter(fmt, legacy, vals) {
+  if (fmt && typeof fmt === 'object') return fmtObject(fmt, vals);
+  return formatter(legacy || 'plain');
+}
+
+/* ============================================================================
+   rules — the house chart rules that are not colour, and the recipe geometry.
+
+   Every number here is drawn on the Figma page `Chart recipes` (281:2) and every
+   one of them is a decision with a date. They live in one place so the ECharts
+   builder below, Chart.js (3.1.2) and the PPTX exporter (3.1.3) cannot drift
+   apart the way the palettes did (G13).
+
+   THE HOUSE CHART STANDARD (3.8.1, 2026-09-21; rule 12 added 2026-09-21 on his review of
+   the built result). Twelve rules decided on rendered
+   pairs — `artifacts/requests/2026-09-21-chart-standard/decide.html`, his picks in
+   `answers.json`, the spec in `STANDARD.md`. They are stated here, once, because
+   the audit that found them (3.8.0) found that a picture fixed on its own comes
+   back: the missing baseline was not a slip in one page, it was this file and the
+   two renderers saying `axisLine: { show: false }` three times over.
+
+     1  a column stands on a baseline, heavier than the grid   `axis.baseline`
+     2  a line at every tick, behind the bars                   `axis.grid`
+     3  a column is rounded on top, square at the foot          `bar.radius`
+     4  a stacked column rounds its TOP SEGMENT only            `barRadius()`
+     5  a line carries a dot at every point                     `line.symbolSize`
+     6  a ranked list reads largest first                       `RANKED_TOP_FIRST`
+     7  the row-name lane is measured, not reserved             `category`
+     8  a donut writes its share in the legend only             `donut.labelsOn`
+     9  a one-series chart has THREE treatments, all documented `barColors()`
+    10  the forecast area is the accent at 12 %                 `area.opacity`
+    11  the dashed forecast line is `chart/4`                   `area.forecast`
+    12  a TWO-series chart is `chart/1` against `chart/rest`    `seriesColor()`
+
+   Rule 11 is a stated exemption: `chart/4` on the 12 % accent reads 1.68 : 1,
+   under the 3.0 : 1 floor a meaningful graphical line is held to. He was shown
+   the three readings and picked it; `docs/contrast-matrix.md` carries the pair
+   with his decision beside it, the way D110's twelve kept pairs are.
+   ============================================================================ */
+
+/** The chart-recipe geometry. Names are the recipe's, values are the ones the
+ *  plots on `Chart recipes` were drawn at. */
+const GEOMETRY = {
+  // RULES 1 and 2 — the lines of a plot. A column stands on a baseline drawn in
+  // `chart/rest` at 2px, heavier than the grid behind it, and the grid keeps a
+  // line at every tick. The baseline belongs to the CATEGORY axis: the foot of a
+  // column chart, the left edge of a ranked one — in both it is the line the bars
+  // stand on. The value axis draws none.
+  axis: {
+    baselineWidth: 2,
+    gridWidth: 1,
+  },
+  bar: {
+    // RULE 3 — 4px on the top corners only, square at the foot, in BOTH renderers.
+    // The foot used to be rounded too on the Chart.js side, on the reasoning that
+    // a fully rounded column would not look like it needed a baseline; it now has
+    // one, so the shape follows the baseline back (D2, `chartjs.js` drops
+    // `borderSkipped: false`).
+    // RULE 4 — a stacked column rounds the TOP of its LAST segment and nothing
+    // else: the joints stay square, because a rounded joint draws a gap that is
+    // not in the data. See `barRadius()`.
+    radius: 4,
+    maxWidth: 96,
+  },
+  line: {
+    // RULE 5 — a 4px spline with a dot at every point. This reverses what this
+    // file said until 2026-09-21 (*no dots — the dot lane is for end markers
+    // only*): one renderer obeyed the written rule and the other did not, and he
+    // picked the dots on the pair (D14).
+    width: 4,
+    symbolSize: 9,
+  },
+  // RULES 10 and 11 — an area (the forecast band) is its series colour at 12 %,
+  // and the dashed line over it is `chart/4` at 3px, 6 on 6 off. The fill used to
+  // render black at 22 % in Figma because a bound paint carried `#000000` as its
+  // written colour (D4); the opacity is his pick from the three rendered bands.
+  // The line on an area carries no dots — the pictures rules 10 and 11 were
+  // picked on were drawn that way.
+  area: {
+    opacity: 0.12,
+    forecast: { width: 3, dash: [6, 6] },
+  },
+  legend: {
+    // circular markers, top-right, 18 apart. The Figma page draws the gap at
+    // `space/16` and states the 2px difference rather than moving the code.
+    itemWidth: 10,
+    itemHeight: 10,
+    itemGap: 18,
+  },
+  grid: {
+    // the plot's padding inside its box; `top` leaves the label lane above the
+    // tallest column (26), and twice that when a legend sits above it (44)
+    left: 8,
+    right: 40,
+    topWithLegend: 44,
+    top: 26,
+    bottom: 4,
+  },
+  category: {
+    // RULE 7 — the row-name lane is MEASURED, not reserved. 200px used to be held
+    // for the name however short the names were, which left the wide empty block
+    // on the left of every ranked card (D6). Nothing is reserved now: the lane is
+    // as wide as the longest name and `containLabel` fits the grid round it. A
+    // caller that must truncate passes `label_width` itself.
+    labelGap: 12,
+  },
+  donut: {
+    // RULE 8 — a donut writes its share in the LEGEND ONLY; the ring stays clean.
+    // Outside labels used to be on unless a caller turned them off, so a composed
+    // donut printed every share twice and ran its leader lines out of the box
+    // (D15). The one exception is a donut with no legend to write into
+    // (`legend: false`, the KPI progress rings): the share goes back on the ring,
+    // because the alternative is a chart that states its number nowhere.
+    labelsOn: false,
+    // the ring: 72% cutout, 3px borders in the on-fill white, slices in the
+    // accent's series order
+    cutout: 72,
+    segmentBorder: 3,
+    radiusInner: '58%',
+    radiusOuter: '85%',
+    // the composed "ring beside its legend" block (donut_compare): the ring takes
+    // 62% of the shorter side, the legend is measured from its real entries at
+    // ~10.5px a character, and the pair is centred as ONE group
+    groupRingShare: 0.62,
+    groupGap: 56,
+    groupLegendMax: 380,
+    // the fallback when there is no canvas to measure with: Poppins' average
+    // advance is about 0.55 of the size. `textWidth()` measures the real string
+    // whenever it can — the estimate at 10.5px a character is what cut
+    // "MobuppsX — 14%" off the right edge of his donut (D16)
+    groupLegendCharRatio: 0.55,
+    groupLegendPad: 34,
+    groupEdgeMin: 24,
+    groupLegend: { itemWidth: 16, itemHeight: 16, itemGap: 22, fontSize: 20 },
+    legend: { itemWidth: 14, itemHeight: 14, itemGap: 16, fontSize: 16 },
+    // a config that reaches the renderer carrying none of the house flags is
+    // restyled to this rather than shipping as a default-ECharts pie
+    // labels come from `labelsOn` above — the standard, not a second copy of it
+    unstyled: { cutout: 70, segmentBorder: 0, legendPct: true },
+  },
+};
+
+/** The canvas a chart is drawn on decides its text size: 15 on a slide, 12 on
+ *  web (`type/<canvas>/label/medium`, D36). Slide is the default because the first
+ *  consumer is a 1920x1080 deck, and an unknown canvas is a slide rather than an
+ *  error — a chart with no text is worse than a chart with slide-sized text.
+ *  Shared by both renderers. */
+function chartText(canvas) {
+  return THEME.text[canvas] || THEME.text.slide;
+}
+
+/** Series `i` of `accent`, cycling. The palettes are monochromatic per accent —
+ *  the accent's own tints — except `multicolor`, which is distinct hues; either
+ *  way the cycle repeats when a chart has more series than the palette has
+ *  entries. An unknown accent falls back to blue, the default mode.
+ *
+ *  Every value comes from `THEME.series`, which is generated from
+ *  `accent/<mode>/chart/1–5` — no palette is typed by hand here or anywhere else
+ *  (G13, DL-10). */
+function seriesColor(theme, accent, i, count) {
+  // RULE 12 — a chart with exactly TWO series is a comparison, and a comparison reads as one thing
+  // against the rest of it: series 1 keeps the accent's `chart/1` and series 2 is `chart/rest`, never
+  // the accent's second tint. This is the two-slice donut rule (Fedor 2026-08-12) generalised to every
+  // chart, at his word on 2026-09-21: *"when you're using two two color charts, so we can use this
+  // gray as the second color… the same way a two-coloured donut chart uses"*. `count` is how many
+  // series the chart has; a caller that does not know it gets the plain palette.
+  if (count === 2 && i === 1) return theme.rest;
+  const base = theme.series[accent] || theme.series.blue;
+  return base[i % base.length];
+}
+
+/** RULE 9 — the colours of a ONE-SERIES chart. Three treatments, all correct,
+ *  all documented (Fedor 2026-09-21: *"you have multicolor, you have one color,
+ *  and you have color with different tints. All these three options are
+ *  correct"*). The design system's job is to make all three available and to show
+ *  all three, not to pick one.
+ *
+ *    'flat'        every bar in the accent's `chart/1` — the default in an accent
+ *                  mode, which is what "a chart follows the accent of the slide"
+ *                  means, and what the system already did
+ *    'tints'       the accent's own chart/1–5, cycling — for a comparison across
+ *                  the bars
+ *    'multicolor'  the red→yellow→blue→gray cycle, hand-set and never automatic
+ *                  (`docs/DESIGN_SYSTEM.md:35`, quoted in STANDARD.md)
+ *
+ *  `accent: 'multicolor'` cycles by default: that palette exists to be cycled, and
+ *  a single-colour reading of it paints every bar red, which is the deck bug
+ *  (D17). This function is the ONE place the cycle lives — ECharts had it and
+ *  Chart.js did not, so the site wrote its own (`docs_gen.py`).
+ *
+ *  @returns {string[]} one colour per bar, `n` long
+ */
+function barColors(theme, accent, n, treatment) {
+  const how = treatment || (accent === 'multicolor' ? 'multicolor' : 'flat');
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    if (how === 'flat') out.push(seriesColor(theme, accent, 0));
+    else if (how === 'multicolor') out.push(seriesColor(theme, 'multicolor', i));
+    else out.push(seriesColor(theme, accent, i));
+  }
+  return out;
+}
+
+/** RULES 3 and 4 — the corner radii of one bar, as the four-corner array both
+ *  renderers take. `horizontal` rotates the rounded pair to the bar's end;
+ *  `stack` is undefined for an unstacked bar, `'last'` for the top segment of a
+ *  stack and `'mid'` for every segment below it.
+ *
+ *  The foot of a column is square in every case: it stands on the baseline. */
+function barRadius(horizontal, stack, all) {
+  const r = GEOMETRY.bar.radius;
+  if (all) return r;
+  if (stack === 'mid') return 0;
+  return horizontal ? [0, r, r, 0] : [r, r, 0, 0];
+}
+
+/** RULE 6 — a ranked list reads largest first: the first row of the data sits at
+ *  the TOP. ECharts runs a y category axis bottom-up, so a horizontal chart needs
+ *  `inverse: true` and has been shipping upside down without it (D13). Chart.js
+ *  and Figma already read top-down, which is why only one renderer was wrong. */
+const RANKED_TOP_FIRST = true;
+
+/** A hex colour at `alpha`, as `rgba()`. RULE 10's band is a colour AT an
+ *  opacity, and the two renderers say that differently — ECharts takes an
+ *  `areaStyle.opacity`, Chart.js takes one colour value — so the conversion lives
+ *  here rather than in either of them. A colour that is not a plain `#rrggbb`
+ *  (already rgba, a CSS name) is returned untouched. */
+function withAlpha(hex, alpha) {
+  const m = /^#([0-9a-f]{6})$/i.exec(String(hex || '').trim());
+  if (!m) return hex;
+  const n = parseInt(m[1], 16);
+  return 'rgba(' + ((n >> 16) & 255) + ',' + ((n >> 8) & 255) + ',' + (n & 255) + ',' + alpha + ')';
+}
+
+/** The rendered width of a string in the chart's own type, in px.
+ *
+ *  RULES 7 and D16 both come from a width that was guessed rather than measured:
+ *  200px reserved for a row name, 10.5px assumed for a character of a legend
+ *  entry — his donut cut "MobuppsX" off the right edge. Measured with a canvas
+ *  when there is a document to make one in (every browser channel), and estimated
+ *  from `groupLegendCharRatio` when there is not (a Node render, a test). */
+let measureCtx;
+function textWidth(text, size, weight) {
+  const str = String(text == null ? '' : text);
+  if (typeof document !== 'undefined' && document.createElement) {
+    try {
+      measureCtx = measureCtx || document.createElement('canvas').getContext('2d');
+      measureCtx.font = (weight ? weight + ' ' : '') + size + 'px ' + THEME.font;
+      const w = measureCtx.measureText(str).width;
+      if (w > 0) return Math.ceil(w);
+    } catch (e) { /* no canvas here — fall through to the estimate */ }
+  }
+  return Math.ceil(str.length * size * GEOMETRY.donut.groupLegendCharRatio);
+}
+
+/** The ink of a label written INSIDE a fill (D110, 2026-09-17).
+ *
+ *  The fill decides it. On an accent's main colour the label takes that accent's
+ *  own `on-accent` — near-black on yellow, white on blue and red — and because the
+ *  rule is keyed by the fill and not by the mode, multicolor's yellow series flips
+ *  with it. On any other fill the label stays `onFill`. A white label on
+ *  yellow/400 read 1.62 : 1; yellow's own ink reads 12.65.
+ *
+ *  Both sides come from `THEME.labelOn`, generated from `accent/<mode>/chart/1`
+ *  and `accent/<mode>/on-accent`. A caller's explicit `label_color` still wins. */
+function labelInk(theme, fill) {
+  const f = typeof fill === 'string' ? fill.toLowerCase() : '';
+  for (const accent of Object.keys(theme.labelOn)) {
+    if (theme.labelOn[accent].fill.toLowerCase() === f) return theme.labelOn[accent].ink;
+  }
+  return theme.onFill;
+}
+
+/** The narrow-band axis floor (stress-test S04, 2026-07-09).
+ *
+ *  Tight-band data — uptime 99.92–99.99 on a 0–100 axis — renders as identical
+ *  full bars. When every value sits in a narrow high band, lift the axis floor so
+ *  the variation is visible. Mixed-sign data is left alone, and an explicit
+ *  `axis.min` always wins (the caller applies that, not this).
+ *
+ *  @param {number[]} values every numeric value in the chart
+ *  @returns {number|undefined} the floor, or undefined when the rule does not apply
+ */
+function narrowBandFloor(values) {
+  if (!values || values.length <= 1) return undefined;
+  const lo = Math.min(...values);
+  const hi = Math.max(...values);
+  if (!(lo > 0 && hi > 0 && (hi - lo) / hi < 0.05)) return undefined;
+  const pad = (hi - lo) || hi * 0.01;
+  return Math.max(0, Math.floor((lo - pad) * 100) / 100);
+}
+
+/** The two-slice donut rule (Fedor 2026-08-12).
+ *
+ *  A donut with exactly TWO slices reads as share-vs-rest: slice 1 keeps the
+ *  accent's main colour and slice 2 is always `chart/rest` — never the accent's
+ *  readable mid tint, which is the rule for every OTHER chart including 3+ slice
+ *  donuts. An explicit `colors` on the config still wins (the kpi_donuts progress
+ *  rings, the designed layouts). `pptx_export.chart` mirrors it per point.
+ */
+function isTwoSlice(labels) {
+  return (labels || []).length === 2;
+}
+
+/** The colour of slice `i` of a donut, with the two-slice rule applied.
+ *  `explicit` is the config's own `colors` array and always wins. */
+function sliceColor(theme, accent, labels, i, explicit) {
+  if (explicit && explicit[i]) return explicit[i];
+  if (isTwoSlice(labels) && i === 1) return theme.rest;
+  return seriesColor(theme, accent, i);
+}
+
+/* ============================================================================
+   ECharts — the Pepper theme and the option builder (SVG renderer).
+
+   `echartsTheme(accent, canvas)` is the payload for `echarts.registerTheme`: the
+   defaults a chart written by hand still picks up. `buildOption(cfg, box)` is the
+   whole house chart — the shape Paggy's decks, the editor's preview and the PPTX
+   exporter all agree on — built from the same THEME.
+
+   Charts are static (`animation:false`) so the SVG output is clean vector.
+   ============================================================================ */
+
+/** The colour of series `i`: the dataset's own `color` wins, then the accent's
+ *  palette. */
+function palette(accent, series, i, count) {
+  return (series && series.color) || seriesColor(THEME, accent, i, count);
+}
+
+/** The ECharts theme object — `echarts.registerTheme('pepper-blue', echartsTheme('blue'))`.
+ *  Everything `buildOption` sets explicitly is set here too, so a chart written
+ *  by hand against the theme looks like a chart the builder made. */
+function echartsTheme(accent, canvas) {
+  const t = chartText(canvas);
+  const text = { color: THEME.ink, fontFamily: THEME.font, fontSize: t.size };
+  return {
+    color: (THEME.series[accent] || THEME.series.blue).slice(),
+    backgroundColor: 'transparent',
+    animation: false,
+    textStyle: text,
+    legend: {
+      icon: 'circle',
+      itemWidth: GEOMETRY.legend.itemWidth,
+      itemHeight: GEOMETRY.legend.itemHeight,
+      itemGap: GEOMETRY.legend.itemGap,
+      textStyle: text,
+    },
+    // RULE 1 — the baseline is the CATEGORY axis' own line: the foot of a column
+    // chart, the left edge of a ranked one. `chart/rest` at 2px, heavier than the
+    // grid. RULE 2 — the grid keeps a line at every tick, on the value axis.
+    categoryAxis: {
+      axisLine: { show: true, lineStyle: { color: THEME.rest, width: GEOMETRY.axis.baselineWidth } },
+      axisTick: { show: false },
+      splitLine: { show: false },
+      axisLabel: text,
+    },
+    valueAxis: {
+      axisLine: { show: false },
+      axisTick: { show: false },
+      splitLine: { lineStyle: { color: THEME.grid, width: GEOMETRY.axis.gridWidth } },
+      axisLabel: text,
+    },
+    bar: { itemStyle: { borderRadius: barRadius(false) }, barMaxWidth: GEOMETRY.bar.maxWidth },
+    // RULE 5 — a dot at every point; stated rather than left to the ECharts default
+    line: { smooth: true, showSymbol: true, symbolSize: GEOMETRY.line.symbolSize, lineStyle: { width: GEOMETRY.line.width } },
+    pie: {
+      radius: [GEOMETRY.donut.radiusInner, GEOMETRY.donut.radiusOuter],
+      itemStyle: { borderColor: THEME.onFill, borderWidth: GEOMETRY.donut.segmentBorder },
+    },
+  };
+}
+
+/* ---------- bar / column / line ---------- */
+function axisChart(cfg) {
+  const t = chartText(cfg.canvas);
+  const textStyle = (size) => ({ color: THEME.ink, fontFamily: THEME.font, fontSize: size || t.size });
+  const horizontal = cfg.index_axis === 'y' || cfg.type === 'hbar';
+  // an area and a sparkline are lines with a fill and, in the sparkline's case,
+  // nothing else drawn — they are chart types the recipes have always shown and
+  // the builder never had (D9)
+  const isArea = cfg.type === 'area' || cfg.type === 'sparkline';
+  const isLine = cfg.type === 'line' || isArea;
+  const spark = cfg.type === 'sparkline';
+  // axis labels and data labels share ONE formatter (cfg.value_format is the
+  // legacy per-label override) — the compact style needs every value to pick
+  // its magnitude, so the numbers are gathered before the axis is built
+  const allVals = (cfg.datasets || []).flatMap((d) => d.data || []).filter((v) => typeof v === 'number');
+  const valFmt = valueFormatter((cfg.axis && cfg.axis.fmt) || cfg.fmt,
+                                (cfg.axis && cfg.axis.format) || cfg.format, allVals);
+  const labFmt = cfg.value_format ? formatter(cfg.value_format) : valFmt;
+
+  const series = (cfg.datasets || []).map((d, i) => {
+    const color = palette(cfg.accent, d, i, (cfg.datasets || []).length);   // RULE 12 needs the count
+    const s = {
+      name: d.label || `Series ${i + 1}`,
+      type: isLine ? 'line' : 'bar',
+      data: d.data,
+      color,
+      label: {
+        show: cfg.data_labels !== false && !isLine,
+        position: cfg.label_inside === 'middle' ? 'inside' : (cfg.label_inside ? 'insideTop' : (horizontal ? 'right' : 'top')),
+        formatter: (p) => labFmt(p.value),
+        ...textStyle(),
+        ...(cfg.label_inside ? { color: cfg.label_color || labelInk(THEME, color) } : {}),
+      },
+    };
+    if (!isLine) {
+      s.barMaxWidth = cfg.bar_max || GEOMETRY.bar.maxWidth;
+      s.itemStyle = { color, borderRadius: barRadius(horizontal, undefined, cfg.radius_all) };
+      if (d.stack || cfg.stacked) {
+        s.stack = d.stack || 'total';
+        // RULE 4 — the TOP segment rounds, the joints stay square. Every segment
+        // used to be square, top included, which is the mark he made on the audit
+        // (*"where rounded corners?"*, D3). The last series of a stack is its top.
+        const last = i === (cfg.datasets || []).length - 1;
+        s.itemStyle.borderRadius = barRadius(horizontal, last ? 'last' : 'mid', cfg.radius_all);
+        s.label.position = 'inside';
+        s.label.formatter = d.pct_label ? (p) => p.value ? labFmt(p.value) : '' : s.label.formatter;
+        if (d.pct_color) s.label.color = d.pct_color;
+      }
+    } else {
+      s.smooth = cfg.smooth !== false;
+      s.lineStyle = { width: GEOMETRY.line.width, color };
+      // RULE 5 — a dot at every point. An area's own line carries none: the
+      // pictures rules 10 and 11 were picked on were drawn that way, and a
+      // forecast series says so for itself (`d.forecast`).
+      s.showSymbol = !isArea && cfg.dots !== false;
+      s.symbolSize = GEOMETRY.line.symbolSize;
+      s.label.show = cfg.data_labels === true;
+      if (isArea) {
+        // RULE 10 — the band is the series colour at 12 %
+        s.areaStyle = { color, opacity: cfg.area_opacity != null ? cfg.area_opacity : GEOMETRY.area.opacity };
+      }
+      if (d.forecast) {
+        // RULE 11 — the dashed forecast line is `chart/4`, 3px, 6 on 6 off. Its
+        // 1.68 : 1 on the 12 % band is a stated exemption, his pick, recorded in
+        // the contrast matrix.
+        const fc = seriesColor(THEME, cfg.accent, 3);   // `chart/4` of this accent
+        s.lineStyle = { width: GEOMETRY.area.forecast.width, color: fc, type: GEOMETRY.area.forecast.dash };
+        s.itemStyle = { color: fc };
+        s.areaStyle = undefined;
+        s.showSymbol = false;
+      }
+      if (spark) { s.showSymbol = false; s.label.show = false; }
+    }
+    return s;
+  });
+
+  // RULE 9 — a ONE-SERIES chart has three treatments and all three are correct:
+  // one flat colour (the default in an accent mode), the accent's own tints, and
+  // multicolor. `barColors` is the one place the per-bar cycle lives, so Chart.js
+  // and the site read the same function instead of writing their own (D17). A
+  // caller names the treatment with `cfg.treatment`; `accent: 'multicolor'`
+  // cycles without being asked, because that palette exists to be cycled and a
+  // single-colour reading of it paints every bar red. Lines stay one colour (one
+  // line cannot cycle); multi-series charts keep their per-series hues.
+  if (series.length === 1 && !isLine && (cfg.treatment || cfg.accent === 'multicolor')) {
+    const bars = barColors(THEME, cfg.accent, (cfg.labels || cfg.datasets[0].data || []).length, cfg.treatment);
+    series[0].itemStyle.color = (p) => bars[p.dataIndex % bars.length];
+  }
+
+  const catAxis = {
+    type: 'category',
+    data: cfg.labels || [],
+    // RULE 1 — the baseline: `chart/rest` at 2px, the line the bars stand on
+    axisLine: { show: true, lineStyle: { color: THEME.rest, width: GEOMETRY.axis.baselineWidth } },
+    axisTick: { show: false },
+    // RULE 6 — largest first. ECharts runs a y category axis bottom-up, so a
+    // ranked chart has been shipping upside down (D13); `inverse` puts row 0 at
+    // the top, which is where the deck and Figma already read it.
+    inverse: cfg.inverse != null ? cfg.inverse : (horizontal && RANKED_TOP_FIRST),
+    axisLabel: {
+      ...textStyle(cfg.category_size || t.size),
+      rotate: cfg.category_rotation || 0,
+      interval: 0,
+      // RULE 7 — measured, not reserved: no width is held for the row name, and
+      // `containLabel` fits the grid round whatever it measures. A caller that
+      // must truncate a very long name passes `label_width` itself (D6).
+      ...(horizontal && cfg.label_width ? { width: cfg.label_width, overflow: 'truncate' } : {}),
+    },
+  };
+  // tight-band data (uptime 99.92-99.99 on a 0-100 axis) renders as identical
+  // full bars — the narrow-band floor lifts the axis so the variation is visible
+  // (rules.js, stress-test S04); an explicit cfg.axis.min always wins.
+  const autoMin = narrowBandFloor(allVals);
+  const valAxis = {
+    type: 'value',
+    min: (cfg.axis && cfg.axis.min) != null ? cfg.axis.min : autoMin,
+    max: cfg.axis && cfg.axis.max,
+    interval: cfg.axis && cfg.axis.interval,
+    // RULE 2 — a line at every tick, behind the bars
+    splitLine: { show: cfg.grid !== false, lineStyle: { color: THEME.grid, width: GEOMETRY.axis.gridWidth } },
+    axisLine: { show: false },
+    axisLabel: { ...textStyle(), formatter: (v) => valFmt(v) },
+  };
+
+  if (spark) {
+    // a sparkline is the line and nothing else: no axis, no grid, no labels
+    catAxis.show = false; valAxis.show = false;
+    catAxis.axisLine = { show: false }; catAxis.axisLabel = { show: false };
+    valAxis.splitLine = { show: false }; valAxis.axisLabel = { show: false };
+  }
+
+  return {
+    animation: false,
+    grid: spark ? { left: 0, right: 0, top: 2, bottom: 2 } : {
+      left: GEOMETRY.grid.left,
+      right: cfg.grid_right != null ? cfg.grid_right : GEOMETRY.grid.right,
+      top: cfg.grid_top != null ? cfg.grid_top
+        : ((cfg.datasets || []).length > 1 ? GEOMETRY.grid.topWithLegend : GEOMETRY.grid.top),
+      bottom: cfg.grid_bottom != null ? cfg.grid_bottom : GEOMETRY.grid.bottom,
+      containLabel: true,
+    },
+    legend: legendBlock(cfg, !spark && (cfg.datasets || []).length > 1 && cfg.legend !== false, textStyle),
+    xAxis: horizontal ? valAxis : catAxis,
+    yAxis: horizontal ? catAxis : valAxis,
+    series,
+    textStyle: textStyle(),
+  };
+}
+
+/** The top-right legend: circular markers, 10px, 18 apart. */
+function legendBlock(cfg, show, textStyle) {
+  if (cfg.legend === true) show = true;  // skill parity: legend even for one series
+  if (show === false) return { show: false };
+  return {
+    show: true, top: 0, right: 0, icon: 'circle',
+    itemWidth: GEOMETRY.legend.itemWidth,
+    itemHeight: GEOMETRY.legend.itemHeight,
+    itemGap: GEOMETRY.legend.itemGap,
+    textStyle: textStyle(),
+  };
+}
+
+/* ---------- donut (pie is retired) ---------- */
+function pieChart(cfg, box) {
+  const t = chartText(cfg.canvas);
+  const textStyle = (size) => ({ color: THEME.ink, fontFamily: THEME.font, fontSize: size || t.size });
+  const D = GEOMETRY.donut;
+  // Pie is retired: every circular chart IS the house donut. Configs written
+  // before the write-path normalizers existed (or by anything that slips past
+  // them) arrive UNSTYLED — carrying none of the house flags — and used to
+  // render as a default-ECharts pie/donut with callout labels. Restyle those
+  // to the donut_compare spec here, at render time, so that look can never
+  // ship. Designed donut layouts and editor-converted donuts always carry at
+  // least one of the flags below and pass through untouched.
+  if (cfg.type === 'pie') cfg.type = 'donut';
+  if (!cfg.data && cfg.datasets && cfg.datasets[0])
+    cfg.data = cfg.datasets[0].data || [];
+  if (cfg.legend_pct == null && cfg.labels_on == null
+      && cfg.legend == null && cfg.cutout == null) {
+    cfg.labels_on = GEOMETRY.donut.labelsOn;
+    cfg.seg_border = D.unstyled.segmentBorder;
+    cfg.cutout = D.unstyled.cutout;
+    cfg.bg = cfg.bg || THEME.page;
+    cfg.legend_pct = D.unstyled.legendPct;
+  }
+  // TWO-slice donuts read as share-vs-rest (Fedor 2026-08-12): slice 1 keeps
+  // the accent's MAIN color, slice 2 is always chart/rest — never the accent's
+  // readable mid tint (that rule stands for every OTHER chart, incl. 3+ slice
+  // donuts). Assigned per slice right here so ECharts can never cycle past it;
+  // an explicit cfg.colors (kpi_donuts rings, designed layouts) still wins.
+  // PPTX mirrors in pptx_export.chart. See rules.js sliceColor.
+  const data = (cfg.labels || []).map((l, i) => ({
+    name: l,
+    value: (cfg.data || [])[i],
+    itemStyle: { color: sliceColor(THEME, cfg.accent, cfg.labels, i, cfg.colors) },
+  }));
+  // a donut has no axis block, so its format lives at the top level (the axis
+  // fallback only catches a config that came from an axis chart type-switch)
+  const fmtSrc = cfg.fmt || (cfg.axis && cfg.axis.fmt);
+  const fmt = valueFormatter(fmtSrc, cfg.format, cfg.data || []);
+  const total = (cfg.data || []).reduce((a, b) => a + (+b || 0), 0);
+  const noLegend = cfg.legend === false;
+  const ringLabels = cfg.labels_on != null ? cfg.labels_on : (noLegend ? true : GEOMETRY.donut.labelsOn);
+  const pctName = (name) => {
+    const i = (cfg.labels || []).indexOf(name);
+    const v = +((cfg.data || [])[i]) || 0;
+    return total ? name + ' — ' + Math.round(v / total * 100) + '%' : name;
+  };
+  // House composition for editor-converted donuts (legend_pct): a padded ring
+  // with the legend right beside it, the pair centred as ONE group in the box
+  // (the donut_compare look). Computed in px from the real element size, so a
+  // wide chart panel can't strand the legend at the far edge or blow the ring
+  // up to full height. Designed donut layouts (no legend_pct) are untouched.
+  let group = null;
+  if (cfg.legend_pct && cfg.legend !== false && box && box.w > 40 && box.h > 40) {
+    const R = Math.round(D.groupRingShare * Math.min(box.w, box.h) / 2);
+    const inner = Math.round(R * ((cfg.cutout || D.cutout) / 100));
+    // estimate the legend block width from the ACTUAL entries (20px Poppins ≈
+    // 10.5px/char + dot/gap) — a fixed guess skews the centring when labels are
+    // short ("Jan — 7%") or long ("PHL — Philippines — 14.3%")
+    // D16 — his mark, *"be carefull with layout becose mobuppsX numer on the right
+    // is cut out"*. The width used to be GUESSED at 10.5px a character and only
+    // the LEFT edge was clamped, so an entry wider than the guess ran off the
+    // right. Measured now, and clamped at both edges: when the group cannot fit,
+    // the ring gives way, not the text.
+    const wide = (cfg.labels || []).map(pctName)
+      .reduce((m, str) => Math.max(m, textWidth(str, D.groupLegend.fontSize)), 0);
+    const legendW = Math.min(D.groupLegendMax, wide + D.groupLegendPad);
+    const gap = D.groupGap;
+    const free = box.w - legendW - gap - 2 * D.groupEdgeMin;
+    const r = Math.max(8, Math.min(R, Math.round(free / 2)));
+    const inner2 = Math.round(r * ((cfg.cutout || D.cutout) / 100));
+    const left = Math.max(D.groupEdgeMin, Math.round((box.w - (2 * r + gap + legendW)) / 2));
+    group = { R: r, inner: inner2, cx: left + r, legendLeft: left + 2 * r + gap };
+  }
+  return {
+    animation: false,
+    // bg: the editor's type-switch sets the page white so a converted donut sits
+    // on white (designed donut layouts leave it unset — transparent, card decides)
+    ...(cfg.bg ? { backgroundColor: cfg.bg } : {}),
+    legend: cfg.legend === false ? { show: false } : (group ? {
+      orient: 'vertical', left: group.legendLeft, top: 'middle', icon: 'circle',
+      itemWidth: D.groupLegend.itemWidth, itemHeight: D.groupLegend.itemHeight,
+      itemGap: D.groupLegend.itemGap, textStyle: textStyle(D.groupLegend.fontSize),
+      formatter: pctName,
+    } : {
+      orient: 'vertical', right: 0, top: 'middle', icon: 'circle',
+      itemWidth: D.legend.itemWidth, itemHeight: D.legend.itemHeight,
+      itemGap: D.legend.itemGap, textStyle: textStyle(D.legend.fontSize),
+      // RULE 8 — the legend is where the share is written, so it carries it by
+      // default; `legend_pct: false` is how a caller whose labels already say the
+      // share (a designed donut layout) turns the suffix off.
+      ...(cfg.legend_pct !== false ? { formatter: pctName } : {}),
+    }),
+    series: [{
+      type: 'pie',
+      radius: group ? [group.inner, group.R]
+                    : (cfg.cutout ? [cfg.cutout + '%', '100%'] : [D.radiusInner, D.radiusOuter]),
+      center: group ? [group.cx, '50%']
+                    : (cfg.legend === false ? ['50%', '50%'] : ['38%', '50%']),
+      data,
+      // RULE 8 — the share is written in the LEGEND only and the ring stays
+      // clean. Outside labels used to be ON unless a caller turned them off, so a
+      // composed donut printed every share twice and ran leader lines out of the
+      // box (D15). The exception is a donut with NO legend to write into: the
+      // share goes back on the ring rather than nowhere.
+      label: ringLabels ? {
+        show: true,
+        formatter: (p) => (fmtSrc || cfg.format) ? fmt(p.value) : p.percent.toFixed(0) + '%',
+        ...textStyle(), fontWeight: THEME.weightStrong,
+        position: 'outside',
+      } : { show: false },
+      labelLine: { show: ringLabels },
+      itemStyle: { borderColor: THEME.onFill, borderWidth: cfg.seg_border != null ? cfg.seg_border : D.segmentBorder },
+    }],
+  };
+}
+
+/** The whole option for one chart config. `box` is the element's current pixel
+ *  size and is only read by the composed donut. */
+function buildOption(cfg, box) {
+  if (cfg.type === 'pie' || cfg.type === 'donut') return pieChart(cfg, box);
+  return axisChart(cfg);
+}
+
+/* ============================================================================
+   Chart.js — the same theme, the other renderer (3.1.2).
+
+   Chart.js has no option builder here the way ECharts does, and deliberately: its
+   consumers (the quarter builder's six chart layouts) each compose their own chart
+   from a generated template, and what they were repeating was not a chart — it was
+   the same ink, the same grid, the same 15px Poppins and the same 4px bar top,
+   typed out thirty-odd times. So this part hands out those PIECES, each one a plain
+   object ready to spread into a Chart.js option:
+
+     ticks: PepperCharts.chartjs.text(),
+     grid:  PepperCharts.chartjs.grid(), border: { display: false },
+     ...PepperCharts.chartjs.bar(),
+
+   `defaults()` sets the globals once, and everything below is what a chart still has
+   to say for itself. Same THEME as the ECharts side, so the two renderers cannot
+   disagree about a colour (DL-10, G13).
+   ============================================================================ */
+
+/** Apply the house globals to `Chart.defaults`. Call it once, after Chart.js loads.
+ *  Returns what it set, so a caller can log or assert it. */
+function chartjsDefaults(canvas, Chart) {
+  const C = Chart || (typeof window !== 'undefined' ? window.Chart : undefined);
+  const t = chartText(canvas);
+  const set = { 'font.family': THEME.font, 'font.size': t.size, color: THEME.ink };
+  if (C && C.defaults) {
+    C.defaults.font.family = THEME.font;
+    C.defaults.font.size = t.size;
+    C.defaults.color = THEME.ink;
+  }
+  return set;
+}
+
+/** The accent's series colours, as Chart.js wants them: a plain array. `count` is how many series
+ *  the chart draws — with exactly two, RULE 12 makes the second one `chart/rest`. */
+function chartjsPalette(accent, count) {
+  const base = (THEME.series[accent] || THEME.series.blue).slice();
+  if (count === 2) return [base[0], THEME.rest];
+  return base;
+}
+
+/** A font block on its own: the canvas role's size (or an override) and the family.
+ *  A total drawn bigger than its bars is the chart's own decision, not the theme's,
+ *  so a size may be passed; the family never varies. */
+function chartjsFont(canvas, size, weight) {
+  return { size: size || chartText(canvas).size, family: THEME.font, ...(weight ? { weight } : {}) };
+}
+
+/** Text in a chart — ticks, legend labels, anything Chart.js styles with
+ *  `{ font, color }`. No family: `defaults()` set it globally, and the smaller the
+ *  option the easier it is to read what a chart actually overrides. */
+function chartjsText(canvas, size) {
+  return { font: { size: size || chartText(canvas).size }, color: THEME.ink };
+}
+
+/** The same, with the family stated. The datalabels plugin draws on its own canvas
+ *  context and does not inherit `Chart.defaults.font.family`, so a data label says
+ *  the family itself. */
+function chartjsLabel(canvas, size, weight) {
+  return { font: chartjsFont(canvas, size, weight), color: THEME.ink };
+}
+
+/** RULE 2 — a light line at every tick, behind the bars. */
+function chartjsGrid() { return { color: THEME.grid, lineWidth: GEOMETRY.axis.gridWidth }; }
+
+/** A value axis draws no line of its own. */
+function chartjsBorder() { return { display: false }; }
+
+/** RULE 1 — the baseline the columns stand on: `chart/rest` at 2px, heavier than
+ *  the grid. It goes on the CATEGORY axis, whose border is the line at zero. Until
+ *  2026-09-21 this file said *"the axis line that is never drawn"* and meant it —
+ *  the first thing he marked on the audit (D1). */
+function chartjsBaseline() {
+  return { display: true, color: THEME.rest, width: GEOMETRY.axis.baselineWidth };
+}
+
+/** RULE 3 — a bar dataset's house shape: 4px on the top corners, square at the
+ *  foot. `borderSkipped: false` used to round the bottom too, so a deck's column
+ *  floated as a pill while the same column in a dashboard sat flat (D2); Chart.js'
+ *  own default skips the start edge, which is exactly the rule. */
+function chartjsBar() {
+  return { borderRadius: GEOMETRY.bar.radius };
+}
+
+/** RULE 4 — a segment of a STACKED bar: the top one rounds, the joints stay
+ *  square. `last` is true for the dataset drawn at the top of the stack. */
+function chartjsStacked(last) {
+  return { borderRadius: last ? GEOMETRY.bar.radius : 0 };
+}
+
+/** RULE 5 — a line dataset: the 4px spline with a dot at every point. The dots
+ *  reverse what this renderer drew until 2026-09-21; ECharts drew them, Chart.js
+ *  did not, and he picked them on the pair (D14). */
+function chartjsLine() {
+  return {
+    borderWidth: GEOMETRY.line.width,
+    pointRadius: GEOMETRY.line.symbolSize / 2,
+    pointHoverRadius: GEOMETRY.line.symbolSize / 2,
+    tension: 0.35,
+  };
+}
+
+/** RULES 10 and 11 — the forecast band and the dashed line over it, as the two
+ *  dataset blocks a Chart.js consumer spreads. `accent` picks the band's colour;
+ *  the line is that accent's `chart/4`. */
+function chartjsArea(accent) {
+  return {
+    ...chartjsLine(),
+    pointRadius: 0,
+    fill: 'origin',
+    backgroundColor: withAlpha(seriesColor(THEME, accent, 0), GEOMETRY.area.opacity),
+    borderColor: seriesColor(THEME, accent, 0),
+  };
+}
+
+function chartjsForecast(accent) {
+  const c = seriesColor(THEME, accent, 3);
+  return {
+    borderWidth: GEOMETRY.area.forecast.width,
+    borderDash: GEOMETRY.area.forecast.dash.slice(),
+    borderColor: c,
+    pointRadius: 0,
+    fill: false,
+    tension: 0.35,
+  };
+}
+
+/** RULE 9 — the three treatments of a ONE-SERIES chart, as the per-bar colour
+ *  array Chart.js takes. This is what the renderer did not have: a deck painted a
+ *  multicolor chart entirely red and could not follow the three-colour rule, and
+ *  the site wrote its own cycler because the package handed it none (D17). One
+ *  rule, one place, three consumers. */
+function chartjsBarColors(accent, n, treatment) {
+  return barColors(THEME, accent, n, treatment);
+}
+
+/** A doughnut: the ring and its borders. `cutout` overrides the house 72% for a
+ *  consumer that draws a thinner ring, and is a stated substitution when it does. */
+function chartjsDoughnut(cutout) {
+  return {
+    cutout: (cutout == null ? GEOMETRY.donut.cutout : cutout) + '%',
+    borderWidth: GEOMETRY.donut.segmentBorder,
+    borderColor: THEME.onFill,
+  };
+}
+
+/** The legend block: circular markers in the chart's own text. `extra` is merged
+ *  into `labels`, which is where a consumer puts its padding or its
+ *  `generateLabels`. */
+function chartjsLegendLabels(canvas, extra) {
+  return {
+    ...chartjsText(canvas),
+    usePointStyle: true,
+    pointStyle: 'circle',
+    ...(extra || {}),
+  };
+}
+
+function chartjsLegend(canvas, extra) {
+  return { labels: chartjsLegendLabels(canvas, extra) };
+}
+
+/** A value axis: the grid, no border, the ticks in chart text, and — when the data
+ *  is handed in — the narrow-band floor as `min`, so a Chart.js chart of uptime
+ *  reads the way the ECharts one does. An explicit `min` always wins. */
+function chartjsValueAxis(canvas, opts) {
+  const o = opts || {};
+  const floor = o.values ? narrowBandFloor(o.values) : undefined;
+  const min = o.min != null ? o.min : floor;
+  return {
+    ...(min != null ? { min } : {}),
+    ...(o.max != null ? { max: o.max } : {}),
+    ticks: { ...chartjsText(canvas), ...(o.ticks || {}) },
+    grid: chartjsGrid(),
+    border: chartjsBorder(),
+  };
+}
+
+/** A category axis: no grid, the baseline, every label kept. */
+function chartjsCategoryAxis(canvas, opts) {
+  const o = opts || {};
+  return {
+    ticks: { autoSkip: false, ...chartjsText(canvas, o.size), ...(o.ticks || {}) },
+    grid: { display: false },
+    // RULE 1 — the category axis carries the baseline
+    border: chartjsBaseline(),
+  };
+}
+
+/** Everything above, as one object — `PepperCharts.chartjs.*`. */
+const chartjs = {
+  defaults: chartjsDefaults,
+  palette: chartjsPalette,
+  color: (accent, i, count) => seriesColor(THEME, accent, i, count),
+  ink: () => THEME.ink,
+  family: () => THEME.font,
+  size: (canvas) => chartText(canvas).size,
+  font: chartjsFont,
+  text: chartjsText,
+  label: chartjsLabel,
+  labels: chartjsLegendLabels,
+  grid: chartjsGrid,
+  border: chartjsBorder,
+  baseline: chartjsBaseline,
+  bar: chartjsBar,
+  stacked: chartjsStacked,
+  line: chartjsLine,
+  area: chartjsArea,
+  forecast: chartjsForecast,
+  barColors: chartjsBarColors,
+  doughnut: chartjsDoughnut,
+  legend: chartjsLegend,
+  valueAxis: chartjsValueAxis,
+  categoryAxis: chartjsCategoryAxis,
+};
+
+/* ============================================================================
+   mount — the optional DOM adapter.
+
+   A page marks a chart with `class="echart" data-chart` and puts its config in a
+   child `<script type="application/json">`; the accent comes from the nearest
+   `[data-accent]` ancestor, which is the same attribute `tokens.css` switches the
+   accent modes on. Nothing here is required to use the theme — a React or Vue
+   consumer calls `buildOption` itself — but the two hard-won behaviours below are
+   worth carrying rather than rediscovering.
+   ============================================================================ */
+
+/** Re-fit every chart in `root` to its container's CURRENT size, rebuilding the
+ *  px-composed donuts (their ring and legend are laid out from the real box). */
+function refit(root) {
+  (root || document).querySelectorAll('.echart[data-chart]').forEach((el) => {
+    if (!el.__chart) return;
+    el.__chart.resize();
+    if (el.__cfg && el.__cfg.legend_pct) {
+      el.__chart.setOption(buildOption(el.__cfg, { w: el.clientWidth, h: el.clientHeight }));
+    }
+  });
+}
+
+/** Render every `[data-chart]` element inside `root`. */
+function renderAll(root) {
+  const nodes = (root || document).querySelectorAll('.echart[data-chart]');
+  nodes.forEach((el) => {
+    const src = el.querySelector('script[type="application/json"]');
+    if (!src) return;
+    let cfg;
+    try { cfg = JSON.parse(src.textContent); } catch (e) { console.error('chart json', e); return; }
+    const slideEl = el.closest('[data-accent]');
+    cfg.accent = cfg.accent || (slideEl ? slideEl.getAttribute('data-accent') : 'blue');
+    if (el.__ro) { el.__ro.disconnect(); el.__ro = null; }
+    if (el.__chart) { el.__chart.dispose(); }
+    const chart = echarts.init(el, null, { renderer: 'svg' });
+    chart.setOption(buildOption(cfg, { w: el.clientWidth, h: el.clientHeight }));
+    el.__chart = chart;
+    el.__cfg = cfg;   // kept for live re-layout while the host card is resized
+    // Keep the chart fitted to its container WHENEVER the container changes size —
+    // font load, a caption growing as the user types, a card resize. ECharts otherwise
+    // keeps its initial SVG size and the plot overlaps the caption until something else
+    // forces a rescale (Fedor 2026-07-14: "the same bug, it goes to normal only if I
+    // click layout mode"). The echart is position:absolute inset:0, so resizing it never
+    // changes its own box → no loop.
+    if (window.ResizeObserver) {
+      let raf = 0;
+      const ro = new ResizeObserver(() => {
+        if (raf) return;
+        raf = requestAnimationFrame(() => {
+          raf = 0;
+          if (!el.__chart) return;
+          el.__chart.resize();
+          if (el.__cfg && el.__cfg.legend_pct) {
+            el.__chart.setOption(buildOption(el.__cfg, { w: el.clientWidth, h: el.clientHeight }));
+          }
+        });
+      });
+      ro.observe(el);
+      el.__ro = ro;
+    }
+  });
+  // The house readiness flag: a print or export path waits on it before it shoots
+  // the page, because an unfinished chart exports as an empty box.
+  window.__chartsReady = true;
+  // Belt-and-suspenders for the initial paint / no-ResizeObserver: re-fit once
+  // webfonts settle (a caption reflows to its real height on font swap).
+  if (document.fonts && document.fonts.ready) {
+    document.fonts.ready.then(() => refit(root));
+  }
+}
+
+/* ============================================================================
+   api — what the package is, from the outside.
+
+   `dist/pepper-charts.js` assigns this to `window.PepperCharts`; the ESM build
+   exports it as the default and every member by name. The four names Paggy's own
+   code already calls — `renderAll`, `buildOption`, `refit`, `valueFormatter` —
+   keep their signatures exactly, so adopting the package is a delivery, not a
+   rewrite.
+   ============================================================================ */
+const PepperCharts = {
+  /** the package version, and the token build it was generated from */
+  version: VERSION,
+  /** the GENERATED theme: palettes, ink, grid, rest, on-fill, type. Read it, do
+   *  not write it — every value traces to a token through `theme.$sources`. */
+  theme: THEME,
+  /** the chart-recipe geometry (radii, legend markers, grid lanes, donut ring) */
+  geometry: GEOMETRY,
+
+  /* the palette */
+  /** series `i` of `accent`; pass `count` so a TWO-series chart gets RULE 12's `chart/rest` */
+  seriesColor: (accent, i, count) => seriesColor(THEME, accent, i, count),
+  palette,
+  sliceColor: (accent, labels, i, explicit) => sliceColor(THEME, accent, labels, i, explicit),
+  /** the ink of a label written inside `fill` — the accent's own on a main fill, `onFill` elsewhere (D110) */
+  labelInk: (fill) => labelInk(THEME, fill),
+
+  /* the rules */
+  narrowBandFloor,
+  isTwoSlice,
+  /** RULE 9 — one colour per bar for a one-series chart: 'flat' (the accent's
+   *  chart/1), 'tints' (its chart/1–5) or 'multicolor' (the red→yellow→blue→gray
+   *  cycle). All three are correct; this is where every channel reads them. */
+  barColors: (accent, n, treatment) => barColors(THEME, accent, n, treatment),
+  /** RULES 3 and 4 — the four-corner radius of a bar; `stack` is 'last' for the
+   *  top segment of a stack and 'mid' for the ones below it */
+  barRadius,
+  /** the rendered width of a string in the chart's own type (RULE 7, D16) */
+  textWidth,
+  /** a hex at an opacity, as rgba — RULE 10's band in the renderer that wants one value */
+  withAlpha,
+
+  /* the numbers */
+  valueFormatter,
+  formatter,
+
+  /* ECharts */
+  echartsTheme,
+  buildOption,
+
+  /* Chart.js — the same theme as pieces to spread into its options */
+  chartjs,
+
+  /* the DOM adapter */
+  renderAll,
+  refit,
+};
+
+export { PepperCharts as default, PepperCharts, THEME, GEOMETRY, VERSION,
+  buildOption, echartsTheme, chartjs, valueFormatter, formatter, palette, seriesColor, sliceColor,
+  narrowBandFloor, isTwoSlice, chartText, renderAll, refit };