onbuzz 4.9.5 → 4.9.7

package/src/tools/office/pres/__tests__/presSystem.test.js

@@ -0,0 +1,365 @@
+/**
+ * presSystem.test.js — system-level tests for the themed presentation
+ * builder. Locks the invariants that make the design system reliable.
+ *
+ * Coverage:
+ *   - Every archetype × every theme builds without throwing.
+ *   - Theme resolver returns a complete shape no matter what the
+ *     agent passes (empty spec, unknown theme, unknown palette).
+ *   - Palette has all 8 semantic roles for every named palette.
+ *   - Deck context tracks sections correctly across mixed slide types.
+ *   - Background dispatch returns the right function for every named
+ *     style (and falls back without throwing on unknown ones).
+ *   - buildThemedPres produces a real .pptx that pres.read can parse.
+ *
+ * These tests are CHEAP — they build to a Buffer in memory and never
+ * touch disk except where a real round-trip matters. Total runtime
+ * should stay under 5s so this can run on every commit.
+ */
+import { describe, it, expect, beforeAll } from '@jest/globals';
+import { tmpdir } from 'os';
+import path from 'path';
+import fs from 'fs/promises';
+
+import { resolveTheme, listThemes } from '../themes/index.js';
+import { listArchetypes, renderArchetype } from '../archetypes/index.js';
+import { listBackgrounds, applyBackground } from '../backgrounds/index.js';
+import { PALETTES, resolvePalette, CHART_SERIES } from '../palettes.js';
+import { resolveSpacing } from '../grid.js';
+import { resolveShape } from '../shapes.js';
+import { buildDeckContext, defineMasters, usesChrome } from '../master.js';
+import { buildThemedPres, isThemedSpec, listSystem } from '../index.js';
+import { readPres } from '../edit/read.js';
+
+/* ─── slide spy — captures every pptxgenjs call without writing ──── */
+function makeSlideSpy() {
+  const calls = [];
+  const slide = {
+    _calls: calls,
+    background: null,
+    addText:   (...args) => { calls.push(['addText', args]); },
+    addShape:  (...args) => { calls.push(['addShape', args]); },
+    addImage:  (...args) => { calls.push(['addImage', args]); },
+    addTable:  (...args) => { calls.push(['addTable', args]); },
+    addChart:  (...args) => { calls.push(['addChart', args]); },
+    addNotes:  (...args) => { calls.push(['addNotes', args]); },
+  };
+  return slide;
+}
+
+/* ─── minimal pptx stub for chart-dependent archetypes ───────────── */
+const fakePptx = {
+  ChartType: { bar: 'bar', doughnut: 'doughnut', pie: 'pie', line: 'line', area: 'area' },
+};
+
+/* ─── one example slide spec per archetype ───────────────────────── */
+const SLIDE_FIXTURES = {
+  hero:            { title: 'Hello', subtitle: 'World', eyebrow: 'Q4', author: 'Loxia', date: '2026-05-29' },
+  agenda:          { title: 'Agenda', items: ['One', 'Two', 'Three'] },
+  sectionHeader:   { number: '01', title: 'Section A', subtitle: 'Where we begin' },
+  headlineMessage: { eyebrow: 'Tagline', message: 'A single sentence carries the whole slide.', footnote: 'Source: us' },
+  productHero:     { eyebrow: 'New', title: 'Product Name', subtitle: 'A short tagline.', imagePosition: 'bottom' },
+  statCallout:     { eyebrow: 'KPI', stat: '47%', label: 'YoY', footnote: 'Source' },
+  bigStat:         { eyebrow: 'Headline', stat: '143', unit: '%', label: 'Net retention', delta: { value: '+8pp', direction: 'up' },
+                     tags: [{ label: 'tag1', kind: 'highlight' }], footnote: 'Source' },
+  statTrio:        { title: 'KPIs', stats: [
+                       { label: 'ARR',  value: '$8.3', unit: 'M', delta: '+47% YoY', deltaDirection: 'up' },
+                       { label: 'NRR',  value: '143',  unit: '%', delta: '+8pp',     deltaDirection: 'up' },
+                       { label: 'Burn', value: '14',   unit: 'mo', delta: '-3mo',    deltaDirection: 'down' },
+                     ] },
+  comparisonGrid:  { title: 'A vs B', cells: [
+                       { eyebrow: 'A', headline: 'Old', body: '...' },
+                       { eyebrow: 'B', headline: 'New', body: '...' },
+                     ] },
+  bentoGrid:       { title: 'Inside', tiles: [
+                       { colStart: 1, colSpan: 8, rowStart: 1, rowSpan: 2, kind: 'stat', value: '143', unit: '%', label: 'NRR' },
+                       { colStart: 9, colSpan: 4, rowStart: 1, rowSpan: 1, kind: 'stat', value: '$8.3', unit: 'M', label: 'ARR' },
+                       { colStart: 9, colSpan: 4, rowStart: 2, rowSpan: 1, kind: 'stat', value: '14', unit: 'mo', label: 'Burn' },
+                       { colStart: 1, colSpan: 12, rowStart: 3, rowSpan: 1, kind: 'feature', headline: 'A thing happened', body: '...' },
+                     ] },
+  bullets:         { title: 'Wins', items: ['A', 'B', 'C'] },
+  twoColText:      { title: 'Two cols', left: { headline: 'L', body: '...' }, right: { headline: 'R', body: '...' } },
+  twoColChart:     { title: 'Chart', leftText: { headline: 'L', body: '...' },
+                     chart: { type: 'donut', data: [{ label: 'A', value: 60 }, { label: 'B', value: 40 }] } },
+  quote:           { quote: 'A sentence', attribution: 'Someone' },
+  imageFullBleed:  { title: 'Title', eyebrow: 'Eyebrow' /* no image — fallback panel */ },
+  table:           { title: 'Data', headers: ['A', 'B'], rows: [['1', '2'], ['3', '4']] },
+  closing:         { eyebrow: 'Thanks', title: 'Bye', contact: [{ label: 'Email', value: 'x@y' }] },
+  freeform:        { title: 'Freeform', items: [{ type: 'text', text: 'hi', x: 0, y: 0, w: 1, h: 0.1 }] },
+};
+
+const THEME_IDS = ['editorial-warm', 'tech-bold', 'data-heavy', 'mono-keynote'];
+
+/* ─── tests ──────────────────────────────────────────────────────── */
+describe('pres — every archetype × every theme renders without throwing', () => {
+  const archetypeIds = listArchetypes();
+
+  it('every archetype has a fixture in SLIDE_FIXTURES (catch missing test coverage)', () => {
+    for (const id of archetypeIds) {
+      expect(SLIDE_FIXTURES[id]).toBeDefined();
+    }
+  });
+
+  for (const themeId of THEME_IDS) {
+    describe(`theme=${themeId}`, () => {
+      const resolved = resolveTheme({ theme: themeId });
+      const ctx = {
+        slideIndex: 0, totalSlides: 1,
+        sectionName: 'TEST', sectionIdx: 0, sectionTotal: 1,
+        brand: 'TestBrand', isSectionStart: false,
+      };
+
+      for (const archetypeId of archetypeIds) {
+        it(`renders ${archetypeId}`, () => {
+          const slide = makeSlideSpy();
+          expect(() => {
+            renderArchetype(slide, resolved, { archetype: archetypeId, ...SLIDE_FIXTURES[archetypeId] }, fakePptx, ctx);
+          }).not.toThrow();
+          // Smoke: the archetype must add SOMETHING to the slide.
+          expect(slide._calls.length).toBeGreaterThan(0);
+        });
+      }
+    });
+  }
+});
+
+describe('pres/themes — resolver always returns a complete shape', () => {
+  it('returns valid resolved object for an empty spec', () => {
+    const r = resolveTheme({});
+    expect(r.theme.id).toBeTruthy();
+    expect(r.palette.bg).toMatch(/^[0-9A-F]{6}$/i);
+    expect(r.spacing.safe).toMatchObject({ x: expect.any(Number), y: expect.any(Number), w: expect.any(Number), h: expect.any(Number) });
+    expect(r.shape.cornerRadius).toBeDefined();
+    expect(typeof r.bg).toBe('string');
+  });
+
+  it('falls back to editorial-warm for unknown theme id', () => {
+    const r = resolveTheme({ theme: 'this-is-not-a-real-theme' });
+    expect(r.theme.id).toBe('editorial-warm');
+  });
+
+  it('falls back to family default for unknown palette override', () => {
+    const r = resolveTheme({ theme: 'tech-bold', palette: 'unknown-palette' });
+    expect(r.palette.name).toBe('electric-night'); // tech-bold's family default
+  });
+
+  it('listThemes returns the 4 registered themes', () => {
+    const names = listThemes().map(t => t.id).sort();
+    expect(names).toEqual(['data-heavy', 'editorial-warm', 'mono-keynote', 'tech-bold']);
+  });
+
+  it('mono-keynote resolves to the mono-light palette by default', () => {
+    const r = resolveTheme({ theme: 'mono-keynote' });
+    expect(r.theme.family).toBe('mono');
+    expect(r.palette.name).toBe('mono-light');
+    expect(r.palette.primary).toBe('0070F3'); // Geist blue
+    expect(r.bg).toBe('solid'); // mono is restrained
+  });
+
+  it('mono-keynote with mono-dark palette inverts surfaces correctly', () => {
+    const r = resolveTheme({ theme: 'mono-keynote', palette: 'mono-dark' });
+    expect(r.palette.bg).toBe('000000');
+    expect(r.palette.text).toBe('FAFAFA');
+  });
+});
+
+describe('pres/palettes — every palette has all 8 semantic roles', () => {
+  it.each(Object.keys(PALETTES))('palette "%s" has every role', (name) => {
+    const p = PALETTES[name];
+    for (const role of ['bg', 'surface', 'text', 'subtle', 'primary', 'accent', 'ink', 'highlight']) {
+      expect(p[role]).toMatch(/^[0-9A-F]{6}$/i);
+    }
+  });
+
+  it.each(Object.keys(PALETTES))('palette "%s" has a CHART_SERIES entry', (name) => {
+    expect(Array.isArray(CHART_SERIES[name])).toBe(true);
+    expect(CHART_SERIES[name].length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('resolvePalette always returns a usable palette object', () => {
+    const r = resolvePalette('nonsense-name-xyz', 'editorial');
+    expect(r.name).toBe('cream-charcoal');
+    expect(r.bg).toMatch(/^[0-9A-F]{6}$/);
+  });
+});
+
+describe('pres/grid + shapes — token resolvers', () => {
+  it('resolveSpacing returns identical shape for unknown preset (defaults to cozy)', () => {
+    const a = resolveSpacing('nonsense');
+    const b = resolveSpacing('cozy');
+    expect(Object.keys(a).sort()).toEqual(Object.keys(b).sort());
+    expect(a.pageMargin).toBe(b.pageMargin);
+  });
+
+  it('resolveShape returns identical shape for unknown preset (defaults to soft)', () => {
+    const a = resolveShape('nonsense');
+    const b = resolveShape('soft');
+    expect(a.cornerRadius).toBe(b.cornerRadius);
+  });
+
+  it('resolveSpacing.col() produces non-overlapping frames within the safe area', () => {
+    const s = resolveSpacing('cozy');
+    const left  = s.col(1, 6);
+    const right = s.col(7, 6);
+    expect(left.x + left.w).toBeLessThanOrEqual(right.x);
+    expect(right.x + right.w).toBeLessThanOrEqual(s.safe.x + s.safe.w + 0.001);
+  });
+});
+
+describe('pres/master — deck context tracks sections across slide list', () => {
+  it('assigns each non-section slide to the most recent sectionHeader', () => {
+    const { context } = buildDeckContext({
+      title: 'Deck',
+      slides: [
+        { archetype: 'hero' },
+        { archetype: 'sectionHeader', title: 'A' },
+        { archetype: 'bullets' },
+        { archetype: 'bullets' },
+        { archetype: 'sectionHeader', title: 'B' },
+        { archetype: 'closing' },
+      ],
+    });
+    expect(context.map(c => c.sectionName)).toEqual([
+      null,    // hero before any section
+      'A',     // section A starts
+      'A', 'A', // inside section A
+      'B',     // section B starts
+      'B',     // closing inside section B
+    ]);
+    expect(context.map(c => c.sectionIdx)).toEqual([0, 0, 0, 0, 1, 1]);
+    expect(context[0].totalSlides).toBe(6);
+    expect(context[0].sectionTotal).toBe(2);
+  });
+
+  it('isSectionStart is true ONLY on sectionHeader slides', () => {
+    const { context } = buildDeckContext({
+      slides: [
+        { archetype: 'hero' },
+        { archetype: 'sectionHeader' },
+        { archetype: 'bullets' },
+      ],
+    });
+    expect(context.map(c => c.isSectionStart)).toEqual([false, true, false]);
+  });
+
+  it('usesChrome returns false for bare archetypes', () => {
+    expect(usesChrome('hero')).toBe(false);
+    expect(usesChrome('sectionHeader')).toBe(false);
+    expect(usesChrome('closing')).toBe(false);
+    expect(usesChrome('imageFullBleed')).toBe(false);
+    expect(usesChrome('headlineMessage')).toBe(false);
+    expect(usesChrome('productHero')).toBe(false);
+    // Default = chrome for everything else.
+    expect(usesChrome('bullets')).toBe(true);
+    expect(usesChrome('bentoGrid')).toBe(true);
+  });
+});
+
+describe('pres/components — glass-card primitive', () => {
+  it('renders without throwing on every theme', async () => {
+    const { glassCard } = await import('../components.js');
+    for (const themeId of THEME_IDS) {
+      const resolved = resolveTheme({ theme: themeId });
+      const slide = makeSlideSpy();
+      expect(() => glassCard(slide, resolved, { x: 0.5, y: 0.5, w: 4, h: 2 })).not.toThrow();
+      expect(slide._calls.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('paints two shapes when tinted (base + tint wash)', async () => {
+    const { glassCard } = await import('../components.js');
+    const resolved = resolveTheme({ theme: 'tech-bold' });
+    const slide = makeSlideSpy();
+    glassCard(slide, resolved, { x: 0.5, y: 0.5, w: 4, h: 2, tint: 'primary' });
+    const shapes = slide._calls.filter(c => c[0] === 'addShape');
+    expect(shapes.length).toBe(2);
+  });
+
+  it('paints only the base shape when not tinted', async () => {
+    const { glassCard } = await import('../components.js');
+    const resolved = resolveTheme({ theme: 'tech-bold' });
+    const slide = makeSlideSpy();
+    glassCard(slide, resolved, { x: 0.5, y: 0.5, w: 4, h: 2 });
+    const shapes = slide._calls.filter(c => c[0] === 'addShape');
+    expect(shapes.length).toBe(1);
+  });
+});
+
+describe('pres/backgrounds — dispatch is total', () => {
+  it('every named style resolves to a renderer', () => {
+    const styles = listBackgrounds();
+    expect(styles).toEqual(expect.arrayContaining(['solid', 'gradient', 'mesh', 'noise', 'geometric', 'grid', 'void', 'orb']));
+  });
+
+  it('every background renders against every theme without throwing', () => {
+    const styles = listBackgrounds();
+    for (const themeId of THEME_IDS) {
+      const resolved = resolveTheme({ theme: themeId });
+      for (const style of styles) {
+        const slide = makeSlideSpy();
+        expect(() => applyBackground(slide, resolved, style)).not.toThrow();
+      }
+    }
+  });
+
+  it('unknown background style falls back to solid (no throw)', () => {
+    const resolved = resolveTheme({ theme: 'tech-bold' });
+    const slide = makeSlideSpy();
+    expect(() => applyBackground(slide, resolved, 'this-doesnt-exist')).not.toThrow();
+    // Some shapes should have been added (or at minimum the bg colour set).
+    expect(slide.background || slide._calls.length > 0).toBeTruthy();
+  });
+});
+
+describe('pres — public API surface', () => {
+  it('isThemedSpec discriminates between new and legacy shape', () => {
+    expect(isThemedSpec({ theme: 'tech-bold' })).toBe(true);
+    expect(isThemedSpec({ theme: { primaryColor: '#000' } })).toBe(false);
+    expect(isThemedSpec({})).toBe(false);
+    expect(isThemedSpec(null)).toBe(false);
+  });
+
+  it('listSystem returns themes / archetypes / backgrounds discovery', () => {
+    const sys = listSystem();
+    expect(Array.isArray(sys.themes)).toBe(true);
+    expect(Array.isArray(sys.archetypes)).toBe(true);
+    expect(Array.isArray(sys.backgrounds)).toBe(true);
+    expect(sys.themes.length).toBe(4);
+    expect(sys.archetypes.length).toBeGreaterThanOrEqual(17);
+    expect(sys.backgrounds.length).toBeGreaterThanOrEqual(8);
+  });
+});
+
+describe('pres — end-to-end: build + read round-trip', () => {
+  let tmpFile;
+  beforeAll(async () => {
+    tmpFile = path.join(tmpdir(), `pres-test-${Date.now()}.pptx`);
+    await buildThemedPres({
+      title: 'Test deck',
+      theme: 'tech-bold',
+      slides: [
+        { archetype: 'hero', title: 'Hello' },
+        { archetype: 'sectionHeader', number: '01', title: 'Part one' },
+        { archetype: 'bigStat', stat: '143', unit: '%', label: 'NRR' },
+        { archetype: 'bullets', title: 'Wins', items: ['A', 'B', 'C'] },
+        { archetype: 'closing', title: 'Bye' },
+      ],
+    }, tmpFile);
+  });
+
+  it('produces a real .pptx file', async () => {
+    const stat = await fs.stat(tmpFile);
+    expect(stat.size).toBeGreaterThan(10_000);
+  });
+
+  it('pres.read can parse the deck and count slides', async () => {
+    const outline = await readPres(tmpFile);
+    expect(outline.slideCount).toBe(5);
+  });
+
+  it('round-trip preserves the deck — tokens scan finds zero unresolved tokens', async () => {
+    const outline = await readPres(tmpFile);
+    // No tokens were authored — the result should be an empty array.
+    expect(outline.tokens).toEqual([]);
+  });
+});

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

@@ -6,30 +6,38 @@
 import { textStyle } from '../typography.js';
 import { cardShape, shapeOpts } from '../shapes.js';
 import { applyBackground } from '../backgrounds/index.js';
+import { headerChrome, footerChrome } from '../components.js';
 
 /**
- * Apply background + optional decorative chrome shared across all
- * archetypes (e.g. footer rule, slide number).
+ * Apply background + (when ctx is supplied) the per-slide chrome.
  *
- *   - `bgOverride` lets an individual archetype request a different
- *     background style than the theme default (the hero archetype in
- *     tech-bold always wants `mesh` even if the deck default is solid).
- *   - `seed` is forwarded so deterministic generators (mesh) place
- *     their blobs consistently per slide.
+ * The slide master already paints the bg flat colour + the top accent
+ * stripe. Background-generators (mesh / geometric / grid / etc.) draw
+ * dynamic decorative shapes on top per slide; chrome renders dynamic
+ * text (section name, slide number, brand, progress dots).
+ *
+ *   - `bgOverride` lets an individual slide request a different
+ *     background style than the theme default.
+ *   - `seed` is forwarded so deterministic background generators
+ *     (mesh) place their blobs consistently per slide.
+ *   - `ctx` from buildDeckContext: { slideIndex, totalSlides,
+ *     sectionName, sectionIdx, sectionTotal, brand, isSectionStart }.
+ *     When omitted the archetype is responsible for any extra chrome
+ *     (hero/section/closing intentionally skip it).
  */
-export function applyChrome(slide, resolved, { bgOverride, seed, footer } = {}) {
+export function applyChrome(slide, resolved, { bgOverride, seed, ctx, chrome } = {}) {
   applyBackground(slide, resolved, bgOverride || resolved.bg, { seed });
 
-  if (footer && footer.text) {
-    slide.addText(footer.text, {
-      x: resolved.spacing.safe.x,
-      y: resolved.spacing.slide.height - resolved.spacing.pageMargin - 0.3,
-      w: resolved.spacing.safe.w,
-      h: 0.3,
-      ...textStyle(resolved.typography, 'caption', {
-        color: resolved.palette.subtle,
-        align: footer.align || 'left',
-      }),
+  if (ctx && chrome !== false) {
+    headerChrome(slide, resolved, {
+      sectionName: ctx.sectionName,
+      slideNumber: ctx.slideIndex + 1,
+      totalSlides: ctx.totalSlides,
+    });
+    footerChrome(slide, resolved, {
+      brand: ctx.brand,
+      sectionTotal: ctx.sectionTotal,
+      currentSectionIdx: ctx.sectionIdx,
     });
   }
 }
@@ -42,9 +50,20 @@ export function rule(slide, x, y, w, color, weight = 1) {
   });
 }
 
-/** Draw a small uppercase eyebrow label above a title block. */
+/** Draw a small uppercase eyebrow label above a title block.
+ *
+ * Skips the uppercase transform when the text contains template tokens
+ * `{{name}}` so token names stay intact for pres.fill — tokens
+ * uppercased to `{{NAME}}` would never match the lowercase values map
+ * the agent passes to fill. We still bump letter-spacing for the eyebrow
+ * look; the fill step (or downstream uppercase-in-data) can rebuild the
+ * fully-rendered casing if needed.
+ */
 export function eyebrow(slide, resolved, text, { x, y, w, color }) {
-  slide.addText(String(text || '').toUpperCase(), {
+  const raw = String(text || '');
+  const hasTokens = /\{\{[^}]+\}\}/.test(raw);
+  const display = hasTokens ? raw : raw.toUpperCase();
+  slide.addText(display, {
     x, y, w, h: 0.25,
     ...textStyle(resolved.typography, 'eyebrow', {
       color: color || resolved.palette.primary,

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

@@ -15,8 +15,8 @@ import { textStyle } from '../typography.js';
 export const id = 'agenda';
 export const slots = ['title', 'items'];
 
-export default function render(slide, resolved, content) {
-  applyChrome(slide, resolved, { bgOverride: content.background, seed: 7 });
+export default function render(slide, resolved, content, _pptx, ctx) {
+  applyChrome(slide, resolved, { bgOverride: content.background, seed: 7, ctx });
 
   const { safe, header, body } = resolved.spacing;
 

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

@@ -0,0 +1,219 @@
+/**
+ * Archetype: bentoGrid — asymmetric tiled layout.
+ *
+ * The pattern Apple popularized for WWDC keynotes and that every modern
+ * deck has adopted since. 12-column grid + tiles of varying size signal
+ * importance through scale. Each tile is a self-contained mini-slide.
+ *
+ * Slots:
+ *   title    (optional) shared header above the grid
+ *   tiles    (required) array of tiles:
+ *            {
+ *              colStart: 1-12, colSpan: 4|6|8|12,
+ *              rowStart: 1-N,  rowSpan: 1|2|3,
+ *              kind: 'stat' | 'feature' | 'quote' | 'image' | 'callout',
+ *              eyebrow?, headline?, body?, value?, unit?, label?,
+ *              accent?: 'primary'|'accent'|'highlight',
+ *              icon?: 'circle'|'square'|'arc'|'diamond'|'chevron',
+ *            }
+ *
+ * Layout uses a 12-col grid with 3-row default; tiles can span 4/6/8/12
+ * cols and 1/2/3 rows. Gap matches the spacing preset's contentGutter.
+ * Cards use the active shape's corner radius — glass-translucent on
+ * dark themes (Apple "liquid glass" feel), solid surface on light.
+ */
+import { applyChrome, placeText, rule } from './_helpers.js';
+import { textStyle } from '../typography.js';
+import { cardShape, shapeOpts } from '../shapes.js';
+import { shade } from '../palettes.js';
+import { glassCard } from '../components.js';
+
+export const id = 'bentoGrid';
+export const slots = ['title', 'tiles'];
+
+/** Luma-aware dark check — used to pick glass-card vs flat-card surface. */
+function isDarkBg(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;
+}
+
+/* ─── icon glyph in a tile corner ─────────────────────────────────── */
+function drawIcon(slide, resolved, { kind, x, y, size, color }) {
+  const palette = resolved.palette;
+  const fill = palette[color] || palette.primary;
+  if (kind === 'circle') {
+    slide.addShape('ellipse', { x, y, w: size, h: size, fill: { color: fill }, line: { type: 'none' } });
+  } else if (kind === 'square') {
+    slide.addShape('rect', { x, y, w: size, h: size, fill: { color: fill }, line: { type: 'none' } });
+  } else if (kind === 'arc') {
+    slide.addShape('ellipse', { x: x - size * 0.3, y: y - size * 0.3, w: size * 1.6, h: size * 1.6,
+      fill: { type: 'none' }, line: { color: fill, width: 2 } });
+  } else if (kind === 'diamond') {
+    slide.addShape('diamond', { x, y, w: size, h: size, fill: { color: fill }, line: { type: 'none' } });
+  } else if (kind === 'chevron') {
+    slide.addShape('rightArrow', { x, y, w: size, h: size * 0.7, fill: { color: fill }, line: { type: 'none' } });
+  }
+}
+
+/* ─── one tile renderer ───────────────────────────────────────────── */
+function renderTile(slide, resolved, tile, frame) {
+  const palette = resolved.palette;
+  const isDark = isDarkBg(palette.bg);
+
+  // Use the dedicated glass-card primitive on dark themes — it draws
+  // a proper translucent-gradient surface + 0.5pt inner stroke. On
+  // light themes a flat surface card reads cleaner.
+  if (isDark) {
+    glassCard(slide, resolved, {
+      x: frame.x, y: frame.y, w: frame.w, h: frame.h,
+      tint: tile.accent,    // subtle colour wash per tile
+    });
+  } else {
+    const shapeKind = cardShape(resolved.shape);
+    slide.addShape(shapeKind, {
+      x: frame.x, y: frame.y, w: frame.w, h: frame.h,
+      ...shapeOpts(resolved.shape, 'card', palette.surface),
+    });
+  }
+
+  const pad = resolved.spacing.blockPadding;
+  const inner = { x: frame.x + pad, y: frame.y + pad, w: frame.w - pad * 2, h: frame.h - pad * 2 };
+  const accentColor = palette[tile.accent] || palette.primary;
+
+  // Optional icon in the top-right corner.
+  if (tile.icon) {
+    drawIcon(slide, resolved, {
+      kind: tile.icon, x: frame.x + frame.w - pad - 0.3,
+      y: frame.y + pad, size: 0.3, color: tile.accent || 'primary',
+    });
+  }
+
+  let yCursor = inner.y;
+
+  if (tile.eyebrow) {
+    slide.addText(String(tile.eyebrow).toUpperCase(), {
+      x: inner.x, y: yCursor, w: inner.w * 0.9, h: 0.28,
+      ...textStyle(resolved.typography, 'eyebrow', {
+        color: accentColor, align: 'left', bold: true, charSpacing: 2,
+      }),
+    });
+    yCursor += 0.35;
+  }
+
+  // The hero element — either a big stat or a headline.
+  if (tile.kind === 'stat' && tile.value !== undefined) {
+    // Stat tile: big value + smaller unit + tiny label.
+    const statH = Math.min(inner.h * 0.55, 2.2);
+    // Conservative font sizing keyed to tile height + width so the
+    // value never wraps regardless of tile geometry.
+    const statFont = Math.min(Math.max(36, statH * 38), Math.max(36, inner.w * 24));
+    const chunks = [{
+      text: String(tile.value),
+      options: {
+        fontFace: resolved.typography.display.fontFace,
+        fontSize: statFont,
+        bold: true,
+        color: palette.ink,
+        charSpacing: -2,
+      },
+    }];
+    if (tile.unit) chunks.push({
+      text: ' ' + tile.unit,
+      options: {
+        fontFace: resolved.typography.body.fontFace,
+        fontSize: statFont * 0.32,
+        bold: true,
+        color: palette.subtle,
+      },
+    });
+    slide.addText(chunks, {
+      x: inner.x, y: yCursor, w: inner.w, h: statH,
+      align: 'left', valign: 'middle', fit: 'shrink', wrap: false,
+    });
+    yCursor += statH + 0.12;
+    if (tile.label) {
+      slide.addText(String(tile.label), {
+        x: inner.x, y: yCursor, w: inner.w, h: inner.h - (yCursor - inner.y),
+        ...textStyle(resolved.typography, 'body', {
+          color: palette.text, align: 'left', valign: 'top',
+        }),
+      });
+    }
+  } else if (tile.kind === 'quote' && tile.headline) {
+    slide.addText(`"${tile.headline}"`, {
+      x: inner.x, y: yCursor, w: inner.w, h: inner.h - (yCursor - inner.y) - 0.4,
+      ...textStyle(resolved.typography, 'subtitle', {
+        color: palette.text, align: 'left', italic: true, valign: 'top',
+      }),
+    });
+    if (tile.body) {
+      slide.addText(`— ${tile.body}`, {
+        x: inner.x, y: inner.y + inner.h - 0.35, w: inner.w, h: 0.3,
+        ...textStyle(resolved.typography, 'caption', {
+          color: palette.subtle, align: 'left',
+        }),
+      });
+    }
+  } else if (tile.headline) {
+    // Feature tile: medium headline + body description.
+    const hSize = Math.min(28, Math.max(18, inner.h * 11));
+    slide.addText(String(tile.headline), {
+      x: inner.x, y: yCursor, w: inner.w, h: Math.min(1.0, inner.h * 0.4),
+      ...textStyle(resolved.typography, 'title', {
+        color: tile.kind === 'callout' ? accentColor : palette.text,
+        fontSize: hSize,
+        align: 'left', valign: 'top',
+      }),
+    });
+    yCursor += Math.min(1.0, inner.h * 0.4) + 0.12;
+    if (tile.body) {
+      slide.addText(String(tile.body), {
+        x: inner.x, y: yCursor, w: inner.w, h: inner.h - (yCursor - inner.y),
+        ...textStyle(resolved.typography, 'body', {
+          color: palette.text, align: 'left', valign: 'top',
+        }),
+      });
+    }
+  }
+}
+
+/* ─── archetype entry ─────────────────────────────────────────────── */
+export default function render(slide, resolved, content, _pptx, ctx) {
+  applyChrome(slide, resolved, { bgOverride: content.background, seed: 131, ctx });
+
+  const { header, body, contentGutter } = resolved.spacing;
+  const palette = resolved.palette;
+
+  // Optional title.
+  if (content.title) {
+    placeText(slide, resolved, 'title', content.title, {
+      x: header.x, y: header.y, w: header.w, h: 0.8,
+    }, { color: palette.text, align: 'left' });
+  }
+
+  const tiles = Array.isArray(content.tiles) ? content.tiles : [];
+  if (!tiles.length) return;
+
+  // Determine row count from max rowStart+rowSpan; default 3.
+  const cols = 12;
+  const rows = Math.max(3, tiles.reduce((m, t) => Math.max(m, (t.rowStart || 1) + (t.rowSpan || 1) - 1), 3));
+  const gap = contentGutter;
+  const cellW = (body.w - gap * (cols - 1)) / cols;
+  const cellH = (body.h - gap * (rows - 1)) / rows;
+
+  tiles.forEach((tile) => {
+    const colStart = Math.max(1, Math.min(cols, tile.colStart || 1));
+    const colSpan  = Math.max(1, Math.min(cols - colStart + 1, tile.colSpan || 4));
+    const rowStart = Math.max(1, Math.min(rows, tile.rowStart || 1));
+    const rowSpan  = Math.max(1, Math.min(rows - rowStart + 1, tile.rowSpan || 1));
+    const x = body.x + (colStart - 1) * (cellW + gap);
+    const y = body.y + (rowStart - 1) * (cellH + gap);
+    const w = colSpan * cellW + (colSpan - 1) * gap;
+    const h = rowSpan * cellH + (rowSpan - 1) * gap;
+    renderTile(slide, resolved, tile, { x, y, w, h });
+  });
+}