@tycoworks/tycoslide 0.7.0 → 0.9.0

package/dist/markdown/blocks/registry.js

@@ -0,0 +1,44 @@
+import { MdastType, parseRegion } from "../mdast.js";
+import { AcceptType } from "../types.js";
+import { CODE } from "./code.js";
+import { IMAGE } from "./image.js";
+import { MERMAID } from "./mermaid.js";
+import { TABLE } from "./table.js";
+import { compileTextAggregate } from "./text.js";
+// ── The one registry: every content kind is one row ───────────────────────────
+// One descriptor per content kind, carrying recognition (`match`/`acceptType`)
+// and the single `compile` that folds the node straight into an engine fill. A
+// region that is exactly one of these nodes folds to that kind. MERMAID precedes
+// CODE, but their matches are already disjoint on `lang`.
+const BLOCKS = [MERMAID, CODE, IMAGE, TABLE];
+/**
+ * Recognize a body/`::name::` region's content and return the engine
+ * `AcceptType` it folds to, plus a lazy `fill` that compiles it to the engine
+ * fill. The split is deliberate: `acceptType` is available synchronously so the
+ * caller can validate a region against its slot BEFORE running the (possibly
+ * expensive — Shiki, Playwright) `fill`. A region that is exactly one
+ * `mermaid`/`code`/`image`/`table` node folds to that kind; anything else
+ * aggregates to one TextFill (prose + lists + headings). The paragraph-unwrap
+ * mirrors remark wrapping a lone `![alt](src)` in a paragraph.
+ */
+export function parseSlotContent(text, ctx) {
+    const nodes = parseRegion(text).children.map(unwrapLoneImage);
+    if (nodes.length === 1) {
+        const handler = BLOCKS.find((h) => h.match(nodes[0]));
+        if (handler)
+            return { acceptType: handler.acceptType, fill: () => handler.compile(nodes[0], ctx) };
+    }
+    // TEXT is the aggregate fallback (prose + lists + headings), not a registry
+    // row — it's what a region folds to when no single-block handler claims it.
+    // Wrapped in an async thunk so its fail-fast (a standalone kind mixed into
+    // prose) surfaces from `fill`, after the caller's acceptType check.
+    return { acceptType: AcceptType.Text, fill: async () => compileTextAggregate(nodes, ctx) };
+}
+/** remark wraps a lone `![alt](src)` in a paragraph; unwrap it so a standalone
+ * image is dispatched as an `image` node, not walked as prose. */
+function unwrapLoneImage(node) {
+    if (node.type === MdastType.Paragraph && node.children.length === 1 && node.children[0].type === MdastType.Image) {
+        return node.children[0];
+    }
+    return node;
+}

package/dist/markdown/blocks/table.d.ts

@@ -0,0 +1,2 @@
+import { type BlockHandler } from "../types.js";
+export declare const TABLE: BlockHandler;

package/dist/markdown/blocks/table.js

@@ -0,0 +1,23 @@
+import { walkPhrasingChildren } from "../inline.js";
+import { MdastType } from "../mdast.js";
+import { AcceptType } from "../types.js";
+export const TABLE = {
+    match: (node) => node.type === MdastType.Table,
+    acceptType: AcceptType.Table,
+    compile: async (node) => compileTable(node),
+};
+/** A GFM `table` → TableFill: first row is headers, the rest are body rows; each
+ * cell's phrasing children become `TextRun[]` via the shared inline walk. */
+function compileTable(node) {
+    const [head, ...body] = node.children;
+    return {
+        headers: head ? head.children.map(cellParagraph) : [],
+        rows: body.map((row) => row.children.map(cellParagraph)),
+    };
+}
+/** One table cell → a StyledParagraph. An empty cell keeps a single empty run so
+ * downstream code sees a run to style, matching the old `parseInlineRuns("")`. */
+function cellParagraph(cell) {
+    const runs = walkPhrasingChildren(cell.children, {});
+    return { runs: runs.length > 0 ? runs : [{ text: "" }] };
+}

package/dist/markdown/blocks/text.d.ts

@@ -0,0 +1,12 @@
+import type { RootContent } from "mdast";
+import type { TextFill } from "../../engine/index.js";
+import type { BlockContext } from "../types.js";
+/**
+ * Aggregate a region's prose blocks into one TextFill. Paragraphs, headings, and
+ * lists become `StyledParagraph[]` in document order; list nesting sets bullet
+ * levels. A region reaching here whose only node is an unsupported standalone
+ * block (a lone `blockquote`, `thematicBreak`, …) — or one that mixes a
+ * standalone kind (table/image/code) into prose — is illegal, so fail fast
+ * naming the layout/slide/slot and the node type.
+ */
+export declare function compileTextAggregate(nodes: RootContent[], ctx: BlockContext): TextFill;

package/dist/markdown/blocks/text.js

@@ -0,0 +1,90 @@
+import { walkPhrasingChildren } from "../inline.js";
+import { MdastType } from "../mdast.js";
+/**
+ * Aggregate a region's prose blocks into one TextFill. Paragraphs, headings, and
+ * lists become `StyledParagraph[]` in document order; list nesting sets bullet
+ * levels. A region reaching here whose only node is an unsupported standalone
+ * block (a lone `blockquote`, `thematicBreak`, …) — or one that mixes a
+ * standalone kind (table/image/code) into prose — is illegal, so fail fast
+ * naming the layout/slide/slot and the node type.
+ */
+export function compileTextAggregate(nodes, ctx) {
+    const paragraphs = [];
+    for (const node of nodes) {
+        switch (node.type) {
+            case MdastType.Paragraph:
+            case MdastType.Heading:
+                for (const runs of splitRunsIntoParagraphs(walkPhrasingChildren(node.children, { breakAsNewline: true }))) {
+                    paragraphs.push({ runs });
+                }
+                break;
+            case MdastType.List:
+                paragraphs.push(...listParagraphs(node, 0));
+                break;
+            default:
+                throw new Error(reject(nodes.length, node.type, ctx));
+        }
+    }
+    return { paragraphs };
+}
+/**
+ * Word the rejection for a node that prose aggregation can't take. A region that
+ * is a single unsupported block asks to be a standalone content kind that
+ * doesn't exist; a node reaching here beside others is a standalone kind
+ * (table/image/code) mixed into prose — both name the layout/slide/slot + type.
+ */
+function reject(nodeCount, nodeType, ctx) {
+    const where = `Slide ${ctx.slideIdx}: layout "${ctx.layoutName}" slot content (from ${ctx.source})`;
+    if (nodeCount === 1) {
+        return `${where} is a standalone "${nodeType}" block, which is not a supported content kind.`;
+    }
+    return (`${where} mixes a "${nodeType}" block with other content; ` +
+        "a table, image, or code block must be the region's only content.");
+}
+/**
+ * A `list` → bulleted `StyledParagraph[]`. Each item's paragraph/heading runs
+ * become a bullet at `level` (top-level list = 0); a nested `list` recurses at
+ * `level + 1`. Ordered and unordered both yield plain bullets — the engine has
+ * no ordered flag.
+ */
+function listParagraphs(list, level) {
+    const out = [];
+    for (const item of list.children) {
+        for (const child of item.children) {
+            if (child.type === MdastType.List) {
+                out.push(...listParagraphs(child, level + 1));
+            }
+            else if (child.type === MdastType.Paragraph || child.type === MdastType.Heading) {
+                for (const runs of splitRunsIntoParagraphs(walkPhrasingChildren(child.children, { breakAsNewline: true }))) {
+                    out.push({ runs, bullet: { level } });
+                }
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Split a paragraph's runs on newlines into one `TextRun[]` per source line —
+ * preserving the pre-mdast "one source line = one StyledParagraph" behavior.
+ * Both a soft break (`\n` inside a text run) and a markdown hard break (a
+ * `break` node the inline walk emits as a `"\n"` run in block context) split
+ * here. Empty segments (a style boundary landing on a line edge) are dropped,
+ * and empty lines produce no paragraph, matching the old blank-line filter.
+ */
+function splitRunsIntoParagraphs(runs) {
+    const lines = [];
+    let current = [];
+    for (const run of runs) {
+        const parts = run.text.split("\n");
+        for (let i = 0; i < parts.length; i++) {
+            if (i > 0) {
+                lines.push(current);
+                current = [];
+            }
+            if (parts[i] !== "")
+                current.push({ ...run, text: parts[i] });
+        }
+    }
+    lines.push(current);
+    return lines.filter((line) => line.length > 0);
+}

package/dist/markdown/deckCompiler.d.ts

@@ -1,36 +1,24 @@
-import { FitMode, type ImageFill } from "../engine/index.js";
+import { type ImageFill } from "../engine/index.js";
 import type { ParsedDocument } from "./slideParser.js";
-import { type CompilerDeck, type CompilerImageParameter, type CompilerLayout } from "./types.js";
+import { AssetType, type CompilerConfig, type CompilerDeck } from "./types.js";
 /**
- * Wrap a resolved image path as an ImageFill using the parameter's declared
- * fit. `param` is narrowed to `CompilerImageParameter` — only image parameters
- * carry a raw path. Mermaid slots never reach here (their content flows as
- * fences through MermaidResolver, which wraps the rendered PNG directly).
- *
- * `path` must be absolute. Callers are responsible for resolution (see
- * `resolve(rootDir, ...)` in the compiler / cli.ts).
- */
-export declare function toImageFill(param: CompilerImageParameter, path: string): ImageFill;
-/**
- * Reserved keys in a deck's frontmatter — global (theme, output) and per-slide
- * (layout, body). Exported so callers (e.g. cli.ts) reference the constants
- * instead of literal strings.
+ * Wrap an absolute image path as an ImageFill, expanding the resolved asset
+ * `type` into the engine's scaling constraints. Callers resolve the path (see
+ * `resolveImagePath`) and the type (from the catalog) first.
  */
-export declare const RESERVED_KEY: {
-    readonly LAYOUT: "layout";
-    readonly BODY: "body";
-    readonly OUTPUT: "output";
-    readonly THEME: "theme";
-};
+export declare function toImageFill(path: string, type: AssetType): ImageFill;
 /**
- * Compile a parsed deck document against a set of layouts.
+ * Compile a parsed deck document against a theme `config`. Each slide's content
+ * is compiled straight into engine fills — prose/tables/images plus highlighted
+ * code (Shiki) and rendered mermaid (PNG) — so the returned deck is
+ * engine-shaped, ready for `buildDeck`.
  *
- * `rootDir` (optional) is the base directory for resolving relative image
- * paths declared in the deck's frontmatter or named slots. When omitted (or
- * empty), image paths are returned unchanged — callers that already produce
- * absolute paths (or callers that don't need resolution, e.g. unit tests)
- * can rely on the pass-through. When provided, relative paths are resolved
- * to absolute via `path.resolve(rootDir, path)`; absolute paths pass through.
+ * `config.rootDir` is the base directory for resolving relative image paths
+ * declared in the deck's frontmatter or named slots. When empty, image paths are
+ * returned unchanged — callers that already produce absolute paths (or don't need
+ * resolution, e.g. unit tests) rely on the pass-through. When set, relative paths
+ * are resolved to absolute via `path.resolve(rootDir, path)`; absolute paths pass
+ * through. `config.codeTheme` / `config.mermaid` / `config.mermaidVariant` /
+ * `config.outputDir` feed the code and mermaid compiles.
  */
-export declare function compileDeck(doc: ParsedDocument, layouts: CompilerLayout[], rootDir?: string): CompilerDeck;
-export { FitMode };
+export declare function compileDeck(doc: ParsedDocument, config: CompilerConfig): Promise<CompilerDeck>;

package/dist/markdown/deckCompiler.js

@@ -1,83 +1,41 @@
 import { resolve } from "node:path";
-import { FILLERS, FitMode, SlotType } from "../engine/index.js";
-import { parseGfmTable, parseStyledParagraph } from "./parsers.js";
-import { RESOLVERS } from "./resolvers/resolver.js";
+import { ImageFit, SlotType } from "../engine/index.js";
+import { parseSlotContent } from "./blocks/registry.js";
+import { validateSlideFrontmatter } from "./schema/deckSchema.js";
 import { templateKeys, templateToSegments } from "./textTemplate.js";
-import { CompilerSlotType, FenceType, ParameterType, } from "./types.js";
-/**
- * Wrap a resolved image path as an ImageFill using the parameter's declared
- * fit. `param` is narrowed to `CompilerImageParameter` — only image parameters
- * carry a raw path. Mermaid slots never reach here (their content flows as
- * fences through MermaidResolver, which wraps the rendered PNG directly).
- *
- * `path` must be absolute. Callers are responsible for resolution (see
- * `resolve(rootDir, ...)` in the compiler / cli.ts).
- */
-export function toImageFill(param, path) {
-    return { type: SlotType.Image, path, fit: param.fit };
-}
-/**
- * Reserved keys in a deck's frontmatter — global (theme, output) and per-slide
- * (layout, body). Exported so callers (e.g. cli.ts) reference the constants
- * instead of literal strings.
- */
-export const RESERVED_KEY = {
-    LAYOUT: "layout",
-    BODY: "body",
-    OUTPUT: "output",
-    THEME: "theme",
+import { AssetType, ParameterType, RESERVED_KEY, } from "./types.js";
+/** Map each semantic asset type to the engine's object-fit directive. */
+const FIT_FOR = {
+    [AssetType.Icon]: ImageFit.ScaleDown,
+    [AssetType.Image]: ImageFit.Contain,
+    [AssetType.Background]: ImageFit.Cover,
 };
-const CODE_FENCE_RE = /^```(\w+)\n([\s\S]*?)```\s*$/;
-function toTextFill(text) {
-    const paragraphs = text
-        .split(/\r?\n/)
-        .filter((line) => line.trim() !== "")
-        .map(parseStyledParagraph);
-    return { paragraphs };
-}
-function parseSlotContent(text) {
-    const fence = CODE_FENCE_RE.exec(text.trim());
-    if (fence) {
-        if (fence[1] === FenceType.Mermaid) {
-            const block = { type: FenceType.Mermaid, definition: fence[2].replace(/\n$/, "") };
-            return block;
-        }
-        const block = { type: FenceType.Code, language: fence[1], source: fence[2].replace(/\n$/, "") };
-        return block;
-    }
-    const table = parseGfmTable(text);
-    if (table)
-        return table;
-    return toTextFill(text);
-}
 /**
- * Matcher for each CompilerSlotType, composed from the engine's `FILLERS` (text,
- * table) and the compiler's `RESOLVERS` (code, mermaid) — no raw guards imported
- * here, so a slot's expected shape always tracks whatever those registries say a
- * fill/fence looks like.
+ * Wrap an absolute image path as an ImageFill, expanding the resolved asset
+ * `type` into the engine's scaling constraints. Callers resolve the path (see
+ * `resolveImagePath`) and the type (from the catalog) first.
  */
-const REGION_MATCHERS = {
-    [CompilerSlotType.Text]: FILLERS[SlotType.Text].matches,
-    [CompilerSlotType.Table]: FILLERS[SlotType.Table].matches,
-    [CompilerSlotType.Code]: RESOLVERS[FenceType.Code].matches,
-    [CompilerSlotType.Mermaid]: RESOLVERS[FenceType.Mermaid].matches,
-};
+export function toImageFill(path, type) {
+    return { type: SlotType.Image, path, fit: FIT_FOR[type] };
+}
+const KNOWN_GLOBAL_KEYS = new Set([RESERVED_KEY.THEME, RESERVED_KEY.OUTPUT]);
+// Anchored whole-field reference: the entire value is `$category.name` or it is
+// not a reference at all. Anchored ⇒ no escaping concerns.
+const ASSET_REF_RE = /^\$([a-zA-Z]\w*)\.([a-zA-Z]\w*)$/;
 /**
- * Assert that a region's parsed block matches the slot's declared type. Called
- * after `parseSlotContent` narrows a body/`::name::` region into a MarkdownBlock.
- * Keys off the CompilerSlotType discriminator via `REGION_MATCHERS`.
+ * Assert that a region's parsed block folds to a type the slot `accepts`. The
+ * folded type comes straight from `parseSlotContent` (which returns it beside
+ * the block — no re-probe). A slot may accept several types (text/table/image);
+ * the author's markdown shape selects one. A type the slot does not accept fails
+ * fast, naming the layout, slot, the type it got, and the types the slot accepts.
  */
-function assertSlotRegion(slot, block, slideIdx, source) {
-    if (!REGION_MATCHERS[slot.type](block)) {
-        throw new Error(`Slide ${slideIdx}: slot "${slot.key}" (type "${slot.type}") got wrong content shape from ${source}.`);
+function assertSlotRegion(slot, got, layoutName, slideIdx, source) {
+    if (!slot.accepts.some((b) => b.type === got)) {
+        const accepted = slot.accepts.map((b) => b.type).join(", ");
+        throw new Error(`Slide ${slideIdx}: layout "${layoutName}" slot "${slot.key}" does not accept ${got} content ` +
+            `(from ${source}); it accepts: ${accepted}.`);
     }
 }
-function isImageParameter(param) {
-    return param.type === ParameterType.Image;
-}
-function isTemplateParameter(param) {
-    return param.type === ParameterType.Template;
-}
 /**
  * Resolve a user-supplied image path against the deck's root directory.
  * When `rootDir` is empty, the path is returned unchanged so callers that
@@ -89,6 +47,26 @@ function resolveImagePath(rootDir, path) {
         return path;
     return resolve(rootDir, path);
 }
+/**
+ * Assert no two layouts sample the same base slide. In the sampled-composition
+ * model one layout is one sampled base slide's region-arrangement, so a shared
+ * `slideNumber` means the old single-content-type welding leaked through — two
+ * layouts on one physical slide that should be one multi-`accepts` layout.
+ * `sourceSlide` inside a slot's `accepts` block is a distinct concept (a
+ * specimen source for one content type) and is legitimately reused across
+ * layouts, so it is deliberately not checked here.
+ */
+function assertUniqueSlideNumbers(layouts) {
+    const layoutNameBySlideNumber = new Map();
+    for (const layout of layouts) {
+        const existing = layoutNameBySlideNumber.get(layout.slideNumber);
+        if (existing !== undefined) {
+            throw new Error(`Layouts "${existing}" and "${layout.name}" share slideNumber ${layout.slideNumber}; ` +
+                "each layout must sample a distinct base slide (one layout = one slide, with slots that accept multiple content types).");
+        }
+        layoutNameBySlideNumber.set(layout.slideNumber, layout.name);
+    }
+}
 /**
  * Validate a layout's key spaces once, independent of any slide, so every later
  * frontmatter lookup and content-map write is unambiguous. Two spaces must each
@@ -122,50 +100,67 @@ function validateLayout(layout) {
         contentKeys.add(key);
     };
     for (const param of layout.parameters) {
-        if (isImageParameter(param)) {
-            claimAuthorKey(param.key, "image parameter");
-            claimContentKey(param.key, "image parameter");
-        }
-        else {
-            const keys = templateKeys(param.template);
-            if (param.required && keys.length === 0) {
-                throw new Error(`Layout "${layout.name}": template parameter "${param.shapeName}" is marked required but its template has no keys to fill.`);
+        switch (param.type) {
+            case ParameterType.Image:
+                claimAuthorKey(param.key, "image parameter");
+                claimContentKey(param.key, "image parameter");
+                break;
+            case ParameterType.Template: {
+                const keys = templateKeys(param.template);
+                if (param.required && keys.length === 0) {
+                    throw new Error(`Layout "${layout.name}": template parameter "${param.shapeName}" is marked required but its template has no keys to fill.`);
+                }
+                for (const key of keys)
+                    claimAuthorKey(key, `template parameter "${param.shapeName}"`);
+                claimContentKey(param.shapeName, "template parameter");
+                break;
             }
-            for (const key of keys)
-                claimAuthorKey(key, `template parameter "${param.shapeName}"`);
-            claimContentKey(param.shapeName, "template parameter");
         }
     }
     for (const slot of layout.slots) {
         claimContentKey(slot.key, "slot");
     }
 }
-function compileStep(slide, layouts, rootDir) {
+async function compileStep(slide, config, assetTypeByPath, resolveAssetRef) {
+    const { layouts, rootDir } = config;
     const { frontmatter, body, slots, index } = slide;
     const layout = frontmatter[RESERVED_KEY.LAYOUT];
     if (layout === undefined) {
         throw new Error(`Slide ${index}: missing required "${RESERVED_KEY.LAYOUT}" in frontmatter`);
     }
+    // Speaker notes are slide-level metadata, stripped from frontmatter before
+    // slot/param resolution — exactly like `layout`. Coerce to string if present.
+    // An empty `notes:` key parses as YAML null; treat it as absent (loose `==`)
+    // so it doesn't write the literal string "null".
+    const notesRaw = frontmatter[RESERVED_KEY.NOTES];
+    const notes = notesRaw == null ? undefined : String(notesRaw);
     const layoutName = String(layout);
     const layoutDef = layouts.find((l) => l.name === layoutName);
     if (!layoutDef) {
         const known = layouts.map((l) => l.name).join(", ");
         throw new Error(`Slide ${index}: unknown layout "${layoutName}". Available layouts: ${known}`);
     }
+    // Reject any frontmatter key not declared by this layout's parameters (reserved
+    // layout/notes stripped first). The per-layout strict schema IS the unknown-key
+    // check — it fires before the resolution loop, so that loop only sees valid keys.
+    validateSlideFrontmatter(frontmatter, layoutDef, index);
     // Map each author-facing key to its owning parameter: template keys → the template
     // parameter that declares them, image keys → the image parameter. validateLayout
     // (run once per layout in compileDeck) has already proven these key spaces are
     // collision-free, so a later lookup is unambiguous.
-    const templateParams = layoutDef.parameters.filter(isTemplateParameter);
+    const templateParams = [];
     const imageByKey = new Map();
     const templateParamByKey = new Map();
     for (const param of layoutDef.parameters) {
-        if (isImageParameter(param)) {
-            imageByKey.set(param.key, param);
-        }
-        else {
-            for (const key of templateKeys(param.template))
-                templateParamByKey.set(key, param);
+        switch (param.type) {
+            case ParameterType.Image:
+                imageByKey.set(param.key, param);
+                break;
+            case ParameterType.Template:
+                templateParams.push(param);
+                for (const key of templateKeys(param.template))
+                    templateParamByKey.set(key, param);
+                break;
         }
     }
     const slotsByKey = new Map(layoutDef.slots.map((s) => [s.key, s]));
@@ -174,11 +169,17 @@ function compileStep(slide, layouts, rootDir) {
     // (gathered per parameter, expanded together once every line is read).
     const valuesByTemplateParam = new Map();
     for (const [key, value] of Object.entries(frontmatter)) {
-        if (key === RESERVED_KEY.LAYOUT)
+        if (key === RESERVED_KEY.LAYOUT || key === RESERVED_KEY.NOTES)
             continue;
         const image = imageByKey.get(key);
         if (image) {
-            content[image.key] = toImageFill(image, resolveImagePath(rootDir, String(value)));
+            const imgPath = resolveImagePath(rootDir, String(value));
+            const assetType = assetTypeByPath.get(imgPath);
+            if (assetType === undefined) {
+                throw new Error(`Slide image "${image.key}": "${value}" has no asset-catalog entry, so no type. ` +
+                    `Add it to the theme's assets with a type (icon | image | background).`);
+            }
+            content[image.key] = toImageFill(imgPath, assetType);
             continue;
         }
         const templateParam = templateParamByKey.get(key);
@@ -189,10 +190,9 @@ function compileStep(slide, layouts, rootDir) {
                 valuesByTemplateParam.set(templateParam, bucket);
             }
             bucket.set(key, String(value));
-            continue;
         }
-        const validKeys = [...templateParamByKey.keys(), ...imageByKey.keys()].join(", ");
-        throw new Error(`Slide ${index}: unknown key "${key}" in layout "${layoutName}". Valid parameters: ${validKeys}`);
+        // Unreachable: validateSlideFrontmatter (above) already rejected any key that is
+        // neither an image key nor a template key, so every key here routes to a parameter.
     }
     // Expand each template parameter whose keys were supplied. Filling any key fills the
     // parameter as a whole — a missing key throws (fail-fast in templateToSegments). A
@@ -217,9 +217,18 @@ function compileStep(slide, layouts, rootDir) {
         if (!bodySlot) {
             throw new Error(`Slide ${index}: layout "${layoutName}" does not accept body content. Valid slots: ${[...slotsByKey.keys()].join(", ")}`);
         }
-        const parsedBody = parseSlotContent(body);
-        assertSlotRegion(bodySlot, parsedBody, index, "body content");
-        content[RESERVED_KEY.BODY] = parsedBody;
+        const parsedBody = parseSlotContent(body, {
+            resolveAssetRef,
+            layoutName,
+            slideIdx: index,
+            source: "body content",
+            config,
+        });
+        // Validate the slot accepts this region's type BEFORE running the (possibly
+        // expensive — Shiki, Playwright) fill: a mismatched region fails fast without
+        // spinning up a renderer.
+        assertSlotRegion(bodySlot, parsedBody.acceptType, layoutName, index, "body content");
+        content[RESERVED_KEY.BODY] = await parsedBody.fill();
     }
     // `::name::` regions resolve against the layout's slots.
     for (const [name, text] of Object.entries(slots)) {
@@ -228,9 +237,10 @@ function compileStep(slide, layouts, rootDir) {
             throw new Error(`Slide ${index}: unknown slot "::${name}::" in layout "${layoutName}". ` +
                 `Valid slots: ${[...slotsByKey.keys()].join(", ")}`);
         }
-        const block = parseSlotContent(text);
-        assertSlotRegion(slot, block, index, `::${name}::`);
-        content[name] = block;
+        const source = `::${name}::`;
+        const parsed = parseSlotContent(text, { resolveAssetRef, layoutName, slideIdx: index, source, config });
+        assertSlotRegion(slot, parsed.acceptType, layoutName, index, source);
+        content[name] = await parsed.fill();
     }
     // Required image parameters (missing frontmatter key) and required slots
     // (missing region) throw with layout + key context. Required template parameters are
@@ -245,23 +255,29 @@ function compileStep(slide, layouts, rootDir) {
             throw new Error(`Slide ${index}: layout "${layoutName}" requires slot "${slot.key}"; none provided`);
         }
     }
-    // CompilerDeckStep.content values are MarkdownBlock — CodeFence and
-    // MermaidFence are legal in transit until the resolvers narrow them into
-    // StyledParagraph[] / ImageFill before the engine sees the deck.
-    return { layout: layoutName, content };
+    // Content values are already engine fills — code fences highlighted to TextFill
+    // and mermaid fences rendered to ImageFill by their handler's `compile`.
+    const step = { layout: layoutName, content };
+    if (notes !== undefined)
+        step.notes = notes;
+    return step;
 }
-const KNOWN_GLOBAL_KEYS = new Set([RESERVED_KEY.THEME, RESERVED_KEY.OUTPUT]);
 /**
- * Compile a parsed deck document against a set of layouts.
+ * Compile a parsed deck document against a theme `config`. Each slide's content
+ * is compiled straight into engine fills — prose/tables/images plus highlighted
+ * code (Shiki) and rendered mermaid (PNG) — so the returned deck is
+ * engine-shaped, ready for `buildDeck`.
  *
- * `rootDir` (optional) is the base directory for resolving relative image
- * paths declared in the deck's frontmatter or named slots. When omitted (or
- * empty), image paths are returned unchanged — callers that already produce
- * absolute paths (or callers that don't need resolution, e.g. unit tests)
- * can rely on the pass-through. When provided, relative paths are resolved
- * to absolute via `path.resolve(rootDir, path)`; absolute paths pass through.
+ * `config.rootDir` is the base directory for resolving relative image paths
+ * declared in the deck's frontmatter or named slots. When empty, image paths are
+ * returned unchanged — callers that already produce absolute paths (or don't need
+ * resolution, e.g. unit tests) rely on the pass-through. When set, relative paths
+ * are resolved to absolute via `path.resolve(rootDir, path)`; absolute paths pass
+ * through. `config.codeTheme` / `config.mermaid` / `config.mermaidVariant` /
+ * `config.outputDir` feed the code and mermaid compiles.
  */
-export function compileDeck(doc, layouts, rootDir = "") {
+export async function compileDeck(doc, config) {
+    const { layouts, rootDir, assets } = config;
     const theme = doc.global[RESERVED_KEY.THEME];
     if (theme === undefined) {
         throw new Error(`Missing required "${RESERVED_KEY.THEME}" in global frontmatter`);
@@ -270,20 +286,49 @@ export function compileDeck(doc, layouts, rootDir = "") {
     if (unknownGlobal.length > 0) {
         throw new Error(`Unknown key(s) in global frontmatter: ${unknownGlobal.join(", ")}. Valid keys: ${[...KNOWN_GLOBAL_KEYS].join(", ")}`);
     }
-    // Validate every layout's key spaces up front (once per layout), so a broken
-    // theme fails fast regardless of which layouts this deck's slides use.
+    // Validate the layout list as a whole (one pass), then each layout's key
+    // spaces up front (once per layout), so a broken theme fails fast regardless
+    // of which layouts this deck's slides use.
+    assertUniqueSlideNumbers(layouts);
     for (const layout of layouts)
         validateLayout(layout);
-    const deck = {
-        theme: String(theme),
-        steps: doc.slides.map((slide) => compileStep(slide, layouts, rootDir)),
+    // Index each catalog asset's resolved path → its declared type, so an image
+    // filled by path inherits the scaling tolerance intrinsic to its pixels.
+    const assetTypeByPath = new Map();
+    for (const group of Object.values(assets)) {
+        for (const entry of Object.values(group)) {
+            assetTypeByPath.set(resolveImagePath(rootDir, entry.path), entry.type);
+        }
+    }
+    // Resolve a body/`::name::` `$category.name` reference against the theme's
+    // curated asset catalog. Anchored ⇒ the whole ref is the reference or it is
+    // nothing; a found entry wraps through the same path→ImageFit mapping as a
+    // frontmatter image (`toImageFill`), so a body image has no second fit story.
+    const resolveAssetRef = (ref) => {
+        const match = ASSET_REF_RE.exec(ref);
+        if (!match) {
+            throw new Error(`Asset reference "${ref}" must be in the form $category.name (e.g. $logos.primary).`);
+        }
+        const [, category, name] = match;
+        const entry = assets[category]?.[name];
+        if (!entry) {
+            const available = Object.entries(assets)
+                .flatMap(([cat, group]) => Object.keys(group).map((n) => `$${cat}.${n}`))
+                .join(", ");
+            throw new Error(`Unknown asset reference "${ref}". Available: ${available}`);
+        }
+        return toImageFill(resolveImagePath(rootDir, entry.path), entry.type);
     };
+    // Slides compile in order: a slide's structural errors (unknown layout/key,
+    // bad asset ref, accept-type mismatch) fire before its own content is rendered.
+    const steps = [];
+    for (const slide of doc.slides) {
+        steps.push(await compileStep(slide, config, assetTypeByPath, resolveAssetRef));
+    }
+    const deck = { theme: String(theme), steps };
     const output = doc.global[RESERVED_KEY.OUTPUT];
     if (output !== undefined) {
         deck.output = String(output);
     }
     return deck;
 }
-// Re-export FitMode so callers that build ImageFills by hand can import it
-// through the compiler surface without reaching into the engine.
-export { FitMode };