@stll/folio-core 0.54.0 → 0.54.2

package/dist/docx/rasterMime.js

@@ -0,0 +1,116 @@
+//#region src/docx/rasterMime.ts
+const RASTER_SIGNATURES = [
+	{
+		mimeType: "image/png",
+		chunks: [{
+			offset: 0,
+			bytes: [
+				137,
+				80,
+				78,
+				71
+			]
+		}]
+	},
+	{
+		mimeType: "image/jpeg",
+		chunks: [{
+			offset: 0,
+			bytes: [255, 216]
+		}]
+	},
+	{
+		mimeType: "image/gif",
+		chunks: [{
+			offset: 0,
+			bytes: [
+				71,
+				73,
+				70,
+				56
+			]
+		}]
+	},
+	{
+		mimeType: "image/bmp",
+		chunks: [{
+			offset: 0,
+			bytes: [66, 77]
+		}]
+	},
+	{
+		mimeType: "image/webp",
+		chunks: [{
+			offset: 0,
+			bytes: [
+				82,
+				73,
+				70,
+				70
+			]
+		}, {
+			offset: 8,
+			bytes: [
+				87,
+				69,
+				66,
+				80
+			]
+		}]
+	},
+	{
+		mimeType: "image/tiff",
+		chunks: [{
+			offset: 0,
+			bytes: [
+				73,
+				73,
+				42,
+				0
+			]
+		}]
+	},
+	{
+		mimeType: "image/tiff",
+		chunks: [{
+			offset: 0,
+			bytes: [
+				77,
+				77,
+				0,
+				42
+			]
+		}]
+	},
+	{
+		mimeType: "image/tiff",
+		chunks: [{
+			offset: 0,
+			bytes: [
+				73,
+				73,
+				43,
+				0
+			]
+		}]
+	},
+	{
+		mimeType: "image/tiff",
+		chunks: [{
+			offset: 0,
+			bytes: [
+				77,
+				77,
+				0,
+				43
+			]
+		}]
+	}
+];
+const RASTER_MIME_TYPES = new Set(RASTER_SIGNATURES.map(({ mimeType }) => mimeType));
+const detectRasterMimeType = (data) => {
+	const bytes = new Uint8Array(data);
+	return RASTER_SIGNATURES.find(({ chunks }) => chunks.every(({ offset, bytes: signature }) => signature.every((byte, index) => bytes[offset + index] === byte)))?.mimeType;
+};
+//#endregion
+export { RASTER_MIME_TYPES, detectRasterMimeType };

package/dist/docx/replyToComment.js

@@ -1,10 +1,16 @@
+import { allocateCommentId, seedCommentIdAbove } from "../prosemirror/commentIdAllocator.js";
 import { generateHexId } from "../utils/hexId.js";
 //#region src/docx/replyToComment.ts
-const nextCommentId = (comments) => {
-	let max = 0;
-	for (const comment of comments) if (comment.id > max) max = comment.id;
-	return max + 1;
-};
+/**
+* Create a threaded reply to an existing comment.
+*
+* Produces a new `Comment` whose `parentId` points at the target comment and
+* whose last paragraph carries a fresh `w14:paraId`, and guarantees the parent
+* has a paraId too — the two ids Word uses to link a reply to its thread in
+* `commentsExtended.xml` (`w15:paraId` / `w15:paraIdParent`). The reply's
+* `document.xml` range markers are synthesized at save time by
+* {@link applyReplyThreadMarkers}, so no anchor work is needed here.
+*/
 const usedParaIds = (comments) => {
 	const ids = /* @__PURE__ */ new Set();
 	for (const comment of comments) for (const paragraph of comment.content) if (paragraph.paraId) ids.add(paragraph.paraId.toUpperCase());
@@ -32,6 +38,7 @@ const createReply = (comments, parentCommentId, input) => {
 	const threadRootId = parent.parentId ?? parent.id;
 	const rootLastParagraph = ((comments.find((comment) => comment.id === threadRootId) ?? parent).content ?? []).at(-1);
 	if (!rootLastParagraph) return null;
+	for (const { id } of comments) seedCommentIdAbove(id);
 	const used = usedParaIds(comments);
 	if (!rootLastParagraph.paraId) rootLastParagraph.paraId = freshParaId(used);
 	const replyParagraph = {
@@ -48,7 +55,7 @@ const createReply = (comments, parentCommentId, input) => {
 		}]
 	};
 	return {
-		id: nextCommentId(comments),
+		id: allocateCommentId(),
 		author: input.author,
 		date: input.date ?? (/* @__PURE__ */ new Date()).toISOString(),
 		parentId: threadRootId,

package/dist/docx/rezip.js

@@ -33,7 +33,7 @@ import { serializeThemeXml } from "./serializer/themeSerializer.js";
 import { hasCanonicalWordprocessingPrefixes } from "./wordprocessingPrefixes.js";
 import { WORDPROCESSINGML_NAMESPACE_URIS, findChild, findChildByNamespaceUri, findChildrenByNamespaceUri, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespaceUri, matchesName, parseXml, parseXmlDocument } from "./xmlParser.js";
 import { TaggedError, panic } from "better-result";
-import { escapeXmlAttribute, escapeXmlText, validateDocxPackage } from "@stll/docx-core";
+import { assertValidOoxmlNumericIds, escapeXmlAttribute, escapeXmlText, validateDocxPackage } from "@stll/docx-core";
 import { mintRelationshipId } from "@stll/docx-core/model";
 import JSZip from "jszip";
 //#region src/docx/rezip.ts
@@ -529,12 +529,19 @@ async function processNewHyperlinks(parts, zip, compressionLevel) {
 */
 const normalizePackageIdsInZip = async (zip, compressionLevel) => {
 	const xmlParts = /* @__PURE__ */ new Map();
-	for (const [path, file] of Object.entries(zip.files)) if (!file.dir && path.startsWith("word/") && path.endsWith(".xml")) xmlParts.set(path, await file.async("text"));
+	for (const [path, file] of Object.entries(zip.files)) if (!file.dir && path.startsWith("word/") && path.endsWith(".xml")) {
+		const xml = await file.async("text");
+		assertValidOoxmlNumericIds(xml, path);
+		xmlParts.set(path, xml);
+	}
 	const normalizedParts = normalizeParaIdRangeInXmlParts(normalizeRevisionIdsInXmlParts(xmlParts));
-	for (const [path, xml] of normalizedParts) if (xml !== xmlParts.get(path)) zip.file(path, xml, {
-		compression: "DEFLATE",
-		compressionOptions: { level: compressionLevel }
-	});
+	for (const [path, xml] of normalizedParts) if (xml !== xmlParts.get(path)) {
+		assertValidOoxmlNumericIds(xml, path);
+		zip.file(path, xml, {
+			compression: "DEFLATE",
+			compressionOptions: { level: compressionLevel }
+		});
+	}
 };
 const EXTENDED_PROPERTIES_PATH = "docProps/app.xml";
 /**
@@ -1600,7 +1607,7 @@ const notePartXmlFor = ({ patch, originalXml, replacementXml, hasDirtyParagraph,
 		return null;
 	};
 	switch (patch.type) {
-		case "patched": return patch.xml === originalXml ? keepOriginal() : patch.xml;
+		case "patched": return patch.xml === originalXml ? null : patch.xml;
 		case "refused": switch (patch.reason) {
 			case "comment-range-balance": return replacementXml;
 			case "unroutable-paragraph": return keepOriginal();

package/dist/docx/selectiveSave.js

@@ -4,6 +4,7 @@ import { hasUnsynthesizedReplyRanges } from "./commentReplyMarkers.js";
 import { detectDocxConformanceClass } from "./conformance.js";
 import { validateFolioDocumentModel } from "./modelValidation.js";
 import { parseNumbering } from "./numberingParser.js";
+import { normalizeImportedNumericIds } from "./numericIdNormalization.js";
 import { isUnsafePackagePath } from "./packageParts.js";
 import { RELATIONSHIP_TYPES } from "./relsParser.js";
 import { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_PART_LOWER, addCommentsExtendedOverride, addCommentsExtendedRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedInlineResources, updateCoreProperties, withoutAttachedTemplate } from "./rezip.js";
@@ -203,6 +204,15 @@ async function attemptSelectiveSave(doc, originalBuffer, options) {
 	try {
 		const zip = await (await import("jszip")).default.loadAsync(originalBuffer);
 		for (const [path, file] of Object.entries(zip.files)) if (!file.dir && isUnsafePackagePath(path)) return null;
+		if (originalBuffer !== doc.originalBuffer) {
+			const sourceParts = /* @__PURE__ */ new Map();
+			for (const [path, file] of Object.entries(zip.files)) {
+				const lowerPath = path.toLowerCase();
+				if (file.dir || !lowerPath.startsWith("word/") || !lowerPath.endsWith(".xml")) continue;
+				sourceParts.set(path, await file.async("text"));
+			}
+			for (const [path, xml] of normalizeImportedNumericIds(sourceParts)) if (xml !== sourceParts.get(path)) zip.file(path, xml);
+		}
 		const updates = /* @__PURE__ */ new Map();
 		if (changedParaIds.size > 0 || structuralChange) {
 			const docXmlFile = zip.file("word/document.xml");

package/dist/docx/serializer/partNamespaces.js

@@ -1,6 +1,6 @@
 import { toTransitionalNamespaceUri } from "../transitionalSpelling.js";
 import { TaggedError } from "better-result";
-import { escapeXmlAttribute } from "@stll/docx-core";
+import { assertValidOoxmlNumericIds, escapeXmlAttribute } from "@stll/docx-core";
 import { OOXML_NS } from "@stll/docx-utils";
 //#region src/docx/serializer/partNamespaces.ts
 /**
@@ -322,7 +322,9 @@ const serializePartElement = ({ partPath, rootName, rootAttributes, baselinePref
 	const attributes = orderedPrefixes.map((prefix) => `xmlns:${prefix}="${escapeXmlAttribute(bindings.get(prefix))}"`);
 	const ignorable = orderedPrefixes.filter((prefix) => NAMESPACE_TABLE.get(prefix)?.ignorable === true);
 	if (ignorable.length > 0) attributes.push(`mc:Ignorable="${ignorable.join(" ")}"`);
-	return `${openingTag} ${attributes.join(" ")}>${body}</${rootName}>`;
+	const xml = `${openingTag} ${attributes.join(" ")}>${body}</${rootName}>`;
+	assertValidOoxmlNumericIds(xml, partPath);
+	return xml;
 };
 //#endregion
 export { OOXML_NAMESPACES, UnboundNamespacePrefixError, readRootNamespaceBindings, serializePartElement };

package/dist/docx/serializer/runSerializer.js

@@ -16,7 +16,7 @@ import { serializeTextFormatting } from "./textFormattingSerializer.js";
 import { getSingularRunPropertyChange, serializeTrackedChangeAttributes } from "./trackedChangeAttributes.js";
 import { intAttr } from "./xmlUtils.js";
 import { panic } from "better-result";
-import { escapeXmlAttribute, escapeXmlText, requiresXmlSpacePreserve } from "@stll/docx-core";
+import { escapeXmlAttribute, escapeXmlText, isValidOoxmlNumericId, requiresXmlSpacePreserve } from "@stll/docx-core";
 import { SCHEME_COLOR_VALUE_BY_THEME_COLOR, knownThemeColor, presetLineDashToken } from "@stll/docx-core/model";
 //#region src/docx/serializer/runSerializer.ts
 /**
@@ -32,7 +32,7 @@ import { SCHEME_COLOR_VALUE_BY_THEME_COLOR, knownThemeColor, presetLineDashToken
 */
 /**
 * Auto-incrementing counter for generating unique image/shape IDs.
-* Used as a fallback when `image.id` or `shape.id` is undefined (e.g., pasted images).
+* Used when a model id cannot identify a DrawingML object (e.g., a VML lexical id).
 * Starts high (100000) to avoid collisions with IDs parsed from existing DOCX content.
 */
 let nextAutoId = 1e5;
@@ -43,9 +43,10 @@ let nextAutoId = 1e5;
 function resetAutoIdCounter() {
 	nextAutoId = 1e5;
 }
-/** Get a unique positive integer ID, using the provided value or generating one */
+/** Get an unsigned integer ID, using the provided value or generating one */
 function getUniqueId(id) {
-	if (id !== void 0 && id !== "" && id !== 0) return String(id);
+	if (id !== void 0 && isValidOoxmlNumericId(id, "unsigned32")) return String(id);
+	if (!isValidOoxmlNumericId(nextAutoId, "unsigned32")) panic("DrawingML generated id space is exhausted.");
 	return String(nextAutoId++);
 }
 function serializeRunPropertyChange(change) {

package/dist/docx/serializer/trackedChangeAttributes.js

@@ -1,6 +1,6 @@
 import { DATE_UTC_ATTRIBUTE } from "../trackedChangeInfo.js";
 import { panic } from "better-result";
-import { escapeXmlAttribute } from "@stll/docx-core";
+import { assertValidOoxmlNumericId, escapeXmlAttribute } from "@stll/docx-core";
 import { normalizeRevisionId } from "@stll/docx-core/model";
 //#region src/docx/serializer/trackedChangeAttributes.ts
 /** Enforces the singular `w:rPrChange` child in a run-property container. */
@@ -14,6 +14,12 @@ const getSingularRunPropertyChange = (propertyChanges) => {
 };
 /** Normalized, unescaped attributes in schema order for an XML element or string serializer. */
 const trackedChangeAttributeEntries = (info) => {
+	assertValidOoxmlNumericId({
+		value: info.id,
+		partPath: "word/*.xml",
+		elementName: "tracked change",
+		attributeName: "w:id"
+	});
 	const author = typeof info.author === "string" ? info.author.trim() : "";
 	const date = typeof info.date === "string" ? info.date.trim() : "";
 	const rawUtcDate = info.utcDate;

package/dist/docx/server/build.js

@@ -1,4 +1,7 @@
+import { mintBookmarkId, reserveBookmarkIds } from "../bookmarkIds.js";
+import { mintEndnoteId } from "../noteIds.js";
 import { TaggedError } from "better-result";
+import { assertValidOoxmlNumericId } from "@stll/docx-core";
 //#region src/docx/server/build.ts
 /**
 * Headless document builders.
@@ -103,10 +106,18 @@ const hyperlink = ({ text, formatting, tooltip, href, anchor }) => ({
 		...formatting
 	})]
 });
-let nextBookmarkId = 0;
 /** `content` wrapped in a named bookmark, the target of `hyperlink({ anchor })`. */
 const bookmark = ({ name, content, id }) => {
-	const bookmarkId = id ?? nextBookmarkId++;
+	if (id !== void 0) {
+		assertValidOoxmlNumericId({
+			value: id,
+			partPath: "word/document.xml",
+			elementName: "w:bookmarkStart",
+			attributeName: "w:id"
+		});
+		reserveBookmarkIds([id]);
+	}
+	const bookmarkId = id ?? mintBookmarkId();
 	const start = {
 		type: "bookmarkStart",
 		id: bookmarkId,
@@ -225,7 +236,7 @@ const table = ({ header, rows, columnWidths, headerShading, repeatHeader = true
 const endnote = (doc, content) => {
 	const endnotes = doc.package.endnotes ?? [];
 	doc.package.endnotes = endnotes;
-	const id = Math.max(0, ...endnotes.map((note) => note.id)) + 1;
+	const id = mintEndnoteId(endnotes.map((note) => note.id));
 	const note = {
 		type: "endnote",
 		id,

package/dist/docx/server/createBilingualDocument.js

@@ -1,5 +1,7 @@
 import { deterministicHexId } from "../../utils/hexId.js";
+import { createBookmarkIdAllocator } from "../bookmarkIds.js";
 import { createBuiltInStyleIndex, resolveHeadingLevel } from "../builtInStyles.js";
+import { createNumberingIdAllocator } from "../numberingIds.js";
 import { mergeParagraphNumbering, paragraphNumberingReference, paragraphNumberingReferenceId } from "../numberingReference.js";
 import { getParagraphText } from "../paragraphParser.js";
 import { cloneParagraphWithoutPropertySource } from "../paragraphPropertySource.js";
@@ -271,8 +273,8 @@ const createNumberingCloner = ({ numbering, styleById, warnings }) => {
 	const nums = numbering?.nums ?? [];
 	const abstractById = new Map(abstractNums.map((item) => [item.abstractNumId, item]));
 	const numById = new Map(nums.map((item) => [item.numId, item]));
-	let nextAbstractNumId = Math.max(0, ...abstractNums.map((item) => item.abstractNumId)) + 1;
-	let nextNumId = Math.max(0, ...nums.map((item) => item.numId)) + 1;
+	const abstractIds = createNumberingIdAllocator("abstract", abstractById.keys());
+	const instanceIds = createNumberingIdAllocator("num", numById.keys());
 	const clonedAbstract = /* @__PURE__ */ new Map();
 	const clonedNum = /* @__PURE__ */ new Map();
 	/**
@@ -291,10 +293,9 @@ const createNumberingCloner = ({ numbering, styleById, warnings }) => {
 		const { numStyleLink: _numStyleLink, styleLink: _styleLink, ...rest } = resolved;
 		const clone = {
 			...rest,
-			abstractNumId: nextAbstractNumId,
+			abstractNumId: abstractIds.next(),
 			levels: structuredClone(resolved.levels)
 		};
-		nextAbstractNumId += 1;
 		clonedAbstract.set(sourceId, clone);
 		return clone;
 	};
@@ -326,10 +327,9 @@ const createNumberingCloner = ({ numbering, styleById, warnings }) => {
 		if (!abstract) warnings.push(`Numbering instance ${numId} references abstractNum ${source.abstractNumId}, which is not defined; its copy shares the source counters.`);
 		const clone = {
 			...source,
-			numId: nextNumId,
+			numId: instanceIds.next(),
 			abstractNumId: abstract ? abstract.abstractNumId : source.abstractNumId
 		};
-		nextNumId += 1;
 		clonedNum.set(numId, clone);
 		return clone.numId;
 	};
@@ -411,7 +411,7 @@ const cloneParagraphForTarget = (paragraph, targetParaId, styleCloner, cloner, b
 	return cloned;
 };
 const createBookmarkIdMinter = (source) => {
-	let nextId = 0;
+	const reservedIds = [];
 	const remapped = /* @__PURE__ */ new Map();
 	const visit = (value, seen) => {
 		if (typeof value !== "object" || value === null || seen.has(value)) return;
@@ -423,15 +423,16 @@ const createBookmarkIdMinter = (source) => {
 		const record = value;
 		if (record["type"] === "bookmarkStart" || record["type"] === "bookmarkEnd") {
 			const id = record["id"];
-			if (typeof id === "number") nextId = Math.max(nextId, id + 1);
+			if (typeof id === "number") reservedIds.push(id);
 		}
 		Object.values(record).forEach((item) => visit(item, seen));
 	};
 	visit(source, /* @__PURE__ */ new Set());
+	const allocator = createBookmarkIdAllocator(reservedIds);
 	return { mint: (sourceId) => {
 		const existing = remapped.get(sourceId);
 		if (existing !== void 0) return existing;
-		const id = nextId++;
+		const id = allocator.next();
 		remapped.set(sourceId, id);
 		return id;
 	} };

package/dist/docx/streamingXmlParser.d.ts

@@ -16,11 +16,14 @@ type AttributeValueSpan = {
   end: number;
 };
 type OpenTagVisitor = (element: XmlElement, attributeValueSpans: ReadonlyMap<string, AttributeValueSpan>) => ReadonlyMap<string, string> | null;
+type OpenTagScanVisitor = (...args: Parameters<OpenTagVisitor>) => null;
 /**
  * @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 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 +31,11 @@ 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";
+};
 //#endregion
-export { parseStreamingXml, rewriteStreamingXmlDecimalAttributes };
+export { parseStreamingXml, parseStreamingXmlWithIdentityVisitor, rewriteStreamingXmlDecimalAttributes, scanStreamingXmlNumericIdAttributes };

package/dist/docx/streamingXmlParser.js

@@ -1,5 +1,6 @@
 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 BUILT_IN_ENTITIES = {
 	amp: "&",
@@ -8,19 +9,35 @@ 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";
+	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 +47,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;
@@ -53,11 +71,15 @@ const parseStreamingXmlInternal = (xml, visitOpenTag, inheritedNamespaceScope =
 			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);
+		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,7 +88,7 @@ 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({
@@ -89,15 +111,35 @@ 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 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,7 +154,23 @@ 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;
+};
+const parseOpenTag = ({ xml, start, close, spanMode, retainAttribute }) => {
 	let cursor = skipWhitespace(xml, start, close);
 	const nameStart = cursor;
 	cursor = scanName(xml, cursor, close);
@@ -120,7 +178,7 @@ const parseOpenTag = (xml, start, close, captureAttributeSpans) => {
 	const name = xml.slice(nameStart, 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 +204,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 = {
@@ -289,4 +358,4 @@ const isUnsafePropertyName = (name) => {
 	}
 };
 //#endregion
-export { parseStreamingXml, rewriteStreamingXmlDecimalAttributes };
+export { parseStreamingXml, parseStreamingXmlWithIdentityVisitor, rewriteStreamingXmlDecimalAttributes, scanStreamingXmlNumericIdAttributes };

package/dist/docx/unzip.d.ts

@@ -99,6 +99,8 @@ type UnzipDocxBehavior = {
  * @returns Promise resolving to extracted content
  */
 declare function unzipDocx(buffer: ArrayBuffer, options?: DocxUnzipOptions, { verifyUnreadEntries }?: UnzipDocxBehavior): Promise<RawDocxContent>;
+/** Keep extracted projections and the source ZIP aligned after parser normalization. */
+declare const replaceRawDocxXmlParts: (content: RawDocxContent, parts: ReadonlyMap<string, string>) => Promise<void>;
 declare function getEntryUncompressedSize(file: JSZip.JSZipObject): number | null;
 /**
  * Get a list of all files in the DOCX
@@ -160,4 +162,4 @@ declare function getContentSummary(content: RawDocxContent): {
   totalFiles: number;
 };
 //#endregion
-export { DocxSecurityError, DocxUnzipLimits, DocxUnzipOptions, RawDocxContent, UnzipDocxBehavior, extractFile, getContentSummary, getEntryUncompressedSize, getFileList, getMediaMimeType, hasFile, mediaToDataUrl, unzipDocx };
+export { DocxSecurityError, DocxUnzipLimits, DocxUnzipOptions, RawDocxContent, UnzipDocxBehavior, extractFile, getContentSummary, getEntryUncompressedSize, getFileList, getMediaMimeType, hasFile, mediaToDataUrl, replaceRawDocxXmlParts, unzipDocx };