@tycoworks/tycoslide 0.7.0

package/dist/engine/fillers/template.js

@@ -0,0 +1,221 @@
+/**
+ * Text-template fill — fills each visual line in place from its template
+ * segments. A visual line starts at either a paragraph boundary (`<a:p>`) or a
+ * soft line break (`<a:br/>`); template line i fills visual line i, 1:1. Styles
+ * are never read or changed: coalesce same-style runs, then a uniform line takes
+ * the substituted text directly, while a multi-style line is matched against the
+ * sample to place each variable's value in the run carrying its style.
+ */
+import { childrenByTag, collectElements, detach, isPlainObject, runText, setRunTextPreservingStyle, Tag, } from "../dom.js";
+/**
+ * Split a shape's text into visual lines. Walk each `<a:p>` in document order;
+ * within a paragraph, iterate child elements in order and cut a new visual line
+ * at every `<a:br/>` (`Tag.LINE_BREAK`), collecting the `<a:r>` runs into the
+ * current line. A paragraph yields (break count + 1) visual lines, so an empty
+ * line (a break with no runs) is still a line positionally.
+ */
+function visualLines(shape) {
+    const lines = [];
+    for (const para of collectElements(shape, Tag.PARAGRAPH)) {
+        let current = [];
+        for (let i = 0; i < para.childNodes.length; i++) {
+            const child = para.childNodes[i];
+            if (child?.nodeType !== 1)
+                continue;
+            if (child.tagName === Tag.LINE_BREAK) {
+                lines.push({ runs: current });
+                current = [];
+            }
+            else if (child.tagName === Tag.RUN) {
+                current.push(child);
+            }
+        }
+        lines.push({ runs: current });
+    }
+    return lines;
+}
+/**
+ * Fill a text shape from its template segments — styles are never read or
+ * changed. Template line i fills the shape's visual line i, 1:1, via
+ * `fillLineFromSegments`: coalesce same-style runs, then a uniform line takes the
+ * substituted text directly, while a multi-style line is matched against the
+ * sample to place each variable's value in the run carrying its style. A template
+ * with more lines than the shape has visual lines is an authoring error (throw);
+ * fewer lines fill the covered lines and leave the rest untouched.
+ */
+export function fillTemplate(shape, fill, shapeName = "") {
+    const lines = visualLines(shape);
+    if (fill.lines.length > lines.length) {
+        throw new Error(`Text shape "${shapeName}": template has ${fill.lines.length} lines but the shape has only ${lines.length} visual line(s); ` +
+            "the template claims a line the shape doesn't have.");
+    }
+    for (let i = 0; i < fill.lines.length; i++) {
+        fillLineFromSegments(lines[i].runs, fill.lines[i], shapeName);
+    }
+}
+/** Discriminator for TemplateFill values. */
+export function isTemplateFill(v) {
+    return isPlainObject(v) && Array.isArray(v.lines);
+}
+function segmentText(s) {
+    return s.kind === "literal" ? s.text : s.value;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Fill one visual line from its template segments. Coalesce same-style runs
+ * within the line first; a resulting single run (uniform line) just takes the
+ * substituted text. A multi-run line has real style boundaries, so match the
+ * template's literals against the shape's sample text to place each variable's
+ * value in the run carrying its style. A variable whose matched span crosses run
+ * boundaries is not an error: it collapses to its first run's style (the spanned
+ * runs are emptied and detached). Position ambiguity still fails fast — adjacent
+ * variables with no separator, or a sample that doesn't fit the template.
+ */
+function fillLineFromSegments(lineRuns, segments, shapeName) {
+    const runs = coalesceRunList(lineRuns);
+    if (runs.length === 0)
+        return;
+    if (runs.length === 1) {
+        setRunTextPreservingStyle(runs[0], segments.map(segmentText).join(""));
+        return;
+    }
+    // Multi-run: real style boundaries.
+    for (let j = 1; j < segments.length; j++) {
+        const prev = segments[j - 1];
+        const cur = segments[j];
+        if (prev.kind === "variable" && cur.kind === "variable") {
+            throw new Error(`Text shape "${shapeName}": variables "{${prev.key}}" and "{${cur.key}}" are adjacent with no separator; ` +
+                "a multi-style shape needs a literal or style boundary between variables.");
+        }
+    }
+    const runTexts = runs.map(runText);
+    const bounds = [];
+    let acc = 0;
+    for (const t of runTexts) {
+        bounds.push([acc, acc + t.length]);
+        acc += t.length;
+    }
+    const sample = runTexts.join("");
+    const source = `^${segments.map((s) => (s.kind === "literal" ? escapeRegExp(s.text) : "([\\s\\S]*?)")).join("")}$`;
+    const match = new RegExp(source, "d").exec(sample);
+    if (!match?.indices) {
+        throw new Error(`Text shape "${shapeName}": its styled sample text ${JSON.stringify(sample)} does not fit the template; ` +
+            "make the shape a single style, or give it sample text matching the template's structure.");
+    }
+    const indices = match.indices;
+    const runOf = (pos) => {
+        for (let k = 0; k < bounds.length; k++)
+            if (pos >= bounds[k][0] && pos < bounds[k][1])
+                return k;
+        return bounds.length - 1;
+    };
+    const out = runs.map(() => "");
+    let cursor = 0;
+    let varIdx = 0;
+    for (const s of segments) {
+        if (s.kind === "literal") {
+            // A literal may straddle run boundaries — split it, each piece stays in its run.
+            let p = 0;
+            while (p < s.text.length) {
+                const k = runOf(cursor + p);
+                const take = Math.min(s.text.length, p + (bounds[k][1] - (cursor + p)));
+                out[k] += s.text.slice(p, take);
+                p = take;
+            }
+            cursor += s.text.length;
+        }
+        else {
+            varIdx++;
+            const span = indices[varIdx];
+            if (!span)
+                throw new Error(`Text shape "${shapeName}": failed to locate variable "{${s.key}}" in the sample text.`);
+            const [vs, ve] = span;
+            // A variable whose span crosses run boundaries collapses to its FIRST run:
+            // the value goes into `out[kStart]`, the spanned runs get no text (they end
+            // up ""), and we detach those empties below so the span becomes one run
+            // carrying the first run's style.
+            const kStart = runOf(vs);
+            out[kStart] += s.value;
+            cursor = ve;
+        }
+    }
+    for (let k = 0; k < runs.length; k++)
+        setRunTextPreservingStyle(runs[k], out[k]);
+    // Detach runs left empty (e.g. runs a collapsed variable's span passed over) so
+    // the visual line loses its now-textless runs. Never detach every run: if all
+    // ended up empty, keep the first as the surviving run.
+    const anyNonEmpty = out.some((t) => t !== "");
+    for (let k = 0; k < runs.length; k++) {
+        if (out[k] === "" && !(!anyNonEmpty && k === 0))
+            detach(runs[k]);
+    }
+}
+// ── Run coalescing (text-template fill) ───────────────────────────────────────
+//
+// PowerPoint scatters one logical line across several runs for no semantic
+// reason. Before a text-template fill we merge adjacent runs that carry an
+// identical style, so a uniform line collapses to one run. We only ever merge
+// runs we can PROVE are stylistically identical; anything uncertain is left
+// untouched — we never guess a run away.
+/**
+ * A run's `<a:rPr>` is "blank" (the default style) when it is missing entirely
+ * or carries no attributes and no child elements. A missing and an empty `<a:rPr>`
+ * are therefore the same style.
+ */
+function isBlankRPr(rPr) {
+    if (!rPr)
+        return true;
+    if (rPr.attributes.length > 0)
+        return false;
+    for (let i = 0; i < rPr.childNodes.length; i++)
+        if (rPr.childNodes[i]?.nodeType === 1)
+            return false;
+    return true;
+}
+/**
+ * Two runs share a style iff their `<a:rPr>` are equal. We compare the whole
+ * node via DOM `isEqualNode` (attribute-order-insensitive, recursive), so every
+ * property — bold, size, color, font, hyperlink, … — is covered without
+ * enumerating them; blank rPrs (missing or empty) compare equal to each other.
+ */
+function sameStyle(a, b) {
+    const ra = childrenByTag(a, Tag.RUN_PROPS)[0] ?? null;
+    const rb = childrenByTag(b, Tag.RUN_PROPS)[0] ?? null;
+    if (isBlankRPr(ra) && isBlankRPr(rb))
+        return true;
+    if (!ra || !rb)
+        return false;
+    return ra.isEqualNode(rb);
+}
+/**
+ * Merge adjacent runs in a run list that carry an identical style: keep the
+ * first, append the others' text into it, and detach the redundant runs.
+ * Provably-same-style only; distinct styles are preserved as separate runs.
+ * Returns the surviving runs (in order). Scoped to the given list — a visual
+ * line's runs, not necessarily a whole paragraph.
+ */
+function coalesceRunList(runs) {
+    const survivors = [];
+    let keep = null;
+    for (const run of runs) {
+        if (keep && sameStyle(keep, run)) {
+            setRunTextPreservingStyle(keep, runText(keep) + runText(run));
+            detach(run);
+        }
+        else {
+            keep = run;
+            survivors.push(run);
+        }
+    }
+    return survivors;
+}
+/**
+ * Merge adjacent same-style runs across a whole paragraph. Thin wrapper over
+ * `coalesceRunList` operating on the paragraph's direct `<a:r>` children.
+ * Exported for tests.
+ */
+export function coalesceSameStyleRuns(para) {
+    coalesceRunList(childrenByTag(para, Tag.RUN));
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Text fill — rebuilds a shape's paragraphs from a TextFill by harvesting
+ * specimen (pPr, rPr) buckets grouped by (bullet kind, level), detaching
+ * specimens from startAt onward, then building fresh paragraphs cloning the
+ * appropriate bucket. This is the strategy for body blocks, bullet lists, rich
+ * runs, and syntax-highlighted code.
+ */
+import type { TextFill } from "../types.js";
+/**
+ * Fill a text shape by rebuilding paragraphs from harvested specimen styles.
+ *
+ * Harvests specimen (pPr,rPr) buckets grouped by (bullet kind, level),
+ * detaches specimens from startAt onward, then builds fresh paragraphs
+ * cloning the appropriate bucket. Bullet input paragraphs pick a bullet
+ * bucket by level (clamped); non-bullet input picks the plain bucket. If a
+ * non-bullet paragraph follows any bullet paragraph, the bullet template's
+ * spcBef is grafted onto it (transition spacing).
+ *
+ * Rich per-paragraph runs (bold/italic/color/link) come through unchanged
+ * via setRichRuns.
+ */
+export declare function fillText(shape: any, fill: TextFill, opts?: {
+    startAt?: number;
+    relation?: any;
+    shapeName?: string;
+}): void;
+/** Discriminator for TextFill values. */
+export declare function isTextFill(v: unknown): v is TextFill;

package/dist/engine/fillers/text.js

@@ -0,0 +1,29 @@
+/**
+ * Text fill — rebuilds a shape's paragraphs from a TextFill by harvesting
+ * specimen (pPr, rPr) buckets grouped by (bullet kind, level), detaching
+ * specimens from startAt onward, then building fresh paragraphs cloning the
+ * appropriate bucket. This is the strategy for body blocks, bullet lists, rich
+ * runs, and syntax-highlighted code.
+ */
+import { isPlainObject, rebuildParagraphs } from "../dom.js";
+/**
+ * Fill a text shape by rebuilding paragraphs from harvested specimen styles.
+ *
+ * Harvests specimen (pPr,rPr) buckets grouped by (bullet kind, level),
+ * detaches specimens from startAt onward, then builds fresh paragraphs
+ * cloning the appropriate bucket. Bullet input paragraphs pick a bullet
+ * bucket by level (clamped); non-bullet input picks the plain bucket. If a
+ * non-bullet paragraph follows any bullet paragraph, the bullet template's
+ * spcBef is grafted onto it (transition spacing).
+ *
+ * Rich per-paragraph runs (bold/italic/color/link) come through unchanged
+ * via setRichRuns.
+ */
+export function fillText(shape, fill, opts = {}) {
+    const { startAt = 0, relation, shapeName = "" } = opts;
+    rebuildParagraphs(shape, fill.paragraphs, startAt, relation, shapeName);
+}
+/** Discriminator for TextFill values. */
+export function isTextFill(v) {
+    return isPlainObject(v) && Array.isArray(v.paragraphs);
+}

package/dist/engine/generate.d.ts

@@ -0,0 +1,51 @@
+/**
+ * PPTX Generation Engine — orchestration.
+ *
+ * `generate()` walks a Deck and dispatches each content value to one of four
+ * `Filler` strategies (in `fillers/filler.ts`), each taking its matching `XFill`:
+ *
+ *   TemplateFill  → fillTemplate   Fills each paragraph in place from its template
+ *     segments — styles are never read or changed. See fillers/template.ts.
+ *
+ *   TextFill  → fillText   Rebuilds a shape's paragraphs from harvested
+ *     specimen styles (bullets, rich runs, syntax-highlighted code). See
+ *     fillers/text.ts / dom.ts.
+ *
+ *   TableFill → fillTable  Clones specimen rows in the template's `<a:tbl>` and
+ *     fills each cell's first paragraph. See fillers/table.ts.
+ *
+ *   ImageFill → fillImage  Points the picture's blip relationship at a new media
+ *     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).
+ */
+import type { Config, Deck, Slot } from "./types.js";
+/**
+ * Generate a PPTX file from a deck definition and a theme configuration.
+ *
+ * Orchestration:
+ *   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]`.
+ *   4. Write the output PPTX.
+ */
+export declare function generate(deck: Deck, config: Config): 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.
+ *
+ * Exported for tests; not part of the public engine surface (index.ts).
+ */
+export declare function validateContentSlots(step: {
+    layout: string;
+    content?: Record<string, unknown>;
+}, tpl: {
+    slots: Slot[];
+}): void;

package/dist/engine/generate.js

@@ -0,0 +1,161 @@
+/**
+ * PPTX Generation Engine — orchestration.
+ *
+ * `generate()` walks a Deck and dispatches each content value to one of four
+ * `Filler` strategies (in `fillers/filler.ts`), each taking its matching `XFill`:
+ *
+ *   TemplateFill  → fillTemplate   Fills each paragraph in place from its template
+ *     segments — styles are never read or changed. See fillers/template.ts.
+ *
+ *   TextFill  → fillText   Rebuilds a shape's paragraphs from harvested
+ *     specimen styles (bullets, rich runs, syntax-highlighted code). See
+ *     fillers/text.ts / dom.ts.
+ *
+ *   TableFill → fillTable  Clones specimen rows in the template's `<a:tbl>` and
+ *     fills each cell's first paragraph. See fillers/table.ts.
+ *
+ *   ImageFill → fillImage  Points the picture's blip relationship at a new media
+ *     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).
+ */
+import { existsSync, rmSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { Automizer, modify } from "pptx-automizer";
+import { FILLERS } from "./fillers/filler.js";
+import { isImageFill } from "./fillers/image.js";
+/**
+ * Generate a PPTX file from a deck definition and a theme configuration.
+ *
+ * Orchestration:
+ *   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]`.
+ *   4. Write the output PPTX.
+ */
+export async function generate(deck, config) {
+    const { layouts, rootDir, template, outputDir } = config;
+    const outFile = deck.output;
+    const outDir = outputDir ?? process.cwd();
+    const automizer = new Automizer({
+        templateDir: resolve(rootDir, "template"),
+        outputDir: outDir,
+        removeExistingSlides: true,
+        autoImportSlideMasters: true,
+        useCreationIds: false,
+        cleanup: true,
+    });
+    const sourceAlias = "source";
+    const pres = automizer.loadRoot(template).load(template, sourceAlias);
+    // Look up the layout a step targets; an unknown name is a hard error.
+    const resolveLayout = (name) => {
+        const match = layouts.find((candidate) => candidate.name === name);
+        if (!match)
+            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().
+    const fillErrors = [];
+    const captureFillErrors = (slide) => {
+        const modifyElement = slide.modifyElement.bind(slide);
+        slide.modifyElement = (shapeName, callbacks) => modifyElement(shapeName, callbacks.map((cb) => typeof cb === "function"
+            ? (...args) => {
+                try {
+                    return cb(...args);
+                }
+                catch (err) {
+                    fillErrors.push(err instanceof Error ? err : new Error(String(err)));
+                    throw err;
+                }
+            }
+            : 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 });
+        }
+    };
+    for (const step of deck.steps) {
+        const layout = resolveLayout(step.layout);
+        pres.addSlide(sourceAlias, layout.slideNumber, (slide) => fillSlide(slide, layout, step));
+    }
+    await pres.write(outFile);
+    if (fillErrors.length > 0) {
+        // The output would be a broken deck — remove it so a failed build never
+        // leaves a misleading artifact behind.
+        rmSync(resolve(outDir, outFile), { force: true });
+        const detail = fillErrors.map((e) => `  - ${e.message}`).join("\n");
+        throw new Error(`generate: ${fillErrors.length} shape fill(s) failed while writing "${outFile}":\n${detail}`);
+    }
+    console.log(`tycoslide: built ${deck.steps.length} slide(s) → ${resolve(outDir, outFile)}`);
+}
+function describeValue(v) {
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "array";
+    if (typeof v === "object") {
+        const t = v.type;
+        return typeof t === "string" ? `object (type="${t}")` : "object";
+    }
+    return typeof v;
+}
+// ── Content-slot validation (test-visible helper) ────────────────────────────
+/**
+ * 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.
+ *
+ * Exported for tests; not part of the public engine surface (index.ts).
+ */
+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(", ")}`);
+    }
+}

package/dist/engine/index.d.ts

@@ -0,0 +1,8 @@
+export { FILLERS } from "./fillers/filler.js";
+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 { 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";

package/dist/engine/index.js

@@ -0,0 +1,7 @@
+export { FILLERS } from "./fillers/filler.js";
+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 { generate } from "./generate.js";
+export { FitMode, SlotType } from "./types.js";

package/dist/engine/types.d.ts

@@ -0,0 +1,128 @@
+/** 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 /
+ * fillImage based on this value.
+ */
+export declare const SlotType: {
+    /** fillTemplate: walk existing runs, replace each in place. */
+    readonly Template: "template";
+    /** fillText: rebuild paragraphs from harvested specimen styles. */
+    readonly Text: "text";
+    /** fillTable: clone specimen rows in an `<a:tbl>`. */
+    readonly Table: "table";
+    /** fillImage: swap the picture's blip and adjust frame geometry. */
+    readonly Image: "image";
+};
+export type SlotType = (typeof SlotType)[keyof typeof SlotType];
+/** A single styled span of text within a paragraph. */
+export type TextRun = {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    strikethrough?: boolean;
+    underline?: boolean;
+    link?: string;
+    color?: string;
+};
+/**
+ * The engine's one normalized text shape. `bullet` presence encodes both
+ * bullet-ness and level: absent = non-bullet, present = bullet at that level.
+ */
+export type StyledParagraph = {
+    runs: TextRun[];
+    bullet?: {
+        level: number;
+    };
+};
+/**
+ * One piece of a template line handed to fillTemplate: a fixed `literal`, or a
+ * `variable` carrying its already-substituted `value` (the `key` is kept only
+ * for error messages). The compiler parses each template line into an ordered
+ * list of these; the engine matches the literals against the shape's sample
+ * text to place each variable's value in the run that carries its style. The
+ * engine never parses `{}` syntax.
+ */
+export type TemplateSegment = {
+    kind: "literal";
+    text: string;
+} | {
+    kind: "variable";
+    key: string;
+    value: string;
+};
+/**
+ * Input to fillTemplate — one segment list per line (mapping to the shape's `<a:p>`
+ * in order). Distinguished from the other fills by its `lines` array.
+ */
+export type TemplateFill = {
+    lines: TemplateSegment[][];
+};
+/**
+ * Input to fillText — a shape's paragraphs rebuilt from harvested specimen
+ * styles. Distinguished from the other fills by its `paragraphs` array. Like
+ * the other three fills, `fillText` takes this whole object; the four
+ * `DeckStep.content` value shapes read as one family.
+ */
+export type TextFill = {
+    paragraphs: StyledParagraph[];
+};
+/** Input to fillTable — headers and body rows as styled cells. */
+export type TableFill = {
+    headers: StyledParagraph[];
+    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.
+ */
+export type ImageFill = {
+    type: typeof SlotType.Image;
+    path: string;
+    fit: FitMode;
+};
+export type Slot = {
+    key: string;
+    shapeName: string;
+    /** Fill strategy discriminator — required, no silent default. */
+    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;
+    slideNumber: number;
+    description: string;
+    whenToUse: string;
+    whenNotToUse: string;
+    slots: Slot[];
+};
+export type DeckStep = {
+    layout: string;
+    content?: Record<string, TextFill | TableFill | ImageFill | TemplateFill>;
+};
+export type Deck = {
+    theme: string;
+    /** Output filename. Required — no silent default. */
+    output: string;
+    steps: DeckStep[];
+};
+export type ThemeConfig = {
+    layouts: Layout[];
+    template: string;
+    outputDir?: string;
+};
+export type Config = ThemeConfig & {
+    rootDir: string;
+};

package/dist/engine/types.js

@@ -0,0 +1,22 @@
+/** 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 /
+ * fillImage based on this value.
+ */
+export const SlotType = {
+    /** fillTemplate: walk existing runs, replace each in place. */
+    Template: "template",
+    /** fillText: rebuild paragraphs from harvested specimen styles. */
+    Text: "text",
+    /** fillTable: clone specimen rows in an `<a:tbl>`. */
+    Table: "table",
+    /** fillImage: swap the picture's blip and adjust frame geometry. */
+    Image: "image",
+};