@tycoworks/tycoslide 0.7.0 → 0.8.0

package/dist/index.js

@@ -42,6 +42,8 @@ export async function resolveDeck(deck, config) {
             const resolvedStep = { layout: step.layout };
             if (step.content)
                 resolvedStep.content = narrowContent(step.content);
+            if (step.notes !== undefined)
+                resolvedStep.notes = step.notes;
             return resolvedStep;
         }),
     };
@@ -72,12 +74,8 @@ function toEngineSlot(slot) {
                 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.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.
@@ -135,12 +133,12 @@ export function toEngineConfig(config) {
  * Mermaid PNGs are cached under `<outputDir>/.tycoslide-cache/mermaid/` so no
  * post-write cleanup is needed.
  */
-export async function buildDeck(deck, config) {
+export async function buildDeck(deck, config, options = {}) {
     const resolved = await resolveDeck(deck, config);
-    await generate(resolved, toEngineConfig(config));
+    await generate(resolved, toEngineConfig(config), options);
 }
 // Engine — primitives-only public surface.
-export { FitMode, fillImage, fillTable, fillTemplate, fillText, generate, SlotType } from "./engine/index.js";
+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";

package/dist/manifest.js

@@ -21,7 +21,7 @@ function stripParameter(param) {
                 return result;
             });
         case ParameterType.Image: {
-            const result = { key: param.key, type: param.type, fit: param.fit };
+            const result = { key: param.key, type: param.type };
             if (param.required)
                 result.required = true;
             if (param.limit)
@@ -38,11 +38,8 @@ function stripSlot(slot) {
         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;
+            // No fields beyond the shared key/type/required/limit.
             break;
         case CompilerSlotType.Code:
             result.codeTheme = slot.codeTheme;
@@ -69,6 +66,7 @@ export function generateManifest(config, options) {
         for (const [name, entry] of Object.entries(entries)) {
             const manifestEntry = {
                 path: entry.path,
+                type: entry.type,
                 description: entry.description,
             };
             if (entry.whenToUse)

package/dist/markdown/deckCompiler.d.ts

@@ -1,16 +1,7 @@
-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";
-/**
- * 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;
+import { type AssetCatalog, AssetType, type CompilerDeck, type CompilerLayout } from "./types.js";
+export declare function toImageFill(path: string, type: AssetType): 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
@@ -21,6 +12,7 @@ export declare const RESERVED_KEY: {
     readonly BODY: "body";
     readonly OUTPUT: "output";
     readonly THEME: "theme";
+    readonly NOTES: "notes";
 };
 /**
  * Compile a parsed deck document against a set of layouts.
@@ -32,5 +24,4 @@ export declare const RESERVED_KEY: {
  * 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 };
+export declare function compileDeck(doc: ParsedDocument, layouts: CompilerLayout[], rootDir?: string, assets?: AssetCatalog): CompilerDeck;

package/dist/markdown/deckCompiler.js

@@ -1,20 +1,22 @@
 import { resolve } from "node:path";
-import { FILLERS, FitMode, SlotType } from "../engine/index.js";
+import { FILLERS, ImageFit, 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";
+import { AssetType, 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).
+ * 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 function toImageFill(param, path) {
-    return { type: SlotType.Image, path, fit: param.fit };
+/** 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,
+};
+export function toImageFill(path, type) {
+    return { type: SlotType.Image, path, fit: FIT_FOR[type] };
 }
 /**
  * Reserved keys in a deck's frontmatter — global (theme, output) and per-slide
@@ -26,6 +28,7 @@ export const RESERVED_KEY = {
     BODY: "body",
     OUTPUT: "output",
     THEME: "theme",
+    NOTES: "notes",
 };
 const CODE_FENCE_RE = /^```(\w+)\n([\s\S]*?)```\s*$/;
 function toTextFill(text) {
@@ -140,12 +143,18 @@ function validateLayout(layout) {
         claimContentKey(slot.key, "slot");
     }
 }
-function compileStep(slide, layouts, rootDir) {
+function compileStep(slide, layouts, rootDir, assetTypeByPath) {
     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) {
@@ -174,11 +183,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);
@@ -248,7 +263,10 @@ function compileStep(slide, layouts, rootDir) {
     // 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 step = { layout: layoutName, content };
+    if (notes !== undefined)
+        step.notes = notes;
+    return step;
 }
 const KNOWN_GLOBAL_KEYS = new Set([RESERVED_KEY.THEME, RESERVED_KEY.OUTPUT]);
 /**
@@ -261,7 +279,7 @@ const KNOWN_GLOBAL_KEYS = new Set([RESERVED_KEY.THEME, RESERVED_KEY.OUTPUT]);
  * 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 = "") {
+export function compileDeck(doc, layouts, rootDir = "", assets = {}) {
     const theme = doc.global[RESERVED_KEY.THEME];
     if (theme === undefined) {
         throw new Error(`Missing required "${RESERVED_KEY.THEME}" in global frontmatter`);
@@ -274,9 +292,17 @@ export function compileDeck(doc, layouts, rootDir = "") {
     // theme fails fast regardless of which layouts this deck's slides use.
     for (const layout of layouts)
         validateLayout(layout);
+    // 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);
+        }
+    }
     const deck = {
         theme: String(theme),
-        steps: doc.slides.map((slide) => compileStep(slide, layouts, rootDir)),
+        steps: doc.slides.map((slide) => compileStep(slide, layouts, rootDir, assetTypeByPath)),
     };
     const output = doc.global[RESERVED_KEY.OUTPUT];
     if (output !== undefined) {
@@ -284,6 +310,3 @@ export function compileDeck(doc, layouts, rootDir = "") {
     }
     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

@@ -1,5 +1,5 @@
-import type { CompilerDeck, CompilerLayout } from "./types.js";
-export declare function compileMarkdownDeck(source: string, layouts: CompilerLayout[], rootDir?: string): CompilerDeck;
+import type { AssetCatalog, CompilerDeck, CompilerLayout } from "./types.js";
+export declare function compileMarkdownDeck(source: string, layouts: CompilerLayout[], rootDir?: string, assets?: AssetCatalog): CompilerDeck;
 export { compileDeck, RESERVED_KEY } from "./deckCompiler.js";
 export { parseGfmTable, parseInlineRuns, parseProseLine, parseStyledParagraph } from "./parsers.js";
 export { CodeResolver, highlightCode, isCodeBlock } from "./resolvers/code.js";
@@ -10,4 +10,4 @@ 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";
+export { AssetType, CompilerSlotType, FenceType, ParameterType } from "./types.js";

package/dist/markdown/index.js

@@ -1,8 +1,8 @@
 import { compileDeck } from "./deckCompiler.js";
 import { parseSlideDocument } from "./slideParser.js";
-export function compileMarkdownDeck(source, layouts, rootDir = "") {
+export function compileMarkdownDeck(source, layouts, rootDir = "", assets = {}) {
     const doc = parseSlideDocument(source);
-    return compileDeck(doc, layouts, rootDir);
+    return compileDeck(doc, layouts, rootDir, assets);
 }
 export { compileDeck, RESERVED_KEY } from "./deckCompiler.js";
 export { parseGfmTable, parseInlineRuns, parseProseLine, parseStyledParagraph } from "./parsers.js";
@@ -10,4 +10,4 @@ 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";
+export { AssetType, CompilerSlotType, FenceType, ParameterType } from "./types.js";

package/dist/markdown/resolvers/mermaid.js

@@ -1,29 +1,14 @@
-import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import { FitMode, SlotType } from "../../engine/index.js";
+import { ImageFit, SlotType } from "../../engine/index.js";
 import { CompilerSlotType, FenceType } from "../types.js";
 import { buildMermaidRenderConfig, injectClassDefs, validateMermaidDefinition, } from "./mermaidTheme.js";
 /** Discriminator for MermaidFence values. Doubles as `MermaidResolver.matches`. */
 export function isMermaidBlock(v) {
     return (typeof v === "object" && v !== null && !Array.isArray(v) && v.type === FenceType.Mermaid);
 }
-function findMmdc() {
-    try {
-        const resolved = execFileSync("npx", ["--no-install", "which", "mmdc"], {
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "pipe"],
-        }).trim();
-        if (resolved)
-            return resolved;
-    }
-    catch {
-        // fall through
-    }
-    throw new Error("mermaid-cli is required for mermaid diagrams. Install it: npm i -D @mermaid-js/mermaid-cli");
-}
 function hashKey(definition, variantName) {
     return createHash("sha256").update(variantName).update("\n").update(definition).digest("hex").slice(0, 16);
 }
@@ -32,7 +17,7 @@ function ensureCacheDir(config) {
     mkdirSync(base, { recursive: true });
     return base;
 }
-function renderOne(definition, variantName, variant, cacheDir, mmdcPath) {
+async function renderOne(definition, variantName, variant, cacheDir) {
     const validated = validateMermaidDefinition(definition);
     const processed = injectClassDefs(validated, variant.accents, variant.accentOpacity, variant.accentTextColor, variant.surface, variant.groupCornerRadius);
     const key = hashKey(processed, variantName);
@@ -40,17 +25,25 @@ function renderOne(definition, variantName, variant, cacheDir, mmdcPath) {
     if (existsSync(outputPath))
         return outputPath;
     const config = buildMermaidRenderConfig(variant);
-    const scratch = tmpdir();
-    const configPath = join(scratch, `tycoslide-mermaid-config-${key}.json`);
-    const inputPath = join(scratch, `tycoslide-mermaid-${key}.mmd`);
-    writeFileSync(configPath, JSON.stringify(config));
+    const inputPath = join(tmpdir(), `tycoslide-mermaid-${key}.mmd`);
     writeFileSync(inputPath, processed);
+    // mermaid-cli's programmatic API (lazy-imported so puppeteer only loads when a
+    // deck actually renders mermaid). Mirrors the old CLI flags: --configFile →
+    // mermaidConfig, -b transparent → backgroundColor, -s 2 → deviceScaleFactor.
+    const { run } = await import("@mermaid-js/mermaid-cli");
     try {
-        execFileSync(mmdcPath, ["-i", inputPath, "-o", outputPath, "--configFile", configPath, "-b", "transparent", "-s", "2"], { stdio: ["pipe", "pipe", "pipe"], timeout: 30_000 });
+        await run(inputPath, outputPath, {
+            quiet: true,
+            outputFormat: "png",
+            parseMMDOptions: {
+                mermaidConfig: config,
+                backgroundColor: "transparent",
+                viewport: { width: 800, height: 600, deviceScaleFactor: 2 },
+            },
+        });
     }
     catch (e) {
-        const stderr = e.stderr?.toString() ?? e.message;
-        throw new Error(`Mermaid render failed:\n${stderr}`);
+        throw new Error(`Mermaid render failed:\n${e?.message ?? e}`);
     }
     return outputPath;
 }
@@ -81,9 +74,8 @@ export const MermaidResolver = {
             throw new Error(`Slide layout "${ctx.layout.name}": mermaid variant "${variantName}" not found in theme. ` +
                 `Available variants: ${Object.keys(config.mermaid).join(", ")}`);
         }
-        const mmdcPath = findMmdc();
         const cacheDir = ensureCacheDir(config);
-        const pngPath = renderOne(fence.definition, variantName, variant, cacheDir, mmdcPath);
-        return { type: SlotType.Image, path: pngPath, fit: FitMode.Contain };
+        const pngPath = await renderOne(fence.definition, variantName, variant, cacheDir);
+        return { type: SlotType.Image, path: pngPath, fit: ImageFit.Contain };
     },
 };

package/dist/markdown/types.d.ts

@@ -1,5 +1,16 @@
-import { type FitMode, type ImageFill, type TableFill, type TemplateFill, type TextFill } from "../engine/index.js";
+import { type ImageFill, type TableFill, type TemplateFill, type TextFill } from "../engine/index.js";
 import type { MermaidConfig } from "./resolvers/mermaidTheme.js";
+/**
+ * An asset's scaling/cropping tolerance, declared in the theme catalog. The
+ * compiler maps it to the engine's object-fit `fit`. `icon`: never enlarge,
+ * never crop. `image`: never crop, may scale. `background`: crop and scale freely.
+ */
+export declare const AssetType: {
+    readonly Icon: "icon";
+    readonly Image: "image";
+    readonly Background: "background";
+};
+export type AssetType = (typeof AssetType)[keyof typeof AssetType];
 /**
  * A theme's declaration of a reusable image asset. Purely compiler-facing —
  * the engine never sees this type; the compiler resolves an entry's `path`
@@ -8,6 +19,8 @@ import type { MermaidConfig } from "./resolvers/mermaidTheme.js";
  */
 export type AssetEntry = {
     path: string;
+    /** Required — a missing type is a fail-fast error. */
+    type: AssetType;
     description: string;
     whenToUse?: string;
 };
@@ -86,6 +99,8 @@ export type MarkdownBlock = TextFill | TableFill | CodeFence | MermaidFence | Im
 export type CompilerDeckStep = {
     layout: string;
     content?: Record<string, MarkdownBlock>;
+    /** Slide-level speaker notes, stripped from frontmatter. Plain text. */
+    notes?: string;
 };
 /**
  * The intermediate deck shape produced by compileDeck. buildDeck runs the
@@ -104,6 +119,8 @@ export type CompilerDeck = {
 export type ResolvedCompilerDeckStep = {
     layout: string;
     content?: Record<string, TextFill | TableFill | ImageFill | TemplateFill>;
+    /** Slide-level speaker notes, threaded through to the engine. Plain text. */
+    notes?: string;
 };
 /**
  * A CompilerDeck whose steps have been passed through the resolvers via
@@ -155,11 +172,10 @@ export type CompilerTemplateParameter = CompilerShapeBase & {
     /** The shape's text as one template with `{key}` placeholders; newlines are line breaks. */
     template: string;
 };
-/** Image parameter: one frontmatter path filled by fillImage. */
+/** Image parameter: one frontmatter path filled by fillImage. Sizing/crop
+ * behaviour comes from the resolved asset's `type`, not the slot. */
 export type CompilerImageParameter = CompilerSlotBase & {
     type: typeof ParameterType.Image;
-    /** How the picture scales inside its frame (required — no silent default). */
-    fit: FitMode;
 };
 /**
  * Compiler-facing parameter. A layout's frontmatter inputs — each written as a
@@ -175,8 +191,6 @@ export type CompilerTextSlot = CompilerSlotBase & {
 /** Table shape backed by an `<a:tbl>` with header + data specimen rows. */
 export type CompilerTableSlot = CompilerSlotBase & {
     type: typeof CompilerSlotType.Table;
-    /** Enforced column count. */
-    columns?: number;
 };
 /**
  * Text slot that consumes a fenced code block. The resolver (`CodeResolver`)

package/dist/markdown/types.js

@@ -1,4 +1,15 @@
-import { SlotType, } from "../engine/index.js";
+import { SlotType } from "../engine/index.js";
+// ── Asset catalog (compiler / theme-metadata only) ───────────────────────────
+/**
+ * An asset's scaling/cropping tolerance, declared in the theme catalog. The
+ * compiler maps it to the engine's object-fit `fit`. `icon`: never enlarge,
+ * never crop. `image`: never crop, may scale. `background`: crop and scale freely.
+ */
+export const AssetType = {
+    Icon: "icon",
+    Image: "image",
+    Background: "background",
+};
 // ── FenceType discriminator ───────────────────────────────────────────────────
 /**
  * Discriminator strings for the compiler-internal fence shapes produced by

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tycoworks/tycoslide",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,6 +22,8 @@
     "format": "biome format --write ."
   },
   "dependencies": {
+    "@mermaid-js/mermaid-cli": "^11.15.0",
+    "@xmldom/xmldom": "^0.9.10",
     "commander": "^15.0.0",
     "image-size": "^2.0.2",
     "pptx-automizer": "^0.8.2",
@@ -35,7 +37,6 @@
   "devDependencies": {
     "@biomejs/biome": "^2.5.1",
     "@types/node": "^22.20.0",
-    "@xmldom/xmldom": "^0.9.10",
     "typescript": "^5.8.0"
   }
 }

package/syntax.md

@@ -91,7 +91,7 @@ A layout advertises two kinds of author-facing input, split by one rule: **a par
   "parameters": [
     { "key": "title",    "type": "template" },
     { "key": "subtitle", "type": "template" },
-    { "key": "logo",     "type": "image", "fit": "contain", "required": true }
+    { "key": "logo",     "type": "image", "required": true }
   ],
   "slots": [
     { "key": "body", "type": "text" },
@@ -114,7 +114,7 @@ Fill a parameter by putting a value under its key in the slide's frontmatter.
   jobTitle: CEO, Acme Corp
   ```
   The engine substitutes each value into the run that carries its style, so if the designer made the name bold and the job title grey, the filled name stays bold and the filled title stays grey.
-- **`image`** -- a picture placeholder. Set it in frontmatter with the image path (from an asset catalog entry, or an absolute path). The parameter declares a `fit`: `contain` shows the whole image, `cover` fills the frame and center-crops overflow.
+- **`image`** -- a picture placeholder. Set it in frontmatter with the image path (from an asset catalog entry, or an absolute path). How it is scaled and cropped is set by the **asset's `type`** in the catalog (`icon` never enlarges past native and never crops; `image` fits the whole picture without cropping; `background` fills the frame and center-crops).
   ```yaml
   hero: assets/diagrams/architecture.png
   ```
@@ -136,13 +136,13 @@ Fill a slot by writing a region in the body: the default (unmarked) region maps
   ```
   ````
   The language tag (e.g. `sql`, `python`, `typescript`) is required -- it drives syntax highlighting. Colors are applied as native text runs in the output, not images.
-- **`mermaid`** -- a mermaid diagram rendered as a themed PNG (see below). Written as a fenced `mermaid` region; the resulting PNG fills the slot with `contain` fit.
+- **`mermaid`** -- a mermaid diagram rendered as a themed PNG (see below). Written as a fenced `mermaid` region; the resulting PNG is shown contained (in its entirety).
 
 ---
 
 ## Mermaid diagrams
 
-Mermaid diagrams are rendered as themed PNGs and delivered to any slot declared with `type: mermaid`. Write a fenced code block with the `mermaid` language tag in a named slot whose layout declares that slot as `type: mermaid` (with a `mermaidVariant` naming the theme's color variant). The resulting PNG behaves like any other image in the slot -- always shown in its entirety (`contain` fit).
+Mermaid diagrams are rendered as themed PNGs and delivered to any slot declared with `type: mermaid`. Write a fenced code block with the `mermaid` language tag in a named slot whose layout declares that slot as `type: mermaid` (with a `mermaidVariant` naming the theme's color variant). The resulting PNG behaves like any other image in the slot -- always shown in its entirety.
 
 To let the same physical slide accept either an image or a diagram, the theme author declares two layouts with the same `slideNumber` -- one exposing the fill as an `image` parameter (frontmatter path), one as a `mermaid` slot (a fenced region). Authors pick between them by naming the layout in frontmatter; the compiler routes content based on the layout's declaration, so there is no ambiguity.
 
@@ -214,7 +214,7 @@ hero: assets/diagrams/architecture.png
 Each parameter or slot in the layout definition may declare:
 - **`type`** (required) -- parameters: `template`, `image`; slots: `text`, `table`, `code`, `mermaid`.
 - **`required: true`** -- the slide has no usable default and the build fails if the parameter/slot has no value (e.g. team-member photos, icon-grid icons, the quote logo). If you don't have a suitable image, ask the user for one.
-- **`fit`** -- image parameters only (required): `contain` shows the whole image inside the frame (letterboxed); `cover` fills the frame and center-crops overflow. Fit is a layout-designer decision baked into the parameter -- callers never override it per slide. Mermaid slots don't declare `fit`; mermaid always renders contained.
+- **image sizing** -- each catalog asset declares a `type` (`icon` | `image` | `background`) that determines how it is scaled and cropped: `icon` never enlarges past native and never crops; `image` fits the whole picture (no crop, may scale); `background` fills and center-crops. Mermaid renders as `image` (contained).
 - **`codeTheme`** -- code slots only (required): the Shiki theme id used to syntax-highlight fenced code that lands in this slot (e.g. `"github-dark"`).
 - **`mermaidVariant`** -- mermaid slots only (required): names the color variant from `theme.mermaid` (e.g. `"dark"`). See [Mermaid diagrams](#mermaid-diagrams) above.
 
@@ -222,6 +222,26 @@ Each layout also declares a `slideNumber` pointing at the physical slide in the
 
 ---
 
+## Speaker notes
+
+Any slide may carry a `notes:` key in its frontmatter -- a plain-text speaker-notes block attached to that slide's notes page. It is slide-level metadata, not a parameter or a slot: it is never routed to a shape and never appears on the slide face, only in the presenter/notes view.
+
+Write multiple lines with a YAML block scalar (`|`); each line becomes one notes paragraph. Blank template notes on the underlying slide are always stripped, so only what you author here shows up.
+
+```yaml
+---
+layout: Body
+title: Key Achievements
+notes: |
+  Open by thanking the regional teams.
+  Land the 23% number, then pause before the churn stat.
+---
+```
+
+To build with all speaker notes omitted, pass `--no-notes` to `tycoslide build` (see [README](README.md#cli)).
+
+---
+
 ## Slides with no body
 
 Slides that have all their content in frontmatter (common for title slides, section dividers) need no body: