@tycoworks/tycoslide 0.15.1 → 0.16.0

package/dist/agents/media.js

@@ -0,0 +1,83 @@
+/**
+ * Media: copy the images a template uses, on its masters, layouts and slides, out
+ * of the .pptx under their original media filenames, as raw material for a theme's
+ * image catalog.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import { imageSize } from "image-size";
+import { Part, RelType } from "./pptx.js";
+const XML_EXT = ".xml";
+/** What happened to one referenced image. */
+export const MediaOutcome = {
+    Copied: "copied",
+    /** A file of that name was already in the output folder, and was left untouched. */
+    Present: "present",
+    /** Byte-identical to an image already handled under another name, so not copied twice. */
+    Duplicate: "duplicate",
+    /** Referenced by a relationship but absent from the package. */
+    Missing: "missing",
+};
+/**
+ * Copy every image the presentation's masters, layouts and slides use into
+ * `outDir` (created if missing), and describe each in first-use order: masters
+ * first, then layouts, then slides, each in number order. Never overwrites: an
+ * image whose filename is already there is left as it is.
+ */
+export async function copyImages(presentation, outDir) {
+    mkdirSync(outDir, { recursive: true });
+    const references = await imageReferences(presentation);
+    const images = [];
+    const firstByContent = new Map();
+    for (const [media, usedBy] of references) {
+        const file = posix.basename(media);
+        if (!presentation.has(media)) {
+            images.push({ file, usedBy, outcome: MediaOutcome.Missing });
+            continue;
+        }
+        const data = await presentation.bytes(media);
+        const size = pixelSize(data);
+        const read = { file, usedBy, ...(size && { size }) };
+        const digest = createHash("sha256").update(data).digest("hex");
+        const duplicateOf = firstByContent.get(digest);
+        if (duplicateOf) {
+            images.push({ ...read, outcome: MediaOutcome.Duplicate, duplicateOf });
+            continue;
+        }
+        firstByContent.set(digest, file);
+        const dest = join(outDir, file);
+        if (existsSync(dest)) {
+            images.push({ ...read, outcome: MediaOutcome.Present });
+            continue;
+        }
+        writeFileSync(dest, data);
+        images.push({ ...read, outcome: MediaOutcome.Copied });
+    }
+    return images;
+}
+/** Media part → the masters, layouts and slides that use it, in first-use order. */
+async function imageReferences(presentation) {
+    const references = new Map();
+    const parts = [Part.Master, Part.Layout, Part.Slide].flatMap((pattern) => presentation.numbered(pattern));
+    for (const part of parts) {
+        const user = posix.basename(part, XML_EXT);
+        for (const media of await presentation.related(part, RelType.Image)) {
+            const users = references.get(media) ?? [];
+            if (!users.includes(user))
+                users.push(user);
+            references.set(media, users);
+        }
+    }
+    return references;
+}
+/** Pixel size of an image, or undefined when its format isn't readable. */
+function pixelSize(data) {
+    try {
+        const { width, height } = imageSize(new Uint8Array(data));
+        return width && height ? { width, height } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/agents/pptx.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Reading a .pptx from the agent layer: open it, parse its parts once, and follow
+ * its relationships. Built on the core's generic package helpers; the names of the
+ * parts and relationships the agent layer looks for live here.
+ */
+import { type Relationship } from "../index.js";
+/** Archive paths of the parts the agent layer reads, numbered by their file name. */
+export declare const Part: {
+    readonly Slide: RegExp;
+    readonly Master: RegExp;
+    readonly Layout: RegExp;
+    readonly EmbeddedFont: RegExp;
+};
+/** Tail segments of the relationship types the agent layer follows. */
+export declare const RelType: {
+    readonly Image: "/image";
+    readonly Theme: "/theme";
+    readonly SlideLayout: "/slideLayout";
+};
+/** `ppt/slides/slide12.xml` → 12, for a part matching one of `Part`'s patterns. */
+export declare function partNumber(part: string, pattern: RegExp): number;
+/** A .pptx opened for reading: its parts, each parsed once, and where their relationships lead. */
+export declare class Presentation {
+    private readonly parsed;
+    private readonly zip;
+    private constructor();
+    /** Open `path`, failing with a plain explanation when it is missing or not a .pptx. */
+    static open(path: string): Promise<Presentation>;
+    /** Every file in the package. */
+    get parts(): string[];
+    /** The parts matching `pattern`, in number order. */
+    numbered(pattern: RegExp): string[];
+    has(part: string): boolean;
+    bytes(part: string): Promise<Buffer>;
+    /** The part's root element. */
+    xml(part: string): Promise<any>;
+    private file;
+    /** The part's relationships to other parts (external links left out), with targets resolved. */
+    relationships(part: string): Promise<Relationship[]>;
+    /** The parts `part` relates to with a relationship type ending in `suffix`. */
+    related(part: string, suffix: string): Promise<string[]>;
+}
+/** The element reached from `el` by a path of child tag names, or undefined. */
+export declare function find(el: any, ...path: string[]): any;
+/** `el`'s element children, only those named `tag` when given; none when `el` is missing. */
+export declare function elementChildren(el: any, tag?: string): any[];
+/** `el`'s attributes by name; none when `el` is missing. */
+export declare function attributes(el: any): Record<string, string>;

package/dist/agents/pptx.js

@@ -0,0 +1,123 @@
+/**
+ * Reading a .pptx from the agent layer: open it, parse its parts once, and follow
+ * its relationships. Built on the core's generic package helpers; the names of the
+ * parts and relationships the agent layer looks for live here.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import JSZip from "jszip";
+import { childrenByTag, PRESENTATION_PART, parseXml, readRelationships, relsPathFor, resolveTarget, } from "../index.js";
+/** Archive paths of the parts the agent layer reads, numbered by their file name. */
+export const Part = {
+    Slide: /^ppt\/slides\/slide(\d+)\.xml$/,
+    Master: /^ppt\/slideMasters\/slideMaster(\d+)\.xml$/,
+    Layout: /^ppt\/slideLayouts\/slideLayout(\d+)\.xml$/,
+    EmbeddedFont: /^ppt\/fonts\/.+\.fntdata$/,
+};
+/** Tail segments of the relationship types the agent layer follows. */
+export const RelType = {
+    Image: "/image",
+    Theme: "/theme",
+    SlideLayout: "/slideLayout",
+};
+/** `ppt/slides/slide12.xml` → 12, for a part matching one of `Part`'s patterns. */
+export function partNumber(part, pattern) {
+    return Number(pattern.exec(part)?.[1]);
+}
+/** A .pptx opened for reading: its parts, each parsed once, and where their relationships lead. */
+export class Presentation {
+    parsed = new Map();
+    zip;
+    constructor(zip) {
+        this.zip = zip;
+    }
+    /** Open `path`, failing with a plain explanation when it is missing or not a .pptx. */
+    static async open(path) {
+        if (!existsSync(path) || !statSync(path).isFile()) {
+            throw new Error(`${path} does not exist or is not a file.`);
+        }
+        let zip;
+        try {
+            zip = await JSZip.loadAsync(readFileSync(path));
+        }
+        catch {
+            throw new Error(`${path} is not a .pptx file (it is not a zip archive).`);
+        }
+        if (!zip.file(PRESENTATION_PART)) {
+            throw new Error(`${path} is not a .pptx file (no ${PRESENTATION_PART} inside; a .docx or .xlsx perhaps?).`);
+        }
+        return new Presentation(zip);
+    }
+    /** Every file in the package. */
+    get parts() {
+        return Object.keys(this.zip.files).filter((name) => !this.zip.files[name].dir);
+    }
+    /** The parts matching `pattern`, in number order. */
+    numbered(pattern) {
+        return this.parts
+            .filter((part) => pattern.test(part))
+            .sort((a, b) => partNumber(a, pattern) - partNumber(b, pattern));
+    }
+    has(part) {
+        return this.zip.file(part) !== null;
+    }
+    async bytes(part) {
+        return this.file(part).async("nodebuffer");
+    }
+    /** The part's root element. */
+    async xml(part) {
+        let doc = this.parsed.get(part);
+        if (!doc) {
+            doc = parseXml(await this.file(part).async("string"));
+            this.parsed.set(part, doc);
+        }
+        return doc.documentElement;
+    }
+    file(part) {
+        const file = this.zip.file(part);
+        if (!file)
+            throw new Error(`${part} is missing from the package.`);
+        return file;
+    }
+    /** The part's relationships to other parts (external links left out), with targets resolved. */
+    async relationships(part) {
+        const rels = this.zip.file(relsPathFor(part));
+        if (!rels)
+            return [];
+        return readRelationships(await rels.async("string"))
+            .filter((rel) => !rel.external)
+            .map((rel) => ({ ...rel, target: resolveTarget(part, rel.target) }));
+    }
+    /** The parts `part` relates to with a relationship type ending in `suffix`. */
+    async related(part, suffix) {
+        return (await this.relationships(part)).filter((rel) => rel.type.endsWith(suffix)).map((rel) => rel.target);
+    }
+}
+/** The element reached from `el` by a path of child tag names, or undefined. */
+export function find(el, ...path) {
+    let node = el;
+    for (const tag of path) {
+        node = node && childrenByTag(node, tag)[0];
+    }
+    return node;
+}
+/** `el`'s element children, only those named `tag` when given; none when `el` is missing. */
+export function elementChildren(el, tag) {
+    if (!el)
+        return [];
+    if (tag)
+        return childrenByTag(el, tag);
+    const out = [];
+    for (let i = 0; i < el.childNodes.length; i++) {
+        if (el.childNodes[i].nodeType === ELEMENT_NODE)
+            out.push(el.childNodes[i]);
+    }
+    return out;
+}
+/** `el`'s attributes by name; none when `el` is missing. */
+export function attributes(el) {
+    const out = {};
+    for (let i = 0; i < (el?.attributes?.length ?? 0); i++)
+        out[el.attributes[i].name] = el.attributes[i].value;
+    return out;
+}
+const ELEMENT_NODE = 1;

package/dist/agents/skill.d.ts

@@ -0,0 +1,43 @@
+import { type CompilerThemeConfig } from "../index.js";
+import type { AssetCatalog } from "./catalog.js";
+/**
+ * Pack `paths` (theme-relative, POSIX) into one archive, reading each through
+ * `read`. Entries keep their declared paths, so expanding reproduces the layout
+ * `theme.json` already refers to.
+ */
+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.
+ */
+export declare function renameSkill(md: string, name: 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,
+ * and lists the engine as a devDependency because the repo builds with it rather
+ * than shipping it.
+ *
+ * Copying that verbatim breaks the consumer twice. An install script runs inside
+ * their container, so anything it touches that is read-only fails their whole
+ * `npm install`. And under `--omit=dev` the engine is never installed, so
+ * `npx tycoslide build` cannot find it.
+ *
+ * What ships instead declares only what the skill needs to RUN: the theme's own
+ * dependencies plus the engine, as runtime dependencies, and no scripts at all.
+ */
+export declare function skillPackageJson(theme: Record<string, unknown>, engine: {
+    name: string;
+    version: string;
+}): string;
+/**
+ * Zip a theme into an uploadable Agent Skill archive whose entries all live
+ * under a single root folder (e.g. `acme-slides/theme.json`), matching Anthropic's
+ * custom-skill format. `themeFiles` names the theme's own top-level files that go
+ * in as they are (the config and the catalog); `generated` is the skill's files
+ * that exist only in the zip (its `package.json`, `SKILL.md` and manifest), by
+ * name. Optional support files are skipped when absent; anything the config or
+ * 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>;

package/dist/agents/skill.js

@@ -0,0 +1,134 @@
+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";
+/** Entries are stored, not deflated: assets are already-compressed images. */
+const NO_COMPRESSION = { type: "nodebuffer", compression: "STORE" };
+/**
+ * Pack `paths` (theme-relative, POSIX) into one archive, reading each through
+ * `read`. Entries keep their declared paths, so expanding reproduces the layout
+ * `theme.json` already refers to.
+ */
+export async function packAssets(paths, read) {
+    const archive = new JSZip();
+    for (const rel of paths)
+        archive.file(rel, read(rel));
+    return archive.generateAsync(NO_COMPRESSION);
+}
+const FRONTMATTER = /^---\n([\s\S]*?)\n---/;
+const NAME_LINE = /^name:[ \t]*.*$/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.
+ */
+export function renameSkill(md, name) {
+    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}`));
+}
+/**
+ * Files a packaged skill needs beyond the theme's own declarations. Only the
+ * lockfile: `package.json` is authored by `skillPackageJson` rather than taken
+ * from the theme directory.
+ */
+const SUPPORT_FILES = ["package-lock.json"];
+/**
+ * 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,
+ * and lists the engine as a devDependency because the repo builds with it rather
+ * than shipping it.
+ *
+ * Copying that verbatim breaks the consumer twice. An install script runs inside
+ * their container, so anything it touches that is read-only fails their whole
+ * `npm install`. And under `--omit=dev` the engine is never installed, so
+ * `npx tycoslide build` cannot find it.
+ *
+ * What ships instead declares only what the skill needs to RUN: the theme's own
+ * dependencies plus the engine, as runtime dependencies, and no scripts at all.
+ */
+export function skillPackageJson(theme, engine) {
+    const dependencies = {
+        ...(theme.dependencies ?? {}),
+        [engine.name]: `^${engine.version}`,
+    };
+    const skill = {
+        name: theme.name,
+        version: theme.version,
+        description: theme.description,
+        private: true,
+        dependencies: Object.fromEntries(Object.entries(dependencies).sort(([a], [b]) => a.localeCompare(b))),
+    };
+    return jsonFile(skill);
+}
+/**
+ * Every path a packaged theme needs, relative to `rootDir` and POSIX-separated,
+ * split by how it ships.
+ *
+ * Derived from the theme config and its image catalog rather than filtered out
+ * of a directory walk: together they declare the template and every image, so
+ * an allowlist stays correct no matter what else sits in the working directory --
+ * built decks, PDFs, slide PNGs, scratch files. Font paths are deliberately
+ * absent when they name a package -- those resolve from node_modules, which
+ * `npm install` restores -- but a `./`- or `/`-prefixed font path is a file the
+ * theme owns, and mermaid reads it during a build, which never expands the
+ * archive. Those ship plain.
+ *
+ * `archived` is the catalog's images, which collapse to one archive because
+ * hosts cap how many FILES a skill may contain. `plain` is everything else,
+ * including the catalog itself.
+ */
+function skillPaths(config, catalog, themeFiles) {
+    const archived = Object.values(catalog).flatMap((category) => Object.values(category).map((entry) => entry.path));
+    const localFonts = (config.fonts ?? []).map((f) => f.path).filter((p) => p.startsWith(".") || p.startsWith("/"));
+    return {
+        plain: [...SUPPORT_FILES, ...themeFiles, `${TEMPLATE_DIR}/${config.template}`, ...localFonts],
+        archived,
+    };
+}
+/**
+ * Zip a theme into an uploadable Agent Skill archive whose entries all live
+ * under a single root folder (e.g. `acme-slides/theme.json`), matching Anthropic's
+ * custom-skill format. `themeFiles` names the theme's own top-level files that go
+ * in as they are (the config and the catalog); `generated` is the skill's files
+ * that exist only in the zip (its `package.json`, `SKILL.md` and manifest), by
+ * name. Optional support files are skipped when absent; anything the config or
+ * catalog declares but that is missing is an error.
+ */
+export async function zipDir(rootDir, folderName, config, catalog, themeFiles, generated) {
+    const zip = new JSZip();
+    const folder = zip.folder(folderName);
+    if (!folder)
+        throw new Error(`Failed to create zip folder: ${folderName}`);
+    for (const [name, content] of Object.entries(generated))
+        folder.file(name, content);
+    const { plain, archived } = skillPaths(config, catalog, themeFiles);
+    const optional = new Set(SUPPORT_FILES);
+    // `optional` is a plain-bucket concept (a lockfile a theme may not have). An
+    // asset the catalog declares is never optional, so the archived loop calls
+    // `required` and a missing one throws rather than silently vanishing.
+    const required = (rel) => {
+        const abs = join(rootDir, ...rel.split("/"));
+        if (existsSync(abs))
+            return readFileSync(abs);
+        throw new Error(`Theme declares "${rel}", but no such file exists`);
+    };
+    const read = (rel) => {
+        if (optional.has(rel) && !existsSync(join(rootDir, ...rel.split("/"))))
+            return null;
+        return required(rel);
+    };
+    for (const rel of plain) {
+        const content = read(rel);
+        if (content !== null)
+            folder.file(rel, content);
+    }
+    if (archived.length > 0)
+        folder.file(ASSETS_ARCHIVE, await packAssets(archived, required));
+    return zip.generateAsync(NO_COMPRESSION);
+}

package/dist/cli.js

@@ -1,16 +1,15 @@
-import { readFileSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { ASSETS_FILE, MANIFEST_FILE, SKILL_FILE, SYNTAX_FILE, THEME_CONFIG, THEME_PACKAGE_DIR } from "./files.js";
+import { registerAgentCommands } from "./agents/commands.js";
+import { PACKAGE_JSON } from "./agents/files.js";
 import { buildDeck } from "./index.js";
-import { generateAssetCatalog, generateManifest } from "./manifest.js";
 import { compileDeck, loadThemeConfig, parseSlideDocument, RESERVED_KEY } from "./markdown/index.js";
-import { renameSkill, skillPackageJson, zipDir } from "./skillZip.js";
-const sdkDir = dirname(fileURLToPath(import.meta.url));
-const skillMdPath = resolve(sdkDir, "..", THEME_PACKAGE_DIR, SKILL_FILE);
-const syntaxMdPath = resolve(sdkDir, "..", THEME_PACKAGE_DIR, SYNTAX_FILE);
-const pkg = JSON.parse(readFileSync(resolve(sdkDir, "..", "package.json"), "utf-8"));
+// The CLI is the one module that wires both layers: `build` from the core, and
+// the agent layer's commands registered onto the same program.
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(readFileSync(resolve(packageRoot, PACKAGE_JSON), "utf-8"));
 const program = new Command().name("tycoslide").description("PPTX template engine CLI").version(pkg.version);
 program
     .command("build")
@@ -45,42 +44,7 @@ program
     deck.output = resolve(dirname(absDeckPath), outName);
     await buildDeck(deck, config, { excludeNotes: !opts.notes });
 });
-program
-    .command("package")
-    .description("Generate the Agent Skill (manifest.json, SKILL.md, syntax.md) for AI agents")
-    .option(`-c, --config <path>`, "path to theme config file", THEME_CONFIG)
-    .action(async (opts) => {
-    const config = loadThemeConfig(resolve(process.cwd(), opts.config));
-    const themePkg = JSON.parse(readFileSync(resolve(process.cwd(), "package.json"), "utf-8"));
-    if (!themePkg.name) {
-        throw new Error('Cannot name the skill: the theme\'s package.json has no "name" field.');
-    }
-    // basename drops any npm scope, e.g. "@acme/acme-slides" -> "acme-slides".
-    const skillName = basename(themePkg.name);
-    writeFileSync(resolve(process.cwd(), MANIFEST_FILE), `${generateManifest(config)}\n`);
-    console.log(`WROTE ${MANIFEST_FILE}`);
-    writeFileSync(resolve(process.cwd(), ASSETS_FILE), `${generateAssetCatalog(config)}\n`);
-    console.log(`WROTE ${ASSETS_FILE}`);
-    let skillMd;
-    try {
-        skillMd = renameSkill(readFileSync(skillMdPath, "utf-8"), skillName);
-    }
-    catch (err) {
-        throw new Error(`${skillMdPath}: ${err.message}`);
-    }
-    writeFileSync(resolve(process.cwd(), SKILL_FILE), skillMd);
-    console.log(`WROTE ${SKILL_FILE}`);
-    const syntaxMd = readFileSync(syntaxMdPath, "utf-8");
-    writeFileSync(resolve(process.cwd(), SYNTAX_FILE), syntaxMd);
-    console.log(`WROTE ${SYNTAX_FILE}`);
-    // Bundle the WHOLE theme so the skill is self-contained: unzip ->
-    // `npm install` (pulls the engine + its deps) -> `npx tycoslide build`.
-    const zipFile = `${skillName}.zip`;
-    const generated = [opts.config, MANIFEST_FILE, ASSETS_FILE, SKILL_FILE, SYNTAX_FILE];
-    const skillPkg = skillPackageJson(themePkg, { name: pkg.name, version: pkg.version });
-    writeFileSync(resolve(process.cwd(), zipFile), await zipDir(process.cwd(), skillName, config, generated, skillPkg));
-    console.log(`WROTE ${zipFile}`);
-});
+registerAgentCommands(program, { root: packageRoot, name: pkg.name, version: pkg.version });
 // Everything below the CLI throws plain Errors carrying a written-for-humans
 // message. Print that message and stop; a Node stack trace tells a deck author
 // nothing about their deck, and buries the part that does.

package/dist/engine/dom.d.ts

@@ -28,6 +28,7 @@ export declare const Tag: {
     readonly BLIP: "a:blip";
     readonly SRC_RECT: "a:srcRect";
     readonly BLIP_FILL: "p:blipFill";
+    readonly NON_VISUAL_PROPS: "p:cNvPr";
     readonly SPACE_BEFORE: "a:spcBef";
     readonly HLINK_CLICK: "a:hlinkClick";
     readonly RELATIONSHIP: "Relationship";
@@ -70,6 +71,8 @@ export declare const Attr: {
     readonly TOP: "t";
     readonly RIGHT: "r";
     readonly BOTTOM: "b";
+    readonly DESCR: "descr";
+    readonly TITLE: "title";
     readonly XML_SPACE: "xml:space";
     readonly PRESERVE: "preserve";
 };

package/dist/engine/dom.js

@@ -28,6 +28,7 @@ export const Tag = {
     BLIP: "a:blip",
     SRC_RECT: "a:srcRect",
     BLIP_FILL: "p:blipFill",
+    NON_VISUAL_PROPS: "p:cNvPr",
     SPACE_BEFORE: "a:spcBef",
     HLINK_CLICK: "a:hlinkClick",
     RELATIONSHIP: "Relationship",
@@ -77,6 +78,9 @@ export const Attr = {
     TOP: "t",
     RIGHT: "r",
     BOTTOM: "b",
+    // non-visual properties (alt text)
+    DESCR: "descr",
+    TITLE: "title",
     // whitespace preservation
     XML_SPACE: "xml:space",
     PRESERVE: "preserve",

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

@@ -1,8 +1,9 @@
 /**
- * Image fill — element-level picture geometry only. 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 pixel size.
+ * 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
+ * pixel size, and rewrites the picture's alt text for the new image.
  */
 import { type ImageFill, ImageFit } from "../types.js";
 /** A picture frame's placement + size, in EMU. */
@@ -37,7 +38,7 @@ export type GeometryResult = {
  * Size a picture shape from its `ImageFit` (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`.
+ * geometry pass go to `console.warn`. Also sets its alt text (`setAltText`).
  *
  * `image.path` is assumed absolute — the compiler / caller resolves it before the
  * ImageFill reaches the engine.

package/dist/engine/fillers/image.js

@@ -1,8 +1,9 @@
 /**
- * Image fill — element-level picture geometry only. 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 pixel size.
+ * 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
+ * pixel size, and rewrites the picture's alt text for the new image.
  */
 import { readFileSync } from "node:fs";
 import { imageSize } from "image-size";
@@ -25,7 +26,7 @@ const MIN_SCALE = 0.2;
  * Size a picture shape from its `ImageFit` (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`.
+ * geometry pass go to `console.warn`. Also sets its alt text (`setAltText`).
  *
  * `image.path` is assumed absolute — the compiler / caller resolves it before the
  * ImageFill reaches the engine.
@@ -38,9 +39,11 @@ export function fillImage(shape, image, shapeName, label) {
     const off = shape.getElementsByTagName(Tag.OFFSET)[0];
     const ext = shape.getElementsByTagName(Tag.EXTENT)[0];
     const blipFill = shape.getElementsByTagName(Tag.BLIP_FILL)[0];
-    if (!off || !ext || !blipFill) {
-        throw new Error(`Image shape "${shapeName}": is not a picture (missing <a:off>, <a:ext>, or <p:blipFill>).`);
+    const nvProps = shape.getElementsByTagName(Tag.NON_VISUAL_PROPS)[0];
+    if (!off || !ext || !blipFill || !nvProps) {
+        throw new Error(`Image shape "${shapeName}": is not a picture (missing <a:off>, <a:ext>, <p:blipFill>, or <p:cNvPr>).`);
     }
+    setAltText(nvProps, image.alt);
     const frame = {
         x: Number(off.getAttribute(Attr.X)),
         y: Number(off.getAttribute(Attr.Y)),
@@ -141,6 +144,20 @@ function applySrcRect(shape, blipFill, l, t, r, b) {
     srcRect.setAttribute(Attr.RIGHT, String(r));
     srcRect.setAttribute(Attr.BOTTOM, String(b));
 }
+/**
+ * Describe the new picture on its `<p:cNvPr>`: `descr` carries the alt text, or
+ * is removed when it is empty, since any description the placeholder carried
+ * was for a different image. The legacy `title` is always removed: on a
+ * template placeholder it is a stale label (often the source filename), and
+ * `descr` alone is what PowerPoint shows and reads.
+ */
+function setAltText(nvProps, alt) {
+    nvProps.removeAttribute(Attr.TITLE);
+    if (alt)
+        nvProps.setAttribute(Attr.DESCR, alt);
+    else
+        nvProps.removeAttribute(Attr.DESCR);
+}
 /** Discriminator for ImageFill values. */
 export function isImageFill(v) {
     return (isPlainObject(v) &&

package/dist/engine/generate.d.ts

@@ -15,8 +15,8 @@
  *     fills each cell's first paragraph. See fillers/table.ts.
  *
  *   ImageFill → fillImage  Points the picture's blip relationship at a new media
- *     file (registered by generate(), swapped by the ImageFiller) and adjusts
- *     geometry for the chosen fit. See fillers/image.ts.
+ *     file (registered by generate(), swapped by the ImageFiller), adjusts
+ *     geometry for the chosen fit, and sets its alt text. See fillers/image.ts.
  *
  * generate() loads the template, registers media, and for each DeckStep clones
  * the layout's base slide and calls `fillSlide`. Each value in `step.content`

package/dist/engine/generate.js

@@ -15,8 +15,8 @@
  *     fills each cell's first paragraph. See fillers/table.ts.
  *
  *   ImageFill → fillImage  Points the picture's blip relationship at a new media
- *     file (registered by generate(), swapped by the ImageFiller) and adjusts
- *     geometry for the chosen fit. See fillers/image.ts.
+ *     file (registered by generate(), swapped by the ImageFiller), adjusts
+ *     geometry for the chosen fit, and sets its alt text. See fillers/image.ts.
  *
  * generate() loads the template, registers media, and for each DeckStep clones
  * the layout's base slide and calls `fillSlide`. Each value in `step.content`

package/dist/engine/index.d.ts

@@ -1,3 +1,4 @@
+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";
@@ -5,5 +6,7 @@ export { fillTemplate } from "./fillers/template.js";
 export { fillText, isTextFill } from "./fillers/text.js";
 export type { GenerateOptions } from "./generate.js";
 export { generate } from "./generate.js";
+export type { Relationship } from "./ooxml.js";
+export { PRESENTATION_PART, parseXml, readRelationships, relsPathFor, resolveTarget } from "./ooxml.js";
 export type { Block, BodyRows, Config, Deck, DeckStep, Frame, ImageFill, Layout, Slot, StyledParagraph, TableFill, TemplateFill, TemplateSegment, TextFill, TextRun, ThemeConfig, } from "./types.js";
 export { ImageFit, SlotType, TEMPLATE_DIR } from "./types.js";