@stll/folio-core 0.47.7 → 0.48.0

package/dist/docx/paragraphProperties.js

@@ -1,6 +1,6 @@
 import { readAttributeBag } from "./attributeRemainder.js";
 import { parseBorderSpec } from "./borderParser.js";
-import { CAPTURE, dispatchChildren, ownedElsewhere, sequencePositions } from "./containerChildren.js";
+import { CAPTURE, dispatchChildrenWithContext, ownedElsewhere, sequencePositions } from "./containerChildren.js";
 import { readParagraphNumbering } from "./numberingReference.js";
 import { FrameWrapSchema, FrameXAlignSchema, FrameYAlignSchema, LineSpacingRuleSchema, ParagraphAlignmentSchema, TabLeaderSchema, TabStopAlignmentSchema, narrowEnum } from "./parserEnums.js";
 import { FRAME_ATTRIBUTES, INDENTATION_ATTRIBUTES, SPACING_ATTRIBUTES, TAB_STOP_ATTRIBUTES } from "./propertyElementAttributes.js";
@@ -74,6 +74,123 @@ function parseFrameProperties(framePr) {
 	return frame;
 }
 /**
+* The content model declares each property once. A source that states one
+* twice keeps the first as the model's value and the repeat as bytes at the
+* same schema ordinal, rather than letting the second silently win or fall off
+* the end of the walk.
+*/
+const readOnce = (name, read) => (child, { formatting, taken }) => {
+	if (taken.has(name) || !read(child, formatting)) return CAPTURE;
+	taken.add(name);
+};
+const readToggle = (name, field) => readOnce(name, (child, formatting) => {
+	formatting[field] = parseBooleanElement(child);
+	return true;
+});
+/**
+* The `w:pPr` decision map. Built once: every reader takes the record it fills
+* from the walk's context rather than closing over it.
+*/
+const PARAGRAPH_PROPERTY_HANDLERS = {
+	pStyle: readOnce("pStyle", (child, formatting) => {
+		const val = getAttribute(child, "w", "val");
+		if (!val) return false;
+		formatting.styleId = val;
+		return true;
+	}),
+	keepNext: readToggle("keepNext", "keepNext"),
+	keepLines: readToggle("keepLines", "keepLines"),
+	pageBreakBefore: readToggle("pageBreakBefore", "pageBreakBefore"),
+	framePr: readOnce("framePr", (child, formatting) => {
+		const frame = parseFrameProperties(child);
+		if (frame === void 0) return false;
+		formatting.frame = frame;
+		return true;
+	}),
+	widowControl: readToggle("widowControl", "widowControl"),
+	numPr: readOnce("numPr", (child, formatting) => {
+		const stated = readParagraphNumbering(child);
+		if (stated !== void 0) formatting.numPr = stated;
+		const numberingChange = findChild(child, "w", "numberingChange");
+		if (numberingChange) formatting.numberingChangeXml = captureVerbatimXml(numberingChange);
+		const numberingInsertion = findChild(child, "w", "ins");
+		if (numberingInsertion) formatting.numberingInsertionXml = captureVerbatimXml(numberingInsertion);
+		const statedLevel = parseNumericAttribute(findChild(child, "w", "ilvl"), "w", "val");
+		return stated !== void 0 || numberingChange !== null || numberingInsertion !== null || statedLevel === -1;
+	}),
+	suppressLineNumbers: readToggle("suppressLineNumbers", "suppressLineNumbers"),
+	pBdr: readOnce("pBdr", (child, formatting) => {
+		const borders = {};
+		for (const side of PARAGRAPH_BORDER_SIDES) {
+			const border = parseBorderSpec(findChild(child, "w", side));
+			if (border) borders[side] = border;
+		}
+		if (Object.keys(borders).length === 0) return false;
+		formatting.borders = borders;
+		return true;
+	}),
+	shd: readOnce("shd", (child, formatting) => {
+		const shading = parseShading(child);
+		if (shading === void 0) return false;
+		formatting.shading = shading;
+		return true;
+	}),
+	tabs: readOnce("tabs", (child, formatting) => {
+		const tabs = parseTabStops(child);
+		if (tabs === void 0) return false;
+		formatting.tabs = tabs;
+		return true;
+	}),
+	suppressAutoHyphens: readToggle("suppressAutoHyphens", "suppressAutoHyphens"),
+	kinsoku: readToggle("kinsoku", "kinsoku"),
+	wordWrap: CAPTURE,
+	overflowPunct: readToggle("overflowPunct", "overflowPunctuation"),
+	topLinePunct: CAPTURE,
+	autoSpaceDE: CAPTURE,
+	autoSpaceDN: CAPTURE,
+	bidi: readToggle("bidi", "bidi"),
+	adjustRightInd: CAPTURE,
+	snapToGrid: readToggle("snapToGrid", "snapToGrid"),
+	spacing: readOnce("spacing", (child, formatting) => readParagraphSpacing(child, formatting)),
+	ind: readOnce("ind", (child, formatting) => readParagraphIndentation(child, formatting)),
+	contextualSpacing: readToggle("contextualSpacing", "contextualSpacing"),
+	mirrorIndents: CAPTURE,
+	suppressOverlap: CAPTURE,
+	jc: readOnce("jc", (child, formatting) => {
+		const val = narrowEnum(getAttribute(child, "w", "val"), ParagraphAlignmentSchema);
+		if (!val) return false;
+		formatting.alignment = val;
+		return true;
+	}),
+	textDirection: CAPTURE,
+	textAlignment: CAPTURE,
+	textboxTightWrap: CAPTURE,
+	outlineLvl: readOnce("outlineLvl", (child, formatting) => {
+		const val = parseNumericAttribute(child, "w", "val");
+		const level = val === void 0 ? void 0 : outlineLevelFromStatedValue(val);
+		if (level === void 0) return val === -1;
+		formatting.outlineLevel = level;
+		return true;
+	}),
+	divId: CAPTURE,
+	cnfStyle: CAPTURE,
+	rPr: ownedElsewhere({
+		container: "paragraph-properties",
+		child: "rPr",
+		reader: "paragraphProperties#parseParagraphProperties"
+	}),
+	sectPr: ownedElsewhere({
+		container: "paragraph-properties",
+		child: "sectPr",
+		reader: "sectionParser#parseSectionProperties"
+	}),
+	pPrChange: ownedElsewhere({
+		container: "paragraph-properties",
+		child: "pPrChange",
+		reader: "paragraphParser#parseParagraphPropertyChanges"
+	})
+};
+/**
 * Read `w:pPr` into {@link ParagraphFormatting}, every declared child carrying
 * a decision.
 *
@@ -93,117 +210,14 @@ function parseFrameProperties(framePr) {
 function parseParagraphProperties(pPr, theme) {
 	if (!pPr) return;
 	const formatting = {};
-	const taken = /* @__PURE__ */ new Set();
-	const once = (name, read) => (child) => {
-		if (taken.has(name) || !read(child)) return CAPTURE;
-		taken.add(name);
-	};
-	const toggle = (name, field) => once(name, (child) => {
-		formatting[field] = parseBooleanElement(child);
-		return true;
-	});
-	const preserved = dispatchChildren({
+	const preserved = dispatchChildrenWithContext({
 		element: pPr,
 		container: "paragraph-properties",
 		capturePosition: sequencePositions("paragraph-properties", pPr),
-		handlers: {
-			pStyle: once("pStyle", (child) => {
-				const val = getAttribute(child, "w", "val");
-				if (!val) return false;
-				formatting.styleId = val;
-				return true;
-			}),
-			keepNext: toggle("keepNext", "keepNext"),
-			keepLines: toggle("keepLines", "keepLines"),
-			pageBreakBefore: toggle("pageBreakBefore", "pageBreakBefore"),
-			framePr: once("framePr", (child) => {
-				const frame = parseFrameProperties(child);
-				if (frame === void 0) return false;
-				formatting.frame = frame;
-				return true;
-			}),
-			widowControl: toggle("widowControl", "widowControl"),
-			numPr: once("numPr", (child) => {
-				const stated = readParagraphNumbering(child);
-				if (stated !== void 0) formatting.numPr = stated;
-				const numberingChange = findChild(child, "w", "numberingChange");
-				if (numberingChange) formatting.numberingChangeXml = captureVerbatimXml(numberingChange);
-				const numberingInsertion = findChild(child, "w", "ins");
-				if (numberingInsertion) formatting.numberingInsertionXml = captureVerbatimXml(numberingInsertion);
-				const statedLevel = parseNumericAttribute(findChild(child, "w", "ilvl"), "w", "val");
-				return stated !== void 0 || numberingChange !== null || numberingInsertion !== null || statedLevel === -1;
-			}),
-			suppressLineNumbers: toggle("suppressLineNumbers", "suppressLineNumbers"),
-			pBdr: once("pBdr", (child) => {
-				const borders = {};
-				for (const side of PARAGRAPH_BORDER_SIDES) {
-					const border = parseBorderSpec(findChild(child, "w", side));
-					if (border) borders[side] = border;
-				}
-				if (Object.keys(borders).length === 0) return false;
-				formatting.borders = borders;
-				return true;
-			}),
-			shd: once("shd", (child) => {
-				const shading = parseShading(child);
-				if (shading === void 0) return false;
-				formatting.shading = shading;
-				return true;
-			}),
-			tabs: once("tabs", (child) => {
-				const tabs = parseTabStops(child);
-				if (tabs === void 0) return false;
-				formatting.tabs = tabs;
-				return true;
-			}),
-			suppressAutoHyphens: toggle("suppressAutoHyphens", "suppressAutoHyphens"),
-			kinsoku: toggle("kinsoku", "kinsoku"),
-			wordWrap: CAPTURE,
-			overflowPunct: toggle("overflowPunct", "overflowPunctuation"),
-			topLinePunct: CAPTURE,
-			autoSpaceDE: CAPTURE,
-			autoSpaceDN: CAPTURE,
-			bidi: toggle("bidi", "bidi"),
-			adjustRightInd: CAPTURE,
-			snapToGrid: toggle("snapToGrid", "snapToGrid"),
-			spacing: once("spacing", (child) => readParagraphSpacing(child, formatting)),
-			ind: once("ind", (child) => readParagraphIndentation(child, formatting)),
-			contextualSpacing: toggle("contextualSpacing", "contextualSpacing"),
-			mirrorIndents: CAPTURE,
-			suppressOverlap: CAPTURE,
-			jc: once("jc", (child) => {
-				const val = narrowEnum(getAttribute(child, "w", "val"), ParagraphAlignmentSchema);
-				if (!val) return false;
-				formatting.alignment = val;
-				return true;
-			}),
-			textDirection: CAPTURE,
-			textAlignment: CAPTURE,
-			textboxTightWrap: CAPTURE,
-			outlineLvl: once("outlineLvl", (child) => {
-				const val = parseNumericAttribute(child, "w", "val");
-				const level = val === void 0 ? void 0 : outlineLevelFromStatedValue(val);
-				if (level === void 0) return val === -1;
-				formatting.outlineLevel = level;
-				return true;
-			}),
-			divId: CAPTURE,
-			cnfStyle: CAPTURE,
-			rPr: ownedElsewhere({
-				container: "paragraph-properties",
-				child: "rPr",
-				reader: "paragraphProperties#parseParagraphProperties"
-			}),
-			sectPr: ownedElsewhere({
-				container: "paragraph-properties",
-				child: "sectPr",
-				reader: "sectionParser#parseSectionProperties"
-			}),
-			pPrChange: ownedElsewhere({
-				container: "paragraph-properties",
-				child: "pPrChange",
-				reader: "paragraphParser#parseParagraphPropertyChanges"
-			})
+		handlers: PARAGRAPH_PROPERTY_HANDLERS,
+		context: {
+			formatting,
+			taken: /* @__PURE__ */ new Set()
 		}
 	});
 	const rPr = findChild(pPr, "w", "rPr");

package/dist/docx/paragraphPropertySource.d.ts

@@ -111,6 +111,11 @@ declare const recreateProseNodeWithParagraphPropertySource: (source: Node, optio
  * can only name a paragraph in the package it came from.
  */
 declare const recreateProseNodeWithDetachedParagraphPropertySource: (source: Node, options?: RecreateProseNodeOptions) => Node;
+/**
+ * A paragraph's attributes without its durable source token, for a copy of
+ * them that is carried by another node and must not claim the paragraph.
+ */
+declare const proseParagraphAttrsWithoutPropertySource: (attrs: Node["attrs"]) => Node["attrs"];
 type SetProseParagraphMarkupOptions = {
   attrs: Node["attrs"];
   ownership: "preserve" | "transfer-allocated-id";
@@ -129,4 +134,4 @@ declare const linkParagraphPropertySourceCandidate: (target: document_d_exports.
 declare const getParagraphPropertySourceCandidate: (paragraph: document_d_exports.Paragraph) => document_d_exports.Paragraph | undefined;
 declare const getParagraphPropertySourceTransferId: (paragraph: document_d_exports.Paragraph) => string | undefined;
 //#endregion
-export { DecodedTableCellParagraphSourcePayload, PARAGRAPH_PROPERTY_SOURCE_VALIDATION_CODES, PROSE_PARAGRAPH_SOURCE_CONTRACT_ATTR, PROSE_PARAGRAPH_SOURCE_TOKEN_ATTR, ParagraphPropertySourceValidationCode, ParagraphPropertySourceValidationError, TABLE_CELL_PARAGRAPH_SOURCE_BINDING_ATTR, TABLE_CELL_PARAGRAPH_SOURCE_PAYLOAD_ERROR_CLASSIFICATIONS, TableCellParagraphPropertySourceBinding, TableCellParagraphSourcePayloadErrorClassification, assignDocumentParagraphPropertySourceContract, assignParagraphPropertySource, cloneDocumentWithParagraphPropertySources, cloneParagraphWithPropertySource, cloneParagraphWithoutPropertySource, cloneTableCellsWithParagraphPropertyCaptures, copyDocumentParagraphPropertySourceContract, copyDocumentParagraphPropertySources, copyParagraphPropertyCapture, copyParagraphPropertySource, createProseParagraphWithPropertySource, decodeTableCellParagraphSourcePayload, getDocumentParagraphPropertySourceContract, getExplicitParagraphPropertySourceTransfers, getParagraphPropertySource, getParagraphPropertySourceCandidate, getParagraphPropertySourceToken, getParagraphPropertySourceTransferId, getProseDocumentParagraphPropertySourceContract, getProseParagraphPropertySourceToken, isParagraphPropertySourceToken, joinProseParagraphsWithRightPropertySource, linkParagraphPropertySourceCandidate, linkProseParagraphPropertySource, paragraphPropertySourceBelongsToDocument, paragraphPropertySourceMatchesEmission, paragraphPropertySourceTokenMatchesContract, recreateProseNodeWithDetachedParagraphPropertySource, recreateProseNodeWithParagraphPropertySource, restoreTableCellsWithParagraphPropertySources, setProseParagraphMarkupWithPropertySource, transferProseParagraphPropertySource, transportTableCellsWithParagraphPropertySources, visitDocumentStoryParagraphs, visitTableCellParagraphPropertySourceBindings };
+export { DecodedTableCellParagraphSourcePayload, PARAGRAPH_PROPERTY_SOURCE_VALIDATION_CODES, PROSE_PARAGRAPH_SOURCE_CONTRACT_ATTR, PROSE_PARAGRAPH_SOURCE_TOKEN_ATTR, ParagraphPropertySourceValidationCode, ParagraphPropertySourceValidationError, TABLE_CELL_PARAGRAPH_SOURCE_BINDING_ATTR, TABLE_CELL_PARAGRAPH_SOURCE_PAYLOAD_ERROR_CLASSIFICATIONS, TableCellParagraphPropertySourceBinding, TableCellParagraphSourcePayloadErrorClassification, assignDocumentParagraphPropertySourceContract, assignParagraphPropertySource, cloneDocumentWithParagraphPropertySources, cloneParagraphWithPropertySource, cloneParagraphWithoutPropertySource, cloneTableCellsWithParagraphPropertyCaptures, copyDocumentParagraphPropertySourceContract, copyDocumentParagraphPropertySources, copyParagraphPropertyCapture, copyParagraphPropertySource, createProseParagraphWithPropertySource, decodeTableCellParagraphSourcePayload, getDocumentParagraphPropertySourceContract, getExplicitParagraphPropertySourceTransfers, getParagraphPropertySource, getParagraphPropertySourceCandidate, getParagraphPropertySourceToken, getParagraphPropertySourceTransferId, getProseDocumentParagraphPropertySourceContract, getProseParagraphPropertySourceToken, isParagraphPropertySourceToken, joinProseParagraphsWithRightPropertySource, linkParagraphPropertySourceCandidate, linkProseParagraphPropertySource, paragraphPropertySourceBelongsToDocument, paragraphPropertySourceMatchesEmission, paragraphPropertySourceTokenMatchesContract, proseParagraphAttrsWithoutPropertySource, recreateProseNodeWithDetachedParagraphPropertySource, recreateProseNodeWithParagraphPropertySource, restoreTableCellsWithParagraphPropertySources, setProseParagraphMarkupWithPropertySource, transferProseParagraphPropertySource, transportTableCellsWithParagraphPropertySources, visitDocumentStoryParagraphs, visitTableCellParagraphPropertySourceBindings };

package/dist/docx/paragraphPropertySource.js

@@ -662,6 +662,14 @@ const recreateProseNodeWithDetachedParagraphPropertySource = (source, options =
 		} : attrs
 	});
 };
+/**
+* A paragraph's attributes without its durable source token, for a copy of
+* them that is carried by another node and must not claim the paragraph.
+*/
+const proseParagraphAttrsWithoutPropertySource = (attrs) => {
+	const { [PROSE_PARAGRAPH_SOURCE_TOKEN_ATTR]: _token, ...rest } = attrs;
+	return rest;
+};
 /** Replace paragraph markup without losing its private parser-owner link. */
 const setProseParagraphMarkupWithPropertySource = ({ attrs, ownership, pos, transaction }) => {
 	const source = transaction.doc.nodeAt(pos);
@@ -695,4 +703,4 @@ const linkParagraphPropertySourceCandidate = (target, source) => {
 const getParagraphPropertySourceCandidate = (paragraph) => paragraphPropertySourceCandidates.get(paragraph);
 const getParagraphPropertySourceTransferId = (paragraph) => paragraphPropertySourceTransferIds.get(paragraph);
 //#endregion
-export { PARAGRAPH_PROPERTY_SOURCE_VALIDATION_CODES, PROSE_PARAGRAPH_SOURCE_CONTRACT_ATTR, PROSE_PARAGRAPH_SOURCE_TOKEN_ATTR, ParagraphPropertySourceValidationError, TABLE_CELL_PARAGRAPH_SOURCE_BINDING_ATTR, TABLE_CELL_PARAGRAPH_SOURCE_PAYLOAD_ERROR_CLASSIFICATIONS, assignDocumentParagraphPropertySourceContract, assignParagraphPropertySource, cloneDocumentWithParagraphPropertySources, cloneParagraphWithPropertySource, cloneParagraphWithoutPropertySource, cloneTableCellsWithParagraphPropertyCaptures, copyDocumentParagraphPropertySourceContract, copyDocumentParagraphPropertySources, copyParagraphPropertyCapture, copyParagraphPropertySource, createProseParagraphWithPropertySource, decodeTableCellParagraphSourcePayload, getDocumentParagraphPropertySourceContract, getExplicitParagraphPropertySourceTransfers, getParagraphPropertySource, getParagraphPropertySourceCandidate, getParagraphPropertySourceToken, getParagraphPropertySourceTransferId, getProseDocumentParagraphPropertySourceContract, getProseParagraphPropertySourceToken, isParagraphPropertySourceToken, joinProseParagraphsWithRightPropertySource, linkParagraphPropertySourceCandidate, linkProseParagraphPropertySource, paragraphPropertySourceBelongsToDocument, paragraphPropertySourceMatchesEmission, paragraphPropertySourceTokenMatchesContract, recreateProseNodeWithDetachedParagraphPropertySource, recreateProseNodeWithParagraphPropertySource, restoreTableCellsWithParagraphPropertySources, setProseParagraphMarkupWithPropertySource, transferProseParagraphPropertySource, transportTableCellsWithParagraphPropertySources, visitDocumentStoryParagraphs, visitTableCellParagraphPropertySourceBindings };
+export { PARAGRAPH_PROPERTY_SOURCE_VALIDATION_CODES, PROSE_PARAGRAPH_SOURCE_CONTRACT_ATTR, PROSE_PARAGRAPH_SOURCE_TOKEN_ATTR, ParagraphPropertySourceValidationError, TABLE_CELL_PARAGRAPH_SOURCE_BINDING_ATTR, TABLE_CELL_PARAGRAPH_SOURCE_PAYLOAD_ERROR_CLASSIFICATIONS, assignDocumentParagraphPropertySourceContract, assignParagraphPropertySource, cloneDocumentWithParagraphPropertySources, cloneParagraphWithPropertySource, cloneParagraphWithoutPropertySource, cloneTableCellsWithParagraphPropertyCaptures, copyDocumentParagraphPropertySourceContract, copyDocumentParagraphPropertySources, copyParagraphPropertyCapture, copyParagraphPropertySource, createProseParagraphWithPropertySource, decodeTableCellParagraphSourcePayload, getDocumentParagraphPropertySourceContract, getExplicitParagraphPropertySourceTransfers, getParagraphPropertySource, getParagraphPropertySourceCandidate, getParagraphPropertySourceToken, getParagraphPropertySourceTransferId, getProseDocumentParagraphPropertySourceContract, getProseParagraphPropertySourceToken, isParagraphPropertySourceToken, joinProseParagraphsWithRightPropertySource, linkParagraphPropertySourceCandidate, linkProseParagraphPropertySource, paragraphPropertySourceBelongsToDocument, paragraphPropertySourceMatchesEmission, paragraphPropertySourceTokenMatchesContract, proseParagraphAttrsWithoutPropertySource, recreateProseNodeWithDetachedParagraphPropertySource, recreateProseNodeWithParagraphPropertySource, restoreTableCellsWithParagraphPropertySources, setProseParagraphMarkupWithPropertySource, transferProseParagraphPropertySource, transportTableCellsWithParagraphPropertySources, visitDocumentStoryParagraphs, visitTableCellParagraphPropertySourceBindings };

package/dist/docx/paragraphTextBoxEnrichment.d.ts

@@ -2,9 +2,10 @@ import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
 import { ParseContext } from "./parseContext.js";
 import { XmlElement } from "./xmlParser.js";
+import { PreviewLedger } from "./previewBudget.js";
 import { StyleMap } from "./styleParser.js";
 import { TableParserFn } from "./textBoxParser.js";
 //#region src/docx/paragraphTextBoxEnrichment.d.ts
-declare const enrichParagraphTextBoxes: (paragraph: document_d_exports.Paragraph, paraXml: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, numbering: NumberingMap | null, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, parseTable: TableParserFn, context?: ParseContext) => void;
+declare const enrichParagraphTextBoxes: (paragraph: document_d_exports.Paragraph, paraXml: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, numbering: NumberingMap | null, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, parseTable: TableParserFn, previews: PreviewLedger, context?: ParseContext) => void;
 //#endregion
 export { enrichParagraphTextBoxes };

package/dist/docx/paragraphTextBoxEnrichment.js

@@ -121,7 +121,7 @@ const vmlWrapType = (positioned, zIndex) => {
 	if (Number.isFinite(zIndex) && zIndex < 0) return "behind";
 	return "inFront";
 };
-const enrichParagraphTextBoxes = (paragraph, paraXml, styles, theme, numbering, rels, media, parseTable, context) => {
+const enrichParagraphTextBoxes = (paragraph, paraXml, styles, theme, numbering, rels, media, parseTable, previews, context) => {
 	enrichTextBoxRuns({
 		content: paragraph.content,
 		xmlChildren: getChildElements(paraXml),
@@ -131,6 +131,7 @@ const enrichParagraphTextBoxes = (paragraph, paraXml, styles, theme, numbering,
 		rels,
 		media,
 		parseTable,
+		previews,
 		context
 	});
 	paragraph.content = consolidateParagraphContent(paragraph.content);
@@ -140,7 +141,7 @@ const trackedChangeTypeFromXml = (localName) => {
 	if (localName === "del") return "deletion";
 	if (localName === "moveFrom" || localName === "moveTo") return localName;
 };
-const enrichTextBoxRuns = ({ content, xmlChildren, styles, theme, numbering, rels, media, parseTable, context }) => {
+const enrichTextBoxRuns = ({ content, xmlChildren, styles, theme, numbering, rels, media, parseTable, previews, context }) => {
 	let parsedIndex = 0;
 	let lastConsumedRun;
 	for (const xmlChild of xmlChildren) {
@@ -157,6 +158,7 @@ const enrichTextBoxRuns = ({ content, xmlChildren, styles, theme, numbering, rel
 			rels,
 			media,
 			parseTable,
+			previews,
 			context
 		});
 		if (localName === "sdt" && parsedContent?.type === "inlineSdt") {
@@ -179,6 +181,7 @@ const enrichTextBoxRuns = ({ content, xmlChildren, styles, theme, numbering, rel
 				rels,
 				media,
 				parseTable,
+				previews,
 				context
 			});
 			parsedIndex = lastSegmentIndex + 1;
@@ -202,7 +205,7 @@ const enrichTextBoxRuns = ({ content, xmlChildren, styles, theme, numbering, rel
 			const wsp = findDeep(runEl, "wps", "wsp");
 			if (wsp) {
 				const txbxContentEl = getTextBoxContentElement(wsp);
-				if (txbxContentEl) textBox.content = parseTextBoxContent(txbxContentEl, parseParagraph, parseTable, styles, theme, numbering, rels, media);
+				if (txbxContentEl) textBox.content = parseTextBoxContent(txbxContentEl, parseParagraph, parseTable, styles, theme, numbering, rels, media, previews);
 			}
 			const shape = {
 				type: "shape",
@@ -242,7 +245,15 @@ const enrichTextBoxRuns = ({ content, xmlChildren, styles, theme, numbering, rel
 			}
 		}
 		for (const pictEl of vmlTextBoxes) {
-			const shape = parseVmlTextBoxShape(pictEl, styles, theme, numbering, rels, media, parseTable);
+			const shape = parseVmlTextBoxShape(pictEl, {
+				styles,
+				theme,
+				numbering,
+				rels,
+				media,
+				parseTable,
+				previews
+			});
 			if (!shape) continue;
 			const shapeContent = {
 				type: "shape",
@@ -265,7 +276,7 @@ const enrichTextBoxRuns = ({ content, xmlChildren, styles, theme, numbering, rel
 		}
 	}
 };
-const parseVmlTextBoxShape = (pictEl, styles, theme, numbering, rels, media, parseTable) => {
+const parseVmlTextBoxShape = (pictEl, { styles, theme, numbering, rels, media, parseTable, previews }) => {
 	const shapeEl = findDeep(pictEl, "v", "shape");
 	const textBoxEl = shapeEl ? findDeep(shapeEl, "v", "textbox") : null;
 	const contentEl = textBoxEl ? findDeep(textBoxEl, "w", "txbxContent") : null;
@@ -292,7 +303,7 @@ const parseVmlTextBoxShape = (pictEl, styles, theme, numbering, rels, media, par
 		...fill === void 0 ? {} : { fill },
 		wrap: { type: vmlWrapType(positioned, zIndex) },
 		textBody: {
-			content: parseTextBoxContent(contentEl, parseParagraph, parseTable, styles, theme, numbering, rels, media),
+			content: parseTextBoxContent(contentEl, parseParagraph, parseTable, styles, theme, numbering, rels, media, previews),
 			...margins === void 0 ? {} : { margins },
 			...anchor === void 0 ? {} : { anchor }
 		}

package/dist/docx/parser.d.ts

@@ -1,6 +1,7 @@
 import { document_d_exports } from "../types/document.js";
 import { DocxInput } from "../utils/docxInput.js";
 import { DocxUnzipOptions } from "./unzip.js";
+import { PreviewBudgetOverrides } from "./previewBudget.js";
 //#region src/docx/parser.d.ts
 /**
  * Progress callback for tracking parsing stages
@@ -45,6 +46,11 @@ type ParseOptions = {
  * @throws {Error} if parsing fails
  */
 declare function parseDocx(input: DocxInput, options?: ParseOptions): Promise<document_d_exports.Document>;
+/**
+ * {@link parseDocx}, charging the package's previews against `previewBudget`
+ * in place of the default per-kind allowances.
+ */
+declare function parseDocxWithPreviewBudget(input: DocxInput, options: ParseOptions, previewBudget: PreviewBudgetOverrides): Promise<document_d_exports.Document>;
 declare const DocxParseError_base: import("better-result").TaggedErrorClass<"DocxParseError">;
 /** DOCX parsing failure: malformed package, unsupported feature, or
  *  upstream parser exception. Wraps the original cause for diagnostics. */
@@ -80,4 +86,4 @@ declare function getDocxSummary(buffer: ArrayBuffer): Promise<{
   variableCount: number;
 }>;
 //#endregion
-export { DocxParseError, MediaResolver, ParseOptions, ProgressCallback, fullParseDocx, getDocxSummary, getDocxVariables, parseDocx, quickParseDocx };
+export { DocxParseError, MediaResolver, ParseOptions, ProgressCallback, fullParseDocx, getDocxSummary, getDocxVariables, parseDocx, parseDocxWithPreviewBudget, quickParseDocx };

package/dist/docx/parser.js

@@ -23,7 +23,7 @@ import { UNNUMBERED_PARAGRAPH_WARNING, UNNUMBERED_STYLE_WARNING, normalizeNumber
 import { assignDocumentParagraphPropertySourceContract } from "./paragraphPropertySource.js";
 import { createParseWarningCollector } from "./parseContext.js";
 import { formatParseWarnings } from "./parseWarningMessage.js";
-import { enforcePackagePreviewBudget } from "./previewBudget.js";
+import { createPackagePreviewBudget } from "./previewBudget.js";
 import { RELATIONSHIP_TYPES, parseRelationships, resolveRelativePath } from "./relsParser.js";
 import { normalizeRenderedPageBreakHints } from "./renderedPageBreakNormalization.js";
 import { parseSettings } from "./settingsParser.js";
@@ -71,10 +71,18 @@ const sha256Hex = async (buffer) => {
 * @returns Promise resolving to Document
 * @throws {Error} if parsing fails
 */
-async function parseDocx(input, options = {}) {
+function parseDocx(input, options = {}) {
+	return parseDocxWithPreviewBudget(input, options, {});
+}
+/**
+* {@link parseDocx}, charging the package's previews against `previewBudget`
+* in place of the default per-kind allowances.
+*/
+async function parseDocxWithPreviewBudget(input, options, previewBudget) {
 	const buffer = input instanceof ArrayBuffer ? input : await toArrayBuffer(input);
 	const { onProgress = () => {}, preloadFonts = true, parseHeadersFooters = true, parseNotes = true, detectVariables = true, password, unzipLimits, mediaResolver } = options;
 	const { context: parseContext, warnings: collectedWarnings } = createParseWarningCollector();
+	const previews = createPackagePreviewBudget();
 	try {
 		const timeStage = (_name, fn) => fn();
 		const timeStageAsync = async (_name, fn) => await fn();
@@ -121,7 +129,7 @@ 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, parseContext.scoped({ part: "word/document.xml" }));
+			if (raw.documentXml) documentBody = parseDocumentBody(raw.documentXml, styles, theme, numbering, rels, media, parseContext.scoped({ part: "word/document.xml" }), previews.ledger);
 			else parseContext.warn({ code: PARSE_WARNING_CODES.documentPartMissing });
 		});
 		onProgress("Parsed document body", 55);
@@ -129,7 +137,7 @@ async function parseDocx(input, options = {}) {
 		let footers;
 		if (parseHeadersFooters) {
 			onProgress("Parsing headers/footers...", 55);
-			const hf = timeStage("headersFooters", () => parseHeadersAndFooters(raw, styles, theme, numbering, rels, media));
+			const hf = timeStage("headersFooters", () => parseHeadersAndFooters(raw, styles, theme, numbering, rels, media, previews.ledger));
 			headers = hf.headers;
 			footers = hf.footers;
 			onProgress("Parsed headers/footers", 65);
@@ -138,15 +146,20 @@ 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, parseContext));
+			const notes = timeStage("footnotesEndnotes", () => parseNotesContent(raw, styles, theme, numbering, rels, media, parseContext, previews.ledger));
 			footnotes = notes.footnotes;
 			endnotes = notes.endnotes;
 			onProgress("Parsed footnotes/endnotes", 75);
 		} else onProgress("Skipping footnotes/endnotes", 75);
 		onProgress("Parsing comments...", 75);
 		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 comments = timeStage("comments", () => parseComments(raw.commentsXml, styles, theme, rels, media, raw.commentsExtensibleXml, raw.commentsExtendedXml, commentsContext, previews.ledger));
+		const parsedComments = [...comments];
 		const commentIdNormalization = normalizeCommentIds(comments);
+		if (commentIdNormalization.droppedDuplicateComments > 0) {
+			const kept = new Set(comments);
+			previews.ledger.release(parsedComments.filter((comment) => !kept.has(comment)));
+		}
 		if (commentIdNormalization.droppedDuplicateComments > 0) commentsContext.warn({
 			code: DUPLICATE_COMMENT_ID_WARNING,
 			count: commentIdNormalization.droppedDuplicateComments
@@ -281,7 +294,7 @@ async function parseDocx(input, options = {}) {
 			...requiredFonts.length > 0 ? { requiredFonts } : {}
 		};
 		assignDocumentParagraphPropertySourceContract(document, await paragraphPropertySourceDigest);
-		enforcePackagePreviewBudget(document.package);
+		previews.enforce(previewBudget);
 		const validation = validateFolioDocumentModel(document);
 		const parsedCompleteModel = parseHeadersFooters && parseNotes;
 		if (!validation.valid && parsedCompleteModel) throw new DocxModelValidationError("Parsed DOCX produced an invalid document model", validation.issues);
@@ -463,7 +476,7 @@ function getHeaderFooterXml(raw, partPath, indexedParts) {
 	const filename = partPath.split("/").pop() ?? partPath;
 	return getMapCaseInsensitive(raw.allXml, partPath) ?? getMapCaseInsensitive(indexedParts, filename);
 }
-function parseHeadersAndFooters(raw, styles, theme, numbering, rels, media) {
+function parseHeadersAndFooters(raw, styles, theme, numbering, rels, media, previews) {
 	const headers = /* @__PURE__ */ new Map();
 	const footers = /* @__PURE__ */ new Map();
 	for (const [rId, rel] of rels.entries()) if (rel.type === RELATIONSHIP_TYPES.header && rel.target) {
@@ -473,7 +486,7 @@ function parseHeadersAndFooters(raw, styles, theme, numbering, rels, media) {
 			const headerRelsPath = getRelationshipsPathForPart(partPath);
 			const headerRelsXml = getMapCaseInsensitive(raw.allXml, headerRelsPath);
 			const headerRels = headerRelsXml ? parseRelationships(headerRelsXml) : /* @__PURE__ */ new Map();
-			const header = parseHeader(headerXml, "default", styles, theme, numbering, headerRels, media);
+			const header = parseHeader(headerXml, "default", styles, theme, numbering, headerRels, media, previews);
 			const watermark = header.watermark;
 			if (watermark?.kind === "picture") {
 				const imageRel = headerRels.get(watermark.imageRId);
@@ -491,7 +504,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) : /* @__PURE__ */ new Map(), media);
+			const footer = parseFooter(footerXml, "default", styles, theme, numbering, footerRelsXml ? parseRelationships(footerRelsXml) : /* @__PURE__ */ new Map(), media, previews);
 			footers.set(rId, footer);
 		}
 	}
@@ -503,16 +516,20 @@ function parseHeadersAndFooters(raw, styles, theme, numbering, rels, media) {
 /**
 * Parse footnotes and endnotes from raw content
 */
-function parseNotesContent(raw, styles, theme, numbering, rels, media, context) {
+function parseNotesContent(raw, styles, theme, numbering, rels, media, context, previews) {
 	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, 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" }));
+	const footnoteMap = parseFootnotes(raw.footnotesXml, styles, theme, numbering, relsForNotePart("word/footnotes.xml"), media, context.scoped({ part: "word/footnotes.xml" }), previews);
+	const endnoteMap = parseEndnotes(raw.endnotesXml, styles, theme, numbering, relsForNotePart("word/endnotes.xml"), media, context.scoped({ part: "word/endnotes.xml" }), previews);
+	const footnotes = footnoteMap.getNormalFootnotes();
+	const endnotes = endnoteMap.getNormalEndnotes();
+	previews.release(footnoteMap.footnotes.filter((note) => !footnotes.includes(note)));
+	previews.release(endnoteMap.endnotes.filter((note) => !endnotes.includes(note)));
 	return {
-		footnotes: footnoteMap.getNormalFootnotes(),
-		endnotes: endnoteMap.getNormalEndnotes()
+		footnotes,
+		endnotes
 	};
 }
 /**
@@ -590,4 +607,4 @@ async function getDocxSummary(buffer) {
 	};
 }
 //#endregion
-export { DocxParseError, fullParseDocx, getDocxSummary, getDocxVariables, parseDocx, quickParseDocx };
+export { DocxParseError, fullParseDocx, getDocxSummary, getDocxVariables, parseDocx, parseDocxWithPreviewBudget, quickParseDocx };