@stll/folio-core 0.45.0 → 0.47.0

package/dist/docx/textBoxParser.d.ts

@@ -1,7 +1,8 @@
 import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
-import { StyleMap } from "./styleParser.js";
+import { ParseContext } from "./parseContext.js";
 import { XmlElement } from "./xmlParser.js";
+import { StyleMap } from "./styleParser.js";
 //#region src/docx/textBoxParser.d.ts
 /**
  * Extract raw paragraph elements from w:txbxContent
@@ -42,9 +43,10 @@ declare function isShapeTextBox(wsp: XmlElement): boolean;
  * parseTextBoxContent() separately with the required parsers.
  *
  * @param drawingEl - The w:drawing XML element
+ * @param context - Where an outline dash outside `ST_PresetLineDashVal` is reported
  * @returns TextBox object with placeholder content, or null if not a text box
  */
-declare function parseTextBox(drawingEl: XmlElement): document_d_exports.TextBox | null;
+declare function parseTextBox(drawingEl: XmlElement, context?: ParseContext): document_d_exports.TextBox | null;
 /**
  * Parse text box content XML element
  * @param wsp - The wps:wsp element containing the text box
@@ -112,5 +114,28 @@ declare function resolveTextBoxOutlineColor(textBox: document_d_exports.TextBox)
  * Get outline width in pixels
  */
 declare function getTextBoxOutlineWidthPx(textBox: document_d_exports.TextBox): number;
+type TextBoxRunScan = {
+  textBoxDrawings: XmlElement[];
+  vmlTextBoxes: XmlElement[];
+  hasNonTextBoxContent: boolean;
+};
+/**
+ * What a run's markup holds for the text-box pass, by kind.
+ *
+ * Two readers need this answer and they must not drift: the enrichment pass
+ * claims these elements, and `parseParagraphContents` has to keep the run they
+ * sit in even though the run parses to nothing until the pass fills it. It
+ * lives here, with `isTextBoxDrawing` and `parseTextBox`, so there is one.
+ */
+type ScanRunForTextBoxDrawingsOptions = {
+  xmlRun: XmlElement;
+  /**
+   * `isVmlPictParsedByRunParser`, passed rather than imported: the run parser
+   * reaches this module through the image parsers, so reading it from here
+   * would close a cycle.
+   */
+  claimedByRunParser: (pictElement: XmlElement) => boolean;
+};
+declare const scanRunForTextBoxDrawings: ({ xmlRun, claimedByRunParser }: ScanRunForTextBoxDrawingsOptions) => TextBoxRunScan;
 //#endregion
-export { ParagraphParserFn, TableParserFn, extractTextBoxContentElements, getTextBoxContentElement, getTextBoxDimensionsPx, getTextBoxHeightPx, getTextBoxMarginsPx, getTextBoxOutlineWidthPx, getTextBoxText, getTextBoxWidthPx, hasTextBoxContent, hasTextBoxFill, hasTextBoxOutline, isFloatingTextBox, isShapeTextBox, isTextBoxDrawing, parseTextBox, parseTextBoxContent, parseTextBoxFromShape, resolveTextBoxFillColor, resolveTextBoxOutlineColor };
+export { ParagraphParserFn, ScanRunForTextBoxDrawingsOptions, TableParserFn, TextBoxRunScan, extractTextBoxContentElements, getTextBoxContentElement, getTextBoxDimensionsPx, getTextBoxHeightPx, getTextBoxMarginsPx, getTextBoxOutlineWidthPx, getTextBoxText, getTextBoxWidthPx, hasTextBoxContent, hasTextBoxFill, hasTextBoxOutline, isFloatingTextBox, isShapeTextBox, isTextBoxDrawing, parseTextBox, parseTextBoxContent, parseTextBoxFromShape, resolveTextBoxFillColor, resolveTextBoxOutlineColor, scanRunForTextBoxDrawings };

package/dist/docx/textBoxParser.js

@@ -1,7 +1,8 @@
 import { emuToPixels } from "../utils/units.js";
-import { parseAnchorPosition, parseAnchorWrap, parseFill, parseOutline, resolveColorValueToHex } from "./drawingUtils.js";
+import { WORDPROCESSING_DRAWING_NAMESPACE_URIS, parseDrawingAnchor } from "./drawingAnchor.js";
+import { parseAnchorPosition, parseAnchorWrap, parseFill, parseInlineWrap, parseOutline, resolveColorValueToHex } from "./drawingUtils.js";
 import { parseNonVisualDrawingNames } from "./nonVisualDrawingProps.js";
-import { findByFullName, findChildByLocalName, findChildByNamespaceUri, findChildrenByLocalName, findChildrenByNamespaceUri, getAttribute, getChildElements, parseNumericAttribute, parseOnOffAttribute } from "./xmlParser.js";
+import { findByFullName, findChildByLocalName, findChildByNamespaceUri, findChildrenByLocalName, findChildrenByNamespaceUri, findDeep, getAttribute, getChildElements, getLocalName, parseNumericAttribute, parseOnOffAttribute } from "./xmlParser.js";
 //#region src/docx/textBoxParser.ts
 const DRAWINGML_MAIN_NAMESPACE_URIS = /* @__PURE__ */ new Set(["http://schemas.openxmlformats.org/drawingml/2006/main", "http://purl.oclc.org/ooxml/drawingml/main"]);
 const WORDPROCESSING_SHAPE_NAMESPACE_URIS = /* @__PURE__ */ new Set(["http://schemas.microsoft.com/office/word/2010/wordprocessingShape"]);
@@ -98,11 +99,17 @@ function parseTextBoxContent(txbxContent, parseParagraph, parseTable, styles, th
 	return blocks;
 }
 /**
+* The `wp:inline` or `wp:anchor` a drawing hangs off, resolved by namespace:
+* the `wp` prefix is the producer's choice and a package free to bind the
+* namespace elsewhere writes the same text box.
+*/
+const findDrawingContainer = (drawingEl) => findChildByNamespaceUri(drawingEl, WORDPROCESSING_DRAWING_NAMESPACE_URIS, "inline") ?? findChildByNamespaceUri(drawingEl, WORDPROCESSING_DRAWING_NAMESPACE_URIS, "anchor");
+/**
 * Check if a drawing element contains a text box
 * Text boxes are shapes with wps:txbx content
 */
 function isTextBoxDrawing(drawingEl) {
-	const container = getChildElements(drawingEl).find((el) => el.name === "wp:inline" || el.name === "wp:anchor");
+	const container = findDrawingContainer(drawingEl);
 	if (!container) return false;
 	const graphic = findByFullName(container, "a:graphic");
 	if (!graphic) return false;
@@ -127,12 +134,13 @@ function isShapeTextBox(wsp) {
 * parseTextBoxContent() separately with the required parsers.
 *
 * @param drawingEl - The w:drawing XML element
+* @param context - Where an outline dash outside `ST_PresetLineDashVal` is reported
 * @returns TextBox object with placeholder content, or null if not a text box
 */
-function parseTextBox(drawingEl) {
-	const container = getChildElements(drawingEl).find((el) => el.name === "wp:inline" || el.name === "wp:anchor");
+function parseTextBox(drawingEl, context) {
+	const container = findDrawingContainer(drawingEl);
 	if (!container) return null;
-	const isAnchor = container.name === "wp:anchor";
+	const isAnchor = getLocalName(container.name) === "anchor";
 	const graphic = findByFullName(container, "a:graphic");
 	if (!graphic) return null;
 	const graphicData = findByFullName(graphic, "a:graphicData");
@@ -151,7 +159,7 @@ function parseTextBox(drawingEl) {
 	const id = docPr ? getAttribute(docPr, null, "id") ?? void 0 : void 0;
 	const names = parseNonVisualDrawingNames(docPr);
 	const fill = parseFill(spPr ?? null);
-	const outline = parseOutline(spPr ?? null);
+	const outline = parseOutline(spPr ?? null, context);
 	const bodyProps = parseBodyProperties(bodyPr ?? null);
 	const textBox = {
 		type: "textBox",
@@ -172,7 +180,9 @@ function parseTextBox(drawingEl) {
 		if (position) textBox.position = position;
 		const wrap = parseAnchorWrap(container);
 		if (wrap) textBox.wrap = wrap;
-	} else textBox.wrap = { type: "inline" };
+		const anchor = parseDrawingAnchor(container);
+		if (anchor) textBox.anchor = anchor;
+	} else textBox.wrap = parseInlineWrap(container);
 	return textBox;
 }
 /**
@@ -290,6 +300,7 @@ const getTextBoxBlockText = (block) => {
 		return runTexts.join("");
 	}
 	if (block.type === "table") return block.rows.map((row) => row.cells.map((cell) => cell.content.map(getTextBoxBlockText).join("\n")).join("	")).join("\n");
+	if (block.type !== "blockSdt") return "";
 	return block.content.map(getTextBoxBlockText).join("\n");
 };
 /**
@@ -313,5 +324,54 @@ function getTextBoxOutlineWidthPx(textBox) {
 	if (!textBox.outline?.width) return 0;
 	return emuToPixels(textBox.outline.width);
 }
+const scanRunForTextBoxDrawings = ({ xmlRun, claimedByRunParser }) => {
+	const textBoxDrawings = [];
+	const vmlTextBoxes = [];
+	let hasNonTextBoxContent = false;
+	const visitDrawing = (drawingEl) => {
+		if (isTextBoxDrawing(drawingEl)) {
+			textBoxDrawings.push(drawingEl);
+			return;
+		}
+		hasNonTextBoxContent = true;
+	};
+	for (const el of getChildElements(xmlRun)) {
+		const name = getLocalName(el.name ?? "");
+		if (name === "rPr") continue;
+		if (name === "drawing") {
+			visitDrawing(el);
+			continue;
+		}
+		if (name === "pict") {
+			if (findDeep(el, "v", "textbox") && !claimedByRunParser(el)) vmlTextBoxes.push(el);
+			else hasNonTextBoxContent = true;
+			continue;
+		}
+		if (name === "AlternateContent") {
+			const branches = getChildElements(el);
+			const choice = branches.find((branch) => getLocalName(branch.name ?? "") === "Choice");
+			const fallback = branches.find((branch) => getLocalName(branch.name ?? "") === "Fallback");
+			const tryBranch = (branch) => {
+				if (!branch) return false;
+				let found = false;
+				for (const innerEl of getChildElements(branch)) if (getLocalName(innerEl.name ?? "") === "drawing") {
+					visitDrawing(innerEl);
+					found = true;
+				}
+				return found;
+			};
+			let foundInBranch = tryBranch(choice);
+			if (!foundInBranch) foundInBranch = tryBranch(fallback);
+			if (!foundInBranch) hasNonTextBoxContent = true;
+			continue;
+		}
+		hasNonTextBoxContent = true;
+	}
+	return {
+		textBoxDrawings,
+		vmlTextBoxes,
+		hasNonTextBoxContent
+	};
+};
 //#endregion
-export { extractTextBoxContentElements, getTextBoxContentElement, getTextBoxDimensionsPx, getTextBoxHeightPx, getTextBoxMarginsPx, getTextBoxOutlineWidthPx, getTextBoxText, getTextBoxWidthPx, hasTextBoxContent, hasTextBoxFill, hasTextBoxOutline, isFloatingTextBox, isShapeTextBox, isTextBoxDrawing, parseTextBox, parseTextBoxContent, parseTextBoxFromShape, resolveTextBoxFillColor, resolveTextBoxOutlineColor };
+export { extractTextBoxContentElements, getTextBoxContentElement, getTextBoxDimensionsPx, getTextBoxHeightPx, getTextBoxMarginsPx, getTextBoxOutlineWidthPx, getTextBoxText, getTextBoxWidthPx, hasTextBoxContent, hasTextBoxFill, hasTextBoxOutline, isFloatingTextBox, isShapeTextBox, isTextBoxDrawing, parseTextBox, parseTextBoxContent, parseTextBoxFromShape, resolveTextBoxFillColor, resolveTextBoxOutlineColor, scanRunForTextBoxDrawings };

package/dist/docx/themeColorAttribute.d.ts

@@ -0,0 +1,13 @@
+import { ParseContext } from "./parseContext.js";
+import { ThemeColorValue } from "@stll/docx-core/model";
+//#region src/docx/themeColorAttribute.d.ts
+type ThemeColorAttributeOptions = {
+  /** The attribute as written, or `null` when the element does not carry it. */
+  raw: string | null | undefined;
+  /** The element the attribute sits on, for the warning's location. */
+  element?: string | undefined;
+  context?: ParseContext | undefined;
+};
+declare const parseThemeColorAttribute: ({ raw, element, context }: ThemeColorAttributeOptions) => ThemeColorValue | undefined;
+//#endregion
+export { ThemeColorAttributeOptions, parseThemeColorAttribute };

package/dist/docx/themeColorAttribute.js

@@ -0,0 +1,24 @@
+import { PARSE_WARNING_CODES, readThemeColor } from "@stll/docx-core/model";
+//#region src/docx/themeColorAttribute.ts
+/**
+* The one reader for a theme-colour attribute.
+*
+* `w:themeColor`, `w:themeFill` and the `w:clrSchemeMapping` values are all
+* `ST_ThemeColor`. Before this the attribute was narrowed against a union that
+* carried DrawingML slot names instead, so `hyperlink` — the token Word writes
+* for a hyperlink's colour — failed to narrow and the attribute was dropped at
+* parse time, taking it out of the next save. The enumeration is now generated
+* from the schema, and a token outside it is captured rather than refused, the
+* way `CT_Border/@w:val` already keeps a style outside `ST_Border`.
+*/
+const parseThemeColorAttribute = ({ raw, element, context }) => {
+	const value = readThemeColor(raw);
+	if (value !== void 0 && typeof value !== "string") context?.warn({
+		code: PARSE_WARNING_CODES.unrecognisedThemeColor,
+		value: value.raw,
+		...element === void 0 ? {} : { element }
+	});
+	return value;
+};
+//#endregion
+export { parseThemeColorAttribute };

package/dist/docx/trackedMoveRangeNormalization.js

@@ -1,4 +1,5 @@
-import { InlineContentRemovals, visitDocxParagraphs, visitInlineContentSlots } from "./paragraphTraversal.js";
+import { InlineContentRemovals } from "./inlineContentRemovals.js";
+import { visitDocxParagraphs, visitInlineContentSlots } from "./paragraphTraversal.js";
 import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/trackedMoveRangeNormalization.ts
 /** The code this normalisation is reported under, owned here, not at the caller. */

package/dist/docx/unzip.js

@@ -1,6 +1,7 @@
 import { bytesToDataUrl } from "../utils/base64.js";
 import { DOCX_CONTAINER_TYPES, detectDocxContainerType } from "./encryption/containerFormat.js";
 import { openDocxBuffer } from "./encryption/openEncryptedDocx.js";
+import { decodeXmlBytes } from "./xmlEncoding.js";
 import { FOLIO_XML_RESOURCE_LIMITS, assertXmlResourceLimits, createXmlPackageBudget } from "./xmlResourceLimits.js";
 import JSZip from "jszip";
 //#region src/docx/unzip.ts
@@ -161,13 +162,13 @@ async function unzipDocx(buffer, options = {}) {
 		if (lowerPath.endsWith(".xml") || lowerPath.endsWith(".rels")) {
 			assertEntrySize(path, declaredSize, limits.maxXmlBytes);
 			if (options.extractAllXml === false && !shouldExtractXmlPart(lowerPath)) continue;
-			extractionTasks.push(() => file.async("text").then((xmlContent) => {
-				assertExtractedSize(path, xmlContent.length, limits.maxXmlBytes);
+			extractionTasks.push(() => file.async("uint8array").then((xmlBytes) => {
+				assertExtractedSize(path, xmlBytes.byteLength, limits.maxXmlBytes);
 				return {
 					type: "xml",
 					path,
 					lowerPath,
-					content: xmlContent
+					content: decodeXmlBytes(xmlBytes)
 				};
 			}));
 		} else if (lowerPath.startsWith("word/media/")) {
@@ -456,7 +457,7 @@ function extractFile(content, path) {
 	const file = content.originalZip.file(path);
 	if (!file || !isParsedDocxEntry(path)) return Promise.resolve(null);
 	const lowerPath = path.toLowerCase();
-	if (lowerPath.endsWith(".xml") || lowerPath.endsWith(".rels")) return file.async("text");
+	if (lowerPath.endsWith(".xml") || lowerPath.endsWith(".rels")) return file.async("uint8array").then(decodeXmlBytes);
 	return file.async("arraybuffer");
 }
 /**

package/dist/docx/vmlImageParser.d.ts

@@ -5,12 +5,37 @@ import { XmlElement } from "./xmlParser.js";
  * Whether a `w:pict` that resolved to no image must still be kept verbatim.
  *
  * VML has no serializer of its own, so an unresolved `w:pict` is only ever
- * preserved or lost. Two owners are excluded: a `v:textbox` belongs to the
- * text-box enrichment pass, which rebuilds it as an editable shape, and a
- * watermark shape belongs to watermarkParser; preserving either would emit the
- * same artwork twice.
+ * preserved or lost. One owner is excluded: a `v:textbox` belongs to the
+ * text-box enrichment pass, which rebuilds it as an editable shape, and
+ * preserving it here as well would emit the same artwork twice.
+ *
+ * A watermark shape is not a second exclusion. Declining for one was a guess
+ * about another module, and `watermarkParser` claims by a far narrower rule
+ * than `isWatermarkShape` states: a direct `v:shape` child of a `w:pict`,
+ * carrying a non-empty `v:textpath` or a `v:imagedata`, alone in its paragraph,
+ * in a header. A `v:oval`, a shape nested in a `v:group`, a shape sharing its
+ * paragraph with text, and every `w:pict` in a footer or in the body fall
+ * outside it, so their artwork was declined here and claimed by no one. The
+ * watermark owner removes its own artwork from the model instead, by emptying
+ * the paragraph it detached, so this predicate need not guess who claimed what.
  */
 declare function shouldPreserveRawVmlPict(pictElement: XmlElement): boolean;
+/**
+ * Whether the run parser turns this `w:pict` into run content of its own.
+ *
+ * Exactly one owner may represent a `w:pict`: the run parser, whose drawing
+ * carries the whole element as captured XML, or the text-box enrichment pass,
+ * which rebuilds one `v:textbox` as an editable shape. Two owners write the
+ * same artwork twice, and when the pict holds text, the saved document says it
+ * twice.
+ *
+ * The enrichment asks this rather than re-deriving the answer from the markup:
+ * its own reading (`v:imagedata` present) named only the picture path, so a
+ * `v:group` claimed by the preview path was represented by both owners. The
+ * result is a pure function of the element, so asking it a second time costs
+ * only the work the run parser already did.
+ */
+declare const isVmlPictParsedByRunParser: (pictElement: XmlElement, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null) => boolean;
 /**
  * Parse a `w:pict` element into an inline image, or null when it carries no
  * ordinary VML picture (no resolvable `<v:imagedata>`, or a watermark shape).
@@ -22,4 +47,4 @@ declare function shouldPreserveRawVmlPict(pictElement: XmlElement): boolean;
  */
 declare function parseVmlImageContent(pictElement: XmlElement, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, rootXmlns?: Record<string, string>): document_d_exports.DrawingContent | null;
 //#endregion
-export { parseVmlImageContent, shouldPreserveRawVmlPict };
+export { isVmlPictParsedByRunParser, parseVmlImageContent, shouldPreserveRawVmlPict };

package/dist/docx/vmlImageParser.js

@@ -1,12 +1,45 @@
 import { sanitizeImageSrc } from "../utils/sanitizeImageSrc.js";
 import { pixelsToEmu } from "../utils/units.js";
 import { resolveImageData } from "./imageParser.js";
+import { imageRawXmlFingerprint } from "./imageRawXml.js";
 import { PREVIEW_KINDS } from "./previewBudget.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
 import { isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx, vmlSvgDataUrl } from "./vmlPreview.js";
 import { isWatermarkShape } from "./watermarkParser.js";
 import { cloneWithXmlnsDeclarations, findAllDeep, findChild, findDeep, getAttribute, getChildElements, getLocalName } from "./xmlParser.js";
+import { DRAWING_RAW_XML_MODES, relationshipIdOf } from "@stll/docx-core/model";
 //#region src/docx/vmlImageParser.ts
+/**
+* VML image parser — legacy `w:pict` inline pictures.
+*
+* Older Word documents (and some exporters) embed inline pictures such as
+* header logos as VML instead of DrawingML:
+*
+*   <w:r><w:pict>
+*     <v:shape id="Picture 1" type="#_x0000_t75" style="width:120pt;height:40pt">
+*       <v:imagedata r:id="rId7" o:title="logo"/>
+*     </v:shape>
+*   </w:pict></w:r>
+*
+* The run parser used to drop `w:pict` entirely, so these pictures never
+* rendered. This resolves `<v:imagedata r:id>` to the same media part a
+* DrawingML image uses and produces the identical `DrawingContent` / `Image`
+* node, so the rest of the pipeline (ProseMirror conversion, layout, painter)
+* renders it through the existing inline-image path.
+*
+* The original VML is preserved verbatim on the returned drawing's `rawXml`:
+* the serializer has no VML synthesis path (it only emits DrawingML), so
+* without this a `w:pict` would round-trip as a `<w:drawing>`. Emitting the
+* captured XML keeps save byte-for-byte for these runs.
+*
+* A watermark `watermarkParser` claimed is detached from its hosting
+* paragraph, so modelling it here as well would paint it twice; the
+* `isWatermarkShape` guard below keeps this reader off that shape. It does not
+* decide whether the markup survives: what nothing claims is preserved
+* verbatim by `shouldPreserveRawVmlPict`.
+*
+* Ported from eigenpal/docx-editor `vmlImageParser.ts`.
+*/
 const VML_POSITION_ABSOLUTE = "absolute";
 const IMAGE_WRAP_INLINE = "inline";
 const IMAGE_WRAP_BEHIND = "behind";
@@ -68,31 +101,33 @@ const previewImage = (pictElement, svg, widthPx, heightPx, style, rootXmlns) =>
 	const horizontalRelative = style["mso-position-horizontal-relative"] === "page";
 	const verticalRelative = style["mso-position-vertical-relative"] === "page";
 	const zIndex = parseVmlNumber(style["z-index"]);
-	return {
-		type: "drawing",
-		image: {
-			type: "image",
-			rId: "",
-			src,
-			mimeType: PREVIEW_KINDS.vmlShape.mimeType,
-			filename: PREVIEW_KINDS.vmlShape.filename,
-			size: {
-				width: pixelsToEmu(widthPx),
-				height: pixelsToEmu(heightPx)
+	const image = {
+		type: "image",
+		src,
+		mimeType: PREVIEW_KINDS.vmlShape.mimeType,
+		filename: PREVIEW_KINDS.vmlShape.filename,
+		size: {
+			width: pixelsToEmu(widthPx),
+			height: pixelsToEmu(heightPx)
+		},
+		wrap: { type: zIndex !== void 0 && zIndex >= 0 ? "inFront" : "behind" },
+		position: {
+			horizontal: {
+				relativeTo: horizontalRelative ? "page" : "character",
+				posOffset: pixelsToSafeEmu(leftPx) ?? 0
 			},
-			wrap: { type: zIndex !== void 0 && zIndex >= 0 ? "inFront" : "behind" },
-			position: {
-				horizontal: {
-					relativeTo: horizontalRelative ? "page" : "character",
-					posOffset: pixelsToSafeEmu(leftPx) ?? 0
-				},
-				vertical: {
-					relativeTo: verticalRelative ? "page" : "paragraph",
-					posOffset: pixelsToSafeEmu(topPx) ?? 0
-				}
+			vertical: {
+				relativeTo: verticalRelative ? "page" : "paragraph",
+				posOffset: pixelsToSafeEmu(topPx) ?? 0
 			}
-		},
-		rawXml: captureVerbatimXml(cloneWithXmlnsDeclarations(pictElement, rootXmlns))
+		}
+	};
+	return {
+		type: "drawing",
+		image,
+		rawXml: captureVerbatimXml(cloneWithXmlnsDeclarations(pictElement, rootXmlns)),
+		rawImageFingerprint: imageRawXmlFingerprint(image),
+		rawXmlMode: DRAWING_RAW_XML_MODES.PREVIEW_ONLY
 	};
 };
 const previewDrawing = (pictElement, preview, rootXmlns) => {
@@ -120,17 +155,41 @@ const VML_DRAWABLE_SHAPES = [
 * Whether a `w:pict` that resolved to no image must still be kept verbatim.
 *
 * VML has no serializer of its own, so an unresolved `w:pict` is only ever
-* preserved or lost. Two owners are excluded: a `v:textbox` belongs to the
-* text-box enrichment pass, which rebuilds it as an editable shape, and a
-* watermark shape belongs to watermarkParser; preserving either would emit the
-* same artwork twice.
+* preserved or lost. One owner is excluded: a `v:textbox` belongs to the
+* text-box enrichment pass, which rebuilds it as an editable shape, and
+* preserving it here as well would emit the same artwork twice.
+*
+* A watermark shape is not a second exclusion. Declining for one was a guess
+* about another module, and `watermarkParser` claims by a far narrower rule
+* than `isWatermarkShape` states: a direct `v:shape` child of a `w:pict`,
+* carrying a non-empty `v:textpath` or a `v:imagedata`, alone in its paragraph,
+* in a header. A `v:oval`, a shape nested in a `v:group`, a shape sharing its
+* paragraph with text, and every `w:pict` in a footer or in the body fall
+* outside it, so their artwork was declined here and claimed by no one. The
+* watermark owner removes its own artwork from the model instead, by emptying
+* the paragraph it detached, so this predicate need not guess who claimed what.
 */
 function shouldPreserveRawVmlPict(pictElement) {
 	if (findDeep(pictElement, "v", "textbox")) return false;
-	const shapes = VML_DRAWABLE_SHAPES.flatMap((localName) => findAllDeep(pictElement, "v", localName));
-	return shapes.length > 0 && !shapes.some((shape) => isWatermarkShape(shape));
+	return VML_DRAWABLE_SHAPES.some((localName) => findDeep(pictElement, "v", localName) !== null);
 }
 /**
+* Whether the run parser turns this `w:pict` into run content of its own.
+*
+* Exactly one owner may represent a `w:pict`: the run parser, whose drawing
+* carries the whole element as captured XML, or the text-box enrichment pass,
+* which rebuilds one `v:textbox` as an editable shape. Two owners write the
+* same artwork twice, and when the pict holds text, the saved document says it
+* twice.
+*
+* The enrichment asks this rather than re-deriving the answer from the markup:
+* its own reading (`v:imagedata` present) named only the picture path, so a
+* `v:group` claimed by the preview path was represented by both owners. The
+* result is a pure function of the element, so asking it a second time costs
+* only the work the run parser already did.
+*/
+const isVmlPictParsedByRunParser = (pictElement, rels, media) => parseVmlImageContent(pictElement, rels, media) !== null || shouldPreserveRawVmlPict(pictElement);
+/**
 * Read the relationship id off a `v:imagedata` element. Word writes `r:id`;
 * some legacy / third-party generators use `r:embed` or the office-namespace
 * `o:relid` instead, so fall back through those before the bare `id`.
@@ -157,8 +216,8 @@ function parseVmlImageContent(pictElement, rels, media, rootXmlns = {}) {
 	for (const shape of shapes) {
 		const imagedata = findChild(shape, "v", "imagedata");
 		if (!imagedata) continue;
-		const rId = readImageDataRId(imagedata);
-		if (rId === void 0 || rId.length === 0) continue;
+		const rId = relationshipIdOf(readImageDataRId(imagedata));
+		if (rId === void 0) continue;
 		if (isWatermarkShape(shape)) continue;
 		const { src, mimeType, filename } = resolveImageData(rId, rels ?? void 0, media ?? void 0);
 		const shapeStyle = parseVmlStyle(getAttribute(shape, null, "style"));
@@ -201,4 +260,4 @@ function parseVmlImageContent(pictElement, rels, media, rootXmlns = {}) {
 	return null;
 }
 //#endregion
-export { parseVmlImageContent, shouldPreserveRawVmlPict };
+export { isVmlPictParsedByRunParser, parseVmlImageContent, shouldPreserveRawVmlPict };

package/dist/docx/vmlPreview.js

@@ -1,4 +1,4 @@
-import { VML_PREVIEW_DATA_URL_PREFIX } from "./previewBudget.js";
+import { PREVIEW_KINDS } from "./previewBudget.js";
 import { findChild, findDeep, getAttribute, getChildElements, getLocalName } from "./xmlParser.js";
 //#region src/docx/vmlPreview.ts
 const MAX_VML_PREVIEW_DEPTH = 16;
@@ -84,7 +84,7 @@ const parseVmlNumber = (raw) => {
 /** Check a physical preview dimension against the retained SVG layout bound. */
 const isValidVmlPreviewDimension = (value) => value !== void 0 && value > 0 && value <= MAX_VML_PREVIEW_DIMENSION_PX;
 /** Encode a generated, already-sanitized SVG without exceeding its output cap. */
-const vmlSvgDataUrl = (svg) => svg.length <= MAX_VML_SVG_CHARACTERS ? `${VML_PREVIEW_DATA_URL_PREFIX}${encodeURIComponent(svg)}` : void 0;
+const vmlSvgDataUrl = (svg) => svg.length <= MAX_VML_SVG_CHARACTERS ? `${PREVIEW_KINDS.vmlShape.srcPrefix}${encodeURIComponent(svg)}` : void 0;
 const validCoordinate = (value) => value !== void 0 && Math.abs(value) <= MAX_VML_PREVIEW_COORDINATE;
 const validExtent = (value) => value !== void 0 && value > 0 && value <= MAX_VML_PREVIEW_COORDINATE;
 const coordinatePair = (raw) => {

package/dist/docx/wrapPolygon.d.ts

@@ -0,0 +1,30 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/wrapPolygon.d.ts
+/**
+ * The polygon a `wp:wrapTight` or `wp:wrapThrough` states: the authored one, or
+ * the rectangle when the model holds none.
+ *
+ * An authored path is written back as it stands, including one shorter than
+ * `CT_WrapPath`'s two `wp:lineTo`. folio is not the validator of its input, and
+ * replacing a short outline with the full extent of the drawing would move text
+ * that the source flows through the object — the same silent substitution this
+ * module exists to end. The rectangle is minted only where the alternative is
+ * omitting a child the type requires.
+ */
+declare const requiredWrapPolygon: (authored: document_d_exports.ImageWrapPolygon | undefined) => document_d_exports.ImageWrapPolygon;
+/**
+ * The polygon a wrap of `type` has to state, or undefined when its type
+ * declares none.
+ *
+ * The editor command that changes a wrap type calls this, so a drawing that
+ * becomes tight or through is minted its rectangle once — at the edit, as a
+ * fact of the document the author can see and undo — and every save after that
+ * writes back what the model then holds.
+ */
+declare const wrapPolygonFor: (type: document_d_exports.ImageWrap["type"], authored: document_d_exports.ImageWrapPolygon | undefined) => document_d_exports.ImageWrapPolygon | undefined;
+/** A copy, deep enough that a ProseMirror attr cannot share a point with the model. */
+declare const copiedWrapPolygon: (polygon: document_d_exports.ImageWrapPolygon | undefined) => document_d_exports.ImageWrapPolygon | undefined;
+/** `wp:wrapPolygon`, written from a polygon {@link wrapPolygonFor} has approved. */
+declare const serializeWrapPolygon: (polygon: document_d_exports.ImageWrapPolygon) => string;
+//#endregion
+export { copiedWrapPolygon, requiredWrapPolygon, serializeWrapPolygon, wrapPolygonFor };

package/dist/docx/wrapPolygon.js

@@ -0,0 +1,70 @@
+import { intAttr } from "./serializer/xmlUtils.js";
+//#region src/docx/wrapPolygon.ts
+/** `CT_WrapPath` coordinates are relative to a box of this many units. */
+const WRAP_PATH_EXTENT = 21600;
+/**
+* The whole drawing, as a closed rectangle in the path's relative space: the
+* polygon that leaves text flowing exactly as the wrap's bounding box would.
+* The only wrap outline folio invents.
+*/
+const DEFAULT_WRAP_POLYGON = {
+	edited: false,
+	start: {
+		x: 0,
+		y: 0
+	},
+	lineTo: [
+		{
+			x: 0,
+			y: WRAP_PATH_EXTENT
+		},
+		{
+			x: WRAP_PATH_EXTENT,
+			y: WRAP_PATH_EXTENT
+		},
+		{
+			x: WRAP_PATH_EXTENT,
+			y: 0
+		},
+		{
+			x: 0,
+			y: 0
+		}
+	]
+};
+/**
+* The polygon a `wp:wrapTight` or `wp:wrapThrough` states: the authored one, or
+* the rectangle when the model holds none.
+*
+* An authored path is written back as it stands, including one shorter than
+* `CT_WrapPath`'s two `wp:lineTo`. folio is not the validator of its input, and
+* replacing a short outline with the full extent of the drawing would move text
+* that the source flows through the object — the same silent substitution this
+* module exists to end. The rectangle is minted only where the alternative is
+* omitting a child the type requires.
+*/
+const requiredWrapPolygon = (authored) => authored ?? DEFAULT_WRAP_POLYGON;
+/**
+* The polygon a wrap of `type` has to state, or undefined when its type
+* declares none.
+*
+* The editor command that changes a wrap type calls this, so a drawing that
+* becomes tight or through is minted its rectangle once — at the edit, as a
+* fact of the document the author can see and undo — and every save after that
+* writes back what the model then holds.
+*/
+const wrapPolygonFor = (type, authored) => type === "tight" || type === "through" ? requiredWrapPolygon(authored) : void 0;
+/** A copy, deep enough that a ProseMirror attr cannot share a point with the model. */
+const copiedWrapPolygon = (polygon) => polygon === void 0 ? void 0 : {
+	...polygon,
+	start: { ...polygon.start },
+	lineTo: polygon.lineTo.map((point) => ({ ...point }))
+};
+/** `wp:wrapPolygon`, written from a polygon {@link wrapPolygonFor} has approved. */
+const serializeWrapPolygon = (polygon) => {
+	const edited = polygon.edited === void 0 ? "" : ` edited="${polygon.edited ? "1" : "0"}"`;
+	const lineTo = polygon.lineTo.map((point) => `<wp:lineTo x="${intAttr(point.x)}" y="${intAttr(point.y)}"/>`).join("");
+	return `<wp:wrapPolygon${edited}><wp:start x="${intAttr(polygon.start.x)}" y="${intAttr(polygon.start.y)}"/>${lineTo}</wp:wrapPolygon>`;
+};
+//#endregion
+export { copiedWrapPolygon, requiredWrapPolygon, serializeWrapPolygon, wrapPolygonFor };

package/dist/docx/xmlEncoding.d.ts

@@ -0,0 +1,5 @@
+//#region src/docx/xmlEncoding.d.ts
+/** Decode the UTF-8 and UTF-16 encodings XML processors must recognize. */
+declare const decodeXmlBytes: (bytes: Uint8Array) => string;
+//#endregion
+export { decodeXmlBytes };

package/dist/docx/xmlEncoding.js

@@ -0,0 +1,12 @@
+//#region src/docx/xmlEncoding.ts
+/** Decode the UTF-8 and UTF-16 encodings XML processors must recognize. */
+const decodeXmlBytes = (bytes) => {
+	if (bytes[0] === 255 && bytes[1] === 254) return new TextDecoder("utf-16le").decode(bytes.subarray(2));
+	if (bytes[0] === 254 && bytes[1] === 255) return new TextDecoder("utf-16be").decode(bytes.subarray(2));
+	if (bytes[0] === 60 && bytes[1] === 0 && bytes[2] === 63 && bytes[3] === 0) return new TextDecoder("utf-16le").decode(bytes);
+	if (bytes[0] === 0 && bytes[1] === 60 && bytes[2] === 0 && bytes[3] === 63) return new TextDecoder("utf-16be").decode(bytes);
+	const utf8Offset = bytes[0] === 239 && bytes[1] === 187 && bytes[2] === 191 ? 3 : 0;
+	return new TextDecoder("utf-8").decode(bytes.subarray(utf8Offset));
+};
+//#endregion
+export { decodeXmlBytes };