@stll/folio-core 0.35.0 → 0.36.0

package/dist/docx/server/validateDocxConformance.js

@@ -98,6 +98,20 @@ const validateRequiredParts = (archive, report) => {
 	});
 	return false;
 };
+const XML_SAFETY_ISSUE = {
+	"doctype-forbidden": {
+		code: "xml-doctype-forbidden",
+		message: "XML package parts must not declare a document type."
+	},
+	"entity-forbidden": {
+		code: "xml-not-well-formed",
+		message: "An XML package part contains an invalid entity reference."
+	},
+	"not-well-formed": {
+		code: "xml-not-well-formed",
+		message: "An XML package part is not well formed."
+	}
+};
 const validateXmlParts = async (archive, report) => {
 	const xmlByPath = /* @__PURE__ */ new Map();
 	let hasInvalidXml = false;
@@ -106,27 +120,17 @@ const validateXmlParts = async (archive, report) => {
 		if (xml === null) continue;
 		xmlByPath.set(part, xml);
 		const safetyIssue = getDocxXmlSafetyIssue(xml);
-		if (safetyIssue === "doctype-forbidden") {
+		if (safetyIssue !== null) {
 			hasInvalidXml = true;
+			const issue = XML_SAFETY_ISSUE[safetyIssue];
 			addIssue(report, {
 				check: "xml-well-formedness",
-				code: "xml-doctype-forbidden",
-				message: "XML package parts must not declare a document type.",
+				...issue,
 				severity: "error",
 				part
 			});
 			continue;
 		}
-		if (safetyIssue === "not-well-formed") {
-			hasInvalidXml = true;
-			addIssue(report, {
-				check: "xml-well-formedness",
-				code: "xml-not-well-formed",
-				message: "An XML package part is not well formed.",
-				severity: "error",
-				part
-			});
-		}
 	}
 	if (hasInvalidXml) {
 		report.checks.set("xml-well-formedness", "failed");

package/dist/docx/tableParser.js

@@ -3,9 +3,9 @@ import { appendBookmarkMarkerToLastParagraphInBlocks, appendBookmarkMarkerToLast
 import { parseParagraph } from "./paragraphParser.js";
 import { enrichParagraphTextBoxes } from "./paragraphTextBoxEnrichment.js";
 import { BorderStyleSchema, FloatingTableXSpecSchema, FloatingTableYSpecSchema, ShadingPatternSchema, TableCellTextDirectionSchema, ThemeColorSlotSchema, narrowEnum } from "./parserEnums.js";
+import { parsePropertyChangeInfo, parseTrackedChangeInfo } from "./trackedChangeInfo.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
 import { cloneElement, findChild, findChildByLocalName, findChildren, getAttribute, getChildElements, getLocalName, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute, parseTableMeasurementValue } from "./xmlParser.js";
-import { normalizeRevisionId } from "@stll/docx-core/model";
 //#region src/docx/tableParser.ts
 /**
 * Sanity cap on `w:gridSpan` (and the derived table column count). Word's
@@ -36,42 +36,6 @@ function parseTableMeasurement(element) {
 function parseWidth(element) {
 	return parseTableMeasurement(element);
 }
-function parseTrackedChangeInfo(node) {
-	const rawId = getAttribute(node, "w", "id");
-	const parsedId = rawId ? Number.parseInt(rawId, 10) : 0;
-	const author = (getAttribute(node, "w", "author") ?? "").trim();
-	const date = (getAttribute(node, "w", "date") ?? "").trim();
-	const initials = (getAttribute(node, "w", "initials") ?? "").trim();
-	const info = {
-		id: normalizeRevisionId(parsedId),
-		author: author.length > 0 ? author : "Unknown"
-	};
-	if (date.length > 0) info.date = date;
-	if (initials.length > 0) info.initials = initials;
-	const utcDate = utcDateAttribute(node);
-	if (utcDate) info.utcDate = utcDate;
-	return info;
-}
-/** `w16du:dateUtc` under whatever prefix the document bound it to. */
-const utcDateAttribute = (node) => {
-	for (const [attribute, value] of Object.entries(node.attributes ?? {})) {
-		if (typeof value !== "string" || getLocalName(attribute) !== "dateUtc") continue;
-		const trimmed = value.trim();
-		if (trimmed.length > 0) return {
-			attribute,
-			value: trimmed
-		};
-	}
-	return null;
-};
-function parsePropertyChangeInfo(node) {
-	const base = parseTrackedChangeInfo(node);
-	const rsid = (getAttribute(node, "w", "rsid") ?? "").trim();
-	return rsid.length > 0 ? {
-		...base,
-		rsid
-	} : base;
-}
 /**
 * Parse a single border specification
 *

package/dist/docx/trackedChangeInfo.d.ts

@@ -0,0 +1,11 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/trackedChangeInfo.d.ts
+declare const DATE_UTC_NAMESPACE_URI = "http://schemas.microsoft.com/office/word/2023/wordml/word16du";
+declare const DATE_UTC_ATTRIBUTE = "w16du:dateUtc";
+/** Parse the metadata shared by every WordprocessingML tracked-change element. */
+declare const parseTrackedChangeInfo: (node: XmlElement) => document_d_exports.TrackedChangeInfo;
+/** Parse the shared metadata plus the optional property-change revision session. */
+declare const parsePropertyChangeInfo: (node: XmlElement) => document_d_exports.PropertyChangeInfo;
+//#endregion
+export { DATE_UTC_ATTRIBUTE, DATE_UTC_NAMESPACE_URI, parsePropertyChangeInfo, parseTrackedChangeInfo };

package/dist/docx/trackedChangeInfo.js

@@ -0,0 +1,38 @@
+import { WORDPROCESSINGML_NAMESPACE_URIS, findAttributeByNamespaceUri, getAttributeByNamespaceUri } from "./xmlParser.js";
+import { normalizeRevisionId } from "@stll/docx-core/model";
+//#region src/docx/trackedChangeInfo.ts
+const DATE_UTC_NAMESPACE_URI = "http://schemas.microsoft.com/office/word/2023/wordml/word16du";
+const DATE_UTC_ATTRIBUTE = "w16du:dateUtc";
+const DATE_UTC_NAMESPACE_URIS = /* @__PURE__ */ new Set([DATE_UTC_NAMESPACE_URI]);
+/** Parse the metadata shared by every WordprocessingML tracked-change element. */
+const parseTrackedChangeInfo = (node) => {
+	const rawId = getAttributeByNamespaceUri(node, WORDPROCESSINGML_NAMESPACE_URIS, "id");
+	const parsedId = rawId ? Number.parseInt(rawId, 10) : 0;
+	const author = (getAttributeByNamespaceUri(node, WORDPROCESSINGML_NAMESPACE_URIS, "author") ?? "").trim();
+	const date = (getAttributeByNamespaceUri(node, WORDPROCESSINGML_NAMESPACE_URIS, "date") ?? "").trim();
+	const initials = (getAttributeByNamespaceUri(node, WORDPROCESSINGML_NAMESPACE_URIS, "initials") ?? "").trim();
+	const info = {
+		id: normalizeRevisionId(parsedId),
+		author: author.length > 0 ? author : "Unknown"
+	};
+	if (date.length > 0) info.date = date;
+	if (initials.length > 0) info.initials = initials;
+	const utcDate = findAttributeByNamespaceUri(node, DATE_UTC_NAMESPACE_URIS, "dateUtc");
+	const utcDateValue = utcDate?.value.trim() ?? "";
+	if (utcDate && utcDateValue.length > 0) info.utcDate = {
+		attribute: DATE_UTC_ATTRIBUTE,
+		value: utcDateValue
+	};
+	return info;
+};
+/** Parse the shared metadata plus the optional property-change revision session. */
+const parsePropertyChangeInfo = (node) => {
+	const info = parseTrackedChangeInfo(node);
+	const rsid = (getAttributeByNamespaceUri(node, WORDPROCESSINGML_NAMESPACE_URIS, "rsid") ?? "").trim();
+	return rsid.length > 0 ? {
+		...info,
+		rsid
+	} : info;
+};
+//#endregion
+export { DATE_UTC_ATTRIBUTE, DATE_UTC_NAMESPACE_URI, parsePropertyChangeInfo, parseTrackedChangeInfo };

package/dist/docx/verbatimCapture.d.ts

@@ -1,4 +1,4 @@
-import { XmlElement } from "./xmlParser.js";
+import { XmlElement, XmlNamespaceScope } from "./xmlParser.js";
 //#region src/docx/verbatimCapture.d.ts
 declare const UntranslatableStrictNamespaceError_base: import("better-result").TaggedErrorClass<"UntranslatableStrictNamespaceError">;
 /** A Strict fragment uses a namespace that has no Transitional counterpart. */
@@ -6,15 +6,26 @@ declare class UntranslatableStrictNamespaceError extends UntranslatableStrictNam
   message: string;
   uri: string;
 }> {}
+declare const captureVerbatimXml: (element: XmlElement) => string;
+type SanitizeCapturedXmlOptions = {
+  allowedLocalNames: ReadonlySet<string>;
+  allowedNamespaceUris: ReadonlySet<string>;
+  inheritedNamespaceScope?: XmlNamespaceScope;
+  requiredNamespaceBindings?: ReadonlyMap<string, string>;
+  transform?: (element: XmlElement) => XmlElement;
+  validate?: (element: XmlElement) => boolean;
+};
+/** Validate a complete XML part immediately before package output. */
+declare const isSafeCapturedXmlDocument: (xml: string) => boolean;
 /**
- * Serialize parsed markup for replay inside a rebuilt Transitional part.
+ * Re-parse and serialize one captured element before replaying it.
  *
- * Every verbatim capture goes through here — a lint rule keeps
- * {@link elementToXml} out of reach of the parsers — so a replay path added
- * later cannot skip the conversion. Markup that binds no Strict namespace,
- * anywhere in scope or in the fragment itself, is serialized once and returned
- * unchanged.
+ * 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.
  */
-declare const captureVerbatimXml: (element: XmlElement) => string;
+declare const sanitizeCapturedXmlElement: (xml: string | undefined, options: SanitizeCapturedXmlOptions) => string | null;
 //#endregion
-export { UntranslatableStrictNamespaceError, captureVerbatimXml };
+export { UntranslatableStrictNamespaceError, captureVerbatimXml, isSafeCapturedXmlDocument, sanitizeCapturedXmlElement };

package/dist/docx/verbatimCapture.js

@@ -1,7 +1,9 @@
 import { TRANSITIONAL_NAMESPACE_BY_STRICT_URI } from "./strictValueEncodings.gen.js";
 import { isStrictNamespaceUri, toTransitionalNamespaceUri, transitionalSlotEncoding } from "./transitionalSpelling.js";
 import { roundHalfAwayFromZero, universalMeasureAs } from "./universalMeasure.js";
-import { elementToXml, getLocalName } from "./xmlParser.js";
+import { NAMESPACES, OOXML_NAMESPACE_SCOPE, cloneElement, elementToXml, getChildElements, getLocalName, getNamespacePrefix, parseXml } from "./xmlParser.js";
+import { assertXmlResourceLimits } from "./xmlResourceLimits.js";
+import { getDocxXmlSafetyIssue } from "./xmlSafety.js";
 import { TaggedError } from "better-result";
 //#region src/docx/verbatimCapture.ts
 /**
@@ -24,6 +26,15 @@ import { TaggedError } from "better-result";
 /** A Strict fragment uses a namespace that has no Transitional counterpart. */
 var UntranslatableStrictNamespaceError = class extends TaggedError("UntranslatableStrictNamespaceError") {};
 const TRANSITIONAL_URIS = new Set(TRANSITIONAL_NAMESPACE_BY_STRICT_URI.values());
+const XML_NAMESPACE_URI = "http://www.w3.org/XML/1998/namespace";
+const XMLNS_NAMESPACE_URI = "http://www.w3.org/2000/xmlns/";
+const XSI_NAMESPACE_URI = "http://www.w3.org/2001/XMLSchema-instance";
+const NCNAME = /^[\p{L}_][\p{L}\p{N}._\-\u00b7\p{M}]*$/u;
+const MC_QNAME_LIST_ATTRIBUTES = /* @__PURE__ */ new Set([
+	"PreserveAttributes",
+	"PreserveElements",
+	"ProcessContent"
+]);
 /**
 * Drawing extensions the repository has no schema for.
 *
@@ -71,12 +82,14 @@ const originOf = (element, inherited) => {
 	});
 	return TRANSITIONAL_URIS.has(uri) ? "transitional" : inherited;
 };
-const convertAttributes = (element, namespaceUri, localName) => {
+const convertAttributes = (element, namespaceUri, localName, convertValues) => {
 	const attributes = element.attributes ?? {};
 	let converted;
 	for (const [name, raw] of Object.entries(attributes)) {
 		if (typeof raw !== "string") continue;
-		const next = name === "xmlns" || name.startsWith("xmlns:") ? toTransitionalNamespaceUri(raw) : transitionalValue(raw, namespaceUri, transitionalSlotEncoding(element.namespaceUri, localName, getLocalName(name)));
+		let next = raw;
+		if (name === "xmlns" || name.startsWith("xmlns:")) next = toTransitionalNamespaceUri(raw);
+		else if (convertValues) next = transitionalValue(raw, namespaceUri, transitionalSlotEncoding(element.namespaceUri, localName, getLocalName(name)));
 		if (next === raw) continue;
 		converted ??= { ...attributes };
 		converted[name] = next;
@@ -93,7 +106,7 @@ const toTransitional = (element, inherited) => {
 	const namespaceUri = element.namespaceUri === void 0 ? "" : toTransitionalNamespaceUri(element.namespaceUri);
 	const localName = getLocalName(element.name);
 	const textEncoding = transitionalSlotEncoding(element.namespaceUri, localName);
-	const attributes = origin === "strict" && element.attributes ? convertAttributes(element, namespaceUri, localName) : void 0;
+	const attributes = element.attributes ? convertAttributes(element, namespaceUri, localName, origin === "strict") : void 0;
 	let elements;
 	for (const [index, child] of (element.elements ?? []).entries()) {
 		const next = origin === "strict" && child.type === "text" && typeof child.text === "string" ? childWithValue(child, transitionalValue(child.text, namespaceUri, textEncoding)) : toTransitional(child, origin);
@@ -113,6 +126,45 @@ const scopeDeclaresStrict = (scope) => {
 	for (let current = scope; current; current = current.parent) for (const uri of current.bindings.values()) if (uri.startsWith("http://purl.oclc.org/ooxml/")) return true;
 	return false;
 };
+const resolveNamespaceBinding = (scope, prefix) => {
+	if (prefix === "xml") return XML_NAMESPACE_URI;
+	for (let current = scope; current; current = current.parent) {
+		const value = current.bindings.get(prefix);
+		if (value !== void 0) return value;
+	}
+};
+const namespaceValueKind = (element, attributeName) => {
+	const prefix = getNamespacePrefix(attributeName);
+	const namespaceUri = prefix === null ? "" : toTransitionalNamespaceUri(resolveNamespaceBinding(element.namespaceScope, prefix) ?? "");
+	const localName = getLocalName(attributeName);
+	if (namespaceUri === XSI_NAMESPACE_URI && localName === "type") return "qname";
+	if (namespaceUri === NAMESPACES.mc) {
+		if (localName === "Ignorable" || localName === "MustUnderstand") return "prefix-list";
+		if (MC_QNAME_LIST_ATTRIBUTES.has(localName)) return "qname-list";
+	}
+	if (prefix === null && localName === "Requires" && getLocalName(element.name ?? "") === "Choice" && toTransitionalNamespaceUri(element.namespaceUri ?? "") === NAMESPACES.mc) return "prefix-list";
+	return null;
+};
+const referencedNamespacePrefixes = (element, attributeName, value) => {
+	const kind = namespaceValueKind(element, attributeName);
+	if (kind === null) return [];
+	const tokens = value.trim() === "" ? [] : value.trim().split(/\s+/u);
+	if (kind === "qname" && tokens.length !== 1) return null;
+	const prefixes = [];
+	for (const token of tokens) {
+		if (kind === "prefix-list") {
+			if (!NCNAME.test(token) || resolveNamespaceBinding(element.namespaceScope, token) === void 0) return null;
+			prefixes.push(token);
+			continue;
+		}
+		const parts = token.split(":");
+		if (parts.length > 2 || parts.some((part) => !NCNAME.test(part))) return null;
+		const prefix = parts.length === 2 ? parts[0] : "";
+		if (prefix !== "" && resolveNamespaceBinding(element.namespaceScope, prefix) === void 0) return null;
+		prefixes.push(prefix);
+	}
+	return prefixes;
+};
 /**
 * Serialize parsed markup for replay inside a rebuilt Transitional part.
 *
@@ -122,10 +174,158 @@ const scopeDeclaresStrict = (scope) => {
 * anywhere in scope or in the fragment itself, is serialized once and returned
 * unchanged.
 */
+const materializeInheritedNamespaceBindings = (element) => {
+	const additions = {};
+	const rootAttributes = element.attributes ?? {};
+	const addInheritedBinding = (node, prefix) => {
+		if (prefix === "xml" || prefix === "xmlns") return;
+		const attributeName = prefix === "" ? "xmlns" : `xmlns:${prefix}`;
+		if (rootAttributes[attributeName] !== void 0 || additions[attributeName] !== void 0) return;
+		const namespaceUri = resolveNamespaceBinding(node.namespaceScope, prefix);
+		if (namespaceUri === void 0) return;
+		const canonicalNamespace = OOXML_NAMESPACE_SCOPE.bindings.get(prefix);
+		if (canonicalNamespace !== void 0 && toTransitionalNamespaceUri(namespaceUri) === canonicalNamespace) return;
+		additions[attributeName] = namespaceUri;
+	};
+	const visit = (node, inheritedDeclarations) => {
+		const declarations = new Set(inheritedDeclarations);
+		for (const name of Object.keys(node.attributes ?? {})) if (name === "xmlns") declarations.add("");
+		else if (name.startsWith("xmlns:")) declarations.add(name.slice(6));
+		const elementPrefix = node.name ? getNamespacePrefix(node.name) : null;
+		if (elementPrefix !== null && !declarations.has(elementPrefix)) addInheritedBinding(node, elementPrefix);
+		else if (elementPrefix === null && !declarations.has("")) addInheritedBinding(node, "");
+		for (const [name, value] of Object.entries(node.attributes ?? {})) {
+			if (name === "xmlns" || name.startsWith("xmlns:")) continue;
+			const attributePrefix = getNamespacePrefix(name);
+			if (attributePrefix !== null && !declarations.has(attributePrefix)) addInheritedBinding(node, attributePrefix);
+			const prefixes = referencedNamespacePrefixes(node, name, String(value));
+			if (prefixes === null) continue;
+			for (const prefix of prefixes) if (!declarations.has(prefix)) addInheritedBinding(node, prefix);
+		}
+		for (const child of node.elements ?? []) if (child.type === "element") visit(child, declarations);
+	};
+	visit(element, /* @__PURE__ */ new Set());
+	return Object.keys(additions).length === 0 ? element : cloneElement(element, { attributes: {
+		...rootAttributes,
+		...additions
+	} });
+};
 const captureVerbatimXml = (element) => {
-	const xml = elementToXml(element);
-	if (!xml.includes("http://purl.oclc.org/ooxml/") && !scopeDeclaresStrict(element.namespaceScope)) return xml;
-	return elementToXml(toTransitional(element, "transitional"));
+	const replayableElement = materializeInheritedNamespaceBindings(element);
+	const xml = elementToXml(replayableElement);
+	if (!xml.includes("http://purl.oclc.org/ooxml/") && !scopeDeclaresStrict(replayableElement.namespaceScope)) return xml;
+	return elementToXml(toTransitional(replayableElement, "transitional"));
+};
+const hasRequiredNamespaceBindings = (element, required) => {
+	if (!required) return true;
+	for (const [prefix, namespaceUri] of required) {
+		const resolved = resolveNamespaceBinding(element.namespaceScope, prefix);
+		if (resolved === void 0 || toTransitionalNamespaceUri(resolved) !== namespaceUri) return false;
+	}
+	return true;
+};
+const validNamespaceDeclaration = (name, value) => {
+	if (name === "xmlns") return value !== XML_NAMESPACE_URI && value !== XMLNS_NAMESPACE_URI;
+	const prefix = name.slice(6);
+	if (prefix.toLowerCase().startsWith("xml") && prefix !== "xml") return false;
+	if (prefix === "xml") return value === XML_NAMESPACE_URI;
+	return value !== "" && value !== XML_NAMESPACE_URI && value !== XMLNS_NAMESPACE_URI;
+};
+const hasBoundNamespaces = (root) => {
+	const pending = [root];
+	while (pending.length > 0) {
+		const element = pending.pop();
+		if (!element || element.type !== "element" || !element.name) return false;
+		const elementPrefix = getNamespacePrefix(element.name);
+		if (elementPrefix === "xmlns" || elementPrefix !== null && elementPrefix !== "xml" && resolveNamespaceBinding(element.namespaceScope, elementPrefix) === void 0) return false;
+		const expandedAttributeNames = /* @__PURE__ */ new Set();
+		for (const [name, rawValue] of Object.entries(element.attributes ?? {})) {
+			const value = String(rawValue ?? "");
+			if (name === "xmlns" || name.startsWith("xmlns:")) {
+				if (!validNamespaceDeclaration(name, value)) return false;
+				continue;
+			}
+			const prefix = getNamespacePrefix(name);
+			if (prefix === "xmlns" || prefix !== null && prefix !== "xml" && resolveNamespaceBinding(element.namespaceScope, prefix) === void 0) return false;
+			const expandedName = `${toTransitionalNamespaceUri((prefix === null ? "" : resolveNamespaceBinding(element.namespaceScope, prefix)) ?? "")}\u0000${getLocalName(name)}`;
+			if (expandedAttributeNames.has(expandedName)) return false;
+			expandedAttributeNames.add(expandedName);
+			if (referencedNamespacePrefixes(element, name, value) === null) return false;
+		}
+		for (const child of getChildElements(element)) pending.push(child);
+	}
+	return true;
+};
+const parsedReplayEnvelope = (xml, inheritedNamespaceScope) => {
+	let wrapper;
+	try {
+		wrapper = parseXml(`<folio-replay-envelope>${xml}</folio-replay-envelope>`, inheritedNamespaceScope).elements?.at(0);
+	} catch {
+		return null;
+	}
+	if (!wrapper || wrapper.type !== "element") return null;
+	let root = null;
+	for (const child of wrapper.elements ?? []) {
+		if (child.type === "text") {
+			if (String(child.text ?? "").trim() !== "") return null;
+			continue;
+		}
+		if (child.type !== "element" || root !== null) return null;
+		root = child;
+	}
+	return root;
+};
+const withinXmlResourceLimits = (xml) => {
+	try {
+		assertXmlResourceLimits(xml);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const EMPTY_NAMESPACE_SCOPE = { bindings: /* @__PURE__ */ new Map() };
+/** Validate a complete XML part immediately before package output. */
+const isSafeCapturedXmlDocument = (xml) => {
+	const trimmed = xml.trim();
+	if (trimmed === "" || !withinXmlResourceLimits(xml) || getDocxXmlSafetyIssue(xml) !== null) return false;
+	const root = parsedReplayEnvelope(trimmed, EMPTY_NAMESPACE_SCOPE);
+	return root !== null && hasBoundNamespaces(root);
+};
+const captureAllowedElement = (element, { allowedLocalNames, allowedNamespaceUris, inheritedNamespaceScope, requiredNamespaceBindings, transform, validate }) => {
+	let passesDomainValidation = true;
+	try {
+		passesDomainValidation = validate?.(element) ?? true;
+	} catch {
+		return null;
+	}
+	if (element.type !== "element" || !element.name || !allowedLocalNames.has(getLocalName(element.name)) || !allowedNamespaceUris.has(toTransitionalNamespaceUri(element.namespaceUri ?? "")) || !hasBoundNamespaces(element) || !hasRequiredNamespaceBindings(element, requiredNamespaceBindings) || !passesDomainValidation) return null;
+	try {
+		const replayElement = transform?.(element) ?? element;
+		if (!(transform === void 0 ? true : validate?.(replayElement) ?? true) || !hasBoundNamespaces(replayElement) || !hasRequiredNamespaceBindings(replayElement, requiredNamespaceBindings)) return null;
+		const captured = captureVerbatimXml(replayElement);
+		const capturedRoot = parsedReplayEnvelope(captured, inheritedNamespaceScope ?? OOXML_NAMESPACE_SCOPE);
+		if (capturedRoot === null || !hasBoundNamespaces(capturedRoot) || !hasRequiredNamespaceBindings(capturedRoot, requiredNamespaceBindings) || !(validate?.(capturedRoot) ?? true)) return null;
+		return captured;
+	} catch {
+		return null;
+	}
+};
+/**
+* Re-parse and serialize one captured element before replaying it.
+*
+* 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.
+*/
+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;
 };
 //#endregion
-export { UntranslatableStrictNamespaceError, captureVerbatimXml };
+export { UntranslatableStrictNamespaceError, captureVerbatimXml, isSafeCapturedXmlDocument, sanitizeCapturedXmlElement };

package/dist/docx/xmlParser.d.ts

@@ -117,6 +117,8 @@ declare const WORDPROCESSINGML_NAMESPACE_URIS: ReadonlySet<string>;
  * from a foreign namespace is not accepted.
  */
 declare function findChildByNamespaceUri(parent: XmlElement | null | undefined, namespaceUris: ReadonlySet<string>, localName: string): XmlElement | null;
+/** All direct children whose local name and resolved namespace both match. */
+declare function findChildrenByNamespaceUri(parent: XmlElement | null | undefined, namespaceUris: ReadonlySet<string>, localName: string): XmlElement[];
 type XmlAttributeMatch = {
   name: string;
   value: string;
@@ -367,4 +369,4 @@ declare function cloneWithXmlnsDeclarations(element: XmlElement, xmlnsDecls: Rec
  */
 declare function cloneElement(element: XmlElement, overrides: Partial<XmlElement>): XmlElement;
 //#endregion
-export { NAMESPACES, OOXML_NAMESPACE_SCOPE, WORDPROCESSINGML_NAMESPACE_URIS, XmlAttributeMatch, XmlElement, XmlNamespaceScope, attachXmlNamespaceContext, cloneElement, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findAttributeByNamespaceUri, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument };
+export { NAMESPACES, 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, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument };

package/dist/docx/xmlParser.js

@@ -227,6 +227,11 @@ function findChildByNamespaceUri(parent, namespaceUris, localName) {
 	for (const child of parent.elements) if (child.type === "element" && hasLocalName(child.name, localName) && namespaceUris.has(child.namespaceUri ?? "")) return child;
 	return null;
 }
+/** All direct children whose local name and resolved namespace both match. */
+function findChildrenByNamespaceUri(parent, namespaceUris, localName) {
+	if (!parent?.elements) return [];
+	return parent.elements.filter((child) => child.type === "element" && hasLocalName(child.name, localName) && namespaceUris.has(child.namespaceUri ?? ""));
+}
 /** Find an attribute whose prefix resolves to one of the accepted namespace URIs. */
 function findAttributeByNamespaceUri(element, namespaceUris, localName) {
 	if (!element?.attributes) return null;
@@ -783,4 +788,4 @@ function cloneElement(element, overrides) {
 	return clone;
 }
 //#endregion
-export { NAMESPACES, OOXML_NAMESPACE_SCOPE, WORDPROCESSINGML_NAMESPACE_URIS, attachXmlNamespaceContext, cloneElement, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findAttributeByNamespaceUri, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument };
+export { NAMESPACES, 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, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument };

package/dist/docx/xmlSafety.d.ts

@@ -1,5 +1,5 @@
 //#region src/docx/xmlSafety.d.ts
-type DocxXmlSafetyIssue = "doctype-forbidden" | "not-well-formed";
+type DocxXmlSafetyIssue = "doctype-forbidden" | "entity-forbidden" | "not-well-formed";
 declare const getDocxXmlSafetyIssue: (xml: string) => DocxXmlSafetyIssue | null;
 //#endregion
 export { DocxXmlSafetyIssue, getDocxXmlSafetyIssue };