@stll/folio-core 0.47.6 → 0.48.0

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

package/dist/docx/fieldParser.js

@@ -141,6 +141,15 @@ function getFormatSwitch(instruction) {
 	return instruction.switches.find((s) => s.switch === "*" || s.switch === "@")?.value;
 }
 /**
+* Get the numeric picture switch value (\#), e.g. `0#` in `PAGE \# 0#`.
+*
+* @param instruction - Parsed instruction
+* @returns Picture string or undefined
+*/
+function getNumericPictureSwitch(instruction) {
+	return instruction.switches.find((s) => s.switch === "#")?.value;
+}
+/**
 * Check if field has MERGEFORMAT switch (preserve formatting)
 *
 * @param instruction - Parsed instruction
@@ -345,16 +354,51 @@ function isTocField(field) {
 * @returns Formatted page number string
 */
 function computePageNumber(pageNumber, instruction, sectionFormat) {
+	const picture = instruction ? getNumericPictureSwitch(instruction) : void 0;
+	if (picture !== void 0) return applyNumericPicture(pageNumber, picture);
 	const format = instruction ? getFormatSwitch(instruction) : void 0;
 	if (!format || format.toUpperCase() === "MERGEFORMAT") return formatSectionPageNumber(pageNumber, sectionFormat);
+	const isLowercaseSwitch = format === format.toLowerCase();
 	switch (format.toUpperCase()) {
-		case "ROMAN": return toRoman(pageNumber);
-		case "ALPHABETIC": return toLetter(pageNumber);
+		case "ROMAN": {
+			const roman = toRoman(pageNumber);
+			return isLowercaseSwitch ? roman.toLowerCase() : roman;
+		}
+		case "ALPHABETIC": {
+			const letters = toLetter(pageNumber);
+			return isLowercaseSwitch ? letters.toLowerCase() : letters;
+		}
 		default: return String(pageNumber);
 	}
 }
 const formatSectionPageNumber = (pageNumber, format) => formatOoxmlCounter(pageNumber, format);
 /**
+* Apply a `\#` numeric picture (ECMA-376 §17.16.4.2) to an integer field
+* value. `0` is a mandatory digit placeholder that zero-pads once the value
+* runs out of digits; `#` is an optional placeholder that is left blank
+* instead; every other picture character (including a thousands separator)
+* is copied through literally. Placeholders line up with the value's digits
+* from the right; digits that reach past the leftmost placeholder are kept,
+* not truncated.
+*/
+function applyNumericPicture(value, picture) {
+	const negative = value < 0;
+	const digits = [...String(Math.trunc(Math.abs(value)))];
+	const pictureChars = [...picture];
+	const output = Array.from({ length: pictureChars.length });
+	let digitIndex = digits.length - 1;
+	for (let i = pictureChars.length - 1; i >= 0; i--) {
+		const char = pictureChars[i];
+		if (char === "0" || char === "#") if (digitIndex >= 0) {
+			output[i] = digits[digitIndex];
+			digitIndex--;
+		} else output[i] = char === "0" ? "0" : "";
+		else output[i] = char;
+	}
+	const overflow = digitIndex >= 0 ? digits.slice(0, digitIndex + 1).join("") : "";
+	return (negative ? "-" : "") + overflow + output.join("");
+}
+/**
 * Convert number to uppercase Roman numerals
 */
 function toRoman(num) {
@@ -555,4 +599,4 @@ function getMergeFieldNames(fields) {
 	}).filter((name) => !!name);
 }
 //#endregion
-export { KNOWN_FIELD_TYPES, 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 { KNOWN_FIELD_TYPES, 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 };

package/dist/docx/fontTableParser.js

@@ -1,5 +1,5 @@
 import { DERIVED_PART_ROOT_ATTRIBUTES, attributeRemainder } from "./attributeRemainder.js";
-import { CAPTURE, dispatchChildren } from "./containerChildren.js";
+import { CAPTURE, dispatchChildrenWithContext } from "./containerChildren.js";
 import { getAttribute, parseXmlDocument } from "./xmlParser.js";
 //#region src/docx/fontTableParser.ts
 const FONT_FAMILIES = [
@@ -22,14 +22,12 @@ const parseFontTable = (xml) => {
 	const root = parseXmlDocument(xml);
 	if (!root) return;
 	const fonts = [];
-	const preserved = dispatchChildren({
+	const preserved = dispatchChildrenWithContext({
 		element: root,
 		container: "w:fonts",
 		capturePosition: () => fonts.length,
-		handlers: { font: (element) => {
-			const font = parseFont(element);
-			if (font) fonts.push(font);
-		} }
+		handlers: FONT_TABLE_HANDLERS,
+		context: fonts
 	});
 	const preservedAttributes = attributeRemainder({
 		element: root,
@@ -45,31 +43,18 @@ const parseFontTable = (xml) => {
 const parseFont = (element) => {
 	const name = getAttribute(element, "w", "name");
 	if (!name) return;
-	const font = { name };
-	let modelled = 0;
-	const read = (key, value) => {
-		if (value === void 0) return;
-		font[key] = value;
-		modelled += 1;
+	const walk = {
+		font: { name },
+		modelled: 0
 	};
-	const preserved = dispatchChildren({
+	const preserved = dispatchChildrenWithContext({
 		element,
 		container: "w:font",
-		capturePosition: () => modelled,
-		handlers: {
-			altName: (child) => read("altName", value(child)),
-			panose1: (child) => read("panose1", value(child)),
-			charset: (child) => read("charset", charsetOf(child)),
-			family: (child) => read("family", narrow(value(child), FONT_FAMILIES)),
-			notTrueType: CAPTURE,
-			pitch: (child) => read("pitch", narrow(value(child), FONT_PITCHES)),
-			sig: (child) => read("sig", signatureOf(child)),
-			embedRegular: (child) => read("embedRegular", embedOf(child)),
-			embedBold: (child) => read("embedBold", embedOf(child)),
-			embedItalic: (child) => read("embedItalic", embedOf(child)),
-			embedBoldItalic: (child) => read("embedBoldItalic", embedOf(child))
-		}
+		capturePosition: () => walk.modelled,
+		handlers: FONT_HANDLERS,
+		context: walk
 	});
+	const { font } = walk;
 	if (preserved !== void 0) font.preserved = preserved;
 	const preservedAttributes = attributeRemainder({
 		element,
@@ -129,5 +114,27 @@ const signatureOf = (element) => {
 	return Object.keys(signature).length === 0 ? void 0 : signature;
 };
 const narrow = (carried, members) => members.find((member) => member === carried);
+const FONT_TABLE_HANDLERS = { font: (element, fonts) => {
+	const font = parseFont(element);
+	if (font) fonts.push(font);
+} };
+const read = (walk, key, carried) => {
+	if (carried === void 0) return;
+	walk.font[key] = carried;
+	walk.modelled += 1;
+};
+const FONT_HANDLERS = {
+	altName: (child, walk) => read(walk, "altName", value(child)),
+	panose1: (child, walk) => read(walk, "panose1", value(child)),
+	charset: (child, walk) => read(walk, "charset", charsetOf(child)),
+	family: (child, walk) => read(walk, "family", narrow(value(child), FONT_FAMILIES)),
+	notTrueType: CAPTURE,
+	pitch: (child, walk) => read(walk, "pitch", narrow(value(child), FONT_PITCHES)),
+	sig: (child, walk) => read(walk, "sig", signatureOf(child)),
+	embedRegular: (child, walk) => read(walk, "embedRegular", embedOf(child)),
+	embedBold: (child, walk) => read(walk, "embedBold", embedOf(child)),
+	embedItalic: (child, walk) => read(walk, "embedItalic", embedOf(child)),
+	embedBoldItalic: (child, walk) => read(walk, "embedBoldItalic", embedOf(child))
+};
 //#endregion
 export { parseFontTable };

package/dist/docx/footnoteParser.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";
 import { parseEndnoteProperties, parseFootnoteProperties } from "./notePropertiesParser.js";
 //#region src/docx/footnoteParser.d.ts
@@ -53,7 +54,7 @@ type EndnoteMap = {
  * @param media - Media files for images
  * @returns FootnoteMap with all footnotes
  */
-declare function parseFootnotes(footnotesXml: string | null, 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): FootnoteMap;
+declare function parseFootnotes(footnotesXml: string | null, 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): FootnoteMap;
 /**
  * Parse endnotes.xml
  *
@@ -65,7 +66,7 @@ declare function parseFootnotes(footnotesXml: string | null, styles?: StyleMap |
  * @param media - Media files for images
  * @returns EndnoteMap with all endnotes
  */
-declare function parseEndnotes(endnotesXml: string | null, 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): EndnoteMap;
+declare function parseEndnotes(endnotesXml: string | null, 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): EndnoteMap;
 /**
  * Get plain text content of a footnote.
  *