@docx4j/core-ts 0.3.2 → 0.5.0

package/dist/html/elements.mjs

@@ -0,0 +1,182 @@
+import { highlightNameOf } from './convert.mjs';
+/** Word's character style for a link's text, as `Range.hyperlink` gives it. */
+export const HYPERLINK_STYLE = 'Hyperlink';
+function walkBlocks(blocks, onParagraph) {
+    for (const b of blocks) {
+        if (b.kind === 'paragraph')
+            onParagraph(b);
+        else
+            for (const row of b.rows)
+                for (const c of row)
+                    walkBlocks(c.blocks, onParagraph);
+    }
+}
+export function needsOf(blocks) {
+    const lists = new Map();
+    const links = new Set();
+    walkBlocks(blocks, (p) => {
+        if (p.list && !lists.has(p.list.key))
+            lists.set(p.list.key, p.list.bullet);
+        for (const i of p.inlines)
+            if ('text' in i && i.link !== undefined)
+                links.add(i.link);
+    });
+    return { lists: [...lists].map(([key, bullet]) => ({ key, bullet })), links: [...links] };
+}
+const esc = (text) => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const attr = (value) => String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;');
+function rPrXml(run, linked) {
+    const out = [];
+    // In the schema's order: rStyle, rFonts, b, i, strike, color, sz, szCs, highlight, u, vertAlign.
+    if (linked)
+        out.push(`<w:rStyle w:val="${HYPERLINK_STYLE}"/>`);
+    else if (run.style)
+        out.push(`<w:rStyle w:val="${attr(run.style)}"/>`);
+    if (run.fontName)
+        out.push(`<w:rFonts w:ascii="${attr(run.fontName)}" w:hAnsi="${attr(run.fontName)}" w:cs="${attr(run.fontName)}"/>`);
+    if (run.bold)
+        out.push('<w:b/>');
+    if (run.italic)
+        out.push('<w:i/>');
+    if (run.strike)
+        out.push('<w:strike/>');
+    // A link's colour is its style's, as `Range.hyperlink` leaves no direct colour on a link.
+    if (run.color && !linked)
+        out.push(`<w:color w:val="${attr(run.color === 'auto' ? 'auto' : run.color.replace(/^#/, ''))}"/>`);
+    if (run.fontSize !== undefined) {
+        const half = Math.round(run.fontSize * 2);
+        out.push(`<w:sz w:val="${half}"/><w:szCs w:val="${half}"/>`);
+    }
+    if (run.highlight) {
+        const name = highlightNameOf(run.highlight);
+        if (name)
+            out.push(`<w:highlight w:val="${name}"/>`);
+    }
+    if (run.underline)
+        out.push('<w:u w:val="single"/>');
+    if (run.vertAlign)
+        out.push(`<w:vertAlign w:val="${run.vertAlign}"/>`);
+    return out.length > 0 ? `<w:rPr>${out.join('')}</w:rPr>` : '';
+}
+function runXml(run, linked) {
+    if (run.text === '')
+        return '';
+    const space = /^\s|\s$|\s\s/.test(run.text) ? ' xml:space="preserve"' : '';
+    return `<w:r>${rPrXml(run, linked)}<w:t${space}>${esc(run.text)}</w:t></w:r>`;
+}
+function inlinesXml(inlines, resolve) {
+    var _a;
+    const out = [];
+    let i = 0;
+    while (i < inlines.length) {
+        const inline = inlines[i];
+        if ('br' in inline) {
+            out.push('<w:r><w:br/></w:r>');
+            i++;
+            continue;
+        }
+        if ('tab' in inline) {
+            out.push('<w:r><w:tab/></w:r>');
+            i++;
+            continue;
+        }
+        const rId = inline.link !== undefined ? (_a = resolve.relId) === null || _a === void 0 ? void 0 : _a.call(resolve, inline.link) : undefined;
+        if (rId === undefined) {
+            out.push(runXml(inline, false));
+            i++;
+            continue;
+        }
+        // The runs of one address under one w:hyperlink, in Word's look.
+        const runs = [];
+        while (i < inlines.length) {
+            const next = inlines[i];
+            if (!('text' in next) || next.link !== inline.link)
+                break;
+            runs.push(runXml(next, true));
+            i++;
+        }
+        out.push(`<w:hyperlink r:id="${attr(rId)}">${runs.join('')}</w:hyperlink>`);
+    }
+    return out.join('');
+}
+function pPrXml(p, resolve) {
+    var _a;
+    const out = [];
+    // In the schema's order: pStyle, numPr, spacing, ind, jc.
+    if (p.style)
+        out.push(`<w:pStyle w:val="${attr(p.style)}"/>`);
+    const numId = p.list ? (_a = resolve.numId) === null || _a === void 0 ? void 0 : _a.call(resolve, p.list.key) : undefined;
+    if (p.list && numId !== undefined)
+        out.push(`<w:numPr><w:ilvl w:val="${p.list.level}"/><w:numId w:val="${attr(numId)}"/></w:numPr>`);
+    if (p.spacing)
+        out.push(`<w:spacing w:before="${p.spacing.before}"/>`);
+    if (p.ind) {
+        const a = [];
+        if (p.ind.start !== undefined)
+            a.push(`w:left="${p.ind.start}"`);
+        if (p.ind.end !== undefined)
+            a.push(`w:right="${p.ind.end}"`);
+        if (p.ind.hanging !== undefined)
+            a.push(`w:hanging="${p.ind.hanging}"`);
+        else if (p.ind.firstLine !== undefined)
+            a.push(`w:firstLine="${p.ind.firstLine}"`);
+        if (a.length > 0)
+            out.push(`<w:ind ${a.join(' ')}/>`);
+    }
+    if (p.jc)
+        out.push(`<w:jc w:val="${attr(p.jc)}"/>`);
+    return out.length > 0 ? `<w:pPr>${out.join('')}</w:pPr>` : '';
+}
+function paragraphXml(p, resolve) {
+    return `<w:p>${pPrXml(p, resolve)}${inlinesXml(p.inlines, resolve)}</w:p>`;
+}
+/** Word's default text width shared equally where the table does not say (A4 or Letter with Word's margins: 9,026 twips). */
+const TEXT_WIDTH = 9026;
+function tableXml(t, resolve) {
+    const columns = Math.max(1, ...t.rows.map((r) => r.reduce((n, c) => n + c.colspan, 0)));
+    const widths = Array.from({ length: columns }, () => Math.floor(TEXT_WIDTH / columns));
+    const first = t.rows[0];
+    if (first && first.every((c) => c.width !== undefined && c.colspan === 1) && first.length === columns)
+        first.forEach((c, i) => { widths[i] = c.width; });
+    const widthOf = (col, span) => { var _a; let w = 0; for (let k = 0; k < span; k++)
+        w += (_a = widths[col + k]) !== null && _a !== void 0 ? _a : widths[0]; return w; };
+    const tcPr = (col, span, merge) => `<w:tcPr><w:tcW w:w="${widthOf(col, span)}" w:type="dxa"/>${span > 1 ? `<w:gridSpan w:val="${span}"/>` : ''}${merge === 'restart' ? '<w:vMerge w:val="restart"/>' : merge === 'continue' ? '<w:vMerge/>' : ''}</w:tcPr>`;
+    const cellXml = (c, col) => {
+        const blocks = c.blocks.length > 0 ? blocksToXml(c.blocks, resolve) : '<w:p/>';
+        return `<w:tc>${tcPr(col, c.colspan, c.rowspan > 1 ? 'restart' : undefined)}${blocks}</w:tc>`;
+    };
+    // A cell spanning rows holds its place in the rows below with a continuation cell, as WordprocessingML writes a vertical merge.
+    const pending = new Map();
+    const rows = t.rows.map((cells, r) => {
+        const out = [];
+        let col = 0;
+        const continuation = () => {
+            const p = pending.get(col);
+            if (!p)
+                return;
+            out.push(`<w:tc>${tcPr(col, p.span, 'continue')}<w:p/></w:tc>`);
+            if (--p.rows <= 0)
+                pending.delete(col);
+            col += p.span;
+        };
+        for (const c of cells) {
+            while (pending.has(col))
+                continuation();
+            out.push(cellXml(c, col));
+            if (c.rowspan > 1)
+                pending.set(col, { rows: c.rowspan - 1, span: c.colspan });
+            col += c.colspan;
+        }
+        while (col < columns && pending.has(col))
+            continuation();
+        const trPr = r === 0 && t.headerRow ? '<w:trPr><w:tblHeader/></w:trPr>' : '';
+        return `<w:tr>${trPr}${out.join('')}</w:tr>`;
+    });
+    const tblPr = `<w:tblPr>${t.style ? `<w:tblStyle w:val="${attr(t.style)}"/>` : ''}<w:tblW w:w="0" w:type="auto"/></w:tblPr>`;
+    const grid = `<w:tblGrid>${widths.map((w) => `<w:gridCol w:w="${w}"/>`).join('')}</w:tblGrid>`;
+    return `<w:tbl>${tblPr}${grid}${rows.join('')}</w:tbl>`;
+}
+/** The blocks as a WordprocessingML fragment: `w:p` and `w:tbl` elements, the prefixes undeclared (`insertXml` declares them). */
+export function blocksToXml(blocks, resolve = {}) {
+    return blocks.map((b) => (b.kind === 'table' ? tableXml(b, resolve) : paragraphXml(b, resolve))).join('');
+}

package/dist/html/index.d.mts

@@ -0,0 +1,2 @@
+export * from './convert.mjs';
+export * from './elements.mjs';

package/dist/html/index.mjs

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// `@docx4j/core-ts/html`: HTML to an intermediate form, and that form to WordprocessingML (CR-005 section 8).
+export * from './convert.mjs';
+export * from './elements.mjs';

package/dist/model/content/Body.d.mts

@@ -192,7 +192,8 @@ export declare class Body {
     replaceText(find: string, replace: string, options?: SearchOptions): number;
     /**
      * Removes everything (section properties stay). While the package tracks changes, every
-     * paragraph is marked deleted and every row's `w:trPr` takes a `w:del` instead.
+     * paragraph is marked deleted and every row's `w:trPr` takes a `w:del` instead. Removed outright,
+     * the relationships the content held (its pictures' images) are settled on save (CR-002 section 47).
      */
     clear(): void;
     /**
@@ -256,3 +257,14 @@ export declare class Body {
      */
     insertContentControl(kind?: ContentControlType): ContentControl;
 }
+/**
+ * A story's tracked changes resolved (`Body.acceptAll` or `rejectAll`), then those of each text box in
+ * it - a `w:txbxContent`, in a DrawingML shape or a VML one - which Word counts as a story of its own
+ * (CR-002 section 49). A text box inside a text box is reached through its own story. Returns how many
+ * changes were listed.
+ *
+ * In a kept `mc:AlternateContent` the text box of every branch is resolved, so that each says the same
+ * afterwards (docx4j's `McMode.ALL`), and the changes are counted in the selected branch alone, so a
+ * text box held in both counts once, as a resolved load's does (CR-010 phase 3).
+ */
+export declare function resolveStory(body: Body, what: 'accept' | 'reject'): number;

package/dist/model/content/Body.mjs

@@ -1,5 +1,5 @@
 import { Docx4JException, PropertyResolverNotCreatedException } from '../../opc/exceptions.mjs';
-import { typeNameOf, childrenOf, linkParents, BLOCK_LEVEL_TYPES, textOf, textOfView, rowsOf, cellsOf } from './tree.mjs';
+import { typeNameOf, childrenOf, linkParents, BLOCK_LEVEL_TYPES, textOf, textOfView, rowsOf, cellsOf, selectedBranchOf, ALTERNATE_CONTENT } from './tree.mjs';
 import { r as textRun, br as breakItem, tbl as tableOf } from '@docx4j/generated-objects-ts/builders/wml';
 import { runOf, paragraphOf, runsOf } from './tree.mjs';
 import { Paragraph } from './Paragraph.mjs';
@@ -9,10 +9,11 @@ import { sdt as sdtOf, nextSdtId } from '@docx4j/generated-objects-ts/builders/w
 import { controlIdScope, sdtKindFor, declareSdtExtensions } from '../customxml/insert.mjs';
 import { InlinePicture, addImage, writableWidthEmu } from './InlinePicture.mjs';
 import { contentOf } from './ooxml.mjs';
+import { relationshipIdsIn, queueRelationshipRemovals } from './relationships.mjs';
 import { expandReplacement } from './search.mjs';
 import { commentApi } from './comments.mjs';
 import { trackerOf, trackInsertedBlock, markHolderInserted } from './tracking.mjs';
-import { trackedChangesOfRow, trackedChangeTokensOfParagraph, groupTouching, BREAK, tablePropertiesChangeOf, cellChangeOf, bodySectionChangeOf, resolveUnlisted, holderInsertionAt } from './TrackedChange.mjs';
+import { trackedChangesOfRow, trackedChangeTokensOfParagraph, groupTouching, BREAK, tablePropertiesChangeOf, cellChangeOf, bodySectionChangeOf, resolveUnlisted, holderInsertionAt, resolving } from './TrackedChange.mjs';
 import { listsOf, listLabelsOf } from './List.mjs';
 /**
  * A subset of Office JS `Word.Body` over any container with block-level content: the main
@@ -239,11 +240,18 @@ export class Body {
      * `values` fills it row by row. The columns are equal over the section's text width.
      */
     insertTable(rowCount, columnCount, location, values) {
+        var _a;
+        var _b;
         if (rowCount < 1 || columnCount < 1)
             throw new Docx4JException(`A table needs at least one row and one column; got ${rowCount} by ${columnCount}`);
         const rows = Array.from({ length: rowCount }, (_, r) => Array.from({ length: columnCount }, (_, c) => { var _a, _b; return (_b = (_a = values === null || values === void 0 ? void 0 : values[r]) === null || _a === void 0 ? void 0 : _a[c]) !== null && _b !== void 0 ? _b : ''; }));
         const width = writableWidthTwips(this.container);
         const element = tableOf(rows, width ? { width } : {});
+        // Word's own default (Insert Table, fixed column width Auto; the editor's check 42, Word 365): an
+        // automatic table width, no w:tblLayout, the cells in twips sharing the text width - the grid and
+        // cells the builder wrote, the table's width made automatic (CR-002 section 42.5 item 7).
+        const tblPr = ((_a = (_b = element.value).tblPr) !== null && _a !== void 0 ? _a : (_b.tblPr = {}));
+        tblPr.tblW = { w: 0, type: 'auto' };
         this.insertElement(element, location);
         return new Table(element, this.content, this);
     }
@@ -257,8 +265,11 @@ export class Body {
             throw new Docx4JException('This body has no part, so an image cannot be related to it');
         const { run, drawing } = addImage(this.part, base64, this.container, writableWidthEmu(this.container), options);
         const paragraph = this.insertParagraph('', location);
-        paragraph.p.content.push(run);
-        linkParents(run, paragraph.p);
+        // under tracking the picture is an insertion, as its paragraph's mark is (insertBreak's form)
+        const tracker = paragraph.changeTracker;
+        const item = tracker ? tracker.ins([run]) : run;
+        paragraph.p.content.push(item);
+        linkParents(item, paragraph.p);
         return new InlinePicture(drawing, run, paragraph);
     }
     insertBreak(type, location) {
@@ -363,11 +374,16 @@ export class Body {
     }
     /**
      * Removes everything (section properties stay). While the package tracks changes, every
-     * paragraph is marked deleted and every row's `w:trPr` takes a `w:del` instead.
+     * paragraph is marked deleted and every row's `w:trPr` takes a `w:del` instead. Removed outright,
+     * the relationships the content held (its pictures' images) are settled on save (CR-002 section 47).
      */
     clear() {
+        var _a;
         const tracker = this.changeTracker;
         if (!tracker) {
+            const ids = new Set();
+            relationshipIdsIn(this.content, ids);
+            queueRelationshipRemovals((_a = this.package_) === null || _a === void 0 ? void 0 : _a.pendingRelationshipRemovals, this.part, ids);
             this.content.length = 0;
             return;
         }
@@ -420,14 +436,14 @@ export class Body {
                         // belongs to that change, which accepts or rejects it along with the row.
                         const tokens = [];
                         for (const cell of cellsOf(row.element.value)) {
-                            const cellChange = cellChangeOf(cell.element, cell.container, row.element.value);
+                            const cellChange = cellChangeOf(cell.element, cell.container, row.element.value, this);
                             if (cellChange)
                                 tokens.push(cellChange, BREAK);
                             visit((_b = childrenOf(cell.element.value)) !== null && _b !== void 0 ? _b : [], tokens);
                             tokens.push(BREAK);
                         }
                         const inner = groupTouching(tokens);
-                        const rowChanges = trackedChangesOfRow(row.element, row.container, inner, { element: el, container: items });
+                        const rowChanges = trackedChangesOfRow(row.element, row.container, inner, { element: el, container: items }, this);
                         if (rowChanges.length > 0)
                             into.push(...rowChanges);
                         else {
@@ -474,18 +490,22 @@ export class Body {
      * pass that resolves nothing ends it.
      */
     resolveAll(what) {
-        let changes = this.getTrackedChanges();
-        const count = changes.length;
-        while (changes.length > 0) {
-            for (let i = changes.length - 1; i >= 0; i--)
-                changes[i][what]();
-            const left = this.getTrackedChanges();
-            if (left.length >= changes.length)
-                break;
-            changes = left;
-        }
-        // and what is never listed: a cell merge, a numbering change, records that change nothing
-        resolveUnlisted(this.content, what);
+        let count = 0;
+        // one resolution for the lot, so the bookmarks are read before the first and after the last
+        resolving(this.package_, this, () => {
+            let changes = this.getTrackedChanges();
+            count = changes.length;
+            while (changes.length > 0) {
+                for (let i = changes.length - 1; i >= 0; i--)
+                    changes[i][what]();
+                const left = this.getTrackedChanges();
+                if (left.length >= changes.length)
+                    break;
+                changes = left;
+            }
+            // and what is never listed: a cell merge, a numbering change, records that change nothing
+            resolveUnlisted(this.content, what);
+        });
         return count;
     }
     /** Every `w:tr` in this body's tables, in document order (rows of nested tables included). */
@@ -770,3 +790,61 @@ function describe(el) {
     const tn = typeNameOf(el);
     return `${(_b = (_a = el.name) === null || _a === void 0 ? void 0 : _a.localPart) !== null && _b !== void 0 ? _b : '?'} (${tn !== null && tn !== void 0 ? tn : 'no TYPE_NAME'})`;
 }
+/**
+ * A story's tracked changes resolved (`Body.acceptAll` or `rejectAll`), then those of each text box in
+ * it - a `w:txbxContent`, in a DrawingML shape or a VML one - which Word counts as a story of its own
+ * (CR-002 section 49). A text box inside a text box is reached through its own story. Returns how many
+ * changes were listed.
+ *
+ * In a kept `mc:AlternateContent` the text box of every branch is resolved, so that each says the same
+ * afterwards (docx4j's `McMode.ALL`), and the changes are counted in the selected branch alone, so a
+ * text box held in both counts once, as a resolved load's does (CR-010 phase 3).
+ */
+export function resolveStory(body, what) {
+    let count = what === 'accept' ? body.acceptAll() : body.rejectAll();
+    for (const { box, selected } of textBoxesIn(body.container)) {
+        const resolved = resolveStory(body.sub(box), what);
+        if (selected)
+            count += resolved;
+    }
+    return count;
+}
+/**
+ * The `w:txbxContent` of every text box in a story's content, not descending into one found, each with
+ * whether it is in a branch a reader takes: false inside a branch of a kept `mc:AlternateContent` other
+ * than its selected one (`selectedBranchOf`).
+ */
+function textBoxesIn(container) {
+    const out = [];
+    const seen = new Set();
+    const visit = (o, selected) => {
+        var _a;
+        if (typeof o !== 'object' || o === null || seen.has(o))
+            return;
+        if (typeof o.nodeType === 'number')
+            return; // DOM the model does not type
+        seen.add(o);
+        if (Array.isArray(o)) {
+            for (const item of o)
+                visit(item, selected);
+            return;
+        }
+        const typeName = o.TYPE_NAME;
+        if (typeName === 'org_docx4j_wml.CTTxbxContent') {
+            out.push({ box: o, selected });
+            return;
+        }
+        if (typeName === ALTERNATE_CONTENT) {
+            const ac = o;
+            const read = selectedBranchOf(ac);
+            for (const branch of [...((_a = ac.choice) !== null && _a !== void 0 ? _a : []), ...(ac.fallback ? [ac.fallback] : [])])
+                visit(branch.any, selected && branch.any === read);
+            return;
+        }
+        for (const key in o)
+            if (key !== 'PARENT')
+                visit(o[key], selected);
+    };
+    visit(container.content, true);
+    return out;
+}

package/dist/model/content/Comment.mjs

@@ -9,6 +9,7 @@ import { Paragraph } from './Paragraph.mjs';
 import { Range } from './Range.mjs';
 import { runOf, paragraphOf, typeNameOf } from './tree.mjs';
 import { revisionDateOf, wordCalendarOf, copyRPr } from './tracking.mjs';
+import { relationshipIdsIn, queueRelationshipRemovals } from './relationships.mjs';
 import { COMMENT_REFERENCE_STYLE, COMMENT_TEXT_STYLE, commentExOf, commentIdsOf, commentPartsAccess, commentParaId, initialsOf, isDone, markersOf, markersOfParagraph, nextCommentId, paraIdTaken, randomHexId, removeMarkers, setCommentApi, } from './comments.mjs';
 /**
  * A subset of Office JS `Word.Comment` over a `w:comment` and the markers that anchor it. A view:
@@ -191,6 +192,12 @@ export class Comment {
             if (i >= 0)
                 comments.splice(i, 1);
         }
+        // what the comment's own content related to - a picture's image - goes on save when nothing else
+        // uses it, as for a picture deleted outright (CR-002 section 50; docx4j's Removals)
+        const released = new Set();
+        relationshipIdsIn(this.element.content, released);
+        const pkg = this.body.package_;
+        queueRelationshipRemovals(pkg === null || pkg === void 0 ? void 0 : pkg.pendingRelationshipRemovals, this.parts.commentsPart, released);
         const paraId = this.paraId;
         if (paraId === undefined)
             return;

package/dist/model/content/InlinePicture.d.mts

@@ -1,4 +1,5 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type * as dml from '@docx4j/generated-objects-ts/modules/org_docx4j_dml';
 import type * as wp from '@docx4j/generated-objects-ts/modules/org_docx4j_dml_wordprocessingDrawing';
 import { IMAGE_CONTENT_TYPES_BY_EXTENSION } from '../../opc/ContentTypes.mjs';
 import { ImagePart } from '../../parts/BinaryPart.mjs';
@@ -22,7 +23,9 @@ export interface ImageInfo {
  * The size and kind of an image, from its header: PNG (IHDR and pHYs), JPEG (SOFn and the JFIF
  * APP0 densities), GIF (the logical screen descriptor) and BMP (the DIB header, with its pixels
  * per metre). docx4j reads these through XML Graphics Commons' ImageInfo; this is the same
- * information, and the same 96 dpi default when a file declares none.
+ * information, and the same 96 dpi default when a file declares none. An SVG document is told by
+ * its root element and has no pixel size (both 0): it can be the part behind an existing picture
+ * (CR-005 section 9, a binding that keeps the drawing) but not be placed as a new one.
  */
 export declare function imageInfoOf(bytes: Uint8Array): ImageInfo;
 /** The natural size of an image in EMU: pixels over the resolution it declares. */
@@ -49,17 +52,56 @@ export interface NewPicture {
     imagePart: ImagePart;
     relId: string;
 }
+/** A new image part, its relationship from the part it was added to, and what its header says. */
+export interface NewImagePart {
+    imagePart: ImagePart;
+    relId: string;
+    info: ImageInfo;
+}
 /**
  * Adds the image as a part of `source` (the main document part, or the header or footer the body
- * belongs to) with a relationship, and builds the run that shows it. docx4j:
- * `BinaryPartAbstractImage.createImagePart` then `createImageInline`.
+ * belongs to) with a relationship, and nothing else: docx4j `BinaryPartAbstractImage.createImagePart`
+ * (`BindingTraverserXSLT.createImagePartReturnRelId`, where a picture binding replaces an `r:embed`
+ * and keeps the drawing, CR-005 section 9). Throws, and adds nothing, when the bytes are not an
+ * image this package reads.
+ */
+export declare function addImagePart(source: Part, base64: string): NewImagePart;
+/**
+ * Adds the image as a part of `source` with a relationship (`addImagePart`), and builds the run
+ * that shows it. docx4j: `BinaryPartAbstractImage.createImagePart` then `createImageInline`.
  */
 export declare function addImage(source: Part, base64: string, scope: object, maxCx: number | undefined, options?: InlinePictureOptions): NewPicture;
 /** The writable width of a section in EMU (page width less the margins), for scaling. */
 export declare function writableWidthEmu(container: object): number | undefined;
+/** The `asvg:svgBlip` in a blip's `a:extLst`, if any: an SVG picture's SVG (CR-002 section 52). */
+export declare function svgBlipOf(blip: dml.CTBlip | undefined): {
+    embed?: string;
+} | undefined;
+/**
+ * Points a blip at a new image the way Word's own picture binding does (test/README.md checks 46 and
+ * 47; CR-002 section 52). The blip's effects and other extensions stay.
+ * - A raster image goes in `r:embed`, and an `asvg:svgBlip` is taken away. Left in place, Word would go
+ *   on drawing its old SVG, and would replace the new image with a PNG of that SVG when it saves.
+ * - An SVG goes under the `asvg:svgBlip`, and `r:embed` is taken away. Word puts a PNG of the SVG it
+ *   makes itself in `r:embed`, which this package cannot make, and Word 365 draws the SVG without one.
+ * `r:link` is left as it was.
+ */
+export declare function setBlipImage(blip: dml.CTBlip, relId: string, svg: boolean): void;
+/**
+ * The inline pictures a run's item holds: the item itself when it is a `w:drawing` whose `wp:inline`
+ * holds a `pic:pic`, and those in a kept `mc:AlternateContent`'s selected branch (`selectedBranchOf`,
+ * CR-010 phase 3). A drawing of anything else, such as a chart, a text box, a group or SmartArt, is no
+ * inline picture: Office JS lists none for an inline text box (CR-010 section 12.6, test/README.md
+ * check 42).
+ */
+export declare function picturesIn(item: Element): Element<wml.Drawing>[];
 /**
- * A subset of Office JS `Word.InlinePicture` over a `w:drawing` holding a `wp:inline`. A view:
- * the drawing, the run it is in and the paragraph. Sizes are points, as Office JS reports them.
+ * A subset of Office JS `Word.InlinePicture` over a `w:drawing` holding a `wp:inline` with a `pic:pic`.
+ * A view: the drawing, the run it is in and the paragraph. Sizes are points, as Office JS reports them.
+ *
+ * A picture in a kept `mc:AlternateContent`'s selected branch has the element as its `holder`. Reads and
+ * the setters are the selected branch's drawing; `delete` removes the element whole, every branch with
+ * it (CR-010 phase 3).
  */
 export declare class InlinePicture {
     /** The `w:drawing` element pair. */
@@ -67,11 +109,15 @@ export declare class InlinePicture {
     /** The run holding the drawing, and the array holding the run. */
     readonly run: Element<wml.R>;
     readonly paragraph: Paragraph;
+    /** The run's item the drawing stands in, where that is not the drawing: a kept `mc:AlternateContent`. */
+    readonly holder?: Element | undefined;
     constructor(
     /** The `w:drawing` element pair. */
     element: Element<wml.Drawing>, 
     /** The run holding the drawing, and the array holding the run. */
-    run: Element<wml.R>, paragraph: Paragraph);
+    run: Element<wml.R>, paragraph: Paragraph, 
+    /** The run's item the drawing stands in, where that is not the drawing: a kept `mc:AlternateContent`. */
+    holder?: Element | undefined);
     /** The wp:inline; a floating picture (wp:anchor) is not an InlinePicture, and throws. */
     get inline(): wp.Inline;
     /** Width in points, as Office JS. */
@@ -85,18 +131,51 @@ export declare class InlinePicture {
     /** wp:docPr/@title (typed since objects 0.1.3; before that the attribute was not marshalled, CR-002 section 8). */
     get altTextTitle(): string;
     set altTextTitle(text: string);
-    /** The kind of image, from the content type of the part the picture embeds. */
+    /**
+     * The kind of image, from the content type of the part `getBase64` reads: `Svg` for an SVG picture
+     * (`svgImagePart`), else the `a:blip`'s part's. Office JS gives `null` for an SVG picture, though its
+     * typings declare the property non-null and `Word.ImageFormat` has `Svg` (test/README.md check 45);
+     * this package gives `Svg`, a departure (CR-002 section 52).
+     */
     get imageFormat(): ImageFormat;
     /** The relationship id of the embedded image (r:embed), if any (extension). */
     get relId(): string | undefined;
-    /** The image's bytes as base64 (Office JS getBase64ImageSrc). */
+    /**
+     * The relationship id of the SVG the picture embeds beside its image, if any (extension): the
+     * `r:embed` of an `asvg:svgBlip` in the `a:blip`'s `a:extLst`, as Office 2016 and later write an SVG
+     * picture, with the `a:blip`'s own image a PNG of it for readers that don't understand SVG.
+     */
+    get svgRelId(): string | undefined;
+    /**
+     * The image's bytes as base64 (Office JS getBase64ImageSrc). For an SVG picture, the SVG
+     * (`svgImagePart`), as Office JS gives it (test/README.md check 43); else the `a:blip`'s image.
+     */
     getBase64(): Promise<string>;
     /** Office JS's name for `getBase64()`. */
     getBase64ImageSrc(): Promise<string>;
-    /** The image part this picture embeds (extension). */
+    /** The image part this picture embeds: the `a:blip`'s, which is an SVG picture's PNG (extension). */
     imagePart(): ImagePart | undefined;
-    /** Removes the picture; the run goes too when the picture was all it held. */
+    /** The SVG part an SVG picture embeds beside its image (`svgRelId`), if any (extension). */
+    svgImagePart(): ImagePart | undefined;
+    private partFor;
+    /**
+     * Removes the picture; the run goes too when the picture was all it held. A picture in a kept
+     * `mc:AlternateContent` takes the element with it, every branch (`holder`).
+     *
+     * While the package tracks changes it is marked deleted instead: its run goes into a `w:del`, and
+     * when the run held more than the picture, the picture is first given a run of its own with the
+     * same properties, so the deletion holds it alone. Accepting the deletion then takes it, and its
+     * image part with it (CR-002 section 46). A picture its author inserted under tracking is taken
+     * back, as `Paragraph.delete` takes back its own text, and one inside a deletion is refused.
+     *
+     * A picture removed outright (tracking off, or taken back) queues its image relationship on the
+     * package. On save the relationship goes if nothing then references it, and the image part with it
+     * when nothing else targets it. Waiting for the save lets a picture cut and pasted back keep its
+     * image.
+     */
     delete(): void;
+    /** The picture's run in a `w:del`, the picture split into a run of its own when the run held more. */
+    private markDeleted;
     private pic;
     private resize;
 }