@tycoworks/tycoslide 0.8.0 → 0.10.0

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

package/dist/index.js

@@ -1,99 +1,64 @@
 import { generate, SlotType, } from "./engine/index.js";
-import { isFence, resolveFences } from "./markdown/resolvers/resolver.js";
-import { CompilerSlotType, ParameterType, } from "./markdown/types.js";
+import { ParameterType, } from "./markdown/types.js";
 /**
- * Narrow a resolved content map to the engine-shaped value union. Runs after
- * `resolveFences`, so no CodeFence or MermaidFence should remain — a leftover is
- * a resolver bug and throws. Every surviving value is already an engine fill
- * (TextFill / TableFill / ImageFill / TemplateFill), so no unwrapping is needed.
+ * A frontmatter parameter always fills one physical shape on the layout's own
+ * slide, so it projects to a single base `Block` (`sourceSlide === baseSlide`)
+ * and never transplants — its `frame` is never read. `NO_FRAME` is that unread
+ * placeholder; only body slots with a transplant block carry a real frame.
  */
-function narrowContent(content) {
-    const out = {};
-    for (const [key, value] of Object.entries(content)) {
-        if (isFence(value)) {
-            throw new Error(`resolveDeck: slot "${key}" still holds an unresolved ${value.type} block ` +
-                "after resolvers ran. This is a resolver bug.");
-        }
-        out[key] = value;
+const NO_FRAME = { x: 0, y: 0, cx: 0, cy: 0 };
+function paramToEngineSlot(param, baseSlide) {
+    const block = (type) => ({ type, sourceSlide: baseSlide, shapeName: param.shapeName });
+    switch (param.type) {
+        case ParameterType.Template:
+            // A text shape carries no top-level key — its template placeholders are the keys. The
+            // compiler emits its expanded content under shapeName, so the engine slot
+            // is keyed by shapeName too.
+            return { key: param.shapeName, frame: NO_FRAME, accepts: [block(SlotType.Template)] };
+        case ParameterType.Image:
+            return { key: param.key, frame: NO_FRAME, accepts: [block(SlotType.Image)] };
     }
-    return out;
 }
 /**
- * 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.
+ * Project a body slot's real `accepts` to engine `Block[]` and pass its `frame`
+ * through. The compiler `accepts` already carry engine content types
+ * (text/table/image) — code folded to text and mermaid to image at authoring —
+ * so projection is 1:1. A slot with no declared `frame` (a base-only slot that
+ * never transplants) gets `NO_FRAME`, which the engine never reads.
  */
-export async function resolveDeck(deck, config) {
-    await resolveFences(deck, config);
-    if (deck.output === undefined) {
-        throw new Error('resolveDeck: deck.output is not set. Set it (e.g. "deck.pptx") before calling buildDeck.');
-    }
-    return {
-        theme: deck.theme,
-        output: deck.output,
-        steps: deck.steps.map((step) => {
-            const resolvedStep = { layout: step.layout };
-            if (step.content)
-                resolvedStep.content = narrowContent(step.content);
-            if (step.notes !== undefined)
-                resolvedStep.notes = step.notes;
-            return resolvedStep;
-        }),
-    };
+function slotToEngineSlot(slot) {
+    const accepts = slot.accepts.map((b) => {
+        const eb = { type: b.type, sourceSlide: b.sourceSlide, shapeName: b.shapeName };
+        if (b.startAt !== undefined)
+            eb.startAt = b.startAt;
+        return eb;
+    });
+    return { key: slot.key, frame: slot.frame ?? NO_FRAME, accepts };
 }
 /**
- * Project a CompilerParameter or CompilerSlot down to the engine's flat Slot.
- * Parameters (Template, Image) map straight to their engine equivalent; compiler-
- * only slot types (Code, Mermaid) map to Text / Image since their resolved
- * StyledParagraph[] / ImageFill content is filled by the corresponding engine
- * primitive once the compiler is done.
- *
- * The discriminated unions narrow per-variant fields, so the projection is a
- * straight switch over all six type values — no runtime "wrong field on wrong
- * type" checks; TypeScript enforces the invariants at authoring time.
+ * Compiler→engine boundary check: a slot with a transplant block (any block
+ * whose `sourceSlide` differs from the layout's base slide) must declare a
+ * `frame` — the real region the transplant is positioned into. A base-only slot
+ * (all blocks in place) needs none. Missing → fail fast, naming layout + slot.
+ * (The engine's `assertSlotsWellFormed` separately rejects duplicate accept
+ * types.)
  */
-function toEngineSlot(slot) {
-    switch (slot.type) {
-        case ParameterType.Template:
-            // A text shape carries no top-level key — its template placeholders are the keys. The
-            // compiler emits its expanded content under shapeName, so the engine slot
-            // is keyed by shapeName too.
-            return { key: slot.shapeName, shapeName: slot.shapeName, type: SlotType.Template };
-        case ParameterType.Image:
-            return { key: slot.key, shapeName: slot.shapeName, type: SlotType.Image };
-        case CompilerSlotType.Text: {
-            const result = { key: slot.key, shapeName: slot.shapeName, type: SlotType.Text };
-            if (slot.startAt !== undefined)
-                result.startAt = slot.startAt;
-            return result;
+function assertSlotFrames(layout) {
+    for (const slot of layout.slots) {
+        const transplants = slot.accepts.some((b) => b.sourceSlide !== layout.slideNumber);
+        if (transplants && slot.frame === undefined) {
+            throw new Error(`Layout "${layout.name}" slot "${slot.key}": a transplant block (sourceSlide ≠ ${layout.slideNumber}) ` +
+                'requires a "frame" (the region to position it into), but none is declared.');
         }
-        case CompilerSlotType.Table:
-            return { key: slot.key, shapeName: slot.shapeName, type: SlotType.Table };
-        case CompilerSlotType.Code:
-            // Highlighter resolves the code fence into StyledParagraph[]; engine
-            // fills it via fillText.
-            return { key: slot.key, shapeName: slot.shapeName, type: SlotType.Text };
-        case CompilerSlotType.Mermaid:
-            // Mermaid renderer produces a PNG (ImageFill); engine fills it via
-            // fillImage. The fit lives on the ImageFill, not the engine Slot.
-            return { key: slot.key, shapeName: slot.shapeName, type: SlotType.Image };
     }
 }
 function toEngineLayout(layout) {
+    assertSlotFrames(layout);
+    const base = layout.slideNumber;
     return {
         name: layout.name,
-        slideNumber: layout.slideNumber,
-        description: layout.description,
-        whenToUse: layout.whenToUse,
-        whenNotToUse: layout.whenNotToUse,
-        slots: [...layout.parameters.map(toEngineSlot), ...layout.slots.map(toEngineSlot)],
+        baseSlide: base,
+        slots: [...layout.parameters.map((p) => paramToEngineSlot(p, base)), ...layout.slots.map(slotToEngineSlot)],
     };
 }
 /**
@@ -124,21 +89,31 @@ export function toEngineConfig(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 async function buildDeck(deck, config, options = {}) {
-    const resolved = await resolveDeck(deck, config);
-    await generate(resolved, toEngineConfig(config), options);
+    if (deck.output === undefined) {
+        throw new Error('buildDeck: deck.output is not set. Set it (e.g. "deck.pptx") before calling buildDeck.');
+    }
+    const engineDeck = { theme: deck.theme, output: deck.output, steps: deck.steps };
+    await generate(engineDeck, toEngineConfig(config), options);
 }
 // Engine — primitives-only public surface.
 export { fillImage, fillTable, fillTemplate, fillText, generate, SlotType } from "./engine/index.js";
 export { generateManifest } from "./manifest.js";
 // Markdown / Compiler
-export { CompilerSlotType, compileMarkdownDeck, FenceType, ParameterType, resolveFences } from "./markdown/index.js";
+export { AcceptType, compileMarkdownDeck, loadThemeConfig, ParameterType, parseThemeConfig } from "./markdown/index.js";