@stll/folio-core 0.44.0 → 0.46.0

package/dist/docx/textBoxParser.js

@@ -1,6 +1,7 @@
 import { emuToPixels } from "../utils/units.js";
 import { parseAnchorPosition, parseAnchorWrap, parseFill, parseOutline, resolveColorValueToHex } from "./drawingUtils.js";
-import { findByFullName, findChildByLocalName, findChildByNamespaceUri, findChildrenByLocalName, findChildrenByNamespaceUri, getAttribute, getChildElements, parseNumericAttribute, parseOnOffAttribute } from "./xmlParser.js";
+import { parseNonVisualDrawingNames } from "./nonVisualDrawingProps.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"]);
@@ -148,13 +149,15 @@ function parseTextBox(drawingEl) {
 	};
 	const docPr = findByFullName(container, "wp:docPr");
 	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 bodyProps = parseBodyProperties(bodyPr ?? null);
 	const textBox = {
 		type: "textBox",
 		size,
-		content: []
+		content: [],
+		...names
 	};
 	if (id) textBox.id = id;
 	if (fill) textBox.fill = fill;
@@ -193,13 +196,15 @@ function parseTextBoxFromShape(wsp, size, position, wrap) {
 	const bodyPr = findChildByNamespaceUri(wsp, WORDPROCESSING_SHAPE_NAMESPACE_URIS, "bodyPr");
 	const cNvPr = wspChildren.find((el) => el.name === "wps:cNvPr");
 	const id = cNvPr ? getAttribute(cNvPr, null, "id") ?? void 0 : void 0;
+	const names = parseNonVisualDrawingNames(cNvPr);
 	const fill = parseFill(spPr ?? null);
 	const outline = parseOutline(spPr ?? null);
 	const bodyProps = parseBodyProperties(bodyPr ?? null);
 	const textBox = {
 		type: "textBox",
 		size,
-		content: []
+		content: [],
+		...names
 	};
 	if (id) textBox.id = id;
 	if (fill) textBox.fill = fill;
@@ -285,6 +290,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 === "preservedBlock") return "";
 	return block.content.map(getTextBoxBlockText).join("\n");
 };
 /**
@@ -308,5 +314,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/unzip.d.ts

@@ -6,10 +6,33 @@ declare class DocxSecurityError extends Error {
 type DocxUnzipLimits = {
   maxInputBytes: number;
   maxFiles: number;
+  /**
+   * Inflated bytes allowed in one XML part.
+   *
+   * A byte ceiling bounds the markup, not what parsing it allocates: a parsed
+   * tree costs 3x to 15x the part's bytes, and the cheapest element to write
+   * is the most expensive per byte. Use `maxXmlElementsPerPart` and the
+   * package bounds to cap memory; this one caps text-dominated parts, where
+   * bytes and cost do track each other.
+   */
   maxXmlBytes: number;
   maxMediaBytes: number;
   maxFontBytes: number;
+  /**
+   * Inflated bytes allowed across every entry in the package.
+   *
+   * Same caveat as `maxXmlBytes`: this is a ceiling on what passes through
+   * memory as bytes, not on what the parsed structure retains.
+   */
   maxTotalUncompressedBytes: number;
+  /** Elements allowed in one XML part, counted before any tree is built. */
+  maxXmlElementsPerPart: number;
+  /** Attributes allowed in one XML part, counted before any tree is built. */
+  maxXmlAttributesPerPart: number;
+  /** Elements allowed across every XML part in the package. */
+  maxXmlElementsPerPackage: number;
+  /** Attributes allowed across every XML part in the package. */
+  maxXmlAttributesPerPackage: number;
   allowedMediaMimeTypes: ReadonlySet<string>;
 };
 type DocxUnzipOptions = Partial<Omit<DocxUnzipLimits, "allowedMediaMimeTypes">> & {

package/dist/docx/unzip.js

@@ -1,6 +1,8 @@
+import { bytesToDataUrl } from "../utils/base64.js";
 import { DOCX_CONTAINER_TYPES, detectDocxContainerType } from "./encryption/containerFormat.js";
 import { openDocxBuffer } from "./encryption/openEncryptedDocx.js";
-import { FOLIO_XML_RESOURCE_LIMITS, assertXmlResourceLimits } from "./xmlResourceLimits.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
 /**
@@ -58,8 +60,21 @@ const DEFAULT_UNZIP_LIMITS = {
 	maxMediaBytes: 25 * MEBIBYTE,
 	maxFontBytes: 10 * MEBIBYTE,
 	maxTotalUncompressedBytes: 250 * MEBIBYTE,
+	maxXmlElementsPerPart: FOLIO_XML_RESOURCE_LIMITS.maxElementsPerPart,
+	maxXmlAttributesPerPart: FOLIO_XML_RESOURCE_LIMITS.maxAttributesPerPart,
+	maxXmlElementsPerPackage: FOLIO_XML_RESOURCE_LIMITS.maxElementsPerPackage,
+	maxXmlAttributesPerPackage: FOLIO_XML_RESOURCE_LIMITS.maxAttributesPerPackage,
 	allowedMediaMimeTypes: DEFAULT_ALLOWED_MEDIA_MIME_TYPES
 };
+/** The XML bounds an unzip enforces, in the shape the preflight takes. */
+const xmlResourceLimitsFor = (limits) => ({
+	maxBytes: limits.maxXmlBytes,
+	maxDepth: FOLIO_XML_RESOURCE_LIMITS.maxDepth,
+	maxElementsPerPart: limits.maxXmlElementsPerPart,
+	maxAttributesPerPart: limits.maxXmlAttributesPerPart,
+	maxElementsPerPackage: limits.maxXmlElementsPerPackage,
+	maxAttributesPerPackage: limits.maxXmlAttributesPerPackage
+});
 const PARSED_XML_PARTS = /* @__PURE__ */ new Set([
 	"[content_types].xml",
 	"_rels/.rels",
@@ -147,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/")) {
@@ -188,10 +203,11 @@ async function unzipDocx(buffer, options = {}) {
 			}));
 		}
 	}
+	const xmlBudget = createXmlPackageBudget();
 	for (const extracted of await Promise.all(extractionTasks.map((extract) => extract()))) {
 		if (!extracted) continue;
 		if (extracted.type === "xml") {
-			assignXmlContent(content, extracted, limits);
+			assignXmlContent(content, extracted, limits, xmlBudget);
 			continue;
 		}
 		if (extracted.type === "media") {
@@ -203,19 +219,21 @@ async function unzipDocx(buffer, options = {}) {
 	return content;
 }
 /**
-* Parts that every consumer expands into an object tree. Preflighting them once
-* here puts the bound on the unzip, so `parseDocx`, the selective save and the
-* repack path all share it instead of each entry point carrying its own.
+* Preflight every XML part the unzip retains, not a named few.
+*
+* Naming the parts to bound is the bug: `word/document.xml`, `word/styles.xml`
+* and `word/numbering.xml` were counted, and headers, footers, footnotes,
+* endnotes, comments and every other `word/*.xml` part were parsed into trees
+* unbounded. Bounding the reader instead of the part list means a part added
+* later is bounded by construction, and the package budget makes the ceiling
+* the package's rather than each part's.
 */
-const PREFLIGHT_XML_PARTS = /* @__PURE__ */ new Set([
-	"word/document.xml",
-	"word/styles.xml",
-	"word/numbering.xml"
-]);
-function assignXmlContent(content, { path, lowerPath, content: xmlContent }, limits) {
-	if (PREFLIGHT_XML_PARTS.has(lowerPath)) assertXmlResourceLimits(xmlContent, {
-		...FOLIO_XML_RESOURCE_LIMITS,
-		maxBytes: limits.maxXmlBytes
+function assignXmlContent(content, { path, lowerPath, content: xmlContent }, limits, budget) {
+	assertXmlResourceLimits({
+		xml: xmlContent,
+		limits: xmlResourceLimitsFor(limits),
+		partPath: path,
+		budget
 	});
 	content.allXml.set(path, xmlContent);
 	if (lowerPath === "word/document.xml") content.documentXml = xmlContent;
@@ -426,14 +444,7 @@ function getMediaMimeType(path) {
 * @returns Data URL string
 */
 function mediaToDataUrl(data, mimeType) {
-	const bytes = new Uint8Array(data);
-	const chunks = [];
-	const chunkSize = 32768;
-	for (let offset = 0; offset < bytes.length; offset += chunkSize) {
-		const chunk = bytes.subarray(offset, offset + chunkSize);
-		chunks.push(String.fromCodePoint(...chunk));
-	}
-	return `data:${mimeType};base64,${btoa(chunks.join(""))}`;
+	return bytesToDataUrl(new Uint8Array(data), mimeType);
 }
 /**
 * Extract a specific file from the original ZIP
@@ -446,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/verbatimCapture.js

@@ -270,7 +270,7 @@ const parsedReplayEnvelope = (xml, inheritedNamespaceScope) => {
 };
 const withinXmlResourceLimits = (xml) => {
 	try {
-		assertXmlResourceLimits(xml);
+		assertXmlResourceLimits({ xml });
 		return true;
 	} catch {
 		return false;

package/dist/docx/vmlImageParser.d.ts

@@ -11,6 +11,22 @@ import { XmlElement } from "./xmlParser.js";
  * same artwork twice.
  */
 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 +38,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,6 +1,7 @@
 import { sanitizeImageSrc } from "../utils/sanitizeImageSrc.js";
 import { pixelsToEmu } from "../utils/units.js";
 import { resolveImageData } from "./imageParser.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";
@@ -73,8 +74,8 @@ const previewImage = (pictElement, svg, widthPx, heightPx, style, rootXmlns) =>
 			type: "image",
 			rId: "",
 			src,
-			mimeType: "image/svg+xml",
-			filename: "vml-shape-preview.svg",
+			mimeType: PREVIEW_KINDS.vmlShape.mimeType,
+			filename: PREVIEW_KINDS.vmlShape.filename,
 			size: {
 				width: pixelsToEmu(widthPx),
 				height: pixelsToEmu(heightPx)
@@ -130,6 +131,22 @@ function shouldPreserveRawVmlPict(pictElement) {
 	return shapes.length > 0 && !shapes.some((shape) => isWatermarkShape(shape));
 }
 /**
+* 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`.
@@ -200,4 +217,4 @@ function parseVmlImageContent(pictElement, rels, media, rootXmlns = {}) {
 	return null;
 }
 //#endregion
-export { parseVmlImageContent, shouldPreserveRawVmlPict };
+export { isVmlPictParsedByRunParser, parseVmlImageContent, shouldPreserveRawVmlPict };

package/dist/docx/vmlPreview.d.ts

@@ -25,7 +25,5 @@ declare const vmlSvgDataUrl: (svg: string) => string | undefined;
 declare const renderStandaloneVmlPreview: (shape: XmlElement) => VmlPreviewResult;
 /** Render a VML group through bounded, non-clipping local-coordinate transforms. */
 declare const renderVmlGroupPreview: (group: XmlElement) => VmlPreviewResult;
-/** Bound retained synthetic VML previews while preserving their raw replay nodes. */
-declare const enforcePackageVmlPreviewBudget: (root: unknown, maxCharacters?: number) => void;
 //#endregion
-export { VmlPreviewResult, enforcePackageVmlPreviewBudget, isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx, vmlSvgDataUrl };
+export { VmlPreviewResult, isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx, vmlSvgDataUrl };

package/dist/docx/vmlPreview.js

@@ -1,3 +1,4 @@
+import { VML_PREVIEW_DATA_URL_PREFIX } from "./previewBudget.js";
 import { findChild, findDeep, getAttribute, getChildElements, getLocalName } from "./xmlParser.js";
 //#region src/docx/vmlPreview.ts
 const MAX_VML_PREVIEW_DEPTH = 16;
@@ -6,10 +7,6 @@ const MAX_VML_PREVIEW_PATH_POINTS = 2e4;
 const MAX_VML_PREVIEW_COORDINATE = 1e6;
 const MAX_VML_PREVIEW_DIMENSION_PX = 2e4;
 const MAX_VML_SVG_CHARACTERS = 1e6;
-const MAX_PACKAGE_VML_PREVIEW_CHARACTERS = 8 * 1024 * 1024;
-const VML_PREVIEW_DATA_URL_PREFIX = "data:image/svg+xml;charset=utf-8,";
-const VML_PREVIEW_FILENAME = "vml-shape-preview.svg";
-const VML_PREVIEW_MIME_TYPE = "image/svg+xml";
 const SAFE_VML_COLORS = /* @__PURE__ */ new Set([
 	"black",
 	"white",
@@ -506,30 +503,5 @@ const renderVmlGroupPreview = (group) => {
 		style
 	};
 };
-/** Bound retained synthetic VML previews while preserving their raw replay nodes. */
-const enforcePackageVmlPreviewBudget = (root, maxCharacters = MAX_PACKAGE_VML_PREVIEW_CHARACTERS) => {
-	let remainingCharacters = Math.max(0, maxCharacters);
-	const visited = /* @__PURE__ */ new WeakSet();
-	const visit = (value) => {
-		if (value === null || typeof value !== "object" || visited.has(value)) return;
-		visited.add(value);
-		if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) return;
-		if (value instanceof Map) {
-			for (const child of value.values()) visit(child);
-			return;
-		}
-		if (Array.isArray(value)) {
-			for (const child of value) visit(child);
-			return;
-		}
-		if ("type" in value && value.type === "image" && "rId" in value && value.rId === "" && "mimeType" in value && value.mimeType === VML_PREVIEW_MIME_TYPE && "filename" in value && value.filename === VML_PREVIEW_FILENAME && "src" in value && typeof value.src === "string" && value.src.startsWith(VML_PREVIEW_DATA_URL_PREFIX)) if (value.src.length <= remainingCharacters) remainingCharacters -= value.src.length;
-		else {
-			remainingCharacters = 0;
-			delete value.src;
-		}
-		for (const child of Object.values(value)) visit(child);
-	};
-	visit(root);
-};
 //#endregion
-export { enforcePackageVmlPreviewBudget, isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx, vmlSvgDataUrl };
+export { isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx, vmlSvgDataUrl };

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 };

package/dist/docx/xmlParser.d.ts

@@ -71,7 +71,22 @@ declare const NAMESPACES: {
 declare const OOXML_NAMESPACE_SCOPE: XmlNamespaceScope;
 declare function parseXml(xml: string, inheritedNamespaceScope?: XmlNamespaceScope): XmlElement;
 /**
- * Serialize an XmlElement back to an XML string
+ * Serialize an XmlElement back to an XML string.
+ *
+ * Written here rather than handed to `fast-xml-parser`'s builder for two
+ * reasons. The builder writes a tab or a newline inside an attribute value
+ * literally, and XML 1.0 §3.3.3 has every conformant reader normalise those to
+ * a space: a `descr="two lines
"` a source file wrote came back as
+ * `descr="two lines "`. `escapeXmlAttribute` writes the character references
+ * that survive that step. And the builder returned a string per node, so a
+ * subtree's bytes were copied into its parent's answer, its grandparent's and
+ * so on, which `writeElement` below replaces with one buffer.
+ *
+ * Those two are the whole difference from the builder: the attribute
+ * character references, an attribute the model dropped written as absent
+ * rather than as the word "undefined", and the characters XML 1.0 §2.2 admits
+ * no spelling for dropped. Every other rule reproduces its output byte for
+ * byte, so replaying a capture is unchanged wherever it was already correct.
  */
 declare function elementToXml(element: XmlElement): string;
 /**
@@ -90,6 +105,15 @@ declare function getLocalName(name: string | undefined): string;
 declare function getNamespacePrefix(name: string): string | null;
 /** Namespace URI resolved from the element's in-scope XML declarations. */
 declare const getNamespaceUri: (element: XmlElement) => string | undefined;
+/**
+ * Namespace URI of one of the element's attributes, by its source spelling.
+ *
+ * An unprefixed attribute has no namespace — it is not in the element's,
+ * which is why this is not {@link getNamespaceUri} with a different argument —
+ * and `undefined` is that answer as well as "the prefix resolves to nothing".
+ * A caller that must tell the two apart checks the spelling for a colon.
+ */
+declare const resolveAttributeNamespaceUri: (element: XmlElement, attributeName: string) => string | undefined;
 /** WordprocessingML main namespace, Transitional and Strict (ECMA-376 Parts 1 and 4). */
 declare const WORDPROCESSINGML_NAMESPACE_URIS: ReadonlySet<string>;
 /** Office document relationship attributes, Transitional and Strict. */
@@ -368,4 +392,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, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument, selectAlternateContentBranch };
+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, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument, resolveAttributeNamespaceUri, selectAlternateContentBranch };

package/dist/docx/xmlParser.js

@@ -1,6 +1,7 @@
 import { NUMBERS_PER_PERCENT, percentageSpelling, transitionalSlotEncoding } from "./transitionalSpelling.js";
 import { universalMeasureAs } from "./universalMeasure.js";
-import { XMLBuilder, XMLParser } from "fast-xml-parser";
+import { escapeXmlAttribute, escapeXmlText } from "@stll/docx-core";
+import { XMLParser } from "fast-xml-parser";
 import { OOXML_NS } from "@stll/docx-utils";
 import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/xmlParser.ts
@@ -42,22 +43,12 @@ const fxpParserOptionsWithStopNodes = {
 	...fxpParserOptions,
 	stopNodes: ["*.w:binData"]
 };
-const fxpBuilderOptions = {
-	preserveOrder: true,
-	ignoreAttributes: false,
-	attributeNamePrefix: "",
-	textNodeName: "#text",
-	suppressEmptyNode: true
-};
 const fxpParser = new XMLParser(fxpParserOptions);
 const fxpParserWithStopNodes = new XMLParser(fxpParserOptionsWithStopNodes);
-const fxpBuilder = new XMLBuilder(fxpBuilderOptions);
 /** Text node key used by fast-xml-parser in preserveOrder mode. */
 const TEXT_KEY = "#text";
 /** Attribute group key used by fast-xml-parser in preserveOrder mode. */
 const ATTR_KEY = ":@";
-/** Character reference required to keep carriage returns through XML end-of-line normalization. */
-const XML_CARRIAGE_RETURN_REFERENCE = "
";
 const EMPTY_NAMESPACE_SCOPE = { bindings: /* @__PURE__ */ new Map() };
 const resolveNamespaceUri = (scope, prefix) => {
 	let current = scope;
@@ -138,18 +129,6 @@ function fxpToRootElement(nodes, inheritedNamespaceScope = EMPTY_NAMESPACE_SCOPE
 	return { elements: nodes };
 }
 /**
-* Convert an XmlElement back into the fast-xml-parser preserveOrder format
-* so we can feed it to XMLBuilder.
-*/
-function elementToFxpNode(el) {
-	if (el.type === "text") return { [TEXT_KEY]: el.text ?? "" };
-	const name = el.name ?? "";
-	const children = el.elements ? el.elements.map(elementToFxpNode) : [];
-	const node = { [name]: children };
-	if (el.attributes && Object.keys(el.attributes).length > 0) node[ATTR_KEY] = el.attributes;
-	return node;
-}
-/**
 * Common OOXML namespace URIs — re-exported from @stll/docx-utils.
 */
 const NAMESPACES = OOXML_NS;
@@ -174,13 +153,64 @@ function parseXml(xml, inheritedNamespaceScope = EMPTY_NAMESPACE_SCOPE) {
 	return fxpToRootElement((xml.includes("binData") ? fxpParserWithStopNodes : fxpParser).parse(xml), inheritedNamespaceScope);
 }
 /**
-* Serialize an XmlElement back to an XML string
+* Serialize an XmlElement back to an XML string.
+*
+* Written here rather than handed to `fast-xml-parser`'s builder for two
+* reasons. The builder writes a tab or a newline inside an attribute value
+* literally, and XML 1.0 §3.3.3 has every conformant reader normalise those to
+* a space: a `descr="two lines
"` a source file wrote came back as
+* `descr="two lines "`. `escapeXmlAttribute` writes the character references
+* that survive that step. And the builder returned a string per node, so a
+* subtree's bytes were copied into its parent's answer, its grandparent's and
+* so on, which `writeElement` below replaces with one buffer.
+*
+* Those two are the whole difference from the builder: the attribute
+* character references, an attribute the model dropped written as absent
+* rather than as the word "undefined", and the characters XML 1.0 §2.2 admits
+* no spelling for dropped. Every other rule reproduces its output byte for
+* byte, so replaying a capture is unchanged wherever it was already correct.
 */
 function elementToXml(element) {
-	const fxpNode = elementToFxpNode(element);
-	return fxpBuilder.build([fxpNode]).replaceAll("\r", XML_CARRIAGE_RETURN_REFERENCE);
+	const out = [];
+	writeElement(element, out);
+	return out.join("");
 }
 /**
+* Serialize into one shared buffer rather than a string per node.
+*
+* Returning a string per element makes a subtree's bytes a substring of its
+* parent's, its grandparent's and so on, so a table pays for its rows, its
+* rows pay for their cells, and a part that nests four levels deep is copied
+* four times before anything is written. Appending into one array of chunks
+* and joining once costs each node its own text and nothing for its ancestors.
+*
+* Whether an element self-closes is not known until its children are written,
+* so the opening tag reserves a slot in the buffer and fills it afterwards:
+* `>` when something was appended, `/>` when nothing was.
+*/
+const writeElement = (element, out) => {
+	if (element.type === "text") {
+		const text = String(element.text ?? "");
+		if (text !== "") out.push(escapeXmlText(text));
+		return;
+	}
+	const name = element.name ?? "";
+	out.push(`<${name}`);
+	if (element.attributes) for (const [attribute, value] of Object.entries(element.attributes)) {
+		if (value === void 0) continue;
+		out.push(` ${attribute}="${escapeXmlAttribute(String(value))}"`);
+	}
+	const openingSlot = out.push("") - 1;
+	const contentStart = out.length;
+	for (const child of element.elements ?? []) writeElement(child, out);
+	if (out.length === contentStart) {
+		out[openingSlot] = "/>";
+		return;
+	}
+	out[openingSlot] = ">";
+	out.push(`</${name}>`);
+};
+/**
 * Parse XML string to a more convenient format
 */
 function parseXmlDocument(xml) {
@@ -216,6 +246,19 @@ function getNamespacePrefix(name) {
 }
 /** Namespace URI resolved from the element's in-scope XML declarations. */
 const getNamespaceUri = (element) => element.namespaceUri;
+/**
+* Namespace URI of one of the element's attributes, by its source spelling.
+*
+* An unprefixed attribute has no namespace — it is not in the element's,
+* which is why this is not {@link getNamespaceUri} with a different argument —
+* and `undefined` is that answer as well as "the prefix resolves to nothing".
+* A caller that must tell the two apart checks the spelling for a colon.
+*/
+const resolveAttributeNamespaceUri = (element, attributeName) => {
+	const colonIndex = attributeName.indexOf(":");
+	if (colonIndex === -1) return;
+	return resolveNamespaceUri(element.namespaceScope, attributeName.slice(0, colonIndex));
+};
 /** WordprocessingML main namespace, Transitional and Strict (ECMA-376 Parts 1 and 4). */
 const WORDPROCESSINGML_NAMESPACE_URIS = /* @__PURE__ */ new Set([NAMESPACES.w, "http://purl.oclc.org/ooxml/wordprocessingml/main"]);
 /** Office document relationship attributes, Transitional and Strict. */
@@ -825,4 +868,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, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument, selectAlternateContentBranch };
+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, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument, resolveAttributeNamespaceUri, selectAlternateContentBranch };