onbuzz 4.9.1 → 4.9.7

package/src/tools/office/pres/archetypes/table.js

@@ -0,0 +1,74 @@
+/**
+ * Archetype: table — title + a striped data table.
+ *
+ * Slots:
+ *   - title     (optional)
+ *   - headers   (required) array of column header strings
+ *   - rows      (required) array of arrays — one inner array per row
+ *
+ * Stripes use the palette's `surface` colour for odd rows; numeric-
+ * looking cells right-align automatically. Data-heavy renders numbers
+ * in monospace.
+ */
+import { applyChrome, placeText } from './_helpers.js';
+import { textStyle } from '../typography.js';
+
+export const id = 'table';
+export const slots = ['title', 'headers', 'rows'];
+
+function isNumeric(value) {
+  if (value === null || value === undefined) return false;
+  const s = String(value).replace(/[\s,$%]/g, '');
+  return s !== '' && !isNaN(Number(s));
+}
+
+export default function render(slide, resolved, content, _pptx, ctx) {
+  applyChrome(slide, resolved, { bgOverride: content.background, seed: 73, ctx });
+
+  const cfg = resolved.archetypeConfig('table');
+  const { header, body } = resolved.spacing;
+
+  placeText(slide, resolved, 'title', content.title, {
+    x: header.x, y: header.y, w: header.w, h: 0.7,
+  }, { color: resolved.palette.text, align: 'left' });
+
+  const headers = content.headers || [];
+  const rows = content.rows || [];
+  if (headers.length === 0) return;
+
+  // Header row
+  const headerRow = headers.map(h => ({
+    text: String(h ?? ''),
+    options: {
+      bold: true,
+      color: resolved.palette.text,
+      fontFace: resolved.typography.subtitle.fontFace,
+      fontSize: resolved.typography.body.fontSize,
+      fill: { color: resolved.palette.surface },
+      align: 'left',
+    },
+  }));
+
+  // Data rows
+  const monoFont = cfg.monospaceNumbers ? resolved.typography.mono.fontFace : null;
+  const tableRows = rows.map((row, i) => row.map((cell) => {
+    const numeric = isNumeric(cell);
+    const fontFace = (numeric && monoFont) ? monoFont : resolved.typography.body.fontFace;
+    return {
+      text: cell === null || cell === undefined ? '' : String(cell),
+      options: {
+        color: resolved.palette.text,
+        fontFace,
+        fontSize: resolved.typography.body.fontSize,
+        align: numeric ? 'right' : 'left',
+        fill: (cfg.striped && i % 2 === 1) ? { color: resolved.palette.surface } : undefined,
+      },
+    };
+  }));
+
+  slide.addTable([headerRow, ...tableRows], {
+    x: body.x, y: body.y, w: body.w, h: body.h,
+    border: { type: 'solid', pt: 0.5, color: resolved.palette.subtle },
+    autoPage: false,
+  });
+}

package/src/tools/office/pres/archetypes/twoColChart.js

@@ -0,0 +1,61 @@
+/**
+ * Archetype: twoColChart — text on the left, chart on the right.
+ *
+ * Slots:
+ *   - title       (optional) header text
+ *   - leftText  { headline, body }   (required)
+ *   - chart     { type, ... }        (required) — see pres/charts
+ *
+ * tech-bold puts the chart inside a surface-coloured card with soft
+ * shadow; editorial and data-heavy leave it inline.
+ */
+import { applyChrome, callout, placeText } from './_helpers.js';
+import { resolveChart } from '../charts/index.js';
+
+export const id = 'twoColChart';
+export const slots = ['title', 'leftText', 'chart'];
+
+export default function render(slide, resolved, content, pptx, ctx) {
+  applyChrome(slide, resolved, { bgOverride: content.background, seed: 47, ctx });
+
+  const cfg = resolved.archetypeConfig('twoColChart');
+  const { header, body, col } = resolved.spacing;
+
+  placeText(slide, resolved, 'title', content.title, {
+    x: header.x, y: header.y, w: header.w, h: 0.7,
+  }, { color: resolved.palette.text, align: 'left' });
+
+  // Left text column — 5/12 of the grid.
+  const left = { ...col(1, 5), y: body.y, h: body.h };
+  if (content.leftText) {
+    placeText(slide, resolved, 'subtitle', content.leftText.headline, {
+      x: left.x, y: left.y, w: left.w, h: 0.6,
+    }, { color: resolved.palette.primary, align: 'left', bold: true });
+
+    placeText(slide, resolved, 'body', content.leftText.body, {
+      x: left.x, y: left.y + 0.7, w: left.w, h: left.h - 0.7,
+    }, { color: resolved.palette.text, align: 'left', valign: 'top' });
+  }
+
+  // Right chart column — 7/12 of the grid.
+  const right = { ...col(6, 7), y: body.y, h: body.h };
+
+  if (cfg.chartElevated) {
+    callout(slide, resolved, right, resolved.palette.surface);
+  }
+
+  const chartSpec = resolveChart(content.chart, resolved);
+  if (chartSpec && pptx) {
+    const padding = resolved.spacing.blockPadding;
+    const chartFrame = {
+      x: right.x + (cfg.chartElevated ? padding : 0),
+      y: right.y + (cfg.chartElevated ? padding : 0),
+      w: right.w - (cfg.chartElevated ? padding * 2 : 0),
+      h: right.h - (cfg.chartElevated ? padding * 2 : 0),
+    };
+    slide.addChart(pptx.ChartType[chartSpec.type] || chartSpec.type, chartSpec.data, {
+      ...chartFrame,
+      ...chartSpec.opts,
+    });
+  }
+}

package/src/tools/office/pres/archetypes/twoColText.js

@@ -0,0 +1,40 @@
+/**
+ * Archetype: twoColText — title + two text columns side by side.
+ *
+ * Slots:
+ *   - title         (optional)
+ *   - left  { headline, body }   (required)
+ *   - right { headline, body }   (required)
+ *
+ * Each column shares one column of the 12-col grid (6 wide each with
+ * a single gutter between). Headlines render in subtitle weight,
+ * body text in body weight, both colored from the palette.
+ */
+import { applyChrome, placeText } from './_helpers.js';
+
+export const id = 'twoColText';
+export const slots = ['title', 'left', 'right'];
+
+export default function render(slide, resolved, content, _pptx, ctx) {
+  applyChrome(slide, resolved, { bgOverride: content.background, seed: 41, ctx });
+
+  const { header, body, col } = resolved.spacing;
+
+  placeText(slide, resolved, 'title', content.title, {
+    x: header.x, y: header.y, w: header.w, h: 0.7,
+  }, { color: resolved.palette.text, align: 'left' });
+
+  const leftFrame  = { ...col(1, 6),  y: body.y, h: body.h };
+  const rightFrame = { ...col(7, 6),  y: body.y, h: body.h };
+
+  for (const [frame, side] of [[leftFrame, content.left], [rightFrame, content.right]]) {
+    if (!side) continue;
+    placeText(slide, resolved, 'subtitle', side.headline, {
+      x: frame.x, y: frame.y, w: frame.w, h: 0.6,
+    }, { color: resolved.palette.primary, align: 'left', bold: true });
+
+    placeText(slide, resolved, 'body', side.body, {
+      x: frame.x, y: frame.y + 0.7, w: frame.w, h: frame.h - 0.7,
+    }, { color: resolved.palette.text, align: 'left', valign: 'top' });
+  }
+}

package/src/tools/office/pres/backgrounds/geometric.js

@@ -0,0 +1,74 @@
+/**
+ * Background: geometric.
+ *
+ * Decorative shapes in corners + along edges. Style depends on the
+ * theme's decoration config:
+ *   - editorial: small hairline rules, a single accent square
+ *   - tech:      diagonal slashes, soft blobs in corners
+ *   - data:      a single thin underline + a tiny corner tick
+ *
+ * Always backgrounded — sits behind content but in front of `bg`.
+ */
+import { SLIDE_DIMENSIONS } from '../grid.js';
+import { shade } from '../palettes.js';
+
+export default function applyGeometric(slide, resolved) {
+  slide.background = { color: resolved.palette.bg };
+  const style = resolved.decoration?.geometric?.style || resolved.theme.family;
+  const density = resolved.decoration?.geometric?.density || 'medium';
+
+  if (style === 'editorial') {
+    // A small accent square in the bottom-right + a hairline rule at top.
+    slide.addShape('rect', {
+      x: SLIDE_DIMENSIONS.width - 0.7,
+      y: SLIDE_DIMENSIONS.height - 0.7,
+      w: 0.35, h: 0.35,
+      fill: { color: resolved.palette.accent, transparency: 30 },
+      line: { type: 'none' },
+    });
+    if (density !== 'minimal') {
+      slide.addShape('line', {
+        x: 0.4, y: 0.32, w: 1.8, h: 0,
+        line: { color: resolved.palette.primary, width: 1 },
+      });
+    }
+  } else if (style === 'tech') {
+    // A large soft blob in the top-right + a diagonal accent line in
+    // the bottom-left. Reads as "modern keynote".
+    slide.addShape('ellipse', {
+      x: SLIDE_DIMENSIONS.width - 3.5,
+      y: -1.5,
+      w: 5, h: 4,
+      fill: { color: resolved.palette.primary, transparency: 70 },
+      line: { type: 'none' },
+    });
+    slide.addShape('ellipse', {
+      x: -1.5,
+      y: SLIDE_DIMENSIONS.height - 1.5,
+      w: 3.5, h: 3.5,
+      fill: { color: resolved.palette.accent, transparency: 75 },
+      line: { type: 'none' },
+    });
+    if (density !== 'minimal') {
+      slide.addShape('line', {
+        x: 0.6, y: SLIDE_DIMENSIONS.height - 0.4, w: 1.6, h: 0,
+        line: { color: resolved.palette.accent, width: 1.5 },
+      });
+    }
+  } else if (style === 'data') {
+    // A single thin "rule" under the header + a tiny corner tick.
+    slide.addShape('rect', {
+      x: 0, y: SLIDE_DIMENSIONS.height - 0.06,
+      w: SLIDE_DIMENSIONS.width, h: 0.06,
+      fill: { color: shade(resolved.palette.subtle, 60), transparency: 50 },
+      line: { type: 'none' },
+    });
+    slide.addShape('rect', {
+      x: SLIDE_DIMENSIONS.width - 0.5,
+      y: 0,
+      w: 0.5, h: 0.06,
+      fill: { color: resolved.palette.primary },
+      line: { type: 'none' },
+    });
+  }
+}

package/src/tools/office/pres/backgrounds/gradient.js

@@ -0,0 +1,38 @@
+/**
+ * Background: linear gradient (palette → shaded palette).
+ *
+ * pptxgenjs's slide.background has limited gradient support, so we
+ * place a full-slide rect with a two-stop linear gradient fill BEHIND
+ * everything else. This works identically in PowerPoint, Keynote, and
+ * Google Slides.
+ *
+ * Direction: 45° from top-left to bottom-right. Two stops derived from
+ * the palette: `bg` ↔ `bg shaded toward primary` for a subtle tint.
+ */
+import { SLIDE_DIMENSIONS } from '../grid.js';
+import { mix } from '../palettes.js';
+
+export default function applyGradient(slide, resolved) {
+  // Solid fallback so the slide isn't transparent if the gradient shape
+  // renders late.
+  slide.background = { color: resolved.palette.bg };
+
+  const stop0 = resolved.palette.bg;
+  const stop1 = mix(resolved.palette.bg, resolved.palette.primary, 0.18);
+
+  slide.addShape('rect', {
+    x: 0, y: 0,
+    w: SLIDE_DIMENSIONS.width,
+    h: SLIDE_DIMENSIONS.height,
+    fill: {
+      type: 'gradient',
+      gradientType: 'linear',
+      angle: 135,
+      stops: [
+        { pos: 0,   color: stop0 },
+        { pos: 100, color: stop1 },
+      ],
+    },
+    line: { type: 'none' },
+  });
+}

package/src/tools/office/pres/backgrounds/grid.js

@@ -0,0 +1,35 @@
+/**
+ * Background: grid (faint reference grid).
+ *
+ * Data-heavy uses this. Thin horizontal + vertical lines at the theme's
+ * configured `spacing` interval, drawn in `subtle` colour with high
+ * transparency so they never compete with content.
+ *
+ * Reads as "this deck takes itself seriously about numbers."
+ */
+import { SLIDE_DIMENSIONS } from '../grid.js';
+
+export default function applyGrid(slide, resolved) {
+  slide.background = { color: resolved.palette.bg };
+
+  const spacing = resolved.decoration?.grid?.spacing || 0.5;
+  const opacity = resolved.decoration?.grid?.lineOpacity || 8; // 0–100, lower = fainter
+  const lineColor = resolved.palette.subtle;
+  const transparency = 100 - opacity;
+
+  // Horizontal lines.
+  for (let y = spacing; y < SLIDE_DIMENSIONS.height; y += spacing) {
+    slide.addShape('line', {
+      x: 0, y, w: SLIDE_DIMENSIONS.width, h: 0,
+      line: { color: lineColor, width: 0.5, transparency },
+    });
+  }
+
+  // Vertical lines.
+  for (let x = spacing; x < SLIDE_DIMENSIONS.width; x += spacing) {
+    slide.addShape('line', {
+      x, y: 0, w: 0, h: SLIDE_DIMENSIONS.height,
+      line: { color: lineColor, width: 0.5, transparency },
+    });
+  }
+}

package/src/tools/office/pres/backgrounds/index.js

@@ -0,0 +1,38 @@
+/**
+ * pres/backgrounds — dispatch for the six background styles.
+ *
+ * Every style is a function `(slide, resolved, opts)` that mutates the
+ * pptxgenjs slide in-place, adding a background colour + any decorative
+ * shapes that sit behind content. Archetypes can call this once per
+ * slide; the global theme picks the default style, per-slide overrides
+ * win.
+ */
+import solid from './solid.js';
+import gradient from './gradient.js';
+import mesh from './mesh.js';
+import noise from './noise.js';
+import geometric from './geometric.js';
+import grid from './grid.js';
+import voidBg from './void.js';
+import orb from './orb.js';
+
+const BACKGROUNDS = {
+  solid, gradient, mesh, noise, geometric, grid, void: voidBg, orb,
+};
+
+export function listBackgrounds() {
+  return Object.keys(BACKGROUNDS);
+}
+
+/**
+ * Apply a background style to a slide.
+ *   - `style`: one of solid | gradient | mesh | noise | geometric | grid
+ *   - `resolved`: full resolved theme (palette + decoration config)
+ *   - `opts.seed`: optional integer for deterministic randomisation
+ *
+ * Unknown styles fall back to solid — never errors.
+ */
+export function applyBackground(slide, resolved, style, opts = {}) {
+  const fn = BACKGROUNDS[style] || BACKGROUNDS.solid;
+  fn(slide, resolved, opts);
+}

package/src/tools/office/pres/backgrounds/mesh.js

@@ -0,0 +1,57 @@
+/**
+ * Background: mesh gradient — Stripe / Linear-style 4-corner radials.
+ *
+ * Industry pattern: a deterministic 4-corner radial mesh. One hue per
+ * corner, each blob at ~55% slide diameter, positioned partially
+ * off-canvas so only the soft arc bleeds onto the slide. From a
+ * distance reads as a continuous mesh; up close it's four overlapping
+ * orbs. Hue assignment uses palette roles so the same palette always
+ * produces the same mesh.
+ */
+import { SLIDE_DIMENSIONS } from '../grid.js';
+import { shade } from '../palettes.js';
+
+function isDarkHex(hex) {
+  const s = String(hex).replace(/^#/, '');
+  if (!/^[0-9A-Fa-f]{6}$/.test(s)) return false;
+  const r = parseInt(s.slice(0, 2), 16);
+  const g = parseInt(s.slice(2, 4), 16);
+  const b = parseInt(s.slice(4, 6), 16);
+  return (0.299 * r + 0.587 * g + 0.114 * b) < 110;
+}
+
+export default function applyMesh(slide, resolved, _opts = {}) {
+  const palette = resolved.palette;
+  slide.background = { color: palette.bg };
+
+  const saturation = resolved.decoration?.mesh?.saturation || 'vivid';
+  const blur = resolved.decoration?.mesh?.blur || 'normal';
+  const bgIsDark = isDarkHex(palette.bg);
+  const baseTrans = bgIsDark ? 65 : 80;
+  const blurAdj = blur === 'high' ? 8 : blur === 'low' ? -8 : 0;
+  const transparency = baseTrans + blurAdj;
+
+  const W = SLIDE_DIMENSIONS.width;
+  const H = SLIDE_DIMENSIONS.height;
+  const diameter = W * 0.55;
+  const offset = -W * 0.12;
+  const corners = [
+    { x: offset,                  y: offset,                  color: palette.primary },
+    { x: W - diameter - offset,   y: offset,                  color: palette.accent  },
+    { x: offset,                  y: H - diameter - offset,   color: shade(palette.primary, -20) },
+    { x: W - diameter - offset,   y: H - diameter - offset,   color: palette.highlight || palette.accent },
+  ];
+
+  if (saturation === 'muted') {
+    for (const c of corners) c.color = shade(c.color, bgIsDark ? -25 : 35);
+  }
+
+  for (const c of corners) {
+    slide.addShape('ellipse', {
+      x: c.x, y: c.y, w: diameter, h: diameter,
+      fill: { color: c.color, transparency },
+      line: { type: 'none' },
+    });
+  }
+}
+

package/src/tools/office/pres/backgrounds/noise.js

@@ -0,0 +1,27 @@
+/**
+ * Background: paper-noise.
+ *
+ * Editorial-warm uses this. Subtle warm tint via a single large soft-
+ * edged ellipse in one corner — gives the slide a "this is paper" feel
+ * without needing real raster noise (which would inflate the deck).
+ *
+ * Cheap to render, works everywhere, reads as "this slide is paper."
+ */
+import { SLIDE_DIMENSIONS } from '../grid.js';
+import { shade } from '../palettes.js';
+
+export default function applyNoise(slide, resolved) {
+  slide.background = { color: resolved.palette.bg };
+
+  // A faint warm vignette in the top-right corner — implies natural
+  // paper texture without requiring an embedded image.
+  const tint = shade(resolved.palette.bg, -6);
+  slide.addShape('ellipse', {
+    x: SLIDE_DIMENSIONS.width * 0.55,
+    y: -SLIDE_DIMENSIONS.height * 0.4,
+    w: SLIDE_DIMENSIONS.width * 1.0,
+    h: SLIDE_DIMENSIONS.height * 1.2,
+    fill: { color: tint, transparency: 60 },
+    line: { type: 'none' },
+  });
+}

package/src/tools/office/pres/backgrounds/orb.js

@@ -0,0 +1,66 @@
+/**
+ * Background: orb — Linear-style single soft orb (not Stripe-4-corner-mesh).
+ *
+ * Reference: Linear's product launch decks. ONE big purple-blue blur
+ * orb anchored in the lower-right, positioned partially off-canvas
+ * so only its soft arc bleeds onto the slide. A smaller cyan accent
+ * orb sits diagonally opposite for visual rhythm.
+ *
+ * Distinguished from `mesh` (which uses 4 corner-anchored orbs in
+ * the Stripe Sessions pattern): orb has the orbs in deliberate
+ * dramatic positions, not a uniform corner-fill.
+ */
+import { SLIDE_DIMENSIONS } from '../grid.js';
+import { shade } from '../palettes.js';
+
+function isDarkHex(hex) {
+  const s = String(hex).replace(/^#/, '');
+  if (!/^[0-9A-Fa-f]{6}$/.test(s)) return false;
+  const r = parseInt(s.slice(0, 2), 16);
+  const g = parseInt(s.slice(2, 4), 16);
+  const b = parseInt(s.slice(4, 6), 16);
+  return (0.299 * r + 0.587 * g + 0.114 * b) < 110;
+}
+
+export default function applyOrb(slide, resolved, _opts = {}) {
+  const palette = resolved.palette;
+  slide.background = { color: palette.bg };
+
+  const W = SLIDE_DIMENSIONS.width;
+  const H = SLIDE_DIMENSIONS.height;
+  const bgIsDark = isDarkHex(palette.bg);
+  // On dark themes the orbs need lower transparency to read; on light
+  // themes they need higher (or they overpower content).
+  const mainTrans = bgIsDark ? 55 : 78;
+  const accentTrans = bgIsDark ? 70 : 85;
+
+  // Primary orb — lower-right, large. Drama anchor for the slide.
+  const mainSize = W * 0.7;
+  slide.addShape('ellipse', {
+    x: W * 0.55, y: H * 0.45,
+    w: mainSize, h: mainSize,
+    fill: { color: palette.primary, transparency: mainTrans },
+    line: { type: 'none' },
+  });
+
+  // Accent orb — upper-left, smaller. Counterweight for composition.
+  const accentSize = W * 0.42;
+  slide.addShape('ellipse', {
+    x: -accentSize * 0.4, y: -accentSize * 0.3,
+    w: accentSize, h: accentSize,
+    fill: { color: palette.highlight || palette.accent, transparency: accentTrans },
+    line: { type: 'none' },
+  });
+
+  // Optional darker shaded primary tucked behind the main orb — adds
+  // depth without a second visible orb.
+  if (bgIsDark) {
+    const depthSize = W * 0.5;
+    slide.addShape('ellipse', {
+      x: W * 0.7, y: H * 0.3,
+      w: depthSize, h: depthSize,
+      fill: { color: shade(palette.primary, -30), transparency: 60 },
+      line: { type: 'none' },
+    });
+  }
+}

package/src/tools/office/pres/backgrounds/solid.js

@@ -0,0 +1,10 @@
+/**
+ * Background: solid
+ *
+ * Just sets the slide's `background` colour to the palette's `bg`.
+ * The simplest, most reliable style — no decorative shapes, no
+ * gradient stops, nothing that depends on PPTX renderer fidelity.
+ */
+export default function applySolid(slide, resolved) {
+  slide.background = { color: resolved.palette.bg };
+}

package/src/tools/office/pres/backgrounds/void.js

@@ -0,0 +1,34 @@
+/**
+ * Background: void — Apple-keynote-style near-black with vignette.
+ *
+ * Pure #000 reads too aggressively on screen; #0A0A0A gives the deck
+ * enough warmth to feel "considered". A single very soft centred
+ * vignette (slightly lifted) adds dimensional depth without bringing
+ * colour into the slide.
+ */
+import { SLIDE_DIMENSIONS } from '../grid.js';
+import { shade } from '../palettes.js';
+
+export default function applyVoid(slide, resolved) {
+  const palette = resolved.palette;
+  const voidColor = isDarkHex(palette.bg) ? palette.bg : '0A0A0A';
+  slide.background = { color: voidColor };
+
+  const W = SLIDE_DIMENSIONS.width;
+  const H = SLIDE_DIMENSIONS.height;
+  const lift = shade(voidColor, 8);
+  slide.addShape('ellipse', {
+    x: -W * 0.2, y: -H * 0.2, w: W * 1.4, h: H * 1.4,
+    fill: { color: lift, transparency: 70 },
+    line: { type: 'none' },
+  });
+}
+
+function isDarkHex(hex) {
+  const s = String(hex).replace(/^#/, '');
+  if (!/^[0-9A-Fa-f]{6}$/.test(s)) return false;
+  const r = parseInt(s.slice(0, 2), 16);
+  const g = parseInt(s.slice(2, 4), 16);
+  const b = parseInt(s.slice(4, 6), 16);
+  return (0.299 * r + 0.587 * g + 0.114 * b) < 110;
+}

package/src/tools/office/pres/charts/index.js

@@ -0,0 +1,119 @@
+/**
+ * pres/charts — theme-styled chart wrapper.
+ *
+ * The agent provides data in a simple shape; we resolve colours,
+ * gridlines, and label typography from the active theme and palette,
+ * then return a `(chartType, data, opts)` triple that the archetype
+ * passes to `slide.addChart(...)`.
+ *
+ * Supported shapes:
+ *   { type: 'bar' | 'column' | 'line' | 'area',  categories: [...], series: [{name, data:[...]}, ...] }
+ *   { type: 'pie' | 'donut',                     data: [{ label, value }, ...] }
+ *
+ * Theme decides:
+ *   - colour sequence (from palettes.CHART_SERIES[paletteName])
+ *   - gridline visibility + colour
+ *   - data-label font + size + colour
+ *   - legend placement + typography
+ *   - donut hole size
+ */
+import { CHART_SERIES } from '../palettes.js';
+
+function colorsFor(resolved) {
+  return CHART_SERIES[resolved.palette.name] || [
+    resolved.palette.primary,
+    resolved.palette.accent,
+    resolved.palette.subtle,
+  ];
+}
+
+/**
+ * Resolve a chart spec to (chartType, data, opts) that pptxgenjs
+ * `slide.addChart` accepts. Returns `null` when the spec is malformed
+ * so the archetype can show a fallback panel instead.
+ *
+ * Note: `chartType` is returned as a string identifier (e.g. 'bar',
+ * 'donut'). The archetype maps the string → `pptx.ChartType[...]`
+ * because the ChartType enum is only available on a pptxgenjs instance.
+ */
+export function resolveChart(spec, resolved) {
+  if (!spec || !spec.type) return null;
+  const t = String(spec.type).toLowerCase();
+  const colors = colorsFor(resolved);
+  const family = resolved.theme.family;
+  const typo = resolved.typography;
+
+  const baseOpts = {
+    chartColors: colors,
+    showLegend: spec.showLegend !== false,
+    legendPos: 'r',
+    legendFontFace: typo.caption.fontFace,
+    legendFontSize: typo.caption.fontSize,
+    legendColor: resolved.palette.text,
+
+    catAxisLineShow: family === 'data',
+    valAxisLineShow: family === 'data',
+    catAxisLabelFontFace: typo.caption.fontFace,
+    catAxisLabelFontSize: typo.caption.fontSize,
+    catAxisLabelColor: resolved.palette.subtle,
+    valAxisLabelFontFace: typo.caption.fontFace,
+    valAxisLabelFontSize: typo.caption.fontSize,
+    valAxisLabelColor: resolved.palette.subtle,
+
+    showValue: false,
+    dataLabelFontFace: typo.caption.fontFace,
+    dataLabelFontSize: typo.caption.fontSize,
+    dataLabelColor: resolved.palette.text,
+
+    // Gridline policy: editorial = none, tech = light, data = visible.
+    valGridLine: family === 'editorial'
+      ? { style: 'none' }
+      : family === 'tech'
+        ? { color: resolved.palette.subtle, size: 0.5, transparency: 70 }
+        : { color: resolved.palette.subtle, size: 0.5, transparency: 30 },
+    catGridLine: { style: 'none' },
+  };
+
+  if (t === 'pie' || t === 'donut') {
+    const items = Array.isArray(spec.data) ? spec.data : [];
+    const data = [{
+      name: spec.name || 'Series',
+      labels: items.map(d => String(d.label ?? '')),
+      values: items.map(d => Number(d.value) || 0),
+    }];
+    const opts = {
+      ...baseOpts,
+      showPercent: spec.showPercent !== false,
+      holeSize: t === 'donut' ? (spec.holeSize ?? 60) : 0,
+      dataLabelPosition: t === 'donut' ? 'outEnd' : 'bestFit',
+    };
+    return { type: t === 'donut' ? 'doughnut' : 'pie', data, opts };
+  }
+
+  // bar / column / line / area: same data shape.
+  const categories = Array.isArray(spec.categories) ? spec.categories : [];
+  const series = Array.isArray(spec.series) ? spec.series : [];
+  const data = series.map(s => ({
+    name: s.name || 'Series',
+    labels: categories.map(c => String(c)),
+    values: (s.data || []).map(v => Number(v) || 0),
+  }));
+
+  const opts = { ...baseOpts };
+  if (t === 'bar') {
+    opts.barDir = 'bar';
+    opts.barGrouping = spec.stacked ? 'stacked' : 'clustered';
+  } else if (t === 'column') {
+    opts.barDir = 'col';
+    opts.barGrouping = spec.stacked ? 'stacked' : 'clustered';
+  } else if (t === 'line') {
+    opts.lineDataSymbol = 'circle';
+    opts.lineDataSymbolSize = 5;
+    opts.lineSize = 2.5;
+  } else if (t === 'area') {
+    opts.fill = colors[0];
+  }
+  // pptxgenjs uses 'bar' for both bar + column (direction differs).
+  const pptxType = (t === 'column' || t === 'bar') ? 'bar' : t;
+  return { type: pptxType, data, opts };
+}