@deckflow/deckuse 1.2.1 → 1.3.0

package/dist/pptx/mutations.js

@@ -0,0 +1,1111 @@
+import { err, ok, parseLength, } from '../core/index.js';
+import { resolveTarget, resolveToRef, cNvPrIdOf } from './addressing.js';
+import { computeAlignUpdates, readBBox, writeBBox } from './align.js';
+import { assertWritable } from './edition.js';
+import { addElement, duplicateElement, normalizeTableRows, updateChart } from './elements.js';
+import { findIndexed, matchesSelector, mergeSlides, slidesForItem } from './indexer.js';
+import { detachPictureAndCleanup, loadPictureBytes, replacePictureMedia } from './picture.js';
+import { detachMediaAndCleanup } from './media.js';
+import { applyShapeProperties, assertChartProperties } from './properties.js';
+import { mapDottedProperties } from './resolve-properties.js';
+import { addSlide, duplicateSlide, ensureNotes, removeSlide, setSlideLayout } from './slides.js';
+import { resolveLayoutRef } from './layout-ref.js';
+import { lengthContextFor } from './slide-size.js';
+import { normalizePlaceholderRole } from './placeholder-role.js';
+import { applyTableCellProperties, applyTableLayout, applyTableProperties } from './table.js';
+import { measureTableLayout, tableHeightMayClipDiagnostic } from './table-measure.js';
+import { REL, NS, attr, children, cNvPr, descendants, first, root, setNodeText, setNodeTextBlocks, } from './xml.js';
+const mapTextRun = (run) => {
+    const styled = { text: run.text };
+    if (run.fontSize !== undefined)
+        styled.fontSize = run.fontSize;
+    if (run.fontFamily !== undefined)
+        styled.fontFamily = run.fontFamily;
+    if (run.textColor !== undefined)
+        styled.textColor = run.textColor;
+    if (run.bold !== undefined)
+        styled.bold = run.bold;
+    if (run.italic !== undefined)
+        styled.italic = run.italic;
+    if (run.underline !== undefined)
+        styled.underline = run.underline;
+    return styled;
+};
+const mapTextBlock = (block) => {
+    const styled = {};
+    const runs = block['runs'];
+    if (Array.isArray(runs)) {
+        styled.runs = runs.map((run) => mapTextRun(run));
+    }
+    else if (typeof block['text'] === 'string') {
+        styled.text = block['text'];
+    }
+    if (typeof block['fontSize'] === 'number')
+        styled.fontSize = block['fontSize'];
+    if (typeof block['fontFamily'] === 'string')
+        styled.fontFamily = block['fontFamily'];
+    if (typeof block['textColor'] === 'string')
+        styled.textColor = block['textColor'];
+    if (typeof block['bold'] === 'boolean')
+        styled.bold = block['bold'];
+    if (typeof block['italic'] === 'boolean')
+        styled.italic = block['italic'];
+    if (typeof block['underline'] === 'boolean')
+        styled.underline = block['underline'];
+    if (typeof block['align'] === 'string')
+        styled.align = block['align'];
+    return styled;
+};
+const SHAPE_LOCAL_NAMES = new Set(['sp', 'pic', 'graphicFrame', 'cxnSp', 'grpSp']);
+const directChild = (node, localName) => children(node).find((child) => child.localName === localName);
+const resolveLengthField = (archive, value, axis) => {
+    if (value === undefined)
+        return undefined;
+    return parseLength(value, lengthContextFor(archive, axis));
+};
+const normalizeTransformFields = (archive, fields) => {
+    const out = { ...fields };
+    for (const key of ['x', 'width']) {
+        if (out[key] !== undefined)
+            out[key] = resolveLengthField(archive, out[key], 'x');
+    }
+    for (const key of ['y', 'height']) {
+        if (out[key] !== undefined && out[key] !== 'auto')
+            out[key] = resolveLengthField(archive, out[key], 'y');
+    }
+    return out;
+};
+export const shapeByCNvPrId = (doc, id) => descendants(doc).find((node) => node.localName != null &&
+    SHAPE_LOCAL_NAMES.has(node.localName) &&
+    attr(cNvPr(node), 'id') === id);
+export const nodeFor = (doc, item) => {
+    if (['slide', 'notes', 'master', 'layout', 'theme'].includes(item.kind))
+        return root(doc);
+    if (item.kind === 'tableCell') {
+        const rawTableId = item.location?.['tableId'], tableId = typeof rawTableId === 'string' ? rawTableId : '';
+        // elementId is `${slideId}:${ancestorPath}` — strip slide prefix, then take the leaf cNvPr id.
+        const afterSlide = tableId.includes(':') ? tableId.slice(tableId.indexOf(':') + 1) : tableId;
+        const tableTail = afterSlide.split('.').at(-1) ?? afterSlide;
+        if (!tableTail)
+            return undefined;
+        const table = shapeByCNvPrId(doc, tableTail);
+        if (!table)
+            return;
+        const row = descendants(table, 'tr')[Number(item.location?.['row'])];
+        return row ? descendants(row, 'tc')[Number(item.location?.['column'])] : undefined;
+    }
+    const id = cNvPrIdOf(item);
+    return id ? shapeByCNvPrId(doc, id) : undefined;
+};
+const placeholderOf = (node) => {
+    const ph = first(node, 'ph');
+    if (!ph)
+        return undefined;
+    const type = attr(ph, 'type') ?? 'body';
+    const idx = attr(ph, 'idx');
+    return { type, ...(idx !== undefined ? { idx } : {}) };
+};
+const findPlaceholderXfrm = (doc, type, idx) => {
+    for (const shape of descendants(doc)) {
+        if (!shape.localName || !SHAPE_LOCAL_NAMES.has(shape.localName))
+            continue;
+        const ph = placeholderOf(shape);
+        if (!ph)
+            continue;
+        if (idx !== undefined && ph.idx === idx) {
+            const xfrm = first(shape, 'xfrm');
+            if (xfrm)
+                return xfrm;
+            continue;
+        }
+        if (ph.type === type && (idx === undefined || ph.idx === undefined)) {
+            const xfrm = first(shape, 'xfrm');
+            if (xfrm)
+                return xfrm;
+        }
+    }
+    return undefined;
+};
+/** Layout/master xfrm for placeholders that omit a local transform. */
+const inheritedXfrm = (archive, slidePart, node) => {
+    const ph = placeholderOf(node);
+    if (!ph)
+        return undefined;
+    const layoutPart = archive
+        .getRelationships(slidePart)
+        .find((rel) => rel.type === REL.layout)?.resolvedTarget;
+    if (!layoutPart || !archive.getPart(layoutPart))
+        return undefined;
+    const fromLayout = findPlaceholderXfrm(archive.readXml(layoutPart), ph.type, ph.idx);
+    if (fromLayout)
+        return fromLayout;
+    const masterPart = archive
+        .getRelationships(layoutPart)
+        .find((rel) => rel.type === REL.slideMaster)?.resolvedTarget;
+    if (!masterPart || !archive.getPart(masterPart))
+        return undefined;
+    return findPlaceholderXfrm(archive.readXml(masterPart), ph.type, ph.idx);
+};
+const copyXfrmInto = (doc, seed, ns, qname) => {
+    const x = doc.createElementNS(ns, qname);
+    for (const name of ['rot', 'flipH', 'flipV']) {
+        const value = seed.getAttribute(name);
+        if (value != null)
+            x.setAttribute(name, value);
+    }
+    for (const [local, q] of [
+        ['off', 'a:off'],
+        ['ext', 'a:ext'],
+        ['chOff', 'a:chOff'],
+        ['chExt', 'a:chExt'],
+    ]) {
+        const src = directChild(seed, local) ?? first(seed, local);
+        if (!src)
+            continue;
+        const child = doc.createElementNS(NS.a, q);
+        for (const name of ['x', 'y', 'cx', 'cy']) {
+            const value = src.getAttribute(name);
+            if (value != null)
+                child.setAttribute(name, value);
+        }
+        x.appendChild(child);
+    }
+    return x;
+};
+const ensureSpPrForTransform = (node) => {
+    const existing = directChild(node, 'spPr');
+    if (existing)
+        return existing;
+    const doc = node.ownerDocument;
+    if (!doc)
+        throw new Error('Element has no document');
+    const prefix = node.prefix ? `${node.prefix}:` : 'p:';
+    const spPr = doc.createElementNS(NS.p, `${prefix}spPr`);
+    const after = children(node).find((child) => child.localName?.startsWith('nv'));
+    if (after?.nextSibling)
+        node.insertBefore(spPr, after.nextSibling);
+    else if (after)
+        node.appendChild(spPr);
+    else if (node.firstChild)
+        node.insertBefore(spPr, node.firstChild);
+    else
+        node.appendChild(spPr);
+    return spPr;
+};
+const ensureGrpSpPr = (node) => {
+    const existing = directChild(node, 'grpSpPr');
+    if (existing)
+        return existing;
+    const doc = node.ownerDocument;
+    if (!doc)
+        throw new Error('Element has no document');
+    const prefix = node.prefix ? `${node.prefix}:` : 'p:';
+    const grpSpPr = doc.createElementNS(NS.p, `${prefix}grpSpPr`);
+    const after = children(node).find((child) => child.localName?.startsWith('nv'));
+    if (after?.nextSibling)
+        node.insertBefore(grpSpPr, after.nextSibling);
+    else if (after)
+        node.appendChild(grpSpPr);
+    else if (node.firstChild)
+        node.insertBefore(grpSpPr, node.firstChild);
+    else
+        node.appendChild(grpSpPr);
+    return grpSpPr;
+};
+const ensureXfrm = (node, archive, partUri) => {
+    const existing = (() => {
+        if (node.localName === 'graphicFrame')
+            return directChild(node, 'xfrm');
+        if (node.localName === 'grpSp') {
+            const grpSpPr = directChild(node, 'grpSpPr');
+            return grpSpPr ? directChild(grpSpPr, 'xfrm') : undefined;
+        }
+        const spPr = directChild(node, 'spPr');
+        return spPr ? directChild(spPr, 'xfrm') : undefined;
+    })();
+    if (existing)
+        return existing;
+    const doc = node.ownerDocument;
+    if (!doc)
+        throw new Error('Element has no document');
+    const seed = archive && partUri ? inheritedXfrm(archive, partUri, node) : undefined;
+    const usePresentationXfrm = node.localName === 'graphicFrame';
+    const ns = usePresentationXfrm ? NS.p : NS.a;
+    const qname = usePresentationXfrm ? 'p:xfrm' : 'a:xfrm';
+    const x = seed ? copyXfrmInto(doc, seed, ns, qname) : doc.createElementNS(ns, qname);
+    if (node.localName === 'graphicFrame') {
+        const after = children(node).find((child) => child.localName?.startsWith('nv'));
+        if (after?.nextSibling)
+            node.insertBefore(x, after.nextSibling);
+        else if (after)
+            node.appendChild(x);
+        else if (node.firstChild)
+            node.insertBefore(x, node.firstChild);
+        else
+            node.appendChild(x);
+        return x;
+    }
+    const container = node.localName === 'grpSp' ? ensureGrpSpPr(node) : ensureSpPrForTransform(node);
+    if (container.firstChild)
+        container.insertBefore(x, container.firstChild);
+    else
+        container.appendChild(x);
+    return x;
+};
+const ensureChild = (parent, localName, qname, beforeLocalNames) => {
+    const existing = directChild(parent, localName);
+    if (existing)
+        return existing;
+    const doc = parent.ownerDocument;
+    if (!doc)
+        throw new Error('Element has no document');
+    const child = doc.createElementNS(NS.a, qname);
+    const before = children(parent).find((item) => item.localName != null && beforeLocalNames.includes(item.localName));
+    if (before)
+        parent.insertBefore(child, before);
+    else
+        parent.appendChild(child);
+    return child;
+};
+const transform = (node, t, opts) => {
+    const x = ensureXfrm(node, opts?.archive, opts?.partUri);
+    const needsOff = typeof t['x'] === 'number' || typeof t['y'] === 'number';
+    const needsExt = typeof t['width'] === 'number' || typeof t['height'] === 'number';
+    const off = needsOff
+        ? ensureChild(x, 'off', 'a:off', ['ext', 'chOff', 'chExt'])
+        : (directChild(x, 'off') ?? first(x, 'off'));
+    const ext = needsExt
+        ? ensureChild(x, 'ext', 'a:ext', ['chOff', 'chExt'])
+        : (directChild(x, 'ext') ?? first(x, 'ext'));
+    if (needsOff && off) {
+        if (typeof t['x'] === 'number')
+            off.setAttribute('x', String(Math.round(t['x'])));
+        else if (!off.hasAttribute('x'))
+            off.setAttribute('x', '0');
+        if (typeof t['y'] === 'number')
+            off.setAttribute('y', String(Math.round(t['y'])));
+        else if (!off.hasAttribute('y'))
+            off.setAttribute('y', '0');
+    }
+    if (needsExt && ext) {
+        if (typeof t['width'] === 'number')
+            ext.setAttribute('cx', String(Math.round(t['width'])));
+        else if (!ext.hasAttribute('cx'))
+            ext.setAttribute('cx', '0');
+        if (typeof t['height'] === 'number')
+            ext.setAttribute('cy', String(Math.round(t['height'])));
+        else if (!ext.hasAttribute('cy'))
+            ext.setAttribute('cy', '0');
+    }
+    if (typeof t['rotation'] === 'number')
+        x.setAttribute('rot', String(Math.round(t['rotation'] * 60000)));
+    if (typeof t['flipHorizontal'] === 'boolean' || typeof t['flipX'] === 'boolean') {
+        const flip = Boolean(t['flipHorizontal'] ?? t['flipX']);
+        if (flip)
+            x.setAttribute('flipH', '1');
+        else
+            x.removeAttribute('flipH');
+    }
+    if (typeof t['flipVertical'] === 'boolean' || typeof t['flipY'] === 'boolean') {
+        const flip = Boolean(t['flipVertical'] ?? t['flipY']);
+        if (flip)
+            x.setAttribute('flipV', '1');
+        else
+            x.removeAttribute('flipV');
+    }
+};
+const indexSlidePartForNotes = (archive, item) => {
+    if (!item.slideId)
+        return undefined;
+    const presentation = archive.readXml('/ppt/presentation.xml');
+    const rels = archive.getRelationships('/ppt/presentation.xml');
+    for (const sld of descendants(presentation, 'sldId')) {
+        if (sld.namespaceURI && sld.namespaceURI !== NS.p)
+            continue;
+        const id = attr(sld, 'id');
+        if (id !== item.slideId)
+            continue;
+        const rid = sld.getAttributeNS(NS.r, 'id') ?? attr(sld, 'r:id');
+        const rel = rels.find((r) => r.id === rid);
+        return rel?.resolvedTarget;
+    }
+    return undefined;
+};
+const materializeNotes = (archive, item) => {
+    if (item.kind !== 'notes')
+        return ok(item);
+    if (item.partUri && archive.getPart(item.partUri))
+        return ok(item);
+    const slidePart = typeof item.location?.['slidePart'] === 'string'
+        ? item.location['slidePart']
+        : indexSlidePartForNotes(archive, item);
+    if (!slidePart)
+        return err('ELEMENT_NOT_FOUND', `Cannot locate slide for notes ${item.ref.elementId ?? ''}`);
+    const partUri = ensureNotes(archive, slidePart);
+    return ok({
+        ...item,
+        partUri,
+        ref: { ...item.ref, path: partUri },
+        location: { ...item.location, partUri, slidePart, region: 'speakerNotes' },
+    });
+};
+const writeText = (archive, item, text, diagnostics) => {
+    const gated = assertWritable(item, archive);
+    if (!gated.ok)
+        return gated;
+    if (item.kind === 'chart' && typeof item.payload?.['chartPart'] === 'string') {
+        const result = updateChart(archive, item.payload['chartPart'], { title: text });
+        if (result.workbook)
+            diagnostics.push({
+                severity: 'warning',
+                code: 'EMBEDDED_WORKBOOK_NOT_SYNCHRONIZED',
+                message: 'Chart cache changed; embedded workbook was not modified',
+            });
+        return ok(undefined, diagnostics);
+    }
+    const notesItem = materializeNotes(archive, item);
+    if (!notesItem.ok)
+        return notesItem;
+    const target = notesItem.value;
+    const doc = archive.readXml(target.partUri), node = nodeFor(doc, target);
+    if (!node)
+        return err('ELEMENT_NOT_FOUND', `Element XML node was not found: ${target.ref.elementId ?? target.ref.path ?? ''}`);
+    setNodeText(node, text);
+    archive.writeXml(target.partUri, doc);
+    return ok(undefined, diagnostics);
+};
+const isDescendantOf = (item, ancestorId) => {
+    if (item.parentId === ancestorId)
+        return true;
+    const elementId = item.ref.elementId;
+    return Boolean(elementId?.startsWith(`${ancestorId}.`));
+};
+/** Without a selector, skip ancestor elements whose text aggregates descendant matches. */
+const narrowReplaceTextCandidates = (candidates) => {
+    if (candidates.length <= 1)
+        return candidates;
+    return candidates.filter((item) => {
+        const id = item.ref.elementId;
+        if (!id)
+            return true;
+        return !candidates.some((other) => other.ref.elementId !== id && isDescendantOf(other, id));
+    });
+};
+const applyReplaceText = (command, archive, index) => {
+    if (command.regex) {
+        try {
+            new RegExp(command.find, 'u');
+        }
+        catch (cause) {
+            return err('INVALID_COMMAND', cause instanceof Error ? cause.message : 'Invalid replaceText regex');
+        }
+    }
+    const matches = (text) => command.regex ? new RegExp(command.find, 'u').test(text) : text.includes(command.find);
+    const replaced = (text) => command.regex
+        ? text.replace(new RegExp(command.find, 'gu'), command.replace)
+        : text.split(command.find).join(command.replace);
+    let candidates = index.elements.filter((item) => Boolean(item.text?.length) &&
+        (!command.selector || matchesSelector(item, command.selector)) &&
+        matches(item.text ?? ''));
+    if (!command.selector)
+        candidates = narrowReplaceTextCandidates(candidates);
+    const limit = command.limit ?? 1000;
+    const selected = candidates.slice(0, limit);
+    const diagnostics = [];
+    const refs = [];
+    const slidePages = [];
+    for (const item of selected) {
+        const next = replaced(item.text ?? '');
+        if (next === item.text)
+            continue;
+        const written = writeText(archive, item, next, diagnostics);
+        if (!written.ok)
+            return written;
+        refs.push(item.ref);
+        slidePages.push(...slidesForItem(index, item));
+    }
+    return ok({
+        changed: refs.length > 0,
+        matched: refs.length,
+        refs,
+        slides: mergeSlides(slidePages),
+        diagnostics,
+    }, diagnostics);
+};
+const resolveCommandRef = (command, index) => {
+    if (command.type === 'replaceText')
+        return err('INVALID_COMMAND', 'replaceText does not resolve a single ref');
+    if (command.type === 'addSlide' || command.type === 'addShape')
+        return err('INVALID_COMMAND', 'addSlide/addShape resolve separately');
+    if (command.type === 'xfrmSet') {
+        const target = command.target ??
+            (command.slide !== undefined && command.shape !== undefined
+                ? `slide:${command.slide}/shape:${command.shape}`
+                : undefined);
+        if (!target)
+            return err('INVALID_COMMAND', 'xfrmSet requires target or slide+shape');
+        const resolved = resolveTarget(index, target);
+        if (!resolved.ok)
+            return resolved;
+        return {
+            ok: true,
+            value: {
+                ref: resolved.value.item.ref,
+                item: resolved.value.item,
+                target: resolved.value.target,
+                parsed: resolved.value.parsed,
+            },
+            diagnostics: [],
+        };
+    }
+    if (command.type === 'zMove' || command.type === 'set' || command.type === 'setTableLayout') {
+        const resolved = resolveTarget(index, command.target);
+        if (!resolved.ok)
+            return resolved;
+        return {
+            ok: true,
+            value: {
+                ref: resolved.value.item.ref,
+                item: resolved.value.item,
+                target: resolved.value.target,
+                parsed: resolved.value.parsed,
+            },
+            diagnostics: [],
+        };
+    }
+    if (command.type === 'add') {
+        const got = resolveToRef(index, {
+            ...(command.parent !== undefined ? { ref: command.parent } : {}),
+            ...(command.target !== undefined ? { target: command.target } : {}),
+        });
+        if (!got.ok)
+            return got;
+        const item = got.value.resolved?.item ?? findIndexed(index, got.value.ref);
+        if (!item)
+            return err('ELEMENT_NOT_FOUND', 'Element reference was not found');
+        return {
+            ok: true,
+            value: {
+                ref: item.ref,
+                item,
+                ...(got.value.resolved?.target !== undefined ? { target: got.value.resolved.target } : {}),
+                ...(got.value.resolved?.parsed !== undefined ? { parsed: got.value.resolved.parsed } : {}),
+            },
+            diagnostics: [],
+        };
+    }
+    const got = resolveToRef(index, {
+        ...('ref' in command && command.ref !== undefined ? { ref: command.ref } : {}),
+        ...('target' in command && command.target !== undefined ? { target: command.target } : {}),
+    });
+    if (!got.ok)
+        return got;
+    // Prefer the item from target resolution so synthetic notes (not yet in the index) work.
+    const item = got.value.resolved?.item ?? findIndexed(index, got.value.ref);
+    if (!item)
+        return err('ELEMENT_NOT_FOUND', 'Element reference was not found');
+    return {
+        ok: true,
+        value: {
+            ref: item.ref,
+            item,
+            ...(got.value.resolved?.target !== undefined ? { target: got.value.resolved.target } : {}),
+            ...(got.value.resolved?.parsed !== undefined ? { parsed: got.value.resolved.parsed } : {}),
+        },
+        diagnostics: [],
+    };
+};
+/** Narrow a shape node to paragraph or run when the target path includes those segments. */
+const focusMutationNode = (shape, parsed) => {
+    if (!parsed?.focus)
+        return ok(shape);
+    if (parsed.focus === 'paragraph' && parsed.paragraph !== undefined) {
+        const paragraphs = descendants(shape, 'p');
+        const p = paragraphs[parsed.paragraph];
+        if (!p)
+            return err('TARGET_NOT_FOUND', `paragraph:${parsed.paragraph} not found on ${parsed.raw}`, [], { target: parsed.raw });
+        return ok(p);
+    }
+    if (parsed.focus === 'run' && parsed.run !== undefined) {
+        const runs = descendants(shape, 'r');
+        const run = runs[parsed.run];
+        if (!run)
+            return err('TARGET_NOT_FOUND', `run:${parsed.run} not found on ${parsed.raw}`, [], {
+                target: parsed.raw,
+            });
+        return ok(run);
+    }
+    return ok(shape);
+};
+const shapeTypeToElement = (shapeType, fields) => {
+    const base = { ...fields };
+    switch (shapeType) {
+        case 'text':
+            return {
+                ...base,
+                kind: 'textbox',
+                type: 'textbox',
+                preset: 'rect',
+                text: typeof fields['text'] === 'string' ? fields['text'] : '',
+            };
+        case 'rect':
+            return { ...base, kind: 'shape', type: 'shape', preset: 'rect' };
+        case 'rounded-rect':
+            return {
+                ...base,
+                kind: 'shape',
+                type: 'shape',
+                preset: 'roundRect',
+                ...(typeof fields['cornerRadius'] === 'number'
+                    ? { cornerRadius: fields['cornerRadius'] }
+                    : {}),
+            };
+        case 'ellipse':
+            return { ...base, kind: 'shape', type: 'shape', preset: 'ellipse' };
+        case 'line':
+        case 'connector':
+            return { ...base, kind: 'connector', type: 'connector', preset: 'line' };
+        case 'elbow':
+        case 'elbow-connector':
+            return { ...base, kind: 'connector', type: 'connector', preset: 'bentConnector3' };
+        case 'curved-connector':
+            return { ...base, kind: 'connector', type: 'connector', preset: 'curvedConnector3' };
+        case 'arrow':
+        case 'right-arrow':
+            return { ...base, kind: 'shape', type: 'shape', preset: 'rightArrow', txBox: false };
+        case 'left-arrow':
+            return { ...base, kind: 'shape', type: 'shape', preset: 'leftArrow', txBox: false };
+        case 'up-arrow':
+            return { ...base, kind: 'shape', type: 'shape', preset: 'upArrow', txBox: false };
+        case 'down-arrow':
+            return { ...base, kind: 'shape', type: 'shape', preset: 'downArrow', txBox: false };
+        case 'chevron':
+            return { ...base, kind: 'shape', type: 'shape', preset: 'chevron', txBox: false };
+        case 'pentagon':
+            return { ...base, kind: 'shape', type: 'shape', preset: 'homePlate', txBox: false };
+        case 'trapezoid':
+            return { ...base, kind: 'shape', type: 'shape', preset: 'trapezoid', txBox: false };
+        case 'triangle':
+            return { ...base, kind: 'shape', type: 'shape', preset: 'triangle', txBox: false };
+        case 'rt-triangle':
+            return { ...base, kind: 'shape', type: 'shape', preset: 'rtTriangle', txBox: false };
+        case 'circular-arrow':
+            return { ...base, kind: 'shape', type: 'shape', preset: 'circularArrow', txBox: false };
+        case 'curved-right-arrow':
+            return { ...base, kind: 'shape', type: 'shape', preset: 'curvedRightArrow', txBox: false };
+        case 'curved-left-arrow':
+            return { ...base, kind: 'shape', type: 'shape', preset: 'curvedLeftArrow', txBox: false };
+        case 'image':
+            return {
+                ...base,
+                kind: 'picture',
+                type: 'picture',
+                ...(typeof fields['file'] === 'string' ? { path: fields['file'] } : {}),
+            };
+        case 'group':
+            return { ...base, kind: 'group', type: 'group' };
+        case 'table':
+            return {
+                ...base,
+                kind: 'table',
+                type: 'table',
+                rows: Array.isArray(fields['rows']) ? fields['rows'] : [['']],
+            };
+        case 'chart':
+            return {
+                ...base,
+                kind: 'chart',
+                type: 'chart',
+                ...(typeof fields['chartType'] === 'string' ? { chartType: fields['chartType'] } : {}),
+                ...(fields['data'] !== undefined ? { data: fields['data'] } : {}),
+            };
+        case 'video':
+            return {
+                ...base,
+                kind: 'video',
+                type: 'video',
+                ...(typeof fields['file'] === 'string' ? { path: fields['file'] } : {}),
+            };
+        case 'audio':
+            return {
+                ...base,
+                kind: 'audio',
+                type: 'audio',
+                ...(typeof fields['file'] === 'string' ? { path: fields['file'] } : {}),
+            };
+    }
+};
+const applyZMove = (doc, node, command, index) => {
+    const parent = node.parentNode;
+    if (!parent)
+        return err('INVALID_COMMAND', 'Shape has no parent for z-order move');
+    const siblings = children(parent).filter((child) => child.localName != null && SHAPE_LOCAL_NAMES.has(child.localName));
+    if (!siblings.includes(node))
+        return err('INVALID_COMMAND', 'Shape is not a direct child of the shape tree');
+    const findSibling = (target) => {
+        const resolved = resolveTarget(index, target);
+        if (!resolved.ok)
+            return resolved;
+        const other = nodeFor(doc, resolved.value.item);
+        if (!other || !siblings.includes(other))
+            return err('TARGET_NOT_FOUND', `z-order reference not on same parent: ${target}`, [], {
+                target,
+            });
+        return { ok: true, value: other, diagnostics: [] };
+    };
+    parent.removeChild(node);
+    if (command.toFront) {
+        parent.appendChild(node);
+        return ok(undefined);
+    }
+    if (command.toBack) {
+        const firstShape = children(parent).find((child) => child.localName != null && SHAPE_LOCAL_NAMES.has(child.localName));
+        if (firstShape)
+            parent.insertBefore(node, firstShape);
+        else
+            parent.appendChild(node);
+        return ok(undefined);
+    }
+    if (command.above) {
+        const other = findSibling(command.above);
+        if (!other.ok)
+            return other;
+        if (other.value.nextSibling)
+            parent.insertBefore(node, other.value.nextSibling);
+        else
+            parent.appendChild(node);
+        return ok(undefined);
+    }
+    if (command.below) {
+        const other = findSibling(command.below);
+        if (!other.ok)
+            return other;
+        parent.insertBefore(node, other.value);
+        return ok(undefined);
+    }
+    return err('INVALID_COMMAND', 'zMove requires --above, --below, --to-front, or --to-back');
+};
+export async function mutate(command, archive, index) {
+    if (command.type === 'replaceText')
+        return applyReplaceText(command, archive, index);
+    if (command.type === 'addSlide') {
+        const slides = index.elements.filter((item) => item.kind === 'slide');
+        let layout;
+        if (command.layout) {
+            const resolved = resolveLayoutRef(archive, index, command.layout, {
+                allowBlankFallback: true,
+            });
+            if (!resolved.ok)
+                return resolved;
+            layout = resolved.value;
+        }
+        // Prefer an explicit layout; otherwise inherit the layout of the anchor slide
+        // (or the first slide) so blank pages still bind to a slideLayout.
+        if (!layout) {
+            const anchor = command.after !== undefined && command.after > 0 ? slides[command.after - 1] : slides[0];
+            if (anchor) {
+                const rels = archive.getRelationships(anchor.partUri);
+                const layoutRel = rels.find((r) => r.type === REL.layout);
+                layout = layoutRel?.resolvedTarget;
+            }
+        }
+        const partUri = addSlide(archive, undefined, layout, command.after);
+        return ok({
+            changed: true,
+            partUri,
+            slides: [],
+            changedParts: [partUri, '/ppt/presentation.xml'],
+        });
+    }
+    if (command.type === 'setSlideLayout') {
+        const slides = index.elements.filter((item) => item.kind === 'slide');
+        const slide = slides[command.slide - 1];
+        if (!slide)
+            return err('TARGET_NOT_FOUND', `slide:${command.slide} does not exist`, [], {
+                target: `slide:${command.slide}`,
+                hint: 'Run deckuse list slides --json.',
+            });
+        const resolved = resolveLayoutRef(archive, index, command.layout);
+        if (!resolved.ok)
+            return resolved;
+        const layoutPart = resolved.value;
+        if (!layoutPart)
+            return err('TARGET_NOT_FOUND', `Layout not found: ${command.layout}`, [], {
+                target: command.layout,
+            });
+        const changed = setSlideLayout(archive, slide.partUri, layoutPart);
+        return ok({
+            changed,
+            slides: [command.slide],
+            changedTargets: [`slide:${command.slide}`],
+            changedParts: changed ? [slide.partUri] : [],
+        });
+    }
+    if (command.type === 'addShape') {
+        const slides = index.elements.filter((item) => item.kind === 'slide');
+        const slide = slides[command.slide - 1];
+        if (!slide)
+            return err('TARGET_NOT_FOUND', `slide:${command.slide} does not exist`, [], {
+                target: `slide:${command.slide}`,
+            });
+        let role;
+        if (command.role !== undefined) {
+            const normalized = normalizePlaceholderRole(command.role);
+            if (!normalized.ok)
+                return err('INVALID_COMMAND', normalized.message);
+            role = normalized.type;
+        }
+        const doc = archive.readXml(slide.partUri);
+        const parent = first(doc, 'spTree') ?? root(doc);
+        const geom = normalizeTransformFields(archive, {
+            ...(command.x !== undefined ? { x: command.x } : {}),
+            ...(command.y !== undefined ? { y: command.y } : {}),
+            ...(command.width !== undefined ? { width: command.width } : {}),
+            ...(command.height !== undefined ? { height: command.height } : {}),
+        });
+        const element = shapeTypeToElement(command.shapeType, {
+            ...(command.name !== undefined ? { name: command.name } : {}),
+            ...(role !== undefined ? { role } : {}),
+            ...geom,
+            ...(command.file !== undefined ? { file: command.file } : {}),
+            ...(command.blocks === undefined && command.text !== undefined ? { text: command.text } : {}),
+            ...(command.cornerRadius !== undefined ? { cornerRadius: command.cornerRadius } : {}),
+            ...(command.rows !== undefined ? { rows: command.rows } : {}),
+            ...(command.theme !== undefined ? { theme: command.theme } : {}),
+            ...(command.alignColumns !== undefined ? { alignColumns: command.alignColumns } : {}),
+            ...(command.chartType !== undefined ? { chartType: command.chartType } : {}),
+            ...(command.data !== undefined ? { data: command.data } : {}),
+            ...(command.showDataLabels !== undefined ? { showDataLabels: command.showDataLabels } : {}),
+        });
+        const created = await addElement(archive, slide.partUri, doc, parent, element);
+        const diagnostics = [];
+        if (command.shapeType === 'table' && command.rows) {
+            const rows = normalizeTableRows(command.rows);
+            const cols = Math.max(1, ...rows.map((r) => r.length));
+            const widthEmu = typeof geom['width'] === 'number'
+                ? geom['width']
+                : parseLength(String(geom['width'] ?? 914400 * cols), {
+                    ...lengthContextFor(archive, 'x'),
+                    axis: 'x',
+                });
+            const layout = measureTableLayout({ rows, widthEmu, fontPt: 11 });
+            if (command.height !== undefined &&
+                command.height !== 'auto' &&
+                typeof geom['height'] === 'number' &&
+                geom['height'] < layout.totalHeightEmu) {
+                diagnostics.push(tableHeightMayClipDiagnostic({
+                    estimatedEmu: layout.totalHeightEmu,
+                    givenEmu: geom['height'],
+                    target: `slide:${command.slide}/shape:${attr(cNvPr(created), 'id') ?? '?'}`,
+                }));
+            }
+        }
+        if (command.chartType === 'combo') {
+            diagnostics.push({
+                severity: 'warning',
+                code: 'COMBO_CHART_RENDER_LIMITED',
+                message: 'combo charts write into PPTX, but community deckuse render may show an Advanced Chart placeholder; prefer column/bar/line/pie for visual QA',
+            });
+        }
+        if (command.fill !== undefined || command.stroke !== undefined) {
+            const styleProps = {};
+            if (command.fill !== undefined)
+                styleProps['fill'] = command.fill;
+            if (command.stroke !== undefined)
+                styleProps['stroke'] = command.stroke;
+            const styled = applyShapeProperties(created, styleProps, {
+                archive,
+                partUri: slide.partUri,
+            });
+            if (!styled.ok)
+                return styled;
+            diagnostics.push(...styled.diagnostics);
+        }
+        if (command.anchor !== undefined || command.wrap !== undefined) {
+            const body = applyShapeProperties(created, {
+                ...(command.anchor !== undefined ? { anchor: command.anchor } : {}),
+                ...(command.wrap !== undefined ? { wrap: command.wrap } : {}),
+            }, { archive, partUri: slide.partUri });
+            if (!body.ok)
+                return body;
+            diagnostics.push(...body.diagnostics);
+        }
+        if (command.blocks !== undefined) {
+            setNodeTextBlocks(created, command.blocks.map((block) => mapTextBlock(block)));
+        }
+        archive.writeXml(slide.partUri, doc);
+        const id = attr(cNvPr(created), 'id') ?? '?';
+        return ok({
+            changed: true,
+            slides: [command.slide],
+            changedTargets: [`slide:${command.slide}/shape:${id}`],
+            changedParts: [slide.partUri],
+            diagnostics,
+        }, diagnostics);
+    }
+    if (command.type === 'alignElements') {
+        const slides = index.elements.filter((item) => item.kind === 'slide');
+        const slide = slides[command.slide - 1];
+        if (!slide)
+            return err('TARGET_NOT_FOUND', `slide:${command.slide} does not exist`, [], {
+                target: `slide:${command.slide}`,
+            });
+        const doc = archive.readXml(slide.partUri);
+        const boxes = [];
+        for (const target of command.targets) {
+            const resolved = resolveTarget(index, target);
+            if (!resolved.ok)
+                return resolved;
+            const node = nodeFor(doc, resolved.value.item);
+            if (!node)
+                return err('ELEMENT_NOT_FOUND', `Element XML node was not found: ${target}`, [], {
+                    target,
+                });
+            const box = readBBox(node);
+            if (!box)
+                return err('INVALID_COMMAND', `Target has no geometry (xfrm): ${target}`, [], { target });
+            boxes.push(box);
+        }
+        const updates = computeAlignUpdates(boxes, command.mode, command.gap, lengthContextFor(archive, command.mode.includes('v') ? 'y' : 'x'));
+        for (const update of updates)
+            writeBBox(update.node, update);
+        archive.writeXml(slide.partUri, doc);
+        return ok({
+            changed: true,
+            slides: [command.slide],
+            changedTargets: [...command.targets],
+            changedParts: [slide.partUri],
+        });
+    }
+    const resolved = resolveCommandRef(command, index);
+    if (!resolved.ok)
+        return resolved;
+    const { item, target, parsed } = resolved.value;
+    if (item.ref.revision && item.ref.revision !== index.revision)
+        return err('TRANSACTION_CONFLICT', `Expected revision ${item.ref.revision}, current ${index.revision}`);
+    // Edition gate (master/layout/theme/advanced chart): hard-deny unless
+    // a registered PptxEditionExtension allows the target.
+    // Slide add/remove/duplicate, addSlide layout binding, and setSlideLayout
+    // rebind are not gated here.
+    if (item.kind !== 'slide') {
+        const gated = assertWritable(item, archive);
+        if (!gated.ok)
+            return gated;
+    }
+    const diagnostics = [];
+    if (item.kind === 'slide') {
+        if (command.type === 'remove') {
+            removeSlide(archive, item.partUri);
+            return ok({
+                changed: true,
+                slides: slidesForItem(index, item),
+                ...(target ? { changedTargets: [target] } : {}),
+                changedParts: ['/ppt/presentation.xml'],
+            });
+        }
+        if (command.type === 'duplicate') {
+            return ok({
+                changed: true,
+                partUri: duplicateSlide(archive, item.partUri),
+                slides: slidesForItem(index, item),
+            });
+        }
+        if (command.type === 'add') {
+            const rawKind = command.element['kind'] ?? command.element['type'];
+            if (rawKind === 'slide') {
+                const template = typeof command.element['templatePart'] === 'string'
+                    ? command.element['templatePart']
+                    : undefined, layout = typeof command.element['layoutPart'] === 'string'
+                    ? command.element['layoutPart']
+                    : undefined;
+                return ok({ changed: true, partUri: addSlide(archive, template, layout), slides: [] });
+            }
+        }
+        if (command.type === 'set' || command.type === 'setProperties') {
+            // slide-level name/hidden not fully modeled; treat as unsupported for now except no-op properties
+            return err('UNSUPPORTED_CAPABILITY', 'Slide property writes beyond add/remove are limited in Phase 1a', [], target !== undefined ? { target } : {});
+        }
+    }
+    const notesReady = materializeNotes(archive, item);
+    if (!notesReady.ok)
+        return notesReady;
+    const liveItem = notesReady.value;
+    const doc = archive.readXml(liveItem.partUri), shapeNode = nodeFor(doc, liveItem);
+    if (!shapeNode)
+        return err('ELEMENT_NOT_FOUND', `Element XML node was not found: ${liveItem.ref.elementId ?? liveItem.ref.path ?? ''}`);
+    const focused = focusMutationNode(shapeNode, parsed);
+    if (!focused.ok)
+        return focused;
+    const node = focused.value;
+    const chartPart = liveItem.kind === 'chart' && typeof liveItem.payload?.['chartPart'] === 'string'
+        ? liveItem.payload['chartPart']
+        : undefined;
+    let chartMutated = false;
+    if (command.type === 'setText') {
+        if (command.blocks !== undefined) {
+            if (chartPart)
+                return err('INVALID_COMMAND', 'Chart titles do not support rich text blocks');
+            setNodeTextBlocks(node, command.blocks.map((block) => mapTextBlock(block)));
+        }
+        else {
+            const text = command.text ?? command.value;
+            if (text === undefined)
+                return err('INVALID_COMMAND', 'setText requires text, value, or blocks');
+            if (chartPart) {
+                const result = updateChart(archive, chartPart, { title: text });
+                chartMutated = true;
+                if (result.workbook)
+                    diagnostics.push({
+                        severity: 'warning',
+                        code: 'EMBEDDED_WORKBOOK_NOT_SYNCHRONIZED',
+                        message: 'Chart cache changed; embedded workbook was not modified',
+                    });
+            }
+            else
+                setNodeText(node, text);
+        }
+    }
+    else if (command.type === 'setTransform') {
+        transform(shapeNode, normalizeTransformFields(archive, command.transform), {
+            archive,
+            partUri: liveItem.partUri,
+        });
+    }
+    else if (command.type === 'xfrmSet') {
+        const geom = normalizeTransformFields(archive, {
+            ...(command.x !== undefined ? { x: command.x } : {}),
+            ...(command.y !== undefined ? { y: command.y } : {}),
+            ...(command.width !== undefined ? { width: command.width } : {}),
+            ...(command.height !== undefined ? { height: command.height } : {}),
+        });
+        transform(shapeNode, {
+            ...geom,
+            ...(command.rotation !== undefined ? { rotation: command.rotation } : {}),
+            ...(command.flipX !== undefined ? { flipX: command.flipX } : {}),
+            ...(command.flipY !== undefined ? { flipY: command.flipY } : {}),
+        }, { archive, partUri: liveItem.partUri });
+    }
+    else if (command.type === 'setTableLayout') {
+        if (liveItem.kind !== 'table')
+            return err('INVALID_COMMAND', 'setTableLayout requires a table target', [], {
+                target: command.target,
+            });
+        const heightOpt = command.height === undefined
+            ? undefined
+            : command.height === 'auto'
+                ? 'auto'
+                : resolveLengthField(archive, command.height, 'y');
+        const laid = applyTableLayout(shapeNode, {
+            ...(heightOpt !== undefined ? { height: heightOpt } : {}),
+            ...(command.redistribute !== undefined ? { redistribute: command.redistribute } : {}),
+        });
+        if (!laid.ok)
+            return laid;
+        if (laid.value.estimatedEmu !== undefined &&
+            typeof heightOpt === 'number' &&
+            heightOpt < laid.value.estimatedEmu) {
+            diagnostics.push(tableHeightMayClipDiagnostic({
+                estimatedEmu: laid.value.estimatedEmu,
+                givenEmu: heightOpt,
+                target: command.target,
+            }));
+        }
+    }
+    else if (command.type === 'set' || command.type === 'setProperties') {
+        if (command.type === 'set' && command.scope && command.scope !== 'local')
+            return err('UNSUPPORTED_CAPABILITY', `Write scope "${command.scope}" is not enabled in Phase 1a; use --scope local`, [], target !== undefined ? { target } : {});
+        const properties = mapDottedProperties(command.properties);
+        if (chartPart) {
+            const checked = assertChartProperties(properties);
+            if (!checked.ok)
+                return checked;
+            const chartProps = { ...properties };
+            if (typeof chartProps['text'] === 'string' && chartProps['title'] === undefined)
+                chartProps['title'] = chartProps['text'];
+            const result = updateChart(archive, chartPart, chartProps);
+            chartMutated = true;
+            if (result.workbook)
+                diagnostics.push({
+                    severity: 'warning',
+                    code: 'EMBEDDED_WORKBOOK_NOT_SYNCHRONIZED',
+                    message: 'Chart cache changed; embedded workbook was not modified',
+                });
+        }
+        else if (liveItem.kind === 'table') {
+            const applied = applyTableProperties(shapeNode, properties, {
+                archive,
+                partUri: liveItem.partUri,
+            });
+            if (!applied.ok)
+                return applied;
+            if (applied.value.applied.length === 0)
+                return err('INVALID_COMMAND', 'set requires at least one supported property');
+        }
+        else if (liveItem.kind === 'tableCell') {
+            const applied = applyTableCellProperties(node, properties);
+            if (!applied.ok)
+                return applied;
+            if (applied.value.applied.length === 0)
+                return err('INVALID_COMMAND', 'set requires at least one supported property');
+        }
+        else {
+            const applied = applyShapeProperties(node, properties, {
+                archive,
+                partUri: liveItem.partUri,
+            });
+            if (!applied.ok)
+                return applied;
+            if (applied.value.applied.length === 0)
+                return err('INVALID_COMMAND', 'set requires at least one supported property');
+        }
+    }
+    else if (command.type === 'zMove') {
+        const moved = applyZMove(doc, shapeNode, command, index);
+        if (!moved.ok)
+            return moved;
+    }
+    else if (command.type === 'replacePicture') {
+        if (liveItem.kind !== 'picture')
+            return err('INVALID_COMMAND', 'replacePicture requires a picture element');
+        const loaded = await loadPictureBytes({
+            ...(command.path !== undefined ? { path: command.path } : {}),
+            ...(command.base64 !== undefined ? { base64: command.base64 } : {}),
+        });
+        if (!loaded.ok)
+            return loaded;
+        const replaced = replacePictureMedia(archive, liveItem.partUri, shapeNode, loaded.value.data, loaded.value.ext);
+        if (!replaced.ok)
+            return replaced;
+    }
+    else if (command.type === 'remove') {
+        if (liveItem.kind === 'picture')
+            detachPictureAndCleanup(archive, liveItem.partUri, doc, shapeNode);
+        else if (liveItem.kind === 'video' || liveItem.kind === 'audio')
+            detachMediaAndCleanup(archive, liveItem.partUri, doc, shapeNode);
+        else
+            shapeNode.parentNode?.removeChild(shapeNode);
+    }
+    else if (command.type === 'duplicate')
+        duplicateElement(doc, shapeNode);
+    else if (command.type === 'add') {
+        const parent = liveItem.kind === 'slide' ? (first(doc, 'spTree') ?? shapeNode) : shapeNode;
+        await addElement(archive, liveItem.partUri, doc, parent, command.element);
+    }
+    else {
+        return err('INVALID_COMMAND', `Unhandled mutation type`);
+    }
+    archive.writeXml(liveItem.partUri, doc);
+    const changedParts = [liveItem.partUri];
+    if (chartMutated && chartPart)
+        changedParts.push(chartPart);
+    if (liveItem.kind === 'notes' && typeof liveItem.location?.['slidePart'] === 'string')
+        changedParts.push(liveItem.location['slidePart']);
+    return ok({
+        changed: true,
+        slides: slidesForItem(index, liveItem),
+        diagnostics,
+        ...(target ? { changedTargets: [target] } : {}),
+        changedParts,
+    }, diagnostics);
+}
+//# sourceMappingURL=mutations.js.map