@stll/folio-core 0.43.0 → 0.45.0

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 };

package/dist/docx/parser.js

@@ -1,35 +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 { normalizeCommentIds } from "./commentIdNormalization.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, normalizeStyleNumberingReferences } 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 { enforcePackagePreviewBudget } from "./previewBudget.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
@@ -70,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();
@@ -81,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());
@@ -114,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;
@@ -131,15 +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) warnings.push(`Dropped ${commentIdNormalization.droppedDuplicateComments} comment(s) repeating a w:id another comment already defines.`);
+		if (commentIdNormalization.droppedDuplicateComments > 0) commentsContext.warn({
+			code: DUPLICATE_COMMENT_ID_WARNING,
+			count: commentIdNormalization.droppedDuplicateComments
+		});
 		if (comments.length > 0) documentBody.comments = comments;
 		normalizeDrawingIds({
 			documentBody,
@@ -165,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,
@@ -182,12 +205,33 @@ async function parseDocx(input, options = {}) {
 			...footnotes !== void 0 ? { footnotes } : {},
 			...endnotes !== void 0 ? { endnotes } : {}
 		});
-		if (numberingReferenceNormalization.unnumberedDanglingReferences > 0) warnings.push(`Unnumbered ${numberingReferenceNormalization.unnumberedDanglingReferences} paragraph(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) warnings.push(`Unnumbered style "${styleId}" whose numbering definition is missing.`);
+		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 } : {},
@@ -195,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);
@@ -234,12 +281,19 @@ async function parseDocx(input, options = {}) {
 			...requiredFonts.length > 0 ? { requiredFonts } : {}
 		};
 		assignDocumentParagraphPropertySourceContract(document, await paragraphPropertySourceDigest);
-		enforcePackageVmlPreviewBudget(document.package);
+		enforcePackagePreviewBudget(document.package);
 		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) {
@@ -418,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") {
@@ -437,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);
 		}
 	}
@@ -449,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/previewBudget.d.ts

@@ -0,0 +1,64 @@
+//#region src/docx/previewBudget.d.ts
+/**
+ * Every synthetic preview a parse attaches to the model, and the budget each
+ * one answers to.
+ *
+ * A preview is not document content. It is a drawing folio makes up so a shape
+ * it cannot project still occupies the page, and the package round-trips from
+ * its preserved XML whether the preview exists or not. So a preview is the one
+ * thing in the model that may be dropped, and a package that would retain more
+ * of it than it is worth has it dropped rather than being refused.
+ *
+ * Producer and budget have to agree on what a preview looks like. They used to
+ * agree by coincidence: the VML producer wrote its filename as a literal and
+ * the budget recognized it as a constant in another file, so renaming one
+ * would have stopped the other charging for it without anything failing. The
+ * table below is that agreement written once, and a producer builds its image
+ * out of the entry the budget matches against.
+ */
+declare const VML_PREVIEW_DATA_URL_PREFIX = "data:image/svg+xml;charset=utf-8,";
+declare const PREVIEW_KINDS: {
+  /** A VML shape folio renders rather than projects (`v:shape`, `v:rect`, ...). */
+  readonly vmlShape: {
+    readonly mimeType: "image/svg+xml";
+    readonly filename: "vml-shape-preview.svg";
+    readonly srcPrefix: "data:image/svg+xml;charset=utf-8,";
+    readonly maxPackageCharacters: number;
+  };
+  /**
+   * A SmartArt diagram: its extent filled with one flat rectangle per shape.
+   *
+   * A raster rather than a vector because the display list decodes only base64
+   * PNG and JPEG, so a vector preview would be missing from every display-list
+   * backend (PDF among them) while still showing in the DOM. That is what
+   * makes this preview expensive: one of them is 7.3 MB of data URL whatever
+   * the package weighs, because its cost follows the extent the author chose
+   * rather than anything the drawing contains.
+   *
+   * Across the public corpus, the fifty packages that produce one retain a
+   * median of 7.3 MB and a maximum of 51.3 MB (ten previews, from a package
+   * under a megabyte). The cap is set above that maximum: it refuses no
+   * legitimate file in the corpus while bounding what had no bound at all, and
+   * it is a ceiling rather than a fix. The fix is for the preview to be a
+   * descriptor the renderer rasterizes, which needs the display-list contract
+   * to carry one.
+   */
+  readonly smartArt: {
+    readonly mimeType: "image/png";
+    readonly filename: "smartart-preview.png";
+    readonly srcPrefix: "data:image/png;base64,";
+    readonly maxPackageCharacters: number;
+  };
+};
+type PreviewKindName = keyof typeof PREVIEW_KINDS;
+/** Per-kind allowances for one package, defaulting to the table's caps. */
+type PreviewBudgetOverrides = Partial<Record<PreviewKindName, number>>;
+/**
+ * Charge every generated preview in the model against its kind's allowance and
+ * drop the `src` of those past it. Dropping leaves the image in place with its
+ * size and wrap, so the page still reserves the space the drawing occupies,
+ * and never touches the preserved XML the package saves from.
+ */
+declare const enforcePackagePreviewBudget: (root: unknown, overrides?: PreviewBudgetOverrides) => void;
+//#endregion
+export { PREVIEW_KINDS, PreviewBudgetOverrides, VML_PREVIEW_DATA_URL_PREFIX, enforcePackagePreviewBudget };

package/dist/docx/previewBudget.js

@@ -0,0 +1,88 @@
+//#region src/docx/previewBudget.ts
+const VML_PREVIEW_DATA_URL_PREFIX = "data:image/svg+xml;charset=utf-8,";
+const MEBIBYTE = 1024 * 1024;
+const PREVIEW_KINDS = {
+	/** A VML shape folio renders rather than projects (`v:shape`, `v:rect`, ...). */
+	vmlShape: {
+		mimeType: "image/svg+xml",
+		filename: "vml-shape-preview.svg",
+		srcPrefix: VML_PREVIEW_DATA_URL_PREFIX,
+		maxPackageCharacters: 8 * MEBIBYTE
+	},
+	/**
+	* A SmartArt diagram: its extent filled with one flat rectangle per shape.
+	*
+	* A raster rather than a vector because the display list decodes only base64
+	* PNG and JPEG, so a vector preview would be missing from every display-list
+	* backend (PDF among them) while still showing in the DOM. That is what
+	* makes this preview expensive: one of them is 7.3 MB of data URL whatever
+	* the package weighs, because its cost follows the extent the author chose
+	* rather than anything the drawing contains.
+	*
+	* Across the public corpus, the fifty packages that produce one retain a
+	* median of 7.3 MB and a maximum of 51.3 MB (ten previews, from a package
+	* under a megabyte). The cap is set above that maximum: it refuses no
+	* legitimate file in the corpus while bounding what had no bound at all, and
+	* it is a ceiling rather than a fix. The fix is for the preview to be a
+	* descriptor the renderer rasterizes, which needs the display-list contract
+	* to carry one.
+	*/
+	smartArt: {
+		mimeType: "image/png",
+		filename: "smartart-preview.png",
+		srcPrefix: "data:image/png;base64,",
+		maxPackageCharacters: 64 * MEBIBYTE
+	}
+};
+const KIND_NAMES = Object.keys(PREVIEW_KINDS);
+/**
+* The kind a model image was generated as, or `undefined` for one the package
+* actually carries. A generated preview has no relationship behind it, so
+* `rId` is empty; the filename and data-URL prefix name which producer made it.
+*/
+const previewKindOf = (value) => {
+	if (!("type" in value) || value.type !== "image" || !("rId" in value) || value.rId !== "" || !("src" in value) || typeof value.src !== "string" || !("mimeType" in value) || !("filename" in value)) return;
+	const { src, mimeType, filename } = value;
+	return KIND_NAMES.find((name) => {
+		const kind = PREVIEW_KINDS[name];
+		return mimeType === kind.mimeType && filename === kind.filename && src.startsWith(kind.srcPrefix);
+	});
+};
+/**
+* Charge every generated preview in the model against its kind's allowance and
+* drop the `src` of those past it. Dropping leaves the image in place with its
+* size and wrap, so the page still reserves the space the drawing occupies,
+* and never touches the preserved XML the package saves from.
+*/
+const enforcePackagePreviewBudget = (root, overrides = {}) => {
+	const remaining = new Map(KIND_NAMES.map((name) => [name, Math.max(0, overrides[name] ?? PREVIEW_KINDS[name].maxPackageCharacters)]));
+	const visited = /* @__PURE__ */ new WeakSet();
+	const visit = (value) => {
+		if (value === null || typeof value !== "object" || visited.has(value)) return;
+		visited.add(value);
+		if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) return;
+		if (value instanceof Map) {
+			for (const child of value.values()) visit(child);
+			return;
+		}
+		if (Array.isArray(value)) {
+			for (const child of value) visit(child);
+			return;
+		}
+		const kind = previewKindOf(value);
+		if (kind !== void 0) {
+			const image = value;
+			const length = image.src.length;
+			const left = remaining.get(kind);
+			if (length <= left) remaining.set(kind, left - length);
+			else {
+				remaining.set(kind, 0);
+				delete image.src;
+			}
+		}
+		for (const child of Object.values(value)) visit(child);
+	};
+	visit(root);
+};
+//#endregion
+export { PREVIEW_KINDS, VML_PREVIEW_DATA_URL_PREFIX, enforcePackagePreviewBudget };

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 };