@tycoworks/tycoslide 0.16.1 → 0.17.1

package/README.md

@@ -35,4 +35,4 @@ Node 23.6 or later. Mermaid diagrams need Chrome on the machine; tycoslide finds
 
 ## Thanks
 
-tycoslide was inspired by [pptx-automizer](https://github.com/singerla/pptx-automizer), which it uses under the hood, and by [Slidev](https://sli.dev) and its markdown slides.
+tycoslide was inspired by [pptx-automizer](https://github.com/singerla/pptx-automizer), which it uses under the hood, and by [Slidev](https://sli.dev)'s way of writing slides in markdown.

package/dist/agents/commands.js

@@ -1,11 +1,10 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { basename, posix, resolve } from "node:path";
 import { loadThemeConfig } from "../index.js";
-import { loadAssetCatalog } from "./catalog.js";
 import { extractTemplate, summarizeExtraction } from "./extract.js";
 import { ASSETS_DIR, ASSETS_FILE, MANIFEST_FILE, PACKAGE_JSON, SKILL_FILE, SKILL_TEMPLATE_FILE, SKILL_ZIP_EXT, TEMPLATE_FILE, THEME_CONFIG, THEME_PACKAGE_DIR, } from "./files.js";
 import { generateManifest } from "./manifest.js";
-import { renameSkill, skillPackageJson, zipDir } from "./skill.js";
+import { loadAssetCatalog, personalizeSkill, skillPackageJson, zipDir } from "./skill.js";
 /** The CLI's line for something written, with an optional note on what it holds. */
 function wrote(target, detail) {
     console.log(detail ? `WROTE ${target}  ${detail}` : `WROTE ${target}`);
@@ -28,7 +27,7 @@ export function registerAgentCommands(program, tool) {
         const skillName = basename(themePkg.name);
         let skillMd;
         try {
-            skillMd = renameSkill(readFileSync(skillMdPath, "utf-8"), skillName);
+            skillMd = personalizeSkill(readFileSync(skillMdPath, "utf-8"), skillName, themePkg.description);
         }
         catch (err) {
             throw new Error(`${skillMdPath}: ${err.message}`);

package/dist/agents/inventory.d.ts

@@ -52,8 +52,8 @@ export type InventoryShape = {
     rows?: number;
     cols?: number;
     /**
-     * The start of the shape's text, with `¶` between paragraphs and `↵` for line
-     * breaks: where a parameter template puts `\n`.
+     * The shape's text, with `¶` between paragraphs and `↵` for line breaks,
+     * either of which a parameter template writes as `\n`.
      */
     text: string;
 };

package/dist/agents/inventory.js

@@ -87,6 +87,8 @@ const Attr = {
     X: "x",
     Y: "y",
     TEXT_BOX: "txBox",
+    WIDTH: "w",
+    HEIGHT: "h",
 };
 /** The twelve colour-scheme slots, in the order PowerPoint lists them. */
 export const SCHEME_SLOTS = [
@@ -298,7 +300,6 @@ const SHAPE_ELEMENTS = new Set([
 const GROUP_SEPARATOR = "/";
 const PARAGRAPH_MARK = "¶";
 const LINE_BREAK_MARK = "↵";
-const TEXT_PREVIEW_CHARS = 80;
 const TEXT_BOX_ON = "1";
 /** A placeholder with no `type` is a body placeholder. */
 const DEFAULT_PLACEHOLDER_TYPE = "body";
@@ -325,14 +326,14 @@ async function readShapes(presentation, parts) {
             }
         }
     }
-    // Set fields only, in a fixed order, and the text cut to a preview.
+    // Set fields only, in a fixed order.
     return found.map(({ shape: { name, kind, frame, frameFrom, rows, cols, text } }) => ({
         name,
         kind,
         ...(frame && { frame }),
         ...(frameFrom && { frameFrom }),
         ...(rows !== undefined && { rows, cols }),
-        text: Array.from(text).slice(0, TEXT_PREVIEW_CHARS).join(""),
+        text,
     }));
 }
 function walkShapes(container, prefix) {
@@ -349,7 +350,7 @@ function describeShape(el, prefix) {
     return {
         name: prefix + (find(nonVisualProps(el), Tag.NON_VISUAL_PROPS)?.getAttribute(Attr.NAME) ?? ""),
         kind: shapeKind(el, table),
-        frame: shapeFrame(el),
+        frame: table ? tableFrame(el, table) : shapeFrame(el),
         rows: table && elementChildren(table, Tag.TABLE_ROW).length,
         cols: table && elementChildren(find(table, Tag.TABLE_GRID), Tag.GRID_COLUMN).length,
         text: el.tagName === Tag.GROUP ? "" : shapeText(el),
@@ -371,13 +372,17 @@ function shapeKind(el, table) {
             return ShapeKind.Other;
     }
 }
-/** The shape's text, `¶` between paragraphs and `↵` for line breaks, whitespace collapsed. */
+/**
+ * The shape's text, `¶` between paragraphs and `↵` for line breaks, whitespace
+ * collapsed. Runs join as PowerPoint shows them, with no space added between: a
+ * run is a stretch of one style, not a word.
+ */
 function shapeText(el) {
     const paragraphs = collectElements(el, Tag.PARAGRAPH).map((paragraph) => elementChildren(paragraph)
         .flatMap((child) => child.tagName === Tag.LINE_BREAK
-        ? [LINE_BREAK_MARK]
+        ? [` ${LINE_BREAK_MARK} `]
         : collectElements(child, Tag.TEXT).map((text) => text.textContent ?? ""))
-        .join(" ")
+        .join("")
         .split(/\s+/)
         .filter(Boolean)
         .join(" "));
@@ -399,6 +404,23 @@ function shapeFrame(el) {
         cy: Number(extent.getAttribute(Attr.CY)),
     };
 }
+/**
+ * A table's frame: where its graphic frame puts it, at the size its column widths
+ * and row heights give it. PowerPoint draws a table at that size, rows growing
+ * taller when their text needs it, and some tools (Google Slides among them)
+ * write a placeholder size on the frame.
+ */
+function tableFrame(el, table) {
+    const frame = shapeFrame(el);
+    if (!frame)
+        return undefined;
+    const total = (els, attr) => els.reduce((sum, e) => sum + Number(e.getAttribute(attr) || 0), 0);
+    return {
+        ...frame,
+        cx: total(elementChildren(find(table, Tag.TABLE_GRID), Tag.GRID_COLUMN), Attr.WIDTH) || frame.cx,
+        cy: total(elementChildren(table, Tag.TABLE_ROW), Attr.HEIGHT) || frame.cy,
+    };
+}
 function nonVisualProps(el) {
     return elementChildren(el).find((child) => child.tagName.startsWith(NON_VISUAL_PREFIX));
 }

package/dist/agents/manifest.js

@@ -1,4 +1,4 @@
-import { templateKeys, } from "../index.js";
+import { AcceptType, templateKeys, } from "../index.js";
 import { ASSETS_FILE, jsonFile } from "./files.js";
 /**
  * Flatten a compiler parameter to the manifest entries advertised to AI authors.
@@ -15,6 +15,9 @@ function stripParameter(param) {
 }
 function stripSlot(slot) {
     const result = { key: slot.key, accepts: slot.accepts.map((b) => b.type) };
+    for (const block of slot.accepts)
+        if (block.type === AcceptType.Image)
+            result.fit = block.fit;
     if (slot.required)
         result.required = true;
     return result;

package/dist/agents/skill.d.ts

@@ -1,5 +1,16 @@
+import * as z from "zod";
 import { type CompilerThemeConfig } from "../index.js";
-import type { AssetCatalog } from "./catalog.js";
+declare const AssetCatalogSchema: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
+    path: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strict>>>;
+export type AssetCatalog = z.infer<typeof AssetCatalogSchema>;
+/**
+ * Read and validate a theme's image catalog, `assets.json`: what a deck-writing
+ * agent searches and copies images from, and what a packaged skill archives. It
+ * is authored with the theme and required; a theme with no images has `{}`.
+ */
+export declare function loadAssetCatalog(themeDir: string): AssetCatalog;
 /**
  * Pack `paths` (theme-relative, POSIX) into one archive, reading each through
  * `read`. Entries keep their declared paths, so expanding reproduces the layout
@@ -7,12 +18,14 @@ import type { AssetCatalog } from "./catalog.js";
  */
 export declare function packAssets(paths: string[], read: (rel: string) => Buffer): Promise<Buffer>;
 /**
- * Rewrite the `name:` value in a SKILL.md's leading YAML frontmatter so the
- * packaged skill is named after the consuming theme, not the source template.
- * Only the leading `---`…`---` block is touched; the body is left byte-for-byte.
- * Throws if there is no frontmatter or no `name:` line — the caller names the file.
+ * Make the skill template the theme's own: its frontmatter `name:` and its title
+ * heading become the theme's name, and the theme's `description`, when it has
+ * one, leads the skill's description, so an agent with several theme skills can
+ * tell them apart. The rest of the body is left byte-for-byte. Throws if there is
+ * no frontmatter, no `name:` line, or no folded description to lead — the caller
+ * names the file.
  */
-export declare function renameSkill(md: string, name: string): string;
+export declare function personalizeSkill(md: string, name: string, description?: string): string;
 /**
  * The `package.json` a packaged skill installs from — deliberately NOT the theme's
  * own. A theme repo's manifest is a development document: it may carry scripts,
@@ -41,3 +54,4 @@ export declare function skillPackageJson(theme: Record<string, unknown>, engine:
  * catalog declares but that is missing is an error.
  */
 export declare function zipDir(rootDir: string, folderName: string, config: CompilerThemeConfig, catalog: AssetCatalog, themeFiles: string[], generated: Record<string, string>): Promise<Buffer>;
+export {};

package/dist/agents/skill.js

@@ -1,8 +1,37 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import JSZip from "jszip";
-import { TEMPLATE_DIR } from "../index.js";
-import { ASSETS_ARCHIVE, jsonFile } from "./files.js";
+import * as z from "zod";
+import { strict, TEMPLATE_DIR } from "../index.js";
+import { ASSETS_ARCHIVE, ASSETS_FILE, jsonFile } from "./files.js";
+/** One image a theme offers deck authors: where it is, and what it shows. */
+const AssetEntrySchema = strict({
+    path: z.string(),
+    description: z.string(),
+});
+// `{ category: { name: entry } }`. Both record levels are open (the names are the
+// theme's own); only the entry is strict.
+const AssetCatalogSchema = z.record(z.string(), z.record(z.string(), AssetEntrySchema));
+/**
+ * Read and validate a theme's image catalog, `assets.json`: what a deck-writing
+ * agent searches and copies images from, and what a packaged skill archives. It
+ * is authored with the theme and required; a theme with no images has `{}`.
+ */
+export function loadAssetCatalog(themeDir) {
+    const path = join(themeDir, ASSETS_FILE);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        throw new Error(`Image catalog not found or invalid JSON: ${path}`);
+    }
+    const result = AssetCatalogSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(`${ASSETS_FILE}: invalid image catalog\n${z.prettifyError(result.error)}`);
+    }
+    return result.data;
+}
 /** Entries are stored, not deflated: assets are already-compressed images. */
 const NO_COMPRESSION = { type: "nodebuffer", compression: "STORE" };
 /**
@@ -18,19 +47,32 @@ export async function packAssets(paths, read) {
 }
 const FRONTMATTER = /^---\n([\s\S]*?)\n---/;
 const NAME_LINE = /^name:[ \t]*.*$/m;
+/** The folded `description: >` opener; the description's lines follow it, indented. */
+const FOLDED_DESCRIPTION_LINE = /^description:[ \t]*>[ \t]*$/m;
+const DESCRIPTION_INDENT = "  ";
+const TITLE_HEADING = /^# .*$/m;
 /**
- * Rewrite the `name:` value in a SKILL.md's leading YAML frontmatter so the
- * packaged skill is named after the consuming theme, not the source template.
- * Only the leading `---`…`---` block is touched; the body is left byte-for-byte.
- * Throws if there is no frontmatter or no `name:` line — the caller names the file.
+ * Make the skill template the theme's own: its frontmatter `name:` and its title
+ * heading become the theme's name, and the theme's `description`, when it has
+ * one, leads the skill's description, so an agent with several theme skills can
+ * tell them apart. The rest of the body is left byte-for-byte. Throws if there is
+ * no frontmatter, no `name:` line, or no folded description to lead — the caller
+ * names the file.
  */
-export function renameSkill(md, name) {
+export function personalizeSkill(md, name, description) {
     const block = md.match(FRONTMATTER);
     if (!block)
         throw new Error("SKILL.md has no YAML frontmatter block");
     if (!NAME_LINE.test(block[1]))
         throw new Error('SKILL.md frontmatter has no "name:" line');
-    return md.replace(block[0], block[0].replace(NAME_LINE, `name: ${name}`));
+    let frontmatter = block[0].replace(NAME_LINE, `name: ${name}`);
+    if (description) {
+        if (!FOLDED_DESCRIPTION_LINE.test(frontmatter)) {
+            throw new Error('SKILL.md frontmatter has no folded "description: >" to lead');
+        }
+        frontmatter = frontmatter.replace(FOLDED_DESCRIPTION_LINE, (line) => `${line}\n${DESCRIPTION_INDENT}${description}`);
+    }
+    return frontmatter + md.slice(block[0].length).replace(TITLE_HEADING, `# ${name}`);
 }
 /**
  * Files a packaged skill needs beyond the theme's own declarations. Only the

package/dist/engine/dom.d.ts

@@ -30,6 +30,8 @@ export declare const Tag: {
     readonly BLIP_FILL: "p:blipFill";
     readonly NON_VISUAL_PROPS: "p:cNvPr";
     readonly SPACE_BEFORE: "a:spcBef";
+    readonly LINE_SPACING: "a:lnSpc";
+    readonly OUTLINE: "a:ln";
     readonly HLINK_CLICK: "a:hlinkClick";
     readonly RELATIONSHIP: "Relationship";
     readonly TABLE: "a:tbl";

package/dist/engine/dom.js

@@ -30,6 +30,8 @@ export const Tag = {
     BLIP_FILL: "p:blipFill",
     NON_VISUAL_PROPS: "p:cNvPr",
     SPACE_BEFORE: "a:spcBef",
+    LINE_SPACING: "a:lnSpc",
+    OUTLINE: "a:ln",
     HLINK_CLICK: "a:hlinkClick",
     RELATIONSHIP: "Relationship",
     TABLE: "a:tbl",
@@ -106,6 +108,16 @@ export function childrenByTag(parent, tagName) {
     }
     return out;
 }
+/**
+ * Insert `child` as `parent`'s first child, or right after a leading `leadingTag`
+ * child when there is one. The schema puts a run's fill after only its outline, and
+ * a paragraph's space before after only its line spacing; PowerPoint reports a file
+ * with either out of place as needing repair.
+ */
+function insertAfterLeading(parent, child, leadingTag) {
+    const leading = childrenByTag(parent, leadingTag)[0];
+    parent.insertBefore(child, leading ? leading.nextSibling : parent.firstChild);
+}
 export function detach(node) {
     if (node?.parentNode)
         node.parentNode.removeChild(node);
@@ -225,7 +237,7 @@ export function setRichRuns(para, runs, relation) {
             const srgbClr = para.ownerDocument.createElement(Tag.SRGB_CLR);
             srgbClr.setAttribute(Attr.VALUE, run.color);
             solidFill.appendChild(srgbClr);
-            rPr.appendChild(solidFill);
+            insertAfterLeading(rPr, solidFill, Tag.OUTLINE);
         }
         if (run.link && relation) {
             let rPr = clone.getElementsByTagName(Tag.RUN_PROPS)[0];
@@ -266,9 +278,27 @@ function paragraphLevel(paragraph) {
     const lvl = ppr?.getAttribute(Attr.LEVEL);
     return lvl ? Number(lvl) || 0 : 0;
 }
+/** A paragraph's `<a:spcBef>`, or null when it has none. */
+function spaceBefore(paragraph) {
+    return paragraph.getElementsByTagName(Tag.PARA_PROPS)[0]?.getElementsByTagName(Tag.SPACE_BEFORE)[0] ?? null;
+}
+/** Give the paragraph a copy of `spacing` as its space before, or none when null. */
+function setSpaceBefore(paragraph, spacing) {
+    const ppr = paragraph.getElementsByTagName(Tag.PARA_PROPS)[0];
+    if (!ppr)
+        return;
+    for (const old of childrenByTag(ppr, Tag.SPACE_BEFORE))
+        ppr.removeChild(old);
+    if (spacing)
+        insertAfterLeading(ppr, spacing.cloneNode(true), Tag.LINE_SPACING);
+}
 function harvestStyles(specimen) {
     const bullets = new Map();
     let paras = null;
+    // Level → the space before a bullet that follows another, taken from the
+    // specimen's second bullet at that level. The first often carries extra space
+    // to set the list off from the text above it.
+    const followOn = new Map();
     for (const p of specimen) {
         const kind = paragraphBulletKind(p);
         const lvl = paragraphLevel(p);
@@ -280,13 +310,15 @@ function harvestStyles(specimen) {
         if (kind === "bullet") {
             if (!bullets.has(lvl))
                 bullets.set(lvl, bucket);
+            else if (!followOn.has(lvl))
+                followOn.set(lvl, spaceBefore(p));
         }
         else {
             if (paras == null)
                 paras = bucket;
         }
     }
-    return { bullets, paras };
+    return { bullets, paras, followOn };
 }
 function specimenBulletPara(specimen, level) {
     for (const p of specimen) {
@@ -317,7 +349,7 @@ export function rebuildParagraphs(shape, paragraphs, startIndex, relation, shape
     if (specimen.length === 0) {
         throw new Error(`Shape "${shapeName}": startAt ${startIndex} is past the last paragraph (shape has ${allParas.length}).`);
     }
-    const { bullets, paras } = harvestStyles(specimen);
+    const { bullets, paras, followOn } = harvestStyles(specimen);
     const maxBulletLevel = bullets.size > 0 ? Math.max(...bullets.keys()) : -1;
     const pickBullet = (lvl) => {
         if (bullets.has(lvl))
@@ -329,18 +361,7 @@ export function rebuildParagraphs(shape, paragraphs, startIndex, relation, shape
     const plainBucket = paras ?? bullets.get(0) ?? null;
     const firstBulletKey = bullets.has(0) ? 0 : maxBulletLevel;
     const firstBullet = firstBulletKey >= 0 ? specimenBulletPara(specimen, firstBulletKey) : null;
-    const transitionSpcBef = firstBullet?.getElementsByTagName(Tag.PARA_PROPS)[0]?.getElementsByTagName(Tag.SPACE_BEFORE)[0] ?? null;
-    const applyTransitionSpacing = (paragraph) => {
-        if (!transitionSpcBef)
-            return;
-        const ppr = paragraph.getElementsByTagName(Tag.PARA_PROPS)[0];
-        if (!ppr)
-            return;
-        const old = ppr.getElementsByTagName(Tag.SPACE_BEFORE)[0];
-        if (old)
-            ppr.removeChild(old);
-        ppr.appendChild(transitionSpcBef.cloneNode(true));
-    };
+    const transitionSpcBef = firstBullet ? spaceBefore(firstBullet) : null;
     for (const p of specimen)
         detach(p);
     const doc = shape.ownerDocument;
@@ -362,8 +383,10 @@ export function rebuildParagraphs(shape, paragraphs, startIndex, relation, shape
         const seedRun = buildRun(doc, bucket?.rPr ?? null, "");
         const newPara = buildParagraph(doc, bucket?.pPr ?? null, seedRun);
         maybeOverrideLevel(newPara, isBullet ? effectiveLvl : null);
-        if (!isBullet && prevWasBullet)
-            applyTransitionSpacing(newPara);
+        if (!isBullet && prevWasBullet && transitionSpcBef)
+            setSpaceBefore(newPara, transitionSpcBef);
+        if (isBullet && prevWasBullet && followOn.has(effectiveLvl))
+            setSpaceBefore(newPara, followOn.get(effectiveLvl));
         setRichRuns(newPara, para.runs, relation);
         txBody.appendChild(newPara);
         prevWasBullet = isBullet;

package/dist/engine/fillers/filler.d.ts

@@ -15,14 +15,15 @@
  * Element-level geometry lives in the `fillX` primitives; cross-shape concerns
  * (media pre-swap for images) live in the callbacks here.
  */
-import { type BodyRows, SlotType } from "../types.js";
+import { type BodyRows, type ImageFit, SlotType } from "../types.js";
 /**
  * The shape a filler targets — a union discriminated by `type` (mirroring the
  * `Block` variants), so each filler's callback sees only its own specimen
  * options. Every target carries a `shapeName` and a human `label` for
  * diagnostics (the author-facing "slide N, layout …, slot …" a filler prints in
  * advisory warnings instead of the raw PPTX shape id); a text target may carry
- * `startAt`, and a table target carries its required `bodyRows` range.
+ * `startAt`, a table target carries its required `bodyRows` range, and an image
+ * target its required `fit`.
  */
 export type TemplateFillTarget = {
     type: typeof SlotType.Template;
@@ -45,6 +46,7 @@ export type ImageFillTarget = {
     type: typeof SlotType.Image;
     shapeName: string;
     label: string;
+    fit: ImageFit;
 };
 export type FillTarget = TemplateFillTarget | TextFillTarget | TableFillTarget | ImageFillTarget;
 /** A pptx-automizer element-modify callback: `(element, relation) => void`. */

package/dist/engine/fillers/filler.js

@@ -17,7 +17,7 @@
  */
 import { basename } from "node:path";
 import { ModifyImageHelper } from "pptx-automizer";
-import { SlotType } from "../types.js";
+import { SlotType, } from "../types.js";
 import { fillImage, isImageFill } from "./image.js";
 import { fillTable, isTableFill } from "./table.js";
 import { fillTemplate, isTemplateFill } from "./template.js";
@@ -44,7 +44,7 @@ const imageFiller = {
     matches: isImageFill,
     callbacks: (v, t) => [
         ModifyImageHelper.setRelationTarget(basename(v.path)),
-        (el) => fillImage(el, v, t.shapeName, t.label),
+        (el) => fillImage(el, v, t.shapeName, t.label, t.fit),
     ],
 };
 export const FILLERS = {

package/dist/engine/fillers/image.d.ts

@@ -2,7 +2,7 @@
  * Image fill — element-level picture geometry and alt text. The media swap
  * (pointing the blip relationship at the new file) is a slide-level modifier in
  * the ImageFiller (`fillers/filler.ts`); this module resolves the frame geometry
- * from the image's `ImageFit` (contain/cover/scale-down) and the source's true
+ * from the slot's `ImageFit` (contain/cover/scale-down) and the source's true
  * pixel size, and rewrites the picture's alt text for the new image.
  */
 import { type ImageFill, ImageFit } from "../types.js";
@@ -35,7 +35,7 @@ export type GeometryResult = {
     warnings: string[];
 };
 /**
- * Size a picture shape from its `ImageFit` (via `computeGeometry`): either write
+ * Size a picture shape by its slot's `fit` (via `computeGeometry`): either write
  * `<a:srcRect>` insets to fill-and-crop, or shrink the frame to the image's
  * aspect ratio and re-center (fit/letterbox). Advisory warnings from the
  * geometry pass go to `console.warn`. Also sets its alt text (`setAltText`).
@@ -43,7 +43,7 @@ export type GeometryResult = {
  * `image.path` is assumed absolute — the compiler / caller resolves it before the
  * ImageFill reaches the engine.
  */
-export declare function fillImage(shape: any, image: ImageFill, shapeName: string, label: string): void;
+export declare function fillImage(shape: any, image: ImageFill, shapeName: string, label: string, fit: ImageFit): void;
 /**
  * Pure fit geometry — no DOM, so it is trivially unit-testable in isolation.
  * `fit` picks the strategy: `cover` scales to the larger axis ratio and

package/dist/engine/fillers/image.js

@@ -2,7 +2,7 @@
  * Image fill — element-level picture geometry and alt text. The media swap
  * (pointing the blip relationship at the new file) is a slide-level modifier in
  * the ImageFiller (`fillers/filler.ts`); this module resolves the frame geometry
- * from the image's `ImageFit` (contain/cover/scale-down) and the source's true
+ * from the slot's `ImageFit` (contain/cover/scale-down) and the source's true
  * pixel size, and rewrites the picture's alt text for the new image.
  */
 import { readFileSync } from "node:fs";
@@ -23,7 +23,7 @@ const SEVERE_MISMATCH_FRACTION = 0.5;
 /** Warn once the image renders below this fraction of its native pixel size. */
 const MIN_SCALE = 0.2;
 /**
- * Size a picture shape from its `ImageFit` (via `computeGeometry`): either write
+ * Size a picture shape by its slot's `fit` (via `computeGeometry`): either write
  * `<a:srcRect>` insets to fill-and-crop, or shrink the frame to the image's
  * aspect ratio and re-center (fit/letterbox). Advisory warnings from the
  * geometry pass go to `console.warn`. Also sets its alt text (`setAltText`).
@@ -31,7 +31,7 @@ const MIN_SCALE = 0.2;
  * `image.path` is assumed absolute — the compiler / caller resolves it before the
  * ImageFill reaches the engine.
  */
-export function fillImage(shape, image, shapeName, label) {
+export function fillImage(shape, image, shapeName, label, fit) {
     const dims = imageSize(new Uint8Array(readFileSync(image.path)));
     if (!dims.width || !dims.height) {
         throw new Error(`Image shape "${shapeName}": could not read image dimensions from "${image.path}".`);
@@ -50,7 +50,7 @@ export function fillImage(shape, image, shapeName, label) {
         w: Number(ext.getAttribute(Attr.CX)),
         h: Number(ext.getAttribute(Attr.CY)),
     };
-    const { geometry, warnings } = computeGeometry(frame, dims.width, dims.height, image.fit);
+    const { geometry, warnings } = computeGeometry(frame, dims.width, dims.height, fit);
     for (const w of warnings)
         console.warn(`Image ${label}: ${w}`);
     if (geometry.placement === Placement.Crop) {

package/dist/engine/generate.js

@@ -272,7 +272,8 @@ function resolveBlock(step, slot, value) {
 }
 /**
  * The shape a filler targets, plus its diagnostic `label` and the intra-specimen
- * options a block declares: `startAt` (text) and the required `bodyRows` (table).
+ * options a block declares: `startAt` (text), the required `bodyRows` (table) and
+ * the required `fit` (image).
  * The block's `type` selects the matching target variant, so each filler's
  * callback sees only its own options.
  */
@@ -287,7 +288,7 @@ function targetOf(block, label) {
         case SlotType.Table:
             return { type: SlotType.Table, shapeName: block.shapeName, label, bodyRows: block.bodyRows };
         case SlotType.Image:
-            return { type: SlotType.Image, shapeName: block.shapeName, label };
+            return { type: SlotType.Image, shapeName: block.shapeName, label, fit: block.fit };
     }
 }
 /**

package/dist/engine/types.d.ts

@@ -99,17 +99,16 @@ export declare const ImageFit: {
 };
 export type ImageFit = (typeof ImageFit)[keyof typeof ImageFit];
 /**
- * Input to fillImage — a resolved image path plus its object-fit directive.
- * `path` must be absolute; the compiler resolves it (and maps the asset's
- * semantic type to a `fit`) before the ImageFill reaches the engine.
- * `alt` is the picture's accessibility description (`descr` on its
+ * Input to fillImage — a resolved image path and its alt text. How the image
+ * fills its shape is the slot's, from its image block's `fit`.
+ * `path` must be absolute; the compiler resolves it before the ImageFill reaches
+ * the engine. `alt` is the picture's accessibility description (`descr` on its
  * `<p:cNvPr>`); empty means none, and clears any description the placeholder
  * carried.
  */
 export type ImageFill = {
     type: typeof SlotType.Image;
     path: string;
-    fit: ImageFit;
     alt: string;
 };
 /** A shape's absolute position and size, in EMU — the slot's frame. */
@@ -128,7 +127,7 @@ export type Frame = {
  * otherwise it is transplanted from `sourceSlide` into the slot's frame. A text
  * block may pin `startAt` (leave the first N specimen paragraphs untouched); a
  * table block MUST declare its `bodyRows` range (the repeatable specimen rows);
- * a template or image block carries neither. `Template` reaches the engine only
+ * an image block MUST declare its `fit`; a template block carries none of them. `Template` reaches the engine only
  * via a frontmatter parameter (`paramToEngineSlot`), never as an author body block.
  *
  * Named `Block` — a kind of content the way an author thinks of it. Distinct
@@ -156,6 +155,7 @@ export type ImageBlock = {
     type: typeof SlotType.Image;
     sourceSlide: number;
     shapeName: string;
+    fit: ImageFit;
 };
 export type Block = TemplateBlock | TextBlock | TableBlock | ImageBlock;
 /**

package/dist/index.js

@@ -34,7 +34,7 @@ function compilerBlockToEngineBlock(b) {
         case AcceptType.Table:
             return { type: SlotType.Table, sourceSlide: b.sourceSlide, shapeName: b.shapeName, bodyRows: b.bodyRows };
         case AcceptType.Image:
-            return { type: SlotType.Image, sourceSlide: b.sourceSlide, shapeName: b.shapeName };
+            return { type: SlotType.Image, sourceSlide: b.sourceSlide, shapeName: b.shapeName, fit: b.fit };
     }
 }
 function slotToEngineSlot(slot) {

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

@@ -1,25 +1,2 @@
-import * as z from "zod";
 import { type BlockHandler } from "../types.js";
 export declare const IMAGE: BlockHandler;
-/**
- * Image options, carried in a markdown image's title: `![alt](src "fit: cover")`.
- * The title is a YAML mapping validated by this strict schema, so an unknown key
- * throws naming the valid ones, and adding an option is one line here.
- */
-declare const imageOptionsSchema: z.ZodObject<{
-    fit: z.ZodOptional<z.ZodEnum<{
-        readonly Contain: "contain";
-        readonly Cover: "cover";
-        readonly ScaleDown: "scale-down";
-    }>>;
-}, z.core.$strict>;
-export type ImageOptions = z.infer<typeof imageOptionsSchema>;
-/**
- * Parse an image title into its options. A missing or blank title means no
- * options. Anything else must be a YAML mapping of known options, or the build
- * fails with `where` (the slide, layout and slot) and a hint for the common
- * mistakes: a caption written in the title, a missing space after the colon, and
- * several options without flow braces.
- */
-export declare function parseImageTitle(title: string | null | undefined, where: string): ImageOptions;
-export {};

package/dist/markdown/blocks/image.js

@@ -1,71 +1,19 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { parse as parseYaml } from "yaml";
-import * as z from "zod";
-import { ImageFit, SlotType } from "../../engine/index.js";
+import { SlotType } from "../../engine/index.js";
 import { MdastType } from "../mdast.js";
-import { strict } from "../schema/strict.js";
-import { isYamlMapping } from "../slideParser.js";
 import { AcceptType } from "../types.js";
-/** The fit when the title gives none: the whole picture, never cropped. */
-const DEFAULT_FIT = ImageFit.Contain;
 export const IMAGE = {
     match: (node) => node.type === MdastType.Image,
     acceptType: AcceptType.Image,
     // `url` is a path relative to the deck. `alt` is the picture's alt text; the
     // parser flattens it to plain text, and an image written without any is "".
-    // `title` carries the image's options.
     compile: async (node, ctx) => {
-        const { url, alt, title } = node;
-        const options = parseImageTitle(title, ctx.region);
+        const { url, alt } = node;
         const path = resolve(ctx.config.deckDir, url);
         if (!existsSync(path)) {
             throw new Error(`${ctx.region}: image "${url}" not found at ${path}`);
         }
-        return { type: SlotType.Image, path, fit: options.fit ?? DEFAULT_FIT, alt: alt ?? "" };
+        return { type: SlotType.Image, path, alt: alt ?? "" };
     },
 };
-/**
- * Image options, carried in a markdown image's title: `![alt](src "fit: cover")`.
- * The title is a YAML mapping validated by this strict schema, so an unknown key
- * throws naming the valid ones, and adding an option is one line here.
- */
-const imageOptionsSchema = strict({
-    fit: z.enum(ImageFit).optional(),
-});
-/** The one-option title every hint quotes, so an author sees the expected form. */
-const EXAMPLE_TITLE = `"fit: ${ImageFit.Contain}"`;
-/** A colon run into the next character, as in `fit:contain`: YAML reads that as one string. */
-const COLON_WITHOUT_SPACE_RE = /:\S/;
-/**
- * Parse an image title into its options. A missing or blank title means no
- * options. Anything else must be a YAML mapping of known options, or the build
- * fails with `where` (the slide, layout and slot) and a hint for the common
- * mistakes: a caption written in the title, a missing space after the colon, and
- * several options without flow braces.
- */
-export function parseImageTitle(title, where) {
-    if (!title?.trim())
-        return {};
-    const prefix = `${where}: image title "${title}"`;
-    let parsed;
-    try {
-        parsed = parseYaml(title);
-    }
-    catch (err) {
-        // The yaml message's first line names the problem; the rest is a code frame.
-        const reason = err.message.split("\n")[0].replace(/:$/, "");
-        throw new Error(`${prefix} is not valid YAML (${reason}). Several options go in braces: "{key: value, key: value}".`);
-    }
-    if (!isYamlMapping(parsed)) {
-        const hint = typeof parsed === "string" && COLON_WITHOUT_SPACE_RE.test(parsed)
-            ? `put a space after the colon, as in ${EXAMPLE_TITLE}`
-            : `the title holds options like ${EXAMPLE_TITLE}; put a description in the alt text instead: ![${title}](…)`;
-        throw new Error(`${prefix} is not a set of options: ${hint}.`);
-    }
-    const result = imageOptionsSchema.safeParse(parsed);
-    if (!result.success) {
-        throw new Error(`${prefix}: ${z.prettifyError(result.error)}`);
-    }
-    return result.data;
-}

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

@@ -7,8 +7,8 @@ export declare const MERMAID_LANG = "mermaid";
  * Recognize a ```mermaid fenced block at a region's top level, folding it to an
  * Image fill, and compile it by rendering the definition to a PNG (cached under
  * `<rootDir>/.tycoslide-cache/mermaid/<hash>.png`, in the theme directory) and wrapping it as an
- * ImageFill. Fit is always `contain` — mermaid diagrams are shown in their
- * entirety — and a fence carries no alt text. Resolution is strict: the theme MUST carry a `mermaid` block, MUST
+ * ImageFill, which fills the slot by the slot's fit like any image. A fence
+ * carries no alt text. Resolution is strict: the theme MUST carry a `mermaid` block, MUST
  * declare a `mermaidVariant`, and that variant MUST exist — each missing piece
  * throws by name.
  */

package/dist/markdown/blocks/mermaid.js

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node
 import { createRequire } from "node:module";
 import { extname, join, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
-import { ImageFit, SlotType } from "../../engine/index.js";
+import { SlotType } from "../../engine/index.js";
 import { MdastType } from "../mdast.js";
 import { AcceptType } from "../types.js";
 import { buildMermaidRenderConfig, injectClassDefs, validateMermaidDefinition, } from "./mermaidTheme.js";
@@ -15,8 +15,8 @@ export const MERMAID_LANG = "mermaid";
  * Recognize a ```mermaid fenced block at a region's top level, folding it to an
  * Image fill, and compile it by rendering the definition to a PNG (cached under
  * `<rootDir>/.tycoslide-cache/mermaid/<hash>.png`, in the theme directory) and wrapping it as an
- * ImageFill. Fit is always `contain` — mermaid diagrams are shown in their
- * entirety — and a fence carries no alt text. Resolution is strict: the theme MUST carry a `mermaid` block, MUST
+ * ImageFill, which fills the slot by the slot's fit like any image. A fence
+ * carries no alt text. Resolution is strict: the theme MUST carry a `mermaid` block, MUST
  * declare a `mermaidVariant`, and that variant MUST exist — each missing piece
  * throws by name.
  */
@@ -42,7 +42,7 @@ export const MERMAID = {
         }
         const cacheDir = ensureCacheDir(config);
         const pngPath = await renderOne(definition, variantName, variant, cacheDir, config);
-        return { type: SlotType.Image, path: pngPath, fit: ImageFit.Contain, alt: "" };
+        return { type: SlotType.Image, path: pngPath, alt: "" };
     },
 };
 const FONT_FORMATS = {
@@ -187,12 +187,12 @@ export async function launchChromium(chromium, browserPath) {
 }
 /**
  * Render a mermaid definition to a transparent PNG via a headless Chromium
- * (Playwright — the proven old driver, stronger headless font fidelity). The
+ * (Playwright, for its headless font fidelity). The
  * theme fonts are injected as `@font-face` and every registered face is awaited
  * (`document.fonts.load()`) BEFORE `mermaid.render()` measures text — the only
  * cross-platform, zero-install way to make Chromium lay out labels in the brand
- * font instead of a substitute. mmdc's `--cssFile` injects too late (after layout)
- * to affect metrics, which is why this replaces its programmatic API.
+ * font instead of a substitute. A stylesheet injected after layout comes too
+ * late to affect the metrics.
  */
 async function renderMermaidToPng(processed, renderConfig, fonts, outputPath, browserPath) {
     const bundle = getMermaidBundle();

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

@@ -3,7 +3,7 @@
  *
  * Owner of MermaidVariant / MermaidConfig — these types are compiler-facing
  * (the engine has no idea mermaid exists). `blocks/mermaid.ts` consumes
- * them to build --configFile input for `mmdc`.
+ * them to build the render config.
  */
 export type MermaidVariant = {
     primary: string;

package/dist/markdown/blocks/mermaidTheme.js

@@ -3,7 +3,7 @@
  *
  * Owner of MermaidVariant / MermaidConfig — these types are compiler-facing
  * (the engine has no idea mermaid exists). `blocks/mermaid.ts` consumes
- * them to build --configFile input for `mmdc`.
+ * them to build the render config.
  */
 const FORBIDDEN_PATTERNS = [/^\s*style\s+\S+\s+/, /^\s*linkStyle\s+/, /^\s*classDef\s+/, /^\s*%%\{init/];
 export function validateMermaidDefinition(definition) {
@@ -88,7 +88,7 @@ export function buildMermaidRenderConfig(variant) {
             tertiaryColor: variant.surface,
             textColor: variant.text,
             titleColor: variant.text,
-            nodeTextColor: variant.text,
+            nodeTextColor: variant.primaryContrast,
             clusterBkg: variant.surface,
             clusterBorder: variant.surfaceBorder,
             edgeLabelBackground: variant.surface,

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

@@ -30,6 +30,11 @@ export declare const ThemeConfigSchema: z.ZodObject<{
                 type: z.ZodLiteral<"image">;
                 sourceSlide: z.ZodNumber;
                 shapeName: z.ZodString;
+                fit: z.ZodEnum<{
+                    readonly Contain: "contain";
+                    readonly Cover: "cover";
+                    readonly ScaleDown: "scale-down";
+                }>;
             }, z.core.$strict>], "type">>;
             frame: z.ZodOptional<z.ZodObject<{
                 x: z.ZodNumber;

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, Variant } from "../types.js";
+import { AcceptType, ImageFit, Variant } from "../types.js";
 import { strict } from "./strict.js";
 /**
  * Fail-fast runtime validation for a `theme.json`. The hand-written types in
@@ -60,9 +60,10 @@ const ParameterSchema = strict({
     template: z.string(),
 });
 // One arm per accept type, discriminated by `type`, mirroring `CompilerBlock`:
-// `startAt` lives only on the text arm, and `bodyRows` only on the table arm (a
-// table block MUST declare its repeatable-row range; text/image arms have no
-// `bodyRows` field, so a stray one is an unknown key the `strict` arm rejects).
+// `startAt` lives only on the text arm, `bodyRows` only on the table arm and `fit`
+// only on the image arm (a table block MUST declare its repeatable-row range and
+// an image block its fit; an option on another arm is an unknown key the `strict`
+// arm rejects).
 const TextBlockSchema = strict({
     type: z.literal(AcceptType.Text),
     sourceSlide: z.number(),
@@ -79,6 +80,7 @@ const ImageBlockSchema = strict({
     type: z.literal(AcceptType.Image),
     sourceSlide: z.number(),
     shapeName: z.string(),
+    fit: z.enum(ImageFit),
 });
 const BlockSchema = z.discriminatedUnion("type", [TextBlockSchema, TableBlockSchema, ImageBlockSchema]);
 const SlotSchema = strict({

package/dist/markdown/slideParser.d.ts

@@ -8,8 +8,6 @@ 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

@@ -16,7 +16,7 @@ export function parseSlideDocument(source) {
 // ============================================
 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) {
+function isYamlMapping(parsed) {
     return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed);
 }
 function extractGlobalFrontmatter(source) {
@@ -136,7 +136,7 @@ function buildSlide(index, fmString, rawContent) {
 export class FrontmatterParseError extends Error {
     constructor(slideIndex, yamlSource, cause) {
         const preview = yamlSource.length > 80 ? `${yamlSource.slice(0, 80)}...` : yamlSource;
-        super(`Invalid YAML in slide ${slideIndex} frontmatter:\n${preview}`);
+        super(`Slide ${slideIndex + 1}: invalid YAML in frontmatter:\n${preview}`);
         this.name = "FrontmatterParseError";
         this.cause = cause;
     }

package/dist/markdown/types.d.ts

@@ -1,7 +1,8 @@
 import type { RootContent } from "mdast";
-import { type BodyRows, type Frame, type ImageFill, type TableFill, type TemplateFill, type TextFill } from "../engine/index.js";
+import { type BodyRows, type Frame, type ImageFill, ImageFit, type TableFill, type TemplateFill, type TextFill } from "../engine/index.js";
 import type { MermaidConfig } from "./blocks/mermaidTheme.js";
 export type { BodyRows };
+export { ImageFit };
 /**
  * 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
@@ -146,9 +147,10 @@ export declare const RESERVED_KEY: {
  * place), otherwise it is transplanted into the slot's `frame`. A text block may
  * pin `startAt` (leave the first N specimen paragraphs untouched); a table block
  * MUST declare its `bodyRows` range (the repeatable `<a:tbl>` specimen rows); an
- * image block carries neither. There is no `Template` variant — `AcceptType` excludes
- * it (a parameter, not a body block). Named `CompilerBlock` to stay distinct from
- * the engine's `Block` and the compiler's `BlockHandler`.
+ * image block MUST declare its `fit`, which sets how every image placed in it
+ * fills the shape. There is no `Template` variant — `AcceptType` excludes it (a
+ * parameter, not a body block). Named `CompilerBlock` to stay distinct from the
+ * engine's `Block` and the compiler's `BlockHandler`.
  */
 export type CompilerTextBlock = {
     type: typeof AcceptType.Text;
@@ -166,6 +168,7 @@ export type CompilerImageBlock = {
     type: typeof AcceptType.Image;
     sourceSlide: number;
     shapeName: string;
+    fit: ImageFit;
 };
 export type CompilerBlock = CompilerTextBlock | CompilerTableBlock | CompilerImageBlock;
 /**

package/dist/markdown/types.js

@@ -1,4 +1,5 @@
-import { SlotType, } from "../engine/index.js";
+import { ImageFit, SlotType, } from "../engine/index.js";
+export { ImageFit };
 // ── AcceptType discriminator (what a slot accepts) ────────────────────────────
 /**
  * The engine content types a slot may `accept`. A subset of the engine's

package/docs/markdown.md

@@ -2,7 +2,7 @@
 
 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 `theme.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 its `theme.json`, and in `manifest.json` when the theme is packaged as a skill — read it first, and never assume a name shown here (`Body`, `TwoColumn`, `hero`, `::left::`, etc.) exists in your theme.
 
 ---
 
@@ -144,23 +144,23 @@ 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`) -- an image, written as `![alt](path "options")` with the path relative to the deck:
+- **image** (slots that accept `image`) -- an image, written as `![alt](path)` with the path relative to the deck:
   ```markdown
   ::logo::
 
-  ![Acme Corp logo](assets/acme-logo.png "fit: contain")
+  ![Acme Corp logo](assets/acme-logo.png)
   ```
-  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).
+  The alt text becomes the image's alt text in PowerPoint; leave it empty for an image that is only decoration. The slot's `fit`, set in the theme, decides how the image fills its shape. A fenced `mermaid` block also fills an image slot, rendering to a themed PNG (see below).
 
 ---
 
 ## Mermaid diagrams
 
-Write a fenced code block with the `mermaid` language tag in a named slot that accepts `image`. It renders to a themed PNG and behaves like any other image in the slot -- always shown in its entirety. The color variant comes from the theme's `mermaidVariant` (set once in `theme.json`, not per slot).
+Write a fenced code block with the `mermaid` language tag in a named slot that accepts `image`. It renders to a themed PNG and fills the slot like any other image, by the slot's `fit`. The color variant comes from the theme's `mermaidVariant` (set once in `theme.json`, not per slot).
 
 ````markdown
 ---
-layout: Full bleed image with title dark
+layout: Diagram
 title: System Architecture
 ---
 
@@ -216,7 +216,7 @@ 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.
-- **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.
+- **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. A shape the theme doesn't map, such as a card drawn behind a stat, stays, so an unfilled one can leave an empty card.
 
 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).
 
@@ -268,11 +268,10 @@ Common errors and fixes:
 
 | Error | Fix |
 |-------|-----|
-| `unknown layout "xyz"` | Check layout names in `theme.json` |
+| `unknown layout "xyz"` | Check layout names in `theme.json` (or `manifest.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 |

package/docs/theme.md

@@ -48,7 +48,7 @@ A slot is a body region. The author's markdown shape picks which accepted block
 
 ### Blocks inside `accepts`
 
-Each block is discriminated by `type` and carries only its own option. A `bodyRows` on a text block or a `startAt` on a table block is an unknown key and fails the load.
+Each block is discriminated by `type` and carries only its own option. A `bodyRows` on a text block, a `startAt` on a table block or a `fit` on either is an unknown key and fails the load.
 
 | Field | Meaning | Error when wrong |
 |---|---|---|
@@ -57,8 +57,9 @@ Each block is discriminated by `type` and carries only its own option. A `bodyRo
 | `shapeName` | Exact name of the specimen shape on `sourceSlide`. Required. | `Can't find element on slide N in source:` and the placeholder remains. |
 | `startAt` | Text only. Leave the first N specimen paragraphs untouched and rebuild from paragraph N. Optional, default 0. | `startAt 3 is past the last paragraph (shape has 2)`. |
 | `bodyRows` | Table only. `[start, end]`, 0-based inclusive: the rows that repeat for data. Required. Row 0 is always the header. Rows above `start` and below `end` render once, as fixed rows. | `bodyRows [s, e] is out of range; require 1 <= start <= end <= R-1 (row 0 is the header)`; `has no <a:tbl> element (is it actually a table?)`. |
+| `fit` | Image only. Sets how every image placed in the shape fills it. `"contain"` shows the whole image and never crops, `"cover"` fills the shape and center-crops, and `"scale-down"` shows the whole image and never enlarges it. Required. | Schema error listing the valid values. |
 
-For an image block the shape must be a real picture: `is not a picture (missing <a:off>, <a:ext>, <p:blipFill>, or <p:cNvPr>)`.
+For an image block the shape must be an image shape: `is not a picture (missing <a:off>, <a:ext>, <p:blipFill>, or <p:cNvPr>)`.
 
 Transplants: a block whose `sourceSlide` differs from the layout's `slideNumber` is copied from that other slide onto the cloned slide, positioned into the slot's `frame`. The shape the slot replaces on the base slide is removed. This is how one slot accepts both text and a table when the styled table lives on a different slide, as the worked example's `Content` layout does with a table from slide 15. The frame is the observed `<a:xfrm>` of the shape being replaced, so a text block in the same slot fills in place and the table lands exactly where the text was. The transplanted shape is positioned and sized to the frame, so its own size on the source slide does not matter.
 
@@ -69,7 +70,7 @@ Optional array of `@font-face` entries used only when rendering mermaid diagrams
 | Field | Meaning | Error when wrong |
 |---|---|---|
 | `family` | CSS family name; must equal the mermaid variant's `fontFamily`. Required. | Warning `fontFamily "X" matches none of the declared theme fonts`, then a substitute font. |
-| `path` | A package specifier such as `@fontsource/inter/files/inter-latin-400-normal.woff2`, or a `./` or `/` file path. Required. | `could not resolve "path" from <rootDir>`; `file not found at ...`; `unsupported format ".otf"`. Supported: woff2, woff, ttf. |
+| `path` | A package specifier such as `@fontsource/inter/files/inter-latin-400-normal.woff2`, or a `./` or `/` file path. Required. | `could not resolve "path" from <rootDir>`; `file not found at ...`; `unsupported format ".eot"`. Supported: woff2, woff, ttf, otf. |
 | `weight` | OpenType weight. Optional, default 400. | None. |
 
 ## `codeTheme`
@@ -84,7 +85,7 @@ Optional record of named color variants. The record keys are free; every variant
 |---|---|
 | `primary` | Node fill color. |
 | `primaryContrast` | Text color on `primary` nodes. |
-| `text` | Default text, title and node label color. |
+| `text` | Default text and title color, including labels outside nodes. |
 | `line` | Edge and arrow color. |
 | `surface` | Subgraph, secondary node and edge-label background. |
 | `surfaceBorder` | Border color for nodes and subgraphs. |
@@ -120,7 +121,7 @@ Optional string naming a key of `mermaid`. Required as soon as any deck has a me
           "accepts": [
             { "type": "text", "sourceSlide": 1, "shapeName": "Text 1" },
             { "type": "table", "sourceSlide": 2, "shapeName": "Table 0", "bodyRows": [1, 1] },
-            { "type": "image", "sourceSlide": 3, "shapeName": "Image 0" }
+            { "type": "image", "sourceSlide": 3, "shapeName": "Image 0", "fit": "contain" }
           ]
         }
       ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tycoworks/tycoslide",
-  "version": "0.16.1",
+  "version": "0.17.1",
   "description": "Create editable PowerPoint slides from markdown, using your existing .pptx templates.",
   "type": "module",
   "main": "dist/index.js",

package/theme-package/SKILL.template.md

@@ -37,33 +37,33 @@ This skill builds decks from a markdown deck file. The theme provides slide layo
 
 ## Layout Discovery
 
-Before writing anything, read `manifest.json`. It lists the theme's **layouts** -- for each: `name`, `description`, `parameters` (frontmatter inputs) and `slots` (body regions). A layout is identified by its `name`; every parameter and slot by its `key`. Slots carry `accepts`, and either may be `required`.
+Before writing anything, read `manifest.json`. It lists the theme's **layouts** -- for each: `name`, `description`, `parameters` (frontmatter inputs) and `slots` (body regions). A layout is identified by its `name`; every parameter and slot by its `key`. Slots carry `accepts`, and either may be `required`. A slot that accepts an image also shows its `fit`. A `cover` slot crops the image to fill the slot, a `contain` slot shows the whole image, and a `scale-down` slot shows the whole image without ever enlarging it.
 
-A layout's inputs split two ways, parameters and slots; see [markdown.md](node_modules/@tycoworks/tycoslide/docs/markdown.md#parameters-and-slots) for how to fill each. Unfilled ones are dropped, so fill as many of a layout's numbered slots (sections, stats, columns) as you have content for.
+A layout's inputs split two ways, parameters and slots; see [markdown.md](node_modules/@tycoworks/tycoslide/docs/markdown.md#parameters-and-slots) for how to fill each. Unfilled ones are dropped, so fill as many of a layout's numbered slots (sections, stats, columns) as you have content for. A card or panel drawn behind an unfilled one stays, so choose a layout with no more of them than you can fill.
 
 Study each layout's `slots` before writing any slides.
 
 ### Images
 
-Images live in `assets.json`: every logo, illustration and icon the theme offers, keyed by category and name, each with a `path`, a `fit` and a `description`. **Search it, do not read it whole** -- an icon set alone can run to thousands of entries. **Search for what the icon depicts, not what you mean by it**: a catalog is indexed by image, so "freshness" finds nothing while `grep -i -B2 "clock" assets.json` and `grep -i -B2 "bolt" assets.json` find the icon you wanted, with its path and fit on the lines above.
+Images live in `assets.json`: every logo, illustration and icon the theme offers, keyed by category and name, each with a `path` and a `description`. **Search it, do not read it whole** -- an icon set alone can run to thousands of entries. **Search for what the icon depicts, not what you mean by it**: a catalog is indexed by image, so "freshness" finds nothing while `grep -i -B1 "clock" assets.json` and `grep -i -B1 "bolt" assets.json` find the icon you wanted, with its path on the line above.
 
-To use an image, copy it into your deck's folder at the same relative path, then write its `path` and `fit` in the image:
+To use an image, copy it into your deck's folder at the same relative path, then write its `path` in the image:
 
 ```bash
 mkdir -p <deck dir>/assets && cp <theme dir>/assets/hub.png <deck dir>/assets/
 ```
 
 ```markdown
-![Central hub connecting three services](assets/hub.png "fit: scale-down")
+![Central hub connecting three services](assets/hub.png)
 ```
 
-If your deck is in the theme folder, the file is already there, so skip the copy. An image the user gives you also goes in the deck's folder; choose its fit by looking at it (`contain` unless it is full-bleed art that may crop). Write alt text for this slide, describing what the image shows here rather than repeating the catalog description.
+If your deck is in the theme folder, the file is already there, so skip the copy. An image the user gives you also goes in the deck's folder. Write alt text for this slide, describing what the image shows here rather than repeating the catalog description.
 
 ---
 
 ## Creating Slides
 
-Write a deck file in markdown, as [markdown.md](node_modules/@tycoworks/tycoslide/docs/markdown.md) describes (see its [full example](node_modules/@tycoworks/tycoslide/docs/markdown.md#full-example)), and build it as its [Build](node_modules/@tycoworks/tycoslide/docs/markdown.md#build) section shows.
+Write a deck file in markdown, as [markdown.md](node_modules/@tycoworks/tycoslide/docs/markdown.md) describes (see its [full example](node_modules/@tycoworks/tycoslide/docs/markdown.md#full-example)), and build it as its [Build](node_modules/@tycoworks/tycoslide/docs/markdown.md#build) section shows. The deck's `theme:` is the path from the deck to this folder's `theme.json`: `./theme.json` when the deck sits in this folder, and the full path to it when the deck is anywhere else.
 
 ---
 
@@ -90,7 +90,7 @@ Keep each slot's content to what its region comfortably holds. When content over
 - **Don't restyle the layout** -- the theme owns all design; you only fill slots
 - **Don't use an image that's wrong for the slot** -- a small slot wants a simple icon, not a dense illustration. If you get a `shrunk to X%` warning, look at the rendered slide: if the image is now too small to make out, use a simpler one. A `leaves X% of the frame empty` warning is the opposite: the image is a different shape from the slot. Neither fails the build -- judge both from the rendered slide.
 - **Don't skip alt text** -- describe what a meaningful image shows and why it's there, not "image of". Leave it empty only for decoration, such as backgrounds and icons beside a heading.
-- **Don't crop what can't be cropped** -- copy the `fit` from `assets.json`. For your own images, never `fit: cover` a diagram, chart, screenshot or logo.
+- **Don't crop what can't be cropped** -- a `cover` slot crops, so never put a diagram (mermaid included), chart, screenshot or logo in one; choose a layout with a `contain` image slot instead.
 - **Don't invent layout names or image paths** -- layouts come from `manifest.json`, and theme images from `assets.json`, copied next to the deck
 - **Don't leave required parameters or slots empty** -- and don't leave a placeholder logo or dummy text in an image slot you care about. If you don't have a suitable image, ask the user for one.
 
@@ -106,7 +106,7 @@ Build the deck again ([Build](node_modules/@tycoworks/tycoslide/docs/markdown.md
 
 | Error | Fix |
 |-------|-----|
-| An image didn't swap / placeholder remains | Write a `::key::` region using the image slot's key, containing `![alt](path "fit: …")` with the path relative to the deck |
+| An image didn't swap / placeholder remains | Write a `::key::` region using the image slot's key, containing `![alt](path)` with the path relative to the deck |
 | `image "…" not found at …` | For a theme image, copy it into the deck's folder at the path you wrote (search `assets.json`; did you unzip `assets.dat`?) |
 
 ### Verification Loop

package/dist/agents/catalog.d.ts

@@ -1,32 +0,0 @@
-import * as z from "zod";
-/**
- * One image a theme offers deck authors. `fit` is the value an author copies
- * into the image's title, so it is already a title value.
- */
-declare const AssetEntrySchema: z.ZodObject<{
-    path: z.ZodString;
-    fit: z.ZodEnum<{
-        readonly Contain: "contain";
-        readonly Cover: "cover";
-        readonly ScaleDown: "scale-down";
-    }>;
-    description: z.ZodString;
-}, z.core.$strict>;
-declare const AssetCatalogSchema: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
-    path: z.ZodString;
-    fit: z.ZodEnum<{
-        readonly Contain: "contain";
-        readonly Cover: "cover";
-        readonly ScaleDown: "scale-down";
-    }>;
-    description: z.ZodString;
-}, z.core.$strict>>>;
-export type AssetEntry = z.infer<typeof AssetEntrySchema>;
-export type AssetCatalog = z.infer<typeof AssetCatalogSchema>;
-/**
- * Read and validate a theme's image catalog, `assets.json`: what a deck-writing
- * agent searches, copies images from, and takes each image's fit from. It is
- * authored with the theme and required; a theme with no images has `{}`.
- */
-export declare function loadAssetCatalog(themeDir: string): AssetCatalog;
-export {};

package/dist/agents/catalog.js

@@ -1,37 +0,0 @@
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import * as z from "zod";
-import { ImageFit, strict } from "../index.js";
-import { ASSETS_FILE } from "./files.js";
-/**
- * One image a theme offers deck authors. `fit` is the value an author copies
- * into the image's title, so it is already a title value.
- */
-const AssetEntrySchema = strict({
-    path: z.string(),
-    fit: z.enum(ImageFit),
-    description: z.string(),
-});
-// `{ category: { name: entry } }`. Both record levels are open (the names are the
-// theme's own); only the entry is strict.
-const AssetCatalogSchema = z.record(z.string(), z.record(z.string(), AssetEntrySchema));
-/**
- * Read and validate a theme's image catalog, `assets.json`: what a deck-writing
- * agent searches, copies images from, and takes each image's fit from. It is
- * authored with the theme and required; a theme with no images has `{}`.
- */
-export function loadAssetCatalog(themeDir) {
-    const path = join(themeDir, ASSETS_FILE);
-    let raw;
-    try {
-        raw = JSON.parse(readFileSync(path, "utf-8"));
-    }
-    catch {
-        throw new Error(`Image catalog not found or invalid JSON: ${path}`);
-    }
-    const result = AssetCatalogSchema.safeParse(raw);
-    if (!result.success) {
-        throw new Error(`${ASSETS_FILE}: invalid image catalog\n${z.prettifyError(result.error)}`);
-    }
-    return result.data;
-}