@tycoworks/tycoslide 0.7.0 → 0.9.0

package/dist/markdown/types.d.ts

@@ -1,5 +1,17 @@
-import { type FitMode, type ImageFill, type TableFill, type TemplateFill, type TextFill } from "../engine/index.js";
-import type { MermaidConfig } from "./resolvers/mermaidTheme.js";
+import type { RootContent } from "mdast";
+import { type Frame, type ImageFill, type TableFill, type TemplateFill, type TextFill } from "../engine/index.js";
+import type { MermaidConfig } from "./blocks/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,23 +20,13 @@ 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;
 };
 /** Two-level catalog: `{ category: { name: AssetEntry } }`. */
 export type AssetCatalog = Record<string, Record<string, AssetEntry>>;
-/**
- * Discriminator strings for the compiler-internal fence shapes produced by
- * deckCompiler.ts. `Code` and `Mermaid` are resolved away entirely (syntax
- * highlighting → TextFill, PNG rendering → ImageFill), so neither reaches the
- * engine. Prose has no FenceType: it becomes a `TextFill` (`{ paragraphs }`),
- * one of the engine's own fill shapes.
- */
-export declare const FenceType: {
-    readonly Code: "code";
-    readonly Mermaid: "mermaid";
-};
-export type FenceType = (typeof FenceType)[keyof typeof FenceType];
 /**
  * Discriminator for a layout's frontmatter *parameters* — inputs the author
  * writes as a single `key: value` line. Two kinds: `Template` (fills a styled
@@ -38,58 +40,84 @@ export declare const ParameterType: {
 };
 export type ParameterType = (typeof ParameterType)[keyof typeof ParameterType];
 /**
- * Compiler-facing slot type for a layout's *slots* — multi-line body regions
- * (the default body region, or a `::name::` region). Narrowed to four kinds;
- * `Template` and `Image` left this list to become parameters. `Code` and `Mermaid`
- * are compiler-only, resolved (syntax highlighting, mermaid PNG rendering)
- * before the engine sees the deck. Required on every CompilerSlot — no silent
- * default.
+ * The engine content types a slot may `accept`. A subset of the engine's
+ * `SlotType`: `Template` is parameter-only, never a body block. There is no
+ * `code` / `mermaid` accept type — a code fence folds into a `Text`-accepting
+ * slot (syntax highlighting → TextFill) and a mermaid fence into an
+ * `Image`-accepting slot (PNG render → ImageFill), the same fold the engine
+ * already performs. The author's markdown shape selects which accepted type a
+ * region routes to.
  */
-export declare const CompilerSlotType: {
+export declare const AcceptType: {
     readonly Text: "text";
     readonly Table: "table";
-    readonly Code: "code";
-    readonly Mermaid: "mermaid";
+    readonly Image: "image";
 };
-export type CompilerSlotType = (typeof CompilerSlotType)[keyof typeof CompilerSlotType];
+export type AcceptType = (typeof AcceptType)[keyof typeof AcceptType];
 /**
- * A fenced code block awaiting syntax highlighting. Produced by deckCompiler,
- * consumed by CodeResolver. Never crosses the engine boundary.
+ * The four engine content shapes a slot's compiled content can be — the value
+ * `compile` produces and the engine fills. ImageFill carries a `.type`
+ * discriminator; the other three — TextFill, TableFill, TemplateFill — are
+ * identified structurally by their signature field.
  */
-export type CodeFence = {
-    type: typeof FenceType.Code;
-    language: string;
-    source: string;
-};
+export type EngineFill = TextFill | TableFill | ImageFill | TemplateFill;
+/**
+ * The three engine content shapes a block handler can produce. A subset of
+ * `EngineFill` — `TemplateFill` is parameter-only (`AcceptType` excludes
+ * `Template`), so no block handler ever compiles one.
+ */
+export type BlockFill = TextFill | TableFill | ImageFill;
 /**
- * A mermaid code fence awaiting rendering. Produced by deckCompiler, consumed
- * by MermaidResolver — the resulting PNG is wrapped as an ImageFill in
- * step.content, so the engine never learns mermaid exists.
+ * Everything a block handler needs to compile a node into its engine fill: the
+ * asset resolver, the diagnostic context to name the offending layout/slide/slot
+ * when a region's markdown shape is illegal (a stray standalone block mixed into
+ * prose), and the theme-level `config` — from which code/mermaid compile read
+ * their one-per-theme style (`codeTheme`, `mermaid`, `mermaidVariant`,
+ * `outputDir`), not the slot.
+ *
+ * Lives in types.ts (not in `blocks/registry.ts`, which re-exports it) so a
+ * per-kind block file can import it without importing the registry — the registry
+ * imports the per-kind handlers, so the reverse would cycle.
  */
-export type MermaidFence = {
-    type: typeof FenceType.Mermaid;
-    definition: string;
+export type BlockContext = {
+    resolveAssetRef: (ref: string) => ImageFill;
+    layoutName: string;
+    slideIdx: number;
+    source: string;
+    config: CompilerConfig;
 };
 /**
- * The full set of value shapes a slot may hold during compilation, before code
- * fences are highlighted (→ TextFill) and mermaid fences are rendered
- * (→ ImageFill). CodeFence, MermaidFence, and ImageFill carry a `.type`
- * discriminator; the three engine fills without one — TextFill, TableFill,
- * TemplateFill — are identified structurally by their signature field.
+ * A block handler recognizes one content kind at the region's top level, folds
+ * it to the engine `AcceptType` it fills, and compiles the node straight into the
+ * matching engine fill — highlighting a code fence to a TextFill, rendering a
+ * mermaid fence to an ImageFill. Recognition (`match`), type (`acceptType`), and
+ * build (`compile`) live together — a new content kind is one file, one registry
+ * row. Non-generic like the engine's `Filler`: the array can't correlate a
+ * per-element type guard with `compile`'s param, so each handler narrows the node
+ * internally with a single-hop cast. Mirrors the old sdk's `SyntaxHandler`.
  */
-export type MarkdownBlock = TextFill | TableFill | CodeFence | MermaidFence | ImageFill | TemplateFill;
+export type BlockHandler = {
+    match(node: RootContent): boolean;
+    acceptType: AcceptType;
+    compile(node: RootContent, ctx: BlockContext): Promise<BlockFill>;
+};
 /**
- * A DeckStep as compileDeck produces it — content values may still be
- * unresolved (CodeFence, MermaidFence) at this point. `resolveFences` narrows
- * these into StyledParagraph[] / ImageFill before the engine sees the deck.
+ * A DeckStep as the compiler produces it. Content is already engine-shaped —
+ * code fences highlighted to TextFill and mermaid fences rendered to ImageFill
+ * during `compile` — so this is structurally equivalent to the engine's DeckStep
+ * and needs no further resolution.
  */
 export type CompilerDeckStep = {
     layout: string;
-    content?: Record<string, MarkdownBlock>;
+    content?: Record<string, EngineFill>;
+    /** Slide-level speaker notes, stripped from frontmatter. Plain text. */
+    notes?: string;
 };
 /**
- * The intermediate deck shape produced by compileDeck. buildDeck runs the
- * resolvers and hands the resulting engine-shaped Deck to generate().
+ * The deck shape the compiler produces. `output` may be unset until a caller
+ * (the CLI, or a programmatic caller) assigns one; `buildDeck` fails fast if it
+ * is still missing. Once `output` is present this is structurally equivalent to
+ * the engine's Deck, so `generate` consumes it without any cast.
  */
 export type CompilerDeck = {
     theme: string;
@@ -97,50 +125,15 @@ export type CompilerDeck = {
     steps: CompilerDeckStep[];
 };
 /**
- * A DeckStep whose content values have been narrowed post-resolution — no
- * CodeFence or MermaidFence remains, only shapes the engine understands.
- * Structurally equivalent to the engine's DeckStep.
+ * Markdown-flavored measurement hints on a slot or template parameter: caps on
+ * expanded run text, line count, or list items. All optional — a missing cap is
+ * "no limit." Advisory metadata surfaced in the manifest; the fill never enforces
+ * it.
  */
-export type ResolvedCompilerDeckStep = {
-    layout: string;
-    content?: Record<string, TextFill | TableFill | ImageFill | TemplateFill>;
-};
-/**
- * A CompilerDeck whose steps have been passed through the resolvers via
- * `resolveFences`. Structurally equivalent to the engine's Deck — deck
- * resolution returns this shape so `generate` can consume it without any cast.
- */
-export type ResolvedCompilerDeck = {
-    theme: string;
-    output: string;
-    steps: ResolvedCompilerDeckStep[];
-};
-/**
- * Fields common to every text shape, image parameter, and slot. A text shape is
- * addressed by `shapeName` and owns a `template` (its placeholders are the
- * fillable keys); image parameters and slots additionally carry a single `key`.
- */
-type CompilerShapeBase = {
-    shapeName: string;
-    limit?: {
-        maxChars?: number;
-        maxLines?: number;
-        maxItems?: number;
-    };
-    /**
-     * Whether the parameter/slot may be omitted from a slide. Optional (defaults
-     * to false): a required one with no value causes the compiler to throw with
-     * layout + key names.
-     */
-    required?: boolean;
-};
-/**
- * Shape base plus a single `key` — the addressing model for image parameters
- * and every slot. Template parameters do NOT extend this: their fillable keys are
- * the placeholders in their `template`, not a single top-level key.
- */
-type CompilerSlotBase = CompilerShapeBase & {
-    key: string;
+export type Limit = {
+    maxChars?: number;
+    maxLines?: number;
+    maxItems?: number;
 };
 /**
  * Template parameter: a styled text shape filled by expanding a `template` into the
@@ -150,76 +143,117 @@ type CompilerSlotBase = CompilerShapeBase & {
  * placeholders in its template. The shape carries no top-level `key`; its
  * placeholders are the keys the author fills in frontmatter.
  */
-export type CompilerTemplateParameter = CompilerShapeBase & {
+export type CompilerTemplateParameter = {
+    shapeName: string;
+    limit?: Limit;
+    /**
+     * Whether the parameter may be omitted from a slide. Optional (defaults to
+     * false): a required one with no value causes the compiler to throw with
+     * layout + key names.
+     */
+    required?: boolean;
     type: typeof ParameterType.Template;
     /** The shape's text as one template with `{key}` placeholders; newlines are line breaks. */
     template: string;
 };
-/** Image parameter: one frontmatter path filled by fillImage. */
-export type CompilerImageParameter = CompilerSlotBase & {
+/** Image parameter: one frontmatter path filled by fillImage. Sizing/crop
+ * behaviour comes from the resolved asset's `type`, not the slot. Carries no
+ * `limit` — measuring an image path against char/line caps is meaningless. */
+export type CompilerImageParameter = {
+    shapeName: string;
+    /**
+     * Whether the parameter may be omitted from a slide. Optional (defaults to
+     * false): a required one with no value causes the compiler to throw with
+     * layout + key names.
+     */
+    required?: boolean;
+    key: string;
     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
  * single `key: value` line, resolved against the layout's `parameters` list.
  */
 export type CompilerParameter = CompilerTemplateParameter | CompilerImageParameter;
-/** Multi-paragraph body filled by fillText (specimen-style rebuild). */
-export type CompilerTextSlot = CompilerSlotBase & {
-    type: typeof CompilerSlotType.Text;
-    /** Leave the first N specimen paragraphs untouched. */
-    startAt?: number;
-};
-/** 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`)
- * uses `codeTheme` to Shiki-highlight the source into StyledParagraph[]; the
- * engine sees the projected Text slot.
+ * 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 type CompilerCodeSlot = CompilerSlotBase & {
-    type: typeof CompilerSlotType.Code;
-    /** Shiki theme id (required — no silent default). */
-    codeTheme: string;
+export declare const RESERVED_KEY: {
+    readonly LAYOUT: "layout";
+    readonly BODY: "body";
+    readonly OUTPUT: "output";
+    readonly THEME: "theme";
+    readonly NOTES: "notes";
 };
 /**
- * Slot that consumes a mermaid code fence. The resolver (`MermaidResolver`)
- * uses `mermaidVariant` to select colors and renders a PNG; the engine sees the
- * projected Image slot with `contain` fit. Mermaid slots do NOT declare `fit` —
- * mermaid diagrams are always contained.
+ * A kind of content a slot accepts, and the real template shape that realizes
+ * it — the compiler mirror of the engine's `Block`. `type` is an engine content
+ * type (`text` | `table` | `image`); `shapeName` names the shape on
+ * `sourceSlide` carrying the specimen styling. When `sourceSlide` equals the
+ * layout's `slideNumber` the shape is already on the cloned slide (fill in
+ * place); otherwise it is transplanted into the slot's `frame`. `startAt` is a
+ * text-specimen concern (leave the first N specimen paragraphs untouched), only
+ * meaningful on a text block. Named `CompilerBlock` to stay distinct from the
+ * engine's `Block` and the compiler's `BlockHandler`.
  */
-export type CompilerMermaidSlot = CompilerSlotBase & {
-    type: typeof CompilerSlotType.Mermaid;
-    /** Name of the mermaid variant (required — no silent default). */
-    mermaidVariant: string;
+export type CompilerBlock = {
+    type: AcceptType;
+    sourceSlide: number;
+    shapeName: string;
+    startAt?: number;
 };
 /**
- * Compiler-facing slot. Discriminated union on `type` — each variant declares
- * ONLY the fields legal for that slot type. A layout's body regions (the
- * default region, or a `::name::` region), resolved against the layout's
- * `slots` list. Adds markdown-flavored concepts (limit hints, code-fence theme
- * selection, mermaid variant naming) on top of the engine's minimal Slot.
- * Compiler-only types (Code, Mermaid) are projected down to engine types (Text,
- * Image) at the engine boundary before the engine sees the layout.
+ * Compiler-facing slot. A layout's body region (the default region, or a
+ * `::name::` region), no longer welded to one shape+type: it `accepts` a set of
+ * `CompilerBlock`s and owns a `frame` (real observed EMU coordinates, never
+ * computed). The author's markdown shape selects which accepted block a region
+ * routes to; a type the slot does not accept fails fast. `frame` is required
+ * only when a slot has a transplant block (a block whose `sourceSlide` differs
+ * from the layout's `slideNumber`); a base-only slot fills in place and needs
+ * none. Adds markdown-flavored `limit` hints on top of the engine's minimal
+ * Slot; per-slot `codeTheme` / `mermaidVariant` moved to the theme level.
  */
-export type CompilerSlot = CompilerTextSlot | CompilerTableSlot | CompilerCodeSlot | CompilerMermaidSlot;
+export type CompilerSlot = {
+    key: string;
+    accepts: CompilerBlock[];
+    frame?: Frame;
+    limit?: Limit;
+    /**
+     * Whether the slot may be omitted from a slide. Optional (defaults to false):
+     * a required slot with no content throws with layout + key names.
+     */
+    required?: boolean;
+};
 export type CompilerLayout = {
     name: string;
     slideNumber: number;
-    description: string;
-    whenToUse: string;
-    whenNotToUse: string;
+    /** Optional prose — a layout is a shape, not a purpose (agent-guidance descoped). */
+    description?: string;
+    whenToUse?: string;
+    whenNotToUse?: string;
     /** Frontmatter inputs (template, image) — one value per `key: value` line. */
     parameters: CompilerParameter[];
-    /** Body regions (text, table, code, mermaid) — the body or `::name::` regions. */
+    /** Body regions — the default body or `::name::` regions; each `accepts` blocks. */
     slots: CompilerSlot[];
 };
+/**
+ * A brand font the theme hands the compiler for HTML-based rendering (currently
+ * mermaid). Purely compiler-facing — the engine fills PPTX shapes, whose fonts
+ * live in the template, and never sees this. `path` is a module specifier
+ * (`@fontsource/inter/files/inter-latin-400-normal.woff2`) resolved from the
+ * theme's directory, or a `./`- / `/`-prefixed filesystem path resolved against
+ * `rootDir`; `family` is the CSS `font-family` name the mermaid variant's
+ * `fontFamily` must match. Register weight 400 + 700 to avoid synthetic bold on
+ * node labels. The mechanism is generic — the theme names its own fonts.
+ */
+export type ThemeFont = {
+    family: string;
+    path: string;
+    /** OpenType weight (default 400). */
+    weight?: number;
+};
 /**
  * Compiler-facing theme configuration. Mirrors the engine's ThemeConfig but
  * carries markdown-flavored fields (mermaid variants) that live outside the
@@ -232,8 +266,21 @@ export type CompilerThemeConfig = {
     template: string;
     outputDir?: string;
     mermaid?: MermaidConfig;
+    /**
+     * Brand fonts injected as `@font-face` when rendering mermaid, so diagram text
+     * uses the theme font instead of a Chromium fallback. Optional — with none
+     * declared, mermaid renders in whatever the OS substitutes.
+     */
+    fonts?: ThemeFont[];
+    /**
+     * Theme-level defaults for the two content types the compiler resolves before
+     * the engine sees them. One code style and one mermaid style per theme (the
+     * design-system framing) — they can't sit on a multi-type slot. `codeTheme` is
+     * a Shiki theme id; `mermaidVariant` names an entry in `mermaid`.
+     */
+    codeTheme?: string;
+    mermaidVariant?: string;
 };
 export type CompilerConfig = CompilerThemeConfig & {
     rootDir: string;
 };
-export {};

package/dist/markdown/types.js

@@ -1,15 +1,14 @@
 import { SlotType, } from "../engine/index.js";
-// ── FenceType discriminator ───────────────────────────────────────────────────
+// ── Asset catalog (compiler / theme-metadata only) ───────────────────────────
 /**
- * Discriminator strings for the compiler-internal fence shapes produced by
- * deckCompiler.ts. `Code` and `Mermaid` are resolved away entirely (syntax
- * highlighting → TextFill, PNG rendering → ImageFill), so neither reaches the
- * engine. Prose has no FenceType: it becomes a `TextFill` (`{ paragraphs }`),
- * one of the engine's own fill shapes.
+ * 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 FenceType = {
-    Code: "code",
-    Mermaid: "mermaid",
+export const AssetType = {
+    Icon: "icon",
+    Image: "image",
+    Background: "background",
 };
 // ── ParameterType discriminator (frontmatter, one value) ──────────────────────
 /**
@@ -23,18 +22,30 @@ export const ParameterType = {
     Template: SlotType.Template,
     Image: SlotType.Image,
 };
-// ── CompilerSlotType discriminator (body region, multi-line) ──────────────────
+// ── AcceptType discriminator (what a slot accepts) ────────────────────────────
 /**
- * Compiler-facing slot type for a layout's *slots* — multi-line body regions
- * (the default body region, or a `::name::` region). Narrowed to four kinds;
- * `Template` and `Image` left this list to become parameters. `Code` and `Mermaid`
- * are compiler-only, resolved (syntax highlighting, mermaid PNG rendering)
- * before the engine sees the deck. Required on every CompilerSlot — no silent
- * default.
+ * The engine content types a slot may `accept`. A subset of the engine's
+ * `SlotType`: `Template` is parameter-only, never a body block. There is no
+ * `code` / `mermaid` accept type — a code fence folds into a `Text`-accepting
+ * slot (syntax highlighting → TextFill) and a mermaid fence into an
+ * `Image`-accepting slot (PNG render → ImageFill), the same fold the engine
+ * already performs. The author's markdown shape selects which accepted type a
+ * region routes to.
  */
-export const CompilerSlotType = {
+export const AcceptType = {
     Text: SlotType.Text,
     Table: SlotType.Table,
-    Code: FenceType.Code,
-    Mermaid: FenceType.Mermaid,
+    Image: SlotType.Image,
+};
+/**
+ * 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",
+    NOTES: "notes",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tycoworks/tycoslide",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,20 +22,24 @@
     "format": "biome format --write ."
   },
   "dependencies": {
+    "@xmldom/xmldom": "^0.9.10",
     "commander": "^15.0.0",
     "image-size": "^2.0.2",
+    "mermaid": "^11.16.1",
+    "playwright": "^1.58.2",
     "pptx-automizer": "^0.8.2",
     "remark-gfm": "^4.0.1",
     "remark-ins": "^1.2.5",
     "remark-parse": "^11.0.0",
     "shiki": "^4.3.0",
     "unified": "^11.0.0",
-    "yaml": "^2.0.0"
+    "yaml": "^2.0.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.1",
     "@types/node": "^22.20.0",
-    "@xmldom/xmldom": "^0.9.10",
+    "jszip": "^3.10.1",
     "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:

package/dist/markdown/parsers.d.ts

@@ -1,32 +0,0 @@
-import type { StyledParagraph, TableFill, TextRun } from "../engine/index.js";
-/**
- * Parse inline markdown formatting in a single line of text into TextRun arrays.
- * Handles **bold**, *italic*, ***bold italic***, ~~strikethrough~~, ++underline++,
- * [link](url), and `inline code`.
- */
-export declare function parseInlineRuns(text: string): TextRun[];
-/**
- * Parse a raw prose line into a StyledParagraph with bullet detection and inline
- * formatting. The caller provides the raw line including leading whitespace and
- * bullet markers.
- */
-export declare function parseStyledParagraph(raw: string): StyledParagraph;
-/**
- * Parse a single line of prose into its structural components.
- *
- * Lines beginning with `- ` or `* ` (optionally preceded by spaces) are
- * recognized as bullet items. Every 2 spaces of leading indent on a bullet
- * line increase its level by 1. A leading dash without a trailing space is
- * NOT a bullet (e.g. `-foo`).
- */
-export declare function parseProseLine(raw: string): {
-    text: string;
-    bullet: boolean;
-    level: number;
-};
-/**
- * Parse a GFM table into TableFill (StyledParagraph[] cells). Returns null
- * for non-table text. Cells carry rich runs so inline formatting works
- * inside tables for free.
- */
-export declare function parseGfmTable(text: string): TableFill | null;