onbuzz 4.9.1 → 4.9.7

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

@@ -0,0 +1,136 @@
+/**
+ * pres/grid — slide geometry + layout math.
+ *
+ * pptxgenjs uses inches as its default unit. The 16:9 wide layout is
+ * 13.333 × 7.5 inches. Everything in the new presentation system is
+ * expressed against this grid so the agent never has to think in pixels
+ * or coordinates — it picks an archetype + spacing density, and the
+ * grid resolves to (x, y, w, h) tuples for pptxgenjs to consume.
+ *
+ * Grid model:
+ *   - 12-column layout (rounded to PPTX-friendly inch fractions)
+ *   - safe-area = full slide minus pageMargin on all sides
+ *   - vertical baseline of 0.25" so type sits on a rhythm
+ *
+ * spacing presets dial the same five knobs (page margin, content gutter,
+ * paragraph gap, header-to-body gap, footer reservation). Changing one
+ * preset restyles every archetype because every archetype reads from
+ * `metrics` and never hardcodes numbers.
+ */
+
+export const SLIDE_DIMENSIONS = {
+  width:  13.333,
+  height: 7.5,
+};
+
+const SPACING_PRESETS = {
+  tight: {
+    pageMargin:       0.4,
+    contentGutter:    0.2,
+    paragraphGap:     0.08,
+    headerBodyGap:    0.2,
+    footerReserve:    0.35,
+    blockPadding:     0.18,
+  },
+  cozy: {
+    pageMargin:       0.6,
+    contentGutter:    0.35,
+    paragraphGap:     0.14,
+    headerBodyGap:    0.35,
+    footerReserve:    0.45,
+    blockPadding:     0.28,
+  },
+  airy: {
+    pageMargin:       0.9,
+    contentGutter:    0.55,
+    paragraphGap:     0.22,
+    headerBodyGap:    0.55,
+    footerReserve:    0.6,
+    blockPadding:     0.4,
+  },
+};
+
+/**
+ * Resolve a spacing preset to absolute metrics + derived helpers.
+ * The agent passes 'tight' | 'cozy' | 'airy' (or omits for 'cozy').
+ */
+export function resolveSpacing(preset = 'cozy') {
+  const base = SPACING_PRESETS[preset] || SPACING_PRESETS.cozy;
+  const { width, height } = SLIDE_DIMENSIONS;
+  const m = base.pageMargin;
+
+  // Safe-area inside the page margins.
+  const safe = {
+    x: m,
+    y: m,
+    w: width  - m * 2,
+    h: height - m * 2,
+  };
+
+  // 12-column grid inside the safe area.
+  const colCount = 12;
+  const colW = (safe.w - base.contentGutter * (colCount - 1)) / colCount;
+
+  /**
+   * Convert a (col, span) pair → { x, w }. Both are 1-based for
+   * readability (col 1 starts at the left margin). Useful for the
+   * two-column / three-column archetypes that the agent can pick
+   * without thinking in inches.
+   */
+  function col(start, span) {
+    const c0 = Math.max(1, Math.min(colCount, start));
+    const cs = Math.max(1, Math.min(colCount - c0 + 1, span));
+    const x = safe.x + (c0 - 1) * (colW + base.contentGutter);
+    const w = cs * colW + (cs - 1) * base.contentGutter;
+    return { x, w };
+  }
+
+  /** Standard header band the title sits in. */
+  const header = {
+    x: safe.x,
+    y: safe.y,
+    w: safe.w,
+    h: 0.9,
+  };
+
+  /** Body area below the header. */
+  const body = {
+    x: safe.x,
+    y: header.y + header.h + base.headerBodyGap,
+    w: safe.w,
+    h: safe.h - (header.h + base.headerBodyGap + base.footerReserve),
+  };
+
+  /** Footer strip reserved at the bottom. */
+  const footer = {
+    x: safe.x,
+    y: height - m - base.footerReserve,
+    w: safe.w,
+    h: base.footerReserve,
+  };
+
+  return {
+    preset,
+    ...base,
+    slide: SLIDE_DIMENSIONS,
+    safe,
+    header,
+    body,
+    footer,
+    colCount,
+    colWidth: colW,
+    col,
+  };
+}
+
+/**
+ * Centered box inside a region — used for hero / quote / closing
+ * archetypes where the content sits in the middle of the slide.
+ */
+export function centerBox(region, w, h) {
+  return {
+    x: region.x + (region.w - w) / 2,
+    y: region.y + (region.h - h) / 2,
+    w, h,
+  };
+}

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

@@ -0,0 +1,100 @@
+/**
+ * pres — themed presentation builder.
+ *
+ * Public entry. Takes the spec the agent provides + an output path,
+ * builds the pptx via pptxgenjs, writes to disk, returns metadata.
+ *
+ * Spec shape:
+ *   {
+ *     title, subject, author, company,
+ *     theme: 'editorial-warm' | 'tech-bold' | 'data-heavy',
+ *     palette, spacing, shape, background,   // optional overrides
+ *     slides: [
+ *       { archetype: 'hero', title, subtitle, eyebrow, ... },
+ *       { archetype: 'agenda', items: [...] },
+ *       ...
+ *     ]
+ *   }
+ *
+ * The new system is opt-in by passing a STRING `theme`. The legacy
+ * shape (theme as an object) is still routed to the old createPres
+ * by the caller in officePres.js.
+ */
+import fs from 'fs/promises';
+import { createRequire } from 'module';
+
+import { resolveTheme, listThemes } from './themes/index.js';
+import { renderArchetype, listArchetypes } from './archetypes/index.js';
+import { listBackgrounds } from './backgrounds/index.js';
+import { defineMasters, buildDeckContext, usesChrome } from './master.js';
+
+const localRequire = createRequire(import.meta.url);
+let pptxgen = null;
+function loadPptx() {
+  if (pptxgen) return pptxgen;
+  const mod = localRequire('pptxgenjs');
+  pptxgen = mod.default || mod;
+  return pptxgen;
+}
+
+/**
+ * Detect the new-format spec — distinguishes from the legacy shape so
+ * officePres.createPres() can route appropriately.
+ */
+export function isThemedSpec(spec) {
+  return !!(spec && typeof spec.theme === 'string');
+}
+
+/** Discovery helpers — used by the verifier + tool description builder. */
+export function listSystem() {
+  return {
+    themes: listThemes(),
+    archetypes: listArchetypes(),
+    backgrounds: listBackgrounds(),
+  };
+}
+
+/**
+ * Build a themed presentation. Returns {path, size, slideCount, theme}.
+ */
+export async function buildThemedPres(spec, outputPath) {
+  const Pptx = loadPptx();
+  const pptx = new Pptx();
+
+  pptx.title = spec.title || '';
+  pptx.subject = spec.subject || '';
+  pptx.author = spec.author || 'Loxia Agent';
+  pptx.company = spec.company || '';
+  pptx.layout = 'LAYOUT_WIDE';
+
+  const resolved = resolveTheme(spec);
+  const { slides, context } = buildDeckContext(spec);
+
+  // Two slide masters per deck so we can apply consistent bg/chrome
+  // and let pptxgenjs dedupe the static parts at file-size level.
+  const masters = defineMasters(pptx, resolved);
+
+  for (let i = 0; i < slides.length; i++) {
+    const slideSpec = slides[i];
+    const ctx = context[i];
+    const masterName = usesChrome(slideSpec.archetype || 'freeform')
+      ? masters.CHROME
+      : masters.BARE;
+    const slide = pptx.addSlide({ masterName });
+    renderArchetype(slide, resolved, slideSpec, pptx, ctx);
+  }
+
+  const buf = await pptx.write({ outputType: 'nodebuffer' });
+  await fs.writeFile(outputPath, buf);
+  const stat = await fs.stat(outputPath);
+  return {
+    path: outputPath,
+    size: stat.size,
+    slideCount: slides.length,
+    theme: resolved.theme.id,
+    palette: resolved.palette.name,
+    spacing: resolved.spacing.preset,
+    shape: resolved.shape.preset,
+    background: resolved.bg,
+  };
+}

package/src/tools/office/pres/master.js

@@ -0,0 +1,107 @@
+/**
+ * pres/master — slide master + deck-level context.
+ *
+ * pptxgenjs's `defineSlideMaster` lets us put recurring chrome (bg
+ * colour, static brand strip, page-number placeholder, decorative
+ * accent shapes) in one place so the file size shrinks and every
+ * slide stays in lockstep visually. The dynamic per-slide chrome
+ * (section name + slide-number text + section progress dots) still
+ * lives on the slide itself — pptxgenjs's master placeholders can't
+ * read per-slide data.
+ *
+ * The deck context is computed once per build: it tracks which
+ * section each slide belongs to (by walking the slide list and
+ * resetting on every sectionHeader archetype) so the chrome can show
+ * "01 / 04" indicators without the agent labelling each slide.
+ */
+import { SLIDE_DIMENSIONS } from './grid.js';
+
+/** Archetypes that intentionally suppress header/footer chrome. */
+const BARE_ARCHETYPES = new Set([
+  'hero', 'sectionHeader', 'closing', 'imageFullBleed',
+  'headlineMessage', 'productHero',
+]);
+
+/** True iff this archetype should render with the chrome master. */
+export function usesChrome(archetypeId) {
+  return !BARE_ARCHETYPES.has(archetypeId);
+}
+
+/**
+ * Define one slide master per theme. We register two variants:
+ *   LOXIA_BARE   — used by hero / section / closing / imageFullBleed
+ *                  (background only; archetype owns the entire canvas)
+ *   LOXIA_CHROME — used by everything else; same background + an
+ *                  ultra-thin accent stripe at top (the dynamic
+ *                  section name + page number sit on the slide via
+ *                  headerChrome/footerChrome).
+ *
+ * Returns the names so the caller can pick the right one per slide.
+ */
+export function defineMasters(pptx, resolved) {
+  const palette = resolved.palette;
+
+  pptx.defineSlideMaster({
+    title: 'LOXIA_BARE',
+    background: { color: palette.bg },
+    objects: [],
+  });
+
+  pptx.defineSlideMaster({
+    title: 'LOXIA_CHROME',
+    background: { color: palette.bg },
+    objects: [
+      // Top accent hairline — the single piece of static chrome the
+      // master can place. Section name + page number are dynamic and
+      // are added per slide.
+      { rect: { x: 0, y: 0, w: SLIDE_DIMENSIONS.width, h: 0.04, fill: { color: palette.primary } } },
+    ],
+  });
+
+  return { BARE: 'LOXIA_BARE', CHROME: 'LOXIA_CHROME' };
+}
+
+/**
+ * Pre-compute a context for every slide so archetypes can render
+ * section progress / page numbers without the agent labelling each
+ * slide manually.
+ *
+ *   { slides: [...originalSlides], context: [{slideIndex, totalSlides,
+ *     sectionName, sectionIdx, sectionTotal, brand, isSectionStart}] }
+ */
+export function buildDeckContext(spec) {
+  const slides = Array.isArray(spec.slides) ? spec.slides : [];
+  const totalSlides = slides.length;
+
+  // First pass: collect sections (sectionHeader slides) so we know
+  // how many total + what their names are.
+  const sections = [];
+  slides.forEach((s, i) => {
+    if (s.archetype === 'sectionHeader') {
+      sections.push({ idx: sections.length, slideIndex: i, name: s.title || `Section ${sections.length + 1}` });
+    }
+  });
+  const sectionTotal = sections.length;
+
+  // Second pass: assign each slide to a section based on which
+  // sectionHeader came before it.
+  const context = [];
+  let currentSectionIdx = -1;
+  for (let i = 0; i < slides.length; i++) {
+    if (slides[i].archetype === 'sectionHeader') {
+      currentSectionIdx++;
+    }
+    const sectionName = currentSectionIdx >= 0 ? sections[currentSectionIdx].name : null;
+    context.push({
+      slideIndex: i,
+      totalSlides,
+      sectionName,
+      sectionIdx: Math.max(0, currentSectionIdx),
+      sectionTotal,
+      brand: spec.company || spec.title || '',
+      isSectionStart: slides[i].archetype === 'sectionHeader',
+    });
+  }
+
+  return { slides, context };
+}

package/src/tools/office/pres/palettes.js

@@ -0,0 +1,258 @@
+/**
+ * pres/palettes — named palettes with six semantic roles.
+ *
+ * Every component (text, shape, chart, divider, background) reads from
+ * the six roles. Swapping a palette restyles the entire deck because
+ * nothing hardcodes a hex.
+ *
+ * Roles:
+ *   bg       — slide background (or base background under decoration)
+ *   surface  — cards, callouts, light blocks placed on top of bg
+ *   text     — primary body text colour
+ *   subtle   — captions, secondary labels, muted dividers
+ *   primary  — brand-leading accent: titles, key data points, CTAs
+ *   accent   — secondary accent: highlights, chart series #2, eyebrows
+ *
+ * Hex strings are stored without the leading "#" because pptxgenjs
+ * accepts both but the no-# form is canonical in PPTX XML.
+ */
+
+/**
+ * Palette = 8 semantic roles:
+ *   bg        slide background
+ *   surface   raised panels / cards / soft callouts
+ *   text      primary body colour
+ *   subtle    captions, dividers, secondary labels
+ *   primary   the deck's leading accent — titles, key data, primary CTAs
+ *   accent    secondary accent — chart series #2, eyebrows, links
+ *   ink       deepest emphasis — headlines that need to shout, pull-quote glyphs
+ *   highlight bright marker colour — pill backgrounds, badges, tag chips
+ *             (deliberately distinct from `accent` so component chrome has its own slot)
+ */
+export const PALETTES = {
+  // ─── editorial-warm family ─────────────────────────────────────────
+  'cream-charcoal': {
+    family: 'editorial',
+    bg:        'FAF6EE',
+    surface:   'FFFFFF',
+    text:      '1A1A1A',
+    subtle:    '7A7368',
+    primary:   'C04A2D',
+    accent:    'E0B872',
+    ink:       '0E0908',
+    highlight: 'E5594F',
+  },
+  'ink-paper': {
+    family: 'editorial',
+    bg:        'FCFCF7',
+    surface:   'FFFFFF',
+    text:      '0E0E0E',
+    subtle:    '5A5A5A',
+    primary:   '1B1B1B',
+    accent:    'B89060',
+    ink:       '000000',
+    highlight: 'FFE45E',
+  },
+  'mint-charcoal': {
+    family: 'editorial',
+    bg:        'F2F7F4',
+    surface:   'FFFFFF',
+    text:      '1A2620',
+    subtle:    '6A7B73',
+    primary:   '2E5E50',
+    accent:    'A8C9B4',
+    ink:       '0A1410',
+    highlight: 'FFB300',
+  },
+
+  // ─── tech-bold family ──────────────────────────────────────────────
+  'electric-night': {
+    family: 'tech',
+    bg:        '0A0E1B',
+    surface:   '151B2E',
+    text:      'F5F7FA',
+    subtle:    '8A93A8',
+    primary:   '5B8DEF',
+    accent:    'F25F4C',
+    ink:       'FFFFFF',
+    highlight: 'FFD166',
+  },
+  'cyber-dawn': {
+    family: 'tech',
+    bg:        'FFFFFF',
+    surface:   'F4F6FA',
+    text:      '0A0E1B',
+    subtle:    '6E7488',
+    primary:   '4F6DF5',
+    accent:    'F25F4C',
+    ink:       '000000',
+    highlight: '14B8A6',
+  },
+  'neon-violet': {
+    family: 'tech',
+    bg:        '0F0A1B',
+    surface:   '1A1330',
+    text:      'F5F0FF',
+    subtle:    '8E84B5',
+    primary:   'A87FFF',
+    accent:    'FFD166',
+    ink:       'FFFFFF',
+    highlight: 'FF6FA3',
+  },
+  // Linear product palette — explicitly WARM grays (not blue-grays).
+  // Background #08090A, surface #1C1D1F, text #F7F8F8 — matches
+  // Linear's post-refresh dark mode tone. Purple orb #5E6AD2 lives in
+  // the primary slot for hero accent moments.
+  'linear-product': {
+    family: 'tech',
+    bg:        '08090A',
+    surface:   '1C1D1F',
+    text:      'F7F8F8',
+    subtle:    '9A9CA0',
+    primary:   '5E6AD2',
+    accent:    '7B68EE',
+    ink:       'FFFFFF',
+    highlight: '4EA8DE',
+  },
+
+  // ─── data-heavy family ─────────────────────────────────────────────
+  'bloomberg': {
+    family: 'data',
+    bg:        'FFFFFF',
+    surface:   'F4F4F4',
+    text:      '1A1A1A',
+    subtle:    '6B6B6B',
+    primary:   'FF6600',
+    accent:    '0066CC',
+    ink:       '000000',
+    highlight: 'FFEB00',
+  },
+  'mono-data': {
+    family: 'data',
+    bg:        'FFFFFF',
+    surface:   'F2F2F2',
+    text:      '1A1A1A',
+    subtle:    '8C8C8C',
+    primary:   '111111',
+    accent:    'D62728',
+    ink:       '000000',
+    highlight: 'FFD60A',
+  },
+  'finch': {
+    family: 'data',
+    bg:        'FAFAF7',
+    surface:   'FFFFFF',
+    text:      '1D1D1F',
+    subtle:    '86868B',
+    primary:   '055CA8',
+    accent:    '00A878',
+    ink:       '0A0E1B',
+    highlight: 'FFD166',
+  },
+
+  // ─── mono-keynote family (Vercel / Geist energy) ───────────────────
+  // Pure-mode palettes for the Vercel-class theme. Single accent (Geist
+  // blue), surfaces in pure greyscale, ink + highlight reserved for
+  // the rare moments of colour.
+  'mono-light': {
+    family: 'mono',
+    bg:        'FFFFFF',
+    surface:   'FAFAFA',
+    text:      '0A0A0A',
+    subtle:    '737373',
+    primary:   '0070F3',   // Geist blue
+    accent:    '0A0A0A',
+    ink:       '000000',
+    highlight: 'FFE45E',   // sticky-note yellow for callout highlights
+  },
+  'mono-dark': {
+    family: 'mono',
+    bg:        '000000',
+    surface:   '0A0A0A',
+    text:      'FAFAFA',
+    subtle:    '737373',
+    primary:   '0070F3',   // Geist blue
+    accent:    'FAFAFA',
+    ink:       'FFFFFF',
+    highlight: 'FFE45E',
+  },
+};
+
+/**
+ * Curated chart series for each palette — used by the chart wrapper so
+ * multi-series visuals stay on-palette and visually distinguishable.
+ * Five colours is enough for ~90% of business charts; beyond that we
+ * recycle and rely on legend + shape differentiation.
+ */
+export const CHART_SERIES = {
+  'cream-charcoal': ['C04A2D', '7A7368', 'E0B872', '4A8580', '3E2723'],
+  'ink-paper':      ['1B1B1B', '5A5A5A', 'B89060', '7B4A24', 'A5A5A5'],
+  'mint-charcoal':  ['2E5E50', 'A8C9B4', '6A7B73', '8B4513', '1A2620'],
+  'electric-night': ['5B8DEF', 'F25F4C', '6DD3CE', 'FFD166', 'BC83FF'],
+  'cyber-dawn':     ['4F6DF5', 'F25F4C', '14B8A6', 'F59E0B', '7C3AED'],
+  'neon-violet':    ['A87FFF', 'FFD166', 'FF6FA3', '4ECDC4', 'A5D8FF'],
+  'linear-product': ['5E6AD2', '7B68EE', '4EA8DE', 'F7B955', 'EF4444'],
+  'bloomberg':      ['FF6600', '0066CC', 'CC3300', '009933', '6633CC'],
+  'mono-data':      ['111111', '8C8C8C', 'D62728', '2CA02C', 'C5B0D5'],
+  'finch':          ['055CA8', '00A878', 'F4A261', 'E76F51', '264653'],
+  // Vercel/Geist palette family — single accent + greyscale ladder for
+  // additional series. Avoids the rainbow chart look that fights the
+  // monochrome canvas.
+  'mono-light':     ['0070F3', '000000', '737373', '0A0A0A', 'B3B3B3'],
+  'mono-dark':      ['0070F3', 'FFFFFF', '737373', 'CCCCCC', '4D4D4D'],
+};
+
+/**
+ * Default palette per theme family. The theme's id determines which
+ * family it belongs to; the agent can override with `palette: 'x'`.
+ */
+export const DEFAULT_PALETTE_BY_FAMILY = {
+  editorial: 'cream-charcoal',
+  tech:      'electric-night',
+  data:      'bloomberg',
+  mono:      'mono-light',
+};
+
+/**
+ * Resolve a palette name → palette object. Falls back to the family
+ * default if the name is unknown. Always returns a valid palette so
+ * downstream code doesn't have to null-check.
+ */
+export function resolvePalette(name, themeFamily = 'editorial') {
+  if (name && PALETTES[name]) return { name, ...PALETTES[name] };
+  const fallback = DEFAULT_PALETTE_BY_FAMILY[themeFamily] || 'cream-charcoal';
+  return { name: fallback, ...PALETTES[fallback] };
+}
+
+/**
+ * Lighten / darken a hex by a percentage (0-100). Used by background
+ * generators to derive secondary stops from a single palette role,
+ * which keeps generated backgrounds anchored to the palette.
+ */
+export function shade(hex, percent) {
+  const h = String(hex).replace(/^#/, '');
+  if (!/^[0-9A-Fa-f]{6}$/.test(h)) return hex;
+  const r = parseInt(h.slice(0, 2), 16);
+  const g = parseInt(h.slice(2, 4), 16);
+  const b = parseInt(h.slice(4, 6), 16);
+  const k = percent / 100;
+  const blend = (c) => Math.round(k < 0 ? c * (1 + k) : c + (255 - c) * k);
+  const toHex = (n) => n.toString(16).padStart(2, '0').toUpperCase();
+  return `${toHex(blend(r))}${toHex(blend(g))}${toHex(blend(b))}`;
+}
+
+/**
+ * Mix two hex colours by `t` (0 → a, 1 → b). Useful for gradient stops
+ * derived from palette roles.
+ */
+export function mix(a, b, t) {
+  const parse = (hex) => {
+    const s = String(hex).replace(/^#/, '');
+    return [parseInt(s.slice(0, 2), 16), parseInt(s.slice(2, 4), 16), parseInt(s.slice(4, 6), 16)];
+  };
+  const [ar, ag, ab] = parse(a);
+  const [br, bg, bb] = parse(b);
+  const lerp = (x, y) => Math.round(x + (y - x) * t);
+  const toHex = (n) => n.toString(16).padStart(2, '0').toUpperCase();
+  return `${toHex(lerp(ar, br))}${toHex(lerp(ag, bg))}${toHex(lerp(ab, bb))}`;
+}

package/src/tools/office/pres/shapes.js

@@ -0,0 +1,83 @@
+/**
+ * pres/shapes — shape tokens.
+ *
+ * One knob ('sharp' | 'soft' | 'round' | 'pill') decides corner radius,
+ * shadow weight, and stroke style for every shape primitive used in
+ * the deck. The agent sets it once at the theme level (or overrides
+ * per slide); archetypes call `resolveShape(shape)` and read tokens.
+ *
+ * pptxgenjs corner-radius units are inches. PPTX shadow units we
+ * package as a plain object that pptxgenjs accepts on shape options.
+ */
+
+const SHAPE_PRESETS = {
+  sharp: {
+    cornerRadius: 0,
+    shadow: null,
+    strokeWeight: 0.5,
+    dividerWeight: 0.5,
+  },
+  soft: {
+    cornerRadius: 0.05,
+    shadow: { type: 'outer', blur: 6, offset: 1, angle: 90, color: '000000', opacity: 0.08 },
+    strokeWeight: 0,
+    dividerWeight: 0.5,
+  },
+  round: {
+    cornerRadius: 0.18,
+    shadow: { type: 'outer', blur: 12, offset: 3, angle: 90, color: '000000', opacity: 0.12 },
+    strokeWeight: 0,
+    dividerWeight: 0,
+  },
+  pill: {
+    // Used for "pill" buttons and tags. The actual corner is rounded
+    // to whichever value pptxgenjs accepts as "fully rounded" — using
+    // half the typical shape height as a safe approximation.
+    cornerRadius: 0.5,
+    shadow: { type: 'outer', blur: 16, offset: 4, angle: 90, color: '000000', opacity: 0.14 },
+    strokeWeight: 0,
+    dividerWeight: 0,
+  },
+};
+
+export function resolveShape(preset = 'soft') {
+  const base = SHAPE_PRESETS[preset] || SHAPE_PRESETS.soft;
+  return { preset, ...base };
+}
+
+/**
+ * Convert a logical shape token into pptxgenjs `addShape` options.
+ * `kind`: 'card' | 'pill' | 'divider' | 'dot'. The caller still
+ * supplies position + fill colour; this fills in the styling.
+ */
+export function shapeOpts(tokens, kind, fillHex, opts = {}) {
+  const out = { fill: { color: fillHex } };
+  if (kind === 'card' || kind === 'pill') {
+    if (tokens.cornerRadius > 0) {
+      out.rectRadius = tokens.cornerRadius;
+    }
+    if (tokens.shadow) {
+      out.shadow = tokens.shadow;
+    }
+    if (tokens.strokeWeight > 0 && opts.stroke) {
+      out.line = { color: opts.stroke, width: tokens.strokeWeight };
+    } else {
+      out.line = { type: 'none' };
+    }
+  } else if (kind === 'divider') {
+    out.line = { color: fillHex, width: opts.width ?? tokens.dividerWeight ?? 0.5 };
+  }
+  return out;
+}
+
+/**
+ * pptxgenjs has two ways to draw a rectangle:
+ *   - `addShape('rect', opts)` — sharp corners
+ *   - `addShape('roundRect', opts)` — corners use opts.rectRadius
+ * `cardShape(tokens)` returns whichever one the current shape token
+ * wants, so archetypes call `slide.addShape(cardShape(tokens), …)`
+ * without branching.
+ */
+export function cardShape(tokens) {
+  return tokens.cornerRadius > 0 ? 'roundRect' : 'rect';
+}