@stll/folio-core 0.54.2 → 0.55.0

package/dist/docx/storyBlockReplay.js

@@ -0,0 +1,367 @@
+import { canonicalJson } from "../utils/canonicalJson.js";
+import { spliceXml } from "./selectiveXmlPatch.js";
+import { getXmlSourceRange, parseStreamingXmlWithSourceRanges } from "./streamingXmlParser.js";
+import { TRANSITIONAL_NAMESPACE_BY_STRICT_URI } from "./strictValueEncodings.gen.js";
+import { captureSourceProfileXml, isSafeCapturedXmlDocument } from "./verbatimCapture.js";
+import { WORDPROCESSINGML_NAMESPACE_URIS, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespaceUri } from "./xmlParser.js";
+import { escapeXmlAttribute } from "@stll/docx-core";
+import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
+//#region src/docx/storyBlockReplay.ts
+const BLOCK_ELEMENT_NAMES = {
+	paragraph: "p",
+	table: "tbl",
+	blockSdt: "sdt",
+	blockCustomXml: "customXml",
+	preservedBlock: null,
+	bookmarkStart: "bookmarkStart",
+	bookmarkEnd: "bookmarkEnd"
+};
+const modelMatchesElement = ({ value, element, mode }) => {
+	if (value === void 0) return false;
+	if (mode === "source" && getLocalName(element.name) === "AlternateContent" && getNamespaceUri(element) === "http://schemas.openxmlformats.org/markup-compatibility/2006" && (value.type === "paragraph" || value.type === "table")) return true;
+	const name = BLOCK_ELEMENT_NAMES[value.type];
+	if (name !== null) return getLocalName(element.name) === name && WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(element) ?? "");
+	if (value.type !== "preservedBlock") return false;
+	const parsed = parseStreamingXmlWithSourceRanges(value.xml, element.namespaceScope);
+	if (parsed.status !== "parsed") return false;
+	const roots = getChildElements(parsed.value);
+	const root = roots.at(0);
+	const normalize = (uri) => uri === void 0 ? void 0 : TRANSITIONAL_NAMESPACE_BY_STRICT_URI.get(uri) ?? uri;
+	return roots.length === 1 && root !== void 0 && getLocalName(root.name) === getLocalName(element.name) && normalize(getNamespaceUri(root)) === normalize(getNamespaceUri(element));
+};
+const XML_TOKEN = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<\?[\s\S]*?\?>|<(?:"[^"]*"|'[^']*'|[^'">])*>/gu;
+const XML_ATTRIBUTE = /([^\s=<>/]+)(\s*=\s*)(["'])(.*?)\3/gsu;
+const readStory = (xml, scope) => {
+	const parsed = parseStreamingXmlWithSourceRanges(xml, scope);
+	if (parsed.status !== "parsed") return null;
+	const roots = getChildElements(parsed.value);
+	const root = roots.at(0);
+	if (roots.length !== 1 || !root || !WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(root) ?? "")) return null;
+	if (root.elements?.some((child) => child.type === "text" && String(child.text ?? "").trim() !== "")) return null;
+	const children = getChildElements(root);
+	const blocks = [];
+	for (const element of children) {
+		const range = getXmlSourceRange(element);
+		if (!range) return null;
+		blocks.push({
+			element,
+			...range
+		});
+	}
+	const range = getXmlSourceRange(root);
+	return range ? {
+		root,
+		blocks,
+		range
+	} : null;
+};
+const effectiveBindings = (element) => {
+	const bindings = /* @__PURE__ */ new Map();
+	let scope = element.namespaceScope;
+	while (scope) {
+		for (const [prefix, uri] of scope.bindings) if (!bindings.has(prefix)) bindings.set(prefix, uri);
+		scope = scope.parent;
+	}
+	return bindings;
+};
+const generatedFragment = ({ xml, element, sourceNamespace, generatedRoot }) => {
+	const strict = TRANSITIONAL_NAMESPACE_BY_STRICT_URI.has(sourceNamespace);
+	const first = [...xml.matchAll(XML_TOKEN)].at(0);
+	if (!first || first.index !== 0 || first[0].startsWith("<!") || first[0].startsWith("<?")) return null;
+	const opening = first[0];
+	const additions = [];
+	const bindings = effectiveBindings(element);
+	const markupCompatibilityUri = "http://schemas.openxmlformats.org/markup-compatibility/2006";
+	const ignorableUris = /* @__PURE__ */ new Set([markupCompatibilityUri]);
+	const inheritedIgnorable = generatedRoot === void 0 ? null : getAttributeByNamespaceUri(generatedRoot, ignorableUris, "Ignorable");
+	const localIgnorable = getAttributeByNamespaceUri(element, ignorableUris, "Ignorable");
+	const ignorable = [...new Set(`${inheritedIgnorable ?? ""} ${localIgnorable ?? ""}`.trim().split(/\s+/u).filter(Boolean))];
+	let ignorableAttribute;
+	if (ignorable.length > 0) {
+		const localAttribute = Object.keys(element.attributes ?? {}).find((name) => {
+			const colon = name.indexOf(":");
+			return colon > 0 && getLocalName(name) === "Ignorable" && bindings.get(name.slice(0, colon)) === markupCompatibilityUri;
+		});
+		const compatibilityPrefix = localAttribute?.slice(0, localAttribute.indexOf(":")) ?? [...bindings].find(([prefix, uri]) => prefix !== "" && uri === markupCompatibilityUri)?.[0];
+		if (compatibilityPrefix === void 0 || ignorable.some((prefix) => !bindings.has(prefix))) return null;
+		ignorableAttribute = `${compatibilityPrefix}:Ignorable`;
+		if (localIgnorable === null) additions.push(` ${ignorableAttribute}="${escapeXmlAttribute(ignorable.join(" "))}"`);
+	}
+	for (const [prefix, uri] of bindings) {
+		const name = prefix === "" ? "xmlns" : `xmlns:${prefix}`;
+		if (element.attributes?.[name] !== void 0) continue;
+		additions.push(` ${name}="${escapeXmlAttribute(uri)}"`);
+	}
+	let replacedOpening = opening.replace(XML_ATTRIBUTE, (match, name, assignment, quote) => name === ignorableAttribute ? `${name}${assignment}${quote}${escapeXmlAttribute(ignorable.join(" "))}${quote}` : match);
+	const close = opening.endsWith("/>") ? replacedOpening.length - 2 : replacedOpening.length - 1;
+	replacedOpening = replacedOpening.slice(0, close) + additions.join("") + replacedOpening.slice(close);
+	const materialized = replacedOpening + xml.slice(opening.length);
+	if (!isSafeCapturedXmlDocument(materialized)) return null;
+	if (!strict) return materialized;
+	const parsed = parseStreamingXmlWithSourceRanges(materialized);
+	if (parsed.status !== "parsed") return null;
+	const root = getChildElements(parsed.value).at(0);
+	return root === void 0 ? null : captureSourceProfileXml(root, DOCX_CONFORMANCE_CLASSES.STRICT);
+};
+const paragraphIdentity = (value) => value.type === "paragraph" ? value.paraId?.toUpperCase() : void 0;
+const addCandidate = ({ map, key, index }) => {
+	const queue = map.get(key);
+	if (queue) queue.indices.push(index);
+	else map.set(key, {
+		indices: [index],
+		cursor: 0
+	});
+};
+const takeCandidate = (queue, used) => {
+	if (!queue) return void 0;
+	while (queue.cursor < queue.indices.length) {
+		const candidate = queue.indices[queue.cursor];
+		queue.cursor += 1;
+		if (candidate !== void 0 && !used.has(candidate)) return candidate;
+	}
+};
+/** Replace only mapped block ranges, retaining authored root syntax and every intervening gap. */
+const replayBlocks = ({ sourceXml, baselineContent, currentContent, serializedXml }, scope) => {
+	const source = readStory(sourceXml, scope?.source);
+	const generated = readStory(serializedXml, scope?.generated);
+	if (!source || !generated || getLocalName(source.root.name) !== getLocalName(generated.root.name) || source.blocks.length !== baselineContent.length || generated.blocks.length !== currentContent.length) return null;
+	if (source.blocks.some((block, index) => !modelMatchesElement({
+		value: baselineContent[index],
+		element: block.element,
+		mode: "source"
+	})) || generated.blocks.some((block, index) => !modelMatchesElement({
+		value: currentContent[index],
+		element: block.element,
+		mode: "generated"
+	}))) return null;
+	const generatedRoot = scope?.generatedRoot ?? generated.root;
+	const fingerprints = baselineContent.map(canonicalJson);
+	const identities = /* @__PURE__ */ new Map();
+	const byFingerprint = /* @__PURE__ */ new Map();
+	for (const [index, block] of baselineContent.entries()) {
+		const fingerprint = fingerprints[index];
+		if (fingerprint === void 0) return null;
+		addCandidate({
+			map: byFingerprint,
+			key: fingerprint,
+			index
+		});
+		const identity = paragraphIdentity(block);
+		if (identity !== void 0) addCandidate({
+			map: identities,
+			key: identity,
+			index
+		});
+	}
+	const used = /* @__PURE__ */ new Set();
+	const fragments = [];
+	for (const [index, block] of currentContent.entries()) {
+		const fingerprint = canonicalJson(block);
+		const identity = paragraphIdentity(block);
+		let originalIndex = takeCandidate(identity === void 0 ? void 0 : identities.get(identity), used) ?? takeCandidate(byFingerprint.get(fingerprint), used);
+		if (originalIndex === void 0 && (block.type === "table" || block.type === "blockSdt" || block.type === "blockCustomXml") && !used.has(index)) {
+			if (baselineContent[index]?.type === block.type) originalIndex = index;
+		}
+		if (originalIndex !== void 0) used.add(originalIndex);
+		const original = originalIndex === void 0 ? void 0 : source.blocks[originalIndex];
+		if (originalIndex !== void 0 && original && fingerprints[originalIndex] === fingerprint) {
+			fragments.push(sourceXml.slice(original.start, original.end));
+			continue;
+		}
+		const replacement = generated.blocks[index];
+		if (!replacement) return null;
+		if (original && originalIndex !== void 0) {
+			const nested = replayNestedBlock({
+				sourceXml,
+				serializedXml,
+				sourceElement: original.element,
+				generatedElement: replacement.element,
+				baseline: baselineContent[originalIndex],
+				current: block,
+				generatedRoot
+			});
+			if (nested !== null) {
+				fragments.push(nested);
+				continue;
+			}
+		}
+		const fragment = generatedFragment({
+			xml: serializedXml.slice(replacement.start, replacement.end),
+			element: replacement.element,
+			sourceNamespace: getNamespaceUri(source.root) ?? "",
+			generatedRoot
+		});
+		if (fragment === null) return null;
+		fragments.push(fragment);
+	}
+	const splices = source.blocks.map((block, index) => ({
+		start: block.start,
+		end: block.end,
+		newXml: index === source.blocks.length - 1 ? fragments.slice(index).join("") : fragments[index] ?? ""
+	}));
+	if (source.blocks.length === 0 && fragments.length > 0) {
+		const opening = [...sourceXml.slice(source.range.start, source.range.end).matchAll(XML_TOKEN)].at(0)?.[0];
+		if (!opening || !source.root.name) return null;
+		if (opening.endsWith("/>")) splices.push({
+			start: source.range.start,
+			end: source.range.end,
+			newXml: `${opening.slice(0, -2)}>${fragments.join("")}</${source.root.name}>`
+		});
+		else {
+			const close = sourceXml.lastIndexOf("</", source.range.end);
+			if (close < source.range.start) return null;
+			splices.push({
+				start: close,
+				end: close,
+				newXml: fragments.join("")
+			});
+		}
+	}
+	return spliceXml(sourceXml, splices);
+};
+const buildStoryBlockReplay = (options) => replayBlocks(options);
+const withoutChildren = (value, key) => Object.fromEntries(Object.entries(value).filter(([name]) => name !== key));
+const wordChildren = (element, name) => getChildElements(element).filter((child) => getLocalName(child.name) === name && WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(child) ?? ""));
+const replayNestedBlock = ({ sourceXml, serializedXml, sourceElement, generatedElement, baseline, current, generatedRoot }) => {
+	if (baseline === void 0 || baseline.type !== current.type) return null;
+	const sourceRange = getXmlSourceRange(sourceElement);
+	if (!sourceRange) return null;
+	const splices = [];
+	const nestedContent = (sourceContainer, generatedContainer, before, after) => {
+		const sourceContentRange = getXmlSourceRange(sourceContainer);
+		const generatedContentRange = getXmlSourceRange(generatedContainer);
+		if (!sourceContentRange || !generatedContentRange) return false;
+		const patched = replayBlocks({
+			sourceXml: sourceXml.slice(sourceContentRange.start, sourceContentRange.end),
+			serializedXml: serializedXml.slice(generatedContentRange.start, generatedContentRange.end),
+			baselineContent: before,
+			currentContent: after
+		}, {
+			source: sourceContainer.namespaceScope,
+			generated: generatedContainer.namespaceScope,
+			generatedRoot
+		});
+		if (patched === null) return false;
+		splices.push({
+			start: sourceContentRange.start - sourceRange.start,
+			end: sourceContentRange.end - sourceRange.start,
+			newXml: patched
+		});
+		return true;
+	};
+	switch (current.type) {
+		case "blockSdt":
+		case "blockCustomXml": {
+			if (baseline.type !== "blockSdt" && baseline.type !== "blockCustomXml" || canonicalJson(withoutChildren(baseline, "content")) !== canonicalJson(withoutChildren(current, "content"))) return null;
+			if (current.type === "blockCustomXml") {
+				if (!nestedContent(sourceElement, generatedElement, baseline.content, current.content)) return null;
+				break;
+			}
+			const sourceChildren = wordChildren(sourceElement, "sdtContent");
+			const generatedChildren = wordChildren(generatedElement, "sdtContent");
+			const sourceContainer = sourceChildren.at(0);
+			const generatedContainer = generatedChildren.at(0);
+			if (sourceChildren.length !== 1 || generatedChildren.length !== 1 || !sourceContainer || !generatedContainer || !nestedContent(sourceContainer, generatedContainer, baseline.content, current.content)) return null;
+			break;
+		}
+		case "table": {
+			if (baseline.type !== "table" || baseline.rows.length !== current.rows.length || canonicalJson(withoutChildren(baseline, "rows")) !== canonicalJson(withoutChildren(current, "rows"))) return null;
+			const sourceRows = wordChildren(sourceElement, "tr");
+			const generatedRows = wordChildren(generatedElement, "tr");
+			if (sourceRows.length !== current.rows.length || generatedRows.length !== current.rows.length) return null;
+			for (const [rowIndex, row] of current.rows.entries()) {
+				const beforeRow = baseline.rows[rowIndex];
+				const sourceRow = sourceRows[rowIndex];
+				const generatedRow = generatedRows[rowIndex];
+				if (beforeRow === void 0 || beforeRow.cells.length !== row.cells.length || canonicalJson(withoutChildren(beforeRow, "cells")) !== canonicalJson(withoutChildren(row, "cells")) || !sourceRow || !generatedRow) return null;
+				const sourceCells = wordChildren(sourceRow, "tc");
+				const generatedCells = wordChildren(generatedRow, "tc");
+				if (sourceCells.length !== row.cells.length || generatedCells.length !== row.cells.length) return null;
+				for (const [cellIndex, cell] of row.cells.entries()) {
+					const beforeCell = beforeRow.cells[cellIndex];
+					const sourceCell = sourceCells[cellIndex];
+					const generatedCell = generatedCells[cellIndex];
+					if (beforeCell === void 0 || canonicalJson(withoutChildren(beforeCell, "content")) !== canonicalJson(withoutChildren(cell, "content")) || !sourceCell || !generatedCell) return null;
+					if (!replayCellContent({
+						sourceXml,
+						serializedXml,
+						sourceCell,
+						generatedCell,
+						before: beforeCell.content,
+						after: cell.content,
+						sourceRangeStart: sourceRange.start,
+						splices,
+						generatedRoot
+					})) return null;
+				}
+			}
+			break;
+		}
+		case "paragraph":
+		case "preservedBlock":
+		case "bookmarkStart":
+		case "bookmarkEnd": return null;
+		default: return current;
+	}
+	return spliceXml(sourceXml.slice(sourceRange.start, sourceRange.end), splices);
+};
+const replayCellContent = ({ sourceXml, serializedXml, sourceCell, generatedCell, before, after, sourceRangeStart, splices, generatedRoot }) => {
+	const sourceRange = getXmlSourceRange(sourceCell);
+	const generatedRange = getXmlSourceRange(generatedCell);
+	if (!sourceRange || !generatedRange) return false;
+	const sourceProperties = wordChildren(sourceCell, "tcPr");
+	const generatedProperties = wordChildren(generatedCell, "tcPr");
+	if (sourceProperties.length > 1 || generatedProperties.length > 1) return false;
+	const sourceProperty = sourceProperties.at(0);
+	const generatedProperty = generatedProperties.at(0);
+	const sourceView = sourceXml.slice(sourceRange.start, sourceRange.end);
+	let generatedView = serializedXml.slice(generatedRange.start, generatedRange.end);
+	const baselineContent = [...before];
+	const currentContent = [...after];
+	if (sourceProperty !== void 0) {
+		if (getChildElements(sourceCell).at(0) !== sourceProperty || !generatedProperty || getChildElements(generatedCell).at(0) !== generatedProperty) return false;
+		const range = getXmlSourceRange(sourceProperty);
+		if (!range) return false;
+		const propertyXml = generatedFragment({
+			xml: sourceXml.slice(range.start, range.end),
+			element: sourceProperty,
+			sourceNamespace: getNamespaceUri(sourceCell) ?? ""
+		});
+		if (propertyXml === null) return false;
+		const property = {
+			type: "preservedBlock",
+			xml: propertyXml
+		};
+		baselineContent.unshift(property);
+		currentContent.unshift(property);
+	} else if (generatedProperty !== void 0) {
+		const range = getXmlSourceRange(generatedProperty);
+		if (!range) return false;
+		const stripped = spliceXml(generatedView, [{
+			start: range.start - generatedRange.start,
+			end: range.end - generatedRange.start,
+			newXml: ""
+		}]);
+		if (stripped === null) return false;
+		generatedView = stripped;
+	}
+	const patched = replayBlocks({
+		sourceXml: sourceView,
+		serializedXml: generatedView,
+		baselineContent,
+		currentContent
+	}, {
+		source: sourceCell.namespaceScope,
+		generated: generatedCell.namespaceScope,
+		generatedRoot
+	});
+	if (patched === null) return false;
+	splices.push({
+		start: sourceRange.start - sourceRangeStart,
+		end: sourceRange.end - sourceRangeStart,
+		newXml: patched
+	});
+	return true;
+};
+//#endregion
+export { buildStoryBlockReplay };

package/dist/docx/streamingXmlParser.d.ts

@@ -6,6 +6,12 @@ type ParseXmlResult = {
 } | {
   status: "unsupported";
 };
+type XmlSourceRange = {
+  readonly start: number;
+  readonly end: number;
+};
+/** Exact element source ranges, available only from the opt-in source-range reader. */
+declare const getXmlSourceRange: (element: XmlElement) => XmlSourceRange | undefined;
 /**
  * Parse ordinary OOXML into Folio's existing element representation in one
  * pass. Unsupported or malformed constructs return a sentinel so callers can
@@ -17,11 +23,20 @@ type AttributeValueSpan = {
 };
 type OpenTagVisitor = (element: XmlElement, attributeValueSpans: ReadonlyMap<string, AttributeValueSpan>) => ReadonlyMap<string, string> | null;
 type OpenTagScanVisitor = (...args: Parameters<OpenTagVisitor>) => null;
+type ElementScanOptions = {
+  element: XmlElement;
+  attributeValueSpans: ReadonlyMap<string, AttributeValueSpan>;
+  nameEnd: number;
+  parent: XmlElement | undefined;
+};
+type ElementScanVisitor = (options: ElementScanOptions) => void;
 /**
  * @param inheritedNamespaceScope the bindings in scope around `xml`, for a
  *   fragment captured out of a part whose root declared them.
  */
 declare const parseStreamingXml: (xml: string, inheritedNamespaceScope?: XmlNamespaceScope) => ParseXmlResult;
+/** Retain source spans for every element without changing the parsed namespace tree. */
+declare const parseStreamingXmlWithSourceRanges: (xml: string, inheritedNamespaceScope?: XmlNamespaceScope) => ParseXmlResult;
 /** Retain the body tree while collecting identities for import repair. */
 declare const parseStreamingXmlWithIdentityVisitor: (xml: string, visitOpenTag: OpenTagScanVisitor) => ParseXmlResult;
 /** Rewrite selected decimal attribute values while preserving every other source byte. */
@@ -37,5 +52,11 @@ declare const scanStreamingXmlNumericIdAttributes: (xml: string, visitOpenTag: O
 } | {
   status: "scanned";
 };
+/** Visit namespace-resolved start tags and source spans without building a tree. */
+declare const scanStreamingXmlElements: (xml: string, visitElement: ElementScanVisitor) => {
+  status: "unsupported";
+} | {
+  status: "scanned";
+};
 //#endregion
-export { parseStreamingXml, parseStreamingXmlWithIdentityVisitor, rewriteStreamingXmlDecimalAttributes, scanStreamingXmlNumericIdAttributes };
+export { getXmlSourceRange, parseStreamingXml, parseStreamingXmlWithIdentityVisitor, parseStreamingXmlWithSourceRanges, rewriteStreamingXmlDecimalAttributes, scanStreamingXmlElements, scanStreamingXmlNumericIdAttributes };

package/dist/docx/streamingXmlParser.js

@@ -2,6 +2,9 @@ import { EMPTY_NAMESPACE_SCOPE, attachXmlNamespaceContext } from "./xmlNamespace
 import { FOLIO_XML_RESOURCE_LIMITS } from "./xmlResourceLimits.js";
 import { isOoxmlNumericIdAttributeName } from "@stll/docx-core";
 //#region src/docx/streamingXmlParser.ts
+const sourceRanges = /* @__PURE__ */ new WeakMap();
+/** Exact element source ranges, available only from the opt-in source-range reader. */
+const getXmlSourceRange = (element) => sourceRanges.get(element);
 const BUILT_IN_ENTITIES = {
 	amp: "&",
 	apos: "'",
@@ -14,6 +17,7 @@ const parseStreamingXmlInternal = (options) => {
 	const visitOpenTag = options.visitOpenTag;
 	let spanMode = "none";
 	if (visitOpenTag !== void 0) spanMode = options.mode === "tree" ? "identities" : "all";
+	if (options.visitElement !== void 0) spanMode = "all";
 	const openTagOptions = {
 		xml,
 		start: 0,
@@ -67,6 +71,10 @@ const parseStreamingXmlInternal = (options) => {
 			const name = xml.slice(open + 2, close).trim();
 			const frame = stack.pop();
 			if (!frame || frame.name !== name) return { status: "unsupported" };
+			if (frame.start !== void 0) sourceRanges.set(frame.element, {
+				start: frame.start,
+				end: close + 1
+			});
 			cursor = close + 1;
 			mergeAdjacentText = false;
 			continue;
@@ -79,6 +87,12 @@ const parseStreamingXmlInternal = (options) => {
 		const scope = parent?.namespaceScope ?? inheritedNamespaceScope;
 		if (options.mode === "attributes" && options.retainAttribute !== void 0 && parsedTag.element.attributes === void 0) parsedTag.element.namespaceScope = scope;
 		else attachXmlNamespaceContext(parsedTag.element, scope);
+		options.visitElement?.({
+			element: parsedTag.element,
+			attributeValueSpans: parsedTag.attributeValueSpans ?? /* @__PURE__ */ new Map(),
+			nameEnd: parsedTag.nameEnd,
+			parent
+		});
 		const rewritten = (options.mode === "tree" ? parsedTag.attributeValueSpans !== void 0 : options.retainAttribute === void 0 || parsedTag.element.attributes !== void 0) ? visitOpenTag?.(parsedTag.element, parsedTag.attributeValueSpans ?? /* @__PURE__ */ new Map()) : null;
 		if (rewritten) for (const [attributeName, value] of rewritten) {
 			const span = parsedTag.attributeValueSpans?.get(attributeName);
@@ -91,11 +105,18 @@ const parseStreamingXmlInternal = (options) => {
 		if (options.mode === "tree") appendElement(parent ?? root, parsedTag.element);
 		if (!parsedTag.selfClosing) {
 			if (stack.length >= FOLIO_XML_RESOURCE_LIMITS.maxDepth) return { status: "unsupported" };
-			stack.push({
+			stack.push(options.mode === "tree" && options.sourceRanges === "tracked" ? {
+				element: parsedTag.element,
+				name: parsedTag.name,
+				start: open
+			} : {
 				element: parsedTag.element,
 				name: parsedTag.name
 			});
-		}
+		} else if (options.mode === "tree" && options.sourceRanges === "tracked") sourceRanges.set(parsedTag.element, {
+			start: open,
+			end: close + 1
+		});
 		cursor = close + 1;
 		mergeAdjacentText = false;
 	}
@@ -121,6 +142,19 @@ const parseStreamingXml = (xml, inheritedNamespaceScope = EMPTY_NAMESPACE_SCOPE)
 		value: parsed.value
 	} : { status: "unsupported" };
 };
+/** Retain source spans for every element without changing the parsed namespace tree. */
+const parseStreamingXmlWithSourceRanges = (xml, inheritedNamespaceScope = EMPTY_NAMESPACE_SCOPE) => {
+	const parsed = parseStreamingXmlInternal({
+		xml,
+		mode: "tree",
+		inheritedNamespaceScope,
+		sourceRanges: "tracked"
+	});
+	return parsed.status === "parsed" ? {
+		status: "parsed",
+		value: parsed.value
+	} : { status: "unsupported" };
+};
 /** Retain the body tree while collecting identities for import repair. */
 const parseStreamingXmlWithIdentityVisitor = (xml, visitOpenTag) => {
 	const parsed = parseStreamingXmlInternal({
@@ -170,12 +204,23 @@ const scanStreamingXmlNumericIdAttributes = (xml, visitOpenTag) => {
 	});
 	return parsed.status === "parsed" ? { status: "scanned" } : parsed;
 };
+/** Visit namespace-resolved start tags and source spans without building a tree. */
+const scanStreamingXmlElements = (xml, visitElement) => {
+	const parsed = parseStreamingXmlInternal({
+		xml,
+		mode: "attributes",
+		visitOpenTag: () => null,
+		visitElement
+	});
+	return parsed.status === "parsed" ? { status: "scanned" } : parsed;
+};
 const parseOpenTag = ({ xml, start, close, spanMode, retainAttribute }) => {
 	let cursor = skipWhitespace(xml, start, close);
 	const nameStart = cursor;
 	cursor = scanName(xml, cursor, close);
 	if (cursor === nameStart) return { status: "unsupported" };
 	const name = xml.slice(nameStart, cursor);
+	const nameEnd = cursor;
 	if (isUnsafePropertyName(name)) return { status: "unsupported" };
 	let attributes;
 	let attributeValueSpans;
@@ -232,6 +277,7 @@ const parseOpenTag = ({ xml, start, close, spanMode, retainAttribute }) => {
 		status: "parsed",
 		element,
 		name,
+		nameEnd,
 		selfClosing,
 		attributeValueSpans
 	};
@@ -358,4 +404,4 @@ const isUnsafePropertyName = (name) => {
 	}
 };
 //#endregion
-export { parseStreamingXml, parseStreamingXmlWithIdentityVisitor, rewriteStreamingXmlDecimalAttributes, scanStreamingXmlNumericIdAttributes };
+export { getXmlSourceRange, parseStreamingXml, parseStreamingXmlWithIdentityVisitor, parseStreamingXmlWithSourceRanges, rewriteStreamingXmlDecimalAttributes, scanStreamingXmlElements, scanStreamingXmlNumericIdAttributes };

package/dist/docx/structuralXmlPatch.js

@@ -1,7 +1,7 @@
 import { canonicalJson } from "../utils/canonicalJson.js";
 import { parseDocumentBody } from "./documentParser.js";
 import { paraIdAttribute } from "./paraIdAttribute.js";
-import { spliceXml } from "./selectiveXmlPatch.js";
+import { spliceSupportsRootNamespaces, spliceXml } from "./selectiveXmlPatch.js";
 import { readRootNamespaceBindings, serializePartElement } from "./serializer/partNamespaces.js";
 import { NAMESPACES, WORDPROCESSINGML_NAMESPACE_URIS, getChildElements, getLocalName, getNamespaceUri, parseXmlDocument } from "./xmlParser.js";
 //#region src/docx/structuralXmlPatch.ts
@@ -203,6 +203,13 @@ const buildStructuralDocumentPatch = ({ originalXml, serializedXml, changedIds }
 		end: source.bodyEnd,
 		newXml: pending.join("")
 	});
+	if (!spliceSupportsRootNamespaces({
+		originalXml,
+		serializedXml,
+		fragments: splices.map(({ newXml }) => newXml).filter(Boolean),
+		originalRoot: source.root,
+		serializedRoot: current.root
+	})) return null;
 	return spliceXml(originalXml, splices);
 };
 //#endregion

package/dist/docx/verbatimCapture.d.ts

@@ -1,3 +1,4 @@
+import { document_d_exports } from "../types/document.js";
 import { XmlElement, XmlNamespaceScope } from "./xmlParser.js";
 //#region src/docx/verbatimCapture.d.ts
 declare const UntranslatableStrictNamespaceError_base: import("better-result").TaggedErrorClass<"UntranslatableStrictNamespaceError">;
@@ -29,5 +30,6 @@ declare const isSafeCapturedXmlDocument: (xml: string) => boolean;
  * must therefore depend on nothing but the element they are given.
  */
 declare const createCapturedXmlSanitizer: (options: SanitizeCapturedXmlOptions) => ((xml: string | undefined) => string | null);
+declare const captureSourceProfileXml: (element: XmlElement, conformance: document_d_exports.DocxConformanceClass | undefined) => string;
 //#endregion
-export { UntranslatableStrictNamespaceError, captureVerbatimXml, createCapturedXmlSanitizer, isSafeCapturedXmlDocument };
+export { UntranslatableStrictNamespaceError, captureSourceProfileXml, captureVerbatimXml, createCapturedXmlSanitizer, isSafeCapturedXmlDocument };

package/dist/docx/verbatimCapture.js

@@ -1,10 +1,11 @@
 import { TRANSITIONAL_NAMESPACE_BY_STRICT_URI } from "./strictValueEncodings.gen.js";
 import { NUMBERS_PER_PERCENT, isStrictNamespaceUri, percentageSpelling, toTransitionalNamespaceUri, transitionalSlotEncoding } from "./transitionalSpelling.js";
 import { roundHalfAwayFromZero, universalMeasureAs } from "./universalMeasure.js";
-import { NAMESPACES, OOXML_NAMESPACE_SCOPE, cloneElement, elementToXml, getChildElements, getLocalName, getNamespacePrefix, parseXml } from "./xmlParser.js";
+import { NAMESPACES, OOXML_NAMESPACE_SCOPE, WORDPROCESSINGML_NAMESPACE_URIS, cloneElement, elementToXml, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespacePrefix, parseXml, resolveAttributeNamespaceUri } from "./xmlParser.js";
 import { assertXmlResourceLimits } from "./xmlResourceLimits.js";
 import { getDocxXmlSafetyIssue } from "./xmlSafety.js";
-import { TaggedError } from "better-result";
+import { TaggedError, panic } from "better-result";
+import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
 //#region src/docx/verbatimCapture.ts
 /**
 * The one way to turn parsed markup into a string a rebuilt part replays.
@@ -75,14 +76,22 @@ const originOf = (element, inherited) => {
 	});
 	return TRANSITIONAL_URIS.has(uri) ? "transitional" : inherited;
 };
-const convertAttributes = (element, namespaceUri, localName, convertValues) => {
+/** A same-local-name extension attribute is not a slot in the element's vocabulary. */
+const attributeSlotEncoding = (element, name) => {
+	if (getNamespacePrefix(name) !== null) {
+		const attributeUri = resolveAttributeNamespaceUri(element, name);
+		if (attributeUri === void 0 || element.namespaceUri === void 0 || toTransitionalNamespaceUri(attributeUri) !== toTransitionalNamespaceUri(element.namespaceUri)) return void 0;
+	}
+	return transitionalSlotEncoding(element.namespaceUri, getLocalName(element.name), getLocalName(name));
+};
+const convertAttributes = (element, namespaceUri, convertValues) => {
 	const attributes = element.attributes ?? {};
 	let converted;
 	for (const [name, raw] of Object.entries(attributes)) {
 		if (typeof raw !== "string") continue;
 		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)));
+		else if (convertValues) next = transitionalValue(raw, namespaceUri, attributeSlotEncoding(element, name));
 		if (next === raw) continue;
 		converted ??= { ...attributes };
 		converted[name] = next;
@@ -99,7 +108,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 = element.attributes ? convertAttributes(element, namespaceUri, localName, origin === "strict") : void 0;
+	const attributes = element.attributes ? convertAttributes(element, namespaceUri, 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);
@@ -363,5 +372,39 @@ const createCapturedXmlSanitizer = (options) => {
 		return sanitized;
 	};
 };
+const STRICT_BY_TRANSITIONAL = new Map([...TRANSITIONAL_NAMESPACE_BY_STRICT_URI].map(([strict, transitional]) => [transitional, strict]));
+const strictPercentage = (value, unit) => /^-?\d+(?:\.\d+)?$/u.test(value) ? `${Number(value) / NUMBERS_PER_PERCENT[unit]}%` : value;
+/** Translate generated markup by namespace/slot, never by a user-text replacement. */
+const strictElement = (element) => {
+	const localName = getLocalName(element.name);
+	for (const [name, value] of Object.entries(element.attributes ?? {})) {
+		if (typeof value !== "string") continue;
+		if (name === "xmlns" || name.startsWith("xmlns:")) {
+			element.attributes[name] = STRICT_BY_TRANSITIONAL.get(value) ?? value;
+			continue;
+		}
+		if (localName === "graphicData" && toTransitionalNamespaceUri(element.namespaceUri ?? "") === NAMESPACES.a && name === "uri") {
+			element.attributes[name] = STRICT_BY_TRANSITIONAL.get(value) ?? value;
+			continue;
+		}
+		const encoding = attributeSlotEncoding(element, name);
+		if (encoding?.percent && (!encoding.measure || getAttributeByNamespaceUri(element, WORDPROCESSINGML_NAMESPACE_URIS, "type") === "pct")) element.attributes[name] = strictPercentage(value, encoding.percent);
+	}
+	const encoding = transitionalSlotEncoding(element.namespaceUri, localName);
+	for (const child of element.elements ?? []) if (child.type === "element") strictElement(child);
+	else if (child.type === "text" && typeof child.text === "string" && encoding?.percent) child.text = strictPercentage(child.text, encoding.percent);
+};
+/** Serialize a generated, scope-bound block in the source part's profile. */
+const cloneSourceProfileTree = (element) => cloneElement(element, {
+	...element.attributes === void 0 ? {} : { attributes: { ...element.attributes } },
+	...element.elements === void 0 ? {} : { elements: element.elements.map(cloneSourceProfileTree) }
+});
+const captureSourceProfileXml = (element, conformance) => {
+	const owned = cloneSourceProfileTree(element);
+	if (conformance === DOCX_CONFORMANCE_CLASSES.STRICT) strictElement(owned);
+	const xml = elementToXml(owned);
+	if (!isSafeCapturedXmlDocument(xml)) panic("Generated source-profile markup is unsafe.");
+	return xml;
+};
 //#endregion
-export { UntranslatableStrictNamespaceError, captureVerbatimXml, createCapturedXmlSanitizer, isSafeCapturedXmlDocument };
+export { UntranslatableStrictNamespaceError, captureSourceProfileXml, captureVerbatimXml, createCapturedXmlSanitizer, isSafeCapturedXmlDocument };

package/dist/i18n/messages/ar.gen.d.ts

@@ -0,0 +1,5 @@
+import { FolioMessages } from "../messages.js";
+//#region src/i18n/messages/ar.gen.d.ts
+declare const messages: FolioMessages;
+//#endregion
+export { messages as default, messages };