onbuzz 4.9.1 → 4.9.7

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 });
+  });
+}

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

@@ -0,0 +1,142 @@
+/**
+ * Archetype: bigStat — one HUGE number that fills the slide.
+ *
+ * For when the data is the entire message. The number renders at
+ * the theme's `stat` size (200pt+) with optional ghosted backdrop
+ * numeral behind it for drama. A small label sits underneath, a
+ * footnote at the bottom edge.
+ *
+ * Slots:
+ *   eyebrow   (optional) small label above the stat
+ *   stat      (required) the number itself — e.g. "+143%" or "$4.2B"
+ *   unit      (optional) shown smaller next to the stat ("%", "M", "x")
+ *   label     (required) one-line description of what the stat measures
+ *   footnote  (optional) source / methodology
+ *   tags      (optional) [{label, kind}] — tag chips below the label
+ *   delta     (optional) {value, direction: 'up'|'down'}
+ */
+import { applyChrome, eyebrow, rule, placeText } from './_helpers.js';
+import { textStyle } from '../typography.js';
+import { backdropNumeral, tag } from '../components.js';
+
+export const id = 'bigStat';
+export const slots = ['eyebrow', 'stat', 'unit', 'label', 'footnote', 'tags', 'delta'];
+
+export default function render(slide, resolved, content, _pptx, ctx) {
+  applyChrome(slide, resolved, { bgOverride: content.background, seed: 103, ctx });
+
+  const { safe } = resolved.spacing;
+  const palette = resolved.palette;
+
+  // Backdrop ghost numeral — first digit of the stat, sitting behind
+  // the foreground. Editorial themes skip this for cleaner look.
+  if (resolved.theme.family !== 'editorial' && content.stat) {
+    const firstDigit = String(content.stat).match(/[0-9]/);
+    if (firstDigit) {
+      backdropNumeral(slide, resolved, {
+        text: firstDigit[0],
+        x: safe.x + safe.w * 0.45,
+        y: safe.y - safe.h * 0.15,
+        w: safe.w * 0.6,
+        h: safe.h,
+        color: palette.primary,
+        transparency: 90,
+        size: 560,
+      });
+    }
+  }
+
+  // Eyebrow + optional tags row at the top.
+  let cursorY = safe.y + safe.h * 0.18;
+  if (content.eyebrow) {
+    eyebrow(slide, resolved, content.eyebrow, {
+      x: safe.x, y: cursorY, w: safe.w * 0.6, color: palette.primary,
+    });
+    cursorY += 0.5;
+  }
+
+  // Layout slots — anchor everything to fixed rows so nothing overlaps.
+  // Top  : eyebrow band (already drawn above)
+  // Mid  : stat + delta
+  // Lower-mid : label (one line)
+  // Bottom-ish: tags row
+  // Footer: footnote
+  const statY = safe.y + safe.h * 0.28;
+  const statH = safe.h * 0.40;
+  const chunks = [{
+    text: String(content.stat ?? ''),
+    options: {
+      fontFace: resolved.typography.display.fontFace,
+      fontSize: resolved.typography.stat.fontSize,
+      bold: true,
+      color: palette.ink,
+      charSpacing: -4,
+    },
+  }];
+  if (content.unit) {
+    chunks.push({
+      text: ' ' + String(content.unit),
+      options: {
+        fontFace: resolved.typography.body.fontFace,
+        fontSize: resolved.typography.stat.fontSize * 0.32,
+        bold: true,
+        color: palette.subtle,
+      },
+    });
+  }
+  slide.addText(chunks, {
+    x: safe.x, y: statY, w: safe.w * 0.65, h: statH,
+    align: 'left', valign: 'middle', fit: 'shrink', wrap: false,
+  });
+
+  // Delta — to the right of the stat (not below) so it doesn't push
+  // the label down. Vertically baseline-aligned with the stat.
+  if (content.delta) {
+    const d = content.delta;
+    const direction = d.direction || (String(d.value || d).startsWith('-') ? 'down' : 'up');
+    const arrowColor = direction === 'down' ? palette.highlight : palette.primary;
+    const arrow = direction === 'down' ? '▼' : '▲';
+    slide.addText(`${arrow}  ${d.value ?? d}`, {
+      x: safe.x + safe.w * 0.65, y: statY,
+      w: safe.w * 0.35, h: statH,
+      fontFace: resolved.typography.subtitle.fontFace,
+      fontSize: 26,
+      bold: true,
+      color: arrowColor,
+      align: 'left',
+      valign: 'middle',
+    });
+  }
+
+  // Label — fixed slot well below the stat band.
+  const labelY = statY + statH + 0.25;
+  const labelH = 0.8;
+  if (content.label) {
+    placeText(slide, resolved, 'subtitle', content.label, {
+      x: safe.x, y: labelY, w: safe.w * 0.85, h: labelH,
+    }, { color: palette.text, align: 'left' });
+  }
+
+  // Tags row — fixed slot below the label, well above the footnote.
+  if (Array.isArray(content.tags) && content.tags.length) {
+    let tagX = safe.x;
+    const tagY = labelY + labelH + 0.15;
+    for (const t of content.tags) {
+      const placed = tag(slide, resolved, {
+        x: tagX, y: tagY,
+        label: typeof t === 'string' ? t : t.label,
+        kind: typeof t === 'object' ? (t.kind || 'subtle') : 'subtle',
+      });
+      tagX += placed.w + 0.12;
+    }
+  }
+
+  // Footnote at the very bottom of the safe area, with a hairline above.
+  if (content.footnote) {
+    const footY = safe.y + safe.h - 0.45;
+    rule(slide, safe.x, footY - 0.08, 0.5, palette.subtle, 0.5);
+    placeText(slide, resolved, 'caption', content.footnote, {
+      x: safe.x, y: footY, w: safe.w, h: 0.35,
+    }, { color: palette.subtle, align: 'left' });
+  }
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Archetype: bullets — title + bullet points (the everyday slide).
+ *
+ * Slots:
+ *   - title    (optional)
+ *   - subtitle (optional one-liner under the title)
+ *   - items    (required) array of strings or { text, ordered, bullet }
+ *
+ * Bullet glyphs come from pptxgenjs's built-in bullet renderer; agent
+ * doesn't have to think about it. Spacing between items is controlled
+ * by the active spacing preset.
+ */
+import { applyChrome, placeBullets, placeText } from './_helpers.js';
+
+export const id = 'bullets';
+export const slots = ['title', 'subtitle', 'items'];
+
+export default function render(slide, resolved, content, _pptx, ctx) {
+  applyChrome(slide, resolved, { bgOverride: content.background, seed: 31, ctx });
+
+  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' });
+
+  if (content.subtitle) {
+    placeText(slide, resolved, 'subtitle', content.subtitle, {
+      x: header.x, y: header.y + 0.7, w: header.w, h: 0.5,
+    }, { color: resolved.palette.subtle, align: 'left' });
+  }
+
+  placeBullets(slide, resolved, content.items, body);
+}

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

@@ -0,0 +1,70 @@
+/**
+ * Archetype: closing — final slide. Thank-you, CTA, contact.
+ *
+ * Slots:
+ *   - eyebrow  (optional) "Thank you." or a similar sign-off label
+ *   - title    (required) the closing message ("Let's build this together.")
+ *   - cta      (optional) {label, url} — a single emphatic line
+ *   - contact  (optional) [{label, value}] — array of contact rows
+ *
+ * Visual: large title, accent-color CTA, contact rows as a small
+ * justified list at the bottom. Always uses the theme default
+ * background unless overridden — the closing slide should match the
+ * hero in mood.
+ */
+import { applyChrome, eyebrow, placeText, rule } from './_helpers.js';
+import { textStyle } from '../typography.js';
+
+export const id = 'closing';
+export const slots = ['eyebrow', 'title', 'cta', 'contact'];
+
+export default function render(slide, resolved, content, _pptx, _ctx) {
+  applyChrome(slide, resolved, { bgOverride: content.background, seed: 83, chrome: false });
+
+  const { safe } = resolved.spacing;
+  const titleY = safe.y + safe.h * 0.36;
+
+  if (content.eyebrow) {
+    eyebrow(slide, resolved, content.eyebrow, {
+      x: safe.x, y: titleY - 0.45, w: safe.w / 2,
+      color: resolved.palette.accent,
+    });
+  }
+
+  placeText(slide, resolved, 'display', content.title, {
+    x: safe.x, y: titleY, w: safe.w * 0.85, h: 2,
+  }, {
+    color: resolved.palette.text,
+    align: 'left',
+    fit: 'shrink',
+  });
+
+  if (content.cta) {
+    const ctaY = titleY + 2.1;
+    rule(slide, safe.x, ctaY, 0.6, resolved.palette.primary, 1.2);
+    const ctaText = content.cta.label || content.cta.url || String(content.cta);
+    slide.addText(ctaText, {
+      x: safe.x, y: ctaY + 0.1, w: safe.w * 0.8, h: 0.5,
+      ...textStyle(resolved.typography, 'subtitle', {
+        color: resolved.palette.primary,
+        align: 'left',
+        bold: true,
+      }),
+      hyperlink: content.cta.url ? { url: content.cta.url } : undefined,
+    });
+  }
+
+  if (Array.isArray(content.contact) && content.contact.length) {
+    const rowsY = safe.y + safe.h - 0.9;
+    const colW = safe.w / Math.max(content.contact.length, 1);
+    content.contact.forEach((row, i) => {
+      const x = safe.x + i * colW;
+      placeText(slide, resolved, 'caption', row.label || '', {
+        x, y: rowsY, w: colW - 0.2, h: 0.3,
+      }, { color: resolved.palette.subtle, align: 'left' });
+      placeText(slide, resolved, 'body', row.value || '', {
+        x, y: rowsY + 0.3, w: colW - 0.2, h: 0.4,
+      }, { color: resolved.palette.text, align: 'left' });
+    });
+  }
+}

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

@@ -0,0 +1,108 @@
+/**
+ * Archetype: comparisonGrid — 2×2 (or 2×3) grid of cards.
+ *
+ * Each cell is a self-contained block — eyebrow, big number-or-keyword,
+ * body description. Used for feature comparisons, segment summaries,
+ * "pros vs cons", quadrant analyses.
+ *
+ * Slots:
+ *   title    (optional)
+ *   subtitle (optional)
+ *   cells    (required) array of 4 (2×2) or 6 (2×3):
+ *            { eyebrow?, headline, body?, accent?: 'primary'|'accent'|'highlight' }
+ *
+ * The first text element in each cell wears the cell's accent colour
+ * — letting the agent visually group/contrast cells without managing
+ * raw hex values.
+ */
+import { applyChrome, placeText, rule } from './_helpers.js';
+import { textStyle } from '../typography.js';
+import { cardShape, shapeOpts } from '../shapes.js';
+
+export const id = 'comparisonGrid';
+export const slots = ['title', 'subtitle', 'cells'];
+
+export default function render(slide, resolved, content, _pptx, ctx) {
+  applyChrome(slide, resolved, { bgOverride: content.background, seed: 109, ctx });
+
+  const { header, body, contentGutter } = resolved.spacing;
+  const palette = resolved.palette;
+
+  placeText(slide, resolved, 'title', content.title, {
+    x: header.x, y: header.y, w: header.w, h: 0.8,
+  }, { color: palette.text, align: 'left' });
+
+  if (content.subtitle) {
+    placeText(slide, resolved, 'subtitle', content.subtitle, {
+      x: header.x, y: header.y + 0.85, w: header.w, h: 0.5,
+    }, { color: palette.subtle, align: 'left' });
+  }
+
+  const cells = Array.isArray(content.cells) ? content.cells : [];
+  if (cells.length === 0) return;
+
+  // 4 cells → 2×2 grid. 6 cells → 2×3. Anything else falls into 2 cols.
+  const cols = 2;
+  const rows = Math.ceil(cells.length / cols);
+  const gap = contentGutter;
+  const cellW = (body.w - gap * (cols - 1)) / cols;
+  const cellH = (body.h - gap * (rows - 1)) / rows;
+  const pad = resolved.spacing.blockPadding;
+
+  cells.forEach((c, i) => {
+    const r = Math.floor(i / cols);
+    const k = i % cols;
+    const cx = body.x + k * (cellW + gap);
+    const cy = body.y + r * (cellH + gap);
+
+    // Card background.
+    slide.addShape(cardShape(resolved.shape), {
+      x: cx, y: cy, w: cellW, h: cellH,
+      ...shapeOpts(resolved.shape, 'card', palette.surface),
+    });
+
+    const inner = { x: cx + pad, y: cy + pad, w: cellW - pad * 2, h: cellH - pad * 2 };
+    let yCursor = inner.y;
+    const accentColor = palette[c.accent] || palette.primary;
+
+    if (c.eyebrow) {
+      slide.addText(String(c.eyebrow).toUpperCase(), {
+        x: inner.x, y: yCursor, w: inner.w, h: 0.3,
+        ...textStyle(resolved.typography, 'eyebrow', {
+          color: accentColor,
+          align: 'left',
+          bold: true,
+          charSpacing: 2,
+        }),
+      });
+      yCursor += 0.4;
+    }
+
+    // Headline — accent-coloured for visual punch.
+    slide.addText(String(c.headline ?? ''), {
+      x: inner.x, y: yCursor, w: inner.w, h: 0.9,
+      ...textStyle(resolved.typography, 'title', {
+        color: accentColor,
+        align: 'left',
+        fontSize: 32,
+      }),
+    });
+    yCursor += 1.0;
+
+    if (c.body) {
+      slide.addText(String(c.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',
+        }),
+      });
+    }
+
+    // Hairline at the bottom-left as a finish detail.
+    if (resolved.shape.preset === 'sharp') {
+      rule(slide, inner.x, cy + cellH - pad * 0.5, 0.4, accentColor, 1.2);
+    }
+  });
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Archetype: freeform — escape hatch.
+ *
+ * When none of the curated archetypes fits, the agent passes a list of
+ * `items` and we place them by type. This loses some of the system's
+ * design guarantees but the items still get themed colours + fonts.
+ *
+ * Slots:
+ *   - title (optional)
+ *   - items  array of { type, ...positionAndContent }
+ *       type: 'text' | 'bullets' | 'image' | 'rect' | 'chart'
+ *       x/y/w/h are in 0..1 normalised against the safe area (so the
+ *       agent thinks "I want this at 60% of the slide width" not "I
+ *       want this at 8 inches")
+ */
+import { applyChrome, callout, placeBullets, placeText } from './_helpers.js';
+import { textStyle } from '../typography.js';
+import { resolveChart } from '../charts/index.js';
+
+export const id = 'freeform';
+export const slots = ['title', 'items'];
+
+function denorm(safe, item) {
+  return {
+    x: safe.x + (item.x ?? 0) * safe.w,
+    y: safe.y + (item.y ?? 0) * safe.h,
+    w: (item.w ?? 1) * safe.w,
+    h: (item.h ?? 1) * safe.h,
+  };
+}
+
+export default function render(slide, resolved, content, pptx, ctx) {
+  applyChrome(slide, resolved, { bgOverride: content.background, seed: 97, ctx });
+  const { safe, header } = resolved.spacing;
+
+  if (content.title) {
+    placeText(slide, resolved, 'title', content.title, {
+      x: header.x, y: header.y, w: header.w, h: 0.7,
+    }, { color: resolved.palette.text, align: 'left' });
+  }
+
+  for (const raw of (content.items || [])) {
+    const frame = denorm(safe, raw);
+    const role = raw.role || 'body';
+    switch ((raw.type || 'text').toLowerCase()) {
+      case 'text': {
+        const colorHex = resolved.palette[raw.color] || raw.color || resolved.palette.text;
+        slide.addText(String(raw.text || ''), {
+          ...frame,
+          ...textStyle(resolved.typography, role, { color: colorHex, align: raw.align || 'left' }),
+        });
+        break;
+      }
+      case 'bullets':
+      case 'list':
+        placeBullets(slide, resolved, raw.items || [], frame);
+        break;
+      case 'image':
+        slide.addImage({ ...frame, path: raw.path, data: raw.data });
+        break;
+      case 'rect':
+      case 'card':
+        callout(slide, resolved, frame, resolved.palette[raw.color] || raw.color || resolved.palette.surface);
+        break;
+      case 'chart': {
+        const c = resolveChart(raw, resolved);
+        if (c && pptx) slide.addChart(pptx.ChartType[c.type] || c.type, c.data, { ...frame, ...c.opts });
+        break;
+      }
+      default:
+        // Unknown items fall back to text — never error during render.
+        slide.addText(String(raw.text || raw.type || ''), {
+          ...frame,
+          ...textStyle(resolved.typography, 'body', { color: resolved.palette.text }),
+        });
+    }
+  }
+}