@tycoworks/tycoslide 0.7.0

package/dist/engine/dom.js

@@ -0,0 +1,354 @@
+/**
+ * Shared shape / DOM helpers used by every fill primitive.
+ *
+ * Two layers live here. First the low-level slide-XML substrate: `Tag` names the
+ * DrawingML / PresentationML elements, plus node utilities (element collection,
+ * run text access, run and paragraph builders) and hyperlink relationship
+ * management. Second, the higher-level StyledParagraph-rebuild machinery shared
+ * by fillText and fillTable: harvest specimen (pPr, rPr) buckets grouped by
+ * (bullet kind, level), detach the specimens, then build fresh paragraphs
+ * cloning the appropriate bucket. No fill strategy lives here — this is the
+ * substrate the fill modules build on.
+ */
+// ── XML Tag Constants ──────────────────────────────────────────────────────────
+/** DrawingML and PresentationML tag names used when manipulating slide XML. */
+export const Tag = {
+    RUN: "a:r",
+    TEXT: "a:t",
+    PARAGRAPH: "a:p",
+    RUN_PROPS: "a:rPr",
+    PARA_PROPS: "a:pPr",
+    BULLET_CHAR: "a:buChar",
+    BULLET_AUTO: "a:buAutoNum",
+    BULLET_NONE: "a:buNone",
+    LINE_BREAK: "a:br",
+    END_PARA_RUN_PROPS: "a:endParaRPr",
+    OFFSET: "a:off",
+    EXTENT: "a:ext",
+    BLIP: "a:blip",
+    SRC_RECT: "a:srcRect",
+    BLIP_FILL: "p:blipFill",
+    SPACE_BEFORE: "a:spcBef",
+    HLINK_CLICK: "a:hlinkClick",
+    RELATIONSHIP: "Relationship",
+    TABLE: "a:tbl",
+    TABLE_ROW: "a:tr",
+    TABLE_CELL: "a:tc",
+    TX_BODY: "a:txBody",
+    SOLID_FILL: "a:solidFill",
+    SRGB_CLR: "a:srgbClr",
+};
+/**
+ * OOXML attribute names and fixed attribute values. Element names live in `Tag`;
+ * this is the same discipline for the attributes and enumerated values written
+ * onto them, so no bare string literal leaks into the fill code.
+ */
+export const Attr = {
+    // rPr marks
+    BOLD: "b",
+    ITALIC: "i",
+    STRIKE: "strike",
+    UNDERLINE: "u",
+    ON: "1",
+    STRIKE_SINGLE: "sngStrike",
+    UNDERLINE_SINGLE: "sng",
+    // color
+    VALUE: "val",
+    // relationships
+    ID: "Id",
+    TYPE: "Type",
+    TARGET: "Target",
+    TARGET_MODE: "TargetMode",
+    EXTERNAL: "External",
+    HLINK_ID: "r:id",
+    // paragraph
+    LEVEL: "lvl",
+    // geometry (offset / extent)
+    X: "x",
+    Y: "y",
+    CX: "cx",
+    CY: "cy",
+    // srcRect edges
+    LEFT: "l",
+    TOP: "t",
+    RIGHT: "r",
+    BOTTOM: "b",
+    // whitespace preservation
+    XML_SPACE: "xml:space",
+    PRESERVE: "preserve",
+};
+/** True for a non-null, non-array object — the shared prefix of every `isXFill`. */
+export function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+// ── DOM Helpers ────────────────────────────────────────────────────────────────
+export function collectElements(parent, tagName) {
+    const out = [];
+    const live = parent.getElementsByTagName(tagName);
+    for (let i = 0; i < live.length; i++)
+        out.push(live[i]);
+    return out;
+}
+export function childrenByTag(parent, tagName) {
+    const out = [];
+    for (let i = 0; i < parent.childNodes.length; i++) {
+        const child = parent.childNodes[i];
+        if (child && child.nodeType === 1 && child.tagName === tagName)
+            out.push(child);
+    }
+    return out;
+}
+export function detach(node) {
+    if (node?.parentNode)
+        node.parentNode.removeChild(node);
+}
+export function runText(run) {
+    const t = run.getElementsByTagName(Tag.TEXT)[0];
+    return t ? (t.textContent ?? "") : "";
+}
+export function setRunTextPreservingStyle(run, text) {
+    let t = run.getElementsByTagName(Tag.TEXT)[0];
+    if (!t) {
+        t = run.ownerDocument.createElement(Tag.TEXT);
+        run.appendChild(t);
+    }
+    if (text !== text.trim())
+        t.setAttribute(Attr.XML_SPACE, Attr.PRESERVE);
+    else
+        t.removeAttribute(Attr.XML_SPACE);
+    t.textContent = text;
+}
+export function leadingDecorativePrefix(text) {
+    const m = /^[\s\p{P}\p{S}]+/u.exec(text);
+    return m ? m[0] : "";
+}
+// ── Run/Paragraph Builders ────────────────────────────────────────────────────
+export function buildRun(doc, cloneRPr, text) {
+    const r = doc.createElement(Tag.RUN);
+    if (cloneRPr)
+        r.appendChild(cloneRPr.cloneNode(true));
+    const t = doc.createElement(Tag.TEXT);
+    if (text !== text.trim())
+        t.setAttribute(Attr.XML_SPACE, Attr.PRESERVE);
+    t.textContent = text;
+    r.appendChild(t);
+    return r;
+}
+export function buildParagraph(doc, clonePPr, run) {
+    const p = doc.createElement(Tag.PARAGRAPH);
+    if (clonePPr)
+        p.appendChild(clonePPr.cloneNode(true));
+    p.appendChild(run);
+    return p;
+}
+// ── Relationship Management ──────────────────────────────────────────────────
+export const HYPERLINK_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
+export function addRelationship(relation, url) {
+    const existing = collectElements(relation, Tag.RELATIONSHIP);
+    let maxId = 0;
+    for (const rel of existing) {
+        const id = rel.getAttribute(Attr.ID);
+        const num = id ? parseInt(id.replace("rId", ""), 10) : 0;
+        if (num > maxId)
+            maxId = num;
+    }
+    const rId = `rId${maxId + 1}`;
+    const rel = relation.ownerDocument.createElement(Tag.RELATIONSHIP);
+    rel.setAttribute(Attr.ID, rId);
+    rel.setAttribute(Attr.TYPE, HYPERLINK_REL_TYPE);
+    rel.setAttribute(Attr.TARGET, url);
+    rel.setAttribute(Attr.TARGET_MODE, Attr.EXTERNAL);
+    relation.appendChild(rel);
+    return rId;
+}
+/**
+ * Replace all runs in a paragraph with a sequence of styled runs, cloning the
+ * first existing run's rPr as the template and layering per-run marks on top.
+ *
+ * Exported for tests; not part of the public engine surface (index.ts).
+ */
+export function setRichRuns(para, runs, relation) {
+    const existing = collectElements(para, Tag.RUN);
+    if (existing.length === 0)
+        return;
+    const tpl = existing[0];
+    const newNodes = [];
+    for (const run of runs) {
+        const clone = tpl.cloneNode(true);
+        const t = clone.getElementsByTagName(Tag.TEXT)[0];
+        if (t) {
+            t.textContent = run.text;
+            // The cloned template run may already carry xml:space — set or clear it to
+            // match the new text, mirroring setRunTextPreservingStyle.
+            if (run.text !== run.text.trim())
+                t.setAttribute(Attr.XML_SPACE, Attr.PRESERVE);
+            else
+                t.removeAttribute(Attr.XML_SPACE);
+        }
+        if (run.bold || run.italic || run.strikethrough || run.underline) {
+            let rPr = clone.getElementsByTagName(Tag.RUN_PROPS)[0];
+            if (!rPr) {
+                rPr = para.ownerDocument.createElement(Tag.RUN_PROPS);
+                clone.insertBefore(rPr, clone.firstChild);
+            }
+            if (run.bold)
+                rPr.setAttribute(Attr.BOLD, Attr.ON);
+            if (run.italic)
+                rPr.setAttribute(Attr.ITALIC, Attr.ON);
+            if (run.strikethrough)
+                rPr.setAttribute(Attr.STRIKE, Attr.STRIKE_SINGLE);
+            if (run.underline)
+                rPr.setAttribute(Attr.UNDERLINE, Attr.UNDERLINE_SINGLE);
+        }
+        if (run.color) {
+            let rPr = clone.getElementsByTagName(Tag.RUN_PROPS)[0];
+            if (!rPr) {
+                rPr = para.ownerDocument.createElement(Tag.RUN_PROPS);
+                clone.insertBefore(rPr, clone.firstChild);
+            }
+            const existingSolidFill = rPr.getElementsByTagName(Tag.SOLID_FILL)[0];
+            if (existingSolidFill)
+                rPr.removeChild(existingSolidFill);
+            const solidFill = para.ownerDocument.createElement(Tag.SOLID_FILL);
+            const srgbClr = para.ownerDocument.createElement(Tag.SRGB_CLR);
+            srgbClr.setAttribute(Attr.VALUE, run.color);
+            solidFill.appendChild(srgbClr);
+            rPr.appendChild(solidFill);
+        }
+        if (run.link && relation) {
+            let rPr = clone.getElementsByTagName(Tag.RUN_PROPS)[0];
+            if (!rPr) {
+                rPr = para.ownerDocument.createElement(Tag.RUN_PROPS);
+                clone.insertBefore(rPr, clone.firstChild);
+            }
+            const rId = addRelationship(relation, run.link);
+            const hlink = para.ownerDocument.createElement(Tag.HLINK_CLICK);
+            hlink.setAttribute(Attr.HLINK_ID, rId);
+            rPr.appendChild(hlink);
+        }
+        newNodes.push(clone);
+    }
+    for (const old of existing)
+        detach(old);
+    const endParaRPr = para.getElementsByTagName(Tag.END_PARA_RUN_PROPS)[0];
+    for (const nr of newNodes) {
+        if (endParaRPr)
+            para.insertBefore(nr, endParaRPr);
+        else
+            para.appendChild(nr);
+    }
+}
+function paragraphBulletKind(paragraph) {
+    const pPr = paragraph.getElementsByTagName(Tag.PARA_PROPS)[0];
+    if (!pPr)
+        return "inherit";
+    if (childrenByTag(pPr, Tag.BULLET_NONE).length > 0)
+        return "none";
+    if (childrenByTag(pPr, Tag.BULLET_CHAR).length > 0 || childrenByTag(pPr, Tag.BULLET_AUTO).length > 0) {
+        return "bullet";
+    }
+    return "inherit";
+}
+function paragraphLevel(paragraph) {
+    const ppr = paragraph.getElementsByTagName(Tag.PARA_PROPS)[0];
+    const lvl = ppr?.getAttribute(Attr.LEVEL);
+    return lvl ? Number(lvl) || 0 : 0;
+}
+function harvestStyles(specimen) {
+    const bullets = new Map();
+    let paras = null;
+    for (const p of specimen) {
+        const kind = paragraphBulletKind(p);
+        const lvl = paragraphLevel(p);
+        const firstRun = collectElements(p, Tag.RUN)[0];
+        const bucket = {
+            pPr: p.getElementsByTagName(Tag.PARA_PROPS)[0] ?? null,
+            rPr: firstRun ? (firstRun.getElementsByTagName(Tag.RUN_PROPS)[0] ?? null) : null,
+        };
+        if (kind === "bullet") {
+            if (!bullets.has(lvl))
+                bullets.set(lvl, bucket);
+        }
+        else {
+            if (paras == null)
+                paras = bucket;
+        }
+    }
+    return { bullets, paras };
+}
+function specimenBulletPara(specimen, level) {
+    for (const p of specimen) {
+        if (paragraphBulletKind(p) === "bullet" && paragraphLevel(p) === level)
+            return p;
+    }
+    return null;
+}
+function maybeOverrideLevel(paragraph, level) {
+    if (level == null)
+        return;
+    const ppr = paragraph.getElementsByTagName(Tag.PARA_PROPS)[0];
+    if (!ppr)
+        return;
+    if (level === 0)
+        ppr.removeAttribute(Attr.LEVEL);
+    else
+        ppr.setAttribute(Attr.LEVEL, String(level));
+}
+// ── Rebuild strategy (shared by fillText and fillTable) ──────────────────────
+export function rebuildParagraphs(shape, paragraphs, startIndex, relation, shapeName = "") {
+    const allParas = collectElements(shape, Tag.PARAGRAPH);
+    if (allParas.length === 0) {
+        throw new Error(`Shape "${shapeName}": has no paragraphs to rebuild from (need at least one specimen <a:p>).`);
+    }
+    const txBody = allParas[0].parentNode;
+    const specimen = allParas.slice(startIndex);
+    if (specimen.length === 0) {
+        throw new Error(`Shape "${shapeName}": startAt ${startIndex} is past the last paragraph (shape has ${allParas.length}).`);
+    }
+    const { bullets, paras } = harvestStyles(specimen);
+    const maxBulletLevel = bullets.size > 0 ? Math.max(...bullets.keys()) : -1;
+    const pickBullet = (lvl) => {
+        if (bullets.has(lvl))
+            return { bucket: bullets.get(lvl), effectiveLvl: lvl };
+        if (maxBulletLevel >= 0)
+            return { bucket: bullets.get(maxBulletLevel), effectiveLvl: maxBulletLevel };
+        return { bucket: null, effectiveLvl: lvl };
+    };
+    const plainBucket = paras ?? bullets.get(0) ?? null;
+    const firstBulletKey = bullets.has(0) ? 0 : maxBulletLevel;
+    const firstBullet = firstBulletKey >= 0 ? specimenBulletPara(specimen, firstBulletKey) : null;
+    const transitionSpcBef = firstBullet?.getElementsByTagName(Tag.PARA_PROPS)[0]?.getElementsByTagName(Tag.SPACE_BEFORE)[0] ?? null;
+    const applyTransitionSpacing = (paragraph) => {
+        if (!transitionSpcBef)
+            return;
+        const ppr = paragraph.getElementsByTagName(Tag.PARA_PROPS)[0];
+        if (!ppr)
+            return;
+        const old = ppr.getElementsByTagName(Tag.SPACE_BEFORE)[0];
+        if (old)
+            ppr.removeChild(old);
+        ppr.appendChild(transitionSpcBef.cloneNode(true));
+    };
+    for (const p of specimen)
+        detach(p);
+    const doc = shape.ownerDocument;
+    let prevWasBullet = false;
+    for (const para of paragraphs) {
+        if (!para.runs || para.runs.length === 0)
+            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;
+        const seedRun = buildRun(doc, bucket?.rPr ?? null, "");
+        const newPara = buildParagraph(doc, bucket?.pPr ?? null, seedRun);
+        maybeOverrideLevel(newPara, isBullet ? effectiveLvl : null);
+        if (!isBullet && prevWasBullet)
+            applyTransitionSpacing(newPara);
+        setRichRuns(newPara, para.runs, relation);
+        txBody.appendChild(newPara);
+        prevWasBullet = isBullet;
+    }
+}

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

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+import { type Slot, SlotType } from "../types.js";
+export type FillContext = {
+    layoutName: string;
+};
+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;
+}
+export declare const FILLERS: Record<SlotType, Filler<any>>;

package/dist/engine/fillers/filler.js

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+import { basename } from "node:path";
+import { ModifyImageHelper } from "pptx-automizer";
+import { SlotType } from "../types.js";
+import { fillImage, isImageFill } from "./image.js";
+import { fillTable, isTableFill } from "./table.js";
+import { fillTemplate, isTemplateFill } from "./template.js";
+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)]),
+    },
+    [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 }),
+            ]);
+        },
+    },
+    [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)]);
+        },
+    },
+    [SlotType.Image]: {
+        matches: isImageFill,
+        label: "ImageFill",
+        fill: (slide, slot, v) => slide.modifyElement(slot.shapeName, [
+            ModifyImageHelper.setRelationTarget(basename(v.path)),
+            (el) => fillImage(el, v, slot.shapeName),
+        ]),
+    },
+};

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

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+import { type ImageFill } from "../types.js";
+/**
+ * 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.
+ *
+ * `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;
+/** Discriminator for ImageFill values. */
+export declare function isImageFill(v: unknown): v is ImageFill;

package/dist/engine/fillers/image.js

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+import { readFileSync } from "node:fs";
+import { imageSize } from "image-size";
+import { Attr, isPlainObject, Tag } from "../dom.js";
+import { FitMode, SlotType } from "../types.js";
+/**
+ * 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.
+ *
+ * `image.path` is assumed absolute — the compiler / caller resolves it before the
+ * ImageFill reaches the engine.
+ */
+export function fillImage(shape, image, shapeName = "") {
+    const dims = imageSize(new Uint8Array(readFileSync(image.path)));
+    if (!dims.width || !dims.height) {
+        throw new Error(`Image shape "${shapeName}": could not read image dimensions from "${image.path}".`);
+    }
+    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 frame = {
+        x: Number(off.getAttribute(Attr.X)),
+        y: Number(off.getAttribute(Attr.Y)),
+        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);
+        return;
+    }
+    // contain: 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));
+}
+/**
+ * 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.
+ */
+function computeFit(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;
+        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,
+        };
+    }
+    const scale = Math.min(fitX, fitY);
+    const cx = Math.round(imgW * scale);
+    const cy = Math.round(imgH * scale);
+    return {
+        kind: "frame",
+        x: Math.round(frame.x + (frame.w - cx) / 2),
+        y: Math.round(frame.y + (frame.h - cy) / 2),
+        cx,
+        cy,
+    };
+}
+/**
+ * Write `<a:srcRect>` crop insets (left/top/right/bottom, in 1/100,000%),
+ * creating the element right after `<a:blip>` when the picture has none yet.
+ */
+function applySrcRect(shape, blipFill, l, t, r, b) {
+    let srcRect = blipFill.getElementsByTagName(Tag.SRC_RECT)[0];
+    if (!srcRect) {
+        srcRect = shape.ownerDocument.createElement(Tag.SRC_RECT);
+        const blip = blipFill.getElementsByTagName(Tag.BLIP)[0];
+        if (blip?.nextSibling)
+            blipFill.insertBefore(srcRect, blip.nextSibling);
+        else
+            blipFill.appendChild(srcRect);
+    }
+    srcRect.setAttribute(Attr.LEFT, String(l));
+    srcRect.setAttribute(Attr.TOP, String(t));
+    srcRect.setAttribute(Attr.RIGHT, String(r));
+    srcRect.setAttribute(Attr.BOTTOM, String(b));
+}
+/** Discriminator for ImageFill values. */
+export function isImageFill(v) {
+    return (isPlainObject(v) &&
+        v.type === SlotType.Image &&
+        typeof v.path === "string");
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Table fill — clones specimen rows in the template's `<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.
+ */
+import type { TableFill } from "../types.js";
+/**
+ * Fill a table shape by cloning specimen rows.
+ *
+ * Row layout in the template's `<a:tbl>`:
+ *   - Row 0: header specimen
+ *   - Row 1: data specimen
+ *   - Row 2 (optional): alternating-data specimen (zebra striping)
+ *
+ * Each cell's first paragraph is rebuilt from the corresponding
+ * StyledParagraph, so tables inherit rich-run/bullet support for free.
+ */
+export declare function fillTable(shape: any, table: TableFill, shapeName?: string): void;
+/** Discriminator for TableFill values. */
+export declare function isTableFill(v: unknown): v is TableFill;

package/dist/engine/fillers/table.js

@@ -0,0 +1,62 @@
+/**
+ * Table fill — clones specimen rows in the template's `<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.
+ */
+import { collectElements, isPlainObject, rebuildParagraphs, Tag } from "../dom.js";
+/**
+ * Fill a table shape by cloning specimen rows.
+ *
+ * Row layout in the template's `<a:tbl>`:
+ *   - Row 0: header specimen
+ *   - Row 1: data specimen
+ *   - Row 2 (optional): alternating-data specimen (zebra striping)
+ *
+ * Each cell's first paragraph is rebuilt from the corresponding
+ * StyledParagraph, so tables inherit rich-run/bullet support for free.
+ */
+export function fillTable(shape, table, shapeName = "") {
+    const tbl = shape.getElementsByTagName(Tag.TABLE)[0];
+    if (!tbl) {
+        throw new Error(`Table shape "${shapeName}": has no <a:tbl> element (is it actually a table?).`);
+    }
+    const rows = collectElements(tbl, Tag.TABLE_ROW);
+    if (rows.length < 2) {
+        throw new Error(`fillTable: template table has ${rows.length} row(s), need at least 2 (header + data specimen)`);
+    }
+    const headerTpl = rows[0];
+    // Only rows 0-2 are specimens (header, data, optional zebra); any further
+    // template rows are intentionally dropped — the specimen rows are re-cloned
+    // per data row below.
+    const dataTpls = rows.length > 2 ? [rows[1], rows[2]] : [rows[1]];
+    const fillRow = (tpl, cells) => {
+        const clone = tpl.cloneNode(true);
+        const tcs = collectElements(clone, Tag.TABLE_CELL);
+        // Fill min(cells, template cells): extra data columns beyond the template's
+        // cell count are intentionally ignored (column count is opt-in via
+        // slot.columns, enforced in the Table filler).
+        for (let i = 0; i < cells.length && i < tcs.length; i++) {
+            const txBody = tcs[i].getElementsByTagName(Tag.TX_BODY)[0] ?? tcs[i];
+            rebuildParagraphs(txBody, [cells[i]], 0, undefined, shapeName);
+        }
+        return clone;
+    };
+    const built = [];
+    built.push(fillRow(headerTpl, table.headers));
+    for (let r = 0; r < table.rows.length; r++) {
+        built.push(fillRow(dataTpls[r % dataTpls.length], table.rows[r]));
+    }
+    for (const row of rows)
+        tbl.removeChild(row);
+    for (const row of built)
+        tbl.appendChild(row);
+}
+/** Discriminator for TableFill values. */
+export function isTableFill(v) {
+    return (isPlainObject(v) &&
+        "headers" in v &&
+        "rows" in v &&
+        Array.isArray(v.headers) &&
+        Array.isArray(v.rows));
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Text-template fill — fills each visual line in place from its template
+ * segments. A visual line starts at either a paragraph boundary (`<a:p>`) or a
+ * soft line break (`<a:br/>`); template line i fills visual line i, 1:1. Styles
+ * are never read or changed: coalesce same-style runs, then a uniform line takes
+ * the substituted text directly, while a multi-style line is matched against the
+ * sample to place each variable's value in the run carrying its style.
+ */
+import type { TemplateFill } from "../types.js";
+/**
+ * Fill a text shape from its template segments — styles are never read or
+ * changed. Template line i fills the shape's visual line i, 1:1, via
+ * `fillLineFromSegments`: coalesce same-style runs, then a uniform line takes the
+ * substituted text directly, while a multi-style line is matched against the
+ * sample to place each variable's value in the run carrying its style. A template
+ * with more lines than the shape has visual lines is an authoring error (throw);
+ * fewer lines fill the covered lines and leave the rest untouched.
+ */
+export declare function fillTemplate(shape: any, fill: TemplateFill, shapeName?: string): void;
+/** Discriminator for TemplateFill values. */
+export declare function isTemplateFill(v: unknown): v is TemplateFill;
+/**
+ * Merge adjacent same-style runs across a whole paragraph. Thin wrapper over
+ * `coalesceRunList` operating on the paragraph's direct `<a:r>` children.
+ * Exported for tests.
+ */
+export declare function coalesceSameStyleRuns(para: any): void;