@tycoworks/tycoslide 0.15.1 → 0.16.0

package/dist/markdown/deckCompiler.d.ts

@@ -1,23 +1,12 @@
-import { type ImageFill } from "../engine/index.js";
 import type { ParsedDocument } from "./slideParser.js";
-import { AssetType, type CompilerConfig, type CompilerDeck } from "./types.js";
-/**
- * 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 function toImageFill(path: string, type: AssetType): ImageFill;
+import { type CompilerConfig, type CompilerDeck } from "./types.js";
 /**
  * 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`.
  *
- * `config.rootDir` is the base directory for resolving the asset catalog's
- * relative image paths. 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` /
+ * Image paths resolve against `config.deckDir`. `config.codeTheme` /
  * `config.mermaid` / `config.mermaidVariant` feed the code and mermaid compiles.
  */
 export declare function compileDeck(doc: ParsedDocument, config: CompilerConfig): Promise<CompilerDeck>;

package/dist/markdown/deckCompiler.js

@@ -1,27 +1,8 @@
-import { resolve } from "node:path";
-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 { AssetType, 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,
-};
-/**
- * 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(path, type) {
-    return { type: SlotType.Image, path, fit: FIT_FOR[type] };
-}
+import { RESERVED_KEY, } from "./types.js";
 const KNOWN_GLOBAL_KEYS = new Set([RESERVED_KEY.THEME]);
-// 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 folds to a type the slot `accepts`. The
  * folded type comes straight from `parseSlotContent` (which returns it beside
@@ -36,17 +17,6 @@ function assertSlotRegion(slot, got, layoutName, slideNo, source) {
             `(from ${source}); it accepts: ${accepted}.`);
     }
 }
-/**
- * Resolve a catalog 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);
-}
 /**
  * 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
@@ -111,7 +81,7 @@ function validateLayout(layout) {
         claimContentKey(slot.key, "slot");
     }
 }
-async function compileStep(slide, config, resolveAssetRef) {
+async function compileStep(slide, config) {
     const { layouts } = config;
     const { frontmatter, slots, index } = slide;
     // Slide numbers in errors are 1-based, matching how an author counts slides in
@@ -192,10 +162,10 @@ async function compileStep(slide, config, resolveAssetRef) {
         }
         const source = `::${name}::`;
         const parsed = parseSlotContent(text, {
-            resolveAssetRef,
             layoutName,
             slideNo: slideNo,
             source,
+            region: `Slide ${slideNo}: layout "${layoutName}" slot content (from ${source})`,
             config,
             layoutVariant: layoutDef.variant,
         });
@@ -222,15 +192,11 @@ async function compileStep(slide, config, resolveAssetRef) {
  * code (Shiki) and rendered mermaid (PNG) — so the returned deck is
  * engine-shaped, ready for `buildDeck`.
  *
- * `config.rootDir` is the base directory for resolving the asset catalog's
- * relative image paths. 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` /
+ * Image paths resolve against `config.deckDir`. `config.codeTheme` /
  * `config.mermaid` / `config.mermaidVariant` feed the code and mermaid compiles.
  */
 export async function compileDeck(doc, config) {
-    const { layouts, rootDir, assets } = config;
+    const { layouts } = config;
     const theme = doc.global[RESERVED_KEY.THEME];
     if (theme === undefined) {
         throw new Error(`Missing required "${RESERVED_KEY.THEME}" in global frontmatter`);
@@ -245,48 +211,11 @@ export async function compileDeck(doc, config) {
     assertUniqueSlideNumbers(layouts);
     for (const layout of layouts)
         validateLayout(layout);
-    // A body image names a picture one of two ways, and both end as an absolute
-    // path plus a fit: `$category.name` looks the picture up in the theme's
-    // catalog (which carries its declared type), while anything else is a file
-    // path relative to the deck (typed `image`, since nothing declares it). Only
-    // the lookup differs; the wrapping is shared.
-    const fromCatalog = (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) {
-            // Every asset in the catalog is far too many to read: a theme's icon set
-            // alone can run to thousands.
-            // A known category narrows it to that category's names, which is what the
-            // author is choosing between; an unknown one lists the categories instead.
-            const group = assets[category];
-            const available = group
-                ? Object.keys(group)
-                    .map((n) => `$${category}.${n}`)
-                    .join(", ")
-                : Object.keys(assets)
-                    .map((c) => `$${c}.*`)
-                    .join(", ");
-            throw new Error(`Unknown asset reference "${ref}". Available: ${available}`);
-        }
-        return { path: resolveImagePath(rootDir, entry.path), type: entry.type };
-    };
-    const fromDeck = (ref) => ({
-        path: resolveImagePath(config.deckDir, ref),
-        type: AssetType.Image,
-    });
-    const resolveAssetRef = (ref) => {
-        const { path, type } = ref.startsWith("$") ? fromCatalog(ref) : fromDeck(ref);
-        return toImageFill(path, 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.
+    // accept-type mismatch) fire before its own content is rendered.
     const steps = [];
     for (const slide of doc.slides) {
-        steps.push(await compileStep(slide, config, resolveAssetRef));
+        steps.push(await compileStep(slide, config));
     }
     return { theme: String(theme), steps };
 }

package/dist/markdown/index.d.ts

@@ -6,8 +6,10 @@ export { type BlockContext, type BlockHandler, parseSlotContent } from "./blocks
 export { compileDeck } from "./deckCompiler.js";
 export { parseInlineRuns } from "./inline.js";
 export { parseRegion } from "./mdast.js";
+export { strict } from "./schema/strict.js";
 export { loadThemeConfig, parseThemeConfig, ThemeConfigSchema } from "./schema/themeConfigSchema.js";
 export type { ParsedDocument, RawSlide } from "./slideParser.js";
 export { parseSlideDocument } from "./slideParser.js";
-export type { AssetCatalog, AssetEntry, CompilerBlock, CompilerConfig, CompilerDeck, CompilerDeckStep, CompilerLayout, CompilerParameter, CompilerSlot, CompilerThemeConfig, EngineFill, LoadedTheme, } from "./types.js";
-export { AcceptType, AssetType, RESERVED_KEY } from "./types.js";
+export { templateKeys } from "./textTemplate.js";
+export type { CompilerBlock, CompilerConfig, CompilerDeck, CompilerDeckStep, CompilerLayout, CompilerParameter, CompilerSlot, CompilerThemeConfig, EngineFill, LoadedTheme, } from "./types.js";
+export { AcceptType, RESERVED_KEY } from "./types.js";

package/dist/markdown/index.js

@@ -9,6 +9,8 @@ export { parseSlotContent } from "./blocks/registry.js";
 export { compileDeck } from "./deckCompiler.js";
 export { parseInlineRuns } from "./inline.js";
 export { parseRegion } from "./mdast.js";
+export { strict } from "./schema/strict.js";
 export { loadThemeConfig, parseThemeConfig, ThemeConfigSchema } from "./schema/themeConfigSchema.js";
 export { parseSlideDocument } from "./slideParser.js";
-export { AcceptType, AssetType, RESERVED_KEY } from "./types.js";
+export { templateKeys } from "./textTemplate.js";
+export { AcceptType, RESERVED_KEY } from "./types.js";

package/dist/markdown/inline.d.ts

@@ -22,5 +22,7 @@ export interface InlineState {
     underline?: boolean;
     link?: string;
     breakAsNewline?: boolean;
+    /** Where the text sits (the slot region), to name in an error. */
+    region?: string;
 }
 export declare function walkPhrasingChildren(children: PhrasingContent[], state: InlineState): TextRun[];

package/dist/markdown/inline.js

@@ -71,12 +71,13 @@ function walkPhrasing(node, state) {
             // path it collapses to a space.
             return [makeRun(state.breakAsNewline ? "\n" : " ", state)];
         default:
-            // Any other phrasing node with a literal `value` (footnote references,
-            // etc.) — emit its text if it has one, otherwise nothing.
+            // Any other phrasing node with a literal `value` (inline HTML) is emitted as
+            // that text. One without (an image inside a sentence) has nothing to show,
+            // so it fails rather than vanish from the slide.
             if ("value" in node && typeof node.value === "string") {
                 return [makeRun(node.value, state)];
             }
-            return [];
+            throw new Error(`${state.region ? `${state.region}: ` : ""}"${node.type}" inside text isn't supported.`);
     }
 }
 export function walkPhrasingChildren(children, state) {

package/dist/markdown/schema/themeConfigSchema.d.ts

@@ -6,8 +6,8 @@ export declare const ThemeConfigSchema: z.ZodObject<{
         slideNumber: z.ZodNumber;
         description: z.ZodOptional<z.ZodString>;
         variant: z.ZodOptional<z.ZodEnum<{
-            light: "light";
-            dark: "dark";
+            readonly Light: "light";
+            readonly Dark: "dark";
         }>>;
         parameters: z.ZodArray<z.ZodObject<{
             shapeName: z.ZodString;
@@ -40,15 +40,6 @@ export declare const ThemeConfigSchema: z.ZodObject<{
             required: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
-    assets: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
-        path: z.ZodString;
-        type: z.ZodEnum<{
-            icon: "icon";
-            image: "image";
-            background: "background";
-        }>;
-        description: z.ZodString;
-    }, z.core.$strict>>>;
     template: z.ZodString;
     mermaid: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         primary: z.ZodString;

package/dist/markdown/schema/themeConfigSchema.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { basename, dirname } from "node:path";
 import * as z from "zod";
-import { AcceptType, AssetType, Variant } from "../types.js";
+import { AcceptType, Variant } from "../types.js";
 import { strict } from "./strict.js";
 /**
  * Fail-fast runtime validation for a `theme.json`. The hand-written types in
@@ -16,13 +16,12 @@ import { strict } from "./strict.js";
  *
  * Every object is a `strictObject` so an unknown key throws instead of being
  * silently dropped — strictness does NOT propagate, so each nested object is
- * independently strict. The two exceptions are the `AssetCatalog` and `mermaid`
- * records, whose keys are user-defined category/asset/variant names (a
- * `z.record`, open by design); strictness lands on their leaf entries.
+ * independently strict. The exception is the `mermaid` record, whose keys are
+ * user-defined variant names (a `z.record`, open by design); strictness lands on
+ * its entries.
  */
-// Reuse the const-object enums as runtime values — no third copy of the literals.
-const assetTypeSchema = z.enum(Object.values(AssetType));
-const variantSchema = z.enum(Object.values(Variant));
+// Reuse the const-object enum as runtime values — no third copy of the literals.
+const variantSchema = z.enum(Variant);
 // A table specimen's repeatable row range: `[start, end]`, 0-based inclusive,
 // non-negative integers. The range is validated against the specimen's actual row
 // count at fill time, where the row count is known.
@@ -35,14 +34,6 @@ const FrameSchema = strict({
     cx: z.number(),
     cy: z.number(),
 });
-const AssetEntrySchema = strict({
-    path: z.string(),
-    type: assetTypeSchema,
-    description: z.string(),
-});
-// AssetCatalog: `{ category: { name: AssetEntry } }`. The two record levels are
-// OPEN (names are user-defined); only the leaf entry is strict.
-const AssetCatalogSchema = z.record(z.string(), z.record(z.string(), AssetEntrySchema));
 const MermaidVariantSchema = strict({
     primary: z.string(),
     primaryContrast: z.string(),
@@ -106,7 +97,6 @@ const LayoutSchema = strict({
 });
 export const ThemeConfigSchema = strict({
     layouts: z.array(LayoutSchema),
-    assets: AssetCatalogSchema,
     template: z.string(),
     mermaid: MermaidConfigSchema.optional(),
     fonts: z.array(ThemeFontSchema).optional(),

package/dist/markdown/slideParser.d.ts

@@ -8,6 +8,8 @@ export interface ParsedDocument {
     slides: RawSlide[];
 }
 export declare function parseSlideDocument(source: string): ParsedDocument;
+/** True for a parsed YAML document that is a mapping (`key: value` pairs). */
+export declare function isYamlMapping(parsed: unknown): parsed is Record<string, unknown>;
 export declare class FrontmatterParseError extends Error {
     constructor(slideIndex: number, yamlSource: string, cause: unknown);
 }

package/dist/markdown/slideParser.js

@@ -15,12 +15,16 @@ export function parseSlideDocument(source) {
 // GLOBAL FRONTMATTER
 // ============================================
 const GLOBAL_FM_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+/** True for a parsed YAML document that is a mapping (`key: value` pairs). */
+export function isYamlMapping(parsed) {
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed);
+}
 function extractGlobalFrontmatter(source) {
     const match = source.match(GLOBAL_FM_RE);
     if (!match)
         return { global: {}, rest: source };
     const parsed = parseYaml(match[1]);
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+    if (isYamlMapping(parsed)) {
         return {
             global: parsed,
             rest: source.slice(match[0].length),
@@ -142,9 +146,8 @@ function parseFrontmatter(yaml, slideIndex) {
         return {};
     try {
         const result = parseYaml(yaml);
-        if (result && typeof result === "object" && !Array.isArray(result)) {
+        if (isYamlMapping(result))
             return result;
-        }
     }
     catch (err) {
         throw new FrontmatterParseError(slideIndex, yaml, err);

package/dist/markdown/types.d.ts

@@ -2,31 +2,6 @@ import type { RootContent } from "mdast";
 import { type BodyRows, type Frame, type ImageFill, type TableFill, type TemplateFill, type TextFill } from "../engine/index.js";
 import type { MermaidConfig } from "./blocks/mermaidTheme.js";
 export type { BodyRows };
-/**
- * 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`
- * to a fully-qualified filesystem path and wraps it as an ImageFill before
- * handing the deck to the engine.
- */
-export type AssetEntry = {
-    path: string;
-    /** Required — a missing type is a fail-fast error. */
-    type: AssetType;
-    description: string;
-};
-/** Two-level catalog: `{ category: { name: AssetEntry } }`. */
-export type AssetCatalog = Record<string, Record<string, AssetEntry>>;
 /**
  * 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
@@ -68,7 +43,7 @@ export type EngineFill = TextFill | TableFill | ImageFill | TemplateFill;
 export type BlockFill = TextFill | TableFill | ImageFill;
 /**
  * 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
+ * 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`), not the
@@ -79,10 +54,11 @@ export type BlockFill = TextFill | TableFill | ImageFill;
  * imports the per-kind handlers, so the reverse would cycle.
  */
 export type BlockContext = {
-    resolveAssetRef: (ref: string) => ImageFill;
     layoutName: string;
     slideNo: number;
     source: string;
+    /** Where the region sits, for the author: the prefix block handlers put on their errors. */
+    region: string;
     config: CompilerConfig;
     /**
      * The current layout's tonal surface, threaded from its `variant`. The code
@@ -251,7 +227,6 @@ export type ThemeFont = {
  */
 export type CompilerThemeConfig = {
     layouts: CompilerLayout[];
-    assets: AssetCatalog;
     template: string;
     mermaid?: MermaidConfig;
     /**
@@ -276,7 +251,7 @@ export type CompilerThemeConfig = {
 };
 /**
  * A theme as loaded from disk: its validated config plus the directory it
- * lives in, which the catalog's relative asset paths resolve against.
+ * lives in, which its relative paths (template, fonts) resolve against.
  */
 export type LoadedTheme = CompilerThemeConfig & {
     rootDir: string;

package/dist/markdown/types.js

@@ -1,15 +1,4 @@
 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",
-};
 // ── AcceptType discriminator (what a slot accepts) ────────────────────────────
 /**
  * The engine content types a slot may `accept`. A subset of the engine's

package/{theme-package/syntax.md → docs/markdown.md}

@@ -1,11 +1,19 @@
 # Markdown Syntax Reference
 
-This document covers the detailed syntax for writing slide content in tycoslide deck files. For an overview of how to create slides, see [SKILL.md](SKILL.md).
+This document covers the detailed syntax for writing slide content in tycoslide deck files.
 
-> **Every layout, parameter, and slot name in the examples below is a placeholder.** Your theme's real names live in `manifest.json` — read it first, and never assume a name shown here (`Body`, `TwoColumn`, `hero`, `::left::`, etc.) exists in your theme.
+> **Every layout, parameter, and slot name in the examples below is a placeholder.** Your theme's real names live in `theme.json` — read it first, and never assume a name shown here (`Body`, `TwoColumn`, `hero`, `::left::`, etc.) exists in your theme.
 
 ---
 
+## File structure
+
+A deck file has three parts:
+
+1. **Global frontmatter** (required) -- the first `---`-delimited block.
+2. **Slides** -- each begins with a `---` separator. A slide's frontmatter sits between `---` delimiters. Body content follows the closing `---`.
+3. **Slide separators** -- a `---` on its own line separates slides.
+
 ## Global frontmatter
 
 Every deck file starts with a global frontmatter block declaring the theme:
@@ -20,6 +28,23 @@ theme: ./theme.json
 
 The output `.pptx` is written next to the deck file, named after it (`deck.md` → `deck.pptx`).
 
+## Slide frontmatter
+
+Every slide must have a `layout:` key. All other frontmatter keys map 1:1 to the layout's **parameters**. A value containing a colon-then-space must be quoted -- `title: "The change: compute on the difference"` -- or YAML reads it as a second key and the build fails.
+
+```yaml
+---
+layout: Body
+title: Key Achievements
+subtitle: This Quarter
+---
+```
+
+- `layout` is required and consumed by the compiler (not forwarded as content).
+- All other frontmatter keys fill parameters: `title` fills the `title` parameter, `subtitle` fills the `subtitle` parameter, etc.
+- Slots (accepting `text`, `table`, `image`) are filled by body regions, not frontmatter -- see below.
+- A slide may also carry a `notes:` block in frontmatter -- plain-text speaker notes for the slide's notes page (see [Speaker notes](#speaker-notes)). It is slide-level metadata, not a parameter or slot.
+
 ---
 
 ## Body content
@@ -28,7 +53,7 @@ A slide's body is split into regions with `::key::` markers. Each region fills t
 
 ```markdown
 ---
-layout: Body            # ← placeholder; use a real layout from your manifest.json
+layout: Body            # ← placeholder; use a real layout from your theme
 title: Key Achievements
 ---
 
@@ -85,30 +110,15 @@ Content after a marker goes to the slot matching that name. The marker names mus
 
 ---
 
-## Parameters and slots (in `manifest.json`)
-
-A layout advertises two kinds of author-facing input, split by one rule: **a parameter is one value on a frontmatter line; a slot is a multi-line region in the body** (a `::key::` region). In `manifest.json` each layout carries two lists, `parameters` and `slots`:
+## Parameters and slots
 
-```jsonc
-{
-  "name": "Feature with code",
-  "parameters": [
-    { "key": "title",    "type": "template" },
-    { "key": "subtitle", "type": "template" },
-    { "key": "logo",     "type": "image", "required": true }
-  ],
-  "slots": [
-    { "key": "body", "accepts": ["text"] },
-    { "key": "diagram", "accepts": ["image"] }
-  ]
-}
-```
+A layout advertises two kinds of author-facing input, split by one rule: **a parameter is one value on a frontmatter line; a slot is a multi-line region in the body** (a `::key::` region).
 
 ### Parameter types (frontmatter lines)
 
 Fill a parameter by putting a value under its key in the slide's frontmatter.
 
-- **`template`** -- a shape whose existing runs are walked and replaced in place, preserving each run's style. Behind the scenes each text shape carries one `template` string with `{key}` placeholders (e.g. `{title}`, or `{name}\n{jobTitle}` for a two-line credits shape), but you never see the template: the manifest advertises **one key per placeholder**, and you fill each key as a plain scalar in frontmatter. A single-placeholder title shape gives you one key:
+- **`template`** -- a shape whose existing runs are walked and replaced in place, preserving each run's style. Behind the scenes each text shape carries one `template` string with `{key}` placeholders (e.g. `{title}`, or `{name}\n{jobTitle}` for a two-line credits shape), but you never see the template: the layout advertises **one key per placeholder**, and you fill each key as a plain scalar in frontmatter. A single-placeholder title shape gives you one key:
   ```yaml
   title: Q3 Results
   ```
@@ -120,7 +130,7 @@ Fill a parameter by putting a value under its key in the slide's frontmatter.
   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.
 ### Body content shapes
 
-Fill a slot by writing a `::key::` region in the body; the marker maps to the slot with that `key`. A slot's manifest entry lists which content types it `accepts` (`text`, `table`, `image`) -- write content whose shape matches one of them:
+Fill a slot by writing a `::key::` region in the body; the marker maps to the slot with that `key`. A slot lists which content types it `accepts` (`text`, `table`, `image`) -- write content whose shape matches one of them:
 
 - **text** (slots that accept `text`) -- markdown paragraphs and bullets, rebuilt from the template's specimen paragraph styles. A fenced code block also routes here:
   ````markdown
@@ -134,13 +144,13 @@ Fill a slot by writing a `::key::` region in the body; the marker maps to the sl
   ````
   The language tag (e.g. `sql`, `python`, `typescript`) is required -- it drives syntax highlighting, using the theme's `codeTheme` (set once in `theme.json`, not per slot). Colors are applied as native text runs in the output, not images.
 - **table** (slots that accept `table`) -- a GFM table. Write it in the slot region between `|`-delimited headers and rows; cells inherit inline formatting (bold, italic, links).
-- **image** (slots that accept `image`) -- a picture, written as `![]($category.name)` for one from the theme's asset catalog, or `![](path/to/file.png)` for a file relative to the deck:
+- **image** (slots that accept `image`) -- an image, written as `![alt](path "options")` with the path relative to the deck:
   ```markdown
   ::logo::
 
-  ![]($brand.primaryDarkWordmark)
+  ![Acme Corp logo](assets/acme-logo.png "fit: contain")
   ```
-  The categories and names are cataloged in `assets.json`. How the picture is scaled and cropped comes from 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. A file path has no catalog entry, so it is always fitted as `image`; put a picture in the catalog when it needs another fit or when agents should be able to find it. A fenced `mermaid` block also fills an image slot, rendering to a themed PNG (see below).
+  The alt text becomes the image's alt text in PowerPoint; leave it empty for an image that is only decoration. The title is optional and holds image options as YAML. The only option is `fit`, one of `contain` (the default, which shows the whole image and never crops), `cover` (fills the frame and center-crops) or `scale-down` (shows the whole image and never enlarges it). Anything else in the title fails the build. A fenced `mermaid` block also fills an image slot, rendering to a themed PNG (see below).
 
 ---
 
@@ -205,9 +215,8 @@ The theme owns all styling. These directives are rejected at build time:
 
 Each parameter or slot in the layout definition may declare:
 - **`accepts`** (slots, required) -- an array of `text`, `table`, `image`.
-- **`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.
+- **`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).
 - **optional (the default)** -- a parameter or slot you leave unfilled is dropped from the slide (its shape is removed), so a layout with numbered slots (e.g. up to six sections, up to four stats) renders only the ones you fill.
-- **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).
 
 Each layout also declares a `slideNumber` pointing at the physical slide in the theme's template -- unique per layout (one layout maps to one physical slide).
 
@@ -247,6 +256,29 @@ subtitle: Advanced Topics
 
 ---
 
+## Build
+
+Build the deck (replace `<deck.md>` with your deck file):
+
+```bash
+npx tycoslide build <deck.md>
+```
+
+Common errors and fixes:
+
+| Error | Fix |
+|-------|-----|
+| `unknown layout "xyz"` | Check layout names in `theme.json` |
+| A parameter or slot didn't fill | Use the key names the layout declares -- parameters in frontmatter, slots as body regions |
+| YAML parse error | Fix the YAML syntax in the slide's frontmatter |
+| `image "…" not found at …` | Check the path; it is relative to the deck file |
+| `is not a set of options` | The image title holds options like `"fit: contain"`; put a description in the alt text |
+| `Skipped setting relation target` | The asset image couldn't be placed; check the path and file |
+| `forbidden style directive` | Remove `style`, `classDef`, `linkStyle`, or `%%{init}` from your mermaid block -- use `class` for grouping instead |
+| `no "mermaid" block` | The theme has no mermaid color config -- add a `mermaid` section to theme.json |
+
+---
+
 ## Full Example
 
 ```markdown
@@ -303,5 +335,5 @@ title: Office Map
 
 ::hero::
 
-![]($images.officeFloorPlan)
+![Office floor plan with meeting rooms marked](assets/office-floor-plan.png)
 ```