@stll/folio-core 0.48.0 → 0.50.0

package/dist/docx/groupDrawingParser.d.ts

@@ -1,7 +1,13 @@
 import { document_d_exports } from "../types/document.js";
 import { XmlElement } from "./xmlParser.js";
 import { PreviewLedger } from "./previewBudget.js";
+import { GroupTextBoxFrame } from "./drawingGroupChildren.js";
 //#region src/docx/groupDrawingParser.d.ts
+/**
+ * The text boxes a group preview does not draw, which the paragraph parser
+ * lifts out as text boxes of their own. Undefined for any other image.
+ */
+declare const groupPreviewTextBoxes: (image: document_d_exports.Image) => readonly GroupTextBoxFrame[] | undefined;
 /**
  * Whether a `w:drawing` carries a WordprocessingGroup payload. A group this
  * module declines to rasterize has no editable projection either — the shape
@@ -11,4 +17,4 @@ declare const isGroupDrawing: (drawing: XmlElement) => boolean;
 /** Parse a WordprocessingGroup drawing into a safe SVG-backed image preview. */
 declare const parseGroupDrawing: (drawing: XmlElement, previews: PreviewLedger, rels?: document_d_exports.RelationshipMap, media?: Map<string, document_d_exports.MediaFile>) => document_d_exports.Image | null;
 //#endregion
-export { isGroupDrawing, parseGroupDrawing };
+export { groupPreviewTextBoxes, isGroupDrawing, parseGroupDrawing };

package/dist/docx/groupDrawingParser.js

@@ -1,4 +1,5 @@
 import { emuToPixels } from "../utils/units.js";
+import { collectGroupTextBoxes, readTransform } from "./drawingGroupChildren.js";
 import { parseImage, resolveImageData } from "./imageParser.js";
 import { findAllDeep, findChildByLocalName, findChildrenByLocalName, getAttribute, getChildElements, getLocalName, getTextContent, parseNumericAttribute } from "./xmlParser.js";
 import { escapeXmlAttribute, escapeXmlText } from "@stll/docx-core";
@@ -9,6 +10,7 @@ const DEFAULT_FONT_HALF_POINTS = 22;
 const DEFAULT_LINE_WIDTH_EMU = 9525;
 const HALF_POINT_TO_EMU = 6350;
 const MAX_GROUP_SHAPES = 256;
+const MAX_GROUP_DEPTH = 16;
 const CROP_SCALE = 1e5;
 const MAX_PATH_COMMANDS = 1e4;
 const MAX_TEXT_CHARACTERS = 2e4;
@@ -79,34 +81,66 @@ const pathData = (path) => {
 	}
 	return commands.join(" ");
 };
-const renderGeometry = (wsp) => {
+/**
+* A child's own `a:xfrm` rotation and flips, applied about its centre in the
+* coordinate space it is drawn in (ECMA-376 §20.1.7.6).
+*/
+const withChildTransform = (element, piece) => {
+	if (!piece) return piece;
+	const transform = readTransform(findChildByLocalName(findChildByLocalName(element, "spPr"), "xfrm"));
+	return wrapTransformed(transform, piece);
+};
+const wrapTransformed = (transform, piece) => {
+	if (transform.rotation === 0 && !transform.flipH && !transform.flipV) return piece;
+	const centerX = transform.x + transform.width / 2;
+	const centerY = transform.y + transform.height / 2;
+	const operations = [];
+	if (transform.rotation !== 0) operations.push(`rotate(${transform.rotation} ${centerX} ${centerY})`);
+	if (transform.flipH || transform.flipV) operations.push(`translate(${centerX} ${centerY}) scale(${transform.flipH ? -1 : 1} ${transform.flipV ? -1 : 1}) translate(${-centerX} ${-centerY})`);
+	return `<g transform="${operations.join(" ")}">${piece}</g>`;
+};
+/**
+* `unitScale` is how many EMUs one unit of the child coordinate space spans.
+* Line widths are authored in EMUs, so they are divided by it to be drawn in
+* the space the geometry is in.
+*/
+const renderGeometry = (wsp, unitScale) => {
 	const { x, y, width, height } = childTransform(wsp);
-	if (width <= 0 || height <= 0) return "";
 	const spPr = findChildByLocalName(wsp, "spPr");
 	const style = findChildByLocalName(wsp, "style");
 	const styleStroke = colorFrom(findChildByLocalName(style, "lnRef"), "none");
 	const fill = colorFrom(spPr, "none");
 	const line = findChildByLocalName(spPr, "ln");
 	const stroke = colorFrom(line, styleStroke);
-	const strokeWidth = line ? parseNumericAttribute(line, null, "w") ?? DEFAULT_LINE_WIDTH_EMU : 0;
+	const strokeWidth = (line ? parseNumericAttribute(line, null, "w") ?? DEFAULT_LINE_WIDTH_EMU : 0) / unitScale;
+	const strokeColor = stroke === "none" ? "none" : `#${stroke}`;
+	if (width <= 0 || height <= 0) {
+		if (width < 0 || height < 0 || width === 0 && height === 0 || strokeColor === "none") return "";
+		return `<line x1="${x}" y1="${y}" x2="${x + width}" y2="${y + height}" stroke="${strokeColor}" stroke-width="${strokeWidth}"/>`;
+	}
 	const paths = findAllDeep(findChildByLocalName(spPr, "custGeom"), "a", "path");
-	if (paths.length === 0) return `<rect x="${x}" y="${y}" width="${width}" height="${height}" fill="${fill === "none" ? "none" : `#${fill}`}" stroke="${stroke === "none" ? "none" : `#${stroke}`}" stroke-width="${strokeWidth}"/>`;
+	if (paths.length === 0) return `<rect x="${x}" y="${y}" width="${width}" height="${height}" fill="${fill === "none" ? "none" : `#${fill}`}" stroke="${strokeColor}" stroke-width="${strokeWidth}"/>`;
 	return paths.map((path) => {
 		const viewWidth = numericAttr(path, "w") || width;
 		const viewHeight = numericAttr(path, "h") || height;
 		const d = pathData(path);
 		if (!d) return "";
-		return `<path d="${d}" transform="translate(${x} ${y}) scale(${width / viewWidth} ${height / viewHeight})" fill="${fill === "none" ? "none" : `#${fill}`}" stroke="${stroke === "none" ? "none" : `#${stroke}`}" stroke-width="${strokeWidth}"/>`;
+		return `<path d="${d}" transform="translate(${x} ${y}) scale(${width / viewWidth} ${height / viewHeight})" fill="${fill === "none" ? "none" : `#${fill}`}" stroke="${strokeColor}" stroke-width="${strokeWidth}"/>`;
 	}).join("");
 };
-const renderTextBox = (wsp) => {
+/**
+* An approximate rendering of a text box the layout does not host (an inline
+* group, or one placed by alignment rather than offset). Font sizes are in
+* EMUs and the drawing is in child units, hence `unitScale`.
+*/
+const renderTextBox = (wsp, unitScale) => {
 	const { x, y, width, height } = childTransform(wsp);
 	if (width <= 0 || height <= 0) return "";
 	const paragraphs = findAllDeep(wsp, "w", "p");
 	const firstSize = findAllDeep(wsp, "w", "sz").at(0);
 	const halfPoints = numericAttr(firstSize ?? null, "val") || DEFAULT_FONT_HALF_POINTS;
 	const color = colorFrom(findAllDeep(wsp, "w", "color").at(0) ?? null, DEFAULT_TEXT_COLOR);
-	const fontSize = halfPoints * HALF_POINT_TO_EMU;
+	const fontSize = halfPoints * HALF_POINT_TO_EMU / unitScale;
 	const maxCharacters = Math.max(1, Math.floor(width / (fontSize * .38)));
 	const lines = paragraphs.flatMap((paragraph) => wrapLine(getTextContent(paragraph).slice(0, MAX_TEXT_CHARACTERS), maxCharacters)).map(escapeXmlText);
 	if (lines.length === 0) return "";
@@ -137,38 +171,92 @@ const renderPicture = (picture, index, rels, media) => {
 	return `<defs><clipPath id="${clipId}"><rect x="${x}" y="${y}" width="${width}" height="${height}"/></clipPath></defs><g clip-path="url(#${clipId})">${image}</g>`;
 };
 const groupViewBox = (group, width, height) => {
-	const transform = findChildByLocalName(findChildByLocalName(group, "grpSpPr"), "xfrm");
-	const childOffset = findChildByLocalName(transform, "chOff");
-	const childExtent = findChildByLocalName(transform, "chExt");
-	const childWidth = numericAttr(childExtent, "cx");
-	const childHeight = numericAttr(childExtent, "cy");
+	const transform = readTransform(findChildByLocalName(findChildByLocalName(group, "grpSpPr"), "xfrm"));
 	return {
-		x: numericAttr(childOffset, "x"),
-		y: numericAttr(childOffset, "y"),
-		width: childWidth > 0 ? childWidth : width,
-		height: childHeight > 0 ? childHeight : height
+		x: transform.childX,
+		y: transform.childY,
+		width: transform.childWidth > 0 ? transform.childWidth : width,
+		height: transform.childHeight > 0 ? transform.childHeight : height
 	};
 };
-const createSvg = (group, width, height, rels, media) => {
-	const children = getChildElements(group).slice(0, MAX_GROUP_SHAPES);
-	let content = "";
-	for (const [index, child] of children.entries()) {
-		const localName = getLocalName(child.name ?? "");
-		let piece;
-		if (localName === "pic") piece = renderPicture(child, index, rels, media);
-		else if (localName === "wsp") piece = findChildByLocalName(child, "txbx") ? renderTextBox(child) : renderGeometry(child);
-		else continue;
-		content += piece;
-		if (content.length > MAX_SVG_CHARACTERS) return null;
-	}
-	if (!content) return null;
+/**
+* A nested group's child space drawn inside its frame in the parent's space,
+* then turned by the group's own rotation and flips.
+*/
+const nestedGroupTransform = (transform) => {
+	const scaleX = transform.childWidth > 0 ? transform.width / transform.childWidth : 1;
+	const scaleY = transform.childHeight > 0 ? transform.height / transform.childHeight : 1;
+	return `translate(${transform.x} ${transform.y}) scale(${scaleX} ${scaleY}) translate(${-transform.childX} ${-transform.childY})`;
+};
+const averageScale = (scale) => (scale.x + scale.y) / 2 || 1;
+const createSvg = (group, width, height, rels, media, hostedTextBoxes) => {
+	let total = 0;
+	let shapes = 0;
+	let serial = 0;
+	/** One container's markup, or null once the budget is spent. */
+	const render = (container, scale, depth) => {
+		let content = "";
+		for (const child of getChildElements(container)) {
+			const index = serial;
+			serial += 1;
+			if (shapes >= MAX_GROUP_SHAPES) break;
+			const localName = getLocalName(child.name ?? "");
+			let piece;
+			if (localName === "pic") {
+				shapes += 1;
+				piece = withChildTransform(child, renderPicture(child, index, rels, media));
+			} else if (localName === "wsp") {
+				shapes += 1;
+				if (hostedTextBoxes.has(child)) continue;
+				const unitScale = averageScale(scale);
+				piece = withChildTransform(child, findChildByLocalName(child, "txbx") ? `${renderGeometry(child, unitScale)}${renderTextBox(child, unitScale)}` : renderGeometry(child, unitScale));
+			} else if (localName === "grpSp" && depth < MAX_GROUP_DEPTH) {
+				const transform = readTransform(findChildByLocalName(findChildByLocalName(child, "grpSpPr"), "xfrm"));
+				const scaleX = transform.childWidth > 0 ? transform.width / transform.childWidth : 1;
+				const scaleY = transform.childHeight > 0 ? transform.height / transform.childHeight : 1;
+				const nested = render(child, {
+					x: scale.x * scaleX,
+					y: scale.y * scaleY
+				}, depth + 1);
+				if (nested === null) return null;
+				piece = nested ? wrapTransformed(transform, `<g transform="${nestedGroupTransform(transform)}">${nested}</g>`) : "";
+				total -= nested.length;
+			} else continue;
+			content += piece;
+			total += piece.length;
+			if (total > MAX_SVG_CHARACTERS) return null;
+		}
+		return content;
+	};
 	const viewBox = groupViewBox(group, width, height);
+	const content = render(group, {
+		x: width / viewBox.width,
+		y: height / viewBox.height
+	}, 0);
+	if (content === null || !content && hostedTextBoxes.size === 0) return null;
 	return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBox.x} ${viewBox.y} ${viewBox.width} ${viewBox.height}" width="${emuToPixels(width)}" height="${emuToPixels(height)}">${content}</svg>`;
 };
 const groupElement = (drawing) => {
 	return findChildByLocalName(findAllDeep(drawing, "a", "graphicData").at(0) ?? null, "wgp");
 };
 /**
+* Whether the layout can place the group's text boxes itself. A floating group
+* positioned by offsets on both axes puts each child at the group's offset
+* plus the child's frame, which a text box anchored beside the group can state
+* exactly; an inline group or one placed by alignment has no such offset.
+*/
+const hostsTextBoxes = (image) => {
+	const position = image.position;
+	return image.wrap.type !== "inline" && image.anchor?.useSimplePosition !== true && position !== void 0 && position.horizontal.alignment === void 0 && position.horizontal.posOffset !== void 0 && position.vertical.alignment === void 0 && position.vertical.posOffset !== void 0;
+};
+/** The text boxes each group preview leaves to the layout, keyed by the preview. */
+const hostedTextBoxFrames = /* @__PURE__ */ new WeakMap();
+/**
+* The text boxes a group preview does not draw, which the paragraph parser
+* lifts out as text boxes of their own. Undefined for any other image.
+*/
+const groupPreviewTextBoxes = (image) => hostedTextBoxFrames.get(image);
+/**
 * Whether a `w:drawing` carries a WordprocessingGroup payload. A group this
 * module declines to rasterize has no editable projection either — the shape
 * model holds one shape, not a group — so the caller must preserve it raw.
@@ -180,10 +268,13 @@ const parseGroupDrawing = (drawing, previews, rels, media) => {
 	if (!group) return null;
 	const image = parseImage(drawing, void 0, void 0);
 	if (!image || image.size.width <= 0 || image.size.height <= 0) return null;
-	const svg = createSvg(group, image.size.width, image.size.height, rels, media);
+	const hosted = hostsTextBoxes(image) ? collectGroupTextBoxes(group, image.size.width, image.size.height) : [];
+	const svg = createSvg(group, image.size.width, image.size.height, rels, media, new Set(hosted.map(({ wsp }) => wsp)));
 	if (!svg || svg.length > MAX_SVG_CHARACTERS) return null;
 	const { rId: _rId, src: _src, mimeType: _mimeType, filename: _filename, ...frame } = image;
-	return previews.svgImage("wpGroup", svg, frame);
+	const preview = previews.svgImage("wpGroup", svg, frame);
+	if (hosted.length > 0) hostedTextBoxFrames.set(preview, hosted);
+	return preview;
 };
 //#endregion
-export { isGroupDrawing, parseGroupDrawing };
+export { groupPreviewTextBoxes, isGroupDrawing, parseGroupDrawing };

package/dist/docx/packageParts.d.ts

@@ -19,6 +19,16 @@ type PackageReferenceRepair = {
   danglingRelationships: string[];
   /** Parts a content-type override named that the package does not hold. */
   danglingOverrides: string[];
+  /**
+   * `<part>|<id>` pairs: an `r:*`-style attribute in `part` named a
+   * relationship id that reconciliation just removed from `part`'s own
+   * `.rels` (because that relationship's target was itself a dangling
+   * reference). Dropping the relationship without also dropping the
+   * attribute that names it would trade one dangling reference for another —
+   * a `.rels` entry pointing nowhere becomes a content attribute pointing at
+   * nothing in its own `.rels`, which is no more valid.
+   */
+  orphanedIdReferences: string[];
 };
 /**
  * Make the package internally consistent before it is written: every internal
@@ -31,5 +41,39 @@ type PackageReferenceRepair = {
  * which is what the repack tests assert about their own output.
  */
 declare const reconcilePackageReferences: (zip: JSZip, compressionLevel: number) => Promise<PackageReferenceRepair>;
+/**
+ * What {@link checkPackageIntegrity} found wrong with a package. Both fields
+ * are empty for a package where every internal relationship resolves and
+ * every reference to one does too — the state {@link reconcilePackageReferences}
+ * is meant to leave behind, and the state a save must never regress from.
+ */
+type PackageIntegrityReport = {
+  /**
+   * `<part>|<id>` pairs: an `r:*`-style attribute in `part` names a
+   * relationship id absent from `part`'s own `.rels` — the id was never
+   * declared, or a repair (this module's or any other) dropped it without
+   * also dropping the attribute that names it.
+   */
+  unresolvedReferences: string[];
+  /**
+   * `<relsPart>|<target>` pairs: an internal (non-external) relationship in
+   * `relsPart` names a target the package does not hold.
+   */
+  danglingRelationshipTargets: string[];
+};
+/**
+ * Verify the two invariants an OPC package must hold for a conforming
+ * consumer to accept it: every `r:*` reference in an XML part resolves in
+ * that part's own `.rels`, and every internal relationship target names a
+ * part the package actually holds.
+ *
+ * A read-only counterpart to {@link reconcilePackageReferences} — that
+ * function repairs a package by removing what does not resolve; this one
+ * only reports what still does not, so a test can assert a save produced
+ * nothing for it to find. Cheap enough to run after every repack in a test
+ * or a corpus-gate invariant: one pass over the `.rels` parts building an id
+ * census, one pass over the XML parts checking references against it.
+ */
+declare const checkPackageIntegrity: (zip: JSZip) => Promise<PackageIntegrityReport>;
 //#endregion
-export { PackageReferenceRepair, isUnsafePackagePath, reconcilePackageReferences, removeUnsafeEntries };
+export { PackageIntegrityReport, PackageReferenceRepair, checkPackageIntegrity, isUnsafePackagePath, reconcilePackageReferences, removeUnsafeEntries };

package/dist/docx/packageParts.js

@@ -3,9 +3,25 @@ import { resolveRelativePath } from "./relsParser.js";
 const CONTENT_TYPE_ELEMENT = /<(?:Default|Override)\b[^>]*?\/?>/giu;
 const PART_NAME_ATTRIBUTE = /\bPartName\s*=\s*(?<quote>["'])(?<value>[^"']*)\k<quote>/u;
 const RELATIONSHIP_ELEMENT = /<Relationship\b[^>]*?(?:\/>|>\s*<\/Relationship>)/giu;
+const RELATIONSHIP_ID_ATTRIBUTE = /\bId\s*=\s*(?<quote>["'])(?<value>[^"']*)\k<quote>/u;
 const TARGET_ATTRIBUTE = /\bTarget\s*=\s*(?<quote>["'])(?<value>[^"']*)\k<quote>/u;
 const TARGET_MODE_ATTRIBUTE = /\bTargetMode\s*=\s*(?<quote>["'])(?<value>[^"']*)\k<quote>/u;
 const CONTENT_TYPES_PATTERN = /^\[Content_Types\]\.xml$/iu;
+/** Escape a string for literal use inside a `RegExp`. */
+const escapeRegExp = (value) => value.replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+/**
+* The XML part a `.rels` part describes: `word/_rels/header1.xml.rels` ->
+* `word/header1.xml`; the package-level `_rels/.rels` has no single owning
+* part (its relationships are resolved by type, never by `r:id`), so it maps
+* to `undefined`.
+*/
+const owningPartPath = (relsPath) => {
+	const slash = relsPath.lastIndexOf("/_rels/");
+	if (slash === -1) return;
+	const directory = relsPath.slice(0, slash);
+	const fileName = relsPath.slice(slash + 7).replace(/\.rels$/iu, "");
+	return fileName ? `${directory ? `${directory}/` : ""}${fileName}` : void 0;
+};
 /** Normalize a package path for comparison: lower case, no leading slash. */
 const normalizePartPath = (path) => (path.startsWith("/") ? path.slice(1) : path).toLowerCase();
 /**
@@ -80,8 +96,10 @@ const reconcilePackageReferences = async (zip, compressionLevel) => {
 	const present = presentPartPaths(zip);
 	const repair = {
 		danglingRelationships: [],
-		danglingOverrides: []
+		danglingOverrides: [],
+		orphanedIdReferences: []
 	};
+	const removedIdsByOwningPart = /* @__PURE__ */ new Map();
 	for (const { path, xml } of await readRelationshipParts(zip)) {
 		let dropped = false;
 		const pruned = xml.replaceAll(RELATIONSHIP_ELEMENT, (element) => {
@@ -89,6 +107,13 @@ const reconcilePackageReferences = async (zip, compressionLevel) => {
 			if (target === null || isPresent(present, target)) return element;
 			repair.danglingRelationships.push(target);
 			dropped = true;
+			const id = RELATIONSHIP_ID_ATTRIBUTE.exec(element)?.groups?.["value"];
+			const owningPart = owningPartPath(path);
+			if (id !== void 0 && owningPart !== void 0) {
+				const ids = removedIdsByOwningPart.get(owningPart) ?? /* @__PURE__ */ new Set();
+				ids.add(id);
+				removedIdsByOwningPart.set(owningPart, ids);
+			}
 			return "";
 		});
 		if (dropped) writePart({
@@ -98,6 +123,28 @@ const reconcilePackageReferences = async (zip, compressionLevel) => {
 			compressionLevel
 		});
 	}
+	for (const [partPath, ids] of removedIdsByOwningPart) {
+		const file = zip.file(partPath);
+		if (!file) continue;
+		const idPattern = [...ids].map((id) => escapeRegExp(id)).join("|");
+		const referencePattern = new RegExp(`\\s+r:[A-Za-z]+\\s*=\\s*(?<quote>["'])(?<id>${idPattern})\\k<quote>`, "gu");
+		const xml = await file.async("text");
+		const removedIds = /* @__PURE__ */ new Set();
+		const scrubbed = xml.replaceAll(referencePattern, (...args) => {
+			const groups = args.at(-1);
+			if (groups?.id !== void 0) removedIds.add(groups.id);
+			return "";
+		});
+		if (removedIds.size > 0) {
+			writePart({
+				zip,
+				path: partPath,
+				xml: scrubbed,
+				compressionLevel
+			});
+			for (const id of removedIds) repair.orphanedIdReferences.push(`${partPath}|${id}`);
+		}
+	}
 	const contentTypes = zip.file(CONTENT_TYPES_PATTERN)[0];
 	if (!contentTypes) return repair;
 	let droppedOverride = false;
@@ -116,5 +163,49 @@ const reconcilePackageReferences = async (zip, compressionLevel) => {
 	});
 	return repair;
 };
+/** Every `r:*`-style attribute value found anywhere in an XML part's text. */
+const REFERENCE_ATTRIBUTE = /\br:[A-Za-z]+\s*=\s*(?<quote>["'])(?<id>[^"']*)\k<quote>/gu;
+/**
+* Verify the two invariants an OPC package must hold for a conforming
+* consumer to accept it: every `r:*` reference in an XML part resolves in
+* that part's own `.rels`, and every internal relationship target names a
+* part the package actually holds.
+*
+* A read-only counterpart to {@link reconcilePackageReferences} — that
+* function repairs a package by removing what does not resolve; this one
+* only reports what still does not, so a test can assert a save produced
+* nothing for it to find. Cheap enough to run after every repack in a test
+* or a corpus-gate invariant: one pass over the `.rels` parts building an id
+* census, one pass over the XML parts checking references against it.
+*/
+const checkPackageIntegrity = async (zip) => {
+	const present = presentPartPaths(zip);
+	const report = {
+		unresolvedReferences: [],
+		danglingRelationshipTargets: []
+	};
+	const idsByOwningPart = /* @__PURE__ */ new Map();
+	for (const { path, xml } of await readRelationshipParts(zip)) {
+		const owningPart = owningPartPath(path);
+		const ids = /* @__PURE__ */ new Set();
+		for (const element of xml.match(RELATIONSHIP_ELEMENT) ?? []) {
+			const id = RELATIONSHIP_ID_ATTRIBUTE.exec(element)?.groups?.["value"];
+			if (id !== void 0) ids.add(id);
+			const target = relationshipTarget(element, path);
+			if (target !== null && !isPresent(present, target)) report.danglingRelationshipTargets.push(`${path}|${target}`);
+		}
+		if (owningPart !== void 0) idsByOwningPart.set(owningPart, ids);
+	}
+	for (const [path, file] of Object.entries(zip.files)) {
+		if (file.dir || !normalizePartPath(path).endsWith(".xml")) continue;
+		const xml = await file.async("text");
+		const ids = idsByOwningPart.get(path);
+		for (const match of xml.matchAll(REFERENCE_ATTRIBUTE)) {
+			const id = match.groups?.["id"];
+			if (id !== void 0 && !ids?.has(id)) report.unresolvedReferences.push(`${path}|${id}`);
+		}
+	}
+	return report;
+};
 //#endregion
-export { isUnsafePackagePath, reconcilePackageReferences, removeUnsafeEntries };
+export { checkPackageIntegrity, isUnsafePackagePath, reconcilePackageReferences, removeUnsafeEntries };

package/dist/docx/paraIdAttribute.d.ts

@@ -85,8 +85,9 @@ declare const alignParagraphOrdinals: (base: readonly ParagraphIdentity[], revis
  * describe one document — the source part and the model parsed from it — so
  * {@link alignParagraphOrdinals}'s `consistent` is the whole of the question: a
  * package with ids on some paragraphs proves its own alignment through them,
- * and one with none is aligned vacuously behind the paragraph-count check the
- * caller already runs.
+ * and one with none is aligned exactly when the two sequences have the same
+ * length. The save asks this per story (main flow, text boxes), so a text box
+ * the model re-reads cannot misalign the main flow.
  */
 type ParagraphIdentityPlan = {
   identities: readonly ParagraphIdentity[];

package/dist/docx/paragraphParser.js

@@ -676,6 +676,81 @@ const FIELD_INLINE_WRAPPER_HANDLERS = {
 	pPr: CAPTURE
 };
 /**
+* The container children a complex field's result may hold and still be
+* assembled into a `ComplexField`: its runs and the zero-width markers read
+* beside them. Any other child is inline content (a hyperlink, a simple field,
+* a content control, a revision, a wrapper, an equation) that `fieldResult`
+* has no place for.
+*/
+const FIELD_TRANSPARENT_CHILDREN = /* @__PURE__ */ new Set([
+	"r",
+	"pPr",
+	"smartTagPr",
+	"customXmlPr",
+	"bookmarkStart",
+	"bookmarkEnd",
+	"commentRangeStart",
+	"commentRangeEnd",
+	"moveFromRangeStart",
+	"moveFromRangeEnd",
+	"moveToRangeStart",
+	"moveToRangeEnd",
+	"proofErr",
+	"permStart",
+	"permEnd",
+	"customXmlDelRangeStart",
+	"customXmlDelRangeEnd",
+	"customXmlInsRangeStart",
+	"customXmlInsRangeEnd",
+	"customXmlMoveFromRangeStart",
+	"customXmlMoveFromRangeEnd",
+	"customXmlMoveToRangeStart",
+	"customXmlMoveToRangeEnd"
+]);
+const isWordprocessingChild = (child) => {
+	const namespace = getNamespaceUri(child);
+	return namespace === void 0 || WORDPROCESSINGML_NAMESPACE_URIS.has(namespace);
+};
+/**
+* The `w:r` children whose `begin` opens a complex field that this container's
+* walk closes.
+*
+* A field is assembled from the runs between its `begin` and its `end`, so it
+* exists only when both are runs of this container with nothing between them
+* that a `ComplexField` cannot hold. A TOC opened here and closed in a later
+* paragraph, a field whose result holds a `w:hyperlink` (a TOC's `\h` entries),
+* and an outer field whose result holds a nested field are none of these; their
+* runs are ordinary content, read in source order alongside the siblings
+* between them. Mirrors the `w:r` handler run by run: a run with a `begin`
+* opens a field, and a run with an `end` closes the one open.
+*/
+const assembledFieldBeginsOf = (container) => {
+	const assembled = /* @__PURE__ */ new Set();
+	let open;
+	for (const child of getChildElements(container)) {
+		const wordprocessing = isWordprocessingChild(child);
+		const localName = getLocalName(child.name);
+		if (!wordprocessing || localName !== "r") {
+			if (!wordprocessing || !FIELD_TRANSPARENT_CHILDREN.has(localName)) open = void 0;
+			continue;
+		}
+		let hasBegin = false;
+		let hasEnd = false;
+		for (const runChild of getChildElements(child)) {
+			if (getLocalName(runChild.name) !== "fldChar" || !isWordprocessingChild(runChild)) continue;
+			const charType = getAttribute(runChild, "w", "fldCharType");
+			if (charType === "end") hasEnd = true;
+			else if (charType !== "separate") hasBegin = true;
+		}
+		if (hasBegin) open = child;
+		if (hasEnd && open !== void 0) {
+			assembled.add(open);
+			open = void 0;
+		}
+	}
+	return assembled;
+};
+/**
 * A transparent wrapper at paragraph level. All four hold ordinary inline
 * content and say something about it rather than about the text, so the
 * recursion is this same walk and `inlineWrapperOf` reads what the element
@@ -714,8 +789,12 @@ const PARAGRAPH_CONTENT_HANDLERS = {
 		}
 		else if (content.type === "instrText") instrText += content.text;
 		if (hasFieldBegin) {
-			if (scan.inComplexField && scan.afterSeparator) {
-				contents.push(...scan.complexFieldResultRuns);
+			scan.assembledFieldBegins ??= assembledFieldBeginsOf(scan.container);
+			if (!scan.assembledFieldBegins.has(child)) hasFieldBegin = false;
+		}
+		if (hasFieldBegin) {
+			if (scan.inComplexField) {
+				contents.push(...scan.complexFieldOpenRuns);
 				scan.inComplexField = false;
 			}
 			scan.inComplexField = true;
@@ -751,7 +830,11 @@ const PARAGRAPH_CONTENT_HANDLERS = {
 			}
 			if (hasFieldEnd) {
 				let resultRuns = scan.complexFieldResultRuns;
-				if (resultRuns.length === 0 && scan.complexFieldFallbackDisplay !== void 0 && isLegacyFormCheckboxInstruction(scan.complexFieldInstr)) resultRuns = [createLegacyFormCheckboxResultRun(scan.complexFieldFallbackDisplay, scan.complexFieldFormatting)];
+				let resultIsFallback = false;
+				if (resultRuns.length === 0 && scan.complexFieldFallbackDisplay !== void 0 && isLegacyFormCheckboxInstruction(scan.complexFieldInstr)) {
+					resultRuns = [createLegacyFormCheckboxResultRun(scan.complexFieldFallbackDisplay, scan.complexFieldFormatting)];
+					resultIsFallback = true;
+				}
 				if (resultRuns.length === 0 && !scan.afterSeparator && endOriginalValue !== void 0) resultRuns = [{
 					type: "run",
 					content: [{
@@ -767,6 +850,7 @@ const PARAGRAPH_CONTENT_HANDLERS = {
 					fieldResult: resultRuns,
 					...scan.complexFieldState
 				};
+				if (resultIsFallback) complexField.fieldResultIsFallback = true;
 				if (scan.complexFieldFormatting) complexField.formatting = scan.complexFieldFormatting;
 				contents.push(complexField);
 				if (commentReferenceId !== null) contents.push({
@@ -922,7 +1006,9 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 		afterSeparator: false,
 		complexFieldState: {},
 		complexFieldFallbackDisplay: void 0,
-		complexFieldFormatting: void 0
+		complexFieldFormatting: void 0,
+		container: paraElement,
+		assembledFieldBegins: void 0
 	};
 	const preserved = dispatchChildrenWithContext({
 		element: paraElement,
@@ -1096,9 +1182,7 @@ function parseParagraph(node, styles, theme, numbering, rels = null, media = nul
 					if (!paragraph.formatting) paragraph.formatting = {};
 					const directInd = pPr ? findChild(pPr, "w", "ind") : null;
 					const hasDirectLeft = hasAttributeAnySpelling(directInd, "CT_Ind @left");
-					const directFirstLine = directInd ? parseNumericAttribute(directInd, "w", "firstLine") : void 0;
-					const directHanging = directInd ? parseNumericAttribute(directInd, "w", "hanging") : void 0;
-					const hasDirectFirstLineOrHanging = directFirstLine !== void 0 && directFirstLine !== 0 || directHanging !== void 0 && directHanging !== 0;
+					const hasDirectFirstLineOrHanging = parseNumericAttribute(directInd, "w", "firstLine") !== void 0 || parseNumericAttribute(directInd, "w", "hanging") !== void 0;
 					if (!hasDirectLeft && !chainInd.left && level.pPr.indentLeft !== void 0) paragraph.formatting.indentLeft = level.pPr.indentLeft;
 					if (!hasDirectFirstLineOrHanging && !chainInd.firstLine && numberingLevelHasMarkerSlot(level)) {
 						if (level.pPr.indentFirstLine !== void 0) paragraph.formatting.indentFirstLine = level.pPr.indentFirstLine;