@tycoworks/tycoslide 0.7.0 → 0.8.0

package/dist/engine/generate.js

@@ -24,9 +24,11 @@
  */
 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.
  *
@@ -39,7 +41,7 @@ import { isImageFill } from "./fillers/image.js";
  *      via `FILLERS[slot.type]`.
  *   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();
@@ -120,10 +122,36 @@ export async function generate(deck, config) {
             filler.fill(slide, slot, value, { layoutName: step.layout });
         }
     };
+    // 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.slideNumber, (slide) => {
+            fillSlide(slide, layout, step);
+            // 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
@@ -145,6 +173,60 @@ function describeValue(v) {
     }
     return typeof v;
 }
+// ── 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);
+        },
+    };
+}
 // ── Content-slot validation (test-visible helper) ────────────────────────────
 /**
  * Validate that every required slot on a layout is supplied. Type/shape

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 { 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>;

package/dist/engine/notes.js

@@ -0,0 +1,313 @@
+/**
+ * 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.
+ */
+import { DOMParser, XMLSerializer } from "@xmldom/xmldom";
+import { Attr, buildParagraph, buildRun, nextFreeRId as nextFreeRIdForDoc, Tag } from "./dom.js";
+// Package-level OOXML names not covered by dom.ts's `Tag`/`Attr` (which name
+// slide-XML tokens): `[Content_Types].xml` Override entries and the tail
+// segments of relationship-type URLs.
+const CT_OVERRIDE = "Override";
+const CT_PART_NAME = "PartName";
+const CT_CONTENT_TYPE = "ContentType";
+const REL_TYPE_SUFFIX = {
+    NotesSlide: "/notesSlide",
+    NotesMaster: "/notesMaster",
+};
+const NS_A = "http://schemas.openxmlformats.org/drawingml/2006/main";
+const NS_P = "http://schemas.openxmlformats.org/presentationml/2006/main";
+const NS_R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+const NS_REL = "http://schemas.openxmlformats.org/package/2006/relationships";
+const NS_CT = "http://schemas.openxmlformats.org/package/2006/content-types";
+const REL_TYPE = {
+    NotesSlide: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesSlide",
+    Slide: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide",
+    NotesMaster: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesMaster",
+};
+const NOTES_SLIDE_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.presentationml.notesSlide+xml";
+const XML_DECL = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\r\n';
+const CONTENT_TYPES_PART = "[Content_Types].xml";
+const PRESENTATION_RELS_PART = "ppt/_rels/presentation.xml.rels";
+const NOTES_SKELETON = `<p:notes xmlns:a="${NS_A}" xmlns:r="${NS_R}" xmlns:p="${NS_P}"><p:cSld><p:spTree>` +
+    `<p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr><p:grpSpPr/>` +
+    `<p:sp><p:nvSpPr><p:cNvPr id="2" name="Notes Placeholder 1"/>` +
+    `<p:cNvSpPr><a:spLocks noGrp="1"/></p:cNvSpPr><p:nvPr><p:ph type="body" idx="1"/></p:nvPr></p:nvSpPr>` +
+    `<p:spPr/><p:txBody><a:bodyPr/><a:lstStyle/></p:txBody></p:sp>` +
+    `</p:spTree></p:cSld><p:clrMapOvr><a:masterClrMapping/></p:clrMapOvr></p:notes>`;
+/**
+ * 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 function buildNotesSlideXml(notes) {
+    const doc = new DOMParser().parseFromString(NOTES_SKELETON, "text/xml");
+    const txBody = doc.getElementsByTagName("p:txBody")[0];
+    for (const line of notes.replace(/\r?\n+$/, "").split(/\r?\n/)) {
+        // Reuse the engine's run/paragraph builders — they set xml:space="preserve"
+        // for leading/trailing whitespace. The skeleton declares xmlns:a, so the
+        // builders' "a:"-prefixed element creation serializes correctly on this doc.
+        txBody.appendChild(buildParagraph(doc, null, buildRun(doc, null, line)));
+    }
+    return serialize(doc);
+}
+/** Next unused `rIdN` in a `.rels` XML string (max existing id + 1). */
+export function nextFreeRId(relsXml) {
+    return nextFreeRIdForDoc(new DOMParser().parseFromString(relsXml, "text/xml"));
+}
+function serialize(doc) {
+    // xmldom re-emits any `<?xml?>` declaration present in the parsed source, so a
+    // doc parsed from an already-declared part would serialize with two of them.
+    // Strip any leading declaration, then prepend exactly one canonical XML_DECL.
+    const body = new XMLSerializer().serializeToString(doc).replace(/^<\?xml[^>]*\?>\s*/, "");
+    return XML_DECL + body;
+}
+function parse(xml) {
+    return new DOMParser().parseFromString(xml, "text/xml");
+}
+async function readString(archive, file) {
+    const raw = await archive.read(file, "string");
+    return typeof raw === "string" ? raw : raw.toString("utf-8");
+}
+function appendRel(relsDoc, id, type, target) {
+    const rel = relsDoc.createElementNS(NS_REL, Tag.RELATIONSHIP);
+    rel.setAttribute(Attr.ID, id);
+    rel.setAttribute(Attr.TYPE, type);
+    rel.setAttribute(Attr.TARGET, target);
+    relsDoc.documentElement.appendChild(rel);
+}
+/** Remove the (single) notesSlide relationship from a slide's rels doc, if present. */
+function removeNotesRel(relsDoc) {
+    const rels = relsDoc.getElementsByTagName(Tag.RELATIONSHIP);
+    for (let i = 0; i < rels.length; i++) {
+        if (rels[i].getAttribute(Attr.TYPE) === REL_TYPE.NotesSlide) {
+            rels[i].parentNode?.removeChild(rels[i]);
+            return true;
+        }
+    }
+    return false;
+}
+function notesRelsXml(slideNumber, masterTarget) {
+    return (XML_DECL +
+        `<Relationships xmlns="${NS_REL}">` +
+        `<Relationship Id="rId1" Type="${REL_TYPE.Slide}" Target="../slides/slide${slideNumber}.xml"/>` +
+        `<Relationship Id="rId2" Type="${REL_TYPE.NotesMaster}" Target="${masterTarget}"/>` +
+        `</Relationships>`);
+}
+/**
+ * The notes master's target relative to `ppt/notesSlides/` (what a notesSlide's
+ * rels needs), read from the package's `presentation.xml.rels`. That file's
+ * targets are relative to `ppt/` (e.g. `notesMasters/notesMaster1.xml`), so a
+ * notesSlide part one directory deeper prefixes `../`. Returns undefined when
+ * the presentation declares no notes master relationship.
+ */
+async function findNotesMaster(archive) {
+    if (!archive.fileExists(PRESENTATION_RELS_PART))
+        return undefined;
+    const relsDoc = parse(await readString(archive, PRESENTATION_RELS_PART));
+    const rels = relsDoc.getElementsByTagName(Tag.RELATIONSHIP);
+    for (let i = 0; i < rels.length; i++) {
+        if (rels[i].getAttribute(Attr.TYPE)?.endsWith(REL_TYPE_SUFFIX.NotesMaster)) {
+            return `../${rels[i].getAttribute(Attr.TARGET)}`;
+        }
+    }
+    return undefined;
+}
+function findOverride(ctDoc, partName) {
+    const overrides = ctDoc.getElementsByTagName(CT_OVERRIDE);
+    for (let i = 0; i < overrides.length; i++) {
+        if (overrides[i].getAttribute(CT_PART_NAME) === partName)
+            return overrides[i];
+    }
+    return undefined;
+}
+async function addContentTypeOverride(archive, partName) {
+    const ctDoc = parse(await readString(archive, CONTENT_TYPES_PART));
+    if (findOverride(ctDoc, partName))
+        return;
+    const override = ctDoc.createElementNS(NS_CT, CT_OVERRIDE);
+    override.setAttribute(CT_PART_NAME, partName);
+    override.setAttribute(CT_CONTENT_TYPE, NOTES_SLIDE_CONTENT_TYPE);
+    ctDoc.documentElement.appendChild(override);
+    await archive.write(CONTENT_TYPES_PART, serialize(ctDoc));
+}
+/** Remove a part's `<Override>` from an already-parsed `[Content_Types].xml` doc. */
+function removeOverrideFromDoc(ctDoc, partName) {
+    const override = findOverride(ctDoc, partName);
+    if (!override)
+        return false;
+    override.parentNode?.removeChild(override);
+    return true;
+}
+async function removeContentTypeOverride(archive, partName) {
+    const ctDoc = parse(await readString(archive, CONTENT_TYPES_PART));
+    if (!removeOverrideFromDoc(ctDoc, partName))
+        return;
+    await archive.write(CONTENT_TYPES_PART, serialize(ctDoc));
+}
+/** Resolve `target` (from a rels file) against `baseDir`, collapsing `.`/`..`. */
+function resolveRelative(baseDir, target) {
+    const parts = baseDir.split("/").filter(Boolean);
+    for (const seg of target.split("/")) {
+        if (seg === "" || seg === ".")
+            continue;
+        if (seg === "..")
+            parts.pop();
+        else
+            parts.push(seg);
+    }
+    return parts.join("/");
+}
+const NOTES_SLIDE_PART = /^ppt\/notesSlides\/notesSlide\d+\.xml$/;
+const PRESENTATION_PART = "ppt/presentation.xml";
+/**
+ * The slide parts a deck actually presents, in `<p:sldIdLst>` order, resolved via
+ * `presentation.xml.rels`. Returns full archive paths (e.g. `ppt/slides/slide1.xml`).
+ *
+ * This deliberately does NOT enumerate `ppt/slides/_rels`: when automizer builds a
+ * deck it removes the template's original slides from `<p:sldIdLst>` first, but
+ * leaves their physical `slideN.xml`/`slideN.xml.rels` parts in the archive until
+ * a later cleanup pass. Those orphaned slide rels still carry `/notesSlide`
+ * relationships, so folder-enumeration would wrongly count template notes as
+ * referenced. Only slides reachable from `presentation.xml` are live.
+ */
+async function liveSlideParts(archive) {
+    const pres = parse(await readString(archive, PRESENTATION_PART));
+    const sldIds = pres.getElementsByTagName("p:sldId");
+    const rIds = [];
+    for (let i = 0; i < sldIds.length; i++) {
+        const rid = sldIds[i].getAttributeNS(NS_R, "id") || sldIds[i].getAttribute(Attr.HLINK_ID);
+        if (rid)
+            rIds.push(rid);
+    }
+    const relsDoc = parse(await readString(archive, PRESENTATION_RELS_PART));
+    const rels = relsDoc.getElementsByTagName(Tag.RELATIONSHIP);
+    const targetById = new Map();
+    for (let i = 0; i < rels.length; i++) {
+        const id = rels[i].getAttribute(Attr.ID);
+        const target = rels[i].getAttribute(Attr.TARGET);
+        if (id && target)
+            targetById.set(id, target);
+    }
+    const parts = [];
+    for (const rid of rIds) {
+        const target = targetById.get(rid);
+        if (target)
+            parts.push(resolveRelative("ppt", target));
+    }
+    return parts;
+}
+/** The `_rels` path for an archive part (`ppt/slides/slide1.xml` → `ppt/slides/_rels/slide1.xml.rels`). */
+function relsPathFor(part) {
+    return part.replace(/\/([^/]+)$/, "/_rels/$1.rels");
+}
+/**
+ * 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 async function sweepOrphanNotes(archive) {
+    const notesParts = (await archive.folder("ppt/notesSlides"))
+        .map((entry) => entry.name)
+        .filter((name) => NOTES_SLIDE_PART.test(name));
+    if (notesParts.length === 0)
+        return;
+    const referenced = new Set();
+    for (const slidePart of await liveSlideParts(archive)) {
+        const relsPath = relsPathFor(slidePart);
+        if (!archive.fileExists(relsPath))
+            continue;
+        const rels = parse(await readString(archive, relsPath)).getElementsByTagName(Tag.RELATIONSHIP);
+        for (let i = 0; i < rels.length; i++) {
+            const target = rels[i].getAttribute(Attr.TARGET);
+            if (target && rels[i].getAttribute(Attr.TYPE)?.endsWith(REL_TYPE_SUFFIX.NotesSlide)) {
+                referenced.add(resolveRelative("ppt/slides", target));
+            }
+        }
+    }
+    const orphans = notesParts.filter((part) => !referenced.has(part));
+    if (orphans.length === 0)
+        return;
+    const ctDoc = parse(await readString(archive, CONTENT_TYPES_PART));
+    let ctChanged = false;
+    for (const part of orphans) {
+        await archive.remove(part);
+        const relsPart = `ppt/notesSlides/_rels/${part.slice(part.lastIndexOf("/") + 1)}.rels`;
+        if (archive.fileExists(relsPart))
+            await archive.remove(relsPart);
+        if (removeOverrideFromDoc(ctDoc, `/${part}`))
+            ctChanged = true;
+    }
+    if (ctChanged)
+        await archive.write(CONTENT_TYPES_PART, serialize(ctDoc));
+}
+/**
+ * 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 async function applyNotesToSlide(archive, slideNumber, notes, excludeNotes) {
+    const notesPath = `ppt/notesSlides/notesSlide${slideNumber}.xml`;
+    const notesRelsPath = `ppt/notesSlides/_rels/notesSlide${slideNumber}.xml.rels`;
+    const slideRelsPath = `ppt/slides/_rels/slide${slideNumber}.xml.rels`;
+    const notesExists = archive.fileExists(notesPath);
+    const shouldWrite = notes !== undefined && notes !== "" && !excludeNotes;
+    if (shouldWrite) {
+        if (notesExists) {
+            // Auto-copied part: overwrite its body; leave rels + content-type as wired.
+            await archive.write(notesPath, buildNotesSlideXml(notes));
+            return;
+        }
+        const masterTarget = await findNotesMaster(archive);
+        if (masterTarget === undefined) {
+            throw new Error(`Speaker notes: slide ${slideNumber} has notes, but the template ships no notes master ` +
+                "(ppt/notesMasters/). Add a notes master to the template (PowerPoint: View → Notes Master), " +
+                "or build with notes disabled. Synthesizing a notes master is not supported.");
+        }
+        await archive.write(notesPath, buildNotesSlideXml(notes));
+        await archive.write(notesRelsPath, notesRelsXml(slideNumber, masterTarget));
+        const relsDoc = parse(await readString(archive, slideRelsPath));
+        appendRel(relsDoc, nextFreeRIdForDoc(relsDoc), REL_TYPE.NotesSlide, `../notesSlides/notesSlide${slideNumber}.xml`);
+        await archive.write(slideRelsPath, serialize(relsDoc));
+        await addContentTypeOverride(archive, `/${notesPath}`);
+        return;
+    }
+    if (!notesExists)
+        return;
+    await archive.remove(notesPath);
+    if (archive.fileExists(notesRelsPath))
+        await archive.remove(notesRelsPath);
+    const relsDoc = parse(await readString(archive, slideRelsPath));
+    if (removeNotesRel(relsDoc))
+        await archive.write(slideRelsPath, serialize(relsDoc));
+    await removeContentTypeOverride(archive, `/${notesPath}`);
+}

package/dist/engine/types.d.ts

@@ -1,11 +1,3 @@
-/** How the engine should scale an image inside its picture frame. */
-export declare const FitMode: {
-    /** Shrink the picture frame to the image's aspect ratio, centered. */
-    readonly Contain: "contain";
-    /** Fill the frame; center-crop overflow via srcRect. */
-    readonly Cover: "cover";
-};
-export type FitMode = (typeof FitMode)[keyof typeof FitMode];
 /**
  * Fill-strategy discriminator carried on every Slot. Required — there is no
  * silent default. The engine dispatches to fillTemplate / fillText / fillTable /
@@ -80,15 +72,26 @@ export type TableFill = {
     rows: StyledParagraph[][];
 };
 /**
- * Input to fillImage — a resolved image path plus its fit mode. `path` must
- * be an absolute filesystem path; the compiler is responsible for resolution
- * before an ImageFill reaches the engine. Relative paths fail loudly at
- * `readFileSync` / `imageSize` in the engine.
+ * How a picture is scaled into its frame — the engine's image-sizing directive,
+ * mirroring CSS `object-fit`. `contain`: fit the whole image, scale both ways,
+ * letterbox. `cover`: fill the frame, centre-crop the overflow. `scale-down`:
+ * like contain but never enlarge past native (a small image sits at native size).
+ */
+export declare const ImageFit: {
+    readonly Contain: "contain";
+    readonly Cover: "cover";
+    readonly ScaleDown: "scale-down";
+};
+export type ImageFit = (typeof ImageFit)[keyof typeof ImageFit];
+/**
+ * Input to fillImage — a resolved image path plus its object-fit directive.
+ * `path` must be absolute; the compiler resolves it (and maps the asset's
+ * semantic type to a `fit`) before the ImageFill reaches the engine.
  */
 export type ImageFill = {
     type: typeof SlotType.Image;
     path: string;
-    fit: FitMode;
+    fit: ImageFit;
 };
 export type Slot = {
     key: string;
@@ -97,8 +100,6 @@ export type Slot = {
     type: SlotType;
     /** Leave the first N specimen paragraphs untouched (fillText only). */
     startAt?: number;
-    /** Enforced column count for table slots. */
-    columns?: number;
 };
 export type Layout = {
     name: string;
@@ -111,6 +112,8 @@ export type Layout = {
 export type DeckStep = {
     layout: string;
     content?: Record<string, TextFill | TableFill | ImageFill | TemplateFill>;
+    /** Slide-level speaker notes — plain text, one paragraph per line. Not a slot. */
+    notes?: string;
 };
 export type Deck = {
     theme: string;

package/dist/engine/types.js

@@ -1,10 +1,3 @@
-/** How the engine should scale an image inside its picture frame. */
-export const FitMode = {
-    /** Shrink the picture frame to the image's aspect ratio, centered. */
-    Contain: "contain",
-    /** Fill the frame; center-crop overflow via srcRect. */
-    Cover: "cover",
-};
 /**
  * Fill-strategy discriminator carried on every Slot. Required — there is no
  * silent default. The engine dispatches to fillTemplate / fillText / fillTable /
@@ -20,3 +13,14 @@ export const SlotType = {
     /** fillImage: swap the picture's blip and adjust frame geometry. */
     Image: "image",
 };
+/**
+ * How a picture is scaled into its frame — the engine's image-sizing directive,
+ * mirroring CSS `object-fit`. `contain`: fit the whole image, scale both ways,
+ * letterbox. `cover`: fill the frame, centre-crop the overflow. `scale-down`:
+ * like contain but never enlarge past native (a small image sits at native size).
+ */
+export const ImageFit = {
+    Contain: "contain",
+    Cover: "cover",
+    ScaleDown: "scale-down",
+};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { type Config, type ThemeConfig } from "./engine/index.js";
+import { type Config, type GenerateOptions, type ThemeConfig } from "./engine/index.js";
 import { type CompilerConfig, type CompilerDeck, type CompilerThemeConfig, type ResolvedCompilerDeck } from "./markdown/types.js";
 /**
  * Run every compiler-owned resolver over `deck` (highlight code fences,
@@ -37,9 +37,9 @@ export declare function toEngineConfig(config: CompilerConfig): Config;
  * Mermaid PNGs are cached under `<outputDir>/.tycoslide-cache/mermaid/` so no
  * post-write cleanup is needed.
  */
-export declare function buildDeck(deck: CompilerDeck, config: CompilerConfig): Promise<void>;
-export type { Config, Deck, DeckStep, ImageFill, Layout, Slot, StyledParagraph, TableFill, TextFill, TextRun, ThemeConfig, } from "./engine/index.js";
-export { FitMode, fillImage, fillTable, fillTemplate, fillText, generate, SlotType } from "./engine/index.js";
+export declare function buildDeck(deck: CompilerDeck, config: CompilerConfig, options?: GenerateOptions): Promise<void>;
+export type { Config, Deck, DeckStep, GenerateOptions, ImageFill, Layout, Slot, StyledParagraph, TableFill, TextFill, TextRun, ThemeConfig, } from "./engine/index.js";
+export { fillImage, fillTable, fillTemplate, fillText, generate, SlotType } from "./engine/index.js";
 export type { ManifestOptions } from "./manifest.js";
 export { generateManifest } from "./manifest.js";
 export type { AssetCatalog, AssetEntry, CodeFence, CompilerConfig, CompilerDeck, CompilerDeckStep, CompilerLayout, CompilerParameter, CompilerSlot, CompilerThemeConfig, MarkdownBlock, MermaidConfig, MermaidFence, MermaidVariant, ParsedDocument, RawSlide, } from "./markdown/index.js";