@docx4j/core-ts 0.3.2 → 0.5.0

package/dist/model/content/InlinePicture.mjs

@@ -1,10 +1,12 @@
 import { inlinePicture } from '@docx4j/generated-objects-ts/builders/wml';
 import { Docx4JException } from '../../opc/exceptions.mjs';
 import { ContentTypes, IMAGE_CONTENT_TYPES_BY_EXTENSION } from '../../opc/ContentTypes.mjs';
-import { base64Decode, base64Encode } from '../../xml/dom.mjs';
+import { base64Decode, base64Encode, decodeXmlText } from '../../xml/dom.mjs';
 import { ImagePart } from '../../parts/BinaryPart.mjs';
 import { PartName } from '../../opc/PartName.mjs';
-import { find, runOf } from './tree.mjs';
+import { find, runOf, linkParents, revisionKindOf, isElement, typeNameOf, isAlternateContent, selectedBranchOf } from './tree.mjs';
+import { copyRPr } from './tracking.mjs';
+import { relationshipIdsIn, queueRelationshipRemovals } from './relationships.mjs';
 /** English Metric Units per inch, and per twip (docx4j UnitsOfMeasurement). */
 const EMU_PER_INCH = 914400;
 const EMU_PER_TWIP = 635;
@@ -15,7 +17,9 @@ const EMU_PER_POINT = 12700;
  * 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 function imageInfoOf(bytes) {
     const png = pngInfo(bytes);
@@ -30,8 +34,27 @@ export function imageInfoOf(bytes) {
     const bmp = bmpInfo(bytes);
     if (bmp)
         return bmp;
+    const svg = svgInfo(bytes);
+    if (svg)
+        return svg;
     const head = Array.from(bytes.subarray(0, 8)).map((b) => b.toString(16).padStart(2, '0')).join(' ');
-    throw new Docx4JException(`Unsupported image format (first bytes ${head}); PNG, JPEG, GIF and BMP are read here`);
+    throw new Docx4JException(`Unsupported image format (first bytes ${head}); PNG, JPEG, GIF, BMP and SVG are read here`);
+}
+/** An SVG document: an XML declaration, comments and a doctype allowed before the `svg` root. */
+function svgInfo(b) {
+    if (b.length < 5)
+        return undefined;
+    let head;
+    try {
+        head = decodeXmlText(b.subarray(0, Math.min(b.length, 4096)));
+    }
+    catch {
+        return undefined;
+    }
+    const body = head.replace(/^\uFEFF/, '').replace(/<\?xml[^>]*\?>/, '').replace(/<!--[\s\S]*?-->/g, '').replace(/<!DOCTYPE[^>]*>/i, '').trimStart();
+    if (!/^<(\w+:)?svg[\s>]/.test(body))
+        return undefined;
+    return { contentType: ContentTypes.IMAGE_SVG, extension: 'svg', widthPx: 0, heightPx: 0, dpiX: DEFAULT_DPI, dpiY: DEFAULT_DPI };
 }
 function be16(b, at) { return (b[at] << 8) | b[at + 1]; }
 function be32(b, at) { return ((b[at] << 24) >>> 0) + (b[at + 1] << 16) + (b[at + 2] << 8) + b[at + 3]; }
@@ -144,11 +167,12 @@ export function naturalSizeEmu(info) {
 }
 /**
  * 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 function addImage(source, base64, scope, maxCx, options = {}) {
-    var _a, _b;
+export function addImagePart(source, base64) {
     const pkg = source.package;
     if (!pkg)
         throw new Docx4JException('This part is not in a package yet; add it before adding an image');
@@ -157,6 +181,21 @@ export function addImage(source, base64, scope, maxCx, options = {}) {
     const imagePart = new ImagePart(freeImageName(pkg, info.extension), info.contentType);
     imagePart.setBytes(bytes);
     const rel = source.addTargetPart(imagePart);
+    return { imagePart, relId: rel.id, info };
+}
+/**
+ * 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 function addImage(source, base64, scope, maxCx, options = {}) {
+    var _a, _b;
+    const bytes = base64Decode(base64);
+    const info = imageInfoOf(bytes);
+    if (info.widthPx === 0 || info.heightPx === 0) {
+        throw new Docx4JException(`A ${info.extension.toUpperCase()} image has no pixel size to place it at; PNG, JPEG, GIF and BMP can be placed`);
+    }
+    const { imagePart, relId } = addImagePart(source, base64);
+    const rel = { id: relId };
     let { cx, cy } = naturalSizeEmu(info);
     if (options.width !== undefined) {
         const wanted = Math.round(options.width * EMU_PER_POINT);
@@ -211,6 +250,57 @@ export function writableWidthEmu(container) {
     const twips = pgSz.w - left - right;
     return twips > 0 ? twips * EMU_PER_TWIP : undefined;
 }
+/** The TYPE_NAME of `asvg:svgBlip`, Office 2016's SVG picture extension of an `a:blip`. */
+const SVG_BLIP = 'org_docx4j_com_microsoft_schemas_office_drawing_x2016_SVG_main.CTSVGBlip';
+/** The `a:ext` URI that `asvg:svgBlip` stands under, and its namespace. */
+const SVG_BLIP_EXT_URI = '{96DAC541-7B7A-43D3-8B79-37D633B846F1}';
+const SVG_NS = 'http://schemas.microsoft.com/office/drawing/2016/SVG/main';
+/** The `asvg:svgBlip` in a blip's `a:extLst`, if any: an SVG picture's SVG (CR-002 section 52). */
+export function svgBlipOf(blip) {
+    var _a, _b;
+    for (const ext of (_b = (_a = blip === null || blip === void 0 ? void 0 : blip.extLst) === null || _a === void 0 ? void 0 : _a.ext) !== null && _b !== void 0 ? _b : []) {
+        const any = ext.any;
+        if (isElement(any) && typeNameOf(any) === SVG_BLIP)
+            return any.value;
+    }
+    return 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 function setBlipImage(blip, relId, svg) {
+    var _a, _b;
+    if (!svg) {
+        blip.embed = relId;
+        const list = blip.extLst;
+        if (list === null || list === void 0 ? void 0 : list.ext) {
+            list.ext = list.ext.filter((ext) => !(isElement(ext.any) && typeNameOf(ext.any) === SVG_BLIP));
+            if (list.ext.length === 0)
+                delete blip.extLst;
+        }
+        return;
+    }
+    delete blip.embed;
+    const existing = svgBlipOf(blip);
+    if (existing) {
+        existing.embed = relId;
+        return;
+    }
+    const list = ((_a = blip.extLst) !== null && _a !== void 0 ? _a : (blip.extLst = { TYPE_NAME: 'org_docx4j_dml.CTOfficeArtExtensionList', ext: [] }));
+    const ext = {
+        TYPE_NAME: 'org_docx4j_dml.CTOfficeArtExtension',
+        uri: SVG_BLIP_EXT_URI,
+        any: { name: { namespaceURI: SVG_NS, localPart: 'svgBlip' }, value: { TYPE_NAME: SVG_BLIP, embed: relId } },
+    };
+    ((_b = list.ext) !== null && _b !== void 0 ? _b : (list.ext = [])).push(ext);
+    linkParents(list, blip);
+}
 const FORMAT_BY_CONTENT_TYPE = {
     [ContentTypes.IMAGE_PNG]: 'Png', [ContentTypes.IMAGE_X_PNG]: 'Png', [ContentTypes.IMAGE_JPEG]: 'Jpeg',
     [ContentTypes.IMAGE_GIF]: 'Gif', [ContentTypes.IMAGE_BMP]: 'Bmp', [ContentTypes.IMAGE_TIFF]: 'Tiff',
@@ -218,18 +308,48 @@ const FORMAT_BY_CONTENT_TYPE = {
     [ContentTypes.IMAGE_WMF]: 'Wmf',
 };
 /**
- * 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.
+ * 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 function picturesIn(item) {
+    var _a;
+    if (isAlternateContent(item)) {
+        return ((_a = selectedBranchOf(item.value)) !== null && _a !== void 0 ? _a : []).flatMap((child) => (isElement(child) ? picturesIn(child) : []));
+    }
+    return item.name.localPart === 'drawing' && holdsInlinePicture(item.value) ? [item] : [];
+}
+/** True for a drawing whose `wp:inline` holds a `pic:pic`. */
+function holdsInlinePicture(drawing) {
+    var _a, _b, _c, _d;
+    const inline = (_a = drawing.anchorOrInline) === null || _a === void 0 ? void 0 : _a[0];
+    if (!inline || inline.TYPE_NAME !== 'org_docx4j_dml_wordprocessingDrawing.Inline')
+        return false;
+    const first = (_d = (_c = (_b = inline.graphic) === null || _b === void 0 ? void 0 : _b.graphicData) === null || _c === void 0 ? void 0 : _c.any) === null || _d === void 0 ? void 0 : _d[0];
+    return isElement(first) && typeNameOf(first) === 'org_docx4j_dml_picture.Pic';
+}
+/**
+ * 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 class InlinePicture {
     constructor(
     /** The `w:drawing` element pair. */
     element, 
     /** The run holding the drawing, and the array holding the run. */
-    run, paragraph) {
+    run, paragraph, 
+    /** The run's item the drawing stands in, where that is not the drawing: a kept `mc:AlternateContent`. */
+    holder) {
         this.element = element;
         this.run = run;
         this.paragraph = paragraph;
+        this.holder = holder;
     }
     /** The wp:inline; a floating picture (wp:anchor) is not an InlinePicture, and throws. */
     get inline() {
@@ -272,20 +392,39 @@ export class InlinePicture {
     set altTextTitle(text) {
         this.inline.docPr.title = text;
     }
-    /** 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() {
-        var _a;
-        const part = this.imagePart();
-        return (_a = (part && FORMAT_BY_CONTENT_TYPE[part.contentType])) !== null && _a !== void 0 ? _a : 'Unsupported';
+        var _a, _b;
+        const part = (_a = this.svgImagePart()) !== null && _a !== void 0 ? _a : this.imagePart();
+        return (_b = (part && FORMAT_BY_CONTENT_TYPE[part.contentType])) !== null && _b !== void 0 ? _b : 'Unsupported';
     }
     /** The relationship id of the embedded image (r:embed), if any (extension). */
     get relId() {
         var _a, _b;
         return (_b = (_a = this.pic()) === null || _a === void 0 ? void 0 : _a.blipFill.blip) === null || _b === void 0 ? void 0 : _b.embed;
     }
-    /** 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() {
+        var _a, _b;
+        const embed = (_b = svgBlipOf((_a = this.pic()) === null || _a === void 0 ? void 0 : _a.blipFill.blip)) === null || _b === void 0 ? void 0 : _b.embed;
+        return embed === undefined || embed === '' ? undefined : embed;
+    }
+    /**
+     * 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.
+     */
     async getBase64() {
-        const part = this.imagePart();
+        var _a;
+        const part = (_a = this.svgImagePart()) !== null && _a !== void 0 ? _a : this.imagePart();
         if (!part)
             throw new Docx4JException('This picture has no image part (a linked or missing image)');
         return base64Encode(await part.getBytes());
@@ -294,29 +433,97 @@ export class InlinePicture {
     getBase64ImageSrc() {
         return this.getBase64();
     }
-    /** 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() {
+        return this.partFor(this.relId);
+    }
+    /** The SVG part an SVG picture embeds beside its image (`svgRelId`), if any (extension). */
+    svgImagePart() {
+        return this.partFor(this.svgRelId);
+    }
+    partFor(relId) {
         var _a;
-        const relId = this.relId;
         const source = this.paragraph.parentBody.part;
         if (!relId || !source)
             return undefined;
         const part = (_a = source.relationshipsPart) === null || _a === void 0 ? void 0 : _a.getPart(relId);
         return part instanceof ImagePart ? part : undefined;
     }
-    /** Removes the picture; the run goes too when the picture was all it held. */
+    /**
+     * 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() {
-        var _a;
+        var _a, _b;
+        const place = placeOf(this.paragraph.p, this.run);
+        if (!place)
+            return;
+        const revision = place.revision;
+        const tracker = this.paragraph.changeTracker;
+        if (tracker && ((revision === null || revision === void 0 ? void 0 : revision.kind) === 'del' || (revision === null || revision === void 0 ? void 0 : revision.kind) === 'moveFrom')) {
+            throw new Docx4JException(`This picture is inside a w:${revision.kind} (deleted by ${revision.value.author}); reject the deletion first`);
+        }
+        if (tracker && !tracker.ownInsertion(revision)) {
+            this.markDeleted(tracker, place);
+            return;
+        }
+        const item = (_a = this.holder) !== null && _a !== void 0 ? _a : this.element;
         const content = this.run.value.content;
-        const at = (_a = content === null || content === void 0 ? void 0 : content.indexOf(this.element)) !== null && _a !== void 0 ? _a : -1;
+        const at = (_b = content === null || content === void 0 ? void 0 : content.indexOf(item)) !== null && _b !== void 0 ? _b : -1;
         if (content && at >= 0)
             content.splice(at, 1);
         if (!content || content.length === 0) {
-            const holder = runHolderOf(this.paragraph.p, this.run);
-            const i = holder ? holder.indexOf(this.run) : -1;
-            if (holder && i >= 0)
-                holder.splice(i, 1);
+            const i = place.items.indexOf(this.run);
+            if (i >= 0)
+                place.items.splice(i, 1);
+            if (revision && revision.items.length === 0) { // an insertion left empty goes with it
+                const j = revision.owner.indexOf(revision.element);
+                if (j >= 0)
+                    revision.owner.splice(j, 1);
+            }
+        }
+        const ids = new Set();
+        relationshipIdsIn(item, ids);
+        const pkg = this.paragraph.parentBody.package_;
+        queueRelationshipRemovals(pkg === null || pkg === void 0 ? void 0 : pkg.pendingRelationshipRemovals, this.paragraph.parentBody.part, ids);
+    }
+    /** The picture's run in a `w:del`, the picture split into a run of its own when the run held more. */
+    markDeleted(tracker, place) {
+        var _a, _b;
+        const run = this.run;
+        const at = place.items.indexOf(run);
+        const content = ((_a = run.value.content) !== null && _a !== void 0 ? _a : []);
+        const item = (_b = this.holder) !== null && _b !== void 0 ? _b : this.element;
+        const i = content.indexOf(item);
+        if (at < 0 || i < 0)
+            return;
+        const before = content.slice(0, i);
+        const after = content.slice(i + 1);
+        const pieces = [];
+        let alone = run;
+        if (before.length > 0 || after.length > 0) {
+            alone = runOf([item], copyRPr(run.value.rPr));
+            if (before.length > 0) {
+                run.value.content = before;
+                pieces.push(run);
+            }
         }
+        pieces.push(tracker.del([alone]));
+        if (after.length > 0)
+            pieces.push(runOf(after, copyRPr(run.value.rPr)));
+        place.items.splice(at, 1, ...pieces);
+        linkParents(pieces, place.parent);
     }
     pic() {
         const any = this.inline.graphic.graphicData.any;
@@ -338,24 +545,27 @@ export class InlinePicture {
         }
     }
 }
-/** The array holding a run inside a paragraph (the paragraph's content, or a holder's). */
-function runHolderOf(p, run) {
-    const seek = (items) => {
-        var _a, _b, _c;
+function placeOf(p, run) {
+    const seek = (items, parent, revision) => {
+        var _a, _b, _c, _d;
         if (!items)
             return undefined;
         if (items.includes(run))
-            return items;
+            return revision ? { items, parent, revision } : { items, parent };
         for (const item of items) {
             const v = item.value;
             if (typeof v !== 'object' || v === null)
                 continue;
-            const nested = seek((_b = (_a = v.content) !== null && _a !== void 0 ? _a : v.customXmlOrSmartTagOrSdt) !== null && _b !== void 0 ? _b : (_c = v.sdtContent) === null || _c === void 0 ? void 0 : _c.content);
-            if (nested)
-                return nested;
+            const holder = (_a = v.sdtContent) !== null && _a !== void 0 ? _a : v;
+            const nested = (_c = (_b = v.content) !== null && _b !== void 0 ? _b : v.customXmlOrSmartTagOrSdt) !== null && _c !== void 0 ? _c : (_d = v.sdtContent) === null || _d === void 0 ? void 0 : _d.content;
+            const kind = revisionKindOf(item);
+            const inner = kind && nested ? { kind, element: item, value: v, items: nested, owner: items } : revision;
+            const found = seek(nested, holder, inner);
+            if (found)
+                return found;
         }
         return undefined;
     };
-    return seek(p.content);
+    return seek(p.content, p, undefined);
 }
 export { IMAGE_CONTENT_TYPES_BY_EXTENSION };

package/dist/model/content/List.mjs

@@ -5,7 +5,7 @@ import { Docx4JException } from '../../opc/exceptions.mjs';
 import { DEFAULT_NUMBERING_XML } from '../../parts/wml/defaultNumbering.mjs';
 import { NumberingState, storyKindOf } from '../listnumbering/state.mjs';
 import { LEVELS } from '../listnumbering/definitions.mjs';
-import { isElement, linkParents } from './tree.mjs';
+import { isElement, linkParents, selectedBranchOf, ALTERNATE_CONTENT } from './tree.mjs';
 import { Font } from './Font.mjs';
 function packageOf(body) {
     const pkg = body.package_;
@@ -60,6 +60,9 @@ function numRefOf(paragraph) {
  * counts in. `test/parity.test.mjs`'s `walkNumbering`, which is the harness's own walk: a text
  * box's paragraphs stay in this story's list (they are in the part, in document order) but
  * count in a story of their own, which is docx4j's rule (CR-014 probe P7).
+ *
+ * A kept `mc:AlternateContent` is walked through its selected branch alone (`selectedBranchOf`,
+ * docx4j's `McMode.READ`), so a text box held in both branches counts once (CR-010 phase 3).
  */
 function walkStory(root, state, emit) {
     const walk = (value, current) => {
@@ -70,11 +73,17 @@ function walkStory(root, state, emit) {
         }
         if (typeof value !== 'object' || value === null)
             return;
+        if (typeof value.nodeType === 'number')
+            return; // DOM the model does not type
         if (isElement(value)) {
             walk(value.value, current);
             return;
         }
         const node = value;
+        if (node.TYPE_NAME === ALTERNATE_CONTENT) {
+            walk(selectedBranchOf(node), current);
+            return;
+        }
         let inner = current;
         if (node.TYPE_NAME === 'org_docx4j_wml.P')
             emit(node, current);

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

@@ -1,6 +1,6 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
 import type { CellContext } from '../properties/table.mjs';
-import { type Element, W_NS, type TextSegment, type TextViewOptions } from './tree.mjs';
+import { type Element, W_NS, type SpanEdges, type SegmentOptions, type TextSegment, type TextViewOptions } from './tree.mjs';
 import { Font, type FontTracking } from './Font.mjs';
 import { Range } from './Range.mjs';
 import { type SearchOptions } from './search.mjs';
@@ -160,7 +160,12 @@ export declare class Paragraph {
     get parentTableCell(): TableCell | undefined;
     /** The run-level content controls in this paragraph, in order, nested ones included. */
     get contentControls(): ContentControl[];
-    /** The inline pictures in this paragraph, in order (Office JS Paragraph.inlinePictures). */
+    /**
+     * The inline pictures in this paragraph, in order (Office JS Paragraph.inlinePictures): each
+     * `w:drawing` whose `wp:inline` holds a `pic:pic`, in a run or in the selected branch of a kept
+     * `mc:AlternateContent` (`picturesIn`). An inline chart, text box or group is not one (CR-010
+     * section 12.6).
+     */
     get inlinePictures(): InlinePicture[];
     /** Text inserted at the start, the end, or replacing the whole paragraph's text. */
     insertText(text: string, location: 'Start' | 'End' | 'Replace'): Range;
@@ -198,6 +203,10 @@ export declare class Paragraph {
     replaceText(find: string, replace: string, options?: SearchOptions): number;
     /** The tracked changes in this paragraph, in document order (CR-002 phase F). */
     getTrackedChanges(): TrackedChange[];
+    /**
+     * The paragraph's range: 'Whole' and 'Content' hold its whole content, the pictures at its start and
+     * end among them, so deleting it deletes them (CR-002 section 48); 'Start' and 'End' are collapsed.
+     */
     getRange(location?: 'Whole' | 'Start' | 'End' | 'Content'): Range;
     /**
      * Removes the paragraph from its container. While the package tracks changes, the content
@@ -214,6 +223,12 @@ export declare class Paragraph {
      * Does nothing when the mark is already deleted.
      */
     markDeletedInPlace(tracker: ChangeTracker): void;
+    /**
+     * Queues the relationships that content removed outright referenced (a picture's image, a link's
+     * target), to be settled when the package is saved: each goes then if nothing references it, and
+     * its part with it when nothing else targets that (CR-002 sections 47 and 48).
+     */
+    releaseRelationships(removed: unknown): void;
     /** The paragraph as XML (extension; Office JS getOoxml wraps it in a package). */
     getXml(): Promise<string>;
     /** docx4j: the P's content list. */
@@ -253,15 +268,19 @@ export declare class Paragraph {
     get changeTracker(): ChangeTracker | undefined;
     /** What `Font` needs to write `w:rPrChange`: the tracker, and the runs that are our own insertion (`Range` shares it). */
     fontTracking(): FontTracking | undefined;
-    /** The text segments (w:t, w:tab, ...) with their offsets. */
-    segments(options?: TextViewOptions): TextSegment[];
+    /** The text segments (w:t, w:tab, ...) with their offsets; `{ objects: true }` adds the pictures. */
+    segments(options?: SegmentOptions): TextSegment[];
     /**
      * Replaces the text in [start, end) with `text` and returns the range of the inserted text.
      * Runs are edited in place: a w:t loses or gains characters, a tab or break inside the range
      * is removed, a run left empty is removed. Text is inserted into the w:t at `start`,
      * else into a new run with the formatting of the nearest run.
+     *
+     * The pictures in the span go with its text: those strictly inside it, and those at an edge `edges`
+     * says the span holds (`WHOLE` for a paragraph's whole content), so a span of no text can still
+     * delete a picture (CR-002 section 48).
      */
-    splice(start: number, end: number, text: string, prefer?: 'before' | 'after'): Range;
+    splice(start: number, end: number, text: string, prefer?: 'before' | 'after', edges?: SpanEdges): Range;
     /**
      * Inserts run-level items (runs, hyperlinks, content controls) at a text offset, splitting the
      * run there when the offset falls inside one. PARENT is linked on what is inserted.
@@ -317,6 +336,8 @@ export declare class Paragraph {
      * The text in [start, end) becomes a deletion: the runs holding it are isolated, their `w:t`
      * turned into `w:delText`, and each run of consecutive ones moved into one `w:del`. Text this
      * author had inserted is simply removed, as Word does, rather than nested in a `w:del`.
+     * The pictures in the span (`splice`'s `edges`) are deleted with the text, each in a run of its own
+     * where its run held more, as `InlinePicture.delete` gives it one (CR-002 section 48).
      * Returns the `w:del` elements it made, in document order.
      */
     private deleteText;
@@ -365,6 +386,8 @@ export declare class Paragraph {
      * Splits runs so that every run holding text in [start, end) holds nothing else, and returns
      * the segments inside the span. `splitAt` does the `w:t` boundaries; this also moves the items
      * of a run that straddles a boundary (a tab, a break, a drawing) out into runs of their own.
+     * The pictures in the span (`splice`'s `edges`) are among the segments returned, and a run
+     * holding one holds nothing outside the span either.
      */
     private isolate;
     /** Moves the items before `seg` into a run of their own, in front of `seg`'s run. */