@stll/folio-core 0.47.7 → 0.49.0

package/dist/docx/textBoxParser.d.ts

@@ -2,6 +2,7 @@ import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
 import { ParseContext } from "./parseContext.js";
 import { XmlElement } from "./xmlParser.js";
+import { PreviewLedger } from "./previewBudget.js";
 import { StyleMap } from "./styleParser.js";
 //#region src/docx/textBoxParser.d.ts
 /**
@@ -15,16 +16,20 @@ declare function extractTextBoxContentElements(txbxContent: XmlElement | null):
 /**
  * Type for the paragraph parser function to avoid circular imports
  */
-type ParagraphParserFn = (node: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, numbering: NumberingMap | null, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null) => document_d_exports.Paragraph;
+type ParagraphParserFn = (node: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, numbering: NumberingMap | null, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, options: {
+  previews: PreviewLedger;
+}) => document_d_exports.Paragraph;
 /**
  * Type for the table parser function to avoid circular imports
  */
-type TableParserFn = (node: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, numbering: NumberingMap | null, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null) => document_d_exports.Table | undefined;
+type TableParserFn = (node: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, numbering: NumberingMap | null, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, options: {
+  previews: PreviewLedger;
+}) => document_d_exports.Table | undefined;
 /**
  * Parse text box content with provided parser functions
  * This avoids circular dependencies by accepting parser functions as parameters
  */
-declare function parseTextBoxContent(txbxContent: XmlElement | null, parseParagraph: ParagraphParserFn, parseTable: TableParserFn | null, styles: StyleMap | null, theme: document_d_exports.Theme | null, numbering: NumberingMap | null, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null): (document_d_exports.Paragraph | document_d_exports.Table)[];
+declare function parseTextBoxContent(txbxContent: XmlElement | null, parseParagraph: ParagraphParserFn, parseTable: TableParserFn | null, styles: StyleMap | null, theme: document_d_exports.Theme | null, numbering: NumberingMap | null, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, previews: PreviewLedger): (document_d_exports.Paragraph | document_d_exports.Table)[];
 /**
  * Check if a drawing element contains a text box
  * Text boxes are shapes with wps:txbx content
@@ -114,8 +119,16 @@ declare function resolveTextBoxOutlineColor(textBox: document_d_exports.TextBox)
  * Get outline width in pixels
  */
 declare function getTextBoxOutlineWidthPx(textBox: document_d_exports.TextBox): number;
+/** A text-box `w:drawing`, with the `mc:AlternateContent` branch it sits in, if any. */
+type TextBoxDrawing = {
+  drawing: XmlElement;
+  alternateContent?: {
+    element: XmlElement;
+    branch: XmlElement;
+  };
+};
 type TextBoxRunScan = {
-  textBoxDrawings: XmlElement[];
+  textBoxDrawings: TextBoxDrawing[];
   vmlTextBoxes: XmlElement[];
   hasNonTextBoxContent: boolean;
 };
@@ -138,4 +151,4 @@ type ScanRunForTextBoxDrawingsOptions = {
 };
 declare const scanRunForTextBoxDrawings: ({ xmlRun, claimedByRunParser }: ScanRunForTextBoxDrawingsOptions) => TextBoxRunScan;
 //#endregion
-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 };
+export { ParagraphParserFn, ScanRunForTextBoxDrawingsOptions, TableParserFn, TextBoxDrawing, 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

@@ -80,7 +80,7 @@ function extractTextBoxContentElements(txbxContent) {
 * Parse text box content with provided parser functions
 * This avoids circular dependencies by accepting parser functions as parameters
 */
-function parseTextBoxContent(txbxContent, parseParagraph, parseTable, styles, theme, numbering, rels, media) {
+function parseTextBoxContent(txbxContent, parseParagraph, parseTable, styles, theme, numbering, rels, media, previews) {
 	if (!txbxContent) return [];
 	const blocks = [];
 	const children = getChildElements(txbxContent);
@@ -89,10 +89,10 @@ function parseTextBoxContent(txbxContent, parseParagraph, parseTable, styles, th
 		const colonIdx = name.indexOf(":");
 		const localName = colonIdx !== -1 ? name.slice(colonIdx + 1) : name;
 		if (localName === "p") {
-			const paragraph = parseParagraph(child, styles, theme, numbering, rels, media);
+			const paragraph = parseParagraph(child, styles, theme, numbering, rels, media, { previews });
 			blocks.push(paragraph);
 		} else if (localName === "tbl" && parseTable) {
-			const table = parseTable(child, styles, theme, numbering, rels, media);
+			const table = parseTable(child, styles, theme, numbering, rels, media, { previews });
 			if (table) blocks.push(table);
 		}
 	}
@@ -328,9 +328,12 @@ const scanRunForTextBoxDrawings = ({ xmlRun, claimedByRunParser }) => {
 	const textBoxDrawings = [];
 	const vmlTextBoxes = [];
 	let hasNonTextBoxContent = false;
-	const visitDrawing = (drawingEl) => {
+	const visitDrawing = (drawingEl, alternateContent) => {
 		if (isTextBoxDrawing(drawingEl)) {
-			textBoxDrawings.push(drawingEl);
+			textBoxDrawings.push({
+				drawing: drawingEl,
+				...alternateContent === void 0 ? {} : { alternateContent }
+			});
 			return;
 		}
 		hasNonTextBoxContent = true;
@@ -355,7 +358,10 @@ const scanRunForTextBoxDrawings = ({ xmlRun, claimedByRunParser }) => {
 				if (!branch) return false;
 				let found = false;
 				for (const innerEl of getChildElements(branch)) if (getLocalName(innerEl.name ?? "") === "drawing") {
-					visitDrawing(innerEl);
+					visitDrawing(innerEl, {
+						element: el,
+						branch
+					});
 					found = true;
 				}
 				return found;

package/dist/docx/verbatimCapture.d.ts

@@ -18,14 +18,16 @@ type SanitizeCapturedXmlOptions = {
 /** Validate a complete XML part immediately before package output. */
 declare const isSafeCapturedXmlDocument: (xml: string) => boolean;
 /**
- * Re-parse and serialize one captured element before replaying it.
+ * {@link sanitizeCapturedXmlElement} over fixed options, memoized by source
+ * string.
  *
- * The parser deliberately ignores declarations, processing instructions,
- * comments, and document types. Returning the caller's source string after a
- * successful parse would therefore replay tokens that were never validated.
- * This function returns only the parsed root serialized through the capture
- * owner, and rejects siblings, unexpected roots, and namespace shadowing.
+ * Sanitizing is a pure function of the string and the options, and a capture
+ * is fixed when it is parsed, so every save after the first would otherwise
+ * re-parse and re-validate the same markup. The key is the string rather than
+ * the object holding it: editor round-trips copy capture holders, but the
+ * string they carry is the one the parser produced. `transform` and `validate`
+ * must therefore depend on nothing but the element they are given.
  */
-declare const sanitizeCapturedXmlElement: (xml: string | undefined, options: SanitizeCapturedXmlOptions) => string | null;
+declare const createCapturedXmlSanitizer: (options: SanitizeCapturedXmlOptions) => ((xml: string | undefined) => string | null);
 //#endregion
-export { UntranslatableStrictNamespaceError, captureVerbatimXml, isSafeCapturedXmlDocument, sanitizeCapturedXmlElement };
+export { UntranslatableStrictNamespaceError, captureVerbatimXml, createCapturedXmlSanitizer, isSafeCapturedXmlDocument };

package/dist/docx/verbatimCapture.js

@@ -313,12 +313,55 @@ const captureAllowedElement = (element, { allowedLocalNames, allowedNamespaceUri
 * owner, and rejects siblings, unexpected roots, and namespace shadowing.
 */
 const sanitizeCapturedXmlElement = (xml, options) => {
-	if (xml === void 0) return null;
 	const trimmed = xml.trim();
 	if (!trimmed) return null;
 	if (!withinXmlResourceLimits(xml) || getDocxXmlSafetyIssue(xml) !== null) return null;
 	const root = parsedReplayEnvelope(trimmed, options.inheritedNamespaceScope ?? OOXML_NAMESPACE_SCOPE);
 	return root ? captureAllowedElement(root, options) : null;
 };
+/**
+* Characters of source and sanitized XML one sanitizer retains. A paragraph
+* capture is a few hundred characters, so this holds every distinct capture of
+* a large document while bounding what outlives the documents it came from.
+*/
+const CAPTURED_XML_SANITIZER_CACHE_CHARACTERS = 2 * 1024 * 1024;
+/**
+* What one cache entry costs beyond its strings, in characters. Charging it
+* keeps many short keys from holding far more memory than their text, and
+* caps the entry count at the budget divided by this.
+*/
+const CAPTURED_XML_SANITIZER_ENTRY_OVERHEAD_CHARACTERS = 64;
+const capturedXmlCacheCharacters = (xml, sanitized) => CAPTURED_XML_SANITIZER_ENTRY_OVERHEAD_CHARACTERS + xml.length + (sanitized?.length ?? 0);
+/**
+* {@link sanitizeCapturedXmlElement} over fixed options, memoized by source
+* string.
+*
+* Sanitizing is a pure function of the string and the options, and a capture
+* is fixed when it is parsed, so every save after the first would otherwise
+* re-parse and re-validate the same markup. The key is the string rather than
+* the object holding it: editor round-trips copy capture holders, but the
+* string they carry is the one the parser produced. `transform` and `validate`
+* must therefore depend on nothing but the element they are given.
+*/
+const createCapturedXmlSanitizer = (options) => {
+	const cache = /* @__PURE__ */ new Map();
+	let cachedCharacters = 0;
+	return (xml) => {
+		if (xml === void 0) return null;
+		const cached = cache.get(xml);
+		if (cached !== void 0) return cached;
+		const sanitized = sanitizeCapturedXmlElement(xml, options);
+		const characters = capturedXmlCacheCharacters(xml, sanitized);
+		if (characters > CAPTURED_XML_SANITIZER_CACHE_CHARACTERS) return sanitized;
+		for (const [oldestXml, oldestSanitized] of cache) {
+			if (cachedCharacters + characters <= CAPTURED_XML_SANITIZER_CACHE_CHARACTERS) break;
+			cache.delete(oldestXml);
+			cachedCharacters -= capturedXmlCacheCharacters(oldestXml, oldestSanitized);
+		}
+		cache.set(xml, sanitized);
+		cachedCharacters += characters;
+		return sanitized;
+	};
+};
 //#endregion
-export { UntranslatableStrictNamespaceError, captureVerbatimXml, isSafeCapturedXmlDocument, sanitizeCapturedXmlElement };
+export { UntranslatableStrictNamespaceError, captureVerbatimXml, createCapturedXmlSanitizer, isSafeCapturedXmlDocument };

package/dist/docx/vmlImageParser.d.ts

@@ -1,5 +1,6 @@
 import { document_d_exports } from "../types/document.js";
 import { XmlElement } from "./xmlParser.js";
+import { PreviewLedger } from "./previewBudget.js";
 //#region src/docx/vmlImageParser.d.ts
 /**
  * Whether a `w:pict` that resolved to no image must still be kept verbatim.
@@ -20,6 +21,16 @@ import { XmlElement } from "./xmlParser.js";
  * the paragraph it detached, so this predicate need not guess who claimed what.
  */
 declare function shouldPreserveRawVmlPict(pictElement: XmlElement): 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).
+ *
+ * `rootXmlns` carries the source document/header namespace declarations. They
+ * are injected onto the captured VML so the raw replay stays self-contained
+ * when the producer bound WordprocessingML / relationship / VML namespaces to
+ * non-canonical prefixes the serializer's root does not declare.
+ */
+declare function parseVmlImageContent(pictElement: XmlElement, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, previews: PreviewLedger, rootXmlns?: Record<string, string>): document_d_exports.DrawingContent | null;
 /**
  * Whether the run parser turns this `w:pict` into run content of its own.
  *
@@ -31,20 +42,11 @@ declare function shouldPreserveRawVmlPict(pictElement: XmlElement): boolean;
  *
  * 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.
+ * `v:group` claimed by the preview path was represented by both owners. It
+ * reads the two decisions {@link parseVmlImageContent} makes without building
+ * either result: a preview built here would be registered against the package
+ * budget for a drawing the model never holds.
  */
 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).
- *
- * `rootXmlns` carries the source document/header namespace declarations. They
- * are injected onto the captured VML so the raw replay stays self-contained
- * when the producer bound WordprocessingML / relationship / VML namespaces to
- * non-canonical prefixes the serializer's root does not declare.
- */
-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 { isVmlPictParsedByRunParser, parseVmlImageContent, shouldPreserveRawVmlPict };

package/dist/docx/vmlImageParser.js

@@ -2,9 +2,8 @@ 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 { fitsVmlSvgCap, isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx } 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";
@@ -93,19 +92,44 @@ const vmlImageLayout = (style) => {
 		}
 	};
 };
-const previewImage = (pictElement, svg, widthPx, heightPx, style, rootXmlns) => {
-	const src = vmlSvgDataUrl(svg);
-	if (!src) return null;
+/** A render the model may retain: one that painted, within the SVG output cap. */
+const retainableRender = (preview) => {
+	switch (preview.type) {
+		case "rendered": return fitsVmlSvgCap(preview.svg) ? preview : null;
+		case "empty":
+		case "invalid": return null;
+		default: return preview;
+	}
+};
+/**
+* The render folio draws a `w:pict` as when it holds no picture: its first
+* group or standalone shape that renders within the cap, or null.
+*
+* Deciding this builds nothing, so the text-box pass can ask whether the run
+* parser claims a pict without making a second preview of it.
+*/
+const vmlPictPreview = (pictElement) => {
+	for (const child of getChildElements(pictElement)) {
+		const localName = getLocalName(child.name ?? "");
+		if (localName === "group") {
+			const preview = retainableRender(renderVmlGroupPreview(child));
+			if (preview) return preview;
+			continue;
+		}
+		if (localName === "rect" || localName === "roundrect" || localName === "oval") {
+			const preview = retainableRender(renderStandaloneVmlPreview(child));
+			if (preview) return preview;
+		}
+	}
+	return null;
+};
+const previewDrawing = (pictElement, { svg, widthPx, heightPx, style }, rootXmlns, previews) => {
 	const leftPx = vmlCssLengthToPx(style["margin-left"] ?? style["left"]) ?? 0;
 	const topPx = vmlCssLengthToPx(style["margin-top"] ?? style["top"]) ?? 0;
 	const horizontalRelative = style["mso-position-horizontal-relative"] === "page";
 	const verticalRelative = style["mso-position-vertical-relative"] === "page";
 	const zIndex = parseVmlNumber(style["z-index"]);
-	const image = {
-		type: "image",
-		src,
-		mimeType: PREVIEW_KINDS.vmlShape.mimeType,
-		filename: PREVIEW_KINDS.vmlShape.filename,
+	const image = previews.svgImage("vmlShape", svg, {
 		size: {
 			width: pixelsToEmu(widthPx),
 			height: pixelsToEmu(heightPx)
@@ -121,7 +145,7 @@ const previewImage = (pictElement, svg, widthPx, heightPx, style, rootXmlns) =>
 				posOffset: pixelsToSafeEmu(topPx) ?? 0
 			}
 		}
-	};
+	});
 	return {
 		type: "drawing",
 		image,
@@ -130,14 +154,6 @@ const previewImage = (pictElement, svg, widthPx, heightPx, style, rootXmlns) =>
 		rawXmlMode: DRAWING_RAW_XML_MODES.PREVIEW_ONLY
 	};
 };
-const previewDrawing = (pictElement, preview, rootXmlns) => {
-	switch (preview.type) {
-		case "rendered": return previewImage(pictElement, preview.svg, preview.widthPx, preview.heightPx, preview.style, rootXmlns);
-		case "empty":
-		case "invalid": return null;
-		default: return preview;
-	}
-};
 /** VML elements that paint something, i.e. content a save must not lose. */
 const VML_DRAWABLE_SHAPES = [
 	"shape",
@@ -174,22 +190,6 @@ function shouldPreserveRawVmlPict(pictElement) {
 	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`.
@@ -198,15 +198,10 @@ function readImageDataRId(imagedata) {
 	return getAttribute(imagedata, "r", "id") ?? getAttribute(imagedata, "r", "embed") ?? getAttribute(imagedata, "o", "relid") ?? getAttribute(imagedata, null, "id") ?? void 0;
 }
 /**
-* 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).
-*
-* `rootXmlns` carries the source document/header namespace declarations. They
-* are injected onto the captured VML so the raw replay stays self-contained
-* when the producer bound WordprocessingML / relationship / VML namespaces to
-* non-canonical prefixes the serializer's root does not declare.
+* The picture a `w:pict` carries: the first shape whose `<v:imagedata>`
+* names a relationship, skipping watermarks, or null.
 */
-function parseVmlImageContent(pictElement, rels, media, rootXmlns = {}) {
+const vmlPictPicture = (pictElement, rels, media) => {
 	const shapes = [
 		...findAllDeep(pictElement, "v", "shape"),
 		...findAllDeep(pictElement, "v", "rect"),
@@ -239,25 +234,45 @@ function parseVmlImageContent(pictElement, rels, media, rootXmlns = {}) {
 		if (filename) image.filename = filename;
 		const title = getAttribute(imagedata, "o", "title");
 		if (title) image.title = title;
-		return {
-			type: "drawing",
-			image,
-			rawXml: captureVerbatimXml(cloneWithXmlnsDeclarations(pictElement, rootXmlns))
-		};
-	}
-	for (const child of getChildElements(pictElement)) {
-		const localName = getLocalName(child.name ?? "");
-		if (localName === "group") {
-			const preview = previewDrawing(pictElement, renderVmlGroupPreview(child), rootXmlns);
-			if (preview) return preview;
-			continue;
-		}
-		if (localName === "rect" || localName === "roundrect" || localName === "oval") {
-			const preview = previewDrawing(pictElement, renderStandaloneVmlPreview(child), rootXmlns);
-			if (preview) return preview;
-		}
+		return image;
 	}
 	return null;
+};
+/**
+* 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).
+*
+* `rootXmlns` carries the source document/header namespace declarations. They
+* are injected onto the captured VML so the raw replay stays self-contained
+* when the producer bound WordprocessingML / relationship / VML namespaces to
+* non-canonical prefixes the serializer's root does not declare.
+*/
+function parseVmlImageContent(pictElement, rels, media, previews, rootXmlns = {}) {
+	const image = vmlPictPicture(pictElement, rels, media);
+	if (image) return {
+		type: "drawing",
+		image,
+		rawXml: captureVerbatimXml(cloneWithXmlnsDeclarations(pictElement, rootXmlns))
+	};
+	const preview = vmlPictPreview(pictElement);
+	return preview ? previewDrawing(pictElement, preview, rootXmlns, previews) : 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. It
+* reads the two decisions {@link parseVmlImageContent} makes without building
+* either result: a preview built here would be registered against the package
+* budget for a drawing the model never holds.
+*/
+const isVmlPictParsedByRunParser = (pictElement, rels, media) => vmlPictPicture(pictElement, rels, media) !== null || vmlPictPreview(pictElement) !== null || shouldPreserveRawVmlPict(pictElement);
 //#endregion
 export { isVmlPictParsedByRunParser, parseVmlImageContent, shouldPreserveRawVmlPict };

package/dist/docx/vmlPreview.d.ts

@@ -19,11 +19,11 @@ declare const parseVmlStyle: (style: string | null) => Record<string, string>;
 declare const parseVmlNumber: (raw: string | null | undefined) => number | undefined;
 /** Check a physical preview dimension against the retained SVG layout bound. */
 declare const isValidVmlPreviewDimension: (value: number | undefined) => value is number;
-/** Encode a generated, already-sanitized SVG without exceeding its output cap. */
-declare const vmlSvgDataUrl: (svg: string) => string | undefined;
+/** Whether a generated, already-sanitized SVG is within the output cap a preview may retain. */
+declare const fitsVmlSvgCap: (svg: string) => boolean;
 /** Render a bounded standalone VML rectangle or oval preview. */
 declare const renderStandaloneVmlPreview: (shape: XmlElement) => VmlPreviewResult;
 /** Render a VML group through bounded, non-clipping local-coordinate transforms. */
 declare const renderVmlGroupPreview: (group: XmlElement) => VmlPreviewResult;
 //#endregion
-export { VmlPreviewResult, isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx, vmlSvgDataUrl };
+export { VmlPreviewResult, fitsVmlSvgCap, isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx };

package/dist/docx/vmlPreview.js

@@ -1,4 +1,3 @@
-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;
@@ -83,8 +82,8 @@ 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 ? `${PREVIEW_KINDS.vmlShape.srcPrefix}${encodeURIComponent(svg)}` : void 0;
+/** Whether a generated, already-sanitized SVG is within the output cap a preview may retain. */
+const fitsVmlSvgCap = (svg) => svg.length <= MAX_VML_SVG_CHARACTERS;
 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) => {
@@ -504,4 +503,4 @@ const renderVmlGroupPreview = (group) => {
 	};
 };
 //#endregion
-export { isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx, vmlSvgDataUrl };
+export { fitsVmlSvgCap, isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx };

package/dist/docx/xmlNamespaceContext.d.ts

@@ -0,0 +1,9 @@
+import { XmlElement, XmlNamespaceScope } from "./xmlParser.js";
+//#region src/docx/xmlNamespaceContext.d.ts
+declare const EMPTY_NAMESPACE_SCOPE: XmlNamespaceScope;
+declare const XML_NAMESPACE_URI = "http://www.w3.org/XML/1998/namespace";
+declare const resolveNamespaceUri: (scope: XmlNamespaceScope | undefined, prefix: string) => string | undefined;
+/** Attach the element's resolved namespace metadata from its in-scope declarations. */
+declare const attachXmlNamespaceContext: (element: XmlElement, inheritedNamespaceScope?: XmlNamespaceScope) => XmlNamespaceScope;
+//#endregion
+export { EMPTY_NAMESPACE_SCOPE, XML_NAMESPACE_URI, attachXmlNamespaceContext, resolveNamespaceUri };

package/dist/docx/xmlNamespaceContext.js

@@ -0,0 +1,54 @@
+//#region src/docx/xmlNamespaceContext.ts
+const EMPTY_NAMESPACE_SCOPE = { bindings: /* @__PURE__ */ new Map() };
+/**
+* Reserved by the XML Namespaces recommendation (§3): every document binds
+* this prefix to this URI whether or not it declares `xmlns:xml`, and no
+* document may bind it to anything else. A source that omits the declaration
+* — the overwhelming majority — must still resolve `xml:space`, `xml:lang`
+* and `xml:id` to it, or a reader mistakes the attribute for an unprefixed
+* one and a save drops its prefix.
+*/
+const XML_RESERVED_PREFIX = "xml";
+const XML_NAMESPACE_URI = "http://www.w3.org/XML/1998/namespace";
+const resolveNamespaceUri = (scope, prefix) => {
+	let current = scope;
+	while (current) {
+		const value = current.bindings.get(prefix);
+		if (value !== void 0) return value;
+		current = current.parent;
+	}
+	return prefix === XML_RESERVED_PREFIX ? XML_NAMESPACE_URI : void 0;
+};
+/** Attach the element's resolved namespace metadata from its in-scope declarations. */
+const attachXmlNamespaceContext = (element, inheritedNamespaceScope = EMPTY_NAMESPACE_SCOPE) => {
+	let localBindings = null;
+	if (element.attributes) for (const [attribute, value] of Object.entries(element.attributes)) {
+		if (typeof value !== "string" || attribute !== "xmlns" && !attribute.startsWith("xmlns:")) continue;
+		localBindings ??= /* @__PURE__ */ new Map();
+		const prefix = attribute === "xmlns" ? "" : attribute.slice(6);
+		localBindings.set(prefix, value);
+	}
+	const namespaceScope = localBindings === null ? inheritedNamespaceScope : {
+		bindings: localBindings,
+		parent: inheritedNamespaceScope
+	};
+	Object.defineProperty(element, "namespaceScope", {
+		configurable: false,
+		enumerable: false,
+		value: namespaceScope,
+		writable: false
+	});
+	const name = element.name ?? "";
+	const colonIndex = name.indexOf(":");
+	const prefix = colonIndex === -1 ? "" : name.slice(0, colonIndex);
+	const namespaceUri = resolveNamespaceUri(namespaceScope, prefix);
+	if (namespaceUri !== void 0) Object.defineProperty(element, "namespaceUri", {
+		configurable: false,
+		enumerable: false,
+		value: namespaceUri,
+		writable: false
+	});
+	return namespaceScope;
+};
+//#endregion
+export { EMPTY_NAMESPACE_SCOPE, XML_NAMESPACE_URI, attachXmlNamespaceContext, resolveNamespaceUri };

package/dist/docx/xmlParser.d.ts

@@ -28,8 +28,6 @@ type XmlNamespaceScope = {
   bindings: ReadonlyMap<string, string>;
   parent?: XmlNamespaceScope;
 };
-/** Attach the element's resolved namespace metadata from its in-scope declarations. */
-declare const attachXmlNamespaceContext: (element: XmlElement, inheritedNamespaceScope?: XmlNamespaceScope) => XmlNamespaceScope;
 /**
  * Common OOXML namespace URIs — re-exported from @stll/docx-utils.
  */
@@ -70,6 +68,11 @@ declare const NAMESPACES: {
  */
 declare const OOXML_NAMESPACE_SCOPE: XmlNamespaceScope;
 declare function parseXml(xml: string, inheritedNamespaceScope?: XmlNamespaceScope): XmlElement;
+/**
+ * The general-purpose reader {@link parseXml} falls back to, and the reference
+ * the streaming reader's equivalence tests compare against.
+ */
+declare function parseXmlWithFastXmlParser(xml: string, inheritedNamespaceScope?: XmlNamespaceScope): XmlElement;
 /**
  * Serialize an XmlElement back to an XML string.
  *
@@ -405,4 +408,4 @@ declare function cloneWithXmlnsDeclarations(element: XmlElement, xmlnsDecls: Rec
  */
 declare function cloneElement(element: XmlElement, overrides: Partial<XmlElement>): XmlElement;
 //#endregion
-export { NAMESPACES, OFFICE_RELATIONSHIP_NAMESPACE_URIS, OOXML_NAMESPACE_SCOPE, WORDPROCESSINGML_NAMESPACE_URIS, XmlAttributeMatch, XmlElement, XmlNamespaceScope, attachXmlNamespaceContext, cloneElement, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findAttributeByNamespaceUri, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findChildrenByNamespaceUri, findDeep, findWordprocessingChild, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffAttribute, parseOnOffChild, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument, resolveAttributeNamespaceUri, selectAlternateContentBranch };
+export { NAMESPACES, OFFICE_RELATIONSHIP_NAMESPACE_URIS, OOXML_NAMESPACE_SCOPE, WORDPROCESSINGML_NAMESPACE_URIS, XmlAttributeMatch, XmlElement, XmlNamespaceScope, cloneElement, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findAttributeByNamespaceUri, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findChildrenByNamespaceUri, findDeep, findWordprocessingChild, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffAttribute, parseOnOffChild, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument, parseXmlWithFastXmlParser, resolveAttributeNamespaceUri, selectAlternateContentBranch };

package/dist/docx/xmlParser.js

@@ -1,5 +1,7 @@
+import { parseStreamingXml } from "./streamingXmlParser.js";
 import { NUMBERS_PER_PERCENT, percentageSpelling, transitionalSlotEncoding } from "./transitionalSpelling.js";
 import { universalMeasureAs } from "./universalMeasure.js";
+import { EMPTY_NAMESPACE_SCOPE, attachXmlNamespaceContext, resolveNamespaceUri } from "./xmlNamespaceContext.js";
 import { escapeXmlAttribute, escapeXmlText } from "@stll/docx-core";
 import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 import { XMLParser } from "fast-xml-parser";
@@ -49,46 +51,6 @@ const fxpParserWithStopNodes = new XMLParser(fxpParserOptionsWithStopNodes);
 const TEXT_KEY = "#text";
 /** Attribute group key used by fast-xml-parser in preserveOrder mode. */
 const ATTR_KEY = ":@";
-const EMPTY_NAMESPACE_SCOPE = { bindings: /* @__PURE__ */ new Map() };
-const resolveNamespaceUri = (scope, prefix) => {
-	let current = scope;
-	while (current) {
-		const value = current.bindings.get(prefix);
-		if (value !== void 0) return value;
-		current = current.parent;
-	}
-};
-/** Attach the element's resolved namespace metadata from its in-scope declarations. */
-const attachXmlNamespaceContext = (element, inheritedNamespaceScope = EMPTY_NAMESPACE_SCOPE) => {
-	let localBindings = null;
-	if (element.attributes) for (const [attribute, value] of Object.entries(element.attributes)) {
-		if (typeof value !== "string" || attribute !== "xmlns" && !attribute.startsWith("xmlns:")) continue;
-		localBindings ??= /* @__PURE__ */ new Map();
-		const prefix = attribute === "xmlns" ? "" : attribute.slice(6);
-		localBindings.set(prefix, value);
-	}
-	const namespaceScope = localBindings === null ? inheritedNamespaceScope : {
-		bindings: localBindings,
-		parent: inheritedNamespaceScope
-	};
-	Object.defineProperty(element, "namespaceScope", {
-		configurable: false,
-		enumerable: false,
-		value: namespaceScope,
-		writable: false
-	});
-	const name = element.name ?? "";
-	const colonIndex = name.indexOf(":");
-	const prefix = colonIndex === -1 ? "" : name.slice(0, colonIndex);
-	const namespaceUri = resolveNamespaceUri(namespaceScope, prefix);
-	if (namespaceUri !== void 0) Object.defineProperty(element, "namespaceUri", {
-		configurable: false,
-		enumerable: false,
-		value: namespaceUri,
-		writable: false
-	});
-	return namespaceScope;
-};
 /**
 * Convert a fast-xml-parser preserveOrder node into an XmlElement.
 *
@@ -150,6 +112,14 @@ const NAMESPACES = OOXML_NS;
 */
 const OOXML_NAMESPACE_SCOPE = { bindings: new Map(Object.entries(OOXML_NS)) };
 function parseXml(xml, inheritedNamespaceScope = EMPTY_NAMESPACE_SCOPE) {
+	const streamed = parseStreamingXml(xml, inheritedNamespaceScope);
+	return streamed.status === "parsed" ? streamed.value : parseXmlWithFastXmlParser(xml, inheritedNamespaceScope);
+}
+/**
+* The general-purpose reader {@link parseXml} falls back to, and the reference
+* the streaming reader's equivalence tests compare against.
+*/
+function parseXmlWithFastXmlParser(xml, inheritedNamespaceScope = EMPTY_NAMESPACE_SCOPE) {
 	return fxpToRootElement((xml.includes("binData") ? fxpParserWithStopNodes : fxpParser).parse(xml), inheritedNamespaceScope);
 }
 /**
@@ -884,4 +854,4 @@ function cloneElement(element, overrides) {
 	return clone;
 }
 //#endregion
-export { NAMESPACES, OFFICE_RELATIONSHIP_NAMESPACE_URIS, OOXML_NAMESPACE_SCOPE, WORDPROCESSINGML_NAMESPACE_URIS, attachXmlNamespaceContext, cloneElement, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findAttributeByNamespaceUri, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findChildrenByNamespaceUri, findDeep, findWordprocessingChild, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffAttribute, parseOnOffChild, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument, resolveAttributeNamespaceUri, selectAlternateContentBranch };
+export { NAMESPACES, OFFICE_RELATIONSHIP_NAMESPACE_URIS, OOXML_NAMESPACE_SCOPE, WORDPROCESSINGML_NAMESPACE_URIS, cloneElement, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findAttributeByNamespaceUri, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findChildrenByNamespaceUri, findDeep, findWordprocessingChild, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffAttribute, parseOnOffChild, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument, parseXmlWithFastXmlParser, resolveAttributeNamespaceUri, selectAlternateContentBranch };