@tycoworks/tycoslide 0.8.0 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # tycoslide
 
-Let AI agents build slides from existing PowerPoint (`.pptx`) templates.
+Let AI agents build slides from existing PowerPoint (`.pptx`) files.
 
 > **Early release** — tycoslide is under active development.
 

package/dist/cli.js

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { buildDeck } from "./index.js";
 import { generateManifest } from "./manifest.js";
-import { compileDeck, parseSlideDocument, RESERVED_KEY, } from "./markdown/index.js";
+import { compileDeck, loadThemeConfig, parseSlideDocument, RESERVED_KEY } from "./markdown/index.js";
 const DEFAULT_CONFIG = "theme.json";
 const SKILL_DIR = "skills/slides";
 const PLUGIN_DIR = ".claude-plugin";
@@ -16,16 +16,6 @@ const BUILD_COMMAND = "npx tycoslide build";
 const sdkDir = dirname(fileURLToPath(import.meta.url));
 const skillMdPath = resolve(sdkDir, "..", SKILL_FILE);
 const syntaxMdPath = resolve(sdkDir, "..", SYNTAX_FILE);
-function loadConfig(absPath) {
-    let raw;
-    try {
-        raw = JSON.parse(readFileSync(absPath, "utf-8"));
-    }
-    catch {
-        throw new Error(`Config file not found or invalid JSON: ${absPath}`);
-    }
-    return { ...raw, rootDir: dirname(absPath) };
-}
 const pkg = JSON.parse(readFileSync(resolve(sdkDir, "..", "package.json"), "utf-8"));
 const program = new Command().name("tycoslide").description("PPTX template engine CLI").version(pkg.version);
 program
@@ -53,8 +43,8 @@ program
     if (!absConfigPath) {
         throw new Error(`${basename(deckPath)}: missing required "${RESERVED_KEY.THEME}" in global frontmatter`);
     }
-    const config = loadConfig(absConfigPath);
-    const deck = compileDeck(doc, config.layouts, config.rootDir, config.assets);
+    const config = loadThemeConfig(absConfigPath);
+    const deck = await compileDeck(doc, config);
     if (!deck.output)
         deck.output = basename(deckPath).replace(/\.md$/, ".pptx");
     await buildDeck(deck, config, { excludeNotes: !opts.notes });
@@ -65,7 +55,7 @@ program
     .option(`-c, --config <path>`, "path to theme config file", DEFAULT_CONFIG)
     .option(`-o, --out <file>`, "write to file instead of stdout")
     .action(async (opts) => {
-    const config = loadConfig(resolve(process.cwd(), opts.config));
+    const config = loadThemeConfig(resolve(process.cwd(), opts.config));
     const json = generateManifest(config, { build: { command: BUILD_COMMAND } });
     if (opts.out) {
         writeFileSync(resolve(process.cwd(), opts.out), `${json}\n`);
@@ -80,7 +70,7 @@ program
     .description("Generate plugin package (plugin.json, manifest.json, SKILL.md, syntax.md) for AI agents")
     .option(`-c, --config <path>`, "path to theme config file", DEFAULT_CONFIG)
     .action(async (opts) => {
-    const config = loadConfig(resolve(process.cwd(), opts.config));
+    const config = loadThemeConfig(resolve(process.cwd(), opts.config));
     const cwd = process.cwd();
     const pkg = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf-8"));
     const pluginMeta = {

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

@@ -1,22 +1,30 @@
 /**
  * The `Filler` strategy registry — one plain-object strategy per SlotType, each
- * pairing a value discriminator with a slide-level fill. The record key IS the
- * slot type, so a strategy carries no redundant `type` field. `generate()`
- * consults `FILLERS[slot.type]` once per (slot, value): `matches` validates the
- * value shape, then `fill` applies it to the slide.
+ * pairing a value discriminator with the element-level modify callbacks that
+ * apply it. The record key IS the slot type, so a strategy carries no redundant
+ * `type` field.
  *
- * Element-level geometry lives in the `fillX` primitives; slide-level concerns
- * (media pre-swap for images, relation access for body hyperlinks, column
- * validation for tables) live in the strategy wrappers here.
+ * `callbacks(value, target)` returns the `(element, relation)` callbacks that
+ * fill one shape. They are deliberately shape-name-agnostic beyond the `target`
+ * so they can be applied two ways: `slide.modifyElement(name, callbacks)` for a
+ * shape already on the cloned base slide, or `slide.addElement(alias, n, name,
+ * callbacks)` for a shape transplanted from another slide — pptx-automizer runs
+ * an appended shape's callbacks against the imported element itself, so the same
+ * callbacks refill a transplant.
+ *
+ * Element-level geometry lives in the `fillX` primitives; cross-shape concerns
+ * (media pre-swap for images) live in the callbacks here.
  */
-import { type Slot, SlotType } from "../types.js";
-export type FillContext = {
-    layoutName: string;
+import { SlotType } from "../types.js";
+/** The shape a filler targets, plus its slot-level options (startAt for text). */
+export type FillTarget = {
+    shapeName: string;
+    startAt?: number;
 };
+/** A pptx-automizer element-modify callback: `(element, relation) => void`. */
+export type ShapeCallback = (element: any, relation: any) => unknown;
 export interface Filler<T> {
     matches(v: unknown): v is T;
-    /** Human name for the mismatch error — no magic string at the throw site. */
-    label: string;
-    fill(slide: any, slot: Slot, value: T, ctx: FillContext): void;
+    callbacks(value: T, target: FillTarget): ShapeCallback[];
 }
 export declare const FILLERS: Record<SlotType, Filler<any>>;

package/dist/engine/fillers/filler.js

@@ -1,13 +1,19 @@
 /**
  * The `Filler` strategy registry — one plain-object strategy per SlotType, each
- * pairing a value discriminator with a slide-level fill. The record key IS the
- * slot type, so a strategy carries no redundant `type` field. `generate()`
- * consults `FILLERS[slot.type]` once per (slot, value): `matches` validates the
- * value shape, then `fill` applies it to the slide.
+ * pairing a value discriminator with the element-level modify callbacks that
+ * apply it. The record key IS the slot type, so a strategy carries no redundant
+ * `type` field.
  *
- * Element-level geometry lives in the `fillX` primitives; slide-level concerns
- * (media pre-swap for images, relation access for body hyperlinks, column
- * validation for tables) live in the strategy wrappers here.
+ * `callbacks(value, target)` returns the `(element, relation)` callbacks that
+ * fill one shape. They are deliberately shape-name-agnostic beyond the `target`
+ * so they can be applied two ways: `slide.modifyElement(name, callbacks)` for a
+ * shape already on the cloned base slide, or `slide.addElement(alias, n, name,
+ * callbacks)` for a shape transplanted from another slide — pptx-automizer runs
+ * an appended shape's callbacks against the imported element itself, so the same
+ * callbacks refill a transplant.
+ *
+ * Element-level geometry lives in the `fillX` primitives; cross-shape concerns
+ * (media pre-swap for images) live in the callbacks here.
  */
 import { basename } from "node:path";
 import { ModifyImageHelper } from "pptx-automizer";
@@ -19,32 +25,23 @@ import { fillText, isTextFill } from "./text.js";
 export const FILLERS = {
     [SlotType.Template]: {
         matches: isTemplateFill,
-        label: "TemplateFill",
-        fill: (slide, slot, v) => slide.modifyElement(slot.shapeName, [(el) => fillTemplate(el, v, slot.shapeName)]),
+        callbacks: (v, t) => [(el) => fillTemplate(el, v, t.shapeName)],
     },
     [SlotType.Text]: {
         matches: isTextFill,
-        label: "TextFill",
-        fill: (slide, slot, v) => {
-            const startAt = slot.startAt ?? 0;
-            slide.modifyElement(slot.shapeName, [
-                (el, relation) => fillText(el, v, { startAt, relation, shapeName: slot.shapeName }),
-            ]);
-        },
+        callbacks: (v, t) => [
+            (el, relation) => fillText(el, v, { startAt: t.startAt ?? 0, relation, shapeName: t.shapeName }),
+        ],
     },
     [SlotType.Table]: {
         matches: isTableFill,
-        label: "TableFill",
-        fill: (slide, slot, v) => {
-            slide.modifyElement(slot.shapeName, [(el) => fillTable(el, v, slot.shapeName)]);
-        },
+        callbacks: (v, t) => [(el) => fillTable(el, v, t.shapeName)],
     },
     [SlotType.Image]: {
         matches: isImageFill,
-        label: "ImageFill",
-        fill: (slide, slot, v) => slide.modifyElement(slot.shapeName, [
+        callbacks: (v, t) => [
             ModifyImageHelper.setRelationTarget(basename(v.path)),
-            (el) => fillImage(el, v, slot.shapeName),
-        ]),
+            (el) => fillImage(el, v, t.shapeName),
+        ],
     },
 };

package/dist/engine/generate.d.ts

@@ -18,11 +18,15 @@
  *     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 = {
     /**
@@ -40,22 +44,24 @@ export type GenerateOptions = {
  *   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, 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,9 +18,13 @@
  *     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";
@@ -36,9 +40,9 @@ import { applyNotesToSlide, sweepOrphanNotes } from "./notes.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, options = {}) {
@@ -62,33 +66,17 @@ export async function generate(deck, config, options = {}) {
             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);
@@ -98,29 +86,13 @@ export async function generate(deck, config, options = {}) {
                     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
@@ -128,8 +100,9 @@ export async function generate(deck, config, options = {}) {
     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.
@@ -162,6 +135,35 @@ export async function generate(deck, config, options = {}) {
     }
     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";
@@ -173,6 +175,105 @@ function describeValue(v) {
     }
     return typeof v;
 }
+// ── Slot fill dispatch (composition-aware) ───────────────────────────────────
+/**
+ * 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; `generate()` calls it inside the `addSlide` callback.
+ */
+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";
@@ -227,17 +328,3 @@ function toNotesArchive(target) {
         },
     };
 }
-// ── 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

@@ -5,5 +5,5 @@ 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 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/types.d.ts

@@ -93,20 +93,50 @@ export type ImageFill = {
     path: string;
     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;
 };
+/**
+ * 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 = {

package/dist/index.d.ts

@@ -1,18 +1,5 @@
 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,
- * 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 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,11 +15,18 @@ 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.
@@ -42,5 +36,5 @@ export type { Config, Deck, DeckStep, GenerateOptions, ImageFill, Layout, Slot,
 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";