@stll/folio-core 0.47.7 → 0.48.0

package/dist/docx/hyperlinkParser.js

@@ -1,7 +1,8 @@
 import { sanitizeExternalUrl } from "../utils/urlSecurity.js";
-import { CAPTURE, dispatchChildren, ownedElsewhere, withPreservedChildren } from "./containerChildren.js";
+import { CAPTURE, dispatchChildrenWithContext, ownedElsewhere, withPreservedChildren } from "./containerChildren.js";
 import { inlineWrapperOf } from "./inlineWrapperParser.js";
 import { preserveInlineChild, preservedInlineCapture } from "./preservedRunContent.js";
+import { standalonePreviewLedger } from "./previewBudget.js";
 import { RELATIONSHIP_TYPES, resolveRelationshipIdOfType } from "./relsParser.js";
 import { parseRun } from "./runParser.js";
 import { runHoldsPayload } from "./runPayload.js";
@@ -44,9 +45,40 @@ function parseBookmarkEnd(node) {
 * @param styles - Style map for resolving run styles
 * @param theme - Theme for resolving colors/fonts
 * @param media - Media files map for image data
+* @param previews - The ledger of the package this link belongs to; a link
+*   read on its own charges its previews to no package
 * @returns Parsed Hyperlink object
 */
-function parseHyperlink(node, rels, styles = null, theme = null, media = null, rootXmlns = {}) {
+function parseHyperlink(node, rels, styles = null, theme = null, media = null, rootXmlns = {}, previews = standalonePreviewLedger()) {
+	const hyperlink = parseHyperlinkShell(node, rels);
+	const inScopeXmlns = mergeXmlnsDeclarations(rootXmlns, node);
+	const children = [];
+	hyperlink.children = withPreservedChildren(children, dispatchChildrenWithContext({
+		element: node,
+		container: "w:hyperlink",
+		capturePosition: () => children.length,
+		handlers: HYPERLINK_CHILD_HANDLERS,
+		context: {
+			push: (child) => {
+				children.push(child);
+			},
+			styles,
+			theme,
+			rels,
+			media,
+			previews,
+			inScopeXmlns
+		}
+	}), preservedInlineCapture);
+	return hyperlink;
+}
+/**
+* A `w:hyperlink`'s own attributes as a link with no children yet.
+*
+* The paragraph parser's revision-segmenting walk reads the children itself,
+* so it takes the shell rather than a link whose children it would discard.
+*/
+function parseHyperlinkShell(node, rels) {
 	const hyperlink = {
 		type: "hyperlink",
 		children: []
@@ -72,25 +104,12 @@ function parseHyperlink(node, rels, styles = null, theme = null, media = null, r
 	if (history !== void 0) hyperlink.history = history;
 	const docLocation = getAttribute(node, "w", "docLocation");
 	if (docLocation) hyperlink.docLocation = docLocation;
-	const inScopeXmlns = mergeXmlnsDeclarations(rootXmlns, node);
-	const children = [];
-	hyperlink.children = withPreservedChildren(children, dispatchChildren({
-		element: node,
-		container: "w:hyperlink",
-		capturePosition: () => children.length,
-		handlers: hyperlinkChildHandlers({
-			push: (child) => {
-				children.push(child);
-			},
-			styles,
-			theme,
-			rels,
-			media,
-			inScopeXmlns
-		})
-	}), preservedInlineCapture);
 	return hyperlink;
 }
+/** A transparent wrapper the link holds, read as the wrapper it is. */
+const linkedInlineWrapper = (element) => (child, context) => {
+	context.push(parseLinkedInlineWrapper(element, child, context));
+};
 /**
 * What a `w:hyperlink` does with every child its content model declares.
 *
@@ -108,56 +127,50 @@ function parseHyperlink(node, rels, styles = null, theme = null, media = null, r
 * recognising is recognised by all of them rather than by whichever list
 * somebody remembered to update.
 */
-const hyperlinkChildHandlers = (context) => {
-	const { push, styles, theme, rels, media, inScopeXmlns } = context;
-	const wrapper = (element) => (child) => {
-		push(parseLinkedInlineWrapper(element, child, context));
-	};
-	return {
-		r: (child) => {
-			const run = parseRun(child, styles, theme, rels, media, inScopeXmlns);
-			if (runHoldsPayload(run)) push(run);
-		},
-		bookmarkStart: (child) => {
-			push(parseBookmarkStart(child));
-		},
-		bookmarkEnd: (child) => {
-			push(parseBookmarkEnd(child));
-		},
-		bdo: wrapper("bdo"),
-		dir: wrapper("dir"),
-		customXml: wrapper("customXml"),
-		smartTag: wrapper("smartTag"),
-		del: CAPTURE,
-		ins: CAPTURE,
-		moveFrom: CAPTURE,
-		moveTo: CAPTURE,
-		commentRangeEnd: CAPTURE,
-		commentRangeStart: CAPTURE,
-		customXmlDelRangeEnd: CAPTURE,
-		customXmlDelRangeStart: CAPTURE,
-		customXmlInsRangeEnd: CAPTURE,
-		customXmlInsRangeStart: CAPTURE,
-		customXmlMoveFromRangeEnd: CAPTURE,
-		customXmlMoveFromRangeStart: CAPTURE,
-		customXmlMoveToRangeEnd: CAPTURE,
-		customXmlMoveToRangeStart: CAPTURE,
-		fldSimple: (child) => {
-			push(preserveInlineChild(child));
-		},
-		hyperlink: (child) => {
-			push(preserveInlineChild(child));
-		},
-		moveFromRangeEnd: CAPTURE,
-		moveFromRangeStart: CAPTURE,
-		moveToRangeEnd: CAPTURE,
-		moveToRangeStart: CAPTURE,
-		permEnd: CAPTURE,
-		permStart: CAPTURE,
-		proofErr: CAPTURE,
-		sdt: CAPTURE,
-		subDoc: CAPTURE
-	};
+const HYPERLINK_CHILD_HANDLERS = {
+	r: (child, { push, styles, theme, rels, media, previews, inScopeXmlns }) => {
+		const run = parseRun(child, styles, theme, rels, media, inScopeXmlns, previews);
+		if (runHoldsPayload(run)) push(run);
+	},
+	bookmarkStart: (child, { push }) => {
+		push(parseBookmarkStart(child));
+	},
+	bookmarkEnd: (child, { push }) => {
+		push(parseBookmarkEnd(child));
+	},
+	bdo: linkedInlineWrapper("bdo"),
+	dir: linkedInlineWrapper("dir"),
+	customXml: linkedInlineWrapper("customXml"),
+	smartTag: linkedInlineWrapper("smartTag"),
+	del: CAPTURE,
+	ins: CAPTURE,
+	moveFrom: CAPTURE,
+	moveTo: CAPTURE,
+	commentRangeEnd: CAPTURE,
+	commentRangeStart: CAPTURE,
+	customXmlDelRangeEnd: CAPTURE,
+	customXmlDelRangeStart: CAPTURE,
+	customXmlInsRangeEnd: CAPTURE,
+	customXmlInsRangeStart: CAPTURE,
+	customXmlMoveFromRangeEnd: CAPTURE,
+	customXmlMoveFromRangeStart: CAPTURE,
+	customXmlMoveToRangeEnd: CAPTURE,
+	customXmlMoveToRangeStart: CAPTURE,
+	fldSimple: (child, { push }) => {
+		push(preserveInlineChild(child));
+	},
+	hyperlink: (child, { push }) => {
+		push(preserveInlineChild(child));
+	},
+	moveFromRangeEnd: CAPTURE,
+	moveFromRangeStart: CAPTURE,
+	moveToRangeEnd: CAPTURE,
+	moveToRangeStart: CAPTURE,
+	permEnd: CAPTURE,
+	permStart: CAPTURE,
+	proofErr: CAPTURE,
+	sdt: CAPTURE,
+	subDoc: CAPTURE
 };
 const LINKED_SMART_TAG_PROPERTIES_OWNER = ownedElsewhere({
 	container: "run-level-content",
@@ -169,6 +182,12 @@ const LINKED_CUSTOM_XML_PROPERTIES_OWNER = ownedElsewhere({
 	child: "customXmlPr",
 	reader: "inlineWrapperParser#inlineWrapperOf"
 });
+const LINKED_INLINE_WRAPPER_HANDLERS = {
+	...HYPERLINK_CHILD_HANDLERS,
+	customXmlPr: LINKED_CUSTOM_XML_PROPERTIES_OWNER,
+	smartTagPr: LINKED_SMART_TAG_PROPERTIES_OWNER,
+	pPr: CAPTURE
+};
 /**
 * A transparent wrapper a link holds, with the content the link would hold.
 *
@@ -185,21 +204,17 @@ const LINKED_CUSTOM_XML_PROPERTIES_OWNER = ownedElsewhere({
 const parseLinkedInlineWrapper = (element, node, context) => {
 	const inScopeXmlns = mergeXmlnsDeclarations(context.inScopeXmlns, node);
 	const content = [];
-	return inlineWrapperOf(element, node, withPreservedChildren(content, dispatchChildren({
+	return inlineWrapperOf(element, node, withPreservedChildren(content, dispatchChildrenWithContext({
 		element: node,
 		container: "run-level-content",
 		capturePosition: () => content.length,
-		handlers: {
-			...hyperlinkChildHandlers({
-				...context,
-				inScopeXmlns,
-				push: (child) => {
-					content.push(child);
-				}
-			}),
-			customXmlPr: LINKED_CUSTOM_XML_PROPERTIES_OWNER,
-			smartTagPr: LINKED_SMART_TAG_PROPERTIES_OWNER,
-			pPr: CAPTURE
+		handlers: LINKED_INLINE_WRAPPER_HANDLERS,
+		context: {
+			...context,
+			inScopeXmlns,
+			push: (child) => {
+				content.push(child);
+			}
 		}
 	}), preservedInlineCapture));
 };
@@ -346,4 +361,4 @@ function createExternalHyperlink(url, children, options) {
 	};
 }
 //#endregion
-export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, hyperlinkChildHandlers, isExternalLink, isInternalLink, parseHyperlink, resolveHyperlinkUrl };
+export { HYPERLINK_CHILD_HANDLERS, createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, isExternalLink, isInternalLink, parseHyperlink, parseHyperlinkShell, resolveHyperlinkUrl };

package/dist/docx/numberingParser.js

@@ -1,5 +1,5 @@
 import { DERIVED_PART_ROOT_ATTRIBUTES, attributeRemainder } from "./attributeRemainder.js";
-import { CAPTURE, dispatchChildren, sequencePositions } from "./containerChildren.js";
+import { CAPTURE, dispatchChildrenWithContext, sequencePositions } from "./containerChildren.js";
 import { isNumberingReference } from "./numberingReference.js";
 import { formatOoxmlCounter, padDecimal } from "./ooxmlCounterFormatter.js";
 import { parseParagraphProperties } from "./paragraphProperties.js";
@@ -25,6 +25,29 @@ const integerValue = (element) => {
 	return parsed === void 0 || !Number.isFinite(parsed) ? void 0 : parsed;
 };
 /**
+* A field read off a sequence child, when the child stated one.
+*
+* `CT_AbstractNum` and `CT_Lvl` are sequences and the serializer writes these
+* fields back in that order, so the sink's index is a count of what has been
+* read and a capture lands between the same two neighbours it sat between.
+*/
+const assignDefined = (target, key, carried) => {
+	if (carried === void 0) return;
+	target[key] = carried;
+};
+const NUMBERING_HANDLERS = {
+	abstractNum: (child, definitions) => {
+		const parsed = parseAbstractNumbering(child);
+		if (parsed) definitions.abstractNums.push(parsed);
+	},
+	num: (child, definitions) => {
+		const parsed = parseNumberingInstance(child);
+		if (parsed) definitions.nums.push(parsed);
+	},
+	numPicBullet: CAPTURE,
+	numIdMacAtCleanup: CAPTURE
+};
+/**
 * Parse numbering.xml into NumberingDefinitions
 *
 * @param numberingXml - Raw XML string from word/numbering.xml (or null if not present)
@@ -38,22 +61,12 @@ function parseNumbering(numberingXml) {
 	if (!numberingXml) return createNumberingMap(definitions);
 	const root = parseXmlDocument(numberingXml);
 	if (!root) return createNumberingMap(definitions);
-	const preserved = dispatchChildren({
+	const preserved = dispatchChildrenWithContext({
 		element: root,
 		container: "w:numbering",
 		capturePosition: sequencePositions("w:numbering", root),
-		handlers: {
-			abstractNum: (child) => {
-				const parsed = parseAbstractNumbering(child);
-				if (parsed) definitions.abstractNums.push(parsed);
-			},
-			num: (child) => {
-				const parsed = parseNumberingInstance(child);
-				if (parsed) definitions.nums.push(parsed);
-			},
-			numPicBullet: CAPTURE,
-			numIdMacAtCleanup: CAPTURE
-		}
+		handlers: NUMBERING_HANDLERS,
+		context: definitions
 	});
 	if (preserved !== void 0) definitions.preserved = preserved;
 	const preservedAttributes = attributeRemainder({
@@ -63,6 +76,18 @@ function parseNumbering(numberingXml) {
 	if (preservedAttributes !== void 0) definitions.preservedAttributes = preservedAttributes;
 	return createNumberingMap(definitions);
 }
+const ABSTRACT_NUM_HANDLERS = {
+	nsid: (child, abstractNum) => assignDefined(abstractNum, "nsid", attributeValue(child)),
+	multiLevelType: (child, abstractNum) => assignDefined(abstractNum, "multiLevelType", narrow(attributeValue(child), MULTI_LEVEL_TYPES)),
+	tmpl: (child, abstractNum) => assignDefined(abstractNum, "tmpl", attributeValue(child)),
+	name: (child, abstractNum) => assignDefined(abstractNum, "name", attributeValue(child)),
+	styleLink: (child, abstractNum) => assignDefined(abstractNum, "styleLink", attributeValue(child)),
+	numStyleLink: (child, abstractNum) => assignDefined(abstractNum, "numStyleLink", attributeValue(child)),
+	lvl: (child, abstractNum) => {
+		const level = parseListLevel(child);
+		if (level) abstractNum.levels.push(level);
+	}
+};
 /**
 * Parse a single w:abstractNum element
 */
@@ -75,26 +100,12 @@ function parseAbstractNumbering(element) {
 		abstractNumId,
 		levels: []
 	};
-	const read = (key, value) => {
-		if (value === void 0) return;
-		abstractNum[key] = value;
-	};
-	const preserved = dispatchChildren({
+	const preserved = dispatchChildrenWithContext({
 		element,
 		container: "w:abstractNum",
 		capturePosition: sequencePositions("w:abstractNum", element),
-		handlers: {
-			nsid: (child) => read("nsid", attributeValue(child)),
-			multiLevelType: (child) => read("multiLevelType", narrow(attributeValue(child), MULTI_LEVEL_TYPES)),
-			tmpl: (child) => read("tmpl", attributeValue(child)),
-			name: (child) => read("name", attributeValue(child)),
-			styleLink: (child) => read("styleLink", attributeValue(child)),
-			numStyleLink: (child) => read("numStyleLink", attributeValue(child)),
-			lvl: (child) => {
-				const level = parseListLevel(child);
-				if (level) abstractNum.levels.push(level);
-			}
-		}
+		handlers: ABSTRACT_NUM_HANDLERS,
+		context: abstractNum
 	});
 	if (preserved !== void 0) abstractNum.preserved = preserved;
 	const preservedAttributes = attributeRemainder({
@@ -113,6 +124,16 @@ const MULTI_LEVEL_TYPES = [
 	"singleLevel"
 ];
 const narrow = (carried, members) => members.find((member) => member === carried);
+const NUMBERING_INSTANCE_HANDLERS = {
+	abstractNumId: (child, walk) => {
+		if (walk.abstractNumId !== void 0) return;
+		walk.abstractNumId = integerValue(child);
+	},
+	lvlOverride: (child, { levelOverrides }) => {
+		const override = parseLevelOverride(child);
+		if (override) levelOverrides.push(override);
+	}
+};
 /**
 * Parse a single w:num element (numbering instance)
 */
@@ -121,23 +142,18 @@ function parseNumberingInstance(element) {
 	if (numIdStr === null) return null;
 	const numId = Number.parseInt(numIdStr, 10);
 	if (Number.isNaN(numId)) return null;
-	const levelOverrides = [];
-	let abstractNumId;
-	const preserved = dispatchChildren({
+	const walk = {
+		abstractNumId: void 0,
+		levelOverrides: []
+	};
+	const preserved = dispatchChildrenWithContext({
 		element,
 		container: "w:num",
 		capturePosition: sequencePositions("w:num", element),
-		handlers: {
-			abstractNumId: (child) => {
-				if (abstractNumId !== void 0) return;
-				abstractNumId = integerValue(child);
-			},
-			lvlOverride: (child) => {
-				const override = parseLevelOverride(child);
-				if (override) levelOverrides.push(override);
-			}
-		}
+		handlers: NUMBERING_INSTANCE_HANDLERS,
+		context: walk
 	});
+	const { abstractNumId, levelOverrides } = walk;
 	if (abstractNumId === void 0) return null;
 	const instance = {
 		numId,
@@ -152,6 +168,16 @@ function parseNumberingInstance(element) {
 	if (preservedAttributes !== void 0) instance.preservedAttributes = preservedAttributes;
 	return instance;
 }
+const LEVEL_OVERRIDE_HANDLERS = {
+	startOverride: (child, override) => {
+		const start = integerValue(child);
+		if (start !== void 0 && override.startOverride === void 0) override.startOverride = start;
+	},
+	lvl: (child, override) => {
+		const level = parseListLevel(child);
+		if (level && override.lvl === void 0) override.lvl = level;
+	}
+};
 /**
 * Parse a single w:lvlOverride element (one level of one numbering instance)
 */
@@ -159,20 +185,12 @@ function parseLevelOverride(element) {
 	const ilvl = parseNumericAttribute(element, "w", "ilvl");
 	if (ilvl === void 0) return null;
 	const override = { ilvl };
-	const preserved = dispatchChildren({
+	const preserved = dispatchChildrenWithContext({
 		element,
 		container: "w:lvlOverride",
 		capturePosition: sequencePositions("w:lvlOverride", element),
-		handlers: {
-			startOverride: (child) => {
-				const start = integerValue(child);
-				if (start !== void 0 && override.startOverride === void 0) override.startOverride = start;
-			},
-			lvl: (child) => {
-				const level = parseListLevel(child);
-				if (level && override.lvl === void 0) override.lvl = level;
-			}
-		}
+		handlers: LEVEL_OVERRIDE_HANDLERS,
+		context: override
 	});
 	if (preserved !== void 0) override.preserved = preserved;
 	const preservedAttributes = attributeRemainder({
@@ -182,6 +200,34 @@ function parseLevelOverride(element) {
 	if (preservedAttributes !== void 0) override.preservedAttributes = preservedAttributes;
 	return override;
 }
+const LIST_LEVEL_HANDLERS = {
+	start: (child, level) => assignDefined(level, "start", integerValue(child)),
+	numFmt: (child, level) => {
+		const resolved = resolveNumFmt(child);
+		if (resolved === null) return CAPTURE;
+		Object.assign(level, resolved);
+	},
+	lvlRestart: (child, level) => assignDefined(level, "lvlRestart", integerValue(child)),
+	pStyle: (child, level) => assignDefined(level, "pStyle", attributeValue(child)),
+	isLgl: (child, level) => assignDefined(level, "isLgl", parseBooleanElement(child)),
+	suff: (child, level) => assignDefined(level, "suffix", narrowEnum(attributeValue(child), LevelSuffixSchema)),
+	lvlText: (child, level) => {
+		assignDefined(level, "lvlText", attributeValue(child) ?? "");
+		const isNull = parseOnOffAttribute(child, "w", "null");
+		if (isNull !== void 0) level.lvlTextNull = isNull;
+	},
+	lvlPicBulletId: (child, level) => assignDefined(level, "lvlPicBulletId", integerValue(child)),
+	legacy: (child, level) => assignDefined(level, "legacy", legacyOf(child)),
+	lvlJc: (child, level) => assignDefined(level, "lvlJc", narrowEnum(attributeValue(child), ParagraphAlignmentSchema)),
+	pPr: (child, level) => assignDefined(level, "pPr", parseParagraphProperties(child, null) ?? {}),
+	rPr: (child, level) => assignDefined(level, "rPr", parseRunProperties(child, null, RUN_PROPERTY_OWNERS.standalone) ?? {})
+};
+/**
+* `mc:AlternateContent` around a custom `w:numFmt` is read for its format by
+* {@link parseListLevel}, and the writer re-emits that format as the level's
+* own `w:numFmt`, so the walk takes it without a capture.
+*/
+const LIST_LEVEL_UNDECLARED = { AlternateContent: () => void 0 };
 /**
 * Parse a single w:lvl element (list level definition)
 */
@@ -194,37 +240,13 @@ function parseListLevel(element) {
 		lvlText: ""
 	};
 	const alternateEl = findChild(element, "mc", "AlternateContent");
-	const read = (key, value) => {
-		if (value === void 0) return;
-		level[key] = value;
-	};
-	const preserved = dispatchChildren({
+	const preserved = dispatchChildrenWithContext({
 		element,
 		container: "w:lvl",
 		capturePosition: sequencePositions("w:lvl", element),
-		handlers: {
-			start: (child) => read("start", integerValue(child)),
-			numFmt: (child) => {
-				const resolved = resolveNumFmt(child);
-				if (resolved === null) return CAPTURE;
-				Object.assign(level, resolved);
-			},
-			lvlRestart: (child) => read("lvlRestart", integerValue(child)),
-			pStyle: (child) => read("pStyle", attributeValue(child)),
-			isLgl: (child) => read("isLgl", parseBooleanElement(child)),
-			suff: (child) => read("suffix", narrowEnum(attributeValue(child), LevelSuffixSchema)),
-			lvlText: (child) => {
-				read("lvlText", attributeValue(child) ?? "");
-				const isNull = parseOnOffAttribute(child, "w", "null");
-				if (isNull !== void 0) level.lvlTextNull = isNull;
-			},
-			lvlPicBulletId: (child) => read("lvlPicBulletId", integerValue(child)),
-			legacy: (child) => read("legacy", legacyOf(child)),
-			lvlJc: (child) => read("lvlJc", narrowEnum(attributeValue(child), ParagraphAlignmentSchema)),
-			pPr: (child) => read("pPr", parseParagraphProperties(child, null) ?? {}),
-			rPr: (child) => read("rPr", parseRunProperties(child, null, RUN_PROPERTY_OWNERS.standalone) ?? {})
-		},
-		undeclared: { AlternateContent: () => void 0 }
+		handlers: LIST_LEVEL_HANDLERS,
+		undeclared: LIST_LEVEL_UNDECLARED,
+		context: level
 	});
 	if (preserved !== void 0) level.preserved = preserved;
 	const preservedAttributes = attributeRemainder({
@@ -340,7 +362,8 @@ const markerFormattingFromLevel = (formatting) => {
 		...formatting.italic !== void 0 ? { italic: formatting.italic } : {},
 		...formatting.italicCs !== void 0 ? { italicCs: formatting.italicCs } : {},
 		...formatting.rtl !== void 0 ? { rtl: formatting.rtl } : {},
-		...formatting.cs !== void 0 ? { cs: formatting.cs } : {}
+		...formatting.cs !== void 0 ? { cs: formatting.cs } : {},
+		...formatting.color !== void 0 ? { color: formatting.color } : {}
 	};
 	return Object.keys(markerFormatting).length > 0 ? markerFormatting : void 0;
 };
@@ -450,6 +473,7 @@ function computeListRendering(numPr, numbering) {
 	if (level.rPr?.hidden) rendering.markerHidden = true;
 	const markerFormatting = markerFormattingFromLevel(level.rPr);
 	if (markerFormatting) rendering.markerFormatting = markerFormatting;
+	if (level.pPr?.tabs?.length) rendering.levelTabs = level.pPr.tabs;
 	if (level.rPr?.allCaps) rendering.markerAllCaps = true;
 	const markerAlignment = markerAlignmentForLevel(level.lvlJc);
 	if (markerAlignment !== void 0) rendering.markerAlignment = markerAlignment;

package/dist/docx/paragraphParser.d.ts

@@ -1,12 +1,15 @@
 import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
 import { XmlElement } from "./xmlParser.js";
+import { PreviewLedger } from "./previewBudget.js";
 import { StyleMap } from "./styleParser.js";
 //#region src/docx/paragraphParser.d.ts
 declare function parseParagraphPropertyChanges(pPr: XmlElement | null, theme: document_d_exports.Theme | null, currentFormatting: document_d_exports.ParagraphFormatting | undefined): document_d_exports.ParagraphPropertyChange[] | undefined;
 type ParseParagraphOptions = {
   inHeaderFooter?: boolean;
   rootXmlns?: Record<string, string>;
+  /** The ledger of the package this paragraph belongs to. */
+  previews: PreviewLedger;
   /** Delay run merging until a source-position-dependent enrichment pass completes. */
   runConsolidation?: "immediate" | "deferred";
 };
@@ -19,7 +22,8 @@ type ParseParagraphOptions = {
  * @param numbering - Numbering definitions for list info
  * @param rels - Relationship map for resolving hyperlink URLs
  * @param media - Media files map for image data
- * @param options - Parsing options for context-specific body behavior
+ * @param options - Parsing options for context-specific body behavior; a
+ *   paragraph read without them charges its previews to no package
  * @returns Parsed Paragraph object
  */
 declare function parseParagraph(node: 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, options?: ParseParagraphOptions): document_d_exports.Paragraph;