@stll/folio-core 0.42.0 → 0.44.0

package/dist/docx/parser.js

@@ -1,34 +1,39 @@
 import { toArrayBuffer } from "../utils/docxInput.js";
 import { loadFontsWithMapping } from "../utils/fontLoader.js";
 import { MAX_PACKAGE_TIFF_PIXELS, convertTiffToPngDataUrl, isTiffMimeType } from "../utils/tiffConverter.js";
+import { DUPLICATE_COMMENT_ID_WARNING, normalizeCommentIds } from "./commentIdNormalization.js";
 import { parseComments } from "./commentParser.js";
-import { normalizeCommentReferences } from "./commentReferenceNormalization.js";
+import { DANGLING_COMMENT_REFERENCE_WARNING, UNBALANCED_COMMENT_RANGE_WARNING, normalizeCommentReferences } from "./commentReferenceNormalization.js";
 import { detectDocxConformanceClass } from "./conformance.js";
 import { parseCoreProperties } from "./corePropertiesParser.js";
+import { countDanglingRelationshipReferences } from "./danglingRelationshipReferences.js";
 import { extractAllTemplateVariables, parseDocumentBody } from "./documentParser.js";
 import { normalizeDrawingIds } from "./drawingIdNormalization.js";
 import { DocxEncryptionError } from "./encryption/errors.js";
 import { parseFontTable } from "./fontTableParser.js";
 import { parseEndnotes, parseFootnotes } from "./footnoteParser.js";
 import { parseFooter, parseHeader } from "./headerFooterParser.js";
-import { normalizeHeaderFooterReferences } from "./headerFooterReferenceNormalization.js";
+import { DANGLING_FOOTER_REFERENCE_WARNING, DANGLING_HEADER_REFERENCE_WARNING, normalizeHeaderFooterReferences } from "./headerFooterReferenceNormalization.js";
 import { assignHeaderFooterVerbatimXml, refreshHeaderFooterVerbatimFingerprint } from "./headerFooterVerbatim.js";
 import { extractMetafileRaster, isMetafileMimeType } from "./metafileRaster.js";
 import { renderEmfSvg } from "./metafileSvg.js";
 import { DocxModelValidationError, formatDocumentModelIssues, validateFolioDocumentModel } from "./modelValidation.js";
 import { parseNumbering } from "./numberingParser.js";
-import { normalizeNumberingReferences } from "./numberingReferenceNormalization.js";
+import { UNNUMBERED_PARAGRAPH_WARNING, UNNUMBERED_STYLE_WARNING, normalizeNumberingReferences, normalizeStyleNumberingReferences } from "./numberingReferenceNormalization.js";
 import { assignDocumentParagraphPropertySourceContract } from "./paragraphPropertySource.js";
+import { createParseWarningCollector } from "./parseContext.js";
+import { formatParseWarnings } from "./parseWarningMessage.js";
 import { RELATIONSHIP_TYPES, parseRelationships, resolveRelativePath } from "./relsParser.js";
 import { normalizeRenderedPageBreakHints } from "./renderedPageBreakNormalization.js";
 import { parseSettings } from "./settingsParser.js";
 import { parseStylesPackage } from "./styleParser.js";
 import { applyThemeFontLang, parseTheme } from "./themeParser.js";
-import { normalizeTrackedMoveRanges } from "./trackedMoveRangeNormalization.js";
+import { UNBALANCED_MOVE_RANGE_WARNING, normalizeTrackedMoveRanges } from "./trackedMoveRangeNormalization.js";
 import { getMediaMimeType, mediaToDataUrl, unzipDocx } from "./unzip.js";
 import { enforcePackageVmlPreviewBudget } from "./vmlPreview.js";
 import { FOLIO_XML_RESOURCE_LIMITS } from "./xmlResourceLimits.js";
 import { TaggedError } from "better-result";
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/parser.ts
 /**
 * Main Parser Orchestrator - Unified parseDocx function
@@ -69,7 +74,7 @@ const sha256Hex = async (buffer) => {
 async function parseDocx(input, options = {}) {
 	const buffer = input instanceof ArrayBuffer ? input : await toArrayBuffer(input);
 	const { onProgress = () => {}, preloadFonts = true, parseHeadersFooters = true, parseNotes = true, detectVariables = true, password, unzipLimits, mediaResolver } = options;
-	const warnings = [];
+	const { context: parseContext, warnings: collectedWarnings } = createParseWarningCollector();
 	try {
 		const timeStage = (_name, fn) => fn();
 		const timeStageAsync = async (_name, fn) => await fn();
@@ -80,8 +85,11 @@ async function parseDocx(input, options = {}) {
 			password,
 			extractAllXml: false
 		}));
-		if (raw.wasEncrypted) warnings.push("Document was opened from password-protected storage; saving writes an unencrypted .docx file.");
-		warnings.push(...raw.warnings);
+		if (raw.wasEncrypted) parseContext.warn({ code: PARSE_WARNING_CODES.packageDecrypted });
+		for (const message of raw.warnings) parseContext.warn({
+			code: PARSE_WARNING_CODES.packageArchive,
+			detail: message
+		});
 		onProgress("Extracted DOCX", 10);
 		onProgress("Parsing relationships...", 10);
 		const rels = timeStage("relationships", () => raw.documentRels ? parseRelationships(raw.documentRels) : /* @__PURE__ */ new Map());
@@ -113,8 +121,8 @@ async function parseDocx(input, options = {}) {
 		onProgress("Parsing document body...", 40);
 		let documentBody = { content: [] };
 		timeStage("documentBody", () => {
-			if (raw.documentXml) documentBody = parseDocumentBody(raw.documentXml, styles, theme, numbering, rels, media);
-			else warnings.push("No document.xml found in DOCX");
+			if (raw.documentXml) documentBody = parseDocumentBody(raw.documentXml, styles, theme, numbering, rels, media, parseContext.scoped({ part: "word/document.xml" }));
+			else parseContext.warn({ code: PARSE_WARNING_CODES.documentPartMissing });
 		});
 		onProgress("Parsed document body", 55);
 		let headers;
@@ -130,13 +138,19 @@ async function parseDocx(input, options = {}) {
 		let endnotes;
 		if (parseNotes) {
 			onProgress("Parsing footnotes/endnotes...", 65);
-			const notes = timeStage("footnotesEndnotes", () => parseNotesContent(raw, styles, theme, numbering, rels, media));
+			const notes = timeStage("footnotesEndnotes", () => parseNotesContent(raw, styles, theme, numbering, rels, media, parseContext));
 			footnotes = notes.footnotes;
 			endnotes = notes.endnotes;
 			onProgress("Parsed footnotes/endnotes", 75);
 		} else onProgress("Skipping footnotes/endnotes", 75);
 		onProgress("Parsing comments...", 75);
-		const comments = timeStage("comments", () => parseComments(raw.commentsXml, styles, theme, rels, media, raw.commentsExtensibleXml, raw.commentsExtendedXml));
+		const commentsContext = parseContext.scoped({ part: "word/comments.xml" });
+		const comments = timeStage("comments", () => parseComments(raw.commentsXml, styles, theme, rels, media, raw.commentsExtensibleXml, raw.commentsExtendedXml, commentsContext));
+		const commentIdNormalization = normalizeCommentIds(comments);
+		if (commentIdNormalization.droppedDuplicateComments > 0) commentsContext.warn({
+			code: DUPLICATE_COMMENT_ID_WARNING,
+			count: commentIdNormalization.droppedDuplicateComments
+		});
 		if (comments.length > 0) documentBody.comments = comments;
 		normalizeDrawingIds({
 			documentBody,
@@ -162,15 +176,27 @@ async function parseDocx(input, options = {}) {
 			...footnotes !== void 0 ? { footnotes } : {},
 			...endnotes !== void 0 ? { endnotes } : {}
 		});
-		if (commentReferenceNormalization.removedDanglingReferences > 0) warnings.push(`Removed ${commentReferenceNormalization.removedDanglingReferences} dangling comment reference marker(s) whose comments.xml entries are missing.`);
-		if (commentReferenceNormalization.reanchoredUnbalancedRanges > 0) warnings.push(`Re-anchored ${commentReferenceNormalization.reanchoredUnbalancedRanges} unbalanced comment range marker(s) as point comments.`);
+		if (commentReferenceNormalization.removedDanglingReferences > 0) parseContext.warn({
+			code: DANGLING_COMMENT_REFERENCE_WARNING,
+			count: commentReferenceNormalization.removedDanglingReferences
+		});
+		if (commentReferenceNormalization.reanchoredUnbalancedRanges > 0) parseContext.warn({
+			code: UNBALANCED_COMMENT_RANGE_WARNING,
+			count: commentReferenceNormalization.reanchoredUnbalancedRanges
+		});
 		const headerFooterReferenceNormalization = normalizeHeaderFooterReferences({
 			documentBody,
 			...headers !== void 0 ? { headers } : {},
 			...footers !== void 0 ? { footers } : {}
 		});
-		if (headerFooterReferenceNormalization.removedDanglingHeaderReferences > 0) warnings.push(`Removed ${headerFooterReferenceNormalization.removedDanglingHeaderReferences} dangling header reference(s) whose header parts are missing.`);
-		if (headerFooterReferenceNormalization.removedDanglingFooterReferences > 0) warnings.push(`Removed ${headerFooterReferenceNormalization.removedDanglingFooterReferences} dangling footer reference(s) whose footer parts are missing.`);
+		if (headerFooterReferenceNormalization.removedDanglingHeaderReferences > 0) parseContext.warn({
+			code: DANGLING_HEADER_REFERENCE_WARNING,
+			count: headerFooterReferenceNormalization.removedDanglingHeaderReferences
+		});
+		if (headerFooterReferenceNormalization.removedDanglingFooterReferences > 0) parseContext.warn({
+			code: DANGLING_FOOTER_REFERENCE_WARNING,
+			count: headerFooterReferenceNormalization.removedDanglingFooterReferences
+		});
 		const numberingReferenceNormalization = normalizeNumberingReferences({
 			documentBody,
 			numbering,
@@ -179,7 +205,33 @@ async function parseDocx(input, options = {}) {
 			...footnotes !== void 0 ? { footnotes } : {},
 			...endnotes !== void 0 ? { endnotes } : {}
 		});
-		if (numberingReferenceNormalization.removedMissingNumberingReferences > 0) warnings.push(`Removed ${numberingReferenceNormalization.removedMissingNumberingReferences} numbering reference(s) whose numbering definitions are missing.`);
+		if (numberingReferenceNormalization.unnumberedDanglingReferences > 0) parseContext.warn({
+			code: UNNUMBERED_PARAGRAPH_WARNING,
+			count: numberingReferenceNormalization.unnumberedDanglingReferences
+		});
+		const styleNumberingNormalization = normalizeStyleNumberingReferences({
+			styles: styleDefinitions?.styles ?? [],
+			numbering
+		});
+		for (const styleId of styleNumberingNormalization.unnumberedStyleIds) parseContext.warn({
+			code: UNNUMBERED_STYLE_WARNING,
+			value: styleId,
+			at: `style "${styleId}"`
+		});
+		const danglingReferences = countDanglingRelationshipReferences({
+			content: documentBody.content,
+			relationships: rels
+		});
+		if (danglingReferences.drawings > 0) parseContext.warn({
+			code: PARSE_WARNING_CODES.danglingRelationshipId,
+			element: "w:drawing",
+			count: danglingReferences.drawings
+		});
+		if (danglingReferences.hyperlinks > 0) parseContext.warn({
+			code: PARSE_WARNING_CODES.danglingRelationshipId,
+			element: "w:hyperlink",
+			count: danglingReferences.hyperlinks
+		});
 		const trackedMoveRangeNormalization = normalizeTrackedMoveRanges({
 			documentBody,
 			...headers !== void 0 ? { headers } : {},
@@ -187,7 +239,10 @@ async function parseDocx(input, options = {}) {
 			...footnotes !== void 0 ? { footnotes } : {},
 			...endnotes !== void 0 ? { endnotes } : {}
 		});
-		if (trackedMoveRangeNormalization.removedUnbalancedMoveRangeMarkers > 0) warnings.push(`Removed ${trackedMoveRangeNormalization.removedUnbalancedMoveRangeMarkers} unbalanced tracked move range marker(s).`);
+		if (trackedMoveRangeNormalization.removedUnbalancedMoveRangeMarkers > 0) parseContext.warn({
+			code: UNBALANCED_MOVE_RANGE_WARNING,
+			count: trackedMoveRangeNormalization.removedUnbalancedMoveRangeMarkers
+		});
 		let templateVariables;
 		if (detectVariables) {
 			onProgress("Detecting template variables...", 75);
@@ -230,8 +285,15 @@ async function parseDocx(input, options = {}) {
 		const validation = validateFolioDocumentModel(document);
 		const parsedCompleteModel = parseHeadersFooters && parseNotes;
 		if (!validation.valid && parsedCompleteModel) throw new DocxModelValidationError("Parsed DOCX produced an invalid document model", validation.issues);
-		warnings.push(...formatDocumentModelIssues(validation.issues));
-		if (warnings.length > 0) document.warnings = warnings;
+		for (const issue of formatDocumentModelIssues(validation.issues)) parseContext.warn({
+			code: PARSE_WARNING_CODES.documentModelIssue,
+			detail: issue
+		});
+		const parseWarnings = collectedWarnings();
+		if (parseWarnings.length > 0) {
+			document.parseWarnings = parseWarnings;
+			document.warnings = formatParseWarnings(parseWarnings);
+		}
 		onProgress("Complete", 100);
 		return document;
 	} catch (error) {
@@ -410,7 +472,7 @@ function parseHeadersAndFooters(raw, styles, theme, numbering, rels, media) {
 		if (headerXml) {
 			const headerRelsPath = getRelationshipsPathForPart(partPath);
 			const headerRelsXml = getMapCaseInsensitive(raw.allXml, headerRelsPath);
-			const headerRels = headerRelsXml ? parseRelationships(headerRelsXml) : rels;
+			const headerRels = headerRelsXml ? parseRelationships(headerRelsXml) : /* @__PURE__ */ new Map();
 			const header = parseHeader(headerXml, "default", styles, theme, numbering, headerRels, media);
 			const watermark = header.watermark;
 			if (watermark?.kind === "picture") {
@@ -429,7 +491,7 @@ function parseHeadersAndFooters(raw, styles, theme, numbering, rels, media) {
 		if (footerXml) {
 			const footerRelsPath = getRelationshipsPathForPart(partPath);
 			const footerRelsXml = getMapCaseInsensitive(raw.allXml, footerRelsPath);
-			const footer = parseFooter(footerXml, "default", styles, theme, numbering, footerRelsXml ? parseRelationships(footerRelsXml) : rels, media);
+			const footer = parseFooter(footerXml, "default", styles, theme, numbering, footerRelsXml ? parseRelationships(footerRelsXml) : /* @__PURE__ */ new Map(), media);
 			footers.set(rId, footer);
 		}
 	}
@@ -441,13 +503,13 @@ function parseHeadersAndFooters(raw, styles, theme, numbering, rels, media) {
 /**
 * Parse footnotes and endnotes from raw content
 */
-function parseNotesContent(raw, styles, theme, numbering, rels, media) {
+function parseNotesContent(raw, styles, theme, numbering, rels, media, context) {
 	const relsForNotePart = (partPath) => {
 		const xml = getMapCaseInsensitive(raw.allXml, getRelationshipsPathForPart(partPath));
 		return xml ? parseRelationships(xml) : rels;
 	};
-	const footnoteMap = parseFootnotes(raw.footnotesXml, styles, theme, numbering, relsForNotePart("word/footnotes.xml"), media);
-	const endnoteMap = parseEndnotes(raw.endnotesXml, styles, theme, numbering, relsForNotePart("word/endnotes.xml"), media);
+	const footnoteMap = parseFootnotes(raw.footnotesXml, styles, theme, numbering, relsForNotePart("word/footnotes.xml"), media, context?.scoped({ part: "word/footnotes.xml" }));
+	const endnoteMap = parseEndnotes(raw.endnotesXml, styles, theme, numbering, relsForNotePart("word/endnotes.xml"), media, context?.scoped({ part: "word/endnotes.xml" }));
 	return {
 		footnotes: footnoteMap.getNormalFootnotes(),
 		endnotes: endnoteMap.getNormalEndnotes()

package/dist/docx/relsParser.d.ts

@@ -107,21 +107,38 @@ declare function getHeaders(map: document_d_exports.RelationshipMap): document_d
  */
 declare function getFooters(map: document_d_exports.RelationshipMap): document_d_exports.Relationship[];
 /**
- * Resolve a relationship ID to a target path
+ * What a relationship id names.
+ *
+ * The three cases are kept apart because collapsing any of them into a string
+ * turns absence into a lookup key: an id the author never wrote, an id whose
+ * target the package no longer holds, and an id that resolves are different
+ * facts, and only the last one may be read as a part.
+ */
+type RelationshipResolution = {
+  status: "resolved";
+  relationship: document_d_exports.Relationship;
+} | {
+  status: "absent";
+} | {
+  status: "dangling";
+  id: string;
+};
+/**
+ * Resolve a relationship id against a relationship map.
  *
- * @param map - RelationshipMap to search
- * @param rId - Relationship ID (e.g., "rId1")
- * @returns Target path or undefined if not found
+ * The only sanctioned way to turn an `r:id`, `r:embed` or `r:link` into a part.
+ * An empty attribute is absence, not an id: `ST_RelationshipId` is an NCName,
+ * so `""` can never name a relationship, and no map can hold it as a key.
  */
-declare function resolveTarget(map: document_d_exports.RelationshipMap, rId: string): string | undefined;
+declare function resolveRelationshipId(map: document_d_exports.RelationshipMap | null | undefined, rId: string | undefined): RelationshipResolution;
 /**
- * Resolve a relationship ID to a full relationship
+ * Resolve a relationship id and require it to name a relationship of one type.
  *
- * @param map - RelationshipMap to search
- * @param rId - Relationship ID (e.g., "rId1")
- * @returns Relationship or undefined if not found
+ * A reference of the wrong type is reported as dangling: the part it names
+ * exists, but not as the thing the reference asked for, and reading it anyway
+ * is how a missing image comes back as `styles.xml`.
  */
-declare function resolveRelationship(map: document_d_exports.RelationshipMap, rId: string): document_d_exports.Relationship | undefined;
+declare function resolveRelationshipIdOfType(map: document_d_exports.RelationshipMap | null | undefined, rId: string | undefined, type: document_d_exports.RelationshipType): RelationshipResolution;
 /**
  * Resolve a relative target path to an absolute path within the DOCX
  *
@@ -158,4 +175,4 @@ declare function parsePackageRelationships(relsXml: string): document_d_exports.
  */
 declare function formatRelationships(map: document_d_exports.RelationshipMap): string;
 //#endregion
-export { RELATIONSHIP_TYPES, filterByType, formatRelationships, getFooters, getHeaders, getHyperlinks, getImages, getRelationshipTypeName, isExternalHyperlink, isFooterRelationship, isHeaderRelationship, isImageRelationship, parseDocumentRelationships, parsePackageRelationships, parseRelationships, resolveRelationship, resolveRelativePath, resolveTarget };
+export { RELATIONSHIP_TYPES, RelationshipResolution, filterByType, formatRelationships, getFooters, getHeaders, getHyperlinks, getImages, getRelationshipTypeName, isExternalHyperlink, isFooterRelationship, isHeaderRelationship, isImageRelationship, parseDocumentRelationships, parsePackageRelationships, parseRelationships, resolveRelationshipId, resolveRelationshipIdOfType, resolveRelativePath };

package/dist/docx/relsParser.js

@@ -155,24 +155,37 @@ function getFooters(map) {
 	return filterByType(map, RELATIONSHIP_TYPES.footer);
 }
 /**
-* Resolve a relationship ID to a target path
+* Resolve a relationship id against a relationship map.
 *
-* @param map - RelationshipMap to search
-* @param rId - Relationship ID (e.g., "rId1")
-* @returns Target path or undefined if not found
+* The only sanctioned way to turn an `r:id`, `r:embed` or `r:link` into a part.
+* An empty attribute is absence, not an id: `ST_RelationshipId` is an NCName,
+* so `""` can never name a relationship, and no map can hold it as a key.
 */
-function resolveTarget(map, rId) {
-	return map.get(rId)?.target;
+function resolveRelationshipId(map, rId) {
+	if (rId === void 0 || rId.length === 0) return { status: "absent" };
+	const relationship = map?.get(rId);
+	return relationship === void 0 ? {
+		status: "dangling",
+		id: rId
+	} : {
+		status: "resolved",
+		relationship
+	};
 }
 /**
-* Resolve a relationship ID to a full relationship
+* Resolve a relationship id and require it to name a relationship of one type.
 *
-* @param map - RelationshipMap to search
-* @param rId - Relationship ID (e.g., "rId1")
-* @returns Relationship or undefined if not found
+* A reference of the wrong type is reported as dangling: the part it names
+* exists, but not as the thing the reference asked for, and reading it anyway
+* is how a missing image comes back as `styles.xml`.
 */
-function resolveRelationship(map, rId) {
-	return map.get(rId);
+function resolveRelationshipIdOfType(map, rId, type) {
+	const resolved = resolveRelationshipId(map, rId);
+	if (resolved.status !== "resolved" || resolved.relationship.type === type) return resolved;
+	return {
+		status: "dangling",
+		id: resolved.relationship.id
+	};
 }
 /**
 * Resolve a relative target path to an absolute path within the DOCX
@@ -232,4 +245,4 @@ function formatRelationships(map) {
 	return lines.join("\n");
 }
 //#endregion
-export { RELATIONSHIP_TYPES, filterByType, formatRelationships, getFooters, getHeaders, getHyperlinks, getImages, getRelationshipTypeName, isExternalHyperlink, isFooterRelationship, isHeaderRelationship, isImageRelationship, parseDocumentRelationships, parsePackageRelationships, parseRelationships, resolveRelationship, resolveRelativePath, resolveTarget };
+export { RELATIONSHIP_TYPES, filterByType, formatRelationships, getFooters, getHeaders, getHyperlinks, getImages, getRelationshipTypeName, isExternalHyperlink, isFooterRelationship, isHeaderRelationship, isImageRelationship, parseDocumentRelationships, parsePackageRelationships, parseRelationships, resolveRelationshipId, resolveRelationshipIdOfType, resolveRelativePath };

package/dist/docx/revisionIdNormalization.js

@@ -31,16 +31,79 @@ const REVISION_ELEMENT_NAMES = /* @__PURE__ */ new Set([
 	"trPrChange"
 ]);
 const REVISION_ELEMENT_CANDIDATE = new RegExp(`<(?:[^\\s<>/:]+:)?(?:${[...REVISION_ELEMENT_NAMES].join("|")})(?:[\\s/>])`, "u");
-const revisionAttribute = (element) => {
-	if (!element.name || !WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(element) ?? "") || !REVISION_ELEMENT_NAMES.has(getLocalName(element.name))) return null;
+/**
+* The rest of the annotation id space.
+*
+* A comment, a bookmark, a protected range and a tracked change all draw their
+* `w:id` from one space: Word allocates from a single counter, which is why a
+* package carrying several kinds almost never repeats a value across them. So
+* an id this pass mints must avoid these as well, or a renumbered `w:ins`
+* lands on a live comment.
+*
+* They are only ever reserved, never claimed. A comment id legitimately
+* appears four times (`w:comment`, both range markers and the reference) and a
+* bookmark id twice, so feeding them to the uniqueness machinery would reject
+* a package Word wrote. Their pairing is also why they are not revision
+* elements: renumbering one end of a range would unpair it.
+*/
+const ANNOTATION_ELEMENT_NAMES = /* @__PURE__ */ new Set([
+	"bookmarkEnd",
+	"bookmarkStart",
+	"comment",
+	"commentRangeEnd",
+	"commentRangeStart",
+	"commentReference",
+	"customXmlDelRangeEnd",
+	"customXmlDelRangeStart",
+	"customXmlInsRangeEnd",
+	"customXmlInsRangeStart",
+	"customXmlMoveFromRangeEnd",
+	"customXmlMoveFromRangeStart",
+	"customXmlMoveToRangeEnd",
+	"customXmlMoveToRangeStart",
+	"moveFromRangeEnd",
+	"moveFromRangeStart",
+	"moveToRangeEnd",
+	"moveToRangeStart",
+	"permEnd",
+	"permStart"
+]);
+const ANNOTATION_ELEMENT_CANDIDATE = new RegExp(`<(?:[^\\s<>/:]+:)?(?:${[...ANNOTATION_ELEMENT_NAMES].join("|")})(?:[\\s/>])`, "u");
+const ID_KINDS = {
+	revision: "revision",
+	annotation: "annotation"
+};
+/** One lookup for both halves of the space, so an element is classified once. */
+const ID_KIND_BY_ELEMENT_NAME = new Map([...[...REVISION_ELEMENT_NAMES].map((name) => [name, ID_KINDS.revision]), ...[...ANNOTATION_ELEMENT_NAMES].map((name) => [name, ID_KINDS.annotation])]);
+/**
+* An element's `w:id` and which half of the annotation space it belongs to.
+*
+* One classifier rather than two, because it runs on every element of every
+* scanned part: resolving the namespace and the local name twice to ask two
+* questions measured 18% on a 17.6 MiB package.
+*
+* `w:permStart` types its id as a string, so a protected range named
+* `everyone` yields nothing. That is correct: a value the allocator can never
+* mint is not one it has to avoid.
+*/
+const identifiedElement = (element) => {
+	if (!element.name || !WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(element) ?? "")) return null;
+	const localName = getLocalName(element.name);
+	const kind = ID_KIND_BY_ELEMENT_NAME.get(localName);
+	if (kind === void 0) return null;
 	const attribute = findAttributeByNamespaceUri(element, WORDPROCESSINGML_NAMESPACE_URIS, "id");
 	if (!attribute) return null;
 	const id = Number(attribute.value);
 	return Number.isSafeInteger(id) && id >= 0 ? {
+		kind,
 		name: attribute.name,
 		id
 	} : null;
 };
+const revisionAttribute = (element) => {
+	const identified = identifiedElement(element);
+	return identified?.kind === ID_KINDS.revision ? identified : null;
+};
 /**
 * Keep physical tracked-change element ids unique across a package.
 *
@@ -57,11 +120,10 @@ const normalizeRevisionIdsInXmlParts = (parts) => {
 		assertXmlResourceLimits(xml);
 		const ids = [];
 		if (rewriteStreamingXmlDecimalAttributes(xml, (element) => {
-			const attribute = revisionAttribute(element);
-			if (attribute) {
-				ids.push(attribute.id);
-				reserved.add(attribute.id);
-			}
+			const identified = identifiedElement(element);
+			if (identified === null) return null;
+			if (identified.kind === ID_KINDS.revision) ids.push(identified.id);
+			reserved.add(identified.id);
 			return null;
 		}).status === "unsupported") throw new XmlResourceLimitError({
 			message: `Revision-id normalization could not safely scan ${path}`,
@@ -73,6 +135,18 @@ const normalizeRevisionIdsInXmlParts = (parts) => {
 	const firstSeen = /* @__PURE__ */ new Set();
 	for (const [path, ids] of occurrencesByPath) for (const id of ids) if (firstSeen.has(id)) repeatedPaths.add(path);
 	else firstSeen.add(id);
+	if (repeatedPaths.size > 0) for (const [path, xml] of parts) {
+		if (occurrencesByPath.has(path) || !ANNOTATION_ELEMENT_CANDIDATE.test(xml)) continue;
+		assertXmlResourceLimits(xml);
+		if (rewriteStreamingXmlDecimalAttributes(xml, (element) => {
+			const identified = identifiedElement(element);
+			if (identified !== null) reserved.add(identified.id);
+			return null;
+		}).status === "unsupported") throw new XmlResourceLimitError({
+			message: `Revision-id normalization could not safely scan ${path}`,
+			limit: "syntax"
+		});
+	}
 	let nextId = 0;
 	const allocate = () => {
 		while (reserved.has(nextId)) nextId += 1;

package/dist/docx/rezip.js

@@ -7,9 +7,12 @@ import { applyReplyThreadMarkers } from "./commentReplyMarkers.js";
 import { normalizeDrawingIds } from "./drawingIdNormalization.js";
 import { rebindDrawingImageRelationship } from "./drawingRelationships.js";
 import { parseEndnotes, parseFootnotes } from "./footnoteParser.js";
+import { parseHeaderFooterType } from "./headerFooterRefParser.js";
 import { assertValidFolioDocumentModel } from "./modelValidation.js";
 import { isNewDataUrlDrawing } from "./newImage.js";
+import { missingNoteReferenceStyles, noteReferenceNeeds } from "./noteReferenceStyles.js";
 import { parseNumbering } from "./numberingParser.js";
+import { isNumberingReference } from "./numberingReference.js";
 import { isUnsafePackagePath, reconcilePackageReferences, removeUnsafeEntries } from "./packageParts.js";
 import { normalizeParaIdRangeInXmlParts } from "./paraIdRangeNormalization.js";
 import { RELATIONSHIP_TYPES, parseRelationships, resolveRelativePath } from "./relsParser.js";
@@ -113,7 +116,7 @@ const extractHeaderFooterReferences = (xml) => {
 			const rId = getAttributeByNamespaceUri(node, OFFICE_RELATIONSHIP_NAMESPACE_URIS, "id");
 			if (rId) references.push({
 				element,
-				type: getAttributeByNamespaceUri(node, WORDPROCESSINGML_NAMESPACE_URIS, "type") ?? "default",
+				type: parseHeaderFooterType(getAttributeByNamespaceUri(node, WORDPROCESSINGML_NAMESPACE_URIS, "type")),
 				rId
 			});
 		}
@@ -1387,6 +1390,42 @@ async function serializeNumberingIntoZip(doc, originalZip, newZip, compressionLe
 }
 const STYLES_PART_PATH = "word/styles.xml";
 const STYLES_CLOSE_ROOT = "</w:styles>";
+/**
+* The style table a package folio creates starts from: `docDefaults` and
+* `Normal`, and nothing else. A document that carries its own style table
+* replaces this part wholesale.
+*/
+const SEED_STYLES_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+  <w:docDefaults>
+    <w:rPrDefault>
+      <w:rPr>
+        <w:rFonts w:ascii="Calibri" w:hAnsi="Calibri"/>
+        <w:sz w:val="22"/>
+      </w:rPr>
+    </w:rPrDefault>
+    <w:pPrDefault>
+      <w:pPr>
+        <w:spacing w:after="200" w:line="276" w:lineRule="auto"/>
+      </w:pPr>
+    </w:pPrDefault>
+  </w:docDefaults>
+  <w:style w:type="paragraph" w:default="1" w:styleId="Normal">
+    <w:name w:val="Normal"/>
+  </w:style>
+</w:styles>`;
+/**
+* The seed part plus the reference styles this package's comments and notes
+* need. A document with no style table of its own never reaches
+* {@link styleDefinitionsToSerialize}, so without this its reference marks
+* would carry a `w:rStyle` naming nothing — the defect
+* `noteReferenceStyles.ts` exists to remove, on the one path that skips it.
+*/
+const seedStylesXmlWith = (missing) => {
+	if (missing.length === 0) return SEED_STYLES_XML;
+	const rootClose = SEED_STYLES_XML.lastIndexOf(STYLES_CLOSE_ROOT);
+	return SEED_STYLES_XML.slice(0, rootClose) + missing.map(serializeStyle).join("") + SEED_STYLES_XML.slice(rootClose);
+};
 const STYLE_ID_PATTERN = /<w:style\b[^>]*?\bw:styleId="(?<id>[^"]+)"/gu;
 /**
 * Append styles the model defines but the original `word/styles.xml` lacks.
@@ -1395,6 +1434,27 @@ const STYLE_ID_PATTERN = /<w:style\b[^>]*?\bw:styleId="(?<id>[^"]+)"/gu;
 * per-language clones a bilingual transform adds, are emitted before the root
 * close so paragraphs referencing them resolve on reopen.
 */
+/**
+* The styles to write into a package folio is authoring: the model's, plus any
+* reference character style the serializers are about to emit for this
+* package's comments and notes but the style table does not define. See
+* `noteReferenceStyles.ts` — the reference mark would otherwise carry a
+* `w:rStyle` pointing at nothing.
+*
+* Only for a package folio writes from scratch. Repacking a document someone
+* else authored preserves `word/styles.xml` byte for byte, and adding a
+* definition there would rewrite a part the user never edited: their document,
+* their style table, missing reference style included.
+*/
+const styleDefinitionsToSerialize = (doc) => {
+	const styles = doc.package.styles;
+	if (!styles) return;
+	const missing = missingNoteReferenceStyles(styles, noteReferenceNeeds(doc.package));
+	return missing.length === 0 ? styles : {
+		...styles,
+		styles: [...styles.styles, ...missing]
+	};
+};
 async function serializeAddedStylesIntoZip(doc, originalZip, newZip, compressionLevel) {
 	const styles = doc.package.styles;
 	if (!styles || styles.styles.length === 0) return;
@@ -1576,25 +1636,7 @@ const createEmptyDocxZip = ({ creator, application }) => {
     </w:sectPr>
   </w:body>
 </w:document>`);
-	zip.file("word/styles.xml", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
-  <w:docDefaults>
-    <w:rPrDefault>
-      <w:rPr>
-        <w:rFonts w:ascii="Calibri" w:hAnsi="Calibri"/>
-        <w:sz w:val="22"/>
-      </w:rPr>
-    </w:rPrDefault>
-    <w:pPrDefault>
-      <w:pPr>
-        <w:spacing w:after="200" w:line="276" w:lineRule="auto"/>
-      </w:pPr>
-    </w:pPrDefault>
-  </w:docDefaults>
-  <w:style w:type="paragraph" w:default="1" w:styleId="Normal">
-    <w:name w:val="Normal"/>
-  </w:style>
-</w:styles>`);
+	zip.file(STYLES_PART_PATH, SEED_STYLES_XML);
 	const now = (/* @__PURE__ */ new Date()).toISOString();
 	const creatorElement = creator === void 0 ? "" : `\n  <dc:creator>${escapeXml(creator)}</dc:creator>`;
 	zip.file("docProps/core.xml", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
@@ -1645,10 +1687,11 @@ const createDocumentSeedZip = async (doc, properties) => {
 	const relationships = ["<Relationship Id=\"rId1\" Type=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles\" Target=\"styles.xml\"/>"];
 	const overrides = [];
 	let nextRelationshipId = 2;
-	if (doc.package.styles) {
+	const styleDefinitions = styleDefinitionsToSerialize(doc);
+	if (styleDefinitions) {
 		assertStyleNumberingReferences(doc);
-		zip.file("word/styles.xml", serializeStylesXml(doc.package.styles));
-	}
+		zip.file(STYLES_PART_PATH, serializeStylesXml(styleDefinitions));
+	} else zip.file(STYLES_PART_PATH, seedStylesXmlWith(missingNoteReferenceStyles(void 0, noteReferenceNeeds(doc.package))));
 	const numbering = doc.package.numbering;
 	if (numbering && (numbering.abstractNums.length > 0 || numbering.nums.length > 0)) {
 		zip.file("word/numbering.xml", serializeNumberingXml(numbering));
@@ -1684,17 +1727,32 @@ const createDocumentSeedZip = async (doc, properties) => {
 };
 const relationshipXml = (id, type, target) => `<Relationship Id="rId${id}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/${type}" Target="${target}"/>`;
 const overrideXml = (partName, contentType) => `<Override PartName="${partName}" ContentType="${contentType}"/>`;
+/**
+* A package this build assembles from a Document must define the numbering its
+* styles name: Word reads a styles.xml reference nothing resolves as no
+* numbering at all, silently dropping the style's list.
+*
+* The panic is an invariant over Folio's own output, not input validation. A
+* source file can carry a dangling style reference, and it never arrives here:
+* `normalizeStyleNumberingReferences` rewrites one to the "no numbering"
+* sentinel at every boundary that mints a Document from user styles (`parseDocx`
+* and the style-set extraction entry points). What reaches this point is what
+* Folio itself put in the model, so a miss is a defect in Folio.
+*/
 const assertStyleNumberingReferences = (doc) => {
 	const referenced = /* @__PURE__ */ new Set();
 	for (const style of doc.package.styles?.styles ?? []) {
 		const numId = style.pPr?.numPr?.numId;
-		if (numId !== void 0) referenced.add(numId);
+		if (isNumberingReference(numId)) referenced.add(numId);
 	}
 	if (referenced.size === 0) return;
-	const available = new Set(doc.package.numbering?.nums.map((numbering) => numbering.numId) ?? []);
-	for (const numId of referenced) if (!available.has(numId)) panic(`Style references missing numbering definition ${numId}`);
+	const available = new Map(doc.package.numbering?.nums.map((numbering) => [numbering.numId, numbering]) ?? []);
 	const availableAbstract = new Set(doc.package.numbering?.abstractNums.map((numbering) => numbering.abstractNumId) ?? []);
-	for (const numbering of doc.package.numbering?.nums ?? []) if (!availableAbstract.has(numbering.abstractNumId)) panic(`Numbering definition ${numbering.numId} references missing abstract numbering`);
+	for (const numId of referenced) {
+		const numbering = available.get(numId);
+		if (!numbering) panic(`Style references missing numbering definition ${numId}`);
+		if (!availableAbstract.has(numbering.abstractNumId)) panic(`Numbering definition ${numbering.numId} references missing abstract numbering`);
+	}
 };
 //#endregion
 export { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_CONTENT_TYPE, COMMENTS_EXTENDED_PART, COMMENTS_EXTENDED_PART_LOWER, DocxPackageFidelityError, addCommentsExtendedOverride, addCommentsExtendedRelationship, addMedia, addRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, collectHyperlinksWithoutRId, createDocx, createEmptyDocx, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedInlineResources, isDocxBuffer, notePartRelsPath, removeCommentsExtendedOverride, removeCommentsExtendedRelationship, repackDocx, repackDocxFromRaw, updateCoreProperties, updateDocumentXml, updateMultipleFiles, updateXmlFile, validateDocx, withoutAttachedTemplate };

package/dist/docx/runConsolidator.js

@@ -114,8 +114,7 @@ function mergeRunContent(content1, content2) {
 	if (lastText?.type === "text" && firstText?.type === "text") {
 		result[result.length - 1] = {
 			type: "text",
-			text: lastText.text + firstText.text,
-			...lastText.preserveSpace || firstText.preserveSpace ? { preserveSpace: true } : {}
+			text: lastText.text + firstText.text
 		};
 		for (let i = 1; i < content2.length; i++) result.push(content2[i]);
 	} else for (const c of content2) result.push(c);