@stll/folio-core 0.47.7 → 0.48.0

package/dist/docx/blockContentParser.js

@@ -1,10 +1,11 @@
 import { parseBookmarkEnd, parseBookmarkStart } from "./bookmarkParser.js";
 import { convertBulletToUnicode } from "./bulletMarkers.js";
-import { CAPTURE, dispatchChildren, ownedElsewhere, withPreservedChildren } from "./containerChildren.js";
+import { CAPTURE, dispatchChildrenWithContext, ownedElsewhere, withPreservedChildren } from "./containerChildren.js";
 import { isNumberingReference } from "./numberingReference.js";
 import { formatOoxmlCounter } from "./ooxmlCounterFormatter.js";
 import { parseParagraph } from "./paragraphParser.js";
 import { enrichParagraphTextBoxes } from "./paragraphTextBoxEnrichment.js";
+import { standalonePreviewLedger } from "./previewBudget.js";
 import { captureSdtSiblingMarkers, parseSdtProperties } from "./sdtProperties.js";
 import { parseTable } from "./tableParser.js";
 import { findWordprocessingChild, mergeXmlnsDeclarations, selectAlternateContentBranch } from "./xmlParser.js";
@@ -84,7 +85,7 @@ const withContainerXmlns = (state, element) => ({
 	...state,
 	options: {
 		...state.options,
-		rootXmlns: mergeXmlnsDeclarations(state.options?.rootXmlns ?? {}, element)
+		rootXmlns: mergeXmlnsDeclarations(state.options.rootXmlns ?? {}, element)
 	}
 });
 /**
@@ -121,74 +122,88 @@ const parseBlockContent = (parent, styles, theme, numbering, rels, media, option
 	},
 	options: {
 		...options,
-		rootXmlns: mergeXmlnsDeclarations(options?.rootXmlns ?? {}, parent)
+		rootXmlns: mergeXmlnsDeclarations(options?.rootXmlns ?? {}, parent),
+		previews: options?.previews ?? standalonePreviewLedger()
 	}
 });
+const BLOCK_CONTENT_UNDECLARED = { AlternateContent: (child, { resources: { styles, theme, numbering, rels, media }, state, modelled }) => {
+	const selectedBranch = selectAlternateContentBranch(child);
+	if (!selectedBranch) return;
+	modelled.push(...parseBlockContentWithState(selectedBranch, styles, theme, numbering, rels, media, withContainerXmlns(withContainerXmlns(state, child), selectedBranch)));
+} };
+const BLOCK_CONTENT_HANDLERS = {
+	p: (child, { resources: { styles, theme, numbering, rels, media }, state, modelled }) => {
+		const paragraph = parseParagraph(child, styles, theme, numbering, rels, media, {
+			...state.options,
+			runConsolidation: "deferred"
+		});
+		enrichParagraphTextBoxes(paragraph, child, styles, theme, numbering, rels, media, parseTable, state.options.previews, state.options.context);
+		computeListMarker(paragraph, {
+			numbering,
+			listCounters: state.listCounters,
+			abstractCounters: state.abstractCounters,
+			restartedNumIds: state.restartedNumIds,
+			previousList: state.previousList
+		});
+		modelled.push(paragraph);
+	},
+	tbl: (child, { resources: { styles, theme, numbering, rels, media }, state, modelled }) => {
+		const table = parseTable(child, styles, theme, numbering, rels, media, state.options);
+		if (!table) return;
+		modelled.push(table);
+	},
+	sdt: (child, { resources: { styles, theme, numbering, rels, media }, state, modelled }) => {
+		modelled.push(parseBlockSdt(child, styles, theme, numbering, rels, media, state));
+	},
+	bookmarkStart: (child, { modelled }) => {
+		modelled.push(parseBookmarkStart(child));
+	},
+	bookmarkEnd: (child, { modelled }) => {
+		modelled.push(parseBookmarkEnd(child));
+	},
+	...BLOCK_CHILD_OWNERS,
+	altChunk: CAPTURE,
+	commentRangeEnd: CAPTURE,
+	commentRangeStart: CAPTURE,
+	customXml: CAPTURE,
+	customXmlDelRangeEnd: CAPTURE,
+	customXmlDelRangeStart: CAPTURE,
+	customXmlInsRangeEnd: CAPTURE,
+	customXmlInsRangeStart: CAPTURE,
+	customXmlMoveFromRangeEnd: CAPTURE,
+	customXmlMoveFromRangeStart: CAPTURE,
+	customXmlMoveToRangeEnd: CAPTURE,
+	customXmlMoveToRangeStart: CAPTURE,
+	del: CAPTURE,
+	ins: CAPTURE,
+	moveFrom: CAPTURE,
+	moveFromRangeEnd: CAPTURE,
+	moveFromRangeStart: CAPTURE,
+	moveTo: CAPTURE,
+	moveToRangeEnd: CAPTURE,
+	moveToRangeStart: CAPTURE,
+	permEnd: CAPTURE,
+	permStart: CAPTURE,
+	proofErr: CAPTURE
+};
 const parseBlockContentWithState = (parent, styles, theme, numbering, rels, media, state) => {
 	const modelled = [];
-	return withPreservedChildren(modelled, dispatchChildren({
+	return withPreservedChildren(modelled, dispatchChildrenWithContext({
 		element: parent,
 		container: "block-content",
 		capturePosition: () => modelled.length,
-		undeclared: { AlternateContent: (child) => {
-			const selectedBranch = selectAlternateContentBranch(child);
-			if (!selectedBranch) return;
-			modelled.push(...parseBlockContentWithState(selectedBranch, styles, theme, numbering, rels, media, withContainerXmlns(withContainerXmlns(state, child), selectedBranch)));
-		} },
-		handlers: {
-			p: (child) => {
-				const paragraph = parseParagraph(child, styles, theme, numbering, rels, media, {
-					...state.options,
-					runConsolidation: "deferred"
-				});
-				enrichParagraphTextBoxes(paragraph, child, styles, theme, numbering, rels, media, parseTable, state.options?.context);
-				computeListMarker(paragraph, {
-					numbering,
-					listCounters: state.listCounters,
-					abstractCounters: state.abstractCounters,
-					restartedNumIds: state.restartedNumIds,
-					previousList: state.previousList
-				});
-				modelled.push(paragraph);
-			},
-			tbl: (child) => {
-				const table = parseTable(child, styles, theme, numbering, rels, media, state.options);
-				if (!table) return;
-				modelled.push(table);
-			},
-			sdt: (child) => {
-				modelled.push(parseBlockSdt(child, styles, theme, numbering, rels, media, state));
-			},
-			bookmarkStart: (child) => {
-				modelled.push(parseBookmarkStart(child));
-			},
-			bookmarkEnd: (child) => {
-				modelled.push(parseBookmarkEnd(child));
+		undeclared: BLOCK_CONTENT_UNDECLARED,
+		handlers: BLOCK_CONTENT_HANDLERS,
+		context: {
+			resources: {
+				styles,
+				theme,
+				numbering,
+				rels,
+				media
 			},
-			...BLOCK_CHILD_OWNERS,
-			altChunk: CAPTURE,
-			commentRangeEnd: CAPTURE,
-			commentRangeStart: CAPTURE,
-			customXml: CAPTURE,
-			customXmlDelRangeEnd: CAPTURE,
-			customXmlDelRangeStart: CAPTURE,
-			customXmlInsRangeEnd: CAPTURE,
-			customXmlInsRangeStart: CAPTURE,
-			customXmlMoveFromRangeEnd: CAPTURE,
-			customXmlMoveFromRangeStart: CAPTURE,
-			customXmlMoveToRangeEnd: CAPTURE,
-			customXmlMoveToRangeStart: CAPTURE,
-			del: CAPTURE,
-			ins: CAPTURE,
-			moveFrom: CAPTURE,
-			moveFromRangeEnd: CAPTURE,
-			moveFromRangeStart: CAPTURE,
-			moveTo: CAPTURE,
-			moveToRangeEnd: CAPTURE,
-			moveToRangeStart: CAPTURE,
-			permEnd: CAPTURE,
-			permStart: CAPTURE,
-			proofErr: CAPTURE
+			state,
+			modelled
 		}
 	}), (xml) => ({
 		type: "preservedBlock",

package/dist/docx/commentParser.d.ts

@@ -1,5 +1,6 @@
 import { document_d_exports } from "../types/document.js";
 import { ParseContext } from "./parseContext.js";
+import { PreviewLedger } from "./previewBudget.js";
 import { StyleMap } from "./styleParser.js";
 //#region src/docx/commentParser.d.ts
 type CommentExtendedInfo = {
@@ -29,6 +30,6 @@ declare function parseCommentsExtended(xml: string): Map<string, CommentExtended
  * local time. If `commentsExtendedXml` is provided, reply-thread
  * parent links (`parentId`) and resolved state (`done`) are populated.
  */
-declare function parseComments(commentsXml: string | null, styles: StyleMap | null, theme: document_d_exports.Theme | null, rels: document_d_exports.RelationshipMap, media: Map<string, document_d_exports.MediaFile>, commentsExtensibleXml?: string | null, commentsExtendedXml?: string | null, context?: ParseContext): document_d_exports.Comment[];
+declare function parseComments(commentsXml: string | null, styles: StyleMap | null, theme: document_d_exports.Theme | null, rels: document_d_exports.RelationshipMap, media: Map<string, document_d_exports.MediaFile>, commentsExtensibleXml?: string | null, commentsExtendedXml?: string | null, context?: ParseContext, previews?: PreviewLedger): document_d_exports.Comment[];
 //#endregion
 export { CommentExtendedInfo, parseComments, parseCommentsExtended };

package/dist/docx/commentParser.js

@@ -1,8 +1,9 @@
 import { commentThreadParaId } from "./commentThreadKey.js";
-import { CAPTURE, dispatchChildren } from "./containerChildren.js";
+import { CAPTURE, dispatchChildrenWithContext } from "./containerChildren.js";
 import { PARA_ID_NAMESPACE_URIS, paraIdAttribute, paraIdParentAttribute } from "./paraIdAttribute.js";
 import { parseParagraph } from "./paragraphParser.js";
 import { cloneParagraphWithPropertySource } from "./paragraphPropertySource.js";
+import { standalonePreviewLedger } from "./previewBudget.js";
 import { RUN_PROPERTY_OWNERS, parseRunProperties } from "./runParser.js";
 import { findChild, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, parseOnOffValue, parseXml } from "./xmlParser.js";
 import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
@@ -97,6 +98,46 @@ function parseCommentsExtended(xml) {
 	}
 	return infoByParaId;
 }
+const COMMENT_BODY_HANDLERS = {
+	p: (contentChild, walk) => {
+		const { styles, theme, rels, media, previews, paragraphs } = walk;
+		const paragraph = parseParagraph(contentChild, styles, theme, null, rels, media, { previews });
+		if (paragraphs.length > 0) {
+			paragraphs.push(paragraph);
+			return;
+		}
+		const normalized = normalizeFirstCommentParagraph(contentChild, paragraph, theme);
+		walk.annotationReferenceFormatting = normalized.annotationReferenceFormatting;
+		paragraphs.push(normalized.paragraph);
+	},
+	altChunk: CAPTURE,
+	bookmarkEnd: CAPTURE,
+	bookmarkStart: CAPTURE,
+	commentRangeEnd: CAPTURE,
+	commentRangeStart: CAPTURE,
+	customXml: CAPTURE,
+	customXmlDelRangeEnd: CAPTURE,
+	customXmlDelRangeStart: CAPTURE,
+	customXmlInsRangeEnd: CAPTURE,
+	customXmlInsRangeStart: CAPTURE,
+	customXmlMoveFromRangeEnd: CAPTURE,
+	customXmlMoveFromRangeStart: CAPTURE,
+	customXmlMoveToRangeEnd: CAPTURE,
+	customXmlMoveToRangeStart: CAPTURE,
+	del: CAPTURE,
+	ins: CAPTURE,
+	moveFrom: CAPTURE,
+	moveFromRangeEnd: CAPTURE,
+	moveFromRangeStart: CAPTURE,
+	moveTo: CAPTURE,
+	moveToRangeEnd: CAPTURE,
+	moveToRangeStart: CAPTURE,
+	permEnd: CAPTURE,
+	permStart: CAPTURE,
+	proofErr: CAPTURE,
+	sdt: CAPTURE,
+	tbl: CAPTURE
+};
 /**
 * Parse comments.xml into an array of Comment objects.
 *
@@ -105,7 +146,7 @@ function parseCommentsExtended(xml) {
 * local time. If `commentsExtendedXml` is provided, reply-thread
 * parent links (`parentId`) and resolved state (`done`) are populated.
 */
-function parseComments(commentsXml, styles, theme, rels, media, commentsExtensibleXml, commentsExtendedXml, context) {
+function parseComments(commentsXml, styles, theme, rels, media, commentsExtensibleXml, commentsExtendedXml, context, previews = standalonePreviewLedger()) {
 	if (!commentsXml) return [];
 	const root = parseXml(commentsXml);
 	const dateUtcByParaId = commentsExtensibleXml ? parseCommentsExtensible(commentsExtensibleXml) : /* @__PURE__ */ new Map();
@@ -135,52 +176,23 @@ function parseComments(commentsXml, styles, theme, rels, media, commentsExtensib
 		const paraId = rawParaId ? String(rawParaId).toUpperCase() : null;
 		const date = (paraId ? dateUtcByParaId.get(paraId) : void 0) ?? localDate;
 		const done = (paraId ? extendedByParaId.get(paraId) : void 0)?.done;
-		const paragraphs = [];
-		let annotationReferenceFormatting;
-		const preserved = dispatchChildren({
+		const walk = {
+			styles,
+			theme,
+			rels,
+			media,
+			previews,
+			paragraphs: [],
+			annotationReferenceFormatting: void 0
+		};
+		const preserved = dispatchChildrenWithContext({
 			element: child,
 			container: "w:comment",
-			capturePosition: () => paragraphs.length,
-			handlers: {
-				p: (contentChild) => {
-					const paragraph = parseParagraph(contentChild, styles, theme, null, rels, media);
-					if (paragraphs.length > 0) {
-						paragraphs.push(paragraph);
-						return;
-					}
-					const normalized = normalizeFirstCommentParagraph(contentChild, paragraph, theme);
-					annotationReferenceFormatting = normalized.annotationReferenceFormatting;
-					paragraphs.push(normalized.paragraph);
-				},
-				altChunk: CAPTURE,
-				bookmarkEnd: CAPTURE,
-				bookmarkStart: CAPTURE,
-				commentRangeEnd: CAPTURE,
-				commentRangeStart: CAPTURE,
-				customXml: CAPTURE,
-				customXmlDelRangeEnd: CAPTURE,
-				customXmlDelRangeStart: CAPTURE,
-				customXmlInsRangeEnd: CAPTURE,
-				customXmlInsRangeStart: CAPTURE,
-				customXmlMoveFromRangeEnd: CAPTURE,
-				customXmlMoveFromRangeStart: CAPTURE,
-				customXmlMoveToRangeEnd: CAPTURE,
-				customXmlMoveToRangeStart: CAPTURE,
-				del: CAPTURE,
-				ins: CAPTURE,
-				moveFrom: CAPTURE,
-				moveFromRangeEnd: CAPTURE,
-				moveFromRangeStart: CAPTURE,
-				moveTo: CAPTURE,
-				moveToRangeEnd: CAPTURE,
-				moveToRangeStart: CAPTURE,
-				permEnd: CAPTURE,
-				permStart: CAPTURE,
-				proofErr: CAPTURE,
-				sdt: CAPTURE,
-				tbl: CAPTURE
-			}
+			capturePosition: () => walk.paragraphs.length,
+			handlers: COMMENT_BODY_HANDLERS,
+			context: walk
 		});
+		const { paragraphs, annotationReferenceFormatting } = walk;
 		if (paraId && !commentIdByParaId.has(paraId)) commentIdByParaId.set(paraId, id);
 		parsed.push({
 			comment: {

package/dist/docx/containerChildren.d.ts

@@ -83,6 +83,12 @@ declare const ownedElsewhere: <Container extends DispatchedContainer, Child exte
  * difference between this and a `default` that says nothing.
  */
 declare const DROPPED_WITH_ITS_WRAPPER = "dropped-with-its-wrapper";
+/**
+ * A handler that reads one child. `context` is the value the walk was given
+ * (see {@link dispatchChildrenWithContext}), so a handler table can be built
+ * once per module rather than as closures per element.
+ */
+type ChildReader<Context = undefined> = (child: XmlElement, context: Context) => typeof CAPTURE | void;
 /**
  * What a container does with one declared child.
  *
@@ -94,7 +100,7 @@ declare const DROPPED_WITH_ITS_WRAPPER = "dropped-with-its-wrapper";
  * it by the outcome rather than by the name is what makes the decision total:
  * the map cannot list the values a reader will refuse.
  */
-type ChildDisposition<Container extends DispatchedContainer = DispatchedContainer, Child extends string = string> = ((child: XmlElement) => typeof CAPTURE | void) | typeof CAPTURE | typeof DROPPED_WITH_ITS_WRAPPER | OwnedElsewhere<Container, Child>;
+type ChildDisposition<Container extends DispatchedContainer = DispatchedContainer, Child extends string = string, Context = undefined> = ChildReader<Context> | typeof CAPTURE | typeof DROPPED_WITH_ITS_WRAPPER | OwnedElsewhere<Container, Child>;
 /**
  * A total decision per declared child.
  *
@@ -103,13 +109,13 @@ type ChildDisposition<Container extends DispatchedContainer = DispatchedContaine
  * type is keyed by the child it is filed under, so an {@link ownedElsewhere}
  * entry cannot name a different child than the one it decides.
  */
-type ChildHandlers<Container extends DispatchedContainer> = Readonly<{ [Child in DeclaredChild<Container>]: ChildDisposition<Container, Child>; }>;
-type DispatchChildrenOptions<Container extends DispatchedContainer> = {
+type ChildHandlers<Container extends DispatchedContainer, Context = undefined> = Readonly<{ [Child in DeclaredChild<Container>]: ChildDisposition<Container, Child, Context>; }>;
+type DispatchChildrenOptions<Container extends DispatchedContainer, Context = undefined> = {
   /** The container element, as the source wrote it. */
   element: XmlElement;
   /** Which container's declared-child set the handler map must be total over. */
   container: Container;
-  handlers: ChildHandlers<Container>;
+  handlers: ChildHandlers<Container, Context>;
   /**
    * Where a capture belongs among the caller's children, called once per
    * captured child.
@@ -135,7 +141,7 @@ type DispatchChildrenOptions<Container extends DispatchedContainer> = {
    *
    * Each entry is a claim that folio reads this name in this container.
    */
-  undeclared?: Readonly<Record<string, ChildDisposition>>;
+  undeclared?: Readonly<Record<string, ChildDisposition<DispatchedContainer, string, Context>>>;
   /**
    * Dispositions for whole namespaces the declared set does not cover, by
    * namespace URI, consulted after {@link undeclared} and before the sink.
@@ -148,7 +154,7 @@ type DispatchChildrenOptions<Container extends DispatchedContainer> = {
    * not a `default` in disguise: a child from any *other* namespace still goes
    * to the sink, which is the branch a hand-written `default` gets wrong.
    */
-  undeclaredNamespaces?: Readonly<Record<string, ChildDisposition>>;
+  undeclaredNamespaces?: Readonly<Record<string, ChildDisposition<DispatchedContainer, string, Context>>>;
 };
 /**
  * The Transitional spelling of a namespace, so one disposition covers both.
@@ -171,7 +177,14 @@ declare const transitionalNamespaceOf: (namespace: string) => string;
  *   none — an empty record is never written, so a fully modelled container
  *   stays byte-identical in the model.
  */
-declare const dispatchChildren: <Container extends DispatchedContainer>({ element, handlers, capturePosition, undeclared, undeclaredNamespaces }: DispatchChildrenOptions<Container>) => PreservedMarkup | undefined;
+declare const dispatchChildren: <Container extends DispatchedContainer>(options: DispatchChildrenOptions<Container>) => PreservedMarkup | undefined;
+/**
+ * {@link dispatchChildren} for a handler table that reads into a value it is
+ * handed rather than one it closes over, so the table is built once.
+ */
+declare const dispatchChildrenWithContext: <Container extends DispatchedContainer, Context>({ element, handlers, capturePosition, undeclared, undeclaredNamespaces, context }: DispatchChildrenOptions<Container, Context> & {
+  context: Context;
+}) => PreservedMarkup | undefined;
 /**
  * Put a container's modelled children back with its preserved ones between
  * them, in source position.
@@ -205,4 +218,4 @@ declare const serializeWithPreservedChildren: (modelled: readonly string[], pres
  */
 declare const sequencePositions: <Container extends SequenceContainer>(container: Container, element: XmlElement) => ((child: XmlElement) => number);
 //#endregion
-export { CAPTURE, ChildDisposition, ChildHandlers, ChildOwnerClaim, ChildOwnerRef, DROPPED_WITH_ITS_WRAPPER, OwnedElsewhere, dispatchChildren, keptUnless, ownedElsewhere, ownedElsewhereClaims, sequencePositions, serializeWithPreservedChildren, transitionalNamespaceOf, withPreservedChildren };
+export { CAPTURE, ChildDisposition, ChildHandlers, ChildOwnerClaim, ChildOwnerRef, ChildReader, DROPPED_WITH_ITS_WRAPPER, OwnedElsewhere, dispatchChildren, dispatchChildrenWithContext, keptUnless, ownedElsewhere, ownedElsewhereClaims, sequencePositions, serializeWithPreservedChildren, transitionalNamespaceOf, withPreservedChildren };

package/dist/docx/containerChildren.js

@@ -59,6 +59,13 @@ const DROPPED_WITH_ITS_WRAPPER = "dropped-with-its-wrapper";
 */
 const transitionalNamespaceOf = (namespace) => TRANSITIONAL_NAMESPACE_BY_STRICT_URI.get(namespace) ?? namespace;
 /**
+* A table's own entry for `key`. Read directly rather than copied into a `Map`
+* per container: the tables are rebuilt per element, and the copy dominated the
+* walk. `Object.hasOwn` keeps a name such as `constructor` from resolving to a
+* prototype member.
+*/
+const ownDisposition = (table, key) => table !== void 0 && Object.hasOwn(table, key) ? table[key] : void 0;
+/**
 * Walk a container's children, handing each to its handler and the rest to the
 * sink.
 *
@@ -66,7 +73,15 @@ const transitionalNamespaceOf = (namespace) => TRANSITIONAL_NAMESPACE_BY_STRICT_
 *   none — an empty record is never written, so a fully modelled container
 *   stays byte-identical in the model.
 */
-const dispatchChildren = ({ element, handlers, capturePosition, undeclared, undeclaredNamespaces }) => {
+const dispatchChildren = (options) => dispatchChildrenWithContext({
+	...options,
+	context: void 0
+});
+/**
+* {@link dispatchChildren} for a handler table that reads into a value it is
+* handed rather than one it closes over, so the table is built once.
+*/
+const dispatchChildrenWithContext = ({ element, handlers, capturePosition, undeclared, undeclaredNamespaces, context }) => {
 	const children = [];
 	const capture = (child) => {
 		children.push({
@@ -74,19 +89,17 @@ const dispatchChildren = ({ element, handlers, capturePosition, undeclared, unde
 			xml: captureVerbatimXml(child)
 		});
 	};
-	const declared = new Map(Object.entries(handlers));
-	const byName = new Map(Object.entries(undeclared ?? {}));
-	const byNamespace = new Map(Object.entries(undeclaredNamespaces ?? {}));
+	const declared = handlers;
 	for (const child of getChildElements(element)) {
 		const localName = getLocalName(child.name);
 		const namespace = getNamespaceUri(child);
-		const disposition = namespace === void 0 || WORDPROCESSINGML_NAMESPACE_URIS.has(namespace) ? declared.get(localName) ?? byName.get(localName) : byName.get(localName) ?? byNamespace.get(transitionalNamespaceOf(namespace));
+		const disposition = namespace === void 0 || WORDPROCESSINGML_NAMESPACE_URIS.has(namespace) ? ownDisposition(declared, localName) ?? ownDisposition(undeclared, localName) : ownDisposition(undeclared, localName) ?? ownDisposition(undeclaredNamespaces, transitionalNamespaceOf(namespace));
 		if (disposition === void 0 || disposition === "capture") {
 			capture(child);
 			continue;
 		}
 		if (typeof disposition !== "function") continue;
-		if (disposition(child) === "capture") capture(child);
+		if (disposition(child, context) === "capture") capture(child);
 	}
 	return children.length === 0 ? void 0 : { children };
 };
@@ -138,16 +151,33 @@ const serializeWithPreservedChildren = (modelled, preserved) => withPreservedChi
 * ahead of the sequence's first slot.
 */
 const sequencePositions = (container, element) => {
+	let positions;
+	return (child) => {
+		positions ??= computeSequencePositions(container, element);
+		return positions.get(child) ?? -1;
+	};
+};
+const SEQUENCE_ORDINALS = /* @__PURE__ */ new Map();
+const sequenceOrdinals = (container) => {
+	const cached = SEQUENCE_ORDINALS.get(container);
+	if (cached !== void 0) return cached;
+	const ordinals = /* @__PURE__ */ new Map();
 	const declared = SEQUENCE_CHILDREN[container];
+	for (const [at, name] of declared.entries()) if (!ordinals.has(name)) ordinals.set(name, at);
+	SEQUENCE_ORDINALS.set(container, ordinals);
+	return ordinals;
+};
+const computeSequencePositions = (container, element) => {
+	const ordinals = sequenceOrdinals(container);
 	const positions = /* @__PURE__ */ new Map();
 	let previous = -1;
 	for (const child of getChildElements(element)) {
 		const namespace = getNamespaceUri(child);
-		const at = namespace === void 0 || WORDPROCESSINGML_NAMESPACE_URIS.has(namespace) ? declared.indexOf(getLocalName(child.name)) : -1;
+		const at = namespace === void 0 || WORDPROCESSINGML_NAMESPACE_URIS.has(namespace) ? ordinals.get(getLocalName(child.name)) ?? -1 : -1;
 		if (at !== -1) previous = at;
 		positions.set(child, at === -1 ? previous : at);
 	}
-	return (child) => positions.get(child) ?? -1;
+	return positions;
 };
 //#endregion
-export { CAPTURE, DROPPED_WITH_ITS_WRAPPER, dispatchChildren, keptUnless, ownedElsewhere, ownedElsewhereClaims, sequencePositions, serializeWithPreservedChildren, transitionalNamespaceOf, withPreservedChildren };
+export { CAPTURE, DROPPED_WITH_ITS_WRAPPER, dispatchChildren, dispatchChildrenWithContext, keptUnless, ownedElsewhere, ownedElsewhereClaims, sequencePositions, serializeWithPreservedChildren, transitionalNamespaceOf, withPreservedChildren };

package/dist/docx/documentParser.d.ts

@@ -1,6 +1,7 @@
 import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
 import { ParseContext } from "./parseContext.js";
+import { PreviewLedger } from "./previewBudget.js";
 import { StyleMap } from "./styleParser.js";
 //#region src/docx/documentParser.d.ts
 /**
@@ -26,9 +27,12 @@ declare function extractAllTemplateVariables(content: document_d_exports.BlockCo
  * @param numbering - Parsed numbering definitions
  * @param rels - Document relationships
  * @param media - Media files
+ * @param context - Where normalisations are reported
+ * @param previews - The ledger of the package this body belongs to; a body
+ *   read on its own charges its previews to no package
  * @returns DocumentBody with content, sections, and template variables
  */
-declare function parseDocumentBody(xml: string, 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, context?: ParseContext): document_d_exports.DocumentBody;
+declare function parseDocumentBody(xml: string, 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, context?: ParseContext, previews?: PreviewLedger): document_d_exports.DocumentBody;
 /**
  * Get all paragraphs from document body (flattened)
  */

package/dist/docx/documentParser.js

@@ -1,7 +1,7 @@
 import { parseBlockContent } from "./blockContentParser.js";
 import { getParagraphText } from "./paragraphParser.js";
+import { standalonePreviewLedger } from "./previewBudget.js";
 import { getDefaultSectionProperties, parseSectionProperties } from "./sectionParser.js";
-import { parseStreamingXml } from "./streamingXmlParser.js";
 import { parseThemeColorAttribute } from "./themeColorAttribute.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
 import { WORDPROCESSINGML_NAMESPACE_URIS, collectXmlnsDeclarations, findChild, findChildByNamespaceUri, getAttributeByNamespaceUri, getLocalName, parseXml } from "./xmlParser.js";
@@ -145,13 +145,15 @@ function parseDocumentBackground(documentEl, context) {
 * @param numbering - Parsed numbering definitions
 * @param rels - Document relationships
 * @param media - Media files
+* @param context - Where normalisations are reported
+* @param previews - The ledger of the package this body belongs to; a body
+*   read on its own charges its previews to no package
 * @returns DocumentBody with content, sections, and template variables
 */
-function parseDocumentBody(xml, styles = null, theme = null, numbering = null, rels = null, media = null, context) {
+function parseDocumentBody(xml, styles = null, theme = null, numbering = null, rels = null, media = null, context, previews = standalonePreviewLedger()) {
 	const result = { content: [] };
 	if (!xml) return result;
-	const streamed = parseStreamingXml(xml);
-	const documentEl = ((streamed.status === "parsed" ? streamed.value : parseXml(xml)).elements ?? []).find((el) => el.type === "element" && (el.name === "w:document" || el.name?.endsWith(":document")));
+	const documentEl = (parseXml(xml).elements ?? []).find((el) => el.type === "element" && (el.name === "w:document" || el.name?.endsWith(":document")));
 	if (!documentEl) return result;
 	const background = parseDocumentBackground(documentEl, context);
 	if (background !== void 0) result.background = background;
@@ -159,7 +161,8 @@ function parseDocumentBody(xml, styles = null, theme = null, numbering = null, r
 	if (!bodyEl) return result;
 	result.content = parseBlockContent(bodyEl, styles, theme, numbering, rels, media, {
 		rootXmlns: collectXmlnsDeclarations(documentEl),
-		context
+		context,
+		previews
 	});
 	const finalSectPr = findChild(bodyEl, "w", "sectPr");
 	if (finalSectPr) result.finalSectionProperties = parseSectionProperties(finalSectPr, context);

package/dist/docx/documentSectionFacts.d.ts

@@ -0,0 +1,22 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/documentSectionFacts.d.ts
+type HeaderFooterReference = {
+  element: "headerReference" | "footerReference";
+  /** The parsed `ST_HdrFtr` value, never the raw attribute. */
+  type: document_d_exports.HeaderFooterType;
+  rId: string;
+};
+/** What a save must not lose from `word/document.xml`. */
+type DocumentSectionFacts = {
+  /** `w:sectPr` elements, excluding the prior records inside `w:sectPrChange`. */
+  sectionCount: number;
+  /** Every header/footer reference, including those inside `w:sectPrChange`. */
+  headerFooterReferences: readonly HeaderFooterReference[];
+};
+/** Both facts from one walk of a parsed document tree. */
+declare const collectDocumentSectionFacts: (root: XmlElement) => DocumentSectionFacts;
+/** Read the section facts of a `word/document.xml` string under the shared resource limits. */
+declare const readDocumentSectionFacts: (xml: string) => DocumentSectionFacts;
+//#endregion
+export { DocumentSectionFacts, HeaderFooterReference, collectDocumentSectionFacts, readDocumentSectionFacts };

package/dist/docx/documentSectionFacts.js

@@ -0,0 +1,43 @@
+import { parseHeaderFooterType } from "./headerFooterRefParser.js";
+import { OFFICE_RELATIONSHIP_NAMESPACE_URIS, WORDPROCESSINGML_NAMESPACE_URIS, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespaceUri, parseXml } from "./xmlParser.js";
+import { assertXmlResourceLimits } from "./xmlResourceLimits.js";
+//#region src/docx/documentSectionFacts.ts
+const isWordprocessingElement = (element, localName) => getLocalName(element.name) === localName && WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(element) ?? "");
+/** Both facts from one walk of a parsed document tree. */
+const collectDocumentSectionFacts = (root) => {
+	let sectionCount = 0;
+	const headerFooterReferences = [];
+	const pending = [{
+		element: root,
+		insidePropertyChange: false
+	}];
+	for (let current = pending.pop(); current !== void 0; current = pending.pop()) {
+		const { element, insidePropertyChange } = current;
+		const localName = getLocalName(element.name);
+		if (!insidePropertyChange && isWordprocessingElement(element, "sectPr")) sectionCount += 1;
+		if ((localName === "headerReference" || localName === "footerReference") && isWordprocessingElement(element, localName)) {
+			const rId = getAttributeByNamespaceUri(element, OFFICE_RELATIONSHIP_NAMESPACE_URIS, "id");
+			if (rId) headerFooterReferences.push({
+				element: localName,
+				type: parseHeaderFooterType(getAttributeByNamespaceUri(element, WORDPROCESSINGML_NAMESPACE_URIS, "type")),
+				rId
+			});
+		}
+		const childrenInsidePropertyChange = insidePropertyChange || isWordprocessingElement(element, "sectPrChange");
+		for (const child of getChildElements(element)) pending.push({
+			element: child,
+			insidePropertyChange: childrenInsidePropertyChange
+		});
+	}
+	return {
+		sectionCount,
+		headerFooterReferences
+	};
+};
+/** Read the section facts of a `word/document.xml` string under the shared resource limits. */
+const readDocumentSectionFacts = (xml) => {
+	assertXmlResourceLimits({ xml });
+	return collectDocumentSectionFacts(parseXml(xml));
+};
+//#endregion
+export { collectDocumentSectionFacts, readDocumentSectionFacts };

package/dist/docx/fieldParser.d.ts

@@ -64,6 +64,13 @@ declare function parseFieldInstruction(instruction: string): ParsedFieldInstruct
  * @returns Format string or undefined
  */
 declare function getFormatSwitch(instruction: ParsedFieldInstruction): string | undefined;
+/**
+ * Get the numeric picture switch value (\#), e.g. `0#` in `PAGE \# 0#`.
+ *
+ * @param instruction - Parsed instruction
+ * @returns Picture string or undefined
+ */
+declare function getNumericPictureSwitch(instruction: ParsedFieldInstruction): string | undefined;
 /**
  * Check if field has MERGEFORMAT switch (preserve formatting)
  *
@@ -237,4 +244,4 @@ declare function getMergeFields(fields: document_d_exports.Field[]): document_d_
  */
 declare function getMergeFieldNames(fields: document_d_exports.Field[]): string[];
 //#endregion
-export { ComplexFieldContext, ComplexFieldState, FieldSwitch, KNOWN_FIELD_TYPES, ParsedFieldInstruction, collectFields, computePageNumber, createComplexFieldContext, finalizeComplexField, formatDate, getFieldDisplayValue, getFieldsByType, getFormatSwitch, getMergeFieldNames, getMergeFields, getPageNumberFields, hasMergeFormat, isDateTimeField, isDocPropertyField, isHyperlinkField, isKnownFieldType, isMergeField, isPageNumberField, isReferenceField, isTocField, isTotalPagesField, parseFieldInstruction, parseFieldType, parseSimpleField, resetComplexFieldContext };
+export { ComplexFieldContext, ComplexFieldState, FieldSwitch, KNOWN_FIELD_TYPES, ParsedFieldInstruction, collectFields, computePageNumber, createComplexFieldContext, finalizeComplexField, formatDate, getFieldDisplayValue, getFieldsByType, getFormatSwitch, getMergeFieldNames, getMergeFields, getNumericPictureSwitch, getPageNumberFields, hasMergeFormat, isDateTimeField, isDocPropertyField, isHyperlinkField, isKnownFieldType, isMergeField, isPageNumberField, isReferenceField, isTocField, isTotalPagesField, parseFieldInstruction, parseFieldType, parseSimpleField, resetComplexFieldContext };