@tycoworks/tycoslide 0.7.0 → 0.9.0

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,37 +72,78 @@ 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;
-    shapeName: string;
-    /** Fill strategy discriminator — required, no silent default. */
+/** A shape's absolute position and size, in EMU — the slot's frame. */
+export type Frame = {
+    x: number;
+    y: number;
+    cx: number;
+    cy: number;
+};
+/**
+ * A kind of content a slot accepts, and the real template shape that realizes
+ * it. `type` is the fill-strategy discriminator; `shapeName` names the shape on
+ * `sourceSlide` that carries the specimen styling. When `sourceSlide` equals the
+ * layout's `baseSlide` the shape is already on the cloned slide (fill in place);
+ * otherwise the shape is transplanted from `sourceSlide` into the slot's frame.
+ * `startAt` is a text-specimen concern (leave the first N specimen paragraphs
+ * untouched) and only meaningful on a text block.
+ *
+ * Named `Block` — a kind of content (image / table / text) the way an author
+ * thinks of it. Distinct from the compiler's `MarkdownBlock` (a parsed markdown
+ * block); different layer, kept separate on purpose.
+ */
+export type Block = {
     type: SlotType;
-    /** Leave the first N specimen paragraphs untouched (fillText only). */
+    sourceSlide: number;
+    shapeName: string;
     startAt?: number;
-    /** Enforced column count for table slots. */
-    columns?: number;
+};
+/**
+ * An author-facing fill region. Not welded to one shape+type: a slot owns its
+ * `frame` and `accepts` a set of `Block`s; the supplied value's shape selects
+ * which block fills. A block whose `sourceSlide === baseSlide` fills in place;
+ * any other block is transplanted into the slot's `frame`.
+ */
+export type Slot = {
+    key: string;
+    frame: Frame;
+    accepts: Block[];
 };
 export type Layout = {
     name: string;
-    slideNumber: number;
-    description: string;
-    whenToUse: string;
-    whenNotToUse: string;
+    /**
+     * The template slide cloned for chrome/background. A block whose `sourceSlide`
+     * equals this is filled in place; any other block is transplanted onto the clone.
+     */
+    baseSlide: number;
     slots: Slot[];
 };
 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,18 +1,5 @@
-import { type Config, 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,
- * render mermaid PNGs) and return a `ResolvedCompilerDeck` whose content
- * values are narrowed to the engine's `TextFill | TableFill | ImageFill |
- * TemplateFill` union. Structurally equivalent to the engine's `Deck` — a
- * caller passes the returned value straight to `generate()` with no cast.
- *
- * Fails fast if `deck.output` is missing: downstream `generate()` requires it,
- * and the CLI populates it before calling `buildDeck`; a programmatic caller
- * that forgot to set it hits the error here instead of a confusing engine-side
- * failure.
- */
-export declare function resolveDeck(deck: CompilerDeck, config: CompilerConfig): Promise<ResolvedCompilerDeck>;
+import { type Config, type GenerateOptions, type ThemeConfig } from "./engine/index.js";
+import { type CompilerConfig, type CompilerDeck, type CompilerThemeConfig } from "./markdown/types.js";
 /**
  * Project a CompilerThemeConfig down to the engine's ThemeConfig shape.
  * Fields are copied cell-by-cell so the boundary is explicit — no casts.
@@ -28,19 +15,26 @@ export declare function toEngineThemeConfig(config: CompilerThemeConfig): ThemeC
  */
 export declare function toEngineConfig(config: CompilerConfig): Config;
 /**
- * End-to-end build: run compiler-owned resolvers (syntax highlighting, mermaid
- * PNG rendering) over the deck via `resolveDeck`, which returns a narrowed
- * `ResolvedCompilerDeck` — structurally equivalent to the engine's `Deck` —
- * then hand it to the engine's primitives-only `generate()`. No cast required:
- * the narrowing happens at the type level via `resolveDeck`.
+ * End-to-end build: `compileDeck` already produced engine-shaped content (code
+ * highlighted, mermaid rendered), so `buildDeck` only asserts an `output` is set
+ * and hands the deck to the engine's primitives-only `generate()`. The deck is
+ * structurally equivalent to the engine's `Deck` once `output` is present, so no
+ * cast is required. `buildDeck` does not itself validate `config` — a
+ * programmatic caller assembling a `CompilerConfig` by hand should load it
+ * through `loadThemeConfig` (or `parseThemeConfig`) first to get the same
+ * fail-fast structural checks the CLI gets.
+ *
+ * Fails fast if `deck.output` is missing: `generate()` requires it, and the CLI
+ * populates it before calling `buildDeck`; a programmatic caller that forgot to
+ * set it hits this error instead of a confusing engine-side failure.
  *
  * 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";
-export { CompilerSlotType, compileMarkdownDeck, FenceType, ParameterType, resolveFences } from "./markdown/index.js";
+export type { AssetCatalog, AssetEntry, CompilerBlock, CompilerConfig, CompilerDeck, CompilerDeckStep, CompilerLayout, CompilerParameter, CompilerSlot, CompilerThemeConfig, EngineFill, Limit, MermaidConfig, MermaidVariant, ParsedDocument, RawSlide, } from "./markdown/index.js";
+export { AcceptType, compileMarkdownDeck, loadThemeConfig, ParameterType, parseThemeConfig } from "./markdown/index.js";