@stll/folio-core 0.40.0 → 0.42.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/rezip.d.ts

@@ -185,18 +185,35 @@ declare const validateDocx: (buffer: ArrayBuffer) => Promise<{
  * @returns true if buffer starts with ZIP signature
  */
 declare function isDocxBuffer(buffer: ArrayBuffer): boolean;
+/**
+ * The document properties a package built from scratch states about itself.
+ *
+ * A property the host does not name is not written at all: the package states
+ * an author and an application only when a caller supplies one. Both are
+ * ignored for a document that carries a source package, which keeps the
+ * properties that package already states.
+ */
+type DocumentPropertiesOptions = {
+  /** `dc:creator` in `docProps/core.xml`. Omitted when absent. */
+  creator?: string;
+  /** `Application` in `docProps/app.xml`. Omitted, with `AppVersion`, when absent. */
+  application?: string;
+};
 /**
  * Create a new empty DOCX file
  *
+ * @param properties - Document properties the package states about itself
  * @returns Promise resolving to minimal DOCX as ArrayBuffer
  */
-declare function createEmptyDocx(): Promise<ArrayBuffer>;
+declare function createEmptyDocx(properties?: DocumentPropertiesOptions): Promise<ArrayBuffer>;
 /**
  * Create a new DOCX from a Document (without requiring original buffer)
  *
  * @param doc - Document to serialize
+ * @param properties - Document properties a package built from scratch states
+ *   about itself; ignored when `doc` carries a source package
  * @returns Promise resolving to DOCX as ArrayBuffer
  */
-declare function createDocx(doc: document_d_exports.Document): Promise<ArrayBuffer>;
+declare function createDocx(doc: document_d_exports.Document, properties?: DocumentPropertiesOptions): Promise<ArrayBuffer>;
 //#endregion
-export { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_CONTENT_TYPE, COMMENTS_EXTENDED_PART, COMMENTS_EXTENDED_PART_LOWER, DocxPackageFidelityError, RepackOptions, addCommentsExtendedOverride, addCommentsExtendedRelationship, addMedia, addRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, collectHyperlinksWithoutRId, createDocx, createEmptyDocx, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedInlineResources, isDocxBuffer, notePartRelsPath, removeCommentsExtendedOverride, removeCommentsExtendedRelationship, repackDocx, repackDocxFromRaw, updateCoreProperties, updateDocumentXml, updateMultipleFiles, updateXmlFile, validateDocx, withoutAttachedTemplate };
+export { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_CONTENT_TYPE, COMMENTS_EXTENDED_PART, COMMENTS_EXTENDED_PART_LOWER, DocumentPropertiesOptions, DocxPackageFidelityError, RepackOptions, addCommentsExtendedOverride, addCommentsExtendedRelationship, addMedia, addRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, collectHyperlinksWithoutRId, createDocx, createEmptyDocx, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedInlineResources, isDocxBuffer, notePartRelsPath, removeCommentsExtendedOverride, removeCommentsExtendedRelationship, repackDocx, repackDocxFromRaw, updateCoreProperties, updateDocumentXml, updateMultipleFiles, updateXmlFile, validateDocx, withoutAttachedTemplate };

package/dist/docx/rezip.js

@@ -1,7 +1,7 @@
 import { consumeTrackedSectionEndpointRemoval } from "../internal/sectionEndpointResolution.js";
 import { consumeSectionReferenceResolution } from "../internal/sectionReferenceResolution.js";
 import { isAllowedExternalWatermarkImageUrl } from "../watermark/index.js";
-import { normalizeAppVersionInExtendedProperties } from "./appVersionNormalization.js";
+import { appVersionInSchemaForm, normalizeAppVersionInExtendedProperties } from "./appVersionNormalization.js";
 import { withoutOrphanCommentRanges } from "./commentRangeIntegrity.js";
 import { applyReplyThreadMarkers } from "./commentReplyMarkers.js";
 import { normalizeDrawingIds } from "./drawingIdNormalization.js";
@@ -1524,14 +1524,24 @@ function isDocxBuffer(buffer) {
 	return view[0] === 80 && view[1] === 75;
 }
 /**
+* The application version a newly created package states.
+*
+* `AppVersion` describes the application, so it is written only alongside one,
+* and it says nothing about the host beyond the `XX.YYYY` form the schema
+* fixes. Deriving it from the mapping every save exit already uses keeps the
+* two from drifting apart.
+*/
+const CREATED_APP_VERSION = appVersionInSchemaForm("1");
+/**
 * Create a new empty DOCX file
 *
+* @param properties - Document properties the package states about itself
 * @returns Promise resolving to minimal DOCX as ArrayBuffer
 */
-function createEmptyDocx() {
-	return generateDocxZip(createEmptyDocxZip(), 6);
+function createEmptyDocx(properties = {}) {
+	return generateDocxZip(createEmptyDocxZip(properties), 6);
 }
-const createEmptyDocxZip = () => {
+const createEmptyDocxZip = ({ creator, application }) => {
 	const zip = new JSZip();
 	zip.file("[Content_Types].xml", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
@@ -1586,16 +1596,15 @@ const createEmptyDocxZip = () => {
   </w:style>
 </w:styles>`);
 	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const creatorElement = creator === void 0 ? "" : `\n  <dc:creator>${escapeXml(creator)}</dc:creator>`;
 	zip.file("docProps/core.xml", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
-  <dc:creator>EigenPal DOCX Editor</dc:creator>
+<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">${creatorElement}
   <dcterms:created xsi:type="dcterms:W3CDTF">${now}</dcterms:created>
   <dcterms:modified xsi:type="dcterms:W3CDTF">${now}</dcterms:modified>
 </cp:coreProperties>`);
+	const applicationElements = application === void 0 ? "" : `\n  <Application>${escapeXml(application)}</Application>\n  <AppVersion>${CREATED_APP_VERSION}</AppVersion>`;
 	zip.file("docProps/app.xml", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/extended-properties">
-  <Application>EigenPal DOCX Editor</Application>
-  <AppVersion>1.0000</AppVersion>
+<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/extended-properties">${applicationElements}
 </Properties>`);
 	return zip;
 };
@@ -1603,9 +1612,11 @@ const createEmptyDocxZip = () => {
 * Create a new DOCX from a Document (without requiring original buffer)
 *
 * @param doc - Document to serialize
+* @param properties - Document properties a package built from scratch states
+*   about itself; ignored when `doc` carries a source package
 * @returns Promise resolving to DOCX as ArrayBuffer
 */
-async function createDocx(doc) {
+async function createDocx(doc, properties = {}) {
 	if (doc.originalBuffer) {
 		const source = await loadParsedZipSource(doc, doc.originalBuffer);
 		return finishRepack({
@@ -1618,7 +1629,7 @@ async function createDocx(doc) {
 			updateModifiedDate: true
 		});
 	}
-	const zip = await createDocumentSeedZip(doc);
+	const zip = await createDocumentSeedZip(doc, properties);
 	return finishRepack({
 		document: withoutOrphanCommentRanges(doc),
 		originalZip: zip,
@@ -1629,8 +1640,8 @@ async function createDocx(doc) {
 		updateModifiedDate: true
 	});
 }
-const createDocumentSeedZip = async (doc) => {
-	const zip = createEmptyDocxZip();
+const createDocumentSeedZip = async (doc, properties) => {
+	const zip = createEmptyDocxZip(properties);
 	const relationships = ["<Relationship Id=\"rId1\" Type=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles\" Target=\"styles.xml\"/>"];
 	const overrides = [];
 	let nextRelationshipId = 2;

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":