@tycoworks/tycoslide 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { type Config, type ThemeConfig } from "./engine/index.js";
+import { type CompilerConfig, type CompilerDeck, type CompilerThemeConfig, type ResolvedCompilerDeck } from "./markdown/types.js";
+/**
+ * Run every compiler-owned resolver over `deck` (highlight code fences,
+ * render mermaid PNGs) and return a `ResolvedCompilerDeck` whose content
+ * values are narrowed to the engine's `TextFill | TableFill | ImageFill |
+ * TemplateFill` union. Structurally equivalent to the engine's `Deck` — a
+ * caller passes the returned value straight to `generate()` with no cast.
+ *
+ * Fails fast if `deck.output` is missing: downstream `generate()` requires it,
+ * and the CLI populates it before calling `buildDeck`; a programmatic caller
+ * that forgot to set it hits the error here instead of a confusing engine-side
+ * failure.
+ */
+export declare function resolveDeck(deck: CompilerDeck, config: CompilerConfig): Promise<ResolvedCompilerDeck>;
+/**
+ * Project a CompilerThemeConfig down to the engine's ThemeConfig shape.
+ * Fields are copied cell-by-cell so the boundary is explicit — no casts.
+ * The compiler's `assets` catalog is intentionally NOT forwarded: the engine
+ * is ignorant of theme-level asset metadata; the compiler resolves any asset
+ * reference to a filesystem path and wraps it as an ImageFill in
+ * `step.content` before this projection runs.
+ */
+export declare function toEngineThemeConfig(config: CompilerThemeConfig): ThemeConfig;
+/**
+ * Project a CompilerConfig down to the engine's Config shape. Explicit
+ * projection at the boundary where compiler-only fields stop mattering.
+ */
+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`.
+ *
+ * Mermaid PNGs are cached under `<outputDir>/.tycoslide-cache/mermaid/` so no
+ * post-write cleanup is needed.
+ */
+export declare function buildDeck(deck: CompilerDeck, config: CompilerConfig): Promise<void>;
+export type { Config, Deck, DeckStep, ImageFill, Layout, Slot, StyledParagraph, TableFill, TextFill, TextRun, ThemeConfig, } from "./engine/index.js";
+export { FitMode, fillImage, fillTable, fillTemplate, fillText, generate, SlotType } from "./engine/index.js";
+export 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";

package/dist/index.js

@@ -0,0 +1,146 @@
+import { generate, SlotType, } from "./engine/index.js";
+import { isFence, resolveFences } from "./markdown/resolvers/resolver.js";
+import { CompilerSlotType, 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.
+ */
+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;
+    }
+    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.
+ */
+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);
+            return resolvedStep;
+        }),
+    };
+}
+/**
+ * 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.
+ */
+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;
+        }
+        case CompilerSlotType.Table: {
+            const result = { key: slot.key, shapeName: slot.shapeName, type: SlotType.Table };
+            if (slot.columns !== undefined)
+                result.columns = slot.columns;
+            return result;
+        }
+        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) {
+    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)],
+    };
+}
+/**
+ * Project a CompilerThemeConfig down to the engine's ThemeConfig shape.
+ * Fields are copied cell-by-cell so the boundary is explicit — no casts.
+ * The compiler's `assets` catalog is intentionally NOT forwarded: the engine
+ * is ignorant of theme-level asset metadata; the compiler resolves any asset
+ * reference to a filesystem path and wraps it as an ImageFill in
+ * `step.content` before this projection runs.
+ */
+export function toEngineThemeConfig(config) {
+    const result = {
+        layouts: config.layouts.map(toEngineLayout),
+        template: config.template,
+    };
+    if (config.outputDir !== undefined)
+        result.outputDir = config.outputDir;
+    return result;
+}
+/**
+ * Project a CompilerConfig down to the engine's Config shape. Explicit
+ * projection at the boundary where compiler-only fields stop mattering.
+ */
+export function toEngineConfig(config) {
+    return {
+        ...toEngineThemeConfig(config),
+        rootDir: config.rootDir,
+    };
+}
+/**
+ * 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`.
+ *
+ * Mermaid PNGs are cached under `<outputDir>/.tycoslide-cache/mermaid/` so no
+ * post-write cleanup is needed.
+ */
+export async function buildDeck(deck, config) {
+    const resolved = await resolveDeck(deck, config);
+    await generate(resolved, toEngineConfig(config));
+}
+// Engine — primitives-only public surface.
+export { FitMode, 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";

package/dist/manifest.d.ts

@@ -0,0 +1,7 @@
+import type { CompilerConfig } from "./markdown/types.js";
+export type ManifestOptions = {
+    build: {
+        command: string;
+    };
+};
+export declare function generateManifest(config: CompilerConfig, options: ManifestOptions): string;

package/dist/manifest.js

@@ -0,0 +1,88 @@
+import { templateKeys } from "./markdown/textTemplate.js";
+import { CompilerSlotType, ParameterType } from "./markdown/types.js";
+/**
+ * Flatten a compiler parameter to the manifest entries advertised to AI authors.
+ * A template parameter has no top-level key — its template's keys are the keys, so it
+ * flattens to one entry per key (shapeName/template stay manifest-internal). An
+ * image parameter is a single key.
+ *
+ * A template parameter's `limit` is deliberately NOT projected here: it measures the
+ * expanded run text (parameter-level), so surfacing it per key would misrepresent
+ * it as per-key. How to advertise a parameter-level limit is a Phase 2 decision;
+ * until then it stays manifest-internal.
+ */
+function stripParameter(param) {
+    switch (param.type) {
+        case ParameterType.Template:
+            return templateKeys(param.template).map((key) => {
+                const result = { key, type: param.type };
+                if (param.required)
+                    result.required = true;
+                return result;
+            });
+        case ParameterType.Image: {
+            const result = { key: param.key, type: param.type, fit: param.fit };
+            if (param.required)
+                result.required = true;
+            if (param.limit)
+                result.limit = param.limit;
+            return [result];
+        }
+    }
+}
+function stripSlot(slot) {
+    const result = { key: slot.key, type: slot.type };
+    if (slot.required)
+        result.required = true;
+    if (slot.limit)
+        result.limit = slot.limit;
+    switch (slot.type) {
+        case CompilerSlotType.Text:
+            // startAt is a fill hint, not a manifest surface concern.
+            break;
+        case CompilerSlotType.Table:
+            if (slot.columns !== undefined)
+                result.columns = slot.columns;
+            break;
+        case CompilerSlotType.Code:
+            result.codeTheme = slot.codeTheme;
+            break;
+        case CompilerSlotType.Mermaid:
+            result.mermaidVariant = slot.mermaidVariant;
+            break;
+    }
+    return result;
+}
+export function generateManifest(config, options) {
+    const layouts = config.layouts.map((layout) => ({
+        name: layout.name,
+        slideNumber: layout.slideNumber,
+        description: layout.description,
+        whenToUse: layout.whenToUse,
+        whenNotToUse: layout.whenNotToUse,
+        parameters: layout.parameters.flatMap(stripParameter),
+        slots: layout.slots.map(stripSlot),
+    }));
+    const assets = {};
+    for (const [category, entries] of Object.entries(config.assets)) {
+        assets[category] = {};
+        for (const [name, entry] of Object.entries(entries)) {
+            const manifestEntry = {
+                path: entry.path,
+                description: entry.description,
+            };
+            if (entry.whenToUse)
+                manifestEntry.whenToUse = entry.whenToUse;
+            assets[category][name] = manifestEntry;
+        }
+    }
+    const manifest = {
+        version: 1,
+        layouts,
+        assets,
+        build: {
+            command: options.build.command,
+        },
+    };
+    return JSON.stringify(manifest, null, 2);
+}

package/dist/markdown/deckCompiler.d.ts

@@ -0,0 +1,36 @@
+import { FitMode, type ImageFill } from "../engine/index.js";
+import type { ParsedDocument } from "./slideParser.js";
+import { type CompilerDeck, type CompilerImageParameter, type CompilerLayout } 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.
+ */
+export declare const RESERVED_KEY: {
+    readonly LAYOUT: "layout";
+    readonly BODY: "body";
+    readonly OUTPUT: "output";
+    readonly THEME: "theme";
+};
+/**
+ * Compile a parsed deck document against a set of layouts.
+ *
+ * `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.
+ */
+export declare function compileDeck(doc: ParsedDocument, layouts: CompilerLayout[], rootDir?: string): CompilerDeck;
+export { FitMode };

package/dist/markdown/deckCompiler.js

@@ -0,0 +1,289 @@
+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 { 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",
+};
+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.
+ */
+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,
+};
+/**
+ * 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`.
+ */
+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 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
+ * already produce absolute paths (or callers that don't care about
+ * resolution) can opt out. Absolute paths always pass through.
+ */
+function resolveImagePath(rootDir, path) {
+    if (!rootDir || path.startsWith("/"))
+        return path;
+    return resolve(rootDir, path);
+}
+/**
+ * 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
+ * be collision-free — otherwise a fill silently clobbers or throws a misleading
+ * error:
+ *
+ * - **Author keys** — what a frontmatter line addresses: every template-parameter key
+ *   and every image-parameter key must be distinct, so a line routes to exactly
+ *   one parameter.
+ * - **Content keys** — what `step.content` is addressed by: every image key, every
+ *   template parameter's `shapeName`, and every slot key must be distinct, so no two
+ *   overwrite each other in the content map.
+ *
+ * Also rejects a required template parameter whose template has no keys — it declares
+ * no way to be filled, so `required` on it is unsatisfiable.
+ */
+function validateLayout(layout) {
+    const authorKeys = new Set();
+    const contentKeys = new Set();
+    const claimAuthorKey = (key, owner) => {
+        if (authorKeys.has(key)) {
+            throw new Error(`Layout "${layout.name}": key "${key}" (${owner}) is declared twice; a frontmatter key fills exactly one parameter.`);
+        }
+        authorKeys.add(key);
+    };
+    const claimContentKey = (key, owner) => {
+        if (contentKeys.has(key)) {
+            throw new Error(`Layout "${layout.name}": name "${key}" (${owner}) collides with another parameter or slot; ` +
+                "each template parameter's shape, image key, and slot key must be distinct.");
+        }
+        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.`);
+            }
+            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) {
+    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`);
+    }
+    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}`);
+    }
+    // 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 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);
+        }
+    }
+    const slotsByKey = new Map(layoutDef.slots.map((s) => [s.key, s]));
+    const content = {};
+    // Frontmatter lines fill image parameters (by key) or template-parameter keys
+    // (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)
+            continue;
+        const image = imageByKey.get(key);
+        if (image) {
+            content[image.key] = toImageFill(image, resolveImagePath(rootDir, String(value)));
+            continue;
+        }
+        const templateParam = templateParamByKey.get(key);
+        if (templateParam) {
+            let bucket = valuesByTemplateParam.get(templateParam);
+            if (!bucket) {
+                bucket = new Map();
+                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}`);
+    }
+    // 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
+    // parameter with no supplied keys stays designer-sample unless required. Content
+    // is keyed by shapeName: one parameter → one entry, regardless of key count.
+    for (const templateParam of templateParams) {
+        const supplied = valuesByTemplateParam.get(templateParam);
+        if (!supplied) {
+            if (templateParam.required) {
+                throw new Error(`Slide ${index}: layout "${layoutName}" requires template parameter "${templateParam.shapeName}" ` +
+                    `(keys: ${templateKeys(templateParam.template).join(", ")}); none provided`);
+            }
+            continue;
+        }
+        content[templateParam.shapeName] = {
+            lines: templateToSegments(templateParam.template, supplied, templateParam.shapeName),
+        };
+    }
+    // The default body region resolves against the layout's body slot.
+    if (body.trim()) {
+        const bodySlot = slotsByKey.get(RESERVED_KEY.BODY);
+        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;
+    }
+    // `::name::` regions resolve against the layout's slots.
+    for (const [name, text] of Object.entries(slots)) {
+        const slot = slotsByKey.get(name);
+        if (!slot) {
+            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;
+    }
+    // Required image parameters (missing frontmatter key) and required slots
+    // (missing region) throw with layout + key context. Required template parameters are
+    // enforced during expansion above.
+    for (const image of imageByKey.values()) {
+        if (image.required && content[image.key] === undefined) {
+            throw new Error(`Slide ${index}: layout "${layoutName}" requires parameter "${image.key}"; none provided`);
+        }
+    }
+    for (const slot of layoutDef.slots) {
+        if (slot.required && content[slot.key] === undefined) {
+            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 };
+}
+const KNOWN_GLOBAL_KEYS = new Set([RESERVED_KEY.THEME, RESERVED_KEY.OUTPUT]);
+/**
+ * Compile a parsed deck document against a set of layouts.
+ *
+ * `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.
+ */
+export function compileDeck(doc, layouts, rootDir = "") {
+    const theme = doc.global[RESERVED_KEY.THEME];
+    if (theme === undefined) {
+        throw new Error(`Missing required "${RESERVED_KEY.THEME}" in global frontmatter`);
+    }
+    const unknownGlobal = Object.keys(doc.global).filter((k) => !KNOWN_GLOBAL_KEYS.has(k));
+    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.
+    for (const layout of layouts)
+        validateLayout(layout);
+    const deck = {
+        theme: String(theme),
+        steps: doc.slides.map((slide) => compileStep(slide, layouts, rootDir)),
+    };
+    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 };

package/dist/markdown/index.d.ts

@@ -0,0 +1,13 @@
+import type { CompilerDeck, CompilerLayout } from "./types.js";
+export declare function compileMarkdownDeck(source: string, layouts: CompilerLayout[], rootDir?: string): CompilerDeck;
+export { compileDeck, RESERVED_KEY } from "./deckCompiler.js";
+export { parseGfmTable, parseInlineRuns, parseProseLine, parseStyledParagraph } from "./parsers.js";
+export { CodeResolver, highlightCode, isCodeBlock } from "./resolvers/code.js";
+export { isMermaidBlock, MermaidResolver } from "./resolvers/mermaid.js";
+export type { MermaidConfig, MermaidVariant } from "./resolvers/mermaidTheme.js";
+export type { ResolveContext, Resolver } from "./resolvers/resolver.js";
+export { isFence, RESOLVERS, resolveFences } from "./resolvers/resolver.js";
+export type { ParsedDocument, RawSlide } from "./slideParser.js";
+export { parseSlideDocument } from "./slideParser.js";
+export type { AssetCatalog, AssetEntry, CodeFence, CompilerCodeSlot, CompilerConfig, CompilerDeck, CompilerDeckStep, CompilerImageParameter, CompilerLayout, CompilerMermaidSlot, CompilerParameter, CompilerSlot, CompilerTableSlot, CompilerTemplateParameter, CompilerTextSlot, CompilerThemeConfig, MarkdownBlock, MermaidFence, ResolvedCompilerDeck, ResolvedCompilerDeckStep, } from "./types.js";
+export { CompilerSlotType, FenceType, ParameterType } from "./types.js";

package/dist/markdown/index.js

@@ -0,0 +1,13 @@
+import { compileDeck } from "./deckCompiler.js";
+import { parseSlideDocument } from "./slideParser.js";
+export function compileMarkdownDeck(source, layouts, rootDir = "") {
+    const doc = parseSlideDocument(source);
+    return compileDeck(doc, layouts, rootDir);
+}
+export { compileDeck, RESERVED_KEY } from "./deckCompiler.js";
+export { parseGfmTable, parseInlineRuns, parseProseLine, parseStyledParagraph } from "./parsers.js";
+export { CodeResolver, highlightCode, isCodeBlock } from "./resolvers/code.js";
+export { isMermaidBlock, MermaidResolver } from "./resolvers/mermaid.js";
+export { isFence, RESOLVERS, resolveFences } from "./resolvers/resolver.js";
+export { parseSlideDocument } from "./slideParser.js";
+export { CompilerSlotType, FenceType, ParameterType } from "./types.js";