@stll/folio-core 0.43.0 → 0.45.0

package/dist/docx/hyperlinkParser.js

@@ -1,6 +1,7 @@
-import { sanitizeExternalUrl, sanitizeLinkTarget } from "../utils/urlSecurity.js";
+import { sanitizeExternalUrl } from "../utils/urlSecurity.js";
+import { RELATIONSHIP_TYPES, resolveRelationshipIdOfType } from "./relsParser.js";
 import { parseRun } from "./runParser.js";
-import { getAttribute, getChildElements, getLocalName, mergeXmlnsDeclarations, parseNumericAttribute } from "./xmlParser.js";
+import { getAttribute, getChildElements, getLocalName, mergeXmlnsDeclarations, parseNumericAttribute, parseOnOffAttribute } from "./xmlParser.js";
 //#region src/docx/hyperlinkParser.ts
 /**
 * Parse bookmark start (w:bookmarkStart)
@@ -49,11 +50,9 @@ function parseHyperlink(node, rels, styles = null, theme = null, media = null, r
 	const rId = getAttribute(node, "r", "id");
 	if (rId) {
 		hyperlink.rId = rId;
-		if (rels) {
-			const rel = rels.get(rId);
-			if (rel) {
-				if (sanitizeExternalUrl(rel.target)) hyperlink.href = rel.target;
-			}
+		const resolved = resolveRelationshipIdOfType(rels, rId, RELATIONSHIP_TYPES.hyperlink);
+		if (resolved.status === "resolved") {
+			if (sanitizeExternalUrl(resolved.relationship.target)) hyperlink.href = resolved.relationship.target;
 		}
 	}
 	const anchor = getAttribute(node, "w", "anchor");
@@ -64,9 +63,8 @@ function parseHyperlink(node, rels, styles = null, theme = null, media = null, r
 	const tooltip = getAttribute(node, "w", "tooltip");
 	if (tooltip) hyperlink.tooltip = tooltip;
 	const tgtFrame = getAttribute(node, "w", "tgtFrame");
-	if (tgtFrame) hyperlink.target = sanitizeLinkTarget(tgtFrame);
-	const history = getAttribute(node, "w", "history");
-	if (history === "1" || history === "true") hyperlink.history = true;
+	if (tgtFrame) hyperlink.target = tgtFrame;
+	if (parseOnOffAttribute(node, "w", "history") === true) hyperlink.history = true;
 	const docLocation = getAttribute(node, "w", "docLocation");
 	if (docLocation) hyperlink.docLocation = docLocation;
 	const inScopeXmlns = mergeXmlnsDeclarations(rootXmlns, node);
@@ -168,13 +166,11 @@ function getHyperlinkRuns(hyperlink) {
 * @returns The resolved URL or undefined
 */
 function resolveHyperlinkUrl(hyperlink, rels) {
-	if (hyperlink.rId) {
-		const rel = rels.get(hyperlink.rId);
-		if (rel) {
-			if (sanitizeExternalUrl(rel.target)) {
-				hyperlink.href = rel.target;
-				return hyperlink.href;
-			}
+	const resolved = resolveRelationshipIdOfType(rels, hyperlink.rId, RELATIONSHIP_TYPES.hyperlink);
+	if (resolved.status === "resolved") {
+		if (sanitizeExternalUrl(resolved.relationship.target)) {
+			hyperlink.href = resolved.relationship.target;
+			return hyperlink.href;
 		}
 	}
 	if (hyperlink.anchor && !hyperlink.href) {

package/dist/docx/imageParser.d.ts

@@ -1,6 +1,14 @@
 import { document_d_exports } from "../types/document.js";
 import { XmlElement } from "./xmlParser.js";
 //#region src/docx/imageParser.d.ts
+/**
+ * The `a:ext` uri under which Word records that a drawing is decorative. The
+ * extension holds `<adec:decorative val="…"/>`; `CT_NonVisualDrawingProps` has
+ * no `@decorative` attribute for it to be written as.
+ */
+declare const DECORATIVE_EXTENSION_URI = "{C183D7F6-B498-43B3-948B-1728B52AA6E4}";
+/** The namespace the decorative extension's element is bound to. */
+declare const DECORATIVE_NAMESPACE = "http://schemas.microsoft.com/office/drawing/2017/decorative";
 /**
  * Resolve image data from relationships and media map
  *
@@ -9,7 +17,7 @@ import { XmlElement } from "./xmlParser.js";
  * @param media - Media files map
  * @returns Object with src (data URL or blob), mimeType, and filename
  */
-declare function resolveImageData(rId: string, rels: document_d_exports.RelationshipMap | undefined, media: Map<string, document_d_exports.MediaFile> | undefined): {
+declare function resolveImageData(rId: string | undefined, rels: document_d_exports.RelationshipMap | undefined, media: Map<string, document_d_exports.MediaFile> | undefined): {
   src?: string;
   mimeType?: string;
   filename?: string;
@@ -89,4 +97,4 @@ declare function getWrapDistancesPx(image: document_d_exports.Image): {
  */
 declare function needsTextWrapping(image: document_d_exports.Image): boolean;
 //#endregion
-export { getImageDimensionsPx, getImageHeightPx, getImageWidthPx, getWrapDistancesPx, hasAltText, isBehindText, isDecorativeImage, isFloatingImage, isInFrontOfText, isInlineImage, needsTextWrapping, parseDrawing, parseImage, resolveImageData };
+export { DECORATIVE_EXTENSION_URI, DECORATIVE_NAMESPACE, getImageDimensionsPx, getImageHeightPx, getImageWidthPx, getWrapDistancesPx, hasAltText, isBehindText, isDecorativeImage, isFloatingImage, isInFrontOfText, isInlineImage, needsTextWrapping, parseDrawing, parseImage, resolveImageData };

package/dist/docx/imageParser.js

@@ -1,11 +1,13 @@
 import { sanitizeImageSrc } from "../utils/sanitizeImageSrc.js";
 import { emuToPixels } from "../utils/units.js";
 import { sanitizeExternalUrl } from "../utils/urlSecurity.js";
-import { WRAP_ELEMENT_NAMES, parsePositionH, parsePositionV, parseWrapElement } from "./drawingUtils.js";
+import { WRAP_ELEMENT_NAMES, parseAnchorBehindDoc, parsePositionH, parsePositionV, parseWrapElement } from "./drawingUtils.js";
 import { parseGraphicFrameLocks } from "./graphicFrameLocks.js";
-import { resolveTarget } from "./relsParser.js";
+import { parseNonVisualDrawingNames } from "./nonVisualDrawingProps.js";
+import { RELATIONSHIP_TYPES, resolveRelationshipIdOfType } from "./relsParser.js";
 import { isTextBoxDrawing } from "./textBoxParser.js";
-import { findByFullName, findChild, getAttribute, getChildElements, parseNumericAttribute, parseOnOffValue } from "./xmlParser.js";
+import { captureVerbatimXml } from "./verbatimCapture.js";
+import { findByFullName, findChild, findChildByNamespaceUri, findChildrenByNamespaceUri, getAttribute, getChildElements, getLocalName, getNamespaceUri, parseNumericAttribute, parseOnOffAttribute, parseOnOffValue } from "./xmlParser.js";
 //#region src/docx/imageParser.ts
 /**
 * Convert rotation value (1/60000 of a degree) to degrees
@@ -64,6 +66,47 @@ function parseEffectExtent(effectExtent) {
 	};
 }
 /**
+* The `a:ext` uri under which Word records that a drawing is decorative. The
+* extension holds `<adec:decorative val="…"/>`; `CT_NonVisualDrawingProps` has
+* no `@decorative` attribute for it to be written as.
+*/
+const DECORATIVE_EXTENSION_URI = "{C183D7F6-B498-43B3-948B-1728B52AA6E4}";
+/** The namespace the decorative extension's element is bound to. */
+const DECORATIVE_NAMESPACE = "http://schemas.microsoft.com/office/drawing/2017/decorative";
+/**
+* `wp:docPr`'s extension list is DrawingML's (`a:extLst` holding `a:ext`), in
+* the Transitional or the Strict namespace. Matching on the local name alone
+* would take an `extLst` some other namespace owns and replay its children
+* inside an `a:extLst`, which is a different container than the source wrote.
+*/
+const DRAWINGML_NAMESPACE_URIS = /* @__PURE__ */ new Set(["http://schemas.openxmlformats.org/drawingml/2006/main", "http://purl.oclc.org/ooxml/drawingml/main"]);
+/**
+* Read the `wp:docPr` extension list.
+*
+* Only the decorative extension is modeled. The rest — a creation id, a
+* local-DPI hint, whatever a later Word writes — are captured as they were
+* written so the save path can put them back: an extension folio drops is a
+* fact the document had and no longer does.
+*/
+const parseDocPropsExtensions = (docPr) => {
+	const extLst = findChildByNamespaceUri(docPr, DRAWINGML_NAMESPACE_URIS, "extLst");
+	if (!extLst) return { other: [] };
+	const result = { other: [] };
+	for (const ext of findChildrenByNamespaceUri(extLst, DRAWINGML_NAMESPACE_URIS, "ext")) {
+		if (getAttribute(ext, null, "uri")?.toUpperCase() !== "{C183D7F6-B498-43B3-948B-1728B52AA6E4}") {
+			result.other.push(captureVerbatimXml(ext));
+			continue;
+		}
+		const flag = getChildElements(ext).find((child) => getLocalName(child.name) === "decorative" && getNamespaceUri(child) === "http://schemas.microsoft.com/office/drawing/2017/decorative");
+		if (!flag) {
+			result.other.push(captureVerbatimXml(ext));
+			continue;
+		}
+		result.decorative = parseOnOffValue(getAttribute(flag, null, "val")) ?? true;
+	}
+	return result;
+};
+/**
 * Parse document properties (wp:docPr)
 *
 * @param docPr - wp:docPr element
@@ -72,18 +115,17 @@ function parseEffectExtent(effectExtent) {
 function parseDocProps(docPr) {
 	if (!docPr) return {};
 	const id = getAttribute(docPr, null, "id");
-	const name = getAttribute(docPr, null, "name");
-	const descr = getAttribute(docPr, null, "descr");
-	const title = getAttribute(docPr, null, "title");
-	const decorative = parseOnOffValue(getAttribute(docPr, null, "decorative")) === true;
+	const names = parseNonVisualDrawingNames(docPr);
+	const hidden = parseOnOffAttribute(docPr, null, "hidden");
+	const { decorative, other: docPrExtensions } = parseDocPropsExtensions(docPr);
 	const hlinkClickEl = findChild(docPr, "a", "hlinkClick");
 	const hlinkRId = hlinkClickEl ? getAttribute(hlinkClickEl, "r", "id") : null;
 	return {
 		...id != null ? { id } : {},
-		...name != null ? { name } : {},
-		...descr != null ? { alt: descr } : {},
-		...title != null ? { title } : {},
-		...decorative ? { decorative } : {},
+		...names,
+		...decorative === void 0 ? {} : { decorative },
+		...hidden === void 0 ? {} : { hidden },
+		...docPrExtensions.length > 0 ? { docPrExtensions } : {},
 		...hlinkRId != null ? { hlinkRId } : {}
 	};
 }
@@ -178,17 +220,20 @@ function parseImageOpacity(blip) {
 	return Math.max(0, amt / 1e5);
 }
 /**
-* Extract rId from a:blip element
+* Extract rId from a:blip element.
+*
+* Undefined when the drawing has no blip to read one from: a chart, a diagram
+* or an OLE frame carries an `a:graphic` that is not a picture, and a
+* `wp:inline` may carry no graphic at all.
 */
 function extractBlipRId(blip) {
-	if (!blip) return "";
+	if (!blip) return;
 	const rEmbed = getAttribute(blip, "r", "embed");
 	if (rEmbed) return rEmbed;
 	const embed = getAttribute(blip, null, "embed");
 	if (embed) return embed;
 	const rLink = getAttribute(blip, "r", "link");
 	if (rLink) return rLink;
-	return "";
 }
 /**
 * Find transform (a:xfrm) from picture shape properties
@@ -242,10 +287,9 @@ function getMimeType(path) {
 * @returns Object with src (data URL or blob), mimeType, and filename
 */
 function resolveImageData(rId, rels, media) {
-	if (!rId || !rels) return {};
-	const rel = rels.get(rId);
-	if (!rel) return {};
-	const targetPath = rel.target;
+	const resolved = resolveRelationshipIdOfType(rels, rId, RELATIONSHIP_TYPES.image);
+	if (resolved.status !== "resolved") return {};
+	const targetPath = resolved.relationship.target;
 	if (!targetPath) return {};
 	const normalizedPath = normalizeMediaPath(targetPath);
 	const filename = targetPath.split("/").pop();
@@ -319,7 +363,7 @@ function parseInline(inlineEl, rels, media) {
 	if (distR !== void 0) wrap.distR = distR;
 	const image = {
 		type: "image",
-		rId,
+		...rId === void 0 ? {} : { rId },
 		size,
 		wrap
 	};
@@ -327,7 +371,9 @@ function parseInline(inlineEl, rels, media) {
 	if (props.name !== void 0) image.docPrName = props.name;
 	if (props.alt !== void 0) image.alt = props.alt;
 	if (props.title !== void 0) image.title = props.title;
-	if (props.decorative) image.decorative = true;
+	if (props.decorative !== void 0) image.decorative = props.decorative;
+	if (props.hidden !== void 0) image.hidden = props.hidden;
+	if (props.docPrExtensions !== void 0) image.docPrExtensions = props.docPrExtensions;
 	const safeSrc = sanitizeImageSrc(imageData.src);
 	if (safeSrc) image.src = safeSrc;
 	if (imageData.mimeType) image.mimeType = imageData.mimeType;
@@ -337,11 +383,12 @@ function parseInline(inlineEl, rels, media) {
 	if (crop) image.crop = crop;
 	if (opacity !== void 0) image.opacity = opacity;
 	if (frameLocks) image.frameLocks = frameLocks;
-	if (props.hlinkRId && rels) {
-		const safeHref = sanitizeExternalUrl(resolveTarget(rels, props.hlinkRId));
+	const hlink = resolveRelationshipIdOfType(rels, props.hlinkRId, RELATIONSHIP_TYPES.hyperlink);
+	if (hlink.status === "resolved") {
+		const safeHref = sanitizeExternalUrl(hlink.relationship.target);
 		if (safeHref) {
 			image.hlinkHref = safeHref;
-			image.hlinkRId = props.hlinkRId;
+			image.hlinkRId = hlink.relationship.id;
 		}
 	}
 	return image;
@@ -359,7 +406,7 @@ function parseAnchor(anchorEl, rels, media) {
 	const padding = parseEffectExtent(findByFullName(anchorEl, "wp:effectExtent"));
 	const props = parseDocProps(findByFullName(anchorEl, "wp:docPr"));
 	const frameLocks = parseGraphicFrameLocks(anchorEl);
-	const behindDoc = parseOnOffValue(getAttribute(anchorEl, null, "behindDoc")) === true;
+	const behindDoc = parseAnchorBehindDoc(anchorEl);
 	const layoutInCell = parseOnOffAttr(anchorEl, "layoutInCell");
 	const allowOverlap = parseOnOffAttr(anchorEl, "allowOverlap");
 	const anchorDistT = parseNumericAttribute(anchorEl, null, "distT");
@@ -391,7 +438,7 @@ function parseAnchor(anchorEl, rels, media) {
 	const transform = parseTransform(findPictureTransform(anchorEl));
 	const image = {
 		type: "image",
-		rId,
+		...rId === void 0 ? {} : { rId },
 		size,
 		wrap
 	};
@@ -399,7 +446,9 @@ function parseAnchor(anchorEl, rels, media) {
 	if (props.name !== void 0) image.docPrName = props.name;
 	if (props.alt !== void 0) image.alt = props.alt;
 	if (props.title !== void 0) image.title = props.title;
-	if (props.decorative) image.decorative = true;
+	if (props.decorative !== void 0) image.decorative = props.decorative;
+	if (props.hidden !== void 0) image.hidden = props.hidden;
+	if (props.docPrExtensions !== void 0) image.docPrExtensions = props.docPrExtensions;
 	const safeSrc = sanitizeImageSrc(imageData.src);
 	if (safeSrc) image.src = safeSrc;
 	if (imageData.mimeType) image.mimeType = imageData.mimeType;
@@ -412,11 +461,12 @@ function parseAnchor(anchorEl, rels, media) {
 	if (frameLocks) image.frameLocks = frameLocks;
 	if (layoutInCell !== void 0) image.layoutInCell = layoutInCell;
 	if (allowOverlap !== void 0) image.allowOverlap = allowOverlap;
-	if (props.hlinkRId && rels) {
-		const safeHref = sanitizeExternalUrl(resolveTarget(rels, props.hlinkRId));
+	const hlink = resolveRelationshipIdOfType(rels, props.hlinkRId, RELATIONSHIP_TYPES.hyperlink);
+	if (hlink.status === "resolved") {
+		const safeHref = sanitizeExternalUrl(hlink.relationship.target);
 		if (safeHref) {
 			image.hlinkHref = safeHref;
-			image.hlinkRId = props.hlinkRId;
+			image.hlinkRId = hlink.relationship.id;
 		}
 	}
 	return image;
@@ -533,4 +583,4 @@ function needsTextWrapping(image) {
 	].includes(image.wrap.type);
 }
 //#endregion
-export { getImageDimensionsPx, getImageHeightPx, getImageWidthPx, getWrapDistancesPx, hasAltText, isBehindText, isDecorativeImage, isFloatingImage, isInFrontOfText, isInlineImage, needsTextWrapping, parseDrawing, parseImage, resolveImageData };
+export { DECORATIVE_EXTENSION_URI, DECORATIVE_NAMESPACE, getImageDimensionsPx, getImageHeightPx, getImageWidthPx, getWrapDistancesPx, hasAltText, isBehindText, isDecorativeImage, isFloatingImage, isInFrontOfText, isInlineImage, needsTextWrapping, parseDrawing, parseImage, resolveImageData };

package/dist/docx/imageRawXml.d.ts

@@ -12,7 +12,20 @@ declare const isDrawingRawXmlMode: (value: unknown) => value is document_d_expor
 declare const EDITED_PREVIEW_FINGERPRINT = "editedPreview";
 /** Fingerprints modeled image fields which make raw DrawingML stale when edited. */
 declare const imageRawXmlFingerprint: (image: document_d_exports.Image) => string;
-/** Editable raw drawing XML can replay only while its modeled projection is unchanged. */
+/**
+ * Whether the serializer writes the captured raw XML back.
+ *
+ * For an unclassified drawing the capture is a cache of the model, so it
+ * replays only while the two agree. For a classified one the capture *is* the
+ * drawing: a preserve-only drawing has a placeholder image, and a preview-only
+ * group has a raster render of shapes the model cannot hold. Regenerating
+ * either writes something the source never contained — for the group, at best
+ * the one child picture the rasterizer saw first under that child's
+ * relationship, in place of the whole group. So a classified capture is always
+ * written back; a stale fingerprint means the edit that made it stale is lost,
+ * which {@link classifyDrawingSafety} reports as `opaque`, and never that
+ * folio may build a replacement.
+ */
 declare const canReplayEditableImageRawXml: (drawing: document_d_exports.DrawingContent) => boolean;
 /**
  * What a drawing costs the document when Folio writes it back.

package/dist/docx/imageRawXml.js

@@ -26,10 +26,29 @@ const EDITED_PREVIEW_FINGERPRINT = "editedPreview";
 const editableImageProjection = ({ id: _id, rId: _rId, src: _src, mimeType: _mimeType, filename: _filename, ...image }) => image;
 /** Fingerprints modeled image fields which make raw DrawingML stale when edited. */
 const imageRawXmlFingerprint = (image) => canonicalJson(editableImageProjection(image));
-/** Editable raw drawing XML can replay only while its modeled projection is unchanged. */
+/** Whether the modeled image still says what the captured raw drawing says. */
+const modelAgreesWithRawXml = (drawing) => drawing.rawImageFingerprint === void 0 || drawing.rawImageFingerprint === imageRawXmlFingerprint(drawing.image);
+/**
+* Whether the serializer writes the captured raw XML back.
+*
+* For an unclassified drawing the capture is a cache of the model, so it
+* replays only while the two agree. For a classified one the capture *is* the
+* drawing: a preserve-only drawing has a placeholder image, and a preview-only
+* group has a raster render of shapes the model cannot hold. Regenerating
+* either writes something the source never contained — for the group, at best
+* the one child picture the rasterizer saw first under that child's
+* relationship, in place of the whole group. So a classified capture is always
+* written back; a stale fingerprint means the edit that made it stale is lost,
+* which {@link classifyDrawingSafety} reports as `opaque`, and never that
+* folio may build a replacement.
+*/
 const canReplayEditableImageRawXml = (drawing) => {
-	if (drawing.rawXmlMode === DRAWING_RAW_XML_MODES.PRESERVE_ONLY) return true;
-	return drawing.rawImageFingerprint === void 0 || drawing.rawImageFingerprint === imageRawXmlFingerprint(drawing.image);
+	switch (drawing.rawXmlMode) {
+		case DRAWING_RAW_XML_MODES.PRESERVE_ONLY:
+		case DRAWING_RAW_XML_MODES.PREVIEW_ONLY: return true;
+		case void 0: return modelAgreesWithRawXml(drawing);
+		default: return drawing;
+	}
 };
 /**
 * What a drawing costs the document when Folio writes it back.
@@ -46,12 +65,12 @@ const DRAWING_SAFETY_CLASSES = {
 	OPAQUE: "opaque"
 };
 /**
-* Regenerated DrawingML points at `image.rId`, and `serializePicGraphic` falls
-* back to `"rId1"` when that id is empty, which rebinds the picture to whichever
-* relationship happens to be first. A drawing with no relationship id therefore
-* has no faithful regeneration.
+* A drawing with no picture relationship has no picture to regenerate. The
+* serializer writes the anchor back without a graphic, which is faithful for an
+* anchor that never had one and lossy for a chart or an OLE frame, so the
+* drawing counts as opaque and an edit must block the save.
 */
-const canRegenerateDrawing = (drawing) => drawing.image.rId !== "";
+const canRegenerateDrawing = (drawing) => drawing.image.rId !== void 0;
 /**
 * Classify a drawing by what the run serializer will do with it.
 *
@@ -60,9 +79,14 @@ const canRegenerateDrawing = (drawing) => drawing.image.rId !== "";
 */
 const classifyDrawingSafety = (drawing) => {
 	if (drawing.rawXml === void 0) return DRAWING_SAFETY_CLASSES.NATIVE;
-	if (canReplayEditableImageRawXml(drawing)) return DRAWING_SAFETY_CLASSES.REPLAYABLE;
-	if (drawing.rawXmlMode === DRAWING_RAW_XML_MODES.PREVIEW_ONLY) return DRAWING_SAFETY_CLASSES.OPAQUE;
-	return canRegenerateDrawing(drawing) ? DRAWING_SAFETY_CLASSES.NATIVE : DRAWING_SAFETY_CLASSES.OPAQUE;
+	switch (drawing.rawXmlMode) {
+		case DRAWING_RAW_XML_MODES.PRESERVE_ONLY: return DRAWING_SAFETY_CLASSES.REPLAYABLE;
+		case DRAWING_RAW_XML_MODES.PREVIEW_ONLY: return modelAgreesWithRawXml(drawing) ? DRAWING_SAFETY_CLASSES.REPLAYABLE : DRAWING_SAFETY_CLASSES.OPAQUE;
+		case void 0:
+			if (modelAgreesWithRawXml(drawing)) return DRAWING_SAFETY_CLASSES.REPLAYABLE;
+			return canRegenerateDrawing(drawing) ? DRAWING_SAFETY_CLASSES.NATIVE : DRAWING_SAFETY_CLASSES.OPAQUE;
+		default: return drawing;
+	}
 };
 //#endregion
 export { DRAWING_SAFETY_CLASSES, EDITED_PREVIEW_FINGERPRINT, allowsDirectDrawingEdit, canReplayEditableImageRawXml, classifyDrawingSafety, imageRawXmlFingerprint, isDrawingRawXmlMode };

package/dist/docx/markupRangeMarker.d.ts

@@ -0,0 +1,15 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/markupRangeMarker.d.ts
+declare const parseMarkupRangeMarker: (node: XmlElement) => document_d_exports.MarkupRangeMarker;
+declare const parseBookmarkRangeMarker: (node: XmlElement) => document_d_exports.BookmarkRangeMarker;
+/**
+ * `w:author` is required on `CT_MoveBookmark`, so an absent one takes the same
+ * `Unknown` fallback a tracked change takes rather than leaving the saved
+ * package short of an attribute the schema demands. `w:date` is required too,
+ * but inventing a timestamp would state a fact about the document that is not
+ * true, so an absent date stays absent.
+ */
+declare const parseMoveBookmarkMarker: (node: XmlElement) => document_d_exports.MoveBookmarkMarker;
+//#endregion
+export { parseBookmarkRangeMarker, parseMarkupRangeMarker, parseMoveBookmarkMarker };

package/dist/docx/markupRangeMarker.js

@@ -0,0 +1,44 @@
+import { getAttribute, parseNumericAttribute } from "./xmlParser.js";
+//#region src/docx/markupRangeMarker.ts
+/** ST_DisplacedByCustomXml. A value outside it is not a placement folio can honour. */
+const DISPLACED_BY_CUSTOM_XML = /* @__PURE__ */ new Set(["next", "prev"]);
+const parseDisplacedByCustomXml = (node) => {
+	const value = getAttribute(node, "w", "displacedByCustomXml") ?? "";
+	return DISPLACED_BY_CUSTOM_XML.has(value) ? value : void 0;
+};
+const parseMarkupRangeMarker = (node) => {
+	const marker = { id: parseNumericAttribute(node, "w", "id") ?? 0 };
+	const displacedByCustomXml = parseDisplacedByCustomXml(node);
+	if (displacedByCustomXml !== void 0) marker.displacedByCustomXml = displacedByCustomXml;
+	return marker;
+};
+const parseBookmarkRangeMarker = (node) => {
+	const marker = {
+		...parseMarkupRangeMarker(node),
+		name: getAttribute(node, "w", "name") ?? ""
+	};
+	const colFirst = parseNumericAttribute(node, "w", "colFirst");
+	if (colFirst !== void 0) marker.colFirst = colFirst;
+	const colLast = parseNumericAttribute(node, "w", "colLast");
+	if (colLast !== void 0) marker.colLast = colLast;
+	return marker;
+};
+/**
+* `w:author` is required on `CT_MoveBookmark`, so an absent one takes the same
+* `Unknown` fallback a tracked change takes rather than leaving the saved
+* package short of an attribute the schema demands. `w:date` is required too,
+* but inventing a timestamp would state a fact about the document that is not
+* true, so an absent date stays absent.
+*/
+const parseMoveBookmarkMarker = (node) => {
+	const author = (getAttribute(node, "w", "author") ?? "").trim();
+	const marker = {
+		...parseBookmarkRangeMarker(node),
+		author: author.length > 0 ? author : "Unknown"
+	};
+	const date = (getAttribute(node, "w", "date") ?? "").trim();
+	if (date.length > 0) marker.date = date;
+	return marker;
+};
+//#endregion
+export { parseBookmarkRangeMarker, parseMarkupRangeMarker, parseMoveBookmarkMarker };

package/dist/docx/mathToMathml.js

@@ -1,4 +1,5 @@
 import { findChildByLocalName, getLocalName } from "./xmlParser.js";
+import { escapeXmlText } from "@stll/docx-core";
 //#region src/docx/mathToMathml.ts
 /**
 * OMML → MathML conversion.
@@ -95,13 +96,13 @@ const MATH_OPERATOR_HINT = /* @__PURE__ */ new Set([
 	"…"
 ]);
 function renderElement(el) {
-	if (el.type === "text") return escapeXml(textValue(el));
+	if (el.type === "text") return escapeXmlText(textValue(el));
 	if (el.type !== "element") return "";
 	switch (el.name ? getLocalName(el.name) : "") {
 		case "oMath":
 		case "oMathPara": return renderChildren(el);
 		case "r": return renderRun(el);
-		case "t": return escapeXml(extractText(el));
+		case "t": return escapeXmlText(extractText(el));
 		case "f": return renderFraction(el);
 		case "num":
 		case "den": return wrapMrow(renderChildren(el));
@@ -179,8 +180,8 @@ function tokenizeMathText(text) {
 	let bufKind = null;
 	const flush = () => {
 		if (!buf) return;
-		if (bufKind === "digit") out += `<mn>${escapeXml(buf)}</mn>`;
-		else out += `<mi>${escapeXml(buf)}</mi>`;
+		if (bufKind === "digit") out += `<mn>${escapeXmlText(buf)}</mn>`;
+		else out += `<mi>${escapeXmlText(buf)}</mi>`;
 		buf = "";
 		bufKind = null;
 	};
@@ -193,7 +194,7 @@ function tokenizeMathText(text) {
 		const kind = classifyChar(ch);
 		if (kind === "operator") {
 			flush();
-			out += `<mo>${escapeXml(ch)}</mo>`;
+			out += `<mo>${escapeXmlText(ch)}</mo>`;
 			continue;
 		}
 		if (kind === "digit") {
@@ -202,7 +203,7 @@ function tokenizeMathText(text) {
 			continue;
 		}
 		flush();
-		out += `<mi>${escapeXml(ch)}</mi>`;
+		out += `<mi>${escapeXmlText(ch)}</mi>`;
 	}
 	flush();
 	return out;
@@ -258,7 +259,7 @@ function renderNary(el) {
 	const chr = (chrEl ? getAttrValue(chrEl, "val") : null) || "∫";
 	const limLocEl = naryPr ? findChildByLocalName(naryPr, "limLoc") : null;
 	const limLoc = (limLocEl ? getAttrValue(limLocEl, "val") : null) || "subSup";
-	const opMml = `<mo>${escapeXml(chr)}</mo>`;
+	const opMml = `<mo>${escapeXmlText(chr)}</mo>`;
 	const subMml = sub ? wrapMrow(renderChildren(sub)) : "";
 	const supMml = sup ? wrapMrow(renderChildren(sup)) : "";
 	const bodyMml = body ? wrapMrow(renderChildren(body)) : "<mrow/>";
@@ -277,8 +278,8 @@ function renderDelimiter(el) {
 	const begChr = begChrEl ? getAttrValue(begChrEl, "val") ?? "(" : "(";
 	const endChr = endChrEl ? getAttrValue(endChrEl, "val") ?? ")" : ")";
 	const sepChr = sepChrEl ? getAttrValue(sepChrEl, "val") ?? "|" : "|";
-	const inner = (el.elements ?? []).filter((c) => c.type === "element" && getLocalName(c.name ?? "") === "e").map((c) => wrapMrow(renderChildren(c))).join(`<mo>${escapeXml(sepChr)}</mo>`);
-	return `<mrow><mo>${escapeXml(begChr)}</mo>${inner}<mo>${escapeXml(endChr)}</mo></mrow>`;
+	const inner = (el.elements ?? []).filter((c) => c.type === "element" && getLocalName(c.name ?? "") === "e").map((c) => wrapMrow(renderChildren(c))).join(`<mo>${escapeXmlText(sepChr)}</mo>`);
+	return `<mrow><mo>${escapeXmlText(begChr)}</mo>${inner}<mo>${escapeXmlText(endChr)}</mo></mrow>`;
 }
 function renderMatrix(el) {
 	return `<mtable>${(el.elements ?? []).filter((c) => c.type === "element" && getLocalName(c.name ?? "") === "mr").map(renderMatrixRow).join("")}</mtable>`;
@@ -291,7 +292,7 @@ function renderAccent(el) {
 	const chrEl = accPr ? findChildByLocalName(accPr, "chr") : null;
 	const chr = chrEl ? getAttrValue(chrEl, "val") ?? "̂" : "̂";
 	const base = findChildByLocalName(el, "e");
-	return `<mover accent="true">${base ? wrapMrow(renderChildren(base)) : "<mrow/>"}<mo>${escapeXml(chr)}</mo></mover>`;
+	return `<mover accent="true">${base ? wrapMrow(renderChildren(base)) : "<mrow/>"}<mo>${escapeXmlText(chr)}</mo></mover>`;
 }
 function renderBar(el) {
 	const barPr = findChildByLocalName(el, "barPr");
@@ -311,7 +312,7 @@ function renderGroupChr(el) {
 	const chr = chrEl ? getAttrValue(chrEl, "val") ?? defaultChr : defaultChr;
 	const base = findChildByLocalName(el, "e");
 	const baseMml = base ? wrapMrow(renderChildren(base)) : "<mrow/>";
-	const grouper = `<mo stretchy="true">${escapeXml(chr)}</mo>`;
+	const grouper = `<mo stretchy="true">${escapeXmlText(chr)}</mo>`;
 	return pos === "top" ? `<mover>${baseMml}${grouper}</mover>` : `<munder>${baseMml}${grouper}</munder>`;
 }
 function renderLimLow(el) {
@@ -350,8 +351,5 @@ function getAttrValue(el, localAttr) {
 		return String(v);
 	}
 }
-function escapeXml(s) {
-	return s.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
-}
 //#endregion
 export { ommlToMathml };

package/dist/docx/nonVisualDrawingProps.d.ts

@@ -0,0 +1,34 @@
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/nonVisualDrawingProps.d.ts
+/** The authored name, alt text and title of a drawing object. */
+type NonVisualDrawingNames = {
+  /** `@name`, schema-required, so `""` means the object was never named. */
+  name?: string;
+  /** `@descr`: alt text, accessibility content. */
+  alt?: string;
+  /** `@title`. */
+  title?: string;
+};
+/**
+ * Read `@name`, `@descr` and `@title` off a `CT_NonVisualDrawingProps` element.
+ *
+ * An attribute that is not there stays absent. `@name` is schema-required, so
+ * an unnamed object still writes one, and `name=""` is the marker the writer
+ * below mints for exactly that: reading it back as an authored name would make
+ * `absent → save → parse` land on `""` instead of absent, and no reader can
+ * tell the two apart. `@descr` and `@title` are optional and written only when
+ * authored, so `""` in either is a string someone wrote.
+ */
+declare const parseNonVisualDrawingNames: (element: XmlElement | null | undefined) => NonVisualDrawingNames;
+/**
+ * The `name`, `descr` and `title` attributes of a `CT_NonVisualDrawingProps`
+ * element, leading space included.
+ *
+ * `@name` is schema-required, so an object carrying none writes the empty
+ * string. folio does not name an object it did not author: a generated
+ * "Shape 3" would overwrite the author's own name for every drawing whose
+ * name did not survive the model, and read back as authored content.
+ */
+declare const serializeNonVisualDrawingNames: (names: NonVisualDrawingNames) => string;
+//#endregion
+export { NonVisualDrawingNames, parseNonVisualDrawingNames, serializeNonVisualDrawingNames };

package/dist/docx/nonVisualDrawingProps.js

@@ -0,0 +1,46 @@
+import { getAttribute } from "./xmlParser.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
+//#region src/docx/nonVisualDrawingProps.ts
+/**
+* `CT_NonVisualDrawingProps` (`wp:docPr`, `wps:cNvPr`, `pic:cNvPr`) carries the
+* three authored strings every drawing object has: its name, its alt text
+* (`descr`) and its title. They are authored content, not folio's to mint, so
+* one reader and one writer own them for every drawing kind.
+*/
+/**
+* Read `@name`, `@descr` and `@title` off a `CT_NonVisualDrawingProps` element.
+*
+* An attribute that is not there stays absent. `@name` is schema-required, so
+* an unnamed object still writes one, and `name=""` is the marker the writer
+* below mints for exactly that: reading it back as an authored name would make
+* `absent → save → parse` land on `""` instead of absent, and no reader can
+* tell the two apart. `@descr` and `@title` are optional and written only when
+* authored, so `""` in either is a string someone wrote.
+*/
+const parseNonVisualDrawingNames = (element) => {
+	if (!element) return {};
+	const name = getAttribute(element, null, "name");
+	const descr = getAttribute(element, null, "descr");
+	const title = getAttribute(element, null, "title");
+	return {
+		...name !== null && name !== "" ? { name } : {},
+		...descr !== null ? { alt: descr } : {},
+		...title !== null ? { title } : {}
+	};
+};
+/**
+* The `name`, `descr` and `title` attributes of a `CT_NonVisualDrawingProps`
+* element, leading space included.
+*
+* `@name` is schema-required, so an object carrying none writes the empty
+* string. folio does not name an object it did not author: a generated
+* "Shape 3" would overwrite the author's own name for every drawing whose
+* name did not survive the model, and read back as authored content.
+*/
+const serializeNonVisualDrawingNames = (names) => {
+	const descr = names.alt === void 0 ? "" : ` descr="${escapeXmlAttribute(names.alt)}"`;
+	const title = names.title === void 0 ? "" : ` title="${escapeXmlAttribute(names.title)}"`;
+	return ` name="${escapeXmlAttribute(names.name ?? "")}"${descr}${title}`;
+};
+//#endregion
+export { parseNonVisualDrawingNames, serializeNonVisualDrawingNames };