@stll/folio-core 0.37.5 → 0.39.0

package/dist/display-list/types.d.ts

@@ -357,6 +357,19 @@ type DisplayLinkTarget = {
   readonly pageIndex: number;
   readonly yPx: number;
 };
+/**
+ * One DOCX comment whose anchor reaches this page.
+ *
+ * A range may cross run and line boundaries, so every painted rectangle is
+ * retained. Raster backends use those rectangles for the highlight; PDF uses
+ * the final one as the location of its single text annotation.
+ */
+type DisplayCommentAnnotation = {
+  readonly commentId: number;
+  readonly rects: readonly DisplayRect[];
+  readonly contents: string;
+  readonly author: string;
+};
 /**
  * What kind of thing a click landed in.
  *
@@ -437,6 +450,8 @@ type DisplayPage = {
    */
   readonly regions: readonly DisplayHitRegion[];
   readonly links: readonly DisplayLink[];
+  /** Native review comments anchored on this page. */
+  readonly comments: readonly DisplayCommentAnnotation[];
 };
 /** One heading, for a document outline. `pageIndex` is 0-based. */
 type DisplayOutlineEntry = {
@@ -473,4 +488,4 @@ type DisplayList = {
   readonly unsupported: readonly DisplayUnsupported[];
 };
 //#endregion
-export { DisplayClipGroup, DisplayColor, DisplayEmbeddedFont, DisplayFontFace, DisplayFontRef, DisplayGlyphRun, DisplayHitRegion, DisplayHitRegionKind, DisplayHitRegionModel, DisplayImagePrimitive, DisplayImageRef, DisplayImageSource, DisplayLine, DisplayLink, DisplayLinkTarget, DisplayList, DisplayMetadata, DisplayModelRange, DisplayOpacityGroup, DisplayOutlineEntry, DisplayPage, DisplayPrimitive, DisplayRect, DisplayRectPrimitive, DisplayRotateGroup, DisplayRunAdjustments, DisplayStoryRef, DisplayStroke, DisplayStrokePattern, DisplayUnsupported };
+export { DisplayClipGroup, DisplayColor, DisplayCommentAnnotation, DisplayEmbeddedFont, DisplayFontFace, DisplayFontRef, DisplayGlyphRun, DisplayHitRegion, DisplayHitRegionKind, DisplayHitRegionModel, DisplayImagePrimitive, DisplayImageRef, DisplayImageSource, DisplayLine, DisplayLink, DisplayLinkTarget, DisplayList, DisplayMetadata, DisplayModelRange, DisplayOpacityGroup, DisplayOutlineEntry, DisplayPage, DisplayPrimitive, DisplayRect, DisplayRectPrimitive, DisplayRotateGroup, DisplayRunAdjustments, DisplayStoryRef, DisplayStroke, DisplayStrokePattern, DisplayUnsupported };

package/dist/document-operations.d.ts

@@ -7,6 +7,8 @@ declare const FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION: 1;
 declare const FOLIO_PARAGRAPH_ALIGNMENT_VALUES: readonly ("left" | "center" | "right" | "both" | "distribute" | "mediumKashida" | "highKashida" | "lowKashida" | "thaiDistribute")[];
 /** `w:spacing/@w:lineRule` values accepted by the operation contract. */
 declare const FOLIO_LINE_SPACING_RULE_VALUES: readonly ("auto" | "exact" | "atLeast")[];
+/** `w:br/@w:clear` values accepted on an authored hard page break. */
+declare const FOLIO_PAGE_BREAK_CLEAR_VALUES: readonly ["none", "left", "right", "all"];
 declare const FOLIO_DOCUMENT_OPERATION_TYPES: readonly ["replaceInBlock", "replaceRange", "commentOnRange", "formatRange", "insertAfterBlock", "insertBeforeBlock", "replaceBlock", "deleteBlock", "splitBlock", "mergeBlockWithNext", "setBlockParagraphProperties", "insertTable", "deleteTable", "commentOnBlock", "insertSignatureTable", "insertTableRow", "deleteTableRow", "insertTableColumn", "deleteTableColumn", "mergeTableCells", "splitTableCell"];
 declare const FOLIO_DOCUMENT_OPERATION_MODES: readonly ["direct", "tracked-changes", "suggested"];
 declare const FOLIO_DOCUMENT_OPERATION_STORIES: readonly ["main", "header", "footer", "footnote", "endnote"];
@@ -97,8 +99,8 @@ declare const FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE: Readonly<{
   readonly replaceRange: readonly ["id", "type", "range", "severity", "area", "precondition", "suggestionId", "replace", "comment"];
   readonly commentOnRange: readonly ["id", "type", "range", "severity", "area", "precondition", "comment"];
   readonly formatRange: readonly ["id", "type", "range", "severity", "area", "precondition", "suggestionId", "formatting"];
-  readonly insertAfterBlock: readonly ["id", "type", "blockId", "severity", "area", "precondition", "suggestionId", "text", "inheritFormatting", "alignment", "spacing", "listLevel", "moveId", "pageBreakBefore", "styleId", "comment"];
-  readonly insertBeforeBlock: readonly ["id", "type", "blockId", "severity", "area", "precondition", "suggestionId", "text", "inheritFormatting", "alignment", "spacing", "listLevel", "moveId", "pageBreakBefore", "styleId", "comment"];
+  readonly insertAfterBlock: readonly ["id", "type", "blockId", "severity", "area", "precondition", "suggestionId", "text", "inheritFormatting", "alignment", "spacing", "indentation", "lineBreakMode", "listLevel", "numbering", "moveId", "pageBreakBefore", "hardPageBreak", "styleId", "comment"];
+  readonly insertBeforeBlock: readonly ["id", "type", "blockId", "severity", "area", "precondition", "suggestionId", "text", "inheritFormatting", "alignment", "spacing", "indentation", "lineBreakMode", "listLevel", "numbering", "moveId", "pageBreakBefore", "hardPageBreak", "styleId", "comment"];
   readonly replaceBlock: readonly ["id", "type", "blockId", "severity", "area", "precondition", "suggestionId", "text", "preserveFormatting", "styleId", "comment"];
   readonly deleteBlock: readonly ["id", "type", "blockId", "severity", "area", "precondition", "suggestionId", "moveId", "comment"];
   readonly splitBlock: readonly ["id", "type", "blockId", "severity", "area", "precondition", "suggestionId", "offset", "separator", "firstParagraphProperties", "secondParagraphProperties"];
@@ -282,4 +284,4 @@ type ApplyFolioDocumentOperationsOptions = {
 };
 declare const applyFolioDocumentOperations: ({ view, snapshot, batch, story, author, createCommentId, createUndoHandle, revisionStamp, wordDiff, tableTemplates }: ApplyFolioDocumentOperationsOptions) => FolioDocumentOperationResult;
 //#endregion
-export { ApplyFolioDocumentOperationsOptions, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationBatchPrecondition, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationQueuedOperation, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationResultBase, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };
+export { ApplyFolioDocumentOperationsOptions, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PAGE_BREAK_CLEAR_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationBatchPrecondition, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationQueuedOperation, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationResultBase, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };

package/dist/document-operations.js

@@ -7,6 +7,13 @@ const FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION = 1;
 const FOLIO_PARAGRAPH_ALIGNMENT_VALUES = Object.freeze([...PARAGRAPH_ALIGNMENT_VALUES]);
 /** `w:spacing/@w:lineRule` values accepted by the operation contract. */
 const FOLIO_LINE_SPACING_RULE_VALUES = Object.freeze([...LINE_SPACING_RULE_VALUES]);
+/** `w:br/@w:clear` values accepted on an authored hard page break. */
+const FOLIO_PAGE_BREAK_CLEAR_VALUES = Object.freeze([
+	"none",
+	"left",
+	"right",
+	"all"
+]);
 const FOLIO_DOCUMENT_OPERATION_TYPES = Object.freeze([
 	"replaceInBlock",
 	"replaceRange",
@@ -242,6 +249,51 @@ const readClearableParagraphSpacing = ({ value, key, path }) => {
 	}
 	return spacing;
 };
+const PARAGRAPH_INDENTATION_KEYS = [
+	"indentLeft",
+	"indentRight",
+	"indentFirstLine",
+	"hangingIndent"
+];
+/** Read one complete direct `w:ind` cluster, preserving zero and false. */
+const readClearableParagraphIndentation = ({ value, key, path }) => {
+	const candidate = value[key];
+	if (candidate === void 0 || candidate === null) return candidate;
+	const indentationPath = `${path}.${key}`;
+	if (!isPlainObject(candidate)) return invalidBatch(indentationPath, "expected an object or null when provided");
+	assertAllowedKeys(candidate, indentationPath, PARAGRAPH_INDENTATION_KEYS);
+	if (Object.keys(candidate).length === 0) return invalidBatch(indentationPath, "expected at least one indentation property");
+	const indentation = {};
+	for (const numberKey of [
+		"indentLeft",
+		"indentRight",
+		"indentFirstLine"
+	]) {
+		const number = candidate[numberKey];
+		if (number === void 0) continue;
+		if (typeof number !== "number" || !Number.isSafeInteger(number)) return invalidBatch(`${indentationPath}.${numberKey}`, "expected a safe integer when provided");
+		indentation[numberKey] = number;
+	}
+	const hangingIndent = candidate["hangingIndent"];
+	if (hangingIndent !== void 0) {
+		if (typeof hangingIndent !== "boolean") return invalidBatch(`${indentationPath}.hangingIndent`, "expected a boolean when provided");
+		indentation.hangingIndent = hangingIndent;
+	}
+	return indentation;
+};
+const readClearableNumbering = ({ value, key, path }) => {
+	const candidate = value[key];
+	if (candidate === void 0 || candidate === null) return candidate;
+	const numberingPath = `${path}.${key}`;
+	if (!isPlainObject(candidate)) return invalidBatch(numberingPath, "expected an object or null when provided");
+	assertAllowedKeys(candidate, numberingPath, ["numId", "level"]);
+	const numId = readNonNegativeInteger(candidate, "numId", numberingPath);
+	if (numId === 0) return invalidBatch(`${numberingPath}.numId`, "expected a positive integer");
+	return {
+		numId,
+		level: readNonNegativeInteger(candidate, "level", numberingPath)
+	};
+};
 /**
 * A rectangular grid of cell texts. Rectangular because a table whose rows
 * hold different cell counts is not a table any consumer can lay out, and the
@@ -269,11 +321,18 @@ const readParagraphProperties = ({ value, key, path }) => {
 	assertAllowedKeys(candidate, propertiesPath, [
 		"styleId",
 		"listLevel",
+		"numbering",
 		"alignment",
-		"spacing"
+		"spacing",
+		"indentation"
 	]);
 	const styleId = candidate["styleId"] === null ? null : readOptionalString(candidate, "styleId", propertiesPath);
 	const listLevel = readClearableNonNegativeInteger(candidate, "listLevel", propertiesPath);
+	const numbering = readClearableNumbering({
+		value: candidate,
+		key: "numbering",
+		path: propertiesPath
+	});
 	const alignment = readClearableParagraphAlignment({
 		value: candidate,
 		key: "alignment",
@@ -284,12 +343,19 @@ const readParagraphProperties = ({ value, key, path }) => {
 		key: "spacing",
 		path: propertiesPath
 	});
-	if (styleId === void 0 && listLevel === void 0 && alignment === void 0 && spacing === void 0) return invalidBatch(propertiesPath, "expected at least one property to set");
+	const indentation = readClearableParagraphIndentation({
+		value: candidate,
+		key: "indentation",
+		path: propertiesPath
+	});
+	if (styleId === void 0 && listLevel === void 0 && numbering === void 0 && alignment === void 0 && spacing === void 0 && indentation === void 0) return invalidBatch(propertiesPath, "expected at least one property to set");
 	return {
 		...styleId !== void 0 && { styleId },
 		...listLevel !== void 0 && { listLevel },
+		...numbering !== void 0 && { numbering },
 		...alignment !== void 0 && { alignment },
-		...spacing !== void 0 && { spacing }
+		...spacing !== void 0 && { spacing },
+		...indentation !== void 0 && { indentation }
 	};
 };
 const readTextRange = (value, path) => {
@@ -430,9 +496,13 @@ const FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE = Object.freeze({
 		"inheritFormatting",
 		"alignment",
 		"spacing",
+		"indentation",
+		"lineBreakMode",
 		"listLevel",
+		"numbering",
 		"moveId",
 		"pageBreakBefore",
+		"hardPageBreak",
 		"styleId",
 		"comment"
 	],
@@ -442,9 +512,13 @@ const FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE = Object.freeze({
 		"inheritFormatting",
 		"alignment",
 		"spacing",
+		"indentation",
+		"lineBreakMode",
 		"listLevel",
+		"numbering",
 		"moveId",
 		"pageBreakBefore",
+		"hardPageBreak",
 		"styleId",
 		"comment"
 	],
@@ -529,6 +603,18 @@ const parseSignatureParties = (value, path) => {
 		return parsedParty;
 	});
 };
+const readOptionalHardPageBreak = (value, path) => {
+	const candidate = value["hardPageBreak"];
+	if (candidate === void 0) return;
+	if (!isPlainObject(candidate)) return invalidBatch(`${path}.hardPageBreak`, "expected an object when provided");
+	const hardPageBreakPath = `${path}.hardPageBreak`;
+	assertAllowedKeys(candidate, hardPageBreakPath, ["clear"]);
+	const clear = candidate["clear"];
+	if (clear === void 0) return {};
+	const validatedClear = FOLIO_PAGE_BREAK_CLEAR_VALUES.find((supported) => supported === clear);
+	if (validatedClear === void 0) return invalidBatch(`${hardPageBreakPath}.clear`, "expected a supported break clear value");
+	return { clear: validatedClear };
+};
 const parseDocumentOperation = (value, index) => {
 	const path = `$.operations[${index}]`;
 	if (!isPlainObject(value)) return invalidBatch(path, "expected an object");
@@ -650,9 +736,15 @@ const parseDocumentOperation = (value, index) => {
 	if (type === "insertAfterBlock" || type === "insertBeforeBlock") {
 		const inheritFormatting = readOptionalBoolean(value, "inheritFormatting", path);
 		const pageBreakBefore = readOptionalBoolean(value, "pageBreakBefore", path);
+		const hardPageBreak = readOptionalHardPageBreak(value, path);
 		const styleId = value["styleId"] === null ? null : readOptionalString(value, "styleId", path);
 		const moveId = readOptionalString(value, "moveId", path);
 		const listLevel = readClearableNonNegativeInteger(value, "listLevel", path);
+		const numbering = readClearableNumbering({
+			value,
+			key: "numbering",
+			path
+		});
 		const alignment = readClearableParagraphAlignment({
 			value,
 			key: "alignment",
@@ -663,18 +755,33 @@ const parseDocumentOperation = (value, index) => {
 			key: "spacing",
 			path
 		});
+		const indentation = readClearableParagraphIndentation({
+			value,
+			key: "indentation",
+			path
+		});
+		const lineBreakMode = value["lineBreakMode"];
+		if (lineBreakMode !== void 0 && lineBreakMode !== "paragraph" && lineBreakMode !== "inline") return invalidBatch(`${path}.lineBreakMode`, "expected \"paragraph\" or \"inline\" when provided");
+		const text = readString(value, "text", path);
+		if (hardPageBreak !== void 0 && text.length > 0) return invalidBatch(`${path}.text`, "expected empty text with hardPageBreak");
+		if (hardPageBreak !== void 0 && pageBreakBefore !== void 0) return invalidBatch(`${path}.pageBreakBefore`, "cannot combine hardPageBreak with pageBreakBefore");
+		if (hardPageBreak !== void 0 && lineBreakMode !== void 0) return invalidBatch(`${path}.lineBreakMode`, "cannot combine hardPageBreak with lineBreakMode");
 		return {
 			...operationMeta,
 			id,
 			type,
 			blockId,
-			text: readString(value, "text", path),
+			text,
 			...inheritFormatting !== void 0 && { inheritFormatting },
 			...alignment !== void 0 && { alignment },
 			...spacing !== void 0 && { spacing },
+			...indentation !== void 0 && { indentation },
+			...lineBreakMode !== void 0 && { lineBreakMode },
 			...listLevel !== void 0 && { listLevel },
+			...numbering !== void 0 && { numbering },
 			...moveId !== void 0 && { moveId },
 			...pageBreakBefore !== void 0 && { pageBreakBefore },
+			...hardPageBreak !== void 0 && { hardPageBreak },
 			...styleId !== void 0 && { styleId },
 			...comment !== void 0 && { comment }
 		};
@@ -1103,4 +1210,4 @@ const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", a
 	};
 };
 //#endregion
-export { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };
+export { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PAGE_BREAK_CLEAR_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };

package/dist/docx/blockContentParser.js

@@ -7,7 +7,7 @@ import { enrichParagraphTextBoxes } from "./paragraphTextBoxEnrichment.js";
 import { parseSdtProperties } from "./sdtProperties.js";
 import { parseTable } from "./tableParser.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
-import { findChild, getChildElements, getLocalName, mergeXmlnsDeclarations } from "./xmlParser.js";
+import { findChild, getChildElements, getLocalName, mergeXmlnsDeclarations, selectAlternateContentBranch } from "./xmlParser.js";
 //#region src/docx/blockContentParser.ts
 const computeListMarker = (paragraph, { numbering, listCounters, abstractCounters, restartedNumIds, previousList }) => {
 	const listRendering = paragraph.listRendering;
@@ -80,6 +80,13 @@ const computeListMarker = (paragraph, { numbering, listCounters, abstractCounter
 	}
 	listRendering.marker = computedMarker;
 };
+const withContainerXmlns = (state, element) => ({
+	...state,
+	options: {
+		...state.options,
+		rootXmlns: mergeXmlnsDeclarations(state.options?.rootXmlns ?? {}, element)
+	}
+});
 const parseBlockContent = (parent, styles, theme, numbering, rels, media, options) => parseBlockContentWithState(parent, styles, theme, numbering, rels, media, {
 	listCounters: /* @__PURE__ */ new Map(),
 	abstractCounters: /* @__PURE__ */ new Map(),
@@ -132,12 +139,17 @@ const parseBlockContentWithState = (parent, styles, theme, numbering, rels, medi
 			const blockSdt = {
 				type: "blockSdt",
 				properties,
-				content: sdtContent ? parseBlockContentWithState(sdtContent, styles, theme, numbering, rels, media, state) : []
+				content: sdtContent ? parseBlockContentWithState(sdtContent, styles, theme, numbering, rels, media, withContainerXmlns(withContainerXmlns(state, child), sdtContent)) : []
 			};
 			if (prependBookmarkMarkersToFirstParagraphInBlocks(blockSdt.content, pendingBookmarkMarkers)) pendingBookmarkMarkers.length = 0;
 			content.push(blockSdt);
 			continue;
 		}
+		if (localName === "AlternateContent") {
+			const selectedBranch = selectAlternateContentBranch(child);
+			if (selectedBranch) content.push(...parseBlockContentWithState(selectedBranch, styles, theme, numbering, rels, media, withContainerXmlns(withContainerXmlns(state, child), selectedBranch)));
+			continue;
+		}
 		if (localName === "bookmarkStart" || localName === "bookmarkEnd") {
 			const marker = parseBookmarkMarker(child, localName);
 			if (!appendBookmarkMarkerToLastParagraphInBlocks(content, marker)) pendingBookmarkMarkers.push(marker);

package/dist/docx/diagramPreview.d.ts

@@ -0,0 +1,7 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/diagramPreview.d.ts
+/** Create a deliberately simple, bounded preview; it is never an editable diagram projection. */
+declare const parseDiagramPreview: (drawing: XmlElement, rels: document_d_exports.RelationshipMap | undefined, media: Map<string, document_d_exports.MediaFile> | undefined) => document_d_exports.Image | null;
+//#endregion
+export { parseDiagramPreview };

package/dist/docx/diagramPreview.js

@@ -0,0 +1,191 @@
+import { resolveRelativePath } from "./relsParser.js";
+import { findChildByNamespaceUri, getAttribute, getLocalName, parseNumericAttribute, parseXmlDocument } from "./xmlParser.js";
+//#region src/docx/diagramPreview.ts
+const MAX_PREVIEW_SHAPES = 128;
+const MAX_PREVIEW_PIXELS = 144e4;
+const MAX_PREVIEW_PAINT_PIXELS = MAX_PREVIEW_PIXELS * 4;
+const DRAWINGML_NAMESPACE_URIS = /* @__PURE__ */ new Set(["http://schemas.openxmlformats.org/drawingml/2006/main", "http://purl.oclc.org/ooxml/drawingml/main"]);
+const DIAGRAM_NAMESPACE_URIS = /* @__PURE__ */ new Set(["http://schemas.openxmlformats.org/drawingml/2006/diagram", "http://purl.oclc.org/ooxml/drawingml/diagram"]);
+const DIAGRAM_DRAWING_NAMESPACE_URIS = /* @__PURE__ */ new Set(["http://schemas.microsoft.com/office/drawing/2008/diagram"]);
+const WORD_DRAWING_NAMESPACE_URIS = /* @__PURE__ */ new Set(["http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing", "http://purl.oclc.org/ooxml/drawingml/wordprocessingDrawing"]);
+const crc32 = (bytes) => {
+	let crc = 4294967295;
+	for (const byte of bytes) {
+		crc ^= byte;
+		for (let bit = 0; bit < 8; bit += 1) crc = crc >>> 1 ^ (crc & 1 ? 3988292384 : 0);
+	}
+	return (crc ^ 4294967295) >>> 0;
+};
+const adler32 = (bytes) => {
+	let a = 1;
+	let b = 0;
+	for (const byte of bytes) {
+		a = (a + byte) % 65521;
+		b = (b + a) % 65521;
+	}
+	return b << 16 | a;
+};
+const pngChunk = (type, data) => {
+	const name = new TextEncoder().encode(type);
+	const output = new Uint8Array(12 + data.length);
+	const view = new DataView(output.buffer);
+	view.setUint32(0, data.length);
+	output.set(name, 4);
+	output.set(data, 8);
+	view.setUint32(8 + data.length, crc32(output.subarray(4, 8 + data.length)));
+	return output;
+};
+const previewPng = (width, height, shapes) => {
+	const scale = Math.min(1, Math.sqrt(MAX_PREVIEW_PIXELS / (width * height)));
+	const w = Math.max(1, Math.round(width * scale));
+	const h = Math.max(1, Math.round(height * scale));
+	const pixels = new Uint8Array((w * 4 + 1) * h);
+	for (let y = 0; y < h; y += 1) {
+		const row = y * (w * 4 + 1);
+		pixels[row] = 0;
+		for (let x = 0; x < w; x += 1) {
+			const index = row + 1 + x * 4;
+			pixels[index] = 238;
+			pixels[index + 1] = 242;
+			pixels[index + 2] = 247;
+			pixels[index + 3] = 255;
+		}
+	}
+	let paintedPixels = 0;
+	for (const shape of shapes) {
+		const sx = Math.max(0, Math.round(shape.x / width * w));
+		const sy = Math.max(0, Math.round(shape.y / height * h));
+		const ex = Math.min(w, Math.round((shape.x + shape.width) / width * w));
+		const ey = Math.min(h, Math.round((shape.y + shape.height) / height * h));
+		const red = Number.parseInt(shape.color.slice(0, 2), 16) || 232;
+		const green = Number.parseInt(shape.color.slice(2, 4), 16) || 238;
+		const blue = Number.parseInt(shape.color.slice(4, 6), 16) || 247;
+		const shapePixels = Math.max(0, ex - sx) * Math.max(0, ey - sy);
+		if (paintedPixels + shapePixels > MAX_PREVIEW_PAINT_PIXELS) break;
+		paintedPixels += shapePixels;
+		for (let y = sy; y < ey; y += 1) {
+			const row = y * (w * 4 + 1);
+			for (let x = sx; x < ex; x += 1) {
+				const index = row + 1 + x * 4;
+				pixels[index] = red;
+				pixels[index + 1] = green;
+				pixels[index + 2] = blue;
+			}
+		}
+	}
+	const compressed = new Uint8Array(2 + pixels.length + Math.ceil(pixels.length / 65535) * 5 + 4);
+	compressed[0] = 120;
+	compressed[1] = 1;
+	let cursor = 2;
+	for (let offset = 0; offset < pixels.length;) {
+		const length = Math.min(65535, pixels.length - offset);
+		compressed[cursor++] = offset + length === pixels.length ? 1 : 0;
+		compressed[cursor++] = length & 255;
+		compressed[cursor++] = length >>> 8;
+		compressed[cursor++] = ~length & 255;
+		compressed[cursor++] = ~length >>> 8 & 255;
+		compressed.set(pixels.subarray(offset, offset + length), cursor);
+		cursor += length;
+		offset += length;
+	}
+	const output = new Uint8Array(cursor + 4);
+	output.set(compressed.subarray(0, cursor));
+	new DataView(output.buffer).setUint32(cursor, adler32(pixels));
+	const signature = new Uint8Array([
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	]);
+	const header = /* @__PURE__ */ new Uint8Array(13);
+	new DataView(header.buffer).setUint32(0, w);
+	new DataView(header.buffer).setUint32(4, h);
+	header[8] = 8;
+	header[9] = 6;
+	const chunks = [
+		signature,
+		pngChunk("IHDR", header),
+		pngChunk("IDAT", output),
+		pngChunk("IEND", /* @__PURE__ */ new Uint8Array())
+	];
+	const png = new Uint8Array(chunks.reduce((total, chunk) => total + chunk.length, 0));
+	let position = 0;
+	for (const chunk of chunks) {
+		png.set(chunk, position);
+		position += chunk.length;
+	}
+	return png;
+};
+const extent = (drawing) => {
+	const value = findChildByNamespaceUri(findChildByNamespaceUri(drawing, WORD_DRAWING_NAMESPACE_URIS, "inline") ?? findChildByNamespaceUri(drawing, WORD_DRAWING_NAMESPACE_URIS, "anchor"), WORD_DRAWING_NAMESPACE_URIS, "extent");
+	return {
+		width: parseNumericAttribute(value, null, "cx") ?? 0,
+		height: parseNumericAttribute(value, null, "cy") ?? 0
+	};
+};
+const cachedDiagramShapes = (rels, media) => {
+	const matches = [...rels.values()].filter((relationship) => relationship.type === "http://schemas.microsoft.com/office/2007/relationships/diagramDrawing");
+	if (matches.length !== 1 || !matches[0]?.target) return [];
+	const path = resolveRelativePath("word/document.xml", matches[0].target);
+	const file = media.get(path);
+	if (!file?.data) return [];
+	const root = parseXmlDocument(new TextDecoder().decode(file.data));
+	if (!root) return [];
+	const shapes = [];
+	for (const shape of descendantsByNamespace(root, DIAGRAM_DRAWING_NAMESPACE_URIS, "sp").slice(0, MAX_PREVIEW_SHAPES)) {
+		const properties = findChildByNamespaceUri(shape, DIAGRAM_DRAWING_NAMESPACE_URIS, "spPr");
+		const transform = findChildByNamespaceUri(properties, DRAWINGML_NAMESPACE_URIS, "xfrm");
+		const offset = findChildByNamespaceUri(transform, DRAWINGML_NAMESPACE_URIS, "off");
+		const size = findChildByNamespaceUri(transform, DRAWINGML_NAMESPACE_URIS, "ext");
+		const width = parseNumericAttribute(size, null, "cx") ?? 0;
+		const height = parseNumericAttribute(size, null, "cy") ?? 0;
+		if (width <= 0 || height <= 0) continue;
+		const color = findChildByNamespaceUri(findChildByNamespaceUri(properties, DRAWINGML_NAMESPACE_URIS, "solidFill"), DRAWINGML_NAMESPACE_URIS, "srgbClr");
+		shapes.push({
+			x: parseNumericAttribute(offset, null, "x") ?? 0,
+			y: parseNumericAttribute(offset, null, "y") ?? 0,
+			width,
+			height,
+			color: getAttribute(color, null, "val") ?? "E8EEF7"
+		});
+	}
+	return shapes;
+};
+const descendantsByNamespace = (root, namespaceUris, localName) => {
+	const result = [];
+	const visit = (element) => {
+		if (element.namespaceUri && namespaceUris.has(element.namespaceUri) && getLocalName(element.name ?? "") === localName) result.push(element);
+		for (const child of element.elements ?? []) if (child.type === "element") visit(child);
+	};
+	visit(root);
+	return result;
+};
+/** Create a deliberately simple, bounded preview; it is never an editable diagram projection. */
+const parseDiagramPreview = (drawing, rels, media) => {
+	if (!rels || !media) return null;
+	const graphicData = descendantsByNamespace(drawing, DRAWINGML_NAMESPACE_URIS, "graphicData").at(0);
+	if (!graphicData || !DIAGRAM_NAMESPACE_URIS.has(getAttribute(graphicData, null, "uri") ?? "")) return null;
+	const { width, height } = extent(drawing);
+	if (width <= 0 || height <= 0) return null;
+	const png = previewPng(width, height, cachedDiagramShapes(rels, media));
+	let binary = "";
+	for (let offset = 0; offset < png.length; offset += 32768) binary += String.fromCodePoint(...png.subarray(offset, offset + 32768));
+	return {
+		type: "image",
+		rId: "",
+		src: `data:image/png;base64,${btoa(binary)}`,
+		mimeType: "image/png",
+		filename: "smartart-preview.png",
+		size: {
+			width,
+			height
+		},
+		wrap: { type: "inline" }
+	};
+};
+//#endregion
+export { parseDiagramPreview };

package/dist/docx/drawingIdNormalization.js

@@ -1,6 +1,27 @@
+import { isNewDataUrlDrawing } from "./newImage.js";
 import { visitDocxParagraphs, visitParagraphRuns } from "./paragraphTraversal.js";
+import { toTransitionalNamespaceUri } from "./transitionalSpelling.js";
+import { captureVerbatimXml } from "./verbatimCapture.js";
+import { NAMESPACES, OOXML_NAMESPACE_SCOPE, getLocalName, getNamespaceUri, parseXml } from "./xmlParser.js";
+import { panic } from "better-result";
 //#region src/docx/drawingIdNormalization.ts
 const GENERATED_DRAWING_ID_START = 1e5;
+const isDetachedRawDrawing = (drawing) => drawing?.rawXml !== void 0 && isNewDataUrlDrawing(drawing);
+const reassignRawDrawingId = ({ xml, id }) => {
+	const root = parseXml(xml, OOXML_NAMESPACE_SCOPE);
+	let foundDocPr = false;
+	const visit = (element) => {
+		if (toTransitionalNamespaceUri(getNamespaceUri(element) ?? "") === NAMESPACES.wp && getLocalName(element.name) === "docPr" || toTransitionalNamespaceUri(getNamespaceUri(element) ?? "") === NAMESPACES.pic && getLocalName(element.name) === "cNvPr") {
+			for (const name of Object.keys(element.attributes ?? {})) if (getLocalName(name) === "id" && element.attributes) {
+				element.attributes[name] = id;
+				if (toTransitionalNamespaceUri(getNamespaceUri(element) ?? "") === NAMESPACES.wp && getLocalName(element.name) === "docPr") foundDocPr = true;
+			}
+		}
+		for (const child of element.elements ?? []) visit(child);
+	};
+	visit(root);
+	return foundDocPr ? (root.elements ?? []).map(captureVerbatimXml).join("") : null;
+};
 const needsGeneratedId = ({ id }) => id === void 0 || id === "" || id === "0";
 const normalizeDrawingIds = (surfaces) => {
 	const entries = [];
@@ -16,12 +37,13 @@ const normalizeDrawingIds = (surfaces) => {
 				}
 				if (content.type === "drawing") entries.push({
 					drawing: content.image,
-					generateWhenMissing: content.rawXml === void 0
+					generateWhenMissing: content.rawXml === void 0,
+					...content.rawXml !== void 0 ? { rawDrawing: content } : {}
 				});
 			}
 		});
 	});
-	const usedIds = new Set(entries.flatMap(({ drawing }) => needsGeneratedId(drawing) ? [] : [drawing.id]));
+	const usedIds = new Set(entries.flatMap(({ drawing, rawDrawing }) => needsGeneratedId(drawing) || isDetachedRawDrawing(rawDrawing) ? [] : [drawing.id]));
 	let nextId = GENERATED_DRAWING_ID_START;
 	for (const { drawing, generateWhenMissing } of entries) {
 		if (!generateWhenMissing || !needsGeneratedId(drawing)) continue;
@@ -30,6 +52,25 @@ const normalizeDrawingIds = (surfaces) => {
 		usedIds.add(drawing.id);
 		nextId += 1;
 	}
+	for (const { drawing, rawDrawing } of entries) {
+		if (!isDetachedRawDrawing(rawDrawing)) continue;
+		if (!needsGeneratedId(drawing) && !usedIds.has(drawing.id)) {
+			usedIds.add(drawing.id);
+			continue;
+		}
+		while (usedIds.has(String(nextId))) nextId += 1;
+		const sourceXml = rawDrawing.rawXml;
+		if (sourceXml === void 0) panic("Detached raw drawing must retain its XML.");
+		const rawXml = reassignRawDrawingId({
+			xml: sourceXml,
+			id: String(nextId)
+		});
+		if (rawXml === null) panic("Detached raw drawing must contain wp:docPr.");
+		drawing.id = String(nextId);
+		rawDrawing.rawXml = rawXml;
+		usedIds.add(drawing.id);
+		nextId += 1;
+	}
 };
 //#endregion
 export { normalizeDrawingIds };

package/dist/docx/drawingRelationships.d.ts

@@ -0,0 +1,10 @@
+//#region src/docx/drawingRelationships.d.ts
+type RebindDrawingImageRelationshipOptions = {
+  xml: string;
+  previousId: string;
+  nextId: string;
+};
+/** Only a single embedded image can travel without importing other package resources. */
+declare const rebindDrawingImageRelationship: ({ xml, previousId, nextId }: RebindDrawingImageRelationshipOptions) => string | null;
+//#endregion
+export { rebindDrawingImageRelationship };

package/dist/docx/drawingRelationships.js

@@ -0,0 +1,28 @@
+import { captureVerbatimXml } from "./verbatimCapture.js";
+import { OFFICE_RELATIONSHIP_NAMESPACE_URIS, OOXML_NAMESPACE_SCOPE, findAttributeByNamespaceUri, getLocalName, getNamespaceUri, parseXml } from "./xmlParser.js";
+//#region src/docx/drawingRelationships.ts
+/** Only a single embedded image can travel without importing other package resources. */
+const rebindDrawingImageRelationship = ({ xml, previousId, nextId }) => {
+	const root = parseXml(xml, OOXML_NAMESPACE_SCOPE);
+	let embeddedCount = 0;
+	let unsupported = false;
+	const visit = (element) => {
+		for (const name of Object.keys(element.attributes ?? {})) {
+			const localName = getLocalName(name);
+			const attribute = findAttributeByNamespaceUri(element, OFFICE_RELATIONSHIP_NAMESPACE_URIS, localName);
+			if (!attribute || attribute.name !== name) continue;
+			if (!(localName === "embed" || localName === "id" && getLocalName(element.name) === "imagedata" && getNamespaceUri(element) === "urn:schemas-microsoft-com:vml") || attribute.value !== previousId) {
+				unsupported = true;
+				continue;
+			}
+			embeddedCount++;
+			if (element.attributes) element.attributes[name] = nextId;
+		}
+		for (const child of element.elements ?? []) visit(child);
+	};
+	visit(root);
+	if (unsupported || embeddedCount !== 1) return null;
+	return (root.elements ?? []).map(captureVerbatimXml).join("");
+};
+//#endregion
+export { rebindDrawingImageRelationship };

package/dist/docx/fieldParser.js

@@ -209,7 +209,7 @@ function resetComplexFieldContext(ctx) {
 function finalizeComplexField(ctx) {
 	return {
 		type: "complexField",
-		instruction: ctx.instruction.trim(),
+		instruction: ctx.instruction,
 		fieldType: parseFieldType(ctx.instruction),
 		fieldCode: ctx.codeRuns,
 		fieldResult: ctx.resultRuns,