@stll/folio-core 0.48.0 → 0.49.0

package/dist/docx/drawingGroupChildren.js

@@ -0,0 +1,176 @@
+import { canonicalJson } from "../utils/canonicalJson.js";
+import { captureVerbatimXml } from "./verbatimCapture.js";
+import { findChildByLocalName, findDeep, getAttribute, getChildElements, getLocalName, parseNumericAttribute, parseXml } from "./xmlParser.js";
+//#region src/docx/drawingGroupChildren.ts
+/**
+* The text boxes of a DrawingML group (`wpg:wgp`), read as frames folio can lay
+* out, and written back into the group's authored XML.
+*
+* A group states a child coordinate space (`a:chOff` / `a:chExt`) that its
+* own frame (`a:off` / `a:ext`) maps onto, and every child's `a:xfrm` is in
+* that space; a nested `wpg:grpSp` repeats the mapping one level down
+* (ECMA-376 §20.1.7.5). Composing the mappings gives each `wps:wsp` a frame
+* in EMUs relative to the group's own top-left corner. Only the frame is
+* mapped: the text inside keeps its authored size and the body insets stay in
+* EMUs.
+*/
+/** `a:xfrm@rot` is in 60,000ths of a degree. */
+const ROTATION_UNITS_PER_DEGREE = 6e4;
+/** Deeper nesting than this is not a drawing anyone authored. */
+const MAX_GROUP_DEPTH = 16;
+const MAX_GROUP_TEXT_BOXES = 256;
+const numberAttribute = (element, name) => parseNumericAttribute(element, null, name) ?? 0;
+const onOffAttribute = (element, name) => {
+	const value = getAttribute(element, null, name);
+	return value === "1" || value === "true" || value === "on";
+};
+/** A `CT_GroupTransform2D` or `CT_Transform2D`; absent children read as zero. */
+const readTransform = (xfrm) => {
+	const offset = findChildByLocalName(xfrm, "off");
+	const extent = findChildByLocalName(xfrm, "ext");
+	const childOffset = findChildByLocalName(xfrm, "chOff");
+	const childExtent = findChildByLocalName(xfrm, "chExt");
+	return {
+		x: numberAttribute(offset, "x"),
+		y: numberAttribute(offset, "y"),
+		width: numberAttribute(extent, "cx"),
+		height: numberAttribute(extent, "cy"),
+		childX: numberAttribute(childOffset, "x"),
+		childY: numberAttribute(childOffset, "y"),
+		childWidth: numberAttribute(childExtent, "cx"),
+		childHeight: numberAttribute(childExtent, "cy"),
+		rotation: numberAttribute(xfrm, "rot") / ROTATION_UNITS_PER_DEGREE,
+		flipH: onOffAttribute(xfrm, "flipH"),
+		flipV: onOffAttribute(xfrm, "flipV")
+	};
+};
+const groupTransform = (group) => readTransform(findChildByLocalName(findChildByLocalName(group, "grpSpPr"), "xfrm"));
+const shapeTransform = (shape) => readTransform(findChildByLocalName(findChildByLocalName(shape, "spPr"), "xfrm"));
+/**
+* The top-level mapping: the group's child space stretched over the drawing's
+* extent. A missing or empty child extent means the child space is the
+* drawing's own.
+*/
+const rootMap = (group, width, height) => {
+	const transform = groupTransform(group);
+	const scaleX = transform.childWidth > 0 ? width / transform.childWidth : 1;
+	const scaleY = transform.childHeight > 0 ? height / transform.childHeight : 1;
+	return {
+		scaleX,
+		scaleY,
+		offsetX: -transform.childX * scaleX,
+		offsetY: -transform.childY * scaleY
+	};
+};
+/** A nested group's child space, mapped through its frame in the parent's space. */
+const nestedMap = (parent, transform) => {
+	const scaleX = transform.childWidth > 0 ? transform.width / transform.childWidth : 1;
+	const scaleY = transform.childHeight > 0 ? transform.height / transform.childHeight : 1;
+	return {
+		scaleX: parent.scaleX * scaleX,
+		scaleY: parent.scaleY * scaleY,
+		offsetX: parent.scaleX * (transform.x - transform.childX * scaleX) + parent.offsetX,
+		offsetY: parent.scaleY * (transform.y - transform.childY * scaleY) + parent.offsetY
+	};
+};
+const hasTextBox = (wsp) => findChildByLocalName(findChildByLocalName(wsp, "txbx"), "txbxContent") !== null;
+/**
+* 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.
+*/
+const collectGroupTextBoxes = (group, width, height) => {
+	const frames = [];
+	const visit = (container, map, path, depth) => {
+		for (const [index, child] of getChildElements(container).entries()) {
+			if (frames.length >= MAX_GROUP_TEXT_BOXES) return;
+			const localName = getLocalName(child.name ?? "");
+			if (localName === "grpSp" && depth < MAX_GROUP_DEPTH) {
+				const transform = groupTransform(child);
+				if (transform.rotation === 0 && !transform.flipH && !transform.flipV) visit(child, nestedMap(map, transform), [...path, index], depth + 1);
+				continue;
+			}
+			if (localName !== "wsp" || !hasTextBox(child)) continue;
+			const transform = shapeTransform(child);
+			const frameWidth = transform.width * map.scaleX;
+			const frameHeight = transform.height * map.scaleY;
+			if (!(frameWidth > 0 && frameHeight > 0)) continue;
+			frames.push({
+				path: [...path, index],
+				wsp: child,
+				x: transform.x * map.scaleX + map.offsetX,
+				y: transform.y * map.scaleY + map.offsetY,
+				width: frameWidth,
+				height: frameHeight,
+				rotation: transform.rotation,
+				flipH: transform.flipH,
+				flipV: transform.flipV
+			});
+		}
+	};
+	visit(group, rootMap(group, width, height), [], 0);
+	return frames;
+};
+/** Two FNV-1a passes with different offsets: a short, stable identity. */
+const fingerprint = (text) => {
+	let first = 2166136261;
+	let second = 16777619;
+	for (let index = 0; index < text.length; index += 1) {
+		const code = text.charCodeAt(index);
+		first = Math.imul(first ^ code, 16777619);
+		second = Math.imul(second ^ code, 96280213);
+	}
+	return `${(first >>> 0).toString(16).padStart(8, "0")}${(second >>> 0).toString(16).padStart(8, "0")}`;
+};
+/** Identity of a group drawing's authored XML. */
+const groupXmlFingerprint = (rawXml) => fingerprint(rawXml);
+/** Identity of a text box's content, compared on save to tell an edit. */
+const groupTextContentFingerprint = (content) => fingerprint(canonicalJson(content));
+/** The group a captured drawing carries; a Fallback branch holds none. */
+const findGroup = (root) => findDeep(root, "wpg", "wgp") ?? void 0;
+const childAtPath = (group, path) => {
+	let current = group;
+	for (const index of path) current = current ? getChildElements(current)[index] : void 0;
+	return current;
+};
+/**
+* The text box content element a path names, or undefined when the path does
+* not lead to a `wps:wsp` holding one.
+*/
+const textBoxContentAt = (group, path) => {
+	const wsp = childAtPath(group, path);
+	if (!wsp || getLocalName(wsp.name ?? "") !== "wsp") return;
+	return findChildByLocalName(findChildByLocalName(wsp, "txbx"), "txbxContent") ?? void 0;
+};
+/**
+* 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.
+*/
+const replaceGroupTextBoxContent = (rawXml, edits) => {
+	const root = parseXml(rawXml);
+	const group = findGroup(root);
+	if (!group) return;
+	const replacements = /* @__PURE__ */ new Map();
+	for (const [index, edit] of edits.entries()) {
+		const content = textBoxContentAt(group, edit.path);
+		if (!content) return;
+		const placeholder = `folio-group-text-${index}-${fingerprint(rawXml)}`;
+		content.elements = [{
+			type: "element",
+			name: placeholder
+		}];
+		replacements.set(`<${placeholder}/>`, edit.contentXml || "<w:p/>");
+	}
+	let xml = (root.elements ?? []).map((element) => captureVerbatimXml(element)).join("");
+	for (const [placeholder, contentXml] of replacements) xml = xml.replace(placeholder, () => contentXml);
+	return xml;
+};
+//#endregion
+export { collectGroupTextBoxes, groupTextContentFingerprint, groupXmlFingerprint, readTransform, replaceGroupTextBoxContent };

package/dist/docx/drawingUtils.js

@@ -107,6 +107,7 @@ function parseFill(spPr) {
 function parseGradientFill(gradientFill) {
 	let type = "linear";
 	let angle;
+	let scaled;
 	const linear = findChildByLocalName(gradientFill, "lin");
 	if (linear) {
 		const authoredAngle = getAttribute(linear, null, "ang");
@@ -114,6 +115,7 @@ function parseGradientFill(gradientFill) {
 			const parsedAngle = Number.parseInt(authoredAngle, 10);
 			angle = Number.isNaN(parsedAngle) ? void 0 : parsedAngle / 6e4;
 		}
+		scaled = parseOnOffValue(getAttribute(linear, null, "scaled"), void 0, "a:lin@scaled");
 	}
 	const path = findChildByLocalName(gradientFill, "path");
 	if (path) {
@@ -139,6 +141,7 @@ function parseGradientFill(gradientFill) {
 		gradient: {
 			type,
 			...angle !== void 0 ? { angle } : {},
+			...scaled !== void 0 ? { scaled } : {},
 			stops
 		}
 	};

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[];