@tycoworks/tycoslide 0.7.0 → 0.8.0

package/README.md

@@ -1,14 +1,14 @@
 # tycoslide
 
-Generate slides from markdown using your real PowerPoint templates.
+Let AI agents build slides from existing PowerPoint (`.pptx`) templates.
 
 > **Early release** — tycoslide is under active development.
 
-## Why tycoslide?
+## How it works
 
-AI can write great slide content, but it can never get things on-brand. No matter what you try, fonts, logos, and colors end up slightly wrong, and you spend hours fixing it by hand.
-
-tycoslide helps AI agents build presentations using your real slide templates, so they're always on-brand. You define a theme with your .pptx files, layouts and design assets, from which agents can quickly build new presentations using markdown.
+1. **tycoslide wraps your PowerPoint file as an agent skill.**
+2. **Your agents use the skill to write slides in markdown.**
+3. **tycoslide builds a finished PowerPoint file from the markdown.**
 
 ## Quick Start
 
@@ -49,7 +49,7 @@ tycoslide build deck.md                   # → deck.pptx
 
 ```bash
 tycoslide build deck.md       # markdown → PPTX (theme resolved from deck frontmatter)
-tycoslide smoke               # one slide per layout → smoke-all.pptx
+tycoslide build deck.md --no-notes   # omit speaker notes from the output
 tycoslide plugin              # generate AI agent plugin package
 tycoslide manifest            # print layout + asset catalog to stdout
 ```

package/SKILL.md

@@ -39,7 +39,7 @@ For brand voice and naming guidelines, read `brand.md` if it exists alongside th
 
 Before writing anything, read `manifest.json`. It contains:
 
-- **layouts** -- for each: `name`, `description`, `parameters` (frontmatter inputs) and `slots` (body regions), each with `type` and optionally `required`, `fit`, `limit`, `codeTheme`, `mermaidVariant`, plus documentation (`whenToUse`, `whenNotToUse`)
+- **layouts** -- for each: `name`, `description`, `parameters` (frontmatter inputs) and `slots` (body regions), each with `type` and optionally `required`, `limit`, `codeTheme`, `mermaidVariant` (plus, for assets, a `type` of `icon`/`image`/`background`), plus documentation (`whenToUse`, `whenNotToUse`)
 - **assets** -- brand logos, client logos, illustrations, and icons (`description`, `whenToUse`)
 
 A layout's inputs split two ways (see [syntax.md](syntax.md) for details):
@@ -101,6 +101,7 @@ subtitle: This Quarter
 - `layout` is required and consumed by the compiler (not forwarded as content).
 - All other frontmatter keys fill parameters: `title` fills the `title` template parameter, `subtitle` fills the `subtitle` parameter, `hero` fills the `hero` image parameter, etc. A multi-line text shape surfaces as several keys (e.g. `name` + `jobTitle`); fill each as its own scalar line.
 - Slots (`text`, `table`, `code`, `mermaid`) are filled by body regions, not frontmatter -- see below.
+- A slide may also carry a `notes:` block in frontmatter -- plain-text speaker notes for the slide's notes page (see [syntax.md](syntax.md#speaker-notes)). It is slide-level metadata, not a parameter or slot.
 
 ### Body content, slots, and formatting
 

package/dist/cli.js

@@ -2,90 +2,10 @@ import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { FitMode, generate, SlotType } from "./engine/index.js";
-import { buildDeck, toEngineConfig } from "./index.js";
+import { buildDeck } from "./index.js";
 import { generateManifest } from "./manifest.js";
-import { toImageFill } from "./markdown/deckCompiler.js";
-import { CompilerSlotType, compileDeck, ParameterType, parseSlideDocument, RESERVED_KEY, } from "./markdown/index.js";
-import { templateKeys, templateToSegments } from "./markdown/textTemplate.js";
-// ── Smoke content fixtures (used by the `smoke` subcommand) ──────────────────
-const line = (text) => ({ runs: [{ text }] });
-const bulletLine = (text, level = 0) => ({ runs: [{ text }], bullet: { level } });
-const SMOKE_TABLE = {
-    headers: ["Feature", "Starter", "Pro", "Business", "Enterprise"].map(line),
-    rows: [
-        ["Users", "5", "25", "100", "Unlimited"].map(line),
-        ["Storage", "1 GB", "10 GB", "100 GB", "1 TB"].map(line),
-        ["Support", "Email", "Priority", "24/7", "Dedicated"].map(line),
-    ],
-};
-const SMOKE_CODE = [
-    { runs: [{ text: "SELECT name, total", color: "FF7B72" }] },
-    { runs: [{ text: "FROM orders", color: "FF7B72" }] },
-    { runs: [{ text: "WHERE created_at > now();", color: "FF7B72" }] },
-];
-const SMOKE_PROSE = [
-    line("Sample intro line for this block."),
-    bulletLine("First point"),
-    bulletLine("Second point"),
-];
-function pickFirstAsset(config) {
-    for (const group of Object.values(config.assets)) {
-        for (const entry of Object.values(group))
-            return entry.path;
-    }
-    return undefined;
-}
-function smokeSteps(config) {
-    const firstAsset = pickFirstAsset(config);
-    const absAsset = firstAsset ? resolve(config.rootDir, firstAsset) : undefined;
-    return config.layouts.map((layout) => {
-        const content = {};
-        // Parameters (frontmatter): text → a placeholder-filled template, image → the first asset.
-        for (const p of layout.parameters) {
-            switch (p.type) {
-                case ParameterType.Image: {
-                    if (!absAsset)
-                        continue;
-                    content[p.key] = toImageFill(p, absAsset);
-                    break;
-                }
-                case ParameterType.Template: {
-                    // Text shapes carry no key — the engine slot is keyed by shapeName.
-                    const values = new Map(templateKeys(p.template).map((k) => [k, "Sample"]));
-                    content[p.shapeName] = { lines: templateToSegments(p.template, values, p.shapeName) };
-                    break;
-                }
-            }
-        }
-        // Slots (body regions): text → prose, table → table, code → code, mermaid → image.
-        for (const s of layout.slots) {
-            switch (s.type) {
-                case CompilerSlotType.Table:
-                    content[s.key] = SMOKE_TABLE;
-                    break;
-                case CompilerSlotType.Code:
-                    content[s.key] = { paragraphs: SMOKE_CODE };
-                    break;
-                case CompilerSlotType.Mermaid: {
-                    // Mermaid slots don't declare fit; smoke fills them with a fixed
-                    // contained ImageFill so the projected engine slot (Image, contain)
-                    // stays consistent with the real renderer's output.
-                    if (!absAsset)
-                        continue;
-                    content[s.key] = { type: SlotType.Image, path: absAsset, fit: FitMode.Contain };
-                    break;
-                }
-                case CompilerSlotType.Text:
-                    content[s.key] = { paragraphs: SMOKE_PROSE };
-                    break;
-            }
-        }
-        return { layout: layout.name, content };
-    });
-}
+import { compileDeck, parseSlideDocument, RESERVED_KEY, } from "./markdown/index.js";
 const DEFAULT_CONFIG = "theme.json";
-const DEFAULT_SMOKE_OUTPUT = "smoke-all.pptx";
 const SKILL_DIR = "skills/slides";
 const PLUGIN_DIR = ".claude-plugin";
 const PLUGIN_FILE = "plugin.json";
@@ -113,6 +33,7 @@ program
     .description("Build a PPTX deck from a Markdown spec")
     .argument("<deck>", "path to deck markdown file")
     .option(`-c, --config <path>`, "override theme config path (default: read from frontmatter)")
+    .option("--no-notes", "omit speaker notes from the output (also strips any inherited template notes)")
     .action(async (deckPath, opts) => {
     const absDeckPath = resolve(process.cwd(), deckPath);
     let source;
@@ -133,10 +54,10 @@ program
         throw new Error(`${basename(deckPath)}: missing required "${RESERVED_KEY.THEME}" in global frontmatter`);
     }
     const config = loadConfig(absConfigPath);
-    const deck = compileDeck(doc, config.layouts, config.rootDir);
+    const deck = compileDeck(doc, config.layouts, config.rootDir, config.assets);
     if (!deck.output)
         deck.output = basename(deckPath).replace(/\.md$/, ".pptx");
-    await buildDeck(deck, config);
+    await buildDeck(deck, config, { excludeNotes: !opts.notes });
 });
 program
     .command("manifest")
@@ -154,16 +75,6 @@ program
         process.stdout.write(`${json}\n`);
     }
 });
-program
-    .command("smoke")
-    .description("Generate one smoke-test slide per layout")
-    .option(`-c, --config <path>`, "path to theme config file", DEFAULT_CONFIG)
-    .option(`-o, --out <file>`, "output PPTX filename", DEFAULT_SMOKE_OUTPUT)
-    .action(async (opts) => {
-    const config = loadConfig(resolve(process.cwd(), opts.config));
-    const steps = smokeSteps(config);
-    await generate({ theme: opts.config, output: opts.out, steps }, toEngineConfig(config));
-});
 program
     .command("plugin")
     .description("Generate plugin package (plugin.json, manifest.json, SKILL.md, syntax.md) for AI agents")

package/dist/engine/dom.d.ts

@@ -32,6 +32,8 @@ export declare const Tag: {
     readonly HLINK_CLICK: "a:hlinkClick";
     readonly RELATIONSHIP: "Relationship";
     readonly TABLE: "a:tbl";
+    readonly TABLE_GRID: "a:tblGrid";
+    readonly GRID_COL: "a:gridCol";
     readonly TABLE_ROW: "a:tr";
     readonly TABLE_CELL: "a:tc";
     readonly TX_BODY: "a:txBody";
@@ -63,6 +65,7 @@ export declare const Attr: {
     readonly Y: "y";
     readonly CX: "cx";
     readonly CY: "cy";
+    readonly WIDTH: "w";
     readonly LEFT: "l";
     readonly TOP: "t";
     readonly RIGHT: "r";
@@ -81,6 +84,8 @@ export declare function leadingDecorativePrefix(text: string): string;
 export declare function buildRun(doc: any, cloneRPr: any | null, text: string): any;
 export declare function buildParagraph(doc: any, clonePPr: any | null, run: any): any;
 export declare const HYPERLINK_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
+/** Next unused `rIdN` (max existing id + 1) among a rels container's `<Relationship>` children. */
+export declare function nextFreeRId(relation: any): string;
 export declare function addRelationship(relation: any, url: string): string;
 /**
  * Replace all runs in a paragraph with a sequence of styled runs, cloning the

package/dist/engine/dom.js

@@ -32,6 +32,8 @@ export const Tag = {
     HLINK_CLICK: "a:hlinkClick",
     RELATIONSHIP: "Relationship",
     TABLE: "a:tbl",
+    TABLE_GRID: "a:tblGrid",
+    GRID_COL: "a:gridCol",
     TABLE_ROW: "a:tr",
     TABLE_CELL: "a:tc",
     TX_BODY: "a:txBody",
@@ -68,6 +70,8 @@ export const Attr = {
     Y: "y",
     CX: "cx",
     CY: "cy",
+    // table grid column width
+    WIDTH: "w",
     // srcRect edges
     LEFT: "l",
     TOP: "t",
@@ -143,7 +147,8 @@ export function buildParagraph(doc, clonePPr, run) {
 }
 // ── Relationship Management ──────────────────────────────────────────────────
 export const HYPERLINK_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
-export function addRelationship(relation, url) {
+/** Next unused `rIdN` (max existing id + 1) among a rels container's `<Relationship>` children. */
+export function nextFreeRId(relation) {
     const existing = collectElements(relation, Tag.RELATIONSHIP);
     let maxId = 0;
     for (const rel of existing) {
@@ -152,7 +157,10 @@ export function addRelationship(relation, url) {
         if (num > maxId)
             maxId = num;
     }
-    const rId = `rId${maxId + 1}`;
+    return `rId${maxId + 1}`;
+}
+export function addRelationship(relation, url) {
+    const rId = nextFreeRId(relation);
     const rel = relation.ownerDocument.createElement(Tag.RELATIONSHIP);
     rel.setAttribute(Attr.ID, rId);
     rel.setAttribute(Attr.TYPE, HYPERLINK_REL_TYPE);
@@ -338,10 +346,18 @@ export function rebuildParagraphs(shape, paragraphs, startIndex, relation, shape
             continue;
         const isBullet = para.bullet !== undefined;
         const inLevel = para.bullet?.level ?? 0;
-        const { bucket, effectiveLvl } = isBullet ? pickBullet(inLevel) : { bucket: plainBucket, effectiveLvl: 0 };
         // Skip fully-empty text (matches previous fillText behavior).
         if (para.runs.length === 1 && !para.runs[0].text)
             continue;
+        // Bulleted content needs a bulleted specimen to model on. A plain-only shape
+        // (e.g. a designer "description" line, buNone) accepts plain text only, so
+        // bulleting it is an authoring error — fail fast rather than emit a run with
+        // no modelled style (which renders in the app default colour, e.g. black on
+        // a dark slide whose real text colour lives only in the specimen's rPr).
+        if (isBullet && bullets.size === 0) {
+            throw new Error(`Shape "${shapeName}": received bulleted content, but its specimen has no bulleted paragraph to model — this slot accepts plain text only.`);
+        }
+        const { bucket, effectiveLvl } = isBullet ? pickBullet(inLevel) : { bucket: plainBucket, effectiveLvl: 0 };
         const seedRun = buildRun(doc, bucket?.rPr ?? null, "");
         const newPara = buildParagraph(doc, bucket?.pPr ?? null, seedRun);
         maybeOverrideLevel(newPara, isBullet ? effectiveLvl : null);

package/dist/engine/fillers/filler.js

@@ -35,10 +35,7 @@ export const FILLERS = {
     [SlotType.Table]: {
         matches: isTableFill,
         label: "TableFill",
-        fill: (slide, slot, v, { layoutName }) => {
-            if (slot.columns !== undefined && v.headers.length !== slot.columns) {
-                throw new Error(`Layout "${layoutName}" slot "${slot.key}": table has ${v.headers.length} columns, template expects ${slot.columns}`);
-            }
+        fill: (slide, slot, v) => {
             slide.modifyElement(slot.shapeName, [(el) => fillTable(el, v, slot.shapeName)]);
         },
     },

package/dist/engine/fillers/image.d.ts

@@ -1,19 +1,58 @@
 /**
  * Image fill — element-level picture geometry only. The media swap (pointing the
  * blip relationship at the new file) is a slide-level modifier in the ImageFiller
- * (`fillers/filler.ts`); this module just adjusts the frame for the fit mode.
+ * (`fillers/filler.ts`); this module resolves the frame geometry from the image's
+ * `ImageFit` (contain/cover/scale-down) and the source's true pixel size.
  */
-import { type ImageFill } from "../types.js";
+import { type ImageFill, ImageFit } from "../types.js";
+/** A picture frame's placement + size, in EMU. */
+interface Frame {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** The two ways a picture is placed: crop the source (`<a:srcRect>`) or resize the frame. */
+declare const Placement: {
+    readonly Crop: "crop";
+    readonly Fit: "fit";
+};
+/** Either a symmetric `<a:srcRect>` crop (fill/cover) or a resized+re-centred frame (fit/contain). */
+type FitGeometry = {
+    placement: typeof Placement.Crop;
+    left: number;
+    top: number;
+} | {
+    placement: typeof Placement.Fit;
+    x: number;
+    y: number;
+    cx: number;
+    cy: number;
+};
+export type GeometryResult = {
+    geometry: FitGeometry;
+    warnings: string[];
+};
 /**
- * Adjust a picture shape's geometry for the chosen fit mode:
- *  - cover: writes `<a:srcRect>` insets (units: 1/100,000%) so the image fills
- *    the frame with the overflowing axis center-cropped.
- *  - contain: shrinks the picture's frame to the image's aspect-ratio dimensions
- *    and re-centers within the original frame bounds.
+ * Size a picture shape from its `ImageFit` (via `computeGeometry`): either write
+ * `<a:srcRect>` insets to fill-and-crop, or shrink the frame to the image's
+ * aspect ratio and re-centre (fit/letterbox). Advisory warnings from the
+ * geometry pass go to `console.warn`.
  *
  * `image.path` is assumed absolute — the compiler / caller resolves it before the
  * ImageFill reaches the engine.
  */
 export declare function fillImage(shape: any, image: ImageFill, shapeName?: string): void;
+/**
+ * Pure fit geometry — no DOM, so it is trivially unit-testable in isolation.
+ * `fit` picks the strategy: `cover` scales to the larger axis ratio and
+ * center-crops the overflow; `contain` scales to the smaller ratio and
+ * letterboxes; `scale-down` is `contain` capped at native size (never enlarge →
+ * the image sits at native size, centred). Emits advisory warnings for scaling
+ * far from native and for a severe aspect mismatch; the caller decides how to
+ * surface them.
+ */
+export declare function computeGeometry(frame: Frame, imgW: number, imgH: number, fit: ImageFit): GeometryResult;
 /** Discriminator for ImageFill values. */
 export declare function isImageFill(v: unknown): v is ImageFill;
+export {};

package/dist/engine/fillers/image.js

@@ -1,18 +1,31 @@
 /**
  * Image fill — element-level picture geometry only. The media swap (pointing the
  * blip relationship at the new file) is a slide-level modifier in the ImageFiller
- * (`fillers/filler.ts`); this module just adjusts the frame for the fit mode.
+ * (`fillers/filler.ts`); this module resolves the frame geometry from the image's
+ * `ImageFit` (contain/cover/scale-down) and the source's true pixel size.
  */
 import { readFileSync } from "node:fs";
 import { imageSize } from "image-size";
 import { Attr, isPlainObject, Tag } from "../dom.js";
-import { FitMode, SlotType } from "../types.js";
+import { ImageFit, SlotType } from "../types.js";
+/** The two ways a picture is placed: crop the source (`<a:srcRect>`) or resize the frame. */
+const Placement = { Crop: "crop", Fit: "fit" };
+const EMU_PER_INCH = 914400;
+/** PPTX's reference pixel density: one source px maps to one output px at this DPI. */
+const PX_PER_INCH = 96;
+/** EMU that one source pixel occupies at native (1:1) size — 9525. */
+const NATIVE_EMU_PER_PX = EMU_PER_INCH / PX_PER_INCH;
+/** `<a:srcRect>` insets are fixed-point fractions of the picture where this = 100%. */
+const SRC_RECT_FULL = 100000;
+/** Warn once the cropped-away or empty area exceeds this fraction of the frame. */
+const SEVERE_MISMATCH_FRACTION = 0.5;
+/** Warn once the image renders below this fraction of its native pixel size. */
+const MIN_SCALE = 0.2;
 /**
- * Adjust a picture shape's geometry for the chosen fit mode:
- *  - cover: writes `<a:srcRect>` insets (units: 1/100,000%) so the image fills
- *    the frame with the overflowing axis center-cropped.
- *  - contain: shrinks the picture's frame to the image's aspect-ratio dimensions
- *    and re-centers within the original frame bounds.
+ * Size a picture shape from its `ImageFit` (via `computeGeometry`): either write
+ * `<a:srcRect>` insets to fill-and-crop, or shrink the frame to the image's
+ * aspect ratio and re-centre (fit/letterbox). Advisory warnings from the
+ * geometry pass go to `console.warn`.
  *
  * `image.path` is assumed absolute — the compiler / caller resolves it before the
  * ImageFill reaches the engine.
@@ -34,48 +47,77 @@ export function fillImage(shape, image, shapeName = "") {
         w: Number(ext.getAttribute(Attr.CX)),
         h: Number(ext.getAttribute(Attr.CY)),
     };
-    const geom = computeFit(frame, dims.width, dims.height, image.fit);
-    if (geom.kind === "crop") {
-        // cover: symmetric crop on the overflowing axis, written as srcRect insets.
-        applySrcRect(shape, blipFill, geom.left, geom.top, geom.left, geom.top);
+    const { geometry, warnings } = computeGeometry(frame, dims.width, dims.height, image.fit);
+    for (const w of warnings)
+        console.warn(`Image "${shapeName}": ${w}`);
+    if (geometry.placement === Placement.Crop) {
+        // fill: symmetric crop on the overflowing axis, written as srcRect insets.
+        applySrcRect(shape, blipFill, geometry.left, geometry.top, geometry.left, geometry.top);
         return;
     }
-    // contain: drop any inherited crop, then resize + re-center the frame itself.
+    // fit: drop any inherited crop, then resize + re-center the frame itself.
     applySrcRect(shape, blipFill, 0, 0, 0, 0);
-    ext.setAttribute(Attr.CX, String(geom.cx));
-    ext.setAttribute(Attr.CY, String(geom.cy));
-    off.setAttribute(Attr.X, String(geom.x));
-    off.setAttribute(Attr.Y, String(geom.y));
+    ext.setAttribute(Attr.CX, String(geometry.cx));
+    ext.setAttribute(Attr.CY, String(geometry.cy));
+    off.setAttribute(Attr.X, String(geometry.x));
+    off.setAttribute(Attr.Y, String(geometry.y));
 }
 /**
  * Pure fit geometry — no DOM, so it is trivially unit-testable in isolation.
- * Given the picture frame (EMU) and the source image's pixel size: cover scales
- * up until both axes are covered and crops the overflow; contain scales down
- * until the whole image fits, then re-centres the shrunken frame.
+ * `fit` picks the strategy: `cover` scales to the larger axis ratio and
+ * center-crops the overflow; `contain` scales to the smaller ratio and
+ * letterboxes; `scale-down` is `contain` capped at native size (never enlarge →
+ * the image sits at native size, centred). Emits advisory warnings for scaling
+ * far from native and for a severe aspect mismatch; the caller decides how to
+ * surface them.
  */
-function computeFit(frame, imgW, imgH, fit) {
+export function computeGeometry(frame, imgW, imgH, fit) {
     const fitX = frame.w / imgW;
     const fitY = frame.h / imgH;
-    const inset = (fraction) => Math.round(fraction * 100000); // <a:srcRect> unit: 1/100,000%
-    if (fit === FitMode.Cover) {
-        const scale = Math.max(fitX, fitY);
-        const shownW = imgW * scale;
-        const shownH = imgH * scale;
+    const allowCrop = fit === ImageFit.Cover;
+    let scale = allowCrop ? Math.max(fitX, fitY) : Math.min(fitX, fitY);
+    if (fit === ImageFit.ScaleDown)
+        scale = Math.min(scale, NATIVE_EMU_PER_PX); // never enlarge past native
+    const warnings = [];
+    const scaleRatio = scale / NATIVE_EMU_PER_PX; // rendered size vs the image's native pixels
+    if (scaleRatio > 1) {
+        warnings.push(`enlarged to ${Math.round(scaleRatio * 100)}% of native — will look soft; supply a larger image`);
+    }
+    else if (scaleRatio < MIN_SCALE) {
+        warnings.push(`shrunk to ${Math.round(scaleRatio * 100)}% of native — the slot is far smaller than the image`);
+    }
+    const shownW = imgW * scale;
+    const shownH = imgH * scale;
+    const inset = (fraction) => Math.round(fraction * SRC_RECT_FULL);
+    if (allowCrop && (shownW > frame.w || shownH > frame.h)) {
+        const cropped = 1 - (frame.w * frame.h) / (shownW * shownH);
+        if (cropped > SEVERE_MISMATCH_FRACTION) {
+            warnings.push(`fills the frame by cropping ${Math.round(cropped * 100)}% of the image (aspect mismatch)`);
+        }
         return {
-            kind: "crop",
-            left: shownW > frame.w ? inset((1 - frame.w / shownW) / 2) : 0,
-            top: shownH > frame.h ? inset((1 - frame.h / shownH) / 2) : 0,
+            geometry: {
+                placement: Placement.Crop,
+                left: shownW > frame.w ? inset((1 - frame.w / shownW) / 2) : 0,
+                top: shownH > frame.h ? inset((1 - frame.h / shownH) / 2) : 0,
+            },
+            warnings,
         };
     }
-    const scale = Math.min(fitX, fitY);
-    const cx = Math.round(imgW * scale);
-    const cy = Math.round(imgH * scale);
+    const empty = 1 - (shownW * shownH) / (frame.w * frame.h);
+    if (empty > SEVERE_MISMATCH_FRACTION) {
+        warnings.push(`leaves ${Math.round(empty * 100)}% of the frame empty (aspect mismatch or small image)`);
+    }
+    const cx = Math.round(shownW);
+    const cy = Math.round(shownH);
     return {
-        kind: "frame",
-        x: Math.round(frame.x + (frame.w - cx) / 2),
-        y: Math.round(frame.y + (frame.h - cy) / 2),
-        cx,
-        cy,
+        geometry: {
+            placement: Placement.Fit,
+            x: Math.round(frame.x + (frame.w - cx) / 2),
+            y: Math.round(frame.y + (frame.h - cy) / 2),
+            cx,
+            cy,
+        },
+        warnings,
     };
 }
 /**

package/dist/engine/fillers/table.d.ts

@@ -1,8 +1,9 @@
 /**
- * Table fill — clones specimen rows in the template's `<a:tbl>` (row 0 header,
+ * Table fill — clones the template's specimen rows in `<a:tbl>` (row 0 header,
  * row 1 data, optional row 2 zebra) and fills each cell's first paragraph with
- * the corresponding StyledParagraph. Row cloning must stay engine-side because
- * it needs pptx-automizer DOM access.
+ * the corresponding StyledParagraph. Cells and `<a:gridCol>` entries are cloned
+ * or trimmed to the header count, sharing the template's total width. Row, cell,
+ * and grid cloning stay engine-side because they need pptx-automizer DOM access.
  */
 import type { TableFill } from "../types.js";
 /**

package/dist/engine/fillers/table.js

@@ -1,10 +1,54 @@
 /**
- * Table fill — clones specimen rows in the template's `<a:tbl>` (row 0 header,
+ * Table fill — clones the template's specimen rows in `<a:tbl>` (row 0 header,
  * row 1 data, optional row 2 zebra) and fills each cell's first paragraph with
- * the corresponding StyledParagraph. Row cloning must stay engine-side because
- * it needs pptx-automizer DOM access.
+ * the corresponding StyledParagraph. Cells and `<a:gridCol>` entries are cloned
+ * or trimmed to the header count, sharing the template's total width. Row, cell,
+ * and grid cloning stay engine-side because they need pptx-automizer DOM access.
  */
-import { collectElements, isPlainObject, rebuildParagraphs, Tag } from "../dom.js";
+import { Attr, collectElements, isPlainObject, rebuildParagraphs, Tag } from "../dom.js";
+const EMPTY_CELL = { runs: [{ text: "" }] };
+/**
+ * Grow or shrink a row's `<a:tc>` list to exactly `n` cells. Added columns clone
+ * the last existing cell (its styling/fill/margins carry over); removed columns
+ * drop from the right. The row is left with no stale specimen cells.
+ */
+function normalizeCellCount(row, n) {
+    const tcs = collectElements(row, Tag.TABLE_CELL);
+    if (tcs.length === n || tcs.length === 0)
+        return;
+    if (tcs.length > n) {
+        for (let i = n; i < tcs.length; i++)
+            row.removeChild(tcs[i]);
+        return;
+    }
+    const specimen = tcs[tcs.length - 1];
+    for (let i = tcs.length; i < n; i++)
+        row.appendChild(specimen.cloneNode(true));
+}
+/**
+ * Rewrite the table's `<a:tblGrid>` to exactly `n` `<a:gridCol>` entries, sharing
+ * the template's total width evenly (the last column absorbs the rounding
+ * remainder so the total is conserved exactly). No-op when the count already
+ * matches. Leaves a grid-less table alone — malformed input we don't worsen.
+ */
+function reconcileGrid(tbl, n) {
+    const grid = tbl.getElementsByTagName(Tag.TABLE_GRID)[0];
+    if (!grid)
+        return;
+    const cols = collectElements(grid, Tag.GRID_COL);
+    if (cols.length === n || cols.length === 0)
+        return;
+    const total = cols.reduce((sum, c) => sum + (Number(c.getAttribute(Attr.WIDTH)) || 0), 0);
+    const each = Math.round(total / n);
+    const specimen = cols[cols.length - 1];
+    for (const c of cols)
+        grid.removeChild(c);
+    for (let i = 0; i < n; i++) {
+        const col = specimen.cloneNode(true);
+        col.setAttribute(Attr.WIDTH, String(i === n - 1 ? total - each * (n - 1) : each));
+        grid.appendChild(col);
+    }
+}
 /**
  * Fill a table shape by cloning specimen rows.
  *
@@ -30,15 +74,16 @@ export function fillTable(shape, table, shapeName = "") {
     // template rows are intentionally dropped — the specimen rows are re-cloned
     // per data row below.
     const dataTpls = rows.length > 2 ? [rows[1], rows[2]] : [rows[1]];
+    // Headers are the source of truth for column count; every row is normalized to
+    // it, and short/long data rows are padded/truncated to match.
+    const n = table.headers.length;
     const fillRow = (tpl, cells) => {
         const clone = tpl.cloneNode(true);
+        normalizeCellCount(clone, n);
         const tcs = collectElements(clone, Tag.TABLE_CELL);
-        // Fill min(cells, template cells): extra data columns beyond the template's
-        // cell count are intentionally ignored (column count is opt-in via
-        // slot.columns, enforced in the Table filler).
-        for (let i = 0; i < cells.length && i < tcs.length; i++) {
+        for (let i = 0; i < n; i++) {
             const txBody = tcs[i].getElementsByTagName(Tag.TX_BODY)[0] ?? tcs[i];
-            rebuildParagraphs(txBody, [cells[i]], 0, undefined, shapeName);
+            rebuildParagraphs(txBody, [cells[i] ?? EMPTY_CELL], 0, undefined, shapeName);
         }
         return clone;
     };
@@ -47,6 +92,10 @@ export function fillTable(shape, table, shapeName = "") {
     for (let r = 0; r < table.rows.length; r++) {
         built.push(fillRow(dataTpls[r % dataTpls.length], table.rows[r]));
     }
+    // Column invariant: grid `<a:gridCol>` count must equal every row's `<a:tc>`
+    // count (both == n). `normalizeCellCount` (in fillRow) holds the per-row half;
+    // `reconcileGrid` holds the grid half. Run the grid half once, table-global.
+    reconcileGrid(tbl, n);
     for (const row of rows)
         tbl.removeChild(row);
     for (const row of built)

package/dist/engine/generate.d.ts

@@ -23,6 +23,16 @@
  * slot's type via `FILLERS[slot.type]` (required, no default).
  */
 import type { Config, Deck, Slot } from "./types.js";
+/** Options for `generate` / `buildDeck`. */
+export type GenerateOptions = {
+    /**
+     * Suppress authored speaker notes. Default `false` (notes are written and any
+     * template notes cloned onto slides are stripped). When `true`, no notes are
+     * written but inherited template notes are still stripped — the deck is
+     * guaranteed notes-free.
+     */
+    excludeNotes?: boolean;
+};
 /**
  * Generate a PPTX file from a deck definition and a theme configuration.
  *
@@ -35,7 +45,7 @@ import type { Config, Deck, Slot } from "./types.js";
  *      via `FILLERS[slot.type]`.
  *   4. Write the output PPTX.
  */
-export declare function generate(deck: Deck, config: Config): Promise<void>;
+export declare function generate(deck: Deck, config: Config, options?: GenerateOptions): Promise<void>;
 /**
  * Validate that every required slot on a layout is supplied. Type/shape
  * validation happens in the compiler now — this is a thin required-only