@tycoworks/tycoslide 0.7.0 → 0.9.0

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

@@ -18,11 +18,25 @@
  *     file (registered by generate(), swapped by the ImageFiller) and adjusts
  *     geometry for the chosen fit. See fillers/image.ts.
  *
- * generate() loads the template, registers media, and for each DeckStep walks
- * the unified `layout.slots`. Each value in `step.content` is dispatched by the
- * slot's type via `FILLERS[slot.type]` (required, no default).
+ * generate() loads the template, registers media, and for each DeckStep clones
+ * the layout's base slide and calls `fillSlide`. Each value in `step.content`
+ * selects, by its own shape, the `Block` in the slot's `accepts` whose type it
+ * matches: a base-slide block fills in place; any other block is transplanted
+ * from its source slide onto the clone, then filled with the same callbacks.
+ *
+ * `generate()` is first below; its helpers follow (function declarations hoist).
  */
-import type { Config, Deck, Slot } from "./types.js";
+import type { Config, Deck, DeckStep, Layout } 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.
  *
@@ -30,22 +44,24 @@ import type { Config, Deck, Slot } from "./types.js";
  *   1. Load the template; register it twice (as root and under an alias).
  *   2. Pre-register every image's media buffer with pptx-automizer, walking
  *      the unified `step.content` for ImageFill values.
- *   3. For each deck step, clone the layout's source slide, then within the
- *      addSlide callback walk `layout.slots` once and dispatch by slot.type
- *      via `FILLERS[slot.type]`.
+ *   3. For each deck step, clone the layout's base slide, then within the
+ *      addSlide callback call `fillSlide` to dispatch each content value to the
+ *      matching `Block` (fill in place, or transplant + fill).
  *   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
- * checker kept for tests and defensive callers.
+ * Fill one cloned slide. Per slot the step supplies a value for: resolve WHICH
+ * shape realizes it (`resolveBlock`), build WHAT to write (`FILLERS[…].callbacks`),
+ * and place it WHERE/HOW (`applyBlock`). Every ambiguity fails fast, naming layout
+ * + slot.
  *
- * Exported for tests; not part of the public engine surface (index.ts).
+ * Exported for tests; `generate()` calls it inside the `addSlide` callback.
+ */
+export declare function fillSlide(slide: any, layout: Layout, step: DeckStep, sourceAlias: string): void;
+/**
+ * Reject a slot whose `accepts` lists two blocks of the same type — the
+ * value→block lookup would silently pick the first. Called once per layout at
+ * build start.
  */
-export declare function validateContentSlots(step: {
-    layout: string;
-    content?: Record<string, unknown>;
-}, tpl: {
-    slots: Slot[];
-}): void;
+export declare function assertSlotsWellFormed(layout: Layout): void;

package/dist/engine/generate.js

@@ -18,15 +18,21 @@
  *     file (registered by generate(), swapped by the ImageFiller) and adjusts
  *     geometry for the chosen fit. See fillers/image.ts.
  *
- * generate() loads the template, registers media, and for each DeckStep walks
- * the unified `layout.slots`. Each value in `step.content` is dispatched by the
- * slot's type via `FILLERS[slot.type]` (required, no default).
+ * generate() loads the template, registers media, and for each DeckStep clones
+ * the layout's base slide and calls `fillSlide`. Each value in `step.content`
+ * selects, by its own shape, the `Block` in the slot's `accepts` whose type it
+ * matches: a base-slide block fills in place; any other block is transplanted
+ * from its source slide onto the clone, then filled with the same callbacks.
+ *
+ * `generate()` is first below; its helpers follow (function declarations hoist).
  */
 import { existsSync, rmSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
+import { DOMParser, XMLSerializer } from "@xmldom/xmldom";
 import { Automizer, modify } from "pptx-automizer";
 import { FILLERS } from "./fillers/filler.js";
 import { isImageFill } from "./fillers/image.js";
+import { applyNotesToSlide, sweepOrphanNotes } from "./notes.js";
 /**
  * Generate a PPTX file from a deck definition and a theme configuration.
  *
@@ -34,12 +40,12 @@ import { isImageFill } from "./fillers/image.js";
  *   1. Load the template; register it twice (as root and under an alias).
  *   2. Pre-register every image's media buffer with pptx-automizer, walking
  *      the unified `step.content` for ImageFill values.
- *   3. For each deck step, clone the layout's source slide, then within the
- *      addSlide callback walk `layout.slots` once and dispatch by slot.type
- *      via `FILLERS[slot.type]`.
+ *   3. For each deck step, clone the layout's base slide, then within the
+ *      addSlide callback call `fillSlide` to dispatch each content value to the
+ *      matching `Block` (fill in place, or transplant + fill).
  *   4. Write the output PPTX.
  */
-export async function generate(deck, config) {
+export async function generate(deck, config, options = {}) {
     const { layouts, rootDir, template, outputDir } = config;
     const outFile = deck.output;
     const outDir = outputDir ?? process.cwd();
@@ -60,33 +66,17 @@ export async function generate(deck, config) {
             throw new Error(`Unknown layout: ${name}`);
         return match;
     };
-    // Register the media for every image slot. Each file is validated (absolute
-    // paths are the caller's responsibility; a stray relative path trips the
-    // existsSync guard here or readFileSync in fillImage) and handed to
-    // pptx-automizer once per distinct filename.
-    const registeredMedia = new Set();
-    for (const step of deck.steps) {
-        for (const value of Object.values(step.content ?? {})) {
-            if (!isImageFill(value))
-                continue;
-            if (!existsSync(value.path)) {
-                throw new Error(`Layout "${step.layout}" image "${value.path}": file not found`);
-            }
-            const file = basename(value.path);
-            if (registeredMedia.has(file))
-                continue;
-            registeredMedia.add(file);
-            pres.loadMedia(file, dirname(value.path));
-        }
-    }
-    // pptx-automizer runs modifyElement callbacks during write() and SWALLOWS any
-    // error they throw (it logs a stack trace but keeps going, producing a broken
-    // slide). A fill primitive's fail-fast throw would therefore never fail the
-    // build. Collect those errors and re-surface them after write().
+    registerMedia(pres, deck);
+    assertLayoutsWellFormed(layouts);
+    // pptx-automizer runs fill callbacks during write() and SWALLOWS any error they
+    // throw (it logs a stack trace but keeps going, producing a broken slide). A
+    // fill primitive's fail-fast throw would therefore never fail the build. This
+    // wraps BOTH fill entry points — `modifyElement` (in-place) and `addElement`
+    // (transplant) — so a throw on a transplanted shape fails the build too.
     const fillErrors = [];
-    const captureFillErrors = (slide) => {
-        const modifyElement = slide.modifyElement.bind(slide);
-        slide.modifyElement = (shapeName, callbacks) => modifyElement(shapeName, callbacks.map((cb) => typeof cb === "function"
+    const wrapCallbacks = (callbacks) => {
+        const arr = Array.isArray(callbacks) ? callbacks : callbacks === undefined ? [] : [callbacks];
+        return arr.map((cb) => typeof cb === "function"
             ? (...args) => {
                 try {
                     return cb(...args);
@@ -96,34 +86,45 @@ export async function generate(deck, config) {
                     throw err;
                 }
             }
-            : cb));
+            : cb);
     };
-    // Populate one cloned slide: for each declared slot that the step supplies a
-    // value for, hand the value to the filler registered for the slot's type.
-    const fillSlide = (slide, layout, step) => {
-        captureFillErrors(slide);
-        for (const slot of layout.slots) {
-            const value = step.content?.[slot.key];
-            if (value === undefined)
-                continue;
-            if (typeof value === "string") {
-                // Fallback: bare string. Compiler normally normalizes to
-                // StyledParagraph[] / ImageFill; this branch only fires when
-                // callers construct decks by hand.
-                slide.modifyElement(slot.shapeName, [modify.setText(value)]);
-                continue;
-            }
-            const filler = FILLERS[slot.type];
-            if (!filler.matches(value)) {
-                throw new Error(`Layout "${step.layout}" slot "${slot.key}" (type "${slot.type}"): expected ${filler.label}, got ${describeValue(value)}`);
-            }
-            filler.fill(slide, slot, value, { layoutName: step.layout });
-        }
+    const captureFillErrors = (slide) => {
+        const modifyElement = slide.modifyElement.bind(slide);
+        slide.modifyElement = (shapeName, callbacks) => modifyElement(shapeName, wrapCallbacks(callbacks));
+        const addElement = slide.addElement.bind(slide);
+        slide.addElement = (presName, slideNumber, selector, callbacks) => addElement(presName, slideNumber, selector, wrapCallbacks(callbacks));
     };
+    // Default: write authored notes and strip any template notes automizer clones
+    // onto slides. When true, no notes are written but inherited notes are still
+    // stripped — the deck is guaranteed notes-free.
+    const excludeNotes = options.excludeNotes ?? false;
     for (const step of deck.steps) {
         const layout = resolveLayout(step.layout);
-        pres.addSlide(sourceAlias, layout.slideNumber, (slide) => fillSlide(slide, layout, step));
+        pres.addSlide(sourceAlias, layout.baseSlide, (slide) => {
+            captureFillErrors(slide);
+            fillSlide(slide, layout, step, sourceAlias);
+            // In-band notes pass: automizer runs this during write() and hands us the
+            // OUTPUT archive (parent.targetArchive) and the real output slide number
+            // (parent.targetNumber), so notes map 1:1 with no slide-number mapping.
+            // Registered for EVERY slide — a slide without authored notes must still
+            // have any auto-copied template notes stripped.
+            slide.modify(async (_document, parent) => {
+                await applyNotesToSlide(toNotesArchive(parent.targetArchive), parent.targetNumber, step.notes, excludeNotes);
+            });
+        });
     }
+    // Sweep the template's orphaned notesSlides. This MUST be a presentation-level
+    // modify callback, not part of the per-slide pass: per-slide callbacks run
+    // during writeSlides(), BEFORE automizer truncates the template's original
+    // slides and renumbers the deck — at which point every template notesSlide
+    // still looks referenced by a not-yet-removed original slide. automizer runs
+    // presentation modify callbacks after truncation, when a notesSlide's
+    // referenced status is final. Runs regardless of excludeNotes — the leak
+    // exists either way. Routed through toNotesArchive so the buffered
+    // [Content_Types].xml write survives automizer's final buffer flush.
+    pres.modify(async (_xml, _index, archive) => {
+        await sweepOrphanNotes(toNotesArchive(archive));
+    });
     await pres.write(outFile);
     if (fillErrors.length > 0) {
         // The output would be a broken deck — remove it so a failed build never
@@ -134,6 +135,35 @@ export async function generate(deck, config) {
     }
     console.log(`tycoslide: built ${deck.steps.length} slide(s) → ${resolve(outDir, outFile)}`);
 }
+// ── generate() helpers ───────────────────────────────────────────────────────
+/**
+ * Register the media for every image slot. Each file is validated (absolute
+ * paths are the caller's responsibility; a stray relative path trips the
+ * existsSync guard here or readFileSync in fillImage) and handed to
+ * pptx-automizer once per distinct filename.
+ */
+function registerMedia(pres, deck) {
+    const registeredMedia = new Set();
+    for (const step of deck.steps) {
+        for (const value of Object.values(step.content ?? {})) {
+            if (!isImageFill(value))
+                continue;
+            if (!existsSync(value.path)) {
+                throw new Error(`Layout "${step.layout}" image "${value.path}": file not found`);
+            }
+            const file = basename(value.path);
+            if (registeredMedia.has(file))
+                continue;
+            registeredMedia.add(file);
+            pres.loadMedia(file, dirname(value.path));
+        }
+    }
+}
+// Validate every layout once, up front (see assertSlotsWellFormed).
+function assertLayoutsWellFormed(layouts) {
+    for (const layout of layouts)
+        assertSlotsWellFormed(layout);
+}
 function describeValue(v) {
     if (v === null)
         return "null";
@@ -145,17 +175,156 @@ function describeValue(v) {
     }
     return typeof v;
 }
-// ── Content-slot validation (test-visible helper) ────────────────────────────
+// ── Slot fill dispatch (composition-aware) ───────────────────────────────────
 /**
- * Validate that every required slot on a layout is supplied. Type/shape
- * validation happens in the compiler now — this is a thin required-only
- * checker kept for tests and defensive callers.
+ * Fill one cloned slide. Per slot the step supplies a value for: resolve WHICH
+ * shape realizes it (`resolveBlock`), build WHAT to write (`FILLERS[…].callbacks`),
+ * and place it WHERE/HOW (`applyBlock`). Every ambiguity fails fast, naming layout
+ * + slot.
  *
- * Exported for tests; not part of the public engine surface (index.ts).
+ * Exported for tests; `generate()` calls it inside the `addSlide` callback.
  */
-export function validateContentSlots(step, tpl) {
-    const missing = tpl.slots.filter((s) => step.content?.[s.key] === undefined).map((s) => s.key);
-    if (missing.length > 0) {
-        throw new Error(`Layout "${step.layout}": missing content for slot(s): ${missing.join(", ")}`);
+export function fillSlide(slide, layout, step, sourceAlias) {
+    assertNoUnknownSlots(step, layout);
+    for (const slot of layout.slots) {
+        const value = step.content?.[slot.key];
+        if (value === undefined)
+            continue; // Empty slot: leave the base slide's shape untouched.
+        const block = resolveBlock(step, slot, value);
+        const callbacks = FILLERS[block.type].callbacks(value, targetOf(block));
+        applyBlock(slide, sourceAlias, layout.baseSlide, slot, block, callbacks);
+    }
+}
+/** The SlotType a resolved `*Fill` value maps to, via the filler discriminators. */
+function fillTypeOf(value) {
+    for (const type of Object.keys(FILLERS)) {
+        if (FILLERS[type].matches(value))
+            return type;
     }
+    return undefined;
+}
+/**
+ * Reject a slot whose `accepts` lists two blocks of the same type — the
+ * value→block lookup would silently pick the first. Called once per layout at
+ * build start.
+ */
+export function assertSlotsWellFormed(layout) {
+    for (const slot of layout.slots) {
+        const seen = new Set();
+        for (const block of slot.accepts) {
+            if (seen.has(block.type)) {
+                throw new Error(`Layout "${layout.name}" slot "${slot.key}": accepts two ${block.type} blocks; each content type may appear once.`);
+            }
+            seen.add(block.type);
+        }
+    }
+}
+/**
+ * A deck supplying content for a slot the layout doesn't declare is an authoring
+ * mistake, not a silent no-op. Runs per step, over `step.content`'s keys.
+ */
+function assertNoUnknownSlots(step, layout) {
+    const keys = new Set(layout.slots.map((s) => s.key));
+    for (const key of Object.keys(step.content ?? {})) {
+        if (!keys.has(key)) {
+            const declared = layout.slots.map((s) => s.key).join(", ") || "none";
+            throw new Error(`Layout "${step.layout}" has no slot "${key}" (declared slots: ${declared}).`);
+        }
+    }
+}
+/**
+ * WHICH shape: pick the `Block` in `slot.accepts` whose type matches the value's
+ * shape. Fails fast — first on an unrecognized value, then on a value no block
+ * accepts (order matters; both messages are asserted).
+ */
+function resolveBlock(step, slot, value) {
+    const requestedType = fillTypeOf(value);
+    if (requestedType === undefined) {
+        throw new Error(`Layout "${step.layout}" slot "${slot.key}": unrecognized content value ${describeValue(value)}.`);
+    }
+    const block = slot.accepts.find((b) => b.type === requestedType);
+    if (!block) {
+        const available = slot.accepts.map((b) => b.type).join(", ") || "none";
+        throw new Error(`Layout "${step.layout}" slot "${slot.key}": no block accepts ${requestedType} content (this slot accepts: ${available}).`);
+    }
+    return block;
+}
+/** The shape a filler targets, plus `startAt` when the (text) block declares it. */
+function targetOf(block) {
+    const target = { shapeName: block.shapeName };
+    if (block.startAt !== undefined)
+        target.startAt = block.startAt;
+    return target;
+}
+/**
+ * WHERE/HOW: place the (already-built) fill callbacks. A base-slide block is
+ * already on the cloned slide → fill in place. Any other block is transplanted:
+ * pptx-automizer runs an appended shape's callbacks against the imported element
+ * itself, so the same callbacks refill it — position it to the slot's frame,
+ * then remove the base shape it supersedes (a base block, if this slot has one —
+ * a slot need not).
+ */
+function applyBlock(slide, sourceAlias, baseSlide, slot, block, callbacks) {
+    if (block.sourceSlide === baseSlide) {
+        slide.modifyElement(block.shapeName, callbacks);
+        return;
+    }
+    slide.addElement(sourceAlias, block.sourceSlide, block.shapeName, [modify.setPosition(slot.frame), ...callbacks]);
+    const baseBlock = slot.accepts.find((b) => b.sourceSlide === baseSlide);
+    if (baseBlock && baseBlock.shapeName !== block.shapeName)
+        slide.removeElement(baseBlock.shapeName);
+}
+// ── Notes archive adapter (automizer-buffer glue) ────────────────────────────
+/** Installed pptx-automizer version this notes-buffer adapter is pinned to. */
+const PPTX_AUTOMIZER_VERSION = "0.8.2";
+/**
+ * Bridge pptx-automizer's OUTPUT archive (`parent.targetArchive`) to the minimal
+ * {@link NotesArchive} surface, cooperating with automizer's XML buffer.
+ *
+ * automizer caches every part it edits via `readXml`/`writeXml` — for a cloned
+ * slide's notes that means `slide{N}.xml.rels`, `notesSlide{N}.xml.rels`, and
+ * `[Content_Types].xml` — as a parsed document, then re-serializes the cache over
+ * the zip at write() time. A plain `write`/`remove` to those parts is therefore
+ * silently reverted at the final flush. This adapter reads the buffered
+ * (automizer-current) content and steers writes/removes back through the same
+ * buffer, so `applyNotesToSlide` stays pure over string+xmldom while its edits
+ * survive. The notes PART (`notesSlide{N}.xml`) is copied raw and never buffered,
+ * so it round-trips as a plain zip entry. The buffer holds docs parsed by the one
+ * installed `@xmldom/xmldom`, so our parser/serializer operate on them safely.
+ */
+function toNotesArchive(target) {
+    // Fail loud if automizer's internals no longer expose the buffer array this
+    // adapter steers writes through: without it, every buffered write would be
+    // silently reverted at the final flush, corrupting the deck with no error.
+    if (!Array.isArray(target.buffer)) {
+        throw new Error("Speaker notes: expected the pptx-automizer archive to expose a `buffer` array " +
+            `(pinned to pptx-automizer ${PPTX_AUTOMIZER_VERSION}); its internals may have changed. ` +
+            "Re-verify the notes buffer adapter before relying on it.");
+    }
+    const buffer = target.buffer;
+    const buffered = (file) => buffer.find((entry) => entry.relativePath === file);
+    return {
+        async read(file, type) {
+            const entry = buffered(file);
+            return entry ? new XMLSerializer().serializeToString(entry.content) : target.read(file, type);
+        },
+        async write(file, data) {
+            const entry = buffered(file);
+            if (entry)
+                entry.content = new DOMParser().parseFromString(data, "application/xml");
+            return target.write(file, data);
+        },
+        async remove(file) {
+            const index = buffer.findIndex((entry) => entry.relativePath === file);
+            if (index !== -1)
+                buffer.splice(index, 1);
+            await target.remove(file);
+        },
+        fileExists(file) {
+            return buffered(file) !== undefined || target.fileExists(file);
+        },
+        async folder(dir) {
+            return target.folder(dir);
+        },
+    };
 }

package/dist/engine/index.d.ts

@@ -3,6 +3,7 @@ export { fillImage } from "./fillers/image.js";
 export { fillTable, isTableFill } from "./fillers/table.js";
 export { fillTemplate } from "./fillers/template.js";
 export { fillText, isTextFill } from "./fillers/text.js";
+export type { GenerateOptions } from "./generate.js";
 export { generate } from "./generate.js";
-export type { Config, Deck, DeckStep, ImageFill, Layout, Slot, StyledParagraph, TableFill, TemplateFill, TemplateSegment, TextFill, TextRun, ThemeConfig, } from "./types.js";
-export { FitMode, SlotType } from "./types.js";
+export type { Block, Config, Deck, DeckStep, Frame, ImageFill, Layout, Slot, StyledParagraph, TableFill, TemplateFill, TemplateSegment, TextFill, TextRun, ThemeConfig, } from "./types.js";
+export { ImageFit, SlotType } from "./types.js";

package/dist/engine/index.js

@@ -4,4 +4,4 @@ export { fillTable, isTableFill } from "./fillers/table.js";
 export { fillTemplate } from "./fillers/template.js";
 export { fillText, isTextFill } from "./fillers/text.js";
 export { generate } from "./generate.js";
-export { FitMode, SlotType } from "./types.js";
+export { ImageFit, SlotType } from "./types.js";

package/dist/engine/notes.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Speaker-notes injection — an in-band pass run per slide during `write()`.
+ *
+ * The render library (pptx-automizer) has no public notes writer, but it does
+ * expose a general seam: `slide.modify((document, parent) => …)` runs while the
+ * deck is being written and hands us `parent.targetArchive` (the OUTPUT archive)
+ * and `parent.targetNumber` (the real output slide number). automizer's clone
+ * auto-copies the source slide's notes as `notesSlide${targetNumber}.xml` and
+ * wires its rels + content-type BEFORE our callback runs, so notes map 1:1 to the
+ * output slide number — no `sldIdLst`→rels→slideK mapping is needed.
+ *
+ * For each slide we either overwrite/synthesize its `notesSlide${N}.xml` (when the
+ * step authored notes) or strip any auto-copied part (when it did not, or notes
+ * are excluded) — so the designer's template notes never leak into the output.
+ */
+/**
+ * The minimal archive surface `applyNotesToSlide` needs. pptx-automizer's
+ * `IArchive` satisfies it structurally (so we never import its internal type), and
+ * the test fake implements it over a `Map`. String-based `read`/`write` only —
+ * XML is parsed/serialized with the engine's own `@xmldom/xmldom` instance, never
+ * automizer's `readXml`/`writeXml` (mixing xmldom instances risks subtle bugs).
+ */
+export type NotesArchive = {
+    read(file: string, type: "string"): Promise<string | Buffer>;
+    write(file: string, data: string): Promise<unknown>;
+    remove(file: string): Promise<void>;
+    fileExists(file: string): boolean;
+    /**
+     * Top-level entries of `dir` (nested `_rels` excluded). `name` is the FULL
+     * archive path (e.g. `ppt/notesSlides/notesSlide1.xml`). pptx-automizer's
+     * `IArchive.folder` satisfies this structurally.
+     */
+    folder(dir: string): Promise<{
+        name: string;
+        relativePath: string;
+    }[]>;
+};
+/**
+ * Build a minimal `<p:notes>` part whose body placeholder carries one `<a:p>`
+ * per line of `notes`. Text goes through DOM text nodes, so `& < > "` escaping
+ * is handled by the serializer.
+ */
+export declare function buildNotesSlideXml(notes: string): string;
+/** Next unused `rIdN` in a `.rels` XML string (max existing id + 1). */
+export declare function nextFreeRId(relsXml: string): string;
+/**
+ * Remove every notesSlide part that no live slide references. automizer drops the
+ * template's orphaned *slides* from the deck when building it but leaves all their
+ * `notesSlides` behind as unreferenced parts (plus their `[Content_Types].xml`
+ * Overrides), so the designer's private notes would otherwise leak into every
+ * output. Run once as a presentation-level pass, after the deck is assembled.
+ *
+ * A notesSlide is "referenced" iff a LIVE slide (reachable from `presentation.xml`,
+ * see {@link liveSlideParts}) carries a `/notesSlide` relationship pointing at it.
+ * Everything else is swept: the part, its rels, and its content-type Override (all
+ * Override removals batched into a single `[Content_Types].xml` read+write).
+ */
+export declare function sweepOrphanNotes(archive: NotesArchive): Promise<void>;
+/**
+ * Set (or strip) the speaker notes on one output slide, keyed on its real output
+ * `slideNumber` (`parent.targetNumber`). Runs inside `slide.modify` during
+ * `write()`, operating on the OUTPUT archive.
+ *
+ * - Authored notes (non-empty and `!excludeNotes`): if automizer auto-copied a
+ *   notes part (`notesSlide${N}.xml` already exists), overwrite its text only —
+ *   its rels and content-type are already correct. Otherwise synthesize the part,
+ *   its rels (→slide + →master), a `notesSlide` rel on the slide (next free rId),
+ *   and the `[Content_Types].xml` override.
+ * - No notes (or excluded): if a part was auto-copied, remove it, its rels, the
+ *   slide's `notesSlide` rel, and the content-type override — so the designer's
+ *   template notes never leak.
+ *
+ * Throws (no silent default) if a slide needs a NEW notes part but the template
+ * ships no notes master — synthesizing one is out of scope.
+ */
+export declare function applyNotesToSlide(archive: NotesArchive, slideNumber: number, notes: string | undefined, excludeNotes: boolean): Promise<void>;