@stll/folio-core 0.40.0 → 0.41.0

package/dist/docx/footnoteParser.js

@@ -1,9 +1,9 @@
+import { blockPlainText } from "./blockPlainText.js";
 import { parseEndnoteProperties, parseFootnoteProperties } from "./notePropertiesParser.js";
-import { getParagraphText, parseParagraph } from "./paragraphParser.js";
+import { parseParagraph } from "./paragraphParser.js";
 import { parseSdtProperties } from "./sdtProperties.js";
 import { parseTable } from "./tableParser.js";
 import { findChild, findChildren, getAttributes, getChildElements, getLocalName, parseXml } from "./xmlParser.js";
-import { panic } from "better-result";
 //#region src/docx/footnoteParser.ts
 /**
 * Parse note type attribute
@@ -173,32 +173,13 @@ function createEndnoteMap(byId, endnotes) {
 * Uses the accepted tracked-change view and recurses through every note block.
 */
 function getFootnoteText(footnote) {
-	return collectNoteBlockTexts(footnote.content).join("\n");
+	return blockPlainText(footnote.content);
 }
 /**
 * Get plain text content of an endnote.
 */
 function getEndnoteText(endnote) {
-	return collectNoteBlockTexts(endnote.content).join("\n");
-}
-function collectNoteBlockTexts(blocks) {
-	const texts = [];
-	for (const block of blocks) switch (block.type) {
-		case "paragraph":
-			texts.push(getParagraphText(block));
-			break;
-		case "table":
-			for (const row of block.rows) {
-				if (row.formatting?.hidden === true) continue;
-				texts.push(row.cells.map((cell) => collectNoteBlockTexts(cell.content).join("\n")).join("	"));
-			}
-			break;
-		case "blockSdt":
-			texts.push(...collectNoteBlockTexts(block.content));
-			break;
-		default: panic(`Unsupported note block in plain-text extraction: ${JSON.stringify(block)}`);
-	}
-	return texts;
+	return blockPlainText(endnote.content);
 }
 /**
 * Check if a footnote is a separator (not regular content)

package/dist/docx/graphicFrameLocks.d.ts

@@ -0,0 +1,22 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/graphicFrameLocks.d.ts
+/** Every modeled lock, in schema order: the total map above keeps it exhaustive. */
+declare const GRAPHIC_FRAME_LOCK_KEYS: ("noGrp" | "noDrilldown" | "noSelect" | "noChangeAspect" | "noMove" | "noResize")[];
+/**
+ * Read the locks off a `wp:inline` or `wp:anchor` element.
+ *
+ * Returns undefined when the element is absent or carries no recognized
+ * attribute: an authored `<a:graphicFrameLocks/>` with nothing on it means the
+ * same as no element at all, so both stay "spec defaults" on the model.
+ */
+declare const parseGraphicFrameLocks: (parent: XmlElement) => document_d_exports.ImageFrameLocks | undefined;
+/**
+ * Emit the whole `wp:cNvGraphicFramePr` element for regenerated DrawingML.
+ *
+ * Absent locks mean no authored frame was ever parsed (a Folio-created
+ * picture), which keeps the historical `noChangeAspect="1"`.
+ */
+declare const serializeGraphicFrameLocks: (locks: document_d_exports.ImageFrameLocks | undefined) => string;
+//#endregion
+export { GRAPHIC_FRAME_LOCK_KEYS, parseGraphicFrameLocks, serializeGraphicFrameLocks };

package/dist/docx/graphicFrameLocks.js

@@ -0,0 +1,55 @@
+import { findChild, getAttribute, parseOnOffValue } from "./xmlParser.js";
+//#region src/docx/graphicFrameLocks.ts
+/**
+* Model key → OOXML attribute. Insertion order is the schema's attribute
+* order, which is also the order we emit.
+*/
+const GRAPHIC_FRAME_LOCK_ATTRIBUTES = {
+	noGrp: "noGrp",
+	noDrilldown: "noDrilldown",
+	noSelect: "noSelect",
+	noChangeAspect: "noChangeAspect",
+	noMove: "noMove",
+	noResize: "noResize"
+};
+const isGraphicFrameLockKey = (key) => key in GRAPHIC_FRAME_LOCK_ATTRIBUTES;
+/** Every modeled lock, in schema order: the total map above keeps it exhaustive. */
+const GRAPHIC_FRAME_LOCK_KEYS = Object.keys(GRAPHIC_FRAME_LOCK_ATTRIBUTES).filter(isGraphicFrameLockKey);
+const DRAWINGML_NAMESPACE = "xmlns:a=\"http://schemas.openxmlformats.org/drawingml/2006/main\"";
+/**
+* Read the locks off a `wp:inline` or `wp:anchor` element.
+*
+* Returns undefined when the element is absent or carries no recognized
+* attribute: an authored `<a:graphicFrameLocks/>` with nothing on it means the
+* same as no element at all, so both stay "spec defaults" on the model.
+*/
+const parseGraphicFrameLocks = (parent) => {
+	const locksEl = findChild(findChild(parent, "wp", "cNvGraphicFramePr"), "a", "graphicFrameLocks");
+	if (!locksEl) return;
+	const locks = {};
+	let present = false;
+	for (const key of GRAPHIC_FRAME_LOCK_KEYS) {
+		const value = parseOnOffValue(getAttribute(locksEl, null, GRAPHIC_FRAME_LOCK_ATTRIBUTES[key]));
+		if (value !== void 0) {
+			locks[key] = value;
+			present = true;
+		}
+	}
+	return present ? locks : void 0;
+};
+/**
+* Emit the whole `wp:cNvGraphicFramePr` element for regenerated DrawingML.
+*
+* Absent locks mean no authored frame was ever parsed (a Folio-created
+* picture), which keeps the historical `noChangeAspect="1"`.
+*/
+const serializeGraphicFrameLocks = (locks) => {
+	const attrs = locks ? GRAPHIC_FRAME_LOCK_KEYS.flatMap((key) => {
+		const value = locks[key];
+		return value === void 0 ? [] : [`${GRAPHIC_FRAME_LOCK_ATTRIBUTES[key]}="${value ? "1" : "0"}"`];
+	}) : ["noChangeAspect=\"1\""];
+	const attrList = attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
+	return `<wp:cNvGraphicFramePr><a:graphicFrameLocks ${DRAWINGML_NAMESPACE}${attrList}/></wp:cNvGraphicFramePr>`;
+};
+//#endregion
+export { GRAPHIC_FRAME_LOCK_KEYS, parseGraphicFrameLocks, serializeGraphicFrameLocks };

package/dist/docx/groupDrawingParser.d.ts

@@ -1,7 +1,13 @@
 import { document_d_exports } from "../types/document.js";
 import { XmlElement } from "./xmlParser.js";
 //#region src/docx/groupDrawingParser.d.ts
+/**
+ * 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.
+ */
+declare const isGroupDrawing: (drawing: XmlElement) => boolean;
 /** Parse a WordprocessingGroup drawing into a safe SVG-backed image preview. */
 declare const parseGroupDrawing: (drawing: XmlElement, rels?: document_d_exports.RelationshipMap, media?: Map<string, document_d_exports.MediaFile>) => document_d_exports.Image | null;
 //#endregion
-export { parseGroupDrawing };
+export { isGroupDrawing, parseGroupDrawing };

package/dist/docx/groupDrawingParser.js

@@ -165,9 +165,18 @@ const createSvg = (group, width, height, rels, media) => {
 	const viewBox = groupViewBox(group, width, height);
 	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 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.
+*/
+const isGroupDrawing = (drawing) => groupElement(drawing) !== null;
 /** Parse a WordprocessingGroup drawing into a safe SVG-backed image preview. */
 const parseGroupDrawing = (drawing, rels, media) => {
-	const group = findChildByLocalName(findAllDeep(drawing, "a", "graphicData").at(0) ?? null, "wgp");
+	const group = groupElement(drawing);
 	if (!group) return null;
 	const image = parseImage(drawing, void 0, void 0);
 	if (!image || image.size.width <= 0 || image.size.height <= 0) return null;
@@ -179,4 +188,4 @@ const parseGroupDrawing = (drawing, rels, media) => {
 	return image;
 };
 //#endregion
-export { parseGroupDrawing };
+export { isGroupDrawing, parseGroupDrawing };

package/dist/docx/headerFooterParser.d.ts

@@ -77,7 +77,11 @@ declare function createEmptyHeaderFooterMap(): HeaderFooterMap;
  */
 declare function buildHeaderFooterMap(references: (document_d_exports.HeaderReference | document_d_exports.FooterReference)[], xmlContents: Map<string, string>, isHeader: boolean, styles?: StyleMap | null, theme?: document_d_exports.Theme | null, numbering?: NumberingMap | null, rels?: document_d_exports.RelationshipMap | null, media?: Map<string, document_d_exports.MediaFile> | null): HeaderFooterMap;
 /**
- * Get plain text content of a header/footer
+ * Get plain text content of a header/footer.
+ *
+ * Shares one walk with the note stories: this used to read only text runs, so a
+ * header's fields, hyperlinks, tabs and breaks were silently absent from its
+ * text while the same paragraph in a footnote read in full.
  */
 declare function getHeaderFooterText(hf: document_d_exports.HeaderFooter): string;
 /**

package/dist/docx/headerFooterParser.js

@@ -1,4 +1,5 @@
 import { parseBlockContent } from "./blockContentParser.js";
+import { blockPlainText } from "./blockPlainText.js";
 import { parseFooterReference, parseFooterReferences, parseHeaderReference, parseHeaderReferences } from "./headerFooterRefParser.js";
 import { assignHeaderFooterVerbatimXml } from "./headerFooterVerbatim.js";
 import { cloneParagraphWithPropertySource } from "./paragraphPropertySource.js";
@@ -139,29 +140,14 @@ function buildHeaderFooterMap(references, xmlContents, isHeader, styles = null,
 	return createHeaderFooterMap(byId);
 }
 /**
-* Get plain text content of a header/footer
+* Get plain text content of a header/footer.
+*
+* Shares one walk with the note stories: this used to read only text runs, so a
+* header's fields, hyperlinks, tabs and breaks were silently absent from its
+* text while the same paragraph in a footnote read in full.
 */
 function getHeaderFooterText(hf) {
-	const texts = [];
-	for (const item of hf.content) if (item.type === "paragraph") {
-		const paraTexts = [];
-		for (const content of item.content) if (content.type === "run") {
-			for (const runContent of content.content) if (runContent.type === "text") paraTexts.push(runContent.text);
-		}
-		texts.push(paraTexts.join(""));
-	} else if (item.type === "blockSdt") texts.push(getHeaderFooterText({
-		type: hf.type,
-		hdrFtrType: hf.hdrFtrType,
-		content: item.content
-	}));
-	else for (const row of item.rows) for (const cell of row.cells) for (const cellContent of cell.content) if (cellContent.type === "paragraph") {
-		const paraTexts = [];
-		for (const content of cellContent.content) if (content.type === "run") {
-			for (const runContent of content.content) if (runContent.type === "text") paraTexts.push(runContent.text);
-		}
-		texts.push(paraTexts.join(""));
-	}
-	return texts.join("\n");
+	return blockPlainText(hf.content);
 }
 /**
 * Check if header/footer is empty (no content)

package/dist/docx/imageParser.js

@@ -2,6 +2,7 @@ import { sanitizeImageSrc } from "../utils/sanitizeImageSrc.js";
 import { emuToPixels } from "../utils/units.js";
 import { sanitizeExternalUrl } from "../utils/urlSecurity.js";
 import { WRAP_ELEMENT_NAMES, parsePositionH, parsePositionV, parseWrapElement } from "./drawingUtils.js";
+import { parseGraphicFrameLocks } from "./graphicFrameLocks.js";
 import { resolveTarget } from "./relsParser.js";
 import { isTextBoxDrawing } from "./textBoxParser.js";
 import { findByFullName, findChild, getAttribute, getChildElements, parseNumericAttribute, parseOnOffValue } from "./xmlParser.js";
@@ -299,6 +300,7 @@ function parseInline(inlineEl, rels, media) {
 	const size = parseExtent(findByFullName(inlineEl, "wp:extent"));
 	const padding = parseEffectExtent(findByFullName(inlineEl, "wp:effectExtent"));
 	const props = parseDocProps(findByFullName(inlineEl, "wp:docPr"));
+	const frameLocks = parseGraphicFrameLocks(inlineEl);
 	const blipFill = findBlipFillElement(inlineEl);
 	const blip = blipFill ? findByFullName(blipFill, "a:blip") : null;
 	const rId = extractBlipRId(blip);
@@ -334,6 +336,7 @@ function parseInline(inlineEl, rels, media) {
 	if (transform) image.transform = transform;
 	if (crop) image.crop = crop;
 	if (opacity !== void 0) image.opacity = opacity;
+	if (frameLocks) image.frameLocks = frameLocks;
 	if (props.hlinkRId && rels) {
 		const safeHref = sanitizeExternalUrl(resolveTarget(rels, props.hlinkRId));
 		if (safeHref) {
@@ -355,6 +358,7 @@ function parseAnchor(anchorEl, rels, media) {
 	const size = parseExtent(findByFullName(anchorEl, "wp:extent"));
 	const padding = parseEffectExtent(findByFullName(anchorEl, "wp:effectExtent"));
 	const props = parseDocProps(findByFullName(anchorEl, "wp:docPr"));
+	const frameLocks = parseGraphicFrameLocks(anchorEl);
 	const behindDoc = parseOnOffValue(getAttribute(anchorEl, null, "behindDoc")) === true;
 	const layoutInCell = parseOnOffAttr(anchorEl, "layoutInCell");
 	const allowOverlap = parseOnOffAttr(anchorEl, "allowOverlap");
@@ -405,6 +409,7 @@ function parseAnchor(anchorEl, rels, media) {
 	if (transform) image.transform = transform;
 	if (crop) image.crop = crop;
 	if (opacity !== void 0) image.opacity = opacity;
+	if (frameLocks) image.frameLocks = frameLocks;
 	if (layoutInCell !== void 0) image.layoutInCell = layoutInCell;
 	if (allowOverlap !== void 0) image.allowOverlap = allowOverlap;
 	if (props.hlinkRId && rels) {

package/dist/docx/imageRawXml.d.ts

@@ -1,8 +1,40 @@
 import { document_d_exports } from "../types/document.js";
 //#region src/docx/imageRawXml.d.ts
+/** An unclassified drawing is an ordinary editable projection; a classified one is not. */
+declare const allowsDirectDrawingEdit: (mode: document_d_exports.DrawingRawXmlMode | undefined) => boolean;
+/** Narrow an unvalidated value (a ProseMirror attr) to a raw-XML mode. */
+declare const isDrawingRawXmlMode: (value: unknown) => value is document_d_exports.DrawingRawXmlMode;
+/**
+ * Stands in for a preview's fingerprint once the editor has changed the image
+ * it renders. `canonicalJson` always produces an object literal, so this can
+ * never collide with a real fingerprint and the drawing can never replay.
+ */
+declare const EDITED_PREVIEW_FINGERPRINT = "editedPreview";
 /** Fingerprints modeled image fields which make raw DrawingML stale when edited. */
 declare const imageRawXmlFingerprint: (image: document_d_exports.Image) => string;
 /** Editable raw drawing XML can replay only while its modeled projection is unchanged. */
 declare const canReplayEditableImageRawXml: (drawing: document_d_exports.DrawingContent) => boolean;
+/**
+ * What a drawing costs the document when Folio writes it back.
+ *
+ * `native` and `replayable` both survive a save intact, so neither restricts
+ * editing; only `opaque` loses content.
+ */
+declare const DRAWING_SAFETY_CLASSES: {
+  /** No raw XML: Folio owns the whole drawing and regenerates it from the model. */
+  readonly NATIVE: "native";
+  /** Raw XML the serializer replays verbatim, so every unmodeled attribute survives. */
+  readonly REPLAYABLE: "replayable";
+  /** Raw XML the serializer can neither replay nor regenerate without losing the media. */
+  readonly OPAQUE: "opaque";
+};
+type DrawingSafetyClass = (typeof DRAWING_SAFETY_CLASSES)[keyof typeof DRAWING_SAFETY_CLASSES];
+/**
+ * Classify a drawing by what the run serializer will do with it.
+ *
+ * Shares {@link canReplayEditableImageRawXml} with the serializer so a
+ * compatibility probe and a save can never disagree about the same drawing.
+ */
+declare const classifyDrawingSafety: (drawing: document_d_exports.DrawingContent) => DrawingSafetyClass;
 //#endregion
-export { canReplayEditableImageRawXml, imageRawXmlFingerprint };
+export { DRAWING_SAFETY_CLASSES, DrawingSafetyClass, EDITED_PREVIEW_FINGERPRINT, allowsDirectDrawingEdit, canReplayEditableImageRawXml, classifyDrawingSafety, imageRawXmlFingerprint, isDrawingRawXmlMode };

package/dist/docx/imageRawXml.js

@@ -1,6 +1,28 @@
 import { canonicalJson } from "../utils/canonicalJson.js";
 import { DRAWING_RAW_XML_MODES } from "@stll/docx-core/model";
 //#region src/docx/imageRawXml.ts
+/**
+* Whether the editor may manipulate the modeled image of a classified drawing.
+*
+* A mode exists precisely because `rawXml` says more than the model does, so
+* both current modes refuse: a resize would either serialize a placeholder
+* (preserve-only) or one child picture in place of a group (preview-only).
+* Totality is the point — a third mode cannot be added without deciding here.
+*/
+const DRAWING_RAW_XML_MODE_ALLOWS_DIRECT_EDIT = {
+	[DRAWING_RAW_XML_MODES.PRESERVE_ONLY]: false,
+	[DRAWING_RAW_XML_MODES.PREVIEW_ONLY]: false
+};
+/** An unclassified drawing is an ordinary editable projection; a classified one is not. */
+const allowsDirectDrawingEdit = (mode) => mode === void 0 || DRAWING_RAW_XML_MODE_ALLOWS_DIRECT_EDIT[mode];
+/** Narrow an unvalidated value (a ProseMirror attr) to a raw-XML mode. */
+const isDrawingRawXmlMode = (value) => typeof value === "string" && value in DRAWING_RAW_XML_MODE_ALLOWS_DIRECT_EDIT;
+/**
+* Stands in for a preview's fingerprint once the editor has changed the image
+* it renders. `canonicalJson` always produces an object literal, so this can
+* never collide with a real fingerprint and the drawing can never replay.
+*/
+const EDITED_PREVIEW_FINGERPRINT = "editedPreview";
 const editableImageProjection = ({ id: _id, rId: _rId, src: _src, mimeType: _mimeType, filename: _filename, ...image }) => image;
 /** Fingerprints modeled image fields which make raw DrawingML stale when edited. */
 const imageRawXmlFingerprint = (image) => canonicalJson(editableImageProjection(image));
@@ -9,5 +31,38 @@ const canReplayEditableImageRawXml = (drawing) => {
 	if (drawing.rawXmlMode === DRAWING_RAW_XML_MODES.PRESERVE_ONLY) return true;
 	return drawing.rawImageFingerprint === void 0 || drawing.rawImageFingerprint === imageRawXmlFingerprint(drawing.image);
 };
+/**
+* What a drawing costs the document when Folio writes it back.
+*
+* `native` and `replayable` both survive a save intact, so neither restricts
+* editing; only `opaque` loses content.
+*/
+const DRAWING_SAFETY_CLASSES = {
+	/** No raw XML: Folio owns the whole drawing and regenerates it from the model. */
+	NATIVE: "native",
+	/** Raw XML the serializer replays verbatim, so every unmodeled attribute survives. */
+	REPLAYABLE: "replayable",
+	/** Raw XML the serializer can neither replay nor regenerate without losing the media. */
+	OPAQUE: "opaque"
+};
+/**
+* Regenerated DrawingML points at `image.rId`, and `serializePicGraphic` falls
+* back to `"rId1"` when that id is empty, which rebinds the picture to whichever
+* relationship happens to be first. A drawing with no relationship id therefore
+* has no faithful regeneration.
+*/
+const canRegenerateDrawing = (drawing) => drawing.image.rId !== "";
+/**
+* Classify a drawing by what the run serializer will do with it.
+*
+* Shares {@link canReplayEditableImageRawXml} with the serializer so a
+* compatibility probe and a save can never disagree about the same drawing.
+*/
+const classifyDrawingSafety = (drawing) => {
+	if (drawing.rawXml === void 0) return DRAWING_SAFETY_CLASSES.NATIVE;
+	if (canReplayEditableImageRawXml(drawing)) return DRAWING_SAFETY_CLASSES.REPLAYABLE;
+	if (drawing.rawXmlMode === DRAWING_RAW_XML_MODES.PREVIEW_ONLY) return DRAWING_SAFETY_CLASSES.OPAQUE;
+	return canRegenerateDrawing(drawing) ? DRAWING_SAFETY_CLASSES.NATIVE : DRAWING_SAFETY_CLASSES.OPAQUE;
+};
 //#endregion
-export { canReplayEditableImageRawXml, imageRawXmlFingerprint };
+export { DRAWING_SAFETY_CLASSES, EDITED_PREVIEW_FINGERPRINT, allowsDirectDrawingEdit, canReplayEditableImageRawXml, classifyDrawingSafety, imageRawXmlFingerprint, isDrawingRawXmlMode };

package/dist/docx/runParser.js

@@ -1,7 +1,7 @@
 import { isValidHexColor } from "../utils/colorResolver.js";
 import { parseHorizontalScalePercent } from "../utils/horizontalScale.js";
 import { parseDiagramPreview } from "./diagramPreview.js";
-import { parseGroupDrawing } from "./groupDrawingParser.js";
+import { isGroupDrawing, parseGroupDrawing } from "./groupDrawingParser.js";
 import { parseImage } from "./imageParser.js";
 import { imageRawXmlFingerprint } from "./imageRawXml.js";
 import { EmphasisMarkSchema, FontHintSchema, FontThemeSchema, HighlightColorSchema, PositionalTabAlignmentSchema, PositionalTabLeaderSchema, PositionalTabRelativeToSchema, ShadingPatternSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum } from "./parserEnums.js";
@@ -11,7 +11,7 @@ import { requiresXmlSpacePreserve } from "./textWhitespace.js";
 import { resolveThemeFontRef } from "./themeParser.js";
 import { parsePropertyChangeInfo } from "./trackedChangeInfo.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
-import { parseVmlImageContent } from "./vmlImageParser.js";
+import { parseVmlImageContent, shouldPreserveRawVmlPict } from "./vmlImageParser.js";
 import { cloneWithXmlnsDeclarations, findAllDeep, findChild, findChildren, getAttribute, getChildElements, getLocalName, getTextContent, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute, selectAlternateContentBranch } from "./xmlParser.js";
 import { DRAWING_RAW_XML_MODES } from "@stll/docx-core/model";
 //#region src/docx/runParser.ts
@@ -470,6 +470,28 @@ function parseInstrText(element) {
 	};
 }
 /**
+* Wrap raw XML the model cannot project at all.
+*
+* `DrawingContent` always carries an `Image`, so preservation-only content
+* gets a placeholder one: the empty `rId` marks it as backed by no
+* relationship, which keeps `classifyDrawingSafety` and the serializer on the
+* replay path instead of regenerating DrawingML from the placeholder.
+*/
+const preserveOnlyDrawing = (rawXml) => ({
+	type: "drawing",
+	image: {
+		type: "image",
+		rId: "",
+		size: {
+			width: 0,
+			height: 0
+		},
+		wrap: { type: "inline" }
+	},
+	rawXml,
+	rawXmlMode: DRAWING_RAW_XML_MODES.PRESERVE_ONLY
+});
+/**
 * Parse drawing content (w:drawing).
 *
 * Dispatches by graphicData payload:
@@ -480,6 +502,8 @@ function parseInstrText(element) {
 *   context that is only available at the block parser level).
 * - `wps:wsp` without text body → generic shape; parsed via
 *   `shapeParser.parseShapeFromDrawing` into a `ShapeContent`.
+* - anything the model cannot project (a group the rasterizer declines,
+*   a diagram, a shape with unmodeled properties) → preservation-only raw XML.
 */
 function parseDrawingContent(element, rels, media) {
 	const groupImage = parseGroupDrawing(element, rels ?? void 0, media ?? void 0);
@@ -487,8 +511,10 @@ function parseDrawingContent(element, rels, media) {
 		type: "drawing",
 		image: groupImage,
 		rawXml: captureVerbatimXml(element),
-		rawImageFingerprint: imageRawXmlFingerprint(groupImage)
+		rawImageFingerprint: imageRawXmlFingerprint(groupImage),
+		rawXmlMode: DRAWING_RAW_XML_MODES.PREVIEW_ONLY
 	};
+	if (isGroupDrawing(element)) return preserveOnlyDrawing(captureVerbatimXml(element));
 	const diagramImage = parseDiagramPreview(element, rels ?? void 0, media ?? void 0);
 	if (diagramImage) return {
 		type: "drawing",
@@ -496,20 +522,7 @@ function parseDrawingContent(element, rels, media) {
 		rawXml: captureVerbatimXml(element),
 		rawXmlMode: DRAWING_RAW_XML_MODES.PRESERVE_ONLY
 	};
-	if (shouldPreserveRawShapeDrawing(element)) return {
-		type: "drawing",
-		image: {
-			type: "image",
-			rId: "",
-			size: {
-				width: 0,
-				height: 0
-			},
-			wrap: { type: "inline" }
-		},
-		rawXml: captureVerbatimXml(element),
-		rawXmlMode: DRAWING_RAW_XML_MODES.PRESERVE_ONLY
-	};
+	if (shouldPreserveRawShapeDrawing(element)) return preserveOnlyDrawing(captureVerbatimXml(element));
 	const shape = parseShapeFromDrawing(element);
 	if (shape) return {
 		type: "shape",
@@ -572,7 +585,11 @@ function parseRunContents(runElement, rels, media, rootXmlns = {}) {
 		}
 		case "pict": {
 			const vmlDrawing = parseVmlImageContent(child, rels, media, rootXmlns);
-			if (vmlDrawing) contents.push(vmlDrawing);
+			if (vmlDrawing) {
+				contents.push(vmlDrawing);
+				break;
+			}
+			if (shouldPreserveRawVmlPict(child)) contents.push(preserveOnlyDrawing(captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns))));
 			break;
 		}
 		case "object": {
@@ -594,13 +611,16 @@ function parseRunContents(runElement, rels, media, rootXmlns = {}) {
 			const alternateChildren = getChildElements(child);
 			const choiceEl = alternateChildren.find((el) => getLocalName(el.name) === "Choice");
 			const fallbackEl = alternateChildren.find((el) => getLocalName(el.name) === "Fallback");
+			const contentsBeforeAlternate = contents.length;
 			const choiceTextBoxDrawing = choiceEl ? getChildElements(choiceEl).find((element) => getLocalName(element.name) === "drawing" && isTextBoxDrawing(element)) : void 0;
 			const groupedChoiceDrawing = choiceEl ? getChildElements(choiceEl).find((element) => getLocalName(element.name) === "drawing" && findAllDeep(element, "wpg", "wgp").length > 0) : void 0;
 			if (groupedChoiceDrawing) {
 				const groupedDrawing = parseDrawingContent(groupedChoiceDrawing, rels, media);
-				if (groupedDrawing?.type === "drawing" && groupedDrawing.image.src) {
-					groupedDrawing.rawXml = captureVerbatimXml(child);
-					contents.push(groupedDrawing);
+				if (groupedDrawing?.type === "drawing" && groupedDrawing.rawXmlMode === DRAWING_RAW_XML_MODES.PREVIEW_ONLY && groupedDrawing.image.src) {
+					contents.push({
+						...groupedDrawing,
+						rawXml: captureVerbatimXml(child)
+					});
 					break;
 				}
 			}
@@ -631,6 +651,8 @@ function parseRunContents(runElement, rels, media, rootXmlns = {}) {
 					elements: [innerChild]
 				}, rels, media, rootXmlns));
 			}
+			const hasTextBoxBranch = [choiceEl, fallbackEl].some((branch) => getChildElements(branch).some((element) => getLocalName(element.name) === "drawing" && isTextBoxDrawing(element)));
+			if (contents.length === contentsBeforeAlternate && !hasTextBoxBranch) contents.push(preserveOnlyDrawing(captureVerbatimXml(cloneWithXmlnsDeclarations(child, rootXmlns))));
 			break;
 		}
 		case "footnoteRef":

package/dist/docx/serializer/runSerializer.js

@@ -1,5 +1,6 @@
 import { isValidHexColor } from "../../utils/colorResolver.js";
 import { THEME_COLOR_TO_DRAWING_SCHEME } from "../drawingUtils.js";
+import { serializeGraphicFrameLocks } from "../graphicFrameLocks.js";
 import { canReplayEditableImageRawXml } from "../imageRawXml.js";
 import { requiresXmlSpacePreserve } from "../textWhitespace.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
@@ -285,6 +286,7 @@ function serializeDrawingContent(content) {
 	const inlineDocPr = hlinkClick ? `<wp:docPr ${inlineDocPrAttrs}>${hlinkClick}</wp:docPr>` : `<wp:docPr ${inlineDocPrAttrs}/>`;
 	const anchorDocPrAttrs = `id="${docPrId}" name="${escapeXml(docPrName)}"${docPrDescription}${docPrTitle}`;
 	const anchorDocPr = hlinkClick ? `<wp:docPr ${anchorDocPrAttrs}>${hlinkClick}</wp:docPr>` : `<wp:docPr ${anchorDocPrAttrs}/>`;
+	const graphicFramePr = serializeGraphicFrameLocks(image.frameLocks);
 	const graphic = serializePicGraphic(image, docPrId);
 	if (!isFloating) return [
 		"<w:drawing>",
@@ -292,7 +294,7 @@ function serializeDrawingContent(content) {
 		`<wp:extent cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
 		effectExtentEl,
 		inlineDocPr,
-		"<wp:cNvGraphicFramePr><a:graphicFrameLocks xmlns:a=\"http://schemas.openxmlformats.org/drawingml/2006/main\" noChangeAspect=\"1\"/></wp:cNvGraphicFramePr>",
+		graphicFramePr,
 		graphic,
 		"</wp:inline>",
 		"</w:drawing>"
@@ -309,7 +311,7 @@ function serializeDrawingContent(content) {
 		effectExtentEl,
 		wrap,
 		anchorDocPr,
-		"<wp:cNvGraphicFramePr><a:graphicFrameLocks xmlns:a=\"http://schemas.openxmlformats.org/drawingml/2006/main\" noChangeAspect=\"1\"/></wp:cNvGraphicFramePr>",
+		graphicFramePr,
 		graphic,
 		"</wp:anchor>",
 		"</w:drawing>"

package/dist/docx/server/createBilingualDocument.js

@@ -1,6 +1,7 @@
 import { deterministicHexId } from "../../utils/hexId.js";
 import { getParagraphText } from "../paragraphParser.js";
 import { cloneParagraphWithoutPropertySource } from "../paragraphPropertySource.js";
+import { getRunText } from "../runParser.js";
 import { TaggedError } from "better-result";
 //#region src/docx/server/createBilingualDocument.ts
 /**
@@ -115,7 +116,7 @@ function createBilingualDocument(source, options) {
 		}
 		if (block.type === "paragraph") {
 			if (isEmptyParagraph(block)) continue;
-			if (block.paraId === void 0 || !options.editableParagraphIds.has(block.paraId)) {
+			if (!isTranslatableParagraph(block, options.editableParagraphIds)) {
 				flushSection();
 				content.push(block);
 				continue;
@@ -129,7 +130,7 @@ function createBilingualDocument(source, options) {
 			sectionRows.push(buildRow(block, copy, styleById, textWidth));
 			continue;
 		}
-		const paragraphs = collectTableParagraphs(block).filter((paragraph) => paragraph.paraId !== void 0 && options.editableParagraphIds.has(paragraph.paraId)).map((paragraph) => ({
+		const paragraphs = collectTableParagraphs(block).filter((paragraph) => isTranslatableParagraph(paragraph, options.editableParagraphIds)).map((paragraph) => ({
 			paraId: paragraph.paraId,
 			sourceText: getParagraphText(paragraph)
 		}));
@@ -208,6 +209,31 @@ const isEmptyParagraph = (paragraph) => {
 	if (getParagraphText(paragraph).trim().length > 0) return false;
 	return paragraph.content.every((item) => item.type === "run" && item.formatting?.hidden !== true && item.content.every((part) => part.type === "text"));
 };
+/**
+* A paragraph whose only text is a field result (a table of contents, a page
+* reference). Word recomputes that text, so translating it would be discarded;
+* the paragraph is copied through full width instead of becoming a row.
+*/
+const isFieldOnlyParagraph = (paragraph) => {
+	let hasField = false;
+	for (const item of paragraph.content) {
+		if (item.type === "simpleField" || item.type === "complexField") {
+			hasField = true;
+			continue;
+		}
+		if (item.type === "run" && getRunText(item).trim().length === 0) continue;
+		return false;
+	}
+	return hasField;
+};
+/**
+* A paragraph offered as a translation row.
+*
+* Every site that builds or reads a row reads this one predicate: creation and
+* reading derive the manifest independently, so a rule added to only one of
+* them would surface as a missing handle rather than as the rule it is.
+*/
+const isTranslatableParagraph = (paragraph, editableParagraphIds) => paragraph.paraId !== void 0 && editableParagraphIds.has(paragraph.paraId) && !isFieldOnlyParagraph(paragraph);
 /** Heading style families across Word UI languages (en, cs/sk, de, fr, pl). */
 const HEADING_STYLE_PATTERN = /heading|nadpis|berschrift|titre|nag[łl]/iu;
 const classifyParagraph = (paragraph, styleById) => {
@@ -459,7 +485,7 @@ const cloneTableForTarget = ({ table, editableParagraphIds, paraIds, styleCloner
 					if (item.type === "table") return cloneTable(item);
 					const targetParaId = paraIds.mint(item.paraId);
 					const copy = cloneParagraphForTarget(item, targetParaId, styleCloner, cloner, bookmarkIds);
-					if (item.paraId !== void 0 && editableParagraphIds.has(item.paraId)) paragraphs.push({
+					if (isTranslatableParagraph(item, editableParagraphIds)) paragraphs.push({
 						sourceParaId: item.paraId,
 						targetParaId,
 						sourceText: getParagraphText(item)
@@ -701,7 +727,7 @@ function readBilingualDocument(document, editableParagraphIds) {
 					}
 					const paragraphs = [];
 					for (const [index, source] of sourceParagraphs.entries()) {
-						if (source.paraId === void 0 || !editableParagraphIds.has(source.paraId)) continue;
+						if (!isTranslatableParagraph(source, editableParagraphIds)) continue;
 						const target = targetParagraphs.at(index);
 						if (target?.paraId === void 0 || target.paraId === source.paraId || !editableParagraphIds.has(target.paraId)) {
 							missingHandleCount += 1;
@@ -725,7 +751,7 @@ function readBilingualDocument(document, editableParagraphIds) {
 					missingHandleCount += 1;
 					continue;
 				}
-				const paragraphs = collectTableParagraphs(sourceTable).filter((paragraph) => paragraph.paraId !== void 0 && editableParagraphIds.has(paragraph.paraId)).map((paragraph) => ({
+				const paragraphs = collectTableParagraphs(sourceTable).filter((paragraph) => isTranslatableParagraph(paragraph, editableParagraphIds)).map((paragraph) => ({
 					paraId: paragraph.paraId,
 					sourceText: getParagraphText(paragraph)
 				}));