@stll/folio-core 0.47.7 → 0.49.0

package/dist/docx/bulletMarkers.js

@@ -28,10 +28,35 @@ const SYMBOL_BULLET_MAP = {
 	62: ">",
 	45: "-"
 };
-const convertBulletToUnicode = (bulletChar) => {
+/**
+* Fonts whose single-byte codes name pictographs rather than Latin letters.
+* A `w:lvlText` character below U+0100 only means a symbol glyph when the
+* numbering level's `w:rFonts` selects one of these faces.
+*/
+const SYMBOL_ENCODED_FONTS = /* @__PURE__ */ new Set([
+	"symbol",
+	"wingdings",
+	"wingdings 2",
+	"wingdings 3",
+	"webdings"
+]);
+/** The face a bullet level's `w:rFonts` names for its (Latin-range) marker character. */
+const bulletMarkerFontName = (formatting) => formatting?.fontFamily?.ascii ?? formatting?.fontFamily?.hAnsi;
+/** A printable Latin-1 character in a named, non-symbol face paints as itself. */
+const isTextFontCharacter = (charCode, fontName) => fontName !== void 0 && (charCode >= 32 && charCode < 127 || charCode >= 160 && charCode < 256) && !SYMBOL_ENCODED_FONTS.has(fontName.trim().toLowerCase());
+/**
+* Map a bullet level's `w:lvlText` to the character painted for it.
+*
+* `fontName` is the level's own `w:rFonts` face. When it is an ordinary text
+* font, a Latin-range character is the letter itself (the common `o` bullet
+* in a monospace face); without a named face the character is read as a
+* symbol-font code.
+*/
+const convertBulletToUnicode = (bulletChar, fontName) => {
 	if (!bulletChar || bulletChar.trim() === "") return "•";
 	const charCode = bulletChar.codePointAt(0);
 	if (charCode === void 0) return "•";
+	if (isTextFontCharacter(charCode, fontName)) return bulletChar;
 	const mapped = SYMBOL_BULLET_MAP[charCode];
 	if (mapped !== void 0) return mapped;
 	if (charCode >= 57344 && charCode <= 63743) return "•";
@@ -39,4 +64,4 @@ const convertBulletToUnicode = (bulletChar) => {
 	return bulletChar;
 };
 //#endregion
-export { convertBulletToUnicode };
+export { bulletMarkerFontName, convertBulletToUnicode };

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/drawingGroupChildren.d.ts

@@ -0,0 +1,60 @@
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/drawingGroupChildren.d.ts
+type GroupTextBoxFrame = {
+  /** Element indices from the `wpg:wgp` down to the `wps:wsp`. */
+  path: number[];
+  wsp: XmlElement;
+  /** EMUs from the group's top-left corner. */
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** Degrees clockwise. */
+  rotation: number;
+  flipH: boolean;
+  flipV: boolean;
+};
+type Transform2D = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  childX: number;
+  childY: number;
+  childWidth: number;
+  childHeight: number;
+  rotation: number;
+  flipH: boolean;
+  flipV: boolean;
+};
+/** A `CT_GroupTransform2D` or `CT_Transform2D`; absent children read as zero. */
+declare const readTransform: (xfrm: XmlElement | null) => Transform2D;
+/**
+ * Every `wps:wsp` with a text box in the group, nested groups included, with
+ * its frame in EMUs from the group's top-left corner.
+ *
+ * A nested group that is rotated or flipped turns its children's frames into
+ * something other than a rectangle in the drawing's axes, so its text boxes
+ * are left out and stay with the preview.
+ */
+declare const collectGroupTextBoxes: (group: XmlElement, width: number, height: number) => GroupTextBoxFrame[];
+/** Identity of a group drawing's authored XML. */
+declare const groupXmlFingerprint: (rawXml: string) => string;
+/** Identity of a text box's content, compared on save to tell an edit. */
+declare const groupTextContentFingerprint: (content: unknown) => string;
+type GroupTextBoxEdit = {
+  path: readonly number[];
+  /** Serialized `w:txbxContent` children. */
+  contentXml: string;
+};
+/**
+ * The captured group XML with each edited text box's content replaced, or
+ * undefined when an edit names no text box in it.
+ *
+ * The replacement is written as a placeholder element and substituted after
+ * the tree is serialized, so the new content is never reparsed and the rest
+ * of the capture is written exactly as it was read.
+ */
+declare const replaceGroupTextBoxContent: (rawXml: string, edits: readonly GroupTextBoxEdit[]) => string | undefined;
+//#endregion
+export { GroupTextBoxEdit, GroupTextBoxFrame, collectGroupTextBoxes, groupTextContentFingerprint, groupXmlFingerprint, readTransform, replaceGroupTextBoxContent };