@stll/folio-core 0.42.0 → 0.44.0

package/dist/docx/paragraphParser.js

@@ -1,21 +1,24 @@
-import { isValidHexColor } from "../utils/colorResolver.js";
 import { isValidHexId } from "../utils/hexId.js";
 import { parseBookmarkEnd as parseBookmarkEnd$1, parseBookmarkStart as parseBookmarkStart$1 } from "./bookmarkParser.js";
+import { parseBorderSpec } from "./borderParser.js";
 import { parseFieldType } from "./fieldParser.js";
 import { parseHyperlink as parseHyperlink$1, parseHyperlinkChild } from "./hyperlinkParser.js";
+import { parseMarkupRangeMarker, parseMoveBookmarkMarker } from "./markupRangeMarker.js";
 import { markerFormattingFromLevel, numberingLevelHasMarkerSlot } from "./numberingParser.js";
+import { isNumberingReference } from "./numberingReference.js";
 import { paraIdInRange } from "./paraIdRangeNormalization.js";
 import { assignParagraphPropertySource } from "./paragraphPropertySource.js";
-import { BorderStyleSchema, FrameWrapSchema, FrameXAlignSchema, FrameYAlignSchema, LineSpacingRuleSchema, ParagraphAlignmentSchema, ShadingPatternSchema, TabLeaderSchema, TabStopAlignmentSchema, ThemeColorSlotSchema, narrowEnum } from "./parserEnums.js";
+import { FrameWrapSchema, FrameXAlignSchema, FrameYAlignSchema, LineSpacingRuleSchema, ParagraphAlignmentSchema, TabLeaderSchema, TabStopAlignmentSchema, narrowEnum } from "./parserEnums.js";
 import { consolidateParagraphContent } from "./runConsolidator.js";
 import { parseRun, parseRunProperties } from "./runParser.js";
 import { parseSdtProperties } from "./sdtProperties.js";
 import { parseSectionProperties } from "./sectionParser.js";
+import { parseShading } from "./shadingParser.js";
 import { parsePropertyChangeInfo, parseTrackedChangeInfo } from "./trackedChangeInfo.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
-import { WORDPROCESSINGML_NAMESPACE_URIS, cloneElement, findChild, findChildByNamespaceUri, findChildren, findChildrenByNamespaceUri, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseNumberingLevelAttribute, parseNumericAttribute, selectAlternateContentBranch } from "./xmlParser.js";
+import { WORDPROCESSINGML_NAMESPACE_URIS, cloneElement, findChild, findChildByNamespaceUri, findChildren, findChildrenByNamespaceUri, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespaceUri, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffAttribute, selectAlternateContentBranch } from "./xmlParser.js";
 import { panic } from "better-result";
-import { PARAGRAPH_MARK_CHANGE_KINDS, REVIEW_CARRIERS } from "@stll/docx-core/model";
+import { BIDI_CONTROLS, PARAGRAPH_MARK_CHANGE_KINDS, REVIEW_CARRIERS } from "@stll/docx-core/model";
 //#region src/docx/paragraphParser.ts
 const FOLIO_REVIEW_HISTORY_NAMESPACES = /* @__PURE__ */ new Set(["urn:stella:folio:review-history:1"]);
 /**
@@ -35,63 +38,6 @@ function extractMathText(el) {
 	return text;
 }
 /**
-* Parse color value from attributes
-*/
-function parseColorValue(rgb, themeColor, themeTint, themeShade) {
-	const color = {};
-	if (rgb && rgb !== "auto") color.rgb = rgb;
-	else if (rgb === "auto") color.auto = true;
-	const validatedThemeColor = narrowEnum(themeColor, ThemeColorSlotSchema);
-	if (validatedThemeColor) color.themeColor = validatedThemeColor;
-	if (themeTint) color.themeTint = themeTint;
-	if (themeShade) color.themeShade = themeShade;
-	return color;
-}
-/**
-* Parse shading properties (w:shd)
-*/
-function parseShadingProperties(shd) {
-	if (!shd) return;
-	const props = {};
-	const color = getAttribute(shd, "w", "color");
-	if (color && color !== "auto" && isValidHexColor(color)) props.color = { rgb: color };
-	const fill = getAttribute(shd, "w", "fill");
-	if (fill && fill !== "auto" && isValidHexColor(fill)) props.fill = { rgb: fill };
-	const validatedThemeFill = narrowEnum(getAttribute(shd, "w", "themeFill"), ThemeColorSlotSchema);
-	if (validatedThemeFill) {
-		props.fill = props.fill || {};
-		props.fill.themeColor = validatedThemeFill;
-	}
-	const themeFillTint = getAttribute(shd, "w", "themeFillTint");
-	if (themeFillTint && props.fill) props.fill.themeTint = themeFillTint;
-	const themeFillShade = getAttribute(shd, "w", "themeFillShade");
-	if (themeFillShade && props.fill) props.fill.themeShade = themeFillShade;
-	const pattern = narrowEnum(getAttribute(shd, "w", "val"), ShadingPatternSchema);
-	if (pattern) props.pattern = pattern;
-	return Object.keys(props).length > 0 ? props : void 0;
-}
-/**
-* Parse border specification (w:top, w:bottom, w:left, w:right, etc.)
-*/
-function parseBorderSpec(border) {
-	if (!border) return;
-	const rawStyle = getAttribute(border, "w", "val");
-	if (!rawStyle) return;
-	const spec = { style: narrowEnum(rawStyle, BorderStyleSchema) ?? rawStyle };
-	const colorVal = getAttribute(border, "w", "color");
-	const themeColor = getAttribute(border, "w", "themeColor");
-	if (colorVal || themeColor) spec.color = parseColorValue(colorVal, themeColor, getAttribute(border, "w", "themeTint"), getAttribute(border, "w", "themeShade"));
-	const sz = parseNumericAttribute(border, "w", "sz");
-	if (sz !== void 0) spec.size = sz;
-	const space = parseNumericAttribute(border, "w", "space");
-	if (space !== void 0) spec.space = space;
-	const shadowAttr = getAttribute(border, "w", "shadow");
-	if (shadowAttr) spec.shadow = shadowAttr === "1" || shadowAttr === "true";
-	const frame = getAttribute(border, "w", "frame");
-	if (frame) spec.frame = frame === "1" || frame === "true";
-	return spec;
-}
-/**
 * Parse tab stops (w:tabs)
 */
 function parseTabStops(tabs) {
@@ -272,10 +218,10 @@ function parseParagraphProperties(pPr, theme, styles) {
 		if (spacingExplicit.before || spacingExplicit.after) formatting.spacingExplicit = spacingExplicit;
 		const lineRule = narrowEnum(getAttribute(spacing, "w", "lineRule"), LineSpacingRuleSchema);
 		if (lineRule) formatting.lineSpacingRule = lineRule;
-		const beforeAuto = getAttribute(spacing, "w", "beforeAutospacing");
-		if (beforeAuto) formatting.beforeAutospacing = beforeAuto === "1" || beforeAuto === "true";
-		const afterAuto = getAttribute(spacing, "w", "afterAutospacing");
-		if (afterAuto) formatting.afterAutospacing = afterAuto === "1" || afterAuto === "true";
+		const beforeAutospacing = parseOnOffAttribute(spacing, "w", "beforeAutospacing");
+		if (beforeAutospacing !== void 0) formatting.beforeAutospacing = beforeAutospacing;
+		const afterAutospacing = parseOnOffAttribute(spacing, "w", "afterAutospacing");
+		if (afterAutospacing !== void 0) formatting.afterAutospacing = afterAutospacing;
 	}
 	const ind = propertyChildren.ind;
 	if (ind) {
@@ -314,7 +260,7 @@ function parseParagraphProperties(pPr, theme, styles) {
 	}
 	const shd = propertyChildren.shd;
 	if (shd) {
-		const shadingResult = parseShadingProperties(shd);
+		const shadingResult = parseShading(shd);
 		if (shadingResult !== void 0) formatting.shading = shadingResult;
 	}
 	const tabs = propertyChildren.tabs;
@@ -347,6 +293,8 @@ function parseParagraphProperties(pPr, theme, styles) {
 				if (val !== void 0) formatting.numPr.ilvl = val;
 			}
 		}
+		const numberingChange = findChild(numPr, "w", "numberingChange");
+		if (numberingChange) formatting.numberingChangeXml = captureVerbatimXml(numberingChange);
 	}
 	const outlineLvl = propertyChildren.outlineLvl;
 	if (outlineLvl) {
@@ -652,6 +600,27 @@ const hyperlinkRevisionWrapperType = (node) => {
 		default: return;
 	}
 };
+const OMML_NAMESPACE = "http://schemas.openxmlformats.org/officeDocument/2006/math";
+/**
+* A bare OMML element as an inline equation, or nothing when the child is not one.
+*
+* `m:oMath` and `m:oMathPara` have branches of their own. This is for the rest
+* of `m:EG_OMathMathElements` — `m:f`, `m:acc`, `m:rad` and their siblings —
+* which the schema admits wherever `m:oMath` is admitted. They carry no
+* structure the editable model holds, so they travel as the markup they
+* arrived as, exactly like the equations that do have a wrapper.
+*/
+const mathContentOf = (child) => {
+	if (getNamespaceUri(child) !== OMML_NAMESPACE) return;
+	const equation = {
+		type: "mathEquation",
+		display: "inline",
+		ommlXml: captureVerbatimXml(child)
+	};
+	const plainText = extractMathText(child);
+	if (plainText) equation.plainText = plainText;
+	return equation;
+};
 const isHyperlinkChildContent = (content) => content.type === "run" || content.type === "bookmarkStart" || content.type === "bookmarkEnd";
 /**
 * A `w:hyperlink` as paragraph content, with any revision wrapper it holds
@@ -741,10 +710,8 @@ function parseSimpleField(node, styles, theme, rels, media, rootXmlns = {}) {
 		fieldType: parseFieldType(instruction),
 		content: []
 	};
-	const fldLock = getAttribute(node, "w", "fldLock");
-	if (fldLock === "1" || fldLock === "true") field.fldLock = true;
-	const dirty = getAttribute(node, "w", "dirty");
-	if (dirty === "1" || dirty === "true") field.dirty = true;
+	if (parseOnOffAttribute(node, "w", "fldLock") === true) field.fldLock = true;
+	if (parseOnOffAttribute(node, "w", "dirty") === true) field.dirty = true;
 	const inScopeXmlns = mergeXmlnsDeclarations(rootXmlns, node);
 	const children = getChildElements(node);
 	for (const child of children) {
@@ -985,57 +952,53 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 				contents.push(...inner);
 				break;
 			}
-			case "moveFromRangeStart": {
-				const id = Number.parseInt(getAttribute(child, "w", "id") ?? "0", 10);
-				const name = getAttribute(child, "w", "name") ?? "";
+			case "moveFromRangeStart":
 				contents.push({
 					type: "moveFromRangeStart",
-					id,
-					name
+					...parseMoveBookmarkMarker(child)
 				});
 				break;
-			}
-			case "moveFromRangeEnd": {
-				const id = Number.parseInt(getAttribute(child, "w", "id") ?? "0", 10);
+			case "moveFromRangeEnd":
 				contents.push({
 					type: "moveFromRangeEnd",
-					id
+					...parseMarkupRangeMarker(child)
 				});
 				break;
-			}
-			case "moveToRangeStart": {
-				const id = Number.parseInt(getAttribute(child, "w", "id") ?? "0", 10);
-				const name = getAttribute(child, "w", "name") ?? "";
+			case "moveToRangeStart":
 				contents.push({
 					type: "moveToRangeStart",
-					id,
-					name
+					...parseMoveBookmarkMarker(child)
 				});
 				break;
-			}
-			case "moveToRangeEnd": {
-				const id = Number.parseInt(getAttribute(child, "w", "id") ?? "0", 10);
+			case "moveToRangeEnd":
 				contents.push({
 					type: "moveToRangeEnd",
-					id
+					...parseMarkupRangeMarker(child)
 				});
 				break;
-			}
-			case "commentRangeStart": {
-				const commentId = Number.parseInt(getAttribute(child, "w", "id") ?? "0", 10);
+			case "commentRangeStart":
 				contents.push({
 					type: "commentRangeStart",
-					id: commentId
+					...parseMarkupRangeMarker(child)
 				});
 				break;
-			}
-			case "commentRangeEnd": {
-				const commentId = Number.parseInt(getAttribute(child, "w", "id") ?? "0", 10);
+			case "commentRangeEnd":
 				contents.push({
 					type: "commentRangeEnd",
-					id: commentId
+					...parseMarkupRangeMarker(child)
 				});
 				break;
+			case "bdo":
+			case "dir": {
+				const direction = getAttribute(child, "w", "val");
+				const wrapper = {
+					type: "bidiWrapper",
+					control: localName === "bdo" ? BIDI_CONTROLS.override : BIDI_CONTROLS.embedding,
+					content: parseParagraphContents(child, styles, theme, null, rels, media, trackedContext, inScopeXmlns)
+				};
+				if (direction === "ltr" || direction === "rtl") wrapper.direction = direction;
+				contents.push(wrapper);
+				break;
 			}
 			case "oMath":
 			case "oMathPara": {
@@ -1051,7 +1014,11 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 				contents.push(mathEq);
 				break;
 			}
-			default: break;
+			default: {
+				const mathElement = mathContentOf(child);
+				if (mathElement !== void 0) contents.push(mathElement);
+				break;
+			}
 		}
 	}
 	if (inComplexField && afterSeparator) contents.push(...complexFieldResultRuns);
@@ -1114,7 +1081,7 @@ function parseParagraph(node, styles, theme, numbering, rels = null, media = nul
 	}
 	if (effectiveNumPr && numbering) {
 		const { numId, ilvl = 0 } = effectiveNumPr;
-		if (numId !== void 0 && numId !== 0) {
+		if (isNumberingReference(numId)) {
 			const level = numbering.getLevel(numId, ilvl);
 			if (level) {
 				const levelNumFmts = [];
@@ -1269,7 +1236,8 @@ const getParagraphContentText = (content) => {
 		case "complexField": return content.fieldResult.map(getRunText).join("");
 		case "inlineSdt": return content.content.map(getParagraphContentText).join("");
 		case "insertion":
-		case "moveTo": return content.content.map(getParagraphContentText).join("");
+		case "moveTo":
+		case "bidiWrapper": return content.content.map(getParagraphContentText).join("");
 		case "deletion":
 		case "moveFrom": return "";
 		case "mathEquation": return content.plainText ?? "";
@@ -1310,7 +1278,7 @@ function isEmptyParagraph(paragraph) {
 * @returns true if paragraph has numbering properties
 */
 function isListItem(paragraph) {
-	return paragraph.formatting?.numPr !== void 0 && paragraph.formatting.numPr.numId !== void 0 && paragraph.formatting.numPr.numId !== 0;
+	return isNumberingReference(paragraph.formatting?.numPr?.numId);
 }
 /**
 * Get the list level of a paragraph (0-8)

package/dist/docx/paragraphPropertySource.js

@@ -265,6 +265,7 @@ const tableCellBlockTraversalByType = {
 	table: "table"
 };
 const tableCellParagraphContentTraversalByType = {
+	bidiWrapper: "content",
 	bookmarkEnd: "leaf",
 	bookmarkStart: "leaf",
 	commentRangeEnd: "leaf",

package/dist/docx/paragraphTraversal.d.ts

@@ -9,6 +9,42 @@ type DocxParagraphSurfaces = {
 };
 /** Visit every run directly owned by a paragraph's inline-content tree. */
 declare const visitParagraphRuns: (paragraph: document_d_exports.Paragraph, visit: (run: document_d_exports.Run) => void) => void;
+/**
+ * One position in an inline-content array: the array itself, the index, and
+ * what sits there. A normaliser that drops or rewrites a marker needs the
+ * array and the index, not only the value.
+ */
+type InlineContentSlot = {
+  content: document_d_exports.ParagraphContent[];
+  index: number;
+  item: document_d_exports.ParagraphContent;
+};
+/**
+ * Visit every inline-content position a paragraph owns, in document order,
+ * descending through every wrapper that is transparent to a range marker.
+ *
+ * The model validator walks the whole inline tree; a normaliser that walks
+ * only `paragraph.content` sees a different document from the one the
+ * validator judges, and a marker inside `w:ins`, `w:hyperlink`, `w:sdt`,
+ * `w:bdo` or `w:dir` then reaches the validator unnormalised. Both sides read
+ * the tree through this one traversal so they cannot disagree again.
+ *
+ * A complex field's runs are skipped: `fieldCode` and `fieldResult` hold runs
+ * only, and a run is not a marker position.
+ */
+declare const visitInlineContentSlots: (paragraph: document_d_exports.Paragraph, visit: (slot: InlineContentSlot) => void) => void;
+/**
+ * Positions marked for removal, per inline-content array.
+ *
+ * Removal shifts every later index in that array, so a normaliser records the
+ * positions while it reads and drops them once, after it has finished reading.
+ */
+declare class InlineContentRemovals {
+  #private;
+  mark({ content, index }: Pick<InlineContentSlot, "content" | "index">): void;
+  /** Applies every marked removal and answers how many items were dropped. */
+  apply(): number;
+}
 declare const visitDocxParagraphs: ({ documentBody, headers, footers, footnotes, endnotes }: DocxParagraphSurfaces, visit: (paragraph: document_d_exports.Paragraph) => void) => void;
 //#endregion
-export { DocxParagraphSurfaces, visitDocxParagraphs, visitParagraphRuns };
+export { DocxParagraphSurfaces, InlineContentRemovals, InlineContentSlot, visitDocxParagraphs, visitInlineContentSlots, visitParagraphRuns };

package/dist/docx/paragraphTraversal.js

@@ -1,3 +1,4 @@
+import { panic } from "better-result";
 //#region src/docx/paragraphTraversal.ts
 /** Visit every run directly owned by a paragraph's inline-content tree. */
 const visitParagraphRuns = (paragraph, visit) => {
@@ -15,6 +16,7 @@ const visitParagraphRuns = (paragraph, visit) => {
 			case "moveFrom":
 			case "moveTo":
 			case "inlineSdt":
+			case "bidiWrapper":
 				for (const child of content.content) visitParagraphContent(child);
 				return;
 			case "complexField":
@@ -36,6 +38,87 @@ const visitParagraphRuns = (paragraph, visit) => {
 	};
 	for (const content of paragraph.content) visitParagraphContent(content);
 };
+/**
+* Visit every inline-content position a paragraph owns, in document order,
+* descending through every wrapper that is transparent to a range marker.
+*
+* The model validator walks the whole inline tree; a normaliser that walks
+* only `paragraph.content` sees a different document from the one the
+* validator judges, and a marker inside `w:ins`, `w:hyperlink`, `w:sdt`,
+* `w:bdo` or `w:dir` then reaches the validator unnormalised. Both sides read
+* the tree through this one traversal so they cannot disagree again.
+*
+* A complex field's runs are skipped: `fieldCode` and `fieldResult` hold runs
+* only, and a run is not a marker position.
+*/
+const visitInlineContentSlots = (paragraph, visit) => {
+	const visitContent = (content) => {
+		for (const [index, item] of content.entries()) {
+			visit({
+				content,
+				index,
+				item
+			});
+			switch (item.type) {
+				case "hyperlink":
+					visitContent(item.children);
+					break;
+				case "simpleField":
+				case "inlineSdt":
+				case "insertion":
+				case "deletion":
+				case "moveFrom":
+				case "moveTo":
+				case "bidiWrapper":
+					visitContent(item.content);
+					break;
+				case "run":
+				case "complexField":
+				case "bookmarkStart":
+				case "bookmarkEnd":
+				case "commentRangeStart":
+				case "commentRangeEnd":
+				case "commentReference":
+				case "moveFromRangeStart":
+				case "moveFromRangeEnd":
+				case "moveToRangeStart":
+				case "moveToRangeEnd":
+				case "mathEquation": break;
+				default: panic(`Unsupported paragraph content: ${JSON.stringify(item)}`);
+			}
+		}
+	};
+	visitContent(paragraph.content);
+};
+/**
+* Positions marked for removal, per inline-content array.
+*
+* Removal shifts every later index in that array, so a normaliser records the
+* positions while it reads and drops them once, after it has finished reading.
+*/
+var InlineContentRemovals = class {
+	#byContent = /* @__PURE__ */ new Map();
+	mark({ content, index }) {
+		const indexes = this.#byContent.get(content);
+		if (indexes) {
+			indexes.add(index);
+			return;
+		}
+		this.#byContent.set(content, /* @__PURE__ */ new Set([index]));
+	}
+	/** Applies every marked removal and answers how many items were dropped. */
+	apply() {
+		let removed = 0;
+		for (const [content, indexes] of this.#byContent) {
+			if (indexes.size === 0) continue;
+			const next = content.filter((_, index) => !indexes.has(index));
+			removed += content.length - next.length;
+			content.length = 0;
+			content.push(...next);
+		}
+		return removed;
+	}
+};
 const visitDocxParagraphs = ({ documentBody, headers, footers, footnotes, endnotes }, visit) => {
 	const seenParagraphs = /* @__PURE__ */ new WeakSet();
 	const visitParagraph = (paragraph) => {
@@ -76,4 +159,4 @@ const visitDocxParagraphs = ({ documentBody, headers, footers, footnotes, endnot
 	for (const comment of documentBody.comments ?? []) for (const paragraph of comment.content) visitParagraph(paragraph);
 };
 //#endregion
-export { visitDocxParagraphs, visitParagraphRuns };
+export { InlineContentRemovals, visitDocxParagraphs, visitInlineContentSlots, visitParagraphRuns };

package/dist/docx/parseContext.d.ts

@@ -0,0 +1,37 @@
+import { ParseWarning, ParseWarningCode } from "@stll/docx-core/model";
+//#region src/docx/parseContext.d.ts
+/** What a call site states; the collector supplies the rest. */
+type ParseWarningReport = {
+  code: ParseWarningCode;
+  /** The element as written, prefix included. */
+  element?: string;
+  /** The best position this part can name, e.g. `style "Heading1"`. */
+  at?: string;
+  /** The value folio declined to read, as written. */
+  value?: string;
+  /** Text passed through from another owner, for the pass-through codes. */
+  detail?: string;
+  /** How many occurrences this one report stands for; defaults to 1. */
+  count?: number;
+};
+type ParseContext = {
+  /** Record one normalisation applied to input folio accepted. */
+  warn: (report: ParseWarningReport) => void;
+  /** The same collector, reporting against another part or position. */
+  scoped: (location: {
+    part?: string;
+    at?: string;
+  }) => ParseContext;
+};
+type ParseWarningCollector = {
+  context: ParseContext;
+  /**
+   * Everything recorded, in the order it was recorded, followed by one entry
+   * per code whose occurrences ran past the cap. Deterministic: the same
+   * document yields the same list.
+   */
+  warnings: () => ParseWarning[];
+};
+declare const createParseWarningCollector: (part?: string) => ParseWarningCollector;
+//#endregion
+export { ParseContext, ParseWarningCollector, ParseWarningReport, createParseWarningCollector };

package/dist/docx/parseContext.js

@@ -0,0 +1,67 @@
+import { MAX_RETAINED_PARSE_WARNINGS_PER_CODE } from "@stll/docx-core/model";
+//#region src/docx/parseContext.ts
+/**
+* The channel a parser reports a normalisation through.
+*
+* Folio accepts input Word accepts, which means normalising at the parse
+* boundary rather than refusing. Every such decision has to be visible, and
+* before this the only place that could say so was `parseDocx` itself: the
+* leaf readers are pure functions with no way to report, so a value outside
+* `ST_OnOff` or a `w:type` outside `ST_HdrFtr` was normalised in silence.
+*
+* The context is an explicit parameter, never a module-level accumulator and
+* never async-local storage. Parsers stay re-entrant, a test can hand one in
+* and read what a single reader reported, and two documents parsed at once
+* cannot write into each other's list. The cost is a threaded argument, which
+* is also the thing that makes the reporting greppable.
+*/
+const PACKAGE_PART = "package";
+const createParseWarningCollector = (part = PACKAGE_PART) => {
+	const retained = [];
+	const retainedByCode = /* @__PURE__ */ new Map();
+	const suppressedByCode = /* @__PURE__ */ new Map();
+	const record = (location, report) => {
+		const count = report.count ?? 1;
+		const kept = retainedByCode.get(report.code) ?? 0;
+		if (kept >= MAX_RETAINED_PARSE_WARNINGS_PER_CODE) {
+			suppressedByCode.set(report.code, (suppressedByCode.get(report.code) ?? 0) + count);
+			return;
+		}
+		retainedByCode.set(report.code, kept + 1);
+		retained.push({
+			code: report.code,
+			location: {
+				...location,
+				...report.element === void 0 ? {} : { element: report.element },
+				...report.at === void 0 ? {} : { at: report.at }
+			},
+			...report.value === void 0 ? {} : { value: report.value },
+			...report.detail === void 0 ? {} : { detail: report.detail },
+			count
+		});
+	};
+	const contextAt = (location) => ({
+		warn: (report) => {
+			record(location, report);
+		},
+		scoped: (next) => {
+			const at = next.at ?? location.at;
+			return contextAt({
+				part: next.part ?? location.part,
+				...location.element === void 0 ? {} : { element: location.element },
+				...at === void 0 ? {} : { at }
+			});
+		}
+	});
+	return {
+		context: contextAt({ part }),
+		warnings: () => [...retained, ...[...suppressedByCode.entries()].sort(([left], [right]) => left < right ? -1 : 1).map(([code, count]) => ({
+			code,
+			location: { part },
+			count,
+			detail: `${String(count)} further occurrence(s) were counted but not retained.`
+		}))]
+	};
+};
+//#endregion
+export { createParseWarningCollector };

package/dist/docx/parseWarningMessage.d.ts

@@ -0,0 +1,6 @@
+import { ParseWarning } from "@stll/docx-core/model";
+//#region src/docx/parseWarningMessage.d.ts
+declare const formatParseWarning: (warning: ParseWarning) => string;
+declare const formatParseWarnings: (warnings: readonly ParseWarning[]) => string[];
+//#endregion
+export { formatParseWarning, formatParseWarnings };

package/dist/docx/parseWarningMessage.js

@@ -0,0 +1,44 @@
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
+//#region src/docx/parseWarningMessage.ts
+/**
+* The one place a parse warning becomes a sentence.
+*
+* `Document.warnings` is the string list hosts have always read, and it is now
+* rendered from `Document.parseWarnings` rather than written at the call site,
+* so a warning cannot say one thing in the structured list and another in the
+* prose. The map is total over the code union: a new code does not compile
+* until it has a message.
+*/
+const plural = (count, singular, pluralForm = `${singular}s`) => `${String(count)} ${count === 1 ? singular : pluralForm}`;
+/** The location suffix, omitted when the part is all we know. */
+const where = ({ location }) => {
+	if (location.at === void 0) return "";
+	return ` at ${location.at} in ${location.part}`;
+};
+const quoted = (value) => value === void 0 ? "" : ` "${value}"`;
+const PARSE_WARNING_MESSAGES = {
+	[PARSE_WARNING_CODES.packageDecrypted]: () => "Document was opened from password-protected storage; saving writes an unencrypted .docx file.",
+	[PARSE_WARNING_CODES.packageArchive]: (warning) => warning.detail ?? "The archive reader reported an issue.",
+	[PARSE_WARNING_CODES.documentPartMissing]: () => "No document.xml found in DOCX",
+	[PARSE_WARNING_CODES.documentModelIssue]: (warning) => warning.detail ?? "The document model reported an issue.",
+	[PARSE_WARNING_CODES.duplicateCommentId]: (warning) => `Dropped ${plural(warning.count, "comment")} repeating a w:id another comment already defines.`,
+	[PARSE_WARNING_CODES.missingCommentId]: (warning) => `Dropped ${plural(warning.count, "comment")} with no readable w:id.`,
+	[PARSE_WARNING_CODES.duplicateNoteId]: (warning) => `Dropped ${plural(warning.count, "note")} repeating a w:id another note already defines.`,
+	[PARSE_WARNING_CODES.danglingCommentReference]: (warning) => `Removed ${plural(warning.count, "dangling comment reference marker")} whose comments.xml entries are missing.`,
+	[PARSE_WARNING_CODES.unbalancedCommentRange]: (warning) => `Re-anchored ${plural(warning.count, "unbalanced comment range marker")} as point comments.`,
+	[PARSE_WARNING_CODES.danglingHeaderReference]: (warning) => `Removed ${plural(warning.count, "dangling header reference")} whose header parts are missing.`,
+	[PARSE_WARNING_CODES.danglingFooterReference]: (warning) => `Removed ${plural(warning.count, "dangling footer reference")} whose footer parts are missing.`,
+	[PARSE_WARNING_CODES.danglingRelationshipId]: (warning) => `Left relationship id${quoted(warning.value)} unresolved${where(warning)}; the part defines no such relationship.`,
+	[PARSE_WARNING_CODES.unnumberedParagraph]: (warning) => `Unnumbered ${plural(warning.count, "paragraph")} whose numbering definitions are missing.`,
+	[PARSE_WARNING_CODES.unnumberedStyle]: (warning) => `Unnumbered style${quoted(warning.value)} whose numbering definition is missing.`,
+	[PARSE_WARNING_CODES.unbalancedMoveRange]: (warning) => `Removed ${plural(warning.count, "unbalanced tracked move range marker")}.`,
+	[PARSE_WARNING_CODES.headerFooterTypeOutsideEnum]: (warning) => `Read header/footer type${quoted(warning.value)} as "default"${where(warning)}; ST_HdrFtr is even, default or first.`,
+	[PARSE_WARNING_CODES.unrecognisedOnOffValue]: (warning) => `Ignored on/off value${quoted(warning.value)}${where(warning)}; ST_OnOff is 1, 0, true, false, on or off.`,
+	[PARSE_WARNING_CODES.borderWithoutValue]: (warning) => `Read a border with no w:val${where(warning)} as having no border style.`,
+	[PARSE_WARNING_CODES.styleSetDuplicateStyleId]: (warning) => `Dropped a style repeating the id${quoted(warning.value)} another style in the set already defines.`,
+	[PARSE_WARNING_CODES.styleSetInitialStyleMissing]: (warning) => `The style set names initial paragraph style${quoted(warning.value)}, which it does not contain; used the set's default instead${where(warning)}.`
+};
+const formatParseWarning = (warning) => PARSE_WARNING_MESSAGES[warning.code](warning);
+const formatParseWarnings = (warnings) => warnings.map(formatParseWarning);
+//#endregion
+export { formatParseWarning, formatParseWarnings };