@tycoworks/tycoslide 0.15.1 → 0.16.0

package/dist/engine/index.js

@@ -1,7 +1,9 @@
+export { childrenByTag, collectElements } from "./dom.js";
 export { FILLERS } from "./fillers/filler.js";
 export { fillImage } from "./fillers/image.js";
 export { fillTable, isTableFill } from "./fillers/table.js";
 export { fillTemplate } from "./fillers/template.js";
 export { fillText, isTextFill } from "./fillers/text.js";
 export { generate } from "./generate.js";
+export { PRESENTATION_PART, parseXml, readRelationships, relsPathFor, resolveTarget } from "./ooxml.js";
 export { ImageFit, SlotType, TEMPLATE_DIR } from "./types.js";

package/dist/engine/notes.js

@@ -13,18 +13,14 @@
  * step authored notes) or strip any auto-copied part (when it did not, or notes
  * are excluded) — so the designer's template notes never leak into the output.
  */
-import { DOMParser, XMLSerializer } from "@xmldom/xmldom";
+import { XMLSerializer } from "@xmldom/xmldom";
 import { Attr, buildParagraph, buildRun, nextFreeRId as nextFreeRIdForDoc, Tag } from "./dom.js";
-// Package-level OOXML names not covered by dom.ts's `Tag`/`Attr` (which name
-// slide-XML tokens): `[Content_Types].xml` Override entries and the tail
-// segments of relationship-type URLs.
+import { PRESENTATION_PART, PRESENTATION_RELS_PART, parseXml, RelTypeSuffix, readRelationships, relsPathFor, resolveTarget, } from "./ooxml.js";
+// `[Content_Types].xml` Override entries: package-level names not covered by
+// dom.ts's `Tag`/`Attr` (which name slide-XML tokens).
 const CT_OVERRIDE = "Override";
 const CT_PART_NAME = "PartName";
 const CT_CONTENT_TYPE = "ContentType";
-const REL_TYPE_SUFFIX = {
-    NotesSlide: "/notesSlide",
-    NotesMaster: "/notesMaster",
-};
 const NS_A = "http://schemas.openxmlformats.org/drawingml/2006/main";
 const NS_P = "http://schemas.openxmlformats.org/presentationml/2006/main";
 const NS_R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
@@ -38,7 +34,6 @@ const REL_TYPE = {
 const NOTES_SLIDE_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.presentationml.notesSlide+xml";
 const XML_DECL = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\r\n';
 const CONTENT_TYPES_PART = "[Content_Types].xml";
-const PRESENTATION_RELS_PART = "ppt/_rels/presentation.xml.rels";
 const NOTES_SKELETON = `<p:notes xmlns:a="${NS_A}" xmlns:r="${NS_R}" xmlns:p="${NS_P}"><p:cSld><p:spTree>` +
     `<p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr><p:grpSpPr/>` +
     `<p:sp><p:nvSpPr><p:cNvPr id="2" name="Notes Placeholder 1"/>` +
@@ -51,7 +46,7 @@ const NOTES_SKELETON = `<p:notes xmlns:a="${NS_A}" xmlns:r="${NS_R}" xmlns:p="${
  * is handled by the serializer.
  */
 export function buildNotesSlideXml(notes) {
-    const doc = new DOMParser().parseFromString(NOTES_SKELETON, "text/xml");
+    const doc = parseXml(NOTES_SKELETON);
     const txBody = doc.getElementsByTagName("p:txBody")[0];
     for (const line of notes.replace(/\r?\n+$/, "").split(/\r?\n/)) {
         // Reuse the engine's run/paragraph builders — they set xml:space="preserve"
@@ -63,7 +58,7 @@ export function buildNotesSlideXml(notes) {
 }
 /** Next unused `rIdN` in a `.rels` XML string (max existing id + 1). */
 export function nextFreeRId(relsXml) {
-    return nextFreeRIdForDoc(new DOMParser().parseFromString(relsXml, "text/xml"));
+    return nextFreeRIdForDoc(parseXml(relsXml));
 }
 function serialize(doc) {
     // xmldom re-emits any `<?xml?>` declaration present in the parsed source, so a
@@ -72,9 +67,6 @@ function serialize(doc) {
     const body = new XMLSerializer().serializeToString(doc).replace(/^<\?xml[^>]*\?>\s*/, "");
     return XML_DECL + body;
 }
-function parse(xml) {
-    return new DOMParser().parseFromString(xml, "text/xml");
-}
 async function readString(archive, file) {
     const raw = await archive.read(file, "string");
     return typeof raw === "string" ? raw : raw.toString("utf-8");
@@ -114,14 +106,8 @@ function notesRelsXml(slideNumber, masterTarget) {
 async function findNotesMaster(archive) {
     if (!archive.fileExists(PRESENTATION_RELS_PART))
         return undefined;
-    const relsDoc = parse(await readString(archive, PRESENTATION_RELS_PART));
-    const rels = relsDoc.getElementsByTagName(Tag.RELATIONSHIP);
-    for (let i = 0; i < rels.length; i++) {
-        if (rels[i].getAttribute(Attr.TYPE)?.endsWith(REL_TYPE_SUFFIX.NotesMaster)) {
-            return `../${rels[i].getAttribute(Attr.TARGET)}`;
-        }
-    }
-    return undefined;
+    const master = readRelationships(await readString(archive, PRESENTATION_RELS_PART)).find((rel) => rel.type.endsWith(RelTypeSuffix.NotesMaster));
+    return master && `../${master.target}`;
 }
 function findOverride(ctDoc, partName) {
     const overrides = ctDoc.getElementsByTagName(CT_OVERRIDE);
@@ -132,7 +118,7 @@ function findOverride(ctDoc, partName) {
     return undefined;
 }
 async function addContentTypeOverride(archive, partName) {
-    const ctDoc = parse(await readString(archive, CONTENT_TYPES_PART));
+    const ctDoc = parseXml(await readString(archive, CONTENT_TYPES_PART));
     if (findOverride(ctDoc, partName))
         return;
     const override = ctDoc.createElementNS(NS_CT, CT_OVERRIDE);
@@ -150,26 +136,12 @@ function removeOverrideFromDoc(ctDoc, partName) {
     return true;
 }
 async function removeContentTypeOverride(archive, partName) {
-    const ctDoc = parse(await readString(archive, CONTENT_TYPES_PART));
+    const ctDoc = parseXml(await readString(archive, CONTENT_TYPES_PART));
     if (!removeOverrideFromDoc(ctDoc, partName))
         return;
     await archive.write(CONTENT_TYPES_PART, serialize(ctDoc));
 }
-/** Resolve `target` (from a rels file) against `baseDir`, collapsing `.`/`..`. */
-function resolveRelative(baseDir, target) {
-    const parts = baseDir.split("/").filter(Boolean);
-    for (const seg of target.split("/")) {
-        if (seg === "" || seg === ".")
-            continue;
-        if (seg === "..")
-            parts.pop();
-        else
-            parts.push(seg);
-    }
-    return parts.join("/");
-}
 const NOTES_SLIDE_PART = /^ppt\/notesSlides\/notesSlide\d+\.xml$/;
-const PRESENTATION_PART = "ppt/presentation.xml";
 /**
  * The slide parts a deck actually presents, in `<p:sldIdLst>` order, resolved via
  * `presentation.xml.rels`. Returns full archive paths (e.g. `ppt/slides/slide1.xml`).
@@ -182,7 +154,7 @@ const PRESENTATION_PART = "ppt/presentation.xml";
  * referenced. Only slides reachable from `presentation.xml` are live.
  */
 async function liveSlideParts(archive) {
-    const pres = parse(await readString(archive, PRESENTATION_PART));
+    const pres = parseXml(await readString(archive, PRESENTATION_PART));
     const sldIds = pres.getElementsByTagName("p:sldId");
     const rIds = [];
     for (let i = 0; i < sldIds.length; i++) {
@@ -190,27 +162,16 @@ async function liveSlideParts(archive) {
         if (rid)
             rIds.push(rid);
     }
-    const relsDoc = parse(await readString(archive, PRESENTATION_RELS_PART));
-    const rels = relsDoc.getElementsByTagName(Tag.RELATIONSHIP);
-    const targetById = new Map();
-    for (let i = 0; i < rels.length; i++) {
-        const id = rels[i].getAttribute(Attr.ID);
-        const target = rels[i].getAttribute(Attr.TARGET);
-        if (id && target)
-            targetById.set(id, target);
-    }
+    const rels = readRelationships(await readString(archive, PRESENTATION_RELS_PART));
+    const targetById = new Map(rels.map((rel) => [rel.id, rel.target]));
     const parts = [];
     for (const rid of rIds) {
         const target = targetById.get(rid);
         if (target)
-            parts.push(resolveRelative("ppt", target));
+            parts.push(resolveTarget(PRESENTATION_PART, target));
     }
     return parts;
 }
-/** The `_rels` path for an archive part (`ppt/slides/slide1.xml` → `ppt/slides/_rels/slide1.xml.rels`). */
-function relsPathFor(part) {
-    return part.replace(/\/([^/]+)$/, "/_rels/$1.rels");
-}
 /**
  * Remove every notesSlide part that no live slide references. automizer drops the
  * template's orphaned *slides* from the deck when building it but leaves all their
@@ -234,18 +195,15 @@ export async function sweepOrphanNotes(archive) {
         const relsPath = relsPathFor(slidePart);
         if (!archive.fileExists(relsPath))
             continue;
-        const rels = parse(await readString(archive, relsPath)).getElementsByTagName(Tag.RELATIONSHIP);
-        for (let i = 0; i < rels.length; i++) {
-            const target = rels[i].getAttribute(Attr.TARGET);
-            if (target && rels[i].getAttribute(Attr.TYPE)?.endsWith(REL_TYPE_SUFFIX.NotesSlide)) {
-                referenced.add(resolveRelative("ppt/slides", target));
-            }
+        for (const rel of readRelationships(await readString(archive, relsPath))) {
+            if (rel.type.endsWith(RelTypeSuffix.NotesSlide))
+                referenced.add(resolveTarget(slidePart, rel.target));
         }
     }
     const orphans = notesParts.filter((part) => !referenced.has(part));
     if (orphans.length === 0)
         return;
-    const ctDoc = parse(await readString(archive, CONTENT_TYPES_PART));
+    const ctDoc = parseXml(await readString(archive, CONTENT_TYPES_PART));
     let ctChanged = false;
     for (const part of orphans) {
         await archive.remove(part);
@@ -295,7 +253,7 @@ export async function applyNotesToSlide(archive, slideNumber, notes, excludeNote
         }
         await archive.write(notesPath, buildNotesSlideXml(notes));
         await archive.write(notesRelsPath, notesRelsXml(slideNumber, masterTarget));
-        const relsDoc = parse(await readString(archive, slideRelsPath));
+        const relsDoc = parseXml(await readString(archive, slideRelsPath));
         appendRel(relsDoc, nextFreeRIdForDoc(relsDoc), REL_TYPE.NotesSlide, `../notesSlides/notesSlide${slideNumber}.xml`);
         await archive.write(slideRelsPath, serialize(relsDoc));
         await addContentTypeOverride(archive, `/${notesPath}`);
@@ -306,7 +264,7 @@ export async function applyNotesToSlide(archive, slideNumber, notes, excludeNote
     await archive.remove(notesPath);
     if (archive.fileExists(notesRelsPath))
         await archive.remove(notesRelsPath);
-    const relsDoc = parse(await readString(archive, slideRelsPath));
+    const relsDoc = parseXml(await readString(archive, slideRelsPath));
     if (removeNotesRel(relsDoc))
         await archive.write(slideRelsPath, serialize(relsDoc));
     await removeContentTypeOverride(archive, `/${notesPath}`);

package/dist/engine/ooxml.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Package-level OOXML: where a .pptx keeps its parts and how they point at each
+ * other. Used by speaker notes; the generic helpers are exported from the core's
+ * public entry for the agent layer's template reading. Slide-XML tokens live in
+ * `dom.ts`'s `Tag` / `Attr`.
+ */
+/** The presentation part; its presence is what makes a zip a .pptx. */
+export declare const PRESENTATION_PART = "ppt/presentation.xml";
+/** The presentation part's relationships: slides, masters, the notes master. */
+export declare const PRESENTATION_RELS_PART = "ppt/_rels/presentation.xml.rels";
+/**
+ * Tail segments of relationship-type URLs. Matching the tail tolerates both the
+ * transitional (`schemas.openxmlformats.org`) and strict (`purl.oclc.org`) forms.
+ */
+export declare const RelTypeSuffix: {
+    readonly NotesSlide: "/notesSlide";
+    readonly NotesMaster: "/notesMaster";
+};
+export declare function parseXml(xml: string): any;
+/** One relationship from a part's rels file. An `external` target is a URL, not a part. */
+export type Relationship = {
+    id: string;
+    type: string;
+    target: string;
+    external: boolean;
+};
+/** The relationships in a rels file. One missing its `Id`, `Type` or `Target` is malformed, and skipped. */
+export declare function readRelationships(relsXml: string): Relationship[];
+/** The `_rels` path for an archive part (`ppt/slides/slide1.xml` → `ppt/slides/_rels/slide1.xml.rels`). */
+export declare function relsPathFor(part: string): string;
+/**
+ * Resolve a relationship `target` from `part`'s rels to an archive path. A target
+ * starting with `/` is package-absolute; anything else is relative to `part`'s
+ * directory. `.` and `..` segments collapse.
+ */
+export declare function resolveTarget(part: string, target: string): string;

package/dist/engine/ooxml.js

@@ -0,0 +1,56 @@
+/**
+ * Package-level OOXML: where a .pptx keeps its parts and how they point at each
+ * other. Used by speaker notes; the generic helpers are exported from the core's
+ * public entry for the agent layer's template reading. Slide-XML tokens live in
+ * `dom.ts`'s `Tag` / `Attr`.
+ */
+import { posix } from "node:path";
+import { DOMParser } from "@xmldom/xmldom";
+import { Attr, collectElements, Tag } from "./dom.js";
+/** The presentation part; its presence is what makes a zip a .pptx. */
+export const PRESENTATION_PART = "ppt/presentation.xml";
+/** The presentation part's relationships: slides, masters, the notes master. */
+export const PRESENTATION_RELS_PART = "ppt/_rels/presentation.xml.rels";
+/**
+ * Tail segments of relationship-type URLs. Matching the tail tolerates both the
+ * transitional (`schemas.openxmlformats.org`) and strict (`purl.oclc.org`) forms.
+ */
+export const RelTypeSuffix = {
+    NotesSlide: "/notesSlide",
+    NotesMaster: "/notesMaster",
+};
+export function parseXml(xml) {
+    return new DOMParser().parseFromString(xml, "text/xml");
+}
+/** The relationships in a rels file. One missing its `Id`, `Type` or `Target` is malformed, and skipped. */
+export function readRelationships(relsXml) {
+    return collectElements(parseXml(relsXml), Tag.RELATIONSHIP).flatMap((rel) => {
+        const id = rel.getAttribute(Attr.ID);
+        const type = rel.getAttribute(Attr.TYPE);
+        const target = rel.getAttribute(Attr.TARGET);
+        if (!id || !type || !target)
+            return [];
+        return [{ id, type, target, external: rel.getAttribute(Attr.TARGET_MODE) === Attr.EXTERNAL }];
+    });
+}
+/** The `_rels` path for an archive part (`ppt/slides/slide1.xml` → `ppt/slides/_rels/slide1.xml.rels`). */
+export function relsPathFor(part) {
+    return part.replace(/\/([^/]+)$/, "/_rels/$1.rels");
+}
+/**
+ * Resolve a relationship `target` from `part`'s rels to an archive path. A target
+ * starting with `/` is package-absolute; anything else is relative to `part`'s
+ * directory. `.` and `..` segments collapse.
+ */
+export function resolveTarget(part, target) {
+    const parts = target.startsWith("/") ? [] : posix.dirname(part).split("/").filter(Boolean);
+    for (const seg of target.split("/")) {
+        if (seg === "" || seg === ".")
+            continue;
+        if (seg === "..")
+            parts.pop();
+        else
+            parts.push(seg);
+    }
+    return parts.join("/");
+}

package/dist/engine/types.d.ts

@@ -102,11 +102,15 @@ 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
+ * `<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. */
 export type Frame = {

package/dist/index.d.ts

@@ -3,10 +3,6 @@ import { type CompilerConfig, type CompilerDeck, type CompilerThemeConfig } from
 /**
  * Project a CompilerThemeConfig down to the engine's ThemeConfig shape.
  * Fields are copied cell-by-cell so the boundary is explicit — no casts.
- * The compiler's `assets` catalog is intentionally NOT forwarded: the engine
- * is ignorant of theme-level asset metadata; the compiler resolves any asset
- * reference to a filesystem path and wraps it as an ImageFill in
- * `step.content` before this projection runs.
  */
 export declare function toEngineThemeConfig(config: CompilerThemeConfig): ThemeConfig;
 /**
@@ -32,10 +28,7 @@ export declare function toEngineConfig(config: CompilerConfig): Config;
  * directory) so no post-write cleanup is needed.
  */
 export declare function buildDeck(deck: CompilerDeck, config: CompilerConfig, options?: GenerateOptions): Promise<void>;
-export type { Config, Deck, DeckStep, GenerateOptions, ImageFill, Layout, Slot, StyledParagraph, TableFill, TextFill, TextRun, ThemeConfig, } from "./engine/index.js";
-export { fillImage, fillTable, fillTemplate, fillText, generate, SlotType } from "./engine/index.js";
-export { ASSETS_ARCHIVE, ASSETS_FILE } from "./files.js";
-export { generateAssetCatalog, generateManifest } from "./manifest.js";
-export type { AssetCatalog, AssetEntry, CompilerBlock, CompilerConfig, CompilerDeck, CompilerDeckStep, CompilerLayout, CompilerParameter, CompilerSlot, CompilerThemeConfig, EngineFill, LoadedTheme, MermaidConfig, MermaidVariant, ParsedDocument, RawSlide, } from "./markdown/index.js";
-export { AcceptType, compileMarkdownDeck, loadThemeConfig, parseThemeConfig } from "./markdown/index.js";
-export { expandAssets } from "./skillZip.js";
+export type { Config, Deck, DeckStep, Frame, GenerateOptions, ImageFill, Layout, Relationship, Slot, StyledParagraph, TableFill, TextFill, TextRun, ThemeConfig, } from "./engine/index.js";
+export { childrenByTag, collectElements, fillImage, fillTable, fillTemplate, fillText, generate, ImageFit, PRESENTATION_PART, parseXml, readRelationships, relsPathFor, resolveTarget, SlotType, TEMPLATE_DIR, } from "./engine/index.js";
+export type { CompilerBlock, CompilerConfig, CompilerDeck, CompilerDeckStep, CompilerLayout, CompilerParameter, CompilerSlot, CompilerThemeConfig, EngineFill, LoadedTheme, MermaidConfig, MermaidVariant, ParsedDocument, RawSlide, } from "./markdown/index.js";
+export { AcceptType, compileMarkdownDeck, loadThemeConfig, parseThemeConfig, strict, templateKeys, } from "./markdown/index.js";

package/dist/index.js

@@ -1,6 +1,5 @@
 import { generate, SlotType, } from "./engine/index.js";
 import { AcceptType, } from "./markdown/types.js";
-import { expandAssets } from "./skillZip.js";
 /**
  * A frontmatter parameter always fills one physical shape on the layout's own
  * slide, so it projects to a single base `Block` (`sourceSlide === baseSlide`)
@@ -70,10 +69,6 @@ function toEngineLayout(layout) {
 /**
  * Project a CompilerThemeConfig down to the engine's ThemeConfig shape.
  * Fields are copied cell-by-cell so the boundary is explicit — no casts.
- * The compiler's `assets` catalog is intentionally NOT forwarded: the engine
- * is ignorant of theme-level asset metadata; the compiler resolves any asset
- * reference to a filesystem path and wraps it as an ImageFill in
- * `step.content` before this projection runs.
  */
 export function toEngineThemeConfig(config) {
     const result = {
@@ -113,18 +108,10 @@ export async function buildDeck(deck, config, options = {}) {
     if (deck.output === undefined) {
         throw new Error('buildDeck: deck.output is not set. Set it (e.g. "deck.pptx") before calling buildDeck.');
     }
-    // A packaged theme ships its assets as one archive, because hosts cap how many
-    // files a skill may contain. Expand it here rather than at compile: the catalog
-    // is what an author reads, and only filling needs the bytes.
-    await expandAssets(config.rootDir);
     const engineDeck = { theme: deck.theme, output: deck.output, steps: deck.steps };
     await generate(engineDeck, toEngineConfig(config), options);
 }
 // Engine — primitives-only public surface.
-export { fillImage, fillTable, fillTemplate, fillText, generate, SlotType } from "./engine/index.js";
-export { ASSETS_ARCHIVE, ASSETS_FILE } from "./files.js";
-// Authoring
-export { generateAssetCatalog, generateManifest } from "./manifest.js";
+export { childrenByTag, collectElements, fillImage, fillTable, fillTemplate, fillText, generate, ImageFit, PRESENTATION_PART, parseXml, readRelationships, relsPathFor, resolveTarget, SlotType, TEMPLATE_DIR, } from "./engine/index.js";
 // Markdown / Compiler
-export { AcceptType, compileMarkdownDeck, loadThemeConfig, parseThemeConfig } from "./markdown/index.js";
-export { expandAssets } from "./skillZip.js";
+export { AcceptType, compileMarkdownDeck, loadThemeConfig, parseThemeConfig, strict, templateKeys, } from "./markdown/index.js";

package/dist/markdown/blocks/code.js

@@ -18,8 +18,7 @@ export const CODE = {
         // A fence with no language can't be highlighted (no Shiki grammar to pick),
         // so fail fast naming the slot rather than attempt a language-less highlight.
         if (!code.lang) {
-            throw new Error(`Slide ${ctx.slideNo}: layout "${ctx.layoutName}" slot content (from ${ctx.source}) has a code fence ` +
-                "with no language; add one after the opening ``` (e.g. ```sql).");
+            throw new Error(`${ctx.region} has a code fence with no language; add one after the opening \`\`\` (e.g. \`\`\`sql).`);
         }
         const codeTheme = ctx.config.codeTheme;
         if (!codeTheme) {

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

@@ -1,2 +1,25 @@
+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,9 +1,71 @@
+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 { 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,
-    // `node.url` is the raw `$category.name` ref; `resolveAssetRef` validates and
-    // resolves it (fail-fast on a malformed or unknown reference). `alt` is ignored.
-    compile: async (node, ctx) => ctx.resolveAssetRef(node.url),
+    // `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 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 ?? "" };
+    },
 };
+/**
+ * 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

@@ -8,7 +8,7 @@ export declare const MERMAID_LANG = "mermaid";
  * 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. Resolution is strict: the theme MUST carry a `mermaid` block, MUST
+ * entirety — and 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

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { extname, join, resolve } from "node:path";
+import { extname, join, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { ImageFit, SlotType } from "../../engine/index.js";
 import { MdastType } from "../mdast.js";
@@ -16,7 +16,7 @@ export const MERMAID_LANG = "mermaid";
  * 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. Resolution is strict: the theme MUST carry a `mermaid` block, MUST
+ * entirety — and 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 };
+        return { type: SlotType.Image, path: pngPath, fit: ImageFit.Contain, alt: "" };
     },
 };
 const FONT_FORMATS = {
@@ -80,7 +80,9 @@ function ensureCacheDir(config) {
  * naming the family + path — never a silent skip.
  */
 function resolveFonts(rootDir, fonts) {
-    const require = createRequire(join(rootDir, "package.json"));
+    // `createRequire` treats a path ending in a separator as a directory, so package
+    // names resolve from the theme's folder (its node_modules).
+    const require = createRequire(join(rootDir, sep));
     return fonts.map((font) => {
         const isFsPath = font.path.startsWith(".") || font.path.startsWith("/");
         let absPath;

package/dist/markdown/blocks/table.js

@@ -4,20 +4,21 @@ import { AcceptType } from "../types.js";
 export const TABLE = {
     match: (node) => node.type === MdastType.Table,
     acceptType: AcceptType.Table,
-    compile: async (node) => compileTable(node),
+    compile: async (node, ctx) => compileTable(node, { region: ctx.region }),
 };
 /** A GFM `table` → TableFill: first row is headers, the rest are body rows; each
  * cell's phrasing children become `TextRun[]` via the shared inline walk. */
-function compileTable(node) {
+function compileTable(node, state) {
     const [head, ...body] = node.children;
+    const cell = (tableCell) => cellParagraph(tableCell, state);
     return {
-        headers: head ? head.children.map(cellParagraph) : [],
-        rows: body.map((row) => row.children.map(cellParagraph)),
+        headers: head ? head.children.map(cell) : [],
+        rows: body.map((row) => row.children.map(cell)),
     };
 }
 /** One table cell → a StyledParagraph. An empty cell keeps a single empty run so
  * downstream code always sees a run to style. */
-function cellParagraph(cell) {
-    const runs = walkPhrasingChildren(cell.children, {});
+function cellParagraph(cell, state) {
+    const runs = walkPhrasingChildren(cell.children, state);
     return { runs: runs.length > 0 ? runs : [{ text: "" }] };
 }

package/dist/markdown/blocks/text.js

@@ -10,16 +10,18 @@ import { MdastType } from "../mdast.js";
  */
 export function compileTextAggregate(nodes, ctx) {
     const paragraphs = [];
+    // Hard breaks split paragraphs here, and inline errors name the region.
+    const state = { breakAsNewline: true, region: ctx.region };
     for (const node of nodes) {
         switch (node.type) {
             case MdastType.Paragraph:
             case MdastType.Heading:
-                for (const runs of splitRunsIntoParagraphs(walkPhrasingChildren(node.children, { breakAsNewline: true }))) {
+                for (const runs of splitRunsIntoParagraphs(walkPhrasingChildren(node.children, state))) {
                     paragraphs.push({ runs });
                 }
                 break;
             case MdastType.List:
-                paragraphs.push(...listParagraphs(node, 0));
+                paragraphs.push(...listParagraphs(node, 0, state));
                 break;
             default:
                 throw new Error(reject(nodes.length, node.type, ctx));
@@ -34,11 +36,10 @@ export function compileTextAggregate(nodes, ctx) {
  * (table/image/code) mixed into prose — both name the layout/slide/slot + type.
  */
 function reject(nodeCount, nodeType, ctx) {
-    const where = `Slide ${ctx.slideNo}: layout "${ctx.layoutName}" slot content (from ${ctx.source})`;
     if (nodeCount === 1) {
-        return `${where} is a standalone "${nodeType}" block, which is not a supported content kind.`;
+        return `${ctx.region} is a standalone "${nodeType}" block, which is not a supported content kind.`;
     }
-    return (`${where} mixes a "${nodeType}" block with other content; ` +
+    return (`${ctx.region} mixes a "${nodeType}" block with other content; ` +
         "a table, image, or code block must be the region's only content.");
 }
 /**
@@ -47,15 +48,15 @@ function reject(nodeCount, nodeType, ctx) {
  * `level + 1`. Ordered and unordered both yield plain bullets — the engine has
  * no ordered flag.
  */
-function listParagraphs(list, level) {
+function listParagraphs(list, level, state) {
     const out = [];
     for (const item of list.children) {
         for (const child of item.children) {
             if (child.type === MdastType.List) {
-                out.push(...listParagraphs(child, level + 1));
+                out.push(...listParagraphs(child, level + 1, state));
             }
             else if (child.type === MdastType.Paragraph || child.type === MdastType.Heading) {
-                for (const runs of splitRunsIntoParagraphs(walkPhrasingChildren(child.children, { breakAsNewline: true }))) {
+                for (const runs of splitRunsIntoParagraphs(walkPhrasingChildren(child.children, state))) {
                     out.push({ runs, bullet: { level } });
                 }
             }