@stll/folio-core 0.54.1 → 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
@@ -16,11 +22,23 @@ type AttributeValueSpan = {
   end: number;
 };
 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. */
 declare const rewriteStreamingXmlDecimalAttributes: (xml: string, visitOpenTag: OpenTagVisitor) => {
   status: "rewritten";
@@ -28,5 +46,17 @@ declare const rewriteStreamingXmlDecimalAttributes: (xml: string, visitOpenTag:
 } | {
   status: "unsupported";
 };
+/** Visit identity attributes and namespace bindings without building an XML tree. */
+declare const scanStreamingXmlNumericIdAttributes: (xml: string, visitOpenTag: OpenTagScanVisitor) => {
+  status: "unsupported";
+} | {
+  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, rewriteStreamingXmlDecimalAttributes };
+export { getXmlSourceRange, parseStreamingXml, parseStreamingXmlWithIdentityVisitor, parseStreamingXmlWithSourceRanges, rewriteStreamingXmlDecimalAttributes, scanStreamingXmlElements, scanStreamingXmlNumericIdAttributes };

package/dist/docx/streamingXmlParser.js

@@ -1,6 +1,10 @@
 import { EMPTY_NAMESPACE_SCOPE, attachXmlNamespaceContext } from "./xmlNamespaceContext.js";
 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: "'",
@@ -8,19 +12,36 @@ const BUILT_IN_ENTITIES = {
 	lt: "<",
 	quot: "\""
 };
-const parseStreamingXmlInternal = (xml, visitOpenTag, inheritedNamespaceScope = EMPTY_NAMESPACE_SCOPE) => {
+const parseStreamingXmlInternal = (options) => {
+	const { xml, inheritedNamespaceScope = EMPTY_NAMESPACE_SCOPE } = 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,
+		close: 0,
+		spanMode,
+		retainAttribute: options.mode === "attributes" ? options.retainAttribute : void 0
+	};
 	const root = { elements: [] };
 	const stack = [];
 	const replacements = [];
 	let cursor = 0;
 	let mergeAdjacentText = false;
+	const acceptText = (text, merge) => {
+		if (options.mode === "tree") return appendText(text, stack, merge);
+		const decoded = decodeXmlEntities(normalizeLineEndings(text));
+		return decoded !== null && (stack.length > 0 || decoded.trim().length === 0);
+	};
 	while (cursor < xml.length) {
 		const open = xml.indexOf("<", cursor);
 		if (open === -1) {
-			if (!appendText(xml.slice(cursor), stack, mergeAdjacentText)) return { status: "unsupported" };
+			if (!acceptText(xml.slice(cursor), mergeAdjacentText)) return { status: "unsupported" };
 			break;
 		}
-		if (open > cursor && !appendText(xml.slice(cursor, open), stack, mergeAdjacentText)) return { status: "unsupported" };
+		if (open > cursor && !acceptText(xml.slice(cursor, open), mergeAdjacentText)) return { status: "unsupported" };
 		if (open > cursor) mergeAdjacentText = true;
 		if (xml.startsWith("<!--", open)) {
 			const close = xml.indexOf("-->", open + 4);
@@ -30,7 +51,8 @@ const parseStreamingXmlInternal = (xml, visitOpenTag, inheritedNamespaceScope =
 		}
 		if (xml.startsWith("<![CDATA[", open)) {
 			const close = xml.indexOf("]]>", open + 9);
-			if (close === -1 || !appendRawText(normalizeLineEndings(xml.slice(open + 9, close)), stack)) return { status: "unsupported" };
+			const text = normalizeLineEndings(xml.slice(open + 9, close));
+			if (close === -1 || !(options.mode === "tree" ? appendRawText(text, stack) : stack.length > 0 || text.trim().length === 0)) return { status: "unsupported" };
 			cursor = close + 3;
 			mergeAdjacentText = false;
 			continue;
@@ -49,15 +71,29 @@ const parseStreamingXmlInternal = (xml, visitOpenTag, inheritedNamespaceScope =
 			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;
 		}
-		const parsedTag = parseOpenTag(xml, open + 1, close, visitOpenTag !== void 0);
+		openTagOptions.start = open + 1;
+		openTagOptions.close = close;
+		const parsedTag = parseOpenTag(openTagOptions);
 		if (parsedTag.status === "unsupported") return parsedTag;
 		const parent = stack.at(-1)?.element;
-		attachXmlNamespaceContext(parsedTag.element, parent === void 0 ? inheritedNamespaceScope : parent.namespaceScope);
-		const rewritten = visitOpenTag?.(parsedTag.element, parsedTag.attributeValueSpans ?? /* @__PURE__ */ new Map());
+		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);
 			if (!span) return { status: "unsupported" };
@@ -66,14 +102,21 @@ const parseStreamingXmlInternal = (xml, visitOpenTag, inheritedNamespaceScope =
 				value
 			});
 		}
-		appendElement(parent ?? root, parsedTag.element);
+		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;
 	}
@@ -89,15 +132,48 @@ const parseStreamingXmlInternal = (xml, visitOpenTag, inheritedNamespaceScope =
 *   fragment captured out of a part whose root declared them.
 */
 const parseStreamingXml = (xml, inheritedNamespaceScope = EMPTY_NAMESPACE_SCOPE) => {
-	const parsed = parseStreamingXmlInternal(xml, void 0, inheritedNamespaceScope);
+	const parsed = parseStreamingXmlInternal({
+		xml,
+		mode: "tree",
+		inheritedNamespaceScope
+	});
+	return parsed.status === "parsed" ? {
+		status: "parsed",
+		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({
+		xml,
+		mode: "tree",
+		visitOpenTag
+	});
+	return parsed.status === "parsed" ? {
+		status: "parsed",
+		value: parsed.value
+	} : parsed;
+};
 /** Rewrite selected decimal attribute values while preserving every other source byte. */
 const rewriteStreamingXmlDecimalAttributes = (xml, visitOpenTag) => {
-	const parsed = parseStreamingXmlInternal(xml, visitOpenTag);
+	const parsed = parseStreamingXmlInternal({
+		xml,
+		mode: "attributes",
+		visitOpenTag
+	});
 	if (parsed.status === "unsupported") return parsed;
 	const chunks = [];
 	let cursor = 0;
@@ -112,15 +188,42 @@ const rewriteStreamingXmlDecimalAttributes = (xml, visitOpenTag) => {
 		value: chunks.join("")
 	};
 };
-const parseOpenTag = (xml, start, close, captureAttributeSpans) => {
+/** Visit identity attributes and namespace bindings without building an XML tree. */
+const scanStreamingXmlNumericIdAttributes = (xml, visitOpenTag) => {
+	const parsed = parseStreamingXmlInternal({
+		xml,
+		mode: "attributes",
+		visitOpenTag,
+		retainAttribute: ({ attributeName, elementName }) => {
+			if (attributeName === "xmlns" || attributeName.startsWith("xmlns:")) return true;
+			return isOoxmlNumericIdAttributeName({
+				elementName,
+				attributeName
+			});
+		}
+	});
+	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;
-	const attributeValueSpans = captureAttributeSpans ? /* @__PURE__ */ new Map() : void 0;
+	let attributeValueSpans;
 	let selfClosing = false;
 	while (cursor < close) {
 		cursor = skipWhitespace(xml, cursor, close);
@@ -146,12 +249,23 @@ const parseOpenTag = (xml, start, close, captureAttributeSpans) => {
 		if (cursor === -1 || cursor > close) return { status: "unsupported" };
 		const decoded = decodeXmlEntities(normalizeLineEndings(xml.slice(valueStart, cursor)));
 		if (decoded === null) return { status: "unsupported" };
-		attributes ??= {};
-		attributes[attributeName] = decoded;
-		attributeValueSpans?.set(attributeName, {
-			start: valueStart,
-			end: cursor
-		});
+		if (retainAttribute === void 0 || retainAttribute({
+			attributeName,
+			elementName: name
+		})) {
+			attributes ??= {};
+			attributes[attributeName] = decoded;
+			if (spanMode === "all" || spanMode === "identities" && isOoxmlNumericIdAttributeName({
+				elementName: name,
+				attributeName
+			})) {
+				attributeValueSpans ??= /* @__PURE__ */ new Map();
+				attributeValueSpans.set(attributeName, {
+					start: valueStart,
+					end: cursor
+				});
+			}
+		}
 		cursor += 1;
 	}
 	const element = {
@@ -163,6 +277,7 @@ const parseOpenTag = (xml, start, close, captureAttributeSpans) => {
 		status: "parsed",
 		element,
 		name,
+		nameEnd,
 		selfClosing,
 		attributeValueSpans
 	};
@@ -289,4 +404,4 @@ const isUnsafePropertyName = (name) => {
 	}
 };
 //#endregion
-export { parseStreamingXml, rewriteStreamingXmlDecimalAttributes };
+export { getXmlSourceRange, parseStreamingXml, parseStreamingXmlWithIdentityVisitor, parseStreamingXmlWithSourceRanges, rewriteStreamingXmlDecimalAttributes, scanStreamingXmlElements, scanStreamingXmlNumericIdAttributes };