@tycoworks/tycoslide 0.7.0 → 0.9.0

package/README.md

@@ -1,14 +1,14 @@
 # tycoslide
 
-Generate slides from markdown using your real PowerPoint templates.
+Let AI agents build slides from existing PowerPoint (`.pptx`) files.
 
 > **Early release** — tycoslide is under active development.
 
-## Why tycoslide?
+## How it works
 
-AI can write great slide content, but it can never get things on-brand. No matter what you try, fonts, logos, and colors end up slightly wrong, and you spend hours fixing it by hand.
-
-tycoslide helps AI agents build presentations using your real slide templates, so they're always on-brand. You define a theme with your .pptx files, layouts and design assets, from which agents can quickly build new presentations using markdown.
+1. **tycoslide wraps your PowerPoint file as an agent skill.**
+2. **Your agents use the skill to write slides in markdown.**
+3. **tycoslide builds a finished PowerPoint file from the markdown.**
 
 ## Quick Start
 
@@ -49,7 +49,7 @@ tycoslide build deck.md                   # → deck.pptx
 
 ```bash
 tycoslide build deck.md       # markdown → PPTX (theme resolved from deck frontmatter)
-tycoslide smoke               # one slide per layout → smoke-all.pptx
+tycoslide build deck.md --no-notes   # omit speaker notes from the output
 tycoslide plugin              # generate AI agent plugin package
 tycoslide manifest            # print layout + asset catalog to stdout
 ```

package/SKILL.md

@@ -39,7 +39,7 @@ For brand voice and naming guidelines, read `brand.md` if it exists alongside th
 
 Before writing anything, read `manifest.json`. It contains:
 
-- **layouts** -- for each: `name`, `description`, `parameters` (frontmatter inputs) and `slots` (body regions), each with `type` and optionally `required`, `fit`, `limit`, `codeTheme`, `mermaidVariant`, plus documentation (`whenToUse`, `whenNotToUse`)
+- **layouts** -- for each: `name`, `description`, `parameters` (frontmatter inputs) and `slots` (body regions), each with `type` and optionally `required`, `limit`, `codeTheme`, `mermaidVariant` (plus, for assets, a `type` of `icon`/`image`/`background`), plus documentation (`whenToUse`, `whenNotToUse`)
 - **assets** -- brand logos, client logos, illustrations, and icons (`description`, `whenToUse`)
 
 A layout's inputs split two ways (see [syntax.md](syntax.md) for details):
@@ -101,6 +101,7 @@ subtitle: This Quarter
 - `layout` is required and consumed by the compiler (not forwarded as content).
 - All other frontmatter keys fill parameters: `title` fills the `title` template parameter, `subtitle` fills the `subtitle` parameter, `hero` fills the `hero` image parameter, etc. A multi-line text shape surfaces as several keys (e.g. `name` + `jobTitle`); fill each as its own scalar line.
 - Slots (`text`, `table`, `code`, `mermaid`) are filled by body regions, not frontmatter -- see below.
+- A slide may also carry a `notes:` block in frontmatter -- plain-text speaker notes for the slide's notes page (see [syntax.md](syntax.md#speaker-notes)). It is slide-level metadata, not a parameter or slot.
 
 ### Body content, slots, and formatting
 

package/dist/cli.js

@@ -2,90 +2,10 @@ import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { FitMode, generate, SlotType } from "./engine/index.js";
-import { buildDeck, toEngineConfig } from "./index.js";
+import { buildDeck } from "./index.js";
 import { generateManifest } from "./manifest.js";
-import { toImageFill } from "./markdown/deckCompiler.js";
-import { CompilerSlotType, compileDeck, ParameterType, parseSlideDocument, RESERVED_KEY, } from "./markdown/index.js";
-import { templateKeys, templateToSegments } from "./markdown/textTemplate.js";
-// ── Smoke content fixtures (used by the `smoke` subcommand) ──────────────────
-const line = (text) => ({ runs: [{ text }] });
-const bulletLine = (text, level = 0) => ({ runs: [{ text }], bullet: { level } });
-const SMOKE_TABLE = {
-    headers: ["Feature", "Starter", "Pro", "Business", "Enterprise"].map(line),
-    rows: [
-        ["Users", "5", "25", "100", "Unlimited"].map(line),
-        ["Storage", "1 GB", "10 GB", "100 GB", "1 TB"].map(line),
-        ["Support", "Email", "Priority", "24/7", "Dedicated"].map(line),
-    ],
-};
-const SMOKE_CODE = [
-    { runs: [{ text: "SELECT name, total", color: "FF7B72" }] },
-    { runs: [{ text: "FROM orders", color: "FF7B72" }] },
-    { runs: [{ text: "WHERE created_at > now();", color: "FF7B72" }] },
-];
-const SMOKE_PROSE = [
-    line("Sample intro line for this block."),
-    bulletLine("First point"),
-    bulletLine("Second point"),
-];
-function pickFirstAsset(config) {
-    for (const group of Object.values(config.assets)) {
-        for (const entry of Object.values(group))
-            return entry.path;
-    }
-    return undefined;
-}
-function smokeSteps(config) {
-    const firstAsset = pickFirstAsset(config);
-    const absAsset = firstAsset ? resolve(config.rootDir, firstAsset) : undefined;
-    return config.layouts.map((layout) => {
-        const content = {};
-        // Parameters (frontmatter): text → a placeholder-filled template, image → the first asset.
-        for (const p of layout.parameters) {
-            switch (p.type) {
-                case ParameterType.Image: {
-                    if (!absAsset)
-                        continue;
-                    content[p.key] = toImageFill(p, absAsset);
-                    break;
-                }
-                case ParameterType.Template: {
-                    // Text shapes carry no key — the engine slot is keyed by shapeName.
-                    const values = new Map(templateKeys(p.template).map((k) => [k, "Sample"]));
-                    content[p.shapeName] = { lines: templateToSegments(p.template, values, p.shapeName) };
-                    break;
-                }
-            }
-        }
-        // Slots (body regions): text → prose, table → table, code → code, mermaid → image.
-        for (const s of layout.slots) {
-            switch (s.type) {
-                case CompilerSlotType.Table:
-                    content[s.key] = SMOKE_TABLE;
-                    break;
-                case CompilerSlotType.Code:
-                    content[s.key] = { paragraphs: SMOKE_CODE };
-                    break;
-                case CompilerSlotType.Mermaid: {
-                    // Mermaid slots don't declare fit; smoke fills them with a fixed
-                    // contained ImageFill so the projected engine slot (Image, contain)
-                    // stays consistent with the real renderer's output.
-                    if (!absAsset)
-                        continue;
-                    content[s.key] = { type: SlotType.Image, path: absAsset, fit: FitMode.Contain };
-                    break;
-                }
-                case CompilerSlotType.Text:
-                    content[s.key] = { paragraphs: SMOKE_PROSE };
-                    break;
-            }
-        }
-        return { layout: layout.name, content };
-    });
-}
+import { compileDeck, loadThemeConfig, parseSlideDocument, RESERVED_KEY } from "./markdown/index.js";
 const DEFAULT_CONFIG = "theme.json";
-const DEFAULT_SMOKE_OUTPUT = "smoke-all.pptx";
 const SKILL_DIR = "skills/slides";
 const PLUGIN_DIR = ".claude-plugin";
 const PLUGIN_FILE = "plugin.json";
@@ -96,16 +16,6 @@ const BUILD_COMMAND = "npx tycoslide build";
 const sdkDir = dirname(fileURLToPath(import.meta.url));
 const skillMdPath = resolve(sdkDir, "..", SKILL_FILE);
 const syntaxMdPath = resolve(sdkDir, "..", SYNTAX_FILE);
-function loadConfig(absPath) {
-    let raw;
-    try {
-        raw = JSON.parse(readFileSync(absPath, "utf-8"));
-    }
-    catch {
-        throw new Error(`Config file not found or invalid JSON: ${absPath}`);
-    }
-    return { ...raw, rootDir: dirname(absPath) };
-}
 const pkg = JSON.parse(readFileSync(resolve(sdkDir, "..", "package.json"), "utf-8"));
 const program = new Command().name("tycoslide").description("PPTX template engine CLI").version(pkg.version);
 program
@@ -113,6 +23,7 @@ program
     .description("Build a PPTX deck from a Markdown spec")
     .argument("<deck>", "path to deck markdown file")
     .option(`-c, --config <path>`, "override theme config path (default: read from frontmatter)")
+    .option("--no-notes", "omit speaker notes from the output (also strips any inherited template notes)")
     .action(async (deckPath, opts) => {
     const absDeckPath = resolve(process.cwd(), deckPath);
     let source;
@@ -132,11 +43,11 @@ program
     if (!absConfigPath) {
         throw new Error(`${basename(deckPath)}: missing required "${RESERVED_KEY.THEME}" in global frontmatter`);
     }
-    const config = loadConfig(absConfigPath);
-    const deck = compileDeck(doc, config.layouts, config.rootDir);
+    const config = loadThemeConfig(absConfigPath);
+    const deck = await compileDeck(doc, config);
     if (!deck.output)
         deck.output = basename(deckPath).replace(/\.md$/, ".pptx");
-    await buildDeck(deck, config);
+    await buildDeck(deck, config, { excludeNotes: !opts.notes });
 });
 program
     .command("manifest")
@@ -144,7 +55,7 @@ program
     .option(`-c, --config <path>`, "path to theme config file", DEFAULT_CONFIG)
     .option(`-o, --out <file>`, "write to file instead of stdout")
     .action(async (opts) => {
-    const config = loadConfig(resolve(process.cwd(), opts.config));
+    const config = loadThemeConfig(resolve(process.cwd(), opts.config));
     const json = generateManifest(config, { build: { command: BUILD_COMMAND } });
     if (opts.out) {
         writeFileSync(resolve(process.cwd(), opts.out), `${json}\n`);
@@ -154,22 +65,12 @@ program
         process.stdout.write(`${json}\n`);
     }
 });
-program
-    .command("smoke")
-    .description("Generate one smoke-test slide per layout")
-    .option(`-c, --config <path>`, "path to theme config file", DEFAULT_CONFIG)
-    .option(`-o, --out <file>`, "output PPTX filename", DEFAULT_SMOKE_OUTPUT)
-    .action(async (opts) => {
-    const config = loadConfig(resolve(process.cwd(), opts.config));
-    const steps = smokeSteps(config);
-    await generate({ theme: opts.config, output: opts.out, steps }, toEngineConfig(config));
-});
 program
     .command("plugin")
     .description("Generate plugin package (plugin.json, manifest.json, SKILL.md, syntax.md) for AI agents")
     .option(`-c, --config <path>`, "path to theme config file", DEFAULT_CONFIG)
     .action(async (opts) => {
-    const config = loadConfig(resolve(process.cwd(), opts.config));
+    const config = loadThemeConfig(resolve(process.cwd(), opts.config));
     const cwd = process.cwd();
     const pkg = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf-8"));
     const pluginMeta = {

package/dist/engine/dom.d.ts

@@ -32,6 +32,8 @@ export declare const Tag: {
     readonly HLINK_CLICK: "a:hlinkClick";
     readonly RELATIONSHIP: "Relationship";
     readonly TABLE: "a:tbl";
+    readonly TABLE_GRID: "a:tblGrid";
+    readonly GRID_COL: "a:gridCol";
     readonly TABLE_ROW: "a:tr";
     readonly TABLE_CELL: "a:tc";
     readonly TX_BODY: "a:txBody";
@@ -63,6 +65,7 @@ export declare const Attr: {
     readonly Y: "y";
     readonly CX: "cx";
     readonly CY: "cy";
+    readonly WIDTH: "w";
     readonly LEFT: "l";
     readonly TOP: "t";
     readonly RIGHT: "r";
@@ -81,6 +84,8 @@ export declare function leadingDecorativePrefix(text: string): string;
 export declare function buildRun(doc: any, cloneRPr: any | null, text: string): any;
 export declare function buildParagraph(doc: any, clonePPr: any | null, run: any): any;
 export declare const HYPERLINK_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
+/** Next unused `rIdN` (max existing id + 1) among a rels container's `<Relationship>` children. */
+export declare function nextFreeRId(relation: any): string;
 export declare function addRelationship(relation: any, url: string): string;
 /**
  * Replace all runs in a paragraph with a sequence of styled runs, cloning the

package/dist/engine/dom.js

@@ -32,6 +32,8 @@ export const Tag = {
     HLINK_CLICK: "a:hlinkClick",
     RELATIONSHIP: "Relationship",
     TABLE: "a:tbl",
+    TABLE_GRID: "a:tblGrid",
+    GRID_COL: "a:gridCol",
     TABLE_ROW: "a:tr",
     TABLE_CELL: "a:tc",
     TX_BODY: "a:txBody",
@@ -68,6 +70,8 @@ export const Attr = {
     Y: "y",
     CX: "cx",
     CY: "cy",
+    // table grid column width
+    WIDTH: "w",
     // srcRect edges
     LEFT: "l",
     TOP: "t",
@@ -143,7 +147,8 @@ export function buildParagraph(doc, clonePPr, run) {
 }
 // ── Relationship Management ──────────────────────────────────────────────────
 export const HYPERLINK_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
-export function addRelationship(relation, url) {
+/** Next unused `rIdN` (max existing id + 1) among a rels container's `<Relationship>` children. */
+export function nextFreeRId(relation) {
     const existing = collectElements(relation, Tag.RELATIONSHIP);
     let maxId = 0;
     for (const rel of existing) {
@@ -152,7 +157,10 @@ export function addRelationship(relation, url) {
         if (num > maxId)
             maxId = num;
     }
-    const rId = `rId${maxId + 1}`;
+    return `rId${maxId + 1}`;
+}
+export function addRelationship(relation, url) {
+    const rId = nextFreeRId(relation);
     const rel = relation.ownerDocument.createElement(Tag.RELATIONSHIP);
     rel.setAttribute(Attr.ID, rId);
     rel.setAttribute(Attr.TYPE, HYPERLINK_REL_TYPE);
@@ -338,10 +346,18 @@ export function rebuildParagraphs(shape, paragraphs, startIndex, relation, shape
             continue;
         const isBullet = para.bullet !== undefined;
         const inLevel = para.bullet?.level ?? 0;
-        const { bucket, effectiveLvl } = isBullet ? pickBullet(inLevel) : { bucket: plainBucket, effectiveLvl: 0 };
         // Skip fully-empty text (matches previous fillText behavior).
         if (para.runs.length === 1 && !para.runs[0].text)
             continue;
+        // Bulleted content needs a bulleted specimen to model on. A plain-only shape
+        // (e.g. a designer "description" line, buNone) accepts plain text only, so
+        // bulleting it is an authoring error — fail fast rather than emit a run with
+        // no modelled style (which renders in the app default colour, e.g. black on
+        // a dark slide whose real text colour lives only in the specimen's rPr).
+        if (isBullet && bullets.size === 0) {
+            throw new Error(`Shape "${shapeName}": received bulleted content, but its specimen has no bulleted paragraph to model — this slot accepts plain text only.`);
+        }
+        const { bucket, effectiveLvl } = isBullet ? pickBullet(inLevel) : { bucket: plainBucket, effectiveLvl: 0 };
         const seedRun = buildRun(doc, bucket?.rPr ?? null, "");
         const newPara = buildParagraph(doc, bucket?.pPr ?? null, seedRun);
         maybeOverrideLevel(newPara, isBullet ? effectiveLvl : null);

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

@@ -1,22 +1,30 @@
 /**
  * The `Filler` strategy registry — one plain-object strategy per SlotType, each
- * pairing a value discriminator with a slide-level fill. The record key IS the
- * slot type, so a strategy carries no redundant `type` field. `generate()`
- * consults `FILLERS[slot.type]` once per (slot, value): `matches` validates the
- * value shape, then `fill` applies it to the slide.
+ * pairing a value discriminator with the element-level modify callbacks that
+ * apply it. The record key IS the slot type, so a strategy carries no redundant
+ * `type` field.
  *
- * Element-level geometry lives in the `fillX` primitives; slide-level concerns
- * (media pre-swap for images, relation access for body hyperlinks, column
- * validation for tables) live in the strategy wrappers here.
+ * `callbacks(value, target)` returns the `(element, relation)` callbacks that
+ * fill one shape. They are deliberately shape-name-agnostic beyond the `target`
+ * so they can be applied two ways: `slide.modifyElement(name, callbacks)` for a
+ * shape already on the cloned base slide, or `slide.addElement(alias, n, name,
+ * callbacks)` for a shape transplanted from another slide — pptx-automizer runs
+ * an appended shape's callbacks against the imported element itself, so the same
+ * callbacks refill a transplant.
+ *
+ * Element-level geometry lives in the `fillX` primitives; cross-shape concerns
+ * (media pre-swap for images) live in the callbacks here.
  */
-import { type Slot, SlotType } from "../types.js";
-export type FillContext = {
-    layoutName: string;
+import { SlotType } from "../types.js";
+/** The shape a filler targets, plus its slot-level options (startAt for text). */
+export type FillTarget = {
+    shapeName: string;
+    startAt?: number;
 };
+/** A pptx-automizer element-modify callback: `(element, relation) => void`. */
+export type ShapeCallback = (element: any, relation: any) => unknown;
 export interface Filler<T> {
     matches(v: unknown): v is T;
-    /** Human name for the mismatch error — no magic string at the throw site. */
-    label: string;
-    fill(slide: any, slot: Slot, value: T, ctx: FillContext): void;
+    callbacks(value: T, target: FillTarget): ShapeCallback[];
 }
 export declare const FILLERS: Record<SlotType, Filler<any>>;

package/dist/engine/fillers/filler.js

@@ -1,13 +1,19 @@
 /**
  * The `Filler` strategy registry — one plain-object strategy per SlotType, each
- * pairing a value discriminator with a slide-level fill. The record key IS the
- * slot type, so a strategy carries no redundant `type` field. `generate()`
- * consults `FILLERS[slot.type]` once per (slot, value): `matches` validates the
- * value shape, then `fill` applies it to the slide.
+ * pairing a value discriminator with the element-level modify callbacks that
+ * apply it. The record key IS the slot type, so a strategy carries no redundant
+ * `type` field.
  *
- * Element-level geometry lives in the `fillX` primitives; slide-level concerns
- * (media pre-swap for images, relation access for body hyperlinks, column
- * validation for tables) live in the strategy wrappers here.
+ * `callbacks(value, target)` returns the `(element, relation)` callbacks that
+ * fill one shape. They are deliberately shape-name-agnostic beyond the `target`
+ * so they can be applied two ways: `slide.modifyElement(name, callbacks)` for a
+ * shape already on the cloned base slide, or `slide.addElement(alias, n, name,
+ * callbacks)` for a shape transplanted from another slide — pptx-automizer runs
+ * an appended shape's callbacks against the imported element itself, so the same
+ * callbacks refill a transplant.
+ *
+ * Element-level geometry lives in the `fillX` primitives; cross-shape concerns
+ * (media pre-swap for images) live in the callbacks here.
  */
 import { basename } from "node:path";
 import { ModifyImageHelper } from "pptx-automizer";
@@ -19,35 +25,23 @@ import { fillText, isTextFill } from "./text.js";
 export const FILLERS = {
     [SlotType.Template]: {
         matches: isTemplateFill,
-        label: "TemplateFill",
-        fill: (slide, slot, v) => slide.modifyElement(slot.shapeName, [(el) => fillTemplate(el, v, slot.shapeName)]),
+        callbacks: (v, t) => [(el) => fillTemplate(el, v, t.shapeName)],
     },
     [SlotType.Text]: {
         matches: isTextFill,
-        label: "TextFill",
-        fill: (slide, slot, v) => {
-            const startAt = slot.startAt ?? 0;
-            slide.modifyElement(slot.shapeName, [
-                (el, relation) => fillText(el, v, { startAt, relation, shapeName: slot.shapeName }),
-            ]);
-        },
+        callbacks: (v, t) => [
+            (el, relation) => fillText(el, v, { startAt: t.startAt ?? 0, relation, shapeName: t.shapeName }),
+        ],
     },
     [SlotType.Table]: {
         matches: isTableFill,
-        label: "TableFill",
-        fill: (slide, slot, v, { layoutName }) => {
-            if (slot.columns !== undefined && v.headers.length !== slot.columns) {
-                throw new Error(`Layout "${layoutName}" slot "${slot.key}": table has ${v.headers.length} columns, template expects ${slot.columns}`);
-            }
-            slide.modifyElement(slot.shapeName, [(el) => fillTable(el, v, slot.shapeName)]);
-        },
+        callbacks: (v, t) => [(el) => fillTable(el, v, t.shapeName)],
     },
     [SlotType.Image]: {
         matches: isImageFill,
-        label: "ImageFill",
-        fill: (slide, slot, v) => slide.modifyElement(slot.shapeName, [
+        callbacks: (v, t) => [
             ModifyImageHelper.setRelationTarget(basename(v.path)),
-            (el) => fillImage(el, v, slot.shapeName),
-        ]),
+            (el) => fillImage(el, v, t.shapeName),
+        ],
     },
 };

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

@@ -1,19 +1,58 @@
 /**
  * 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 just adjusts the frame for the fit mode.
+ * (`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.
  */
-import { type ImageFill } from "../types.js";
+import { type ImageFill, ImageFit } from "../types.js";
+/** A picture frame's placement + size, in EMU. */
+interface Frame {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** The two ways a picture is placed: crop the source (`<a:srcRect>`) or resize the frame. */
+declare const Placement: {
+    readonly Crop: "crop";
+    readonly Fit: "fit";
+};
+/** Either a symmetric `<a:srcRect>` crop (fill/cover) or a resized+re-centred frame (fit/contain). */
+type FitGeometry = {
+    placement: typeof Placement.Crop;
+    left: number;
+    top: number;
+} | {
+    placement: typeof Placement.Fit;
+    x: number;
+    y: number;
+    cx: number;
+    cy: number;
+};
+export type GeometryResult = {
+    geometry: FitGeometry;
+    warnings: string[];
+};
 /**
- * Adjust a picture shape's geometry for the chosen fit mode:
- *  - cover: writes `<a:srcRect>` insets (units: 1/100,000%) so the image fills
- *    the frame with the overflowing axis center-cropped.
- *  - contain: shrinks the picture's frame to the image's aspect-ratio dimensions
- *    and re-centers within the original frame bounds.
+ * 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-centre (fit/letterbox). Advisory warnings from the
+ * geometry pass go to `console.warn`.
  *
  * `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): 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
+ * center-crops the overflow; `contain` scales to the smaller ratio and
+ * letterboxes; `scale-down` is `contain` capped at native size (never enlarge →
+ * the image sits at native size, centred). Emits advisory warnings for scaling
+ * far from native and for a severe aspect mismatch; the caller decides how to
+ * surface them.
+ */
+export declare function computeGeometry(frame: Frame, imgW: number, imgH: number, fit: ImageFit): GeometryResult;
 /** Discriminator for ImageFill values. */
 export declare function isImageFill(v: unknown): v is ImageFill;
+export {};

package/dist/engine/fillers/image.js

@@ -1,18 +1,31 @@
 /**
  * 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 just adjusts the frame for the fit mode.
+ * (`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.
  */
 import { readFileSync } from "node:fs";
 import { imageSize } from "image-size";
 import { Attr, isPlainObject, Tag } from "../dom.js";
-import { FitMode, SlotType } from "../types.js";
+import { ImageFit, SlotType } from "../types.js";
+/** The two ways a picture is placed: crop the source (`<a:srcRect>`) or resize the frame. */
+const Placement = { Crop: "crop", Fit: "fit" };
+const EMU_PER_INCH = 914400;
+/** PPTX's reference pixel density: one source px maps to one output px at this DPI. */
+const PX_PER_INCH = 96;
+/** EMU that one source pixel occupies at native (1:1) size — 9525. */
+const NATIVE_EMU_PER_PX = EMU_PER_INCH / PX_PER_INCH;
+/** `<a:srcRect>` insets are fixed-point fractions of the picture where this = 100%. */
+const SRC_RECT_FULL = 100000;
+/** Warn once the cropped-away or empty area exceeds this fraction of the frame. */
+const SEVERE_MISMATCH_FRACTION = 0.5;
+/** Warn once the image renders below this fraction of its native pixel size. */
+const MIN_SCALE = 0.2;
 /**
- * Adjust a picture shape's geometry for the chosen fit mode:
- *  - cover: writes `<a:srcRect>` insets (units: 1/100,000%) so the image fills
- *    the frame with the overflowing axis center-cropped.
- *  - contain: shrinks the picture's frame to the image's aspect-ratio dimensions
- *    and re-centers within the original frame bounds.
+ * 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-centre (fit/letterbox). Advisory warnings from the
+ * geometry pass go to `console.warn`.
  *
  * `image.path` is assumed absolute — the compiler / caller resolves it before the
  * ImageFill reaches the engine.
@@ -34,48 +47,77 @@ export function fillImage(shape, image, shapeName = "") {
         w: Number(ext.getAttribute(Attr.CX)),
         h: Number(ext.getAttribute(Attr.CY)),
     };
-    const geom = computeFit(frame, dims.width, dims.height, image.fit);
-    if (geom.kind === "crop") {
-        // cover: symmetric crop on the overflowing axis, written as srcRect insets.
-        applySrcRect(shape, blipFill, geom.left, geom.top, geom.left, geom.top);
+    const { geometry, warnings } = computeGeometry(frame, dims.width, dims.height, image.fit);
+    for (const w of warnings)
+        console.warn(`Image "${shapeName}": ${w}`);
+    if (geometry.placement === Placement.Crop) {
+        // fill: symmetric crop on the overflowing axis, written as srcRect insets.
+        applySrcRect(shape, blipFill, geometry.left, geometry.top, geometry.left, geometry.top);
         return;
     }
-    // contain: drop any inherited crop, then resize + re-center the frame itself.
+    // fit: drop any inherited crop, then resize + re-center the frame itself.
     applySrcRect(shape, blipFill, 0, 0, 0, 0);
-    ext.setAttribute(Attr.CX, String(geom.cx));
-    ext.setAttribute(Attr.CY, String(geom.cy));
-    off.setAttribute(Attr.X, String(geom.x));
-    off.setAttribute(Attr.Y, String(geom.y));
+    ext.setAttribute(Attr.CX, String(geometry.cx));
+    ext.setAttribute(Attr.CY, String(geometry.cy));
+    off.setAttribute(Attr.X, String(geometry.x));
+    off.setAttribute(Attr.Y, String(geometry.y));
 }
 /**
  * Pure fit geometry — no DOM, so it is trivially unit-testable in isolation.
- * Given the picture frame (EMU) and the source image's pixel size: cover scales
- * up until both axes are covered and crops the overflow; contain scales down
- * until the whole image fits, then re-centres the shrunken frame.
+ * `fit` picks the strategy: `cover` scales to the larger axis ratio and
+ * center-crops the overflow; `contain` scales to the smaller ratio and
+ * letterboxes; `scale-down` is `contain` capped at native size (never enlarge →
+ * the image sits at native size, centred). Emits advisory warnings for scaling
+ * far from native and for a severe aspect mismatch; the caller decides how to
+ * surface them.
  */
-function computeFit(frame, imgW, imgH, fit) {
+export function computeGeometry(frame, imgW, imgH, fit) {
     const fitX = frame.w / imgW;
     const fitY = frame.h / imgH;
-    const inset = (fraction) => Math.round(fraction * 100000); // <a:srcRect> unit: 1/100,000%
-    if (fit === FitMode.Cover) {
-        const scale = Math.max(fitX, fitY);
-        const shownW = imgW * scale;
-        const shownH = imgH * scale;
+    const allowCrop = fit === ImageFit.Cover;
+    let scale = allowCrop ? Math.max(fitX, fitY) : Math.min(fitX, fitY);
+    if (fit === ImageFit.ScaleDown)
+        scale = Math.min(scale, NATIVE_EMU_PER_PX); // never enlarge past native
+    const warnings = [];
+    const scaleRatio = scale / NATIVE_EMU_PER_PX; // rendered size vs the image's native pixels
+    if (scaleRatio > 1) {
+        warnings.push(`enlarged to ${Math.round(scaleRatio * 100)}% of native — will look soft; supply a larger image`);
+    }
+    else if (scaleRatio < MIN_SCALE) {
+        warnings.push(`shrunk to ${Math.round(scaleRatio * 100)}% of native — the slot is far smaller than the image`);
+    }
+    const shownW = imgW * scale;
+    const shownH = imgH * scale;
+    const inset = (fraction) => Math.round(fraction * SRC_RECT_FULL);
+    if (allowCrop && (shownW > frame.w || shownH > frame.h)) {
+        const cropped = 1 - (frame.w * frame.h) / (shownW * shownH);
+        if (cropped > SEVERE_MISMATCH_FRACTION) {
+            warnings.push(`fills the frame by cropping ${Math.round(cropped * 100)}% of the image (aspect mismatch)`);
+        }
         return {
-            kind: "crop",
-            left: shownW > frame.w ? inset((1 - frame.w / shownW) / 2) : 0,
-            top: shownH > frame.h ? inset((1 - frame.h / shownH) / 2) : 0,
+            geometry: {
+                placement: Placement.Crop,
+                left: shownW > frame.w ? inset((1 - frame.w / shownW) / 2) : 0,
+                top: shownH > frame.h ? inset((1 - frame.h / shownH) / 2) : 0,
+            },
+            warnings,
         };
     }
-    const scale = Math.min(fitX, fitY);
-    const cx = Math.round(imgW * scale);
-    const cy = Math.round(imgH * scale);
+    const empty = 1 - (shownW * shownH) / (frame.w * frame.h);
+    if (empty > SEVERE_MISMATCH_FRACTION) {
+        warnings.push(`leaves ${Math.round(empty * 100)}% of the frame empty (aspect mismatch or small image)`);
+    }
+    const cx = Math.round(shownW);
+    const cy = Math.round(shownH);
     return {
-        kind: "frame",
-        x: Math.round(frame.x + (frame.w - cx) / 2),
-        y: Math.round(frame.y + (frame.h - cy) / 2),
-        cx,
-        cy,
+        geometry: {
+            placement: Placement.Fit,
+            x: Math.round(frame.x + (frame.w - cx) / 2),
+            y: Math.round(frame.y + (frame.h - cy) / 2),
+            cx,
+            cy,
+        },
+        warnings,
     };
 }
 /**

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

@@ -1,8 +1,9 @@
 /**
- * Table fill — clones specimen rows in the template's `<a:tbl>` (row 0 header,
+ * Table fill — clones the template's specimen rows in `<a:tbl>` (row 0 header,
  * row 1 data, optional row 2 zebra) and fills each cell's first paragraph with
- * the corresponding StyledParagraph. Row cloning must stay engine-side because
- * it needs pptx-automizer DOM access.
+ * the corresponding StyledParagraph. Cells and `<a:gridCol>` entries are cloned
+ * or trimmed to the header count, sharing the template's total width. Row, cell,
+ * and grid cloning stay engine-side because they need pptx-automizer DOM access.
  */
 import type { TableFill } from "../types.js";
 /**