@stll/folio-core 0.40.0 → 0.41.0

package/dist/docx/shapeParser.js

@@ -87,6 +87,28 @@ function hasUnsupportedRgbColorModifiers(spPr) {
 function hasUnmodeledFill(spPr) {
 	return findChildByLocalName(spPr, "pattFill") !== null || findChildByLocalName(spPr, "blipFill") !== null || findChildByLocalName(spPr, "grpFill") !== null;
 }
+/**
+* Shape properties the serializer never emits: `Shape` models geometry, fill,
+* outline and transform only, so a shadow, glow, reflection or 3-D scene would
+* be dropped on save.
+*/
+const UNMODELED_EFFECT_ELEMENTS = [
+	"effectLst",
+	"effectDag",
+	"scene3d",
+	"sp3d"
+];
+/**
+* An empty `<a:effectLst/>` is Word's explicit "no effects" marker and models
+* fine; carried attributes (`<a:sp3d extrusionH="…"/>`) or children do not.
+*/
+function hasUnmodeledEffects(spPr) {
+	return UNMODELED_EFFECT_ELEMENTS.some((localName) => {
+		const element = findChildByLocalName(spPr, localName);
+		if (!element) return false;
+		return getChildElements(element).length > 0 || Object.keys(element.attributes ?? {}).length > 0;
+	});
+}
 function colorNeedsRawPreservation(color) {
 	return color !== void 0 && color.rgb === void 0;
 }
@@ -97,6 +119,14 @@ function fillNeedsRawPreservation(fill) {
 	return false;
 }
 /**
+* The single answer to "does this `wps:spPr` carry something the editable
+* `Shape` model would lose?". `parseShapeFromDrawing` refuses such a shape and
+* `shouldPreserveRawShapeDrawing` claims it for verbatim preservation, so both
+* must read the same predicate: a reason added to only one of them would
+* either drop the drawing or model it lossily.
+*/
+const shapeNeedsRawPreservation = (spPr) => hasUnsupportedGeometry(spPr) || hasUnsupportedRgbColorModifiers(spPr) || hasUnmodeledFill(spPr) || hasUnmodeledEffects(spPr) || fillNeedsRawPreservation(parseShapeFill(spPr));
+/**
 * Parse a `<wps:wsp>` element into a Shape model. Does NOT pick up the
 * extent / position / wrap fields — those live on the wrapping
 * `<wp:inline>` / `<wp:anchor>` and are handled by `parseShapeFromDrawing`.
@@ -143,7 +173,7 @@ function parseShapeFromDrawing(drawingEl) {
 	if (!wsp) return null;
 	if (findChildByLocalName(wsp, "txbx") !== null) return null;
 	const spPr = findChildByLocalName(wsp, "spPr");
-	if (hasUnsupportedGeometry(spPr) || hasUnsupportedRgbColorModifiers(spPr) || hasUnmodeledFill(spPr) || fillNeedsRawPreservation(parseShapeFill(spPr))) return null;
+	if (shapeNeedsRawPreservation(spPr)) return null;
 	const shape = parseShape(wsp);
 	const extent = findChildByLocalName(container, "extent");
 	if (extent) {
@@ -178,11 +208,7 @@ function shouldPreserveRawShapeDrawing(drawingEl) {
 	const graphicData = graphic ? findChildByLocalName(graphic, "graphicData") : null;
 	const wsp = graphicData ? findChildByLocalName(graphicData, "wsp") : null;
 	if (!wsp || findChildByLocalName(wsp, "txbx") !== null) return false;
-	const spPr = findChildByLocalName(wsp, "spPr");
-	if (hasUnsupportedGeometry(spPr)) return true;
-	if (hasUnsupportedRgbColorModifiers(spPr)) return true;
-	if (hasUnmodeledFill(spPr)) return true;
-	return fillNeedsRawPreservation(parseShapeFill(spPr));
+	return shapeNeedsRawPreservation(findChildByLocalName(wsp, "spPr"));
 }
 //#endregion
 export { parseShape, parseShapeFromDrawing, shouldPreserveRawShapeDrawing };

package/dist/docx/vmlImageParser.d.ts

@@ -1,6 +1,16 @@
 import { document_d_exports } from "../types/document.js";
 import { XmlElement } from "./xmlParser.js";
 //#region src/docx/vmlImageParser.d.ts
+/**
+ * Whether a `w:pict` that resolved to no image must still be kept verbatim.
+ *
+ * VML has no serializer of its own, so an unresolved `w:pict` is only ever
+ * preserved or lost. Two owners are excluded: a `v:textbox` belongs to the
+ * text-box enrichment pass, which rebuilds it as an editable shape, and a
+ * watermark shape belongs to watermarkParser; preserving either would emit the
+ * same artwork twice.
+ */
+declare function shouldPreserveRawVmlPict(pictElement: XmlElement): boolean;
 /**
  * Parse a `w:pict` element into an inline image, or null when it carries no
  * ordinary VML picture (no resolvable `<v:imagedata>`, or a watermark shape).
@@ -12,4 +22,4 @@ import { XmlElement } from "./xmlParser.js";
  */
 declare function parseVmlImageContent(pictElement: XmlElement, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, rootXmlns?: Record<string, string>): document_d_exports.DrawingContent | null;
 //#endregion
-export { parseVmlImageContent };
+export { parseVmlImageContent, shouldPreserveRawVmlPict };

package/dist/docx/vmlImageParser.js

@@ -4,7 +4,7 @@ import { resolveImageData } from "./imageParser.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
 import { isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx, vmlSvgDataUrl } from "./vmlPreview.js";
 import { isWatermarkShape } from "./watermarkParser.js";
-import { cloneWithXmlnsDeclarations, findAllDeep, findChild, getAttribute, getChildElements, getLocalName } from "./xmlParser.js";
+import { cloneWithXmlnsDeclarations, findAllDeep, findChild, findDeep, getAttribute, getChildElements, getLocalName } from "./xmlParser.js";
 //#region src/docx/vmlImageParser.ts
 const VML_POSITION_ABSOLUTE = "absolute";
 const IMAGE_WRAP_INLINE = "inline";
@@ -102,6 +102,33 @@ const previewDrawing = (pictElement, preview, rootXmlns) => {
 		default: return preview;
 	}
 };
+/** VML elements that paint something, i.e. content a save must not lose. */
+const VML_DRAWABLE_SHAPES = [
+	"shape",
+	"group",
+	"rect",
+	"roundrect",
+	"oval",
+	"line",
+	"polyline",
+	"curve",
+	"arc",
+	"image"
+];
+/**
+* Whether a `w:pict` that resolved to no image must still be kept verbatim.
+*
+* VML has no serializer of its own, so an unresolved `w:pict` is only ever
+* preserved or lost. Two owners are excluded: a `v:textbox` belongs to the
+* text-box enrichment pass, which rebuilds it as an editable shape, and a
+* watermark shape belongs to watermarkParser; preserving either would emit the
+* same artwork twice.
+*/
+function shouldPreserveRawVmlPict(pictElement) {
+	if (findDeep(pictElement, "v", "textbox")) return false;
+	const shapes = VML_DRAWABLE_SHAPES.flatMap((localName) => findAllDeep(pictElement, "v", localName));
+	return shapes.length > 0 && !shapes.some((shape) => isWatermarkShape(shape));
+}
 /**
 * Read the relationship id off a `v:imagedata` element. Word writes `r:id`;
 * some legacy / third-party generators use `r:embed` or the office-namespace
@@ -173,4 +200,4 @@ function parseVmlImageContent(pictElement, rels, media, rootXmlns = {}) {
 	return null;
 }
 //#endregion
-export { parseVmlImageContent };
+export { parseVmlImageContent, shouldPreserveRawVmlPict };

package/dist/index.d.ts

@@ -21,7 +21,8 @@ import { mergeDocumentContent } from "./utils/mergeDocumentContent.js";
 import { DocumentStyleCatalog, DocumentStyleCatalogEntry, ExtractDocumentStyleSetOptions, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, inspectDocumentStyles, inspectDocumentStylesFromDocx } from "./style-sets/extract.js";
 import { STELLA_STYLE_SET_NAME, createStellaStyleDocumentPreset, createStellaStyleSet } from "./style-sets/stellaStyle.js";
 import { createDocx } from "./docx/rezip.js";
-import { DocxCompatibility, DocxCompatibilityContext, DocxCompatibilityIssue, DocxCompatibilityLocation, DocxCompatibilityPart, FolioDocxCompatibilityHost, FolioDocxCompatibilityProfile, InspectDocxCompatibilityOptions, inspectDocxCompatibility } from "./docx/compatibility.js";
+import { DRAWING_SAFETY_CLASSES, DrawingSafetyClass } from "./docx/imageRawXml.js";
+import { DocxCompatibility, DocxCompatibilityContext, DocxCompatibilityIssue, DocxCompatibilityLocation, DocxCompatibilityPart, DocxDrawingClassification, FolioDocxCompatibilityHost, FolioDocxCompatibilityProfile, InspectDocxCompatibilityOptions, inspectDocxCompatibility } from "./docx/compatibility.js";
 import { BlockRect } from "./paged-layout/blockGeometry.js";
 import { setAISuggestionsMeta, setFocusedSuggestionMeta } from "./prosemirror/plugins/aiSuggestionDecorations.js";
 import { scrollFolioPositionIntoView } from "./paged-layout/scrollToPmPosition.js";
@@ -40,4 +41,4 @@ import { getGoogleFontsEnabled, setEmbeddedFontFamilyMap, setGoogleFontsEnabled
 import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
 type Document = document_d_exports.Document;
 type DocxConformanceClass = document_d_exports.DocxConformanceClass;
-export { type AIBarStatus, type AIChatMode, type AICitation, type AICitationRange, type AICitationSource, type AIGenerateInput, type AISuggestion, type AISuggestionApplyMode, type AISuggestionPreset, type AISuggestionSeverity, type AISuggestionStatus, type AcceptAutocompleteResult, type AnonymizationMatch, type AnonymizationTerm, type ApplyFolioDocumentOperationsOptions, type ApplyResult, type AutocompleteSuggestionPluginOptions, type AutocompleteSuggestionState, type AutocompleteSuggestionStatus, type AutocompleteTriggerCheck, type AutocompleteTriggerOptions, type AutocompleteTriggerSkipReason, type BlockRect, COMPARE_REVISION_FORMATS, COMPARE_UNSUPPORTED_REASONS, COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, type CompareChange, type CompareChangeLocation, type CompareCompatibility, type CompareContentOptions, CompareDocxApplyError, type CompareDocxError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, type CompareDocxOptions, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, type CompareFolioRequirement, type CompareResult, type CompareRevisionFormat, type CompareUnsupportedPart, type CompareUnsupportedReason, type CompareVerification, type CompareVerificationCause, type CompareVerificationFailure, type CompareVerificationInvariant, type CreateEmptyDocumentOptions, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DOCX_CONFORMANCE_CLASSES, type DeriveBlockIdInput, type DirectiveKind, type DirectiveRange, type Document, type DocumentPreset, type DocumentStyleCatalog, type DocumentStyleCatalogEntry, type DocumentStyleSet, type DocxCompatibility, type DocxCompatibilityContext, type DocxCompatibilityIssue, type DocxCompatibilityLocation, type DocxCompatibilityPart, type DocxConformanceClass, type EmbeddedFont, type EmbeddedFontParts, type ExtractDocumentStyleSetOptions, FOLIO_CONTENT_COMPARISON_LIMITS, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, 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, type FinalParagraphMarkRevision, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIBlockStructuralBoundary, type FolioAIBlockTableLocation, type FolioAIComment, type FolioAIEditAppliedOperation, type FolioAIEditApplyMode, type FolioAIEditApplyOutcome, type FolioAIEditApplyResult, type FolioAIEditNormalization, type FolioAIEditNormalizationCode, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditReviewMeta, type FolioAIEditSeverity, type FolioAIEditSkipReason, type FolioAIEditSkippedOperation, type FolioAIEditSnapshot, type FolioAIInlineBooleanProperty, type FolioAIInlineFormatting, type FolioAIInlineFormattingPatch, type FolioAIParagraphSpacing, type FolioAISignatureParty, type FolioBlockId, type FolioContentBlock, type FolioContentBlockProperty, type FolioContentComparison, type FolioContentComparisonError, type FolioContentComparisonEvent, type FolioContentComparisonLimit, FolioContentComparisonLimitError, type FolioContentContainerPathEntry, type FolioContentFormatRange, type FolioContentFormattingChange, type FolioContentIdStability, type FolioContentInlineBooleanProperty, type FolioContentInlineComparisonResult, type FolioContentInlineFormatting, type FolioContentInlineFormattingPatch, FolioContentInlinePresentationProjectionError, type FolioContentLineSpacingRule, type FolioContentParagraphAlignment, type FolioContentParagraphFormattingPatch, type FolioContentParagraphKind, type FolioContentParagraphSpacing, type FolioContentRun, type FolioContentSnapshot, type FolioContentStructuralChange, type FolioContentTableLocation, type FolioContentTextSegment, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationResultBase, type FolioDocumentOperationStatus, type FolioDocumentOperationStory, type FolioDocumentOperationType, type FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocxCompatibilityHost, type FolioDocxCompatibilityProfile, type FolioRevisionStamp, type FolioWordDiffOptions, type ImageMeta, type ImageRef, type InspectDocxCompatibilityOptions, InvalidCompareDocxOptionsError, InvalidFolioContentComparisonError, InvalidFolioDocumentOperationBatchError, MAX_COMPARE_OPERATIONS, type MarkdownOptions, type MarkdownResult, type PositionalText, type ResolvedAnchor, STELLA_STYLE_SET_NAME, type TemplatePreviewSpan, type TemplatePreviewValue, type TemplatePreviewValues, type TemplateSlashMenuKeyAction, type TemplateSlashMenuState, UnsupportedFolioDocumentOperationVersionError, WORD_DIFF_GRANULARITIES, type WordDiffGranularity, type WordDiffNormalization, type WordDiffOptions, type WordDiffSegment, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applyFolioDocumentOperations, applySuggestions, assertSupportedFolioDocumentOperationVersion, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildEmbeddedFontFamilyMap, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, compareContent, compareDocx, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, createStellaStyleDocumentPreset, createStellaStyleSet, currentFolioBlockId, deriveBlockId, diffWordSegments, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getGoogleFontsEnabled, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxCompatibility, isFolioAIContentBlock, isFolioBlockId, isFolioDocumentOperationModeSupported, isSequentialFolioBlockId, isSuggestionStale, isSupportedFolioDocumentOperationVersion, mergeDocumentContent, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scopeEmbeddedFontFamily, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setEmbeddedFontFamilyMap, setFocusedSuggestionMeta, setGoogleFontsEnabled, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };
+export { type AIBarStatus, type AIChatMode, type AICitation, type AICitationRange, type AICitationSource, type AIGenerateInput, type AISuggestion, type AISuggestionApplyMode, type AISuggestionPreset, type AISuggestionSeverity, type AISuggestionStatus, type AcceptAutocompleteResult, type AnonymizationMatch, type AnonymizationTerm, type ApplyFolioDocumentOperationsOptions, type ApplyResult, type AutocompleteSuggestionPluginOptions, type AutocompleteSuggestionState, type AutocompleteSuggestionStatus, type AutocompleteTriggerCheck, type AutocompleteTriggerOptions, type AutocompleteTriggerSkipReason, type BlockRect, COMPARE_REVISION_FORMATS, COMPARE_UNSUPPORTED_REASONS, COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, type CompareChange, type CompareChangeLocation, type CompareCompatibility, type CompareContentOptions, CompareDocxApplyError, type CompareDocxError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, type CompareDocxOptions, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, type CompareFolioRequirement, type CompareResult, type CompareRevisionFormat, type CompareUnsupportedPart, type CompareUnsupportedReason, type CompareVerification, type CompareVerificationCause, type CompareVerificationFailure, type CompareVerificationInvariant, type CreateEmptyDocumentOptions, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DOCX_CONFORMANCE_CLASSES, DRAWING_SAFETY_CLASSES, type DeriveBlockIdInput, type DirectiveKind, type DirectiveRange, type Document, type DocumentPreset, type DocumentStyleCatalog, type DocumentStyleCatalogEntry, type DocumentStyleSet, type DocxCompatibility, type DocxCompatibilityContext, type DocxCompatibilityIssue, type DocxCompatibilityLocation, type DocxCompatibilityPart, type DocxConformanceClass, type DocxDrawingClassification, type DrawingSafetyClass, type EmbeddedFont, type EmbeddedFontParts, type ExtractDocumentStyleSetOptions, FOLIO_CONTENT_COMPARISON_LIMITS, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, 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, type FinalParagraphMarkRevision, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIBlockStructuralBoundary, type FolioAIBlockTableLocation, type FolioAIComment, type FolioAIEditAppliedOperation, type FolioAIEditApplyMode, type FolioAIEditApplyOutcome, type FolioAIEditApplyResult, type FolioAIEditNormalization, type FolioAIEditNormalizationCode, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditReviewMeta, type FolioAIEditSeverity, type FolioAIEditSkipReason, type FolioAIEditSkippedOperation, type FolioAIEditSnapshot, type FolioAIInlineBooleanProperty, type FolioAIInlineFormatting, type FolioAIInlineFormattingPatch, type FolioAIParagraphSpacing, type FolioAISignatureParty, type FolioBlockId, type FolioContentBlock, type FolioContentBlockProperty, type FolioContentComparison, type FolioContentComparisonError, type FolioContentComparisonEvent, type FolioContentComparisonLimit, FolioContentComparisonLimitError, type FolioContentContainerPathEntry, type FolioContentFormatRange, type FolioContentFormattingChange, type FolioContentIdStability, type FolioContentInlineBooleanProperty, type FolioContentInlineComparisonResult, type FolioContentInlineFormatting, type FolioContentInlineFormattingPatch, FolioContentInlinePresentationProjectionError, type FolioContentLineSpacingRule, type FolioContentParagraphAlignment, type FolioContentParagraphFormattingPatch, type FolioContentParagraphKind, type FolioContentParagraphSpacing, type FolioContentRun, type FolioContentSnapshot, type FolioContentStructuralChange, type FolioContentTableLocation, type FolioContentTextSegment, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationResultBase, type FolioDocumentOperationStatus, type FolioDocumentOperationStory, type FolioDocumentOperationType, type FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocxCompatibilityHost, type FolioDocxCompatibilityProfile, type FolioRevisionStamp, type FolioWordDiffOptions, type ImageMeta, type ImageRef, type InspectDocxCompatibilityOptions, InvalidCompareDocxOptionsError, InvalidFolioContentComparisonError, InvalidFolioDocumentOperationBatchError, MAX_COMPARE_OPERATIONS, type MarkdownOptions, type MarkdownResult, type PositionalText, type ResolvedAnchor, STELLA_STYLE_SET_NAME, type TemplatePreviewSpan, type TemplatePreviewValue, type TemplatePreviewValues, type TemplateSlashMenuKeyAction, type TemplateSlashMenuState, UnsupportedFolioDocumentOperationVersionError, WORD_DIFF_GRANULARITIES, type WordDiffGranularity, type WordDiffNormalization, type WordDiffOptions, type WordDiffSegment, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applyFolioDocumentOperations, applySuggestions, assertSupportedFolioDocumentOperationVersion, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildEmbeddedFontFamilyMap, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, compareContent, compareDocx, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, createStellaStyleDocumentPreset, createStellaStyleSet, currentFolioBlockId, deriveBlockId, diffWordSegments, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getGoogleFontsEnabled, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxCompatibility, isFolioAIContentBlock, isFolioBlockId, isFolioDocumentOperationModeSupported, isSequentialFolioBlockId, isSuggestionStale, isSupportedFolioDocumentOperationVersion, mergeDocumentContent, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scopeEmbeddedFontFamily, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setEmbeddedFontFamilyMap, setFocusedSuggestionMeta, setGoogleFontsEnabled, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };

package/dist/index.js

@@ -11,6 +11,7 @@ import { COMPARE_REVISION_FORMATS, COMPARE_UNSUPPORTED_REASONS, CompareDocxApply
 import { COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS } from "./compare/verification.js";
 import { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, 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 } from "./document-operations.js";
 import { inspectDocxCompatibility } from "./docx/compatibility.js";
+import { DRAWING_SAFETY_CLASSES } from "./docx/imageRawXml.js";
 import { createDocx } from "./docx/rezip.js";
 import { buildEmbeddedFontFamilyMap, extractEmbeddedFonts, getEmbeddedFontFaces, scopeEmbeddedFontFamily } from "./fonts/embeddedFonts.js";
 import { fromMarkdown } from "./markdown/fromMarkdown.js";
@@ -32,4 +33,4 @@ import { createEmptyDocument } from "./utils/createDocument.js";
 import { getGoogleFontsEnabled, setEmbeddedFontFamilyMap, setGoogleFontsEnabled } from "./utils/fontResolver.js";
 import { mergeDocumentContent } from "./utils/mergeDocumentContent.js";
 import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
-export { COMPARE_REVISION_FORMATS, COMPARE_UNSUPPORTED_REASONS, COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, CompareDocxApplyError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DOCX_CONFORMANCE_CLASSES, FOLIO_CONTENT_COMPARISON_LIMITS, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, 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, FolioContentComparisonLimitError, FolioContentInlinePresentationProjectionError, InvalidCompareDocxOptionsError, InvalidFolioContentComparisonError, InvalidFolioDocumentOperationBatchError, MAX_COMPARE_OPERATIONS, STELLA_STYLE_SET_NAME, UnsupportedFolioDocumentOperationVersionError, WORD_DIFF_GRANULARITIES, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applyFolioDocumentOperations, applySuggestions, assertSupportedFolioDocumentOperationVersion, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildEmbeddedFontFamilyMap, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, compareContent, compareDocx, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, createStellaStyleDocumentPreset, createStellaStyleSet, currentFolioBlockId, deriveBlockId, diffWordSegments, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getGoogleFontsEnabled, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxCompatibility, isFolioAIContentBlock, isFolioBlockId, isFolioDocumentOperationModeSupported, isSequentialFolioBlockId, isSuggestionStale, isSupportedFolioDocumentOperationVersion, mergeDocumentContent, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scopeEmbeddedFontFamily, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setEmbeddedFontFamilyMap, setFocusedSuggestionMeta, setGoogleFontsEnabled, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };
+export { COMPARE_REVISION_FORMATS, COMPARE_UNSUPPORTED_REASONS, COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, CompareDocxApplyError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DOCX_CONFORMANCE_CLASSES, DRAWING_SAFETY_CLASSES, FOLIO_CONTENT_COMPARISON_LIMITS, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, 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, FolioContentComparisonLimitError, FolioContentInlinePresentationProjectionError, InvalidCompareDocxOptionsError, InvalidFolioContentComparisonError, InvalidFolioDocumentOperationBatchError, MAX_COMPARE_OPERATIONS, STELLA_STYLE_SET_NAME, UnsupportedFolioDocumentOperationVersionError, WORD_DIFF_GRANULARITIES, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applyFolioDocumentOperations, applySuggestions, assertSupportedFolioDocumentOperationVersion, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildEmbeddedFontFamilyMap, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, compareContent, compareDocx, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, createStellaStyleDocumentPreset, createStellaStyleSet, currentFolioBlockId, deriveBlockId, diffWordSegments, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getGoogleFontsEnabled, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxCompatibility, isFolioAIContentBlock, isFolioBlockId, isFolioDocumentOperationModeSupported, isSequentialFolioBlockId, isSuggestionStale, isSupportedFolioDocumentOperationVersion, mergeDocumentContent, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scopeEmbeddedFontFamily, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setEmbeddedFontFamilyMap, setFocusedSuggestionMeta, setGoogleFontsEnabled, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };

package/dist/internal/compare/inline-presentation.d.ts

@@ -1,7 +1,15 @@
-import { FolioContentBlock, FolioContentInlineComparisonResult } from "../../compare/content-types.js";
+import { FolioContentBlock, FolioContentInlineComparisonResult, FolioContentInlineFormatting } from "../../compare/content-types.js";
 //#region src/internal/compare/inline-presentation.d.ts
-/** Derived from the descriptor grammar; tests use it to prove full coverage. */
-declare const CANONICAL_INLINE_PRESENTATION_PROPERTIES: readonly ("bold" | "italic" | "underline" | "strike" | "fontFamily" | "fontSizePt" | "color")[];
+type InlineFormattingProperty = keyof FolioContentInlineFormatting;
+/**
+ * Derived from the descriptor grammar; tests use it to prove full coverage.
+ *
+ * Annotated, against the usual rule, for the reason given on
+ * `DISPLAY_PRIMITIVE_KINDS`: the inferred union's member order is not stable
+ * across declaration builds, and naming the alias keeps the emitted `.d.ts`
+ * reproducible.
+ */
+declare const CANONICAL_INLINE_PRESENTATION_PROPERTIES: readonly InlineFormattingProperty[];
 type InlinePresentationBlock = Pick<FolioContentBlock, "previewRuns" | "text">;
 type CanonicalInlinePresentationSegmentsOptions = {
   baseBlock: InlinePresentationBlock;

package/dist/internal/compare/inline-presentation.js

@@ -28,7 +28,14 @@ const INLINE_PRESENTATION_GRAMMAR = {
 	color: ["color"]
 };
 const INLINE_PRESENTATION_HOT_PATH_GRAMMAR = INLINE_PRESENTATION_GRAMMAR;
-/** Derived from the descriptor grammar; tests use it to prove full coverage. */
+/**
+* Derived from the descriptor grammar; tests use it to prove full coverage.
+*
+* Annotated, against the usual rule, for the reason given on
+* `DISPLAY_PRIMITIVE_KINDS`: the inferred union's member order is not stable
+* across declaration builds, and naming the alias keeps the emitted `.d.ts`
+* reproducible.
+*/
 const CANONICAL_INLINE_PRESENTATION_PROPERTIES = Object.freeze([
 	...INLINE_PRESENTATION_GRAMMAR.boolean,
 	...INLINE_PRESENTATION_GRAMMAR.string,

package/dist/prosemirror/attrs/index.js

@@ -1,3 +1,5 @@
+import { GRAPHIC_FRAME_LOCK_KEYS } from "../../docx/graphicFrameLocks.js";
+import { allowsDirectDrawingEdit, isDrawingRawXmlMode } from "../../docx/imageRawXml.js";
 import { EMPHASIS_MARK_VALUES, FIELD_TYPE_VALUES, FONT_HINT_VALUES, FONT_THEME_VALUES, HIGHLIGHT_COLOR_VALUES, IMAGE_HORIZONTAL_ALIGNMENT_VALUES, IMAGE_HORIZONTAL_RELATIVE_TO_VALUES, IMAGE_VERTICAL_ALIGNMENT_VALUES, IMAGE_VERTICAL_RELATIVE_TO_VALUES, IMAGE_WRAP_TEXT_VALUES, IMAGE_WRAP_TYPE_VALUES, LINE_SPACING_RULE_VALUES, NUMBER_FORMAT_VALUES, OUTLINE_STYLE_ATTR_VALUES, PARAGRAPH_ALIGNMENT_VALUES, POSITIONAL_TAB_ALIGNMENT_VALUES, POSITIONAL_TAB_LEADER_VALUES, POSITIONAL_TAB_RELATIVE_TO_VALUES, SDT_LOCK_VALUES, SDT_TYPE_VALUES, SHADING_PATTERN_VALUES, TABLE_CELL_TEXT_DIRECTION_VALUES, TABLE_CELL_VERTICAL_ALIGNMENT_VALUES, TABLE_JUSTIFICATION_VALUES, TABLE_ROW_HEIGHT_RULE_VALUES, TABLE_WIDTH_TYPE_VALUES, TAB_LEADER_VALUES, TAB_STOP_ALIGNMENT_VALUES, TEXT_EFFECT_VALUES, THEME_COLOR_SLOT_VALUES, UNDERLINE_STYLE_VALUES } from "../../types/documentEnumValues.js";
 import { canonicalJson } from "../../utils/canonicalJson.js";
 import { normalizeHorizontalScalePercent } from "../../utils/horizontalScale.js";
@@ -395,8 +397,18 @@ const readImageAttrs = (node) => {
 	optionalNumber(attrs, "distBottom", "image.attrs.distBottom", issues);
 	optionalNumber(attrs, "distLeft", "image.attrs.distLeft", issues);
 	optionalNumber(attrs, "distRight", "image.attrs.distRight", issues);
+	optionalNumber(attrs, "opacity", "image.attrs.opacity", issues);
+	optionalNumber(attrs, "cropTop", "image.attrs.cropTop", issues);
+	optionalNumber(attrs, "cropRight", "image.attrs.cropRight", issues);
+	optionalNumber(attrs, "cropBottom", "image.attrs.cropBottom", issues);
+	optionalNumber(attrs, "cropLeft", "image.attrs.cropLeft", issues);
+	optionalNumber(attrs, "paddingTop", "image.attrs.paddingTop", issues);
+	optionalNumber(attrs, "paddingRight", "image.attrs.paddingRight", issues);
+	optionalNumber(attrs, "paddingBottom", "image.attrs.paddingBottom", issues);
+	optionalNumber(attrs, "paddingLeft", "image.attrs.paddingLeft", issues);
 	optionalImagePosition(attrs, "position", "image.attrs.position", issues);
 	optionalBoolean(attrs, "layoutInCell", "image.attrs.layoutInCell", issues);
+	optionalImageFrameLocks(attrs, "frameLocks", "image.attrs.frameLocks", issues);
 	optionalNumber(attrs, "borderWidth", "image.attrs.borderWidth", issues);
 	optionalString(attrs, "borderColor", "image.attrs.borderColor", issues);
 	optionalString(attrs, "borderStyle", "image.attrs.borderStyle", issues);
@@ -405,10 +417,11 @@ const readImageAttrs = (node) => {
 	optionalString(attrs, "hlinkRId", "image.attrs.hlinkRId", issues);
 	optionalString(attrs, "_docxRawXml", "image.attrs._docxRawXml", issues);
 	optionalOneOf(attrs, "_docxRawXmlMode", "image.attrs._docxRawXmlMode", issues, Object.values(DRAWING_RAW_XML_MODES));
+	optionalString(attrs, "_docxRawImageFingerprint", "image.attrs._docxRawImageFingerprint", issues);
 	const rawXml = attrs["_docxRawXml"];
-	if (attrs["_docxRawXmlMode"] === DRAWING_RAW_XML_MODES.PRESERVE_ONLY && (typeof rawXml !== "string" || rawXml.trim().length === 0)) issues.push({
+	if (isDrawingRawXmlMode(attrs["_docxRawXmlMode"]) && (typeof rawXml !== "string" || rawXml.trim().length === 0)) issues.push({
 		path: "image.attrs._docxRawXml",
-		message: "Preservation-only drawings require raw XML."
+		message: "Classified drawings require raw XML."
 	});
 	optionalBoolean(attrs, "_docxObjectPreview", "image.attrs._docxObjectPreview", issues);
 	return attrsResult(attrs, issues);
@@ -821,6 +834,7 @@ const IMAGE_RESOURCE_ATTRS = /* @__PURE__ */ new Set([
 	"rId",
 	"_docxRawXml",
 	"_docxRawXmlMode",
+	"_docxRawImageFingerprint",
 	"_docxObjectPreview"
 ]);
 const imageAttrValuesEqual = (left, right) => {
@@ -831,7 +845,11 @@ const imageAttrValuesEqual = (left, right) => {
 const mergeImageAttrs = (node, patch) => {
 	const current = expectImageAttrs(node);
 	const merged = mergeNodeAttrs(node, readImageAttrs, "image attrs", patch);
-	if (!Object.entries(patch).some(([key, value]) => !IMAGE_RESOURCE_ATTRS.has(key) && !imageAttrValuesEqual(Reflect.get(current, key), value)) || current._docxRawXml === void 0 || current._docxRawXmlMode === DRAWING_RAW_XML_MODES.PRESERVE_ONLY) return merged;
+	if (!Object.entries(patch).some(([key, value]) => !IMAGE_RESOURCE_ATTRS.has(key) && !imageAttrValuesEqual(Reflect.get(current, key), value)) || current._docxRawXml === void 0) return merged;
+	if (!allowsDirectDrawingEdit(current._docxRawXmlMode)) {
+		const { _docxRawImageFingerprint: _discardedFingerprint, ...editedAttrs } = merged;
+		return editedAttrs;
+	}
 	const { _docxRawXml: _discardedRawXml, ...editableAttrs } = merged;
 	return editableAttrs;
 };
@@ -1769,6 +1787,18 @@ const validatePropertyChangeInfo = (value, path, issues) => {
 	optionalOneOf(value, "provenance", `${path}.provenance`, issues, TRACKED_CHANGE_PROVENANCE_VALUES);
 	optionalString(value, "suggestionId", `${path}.suggestionId`, issues);
 };
+const optionalImageFrameLocks = (attrs, key, path, issues) => {
+	const value = attrs[key];
+	if (value === void 0 || value === null) return;
+	if (!isRecord(value)) {
+		issues.push({
+			path,
+			message: "Expected an object."
+		});
+		return;
+	}
+	for (const lock of GRAPHIC_FRAME_LOCK_KEYS) optionalBoolean(value, lock, `${path}.${lock}`, issues);
+};
 const optionalImagePosition = (attrs, key, path, issues) => {
 	const value = attrs[key];
 	if (value === void 0 || value === null) return;

package/dist/prosemirror/conversion/fromProseDoc.d.ts

@@ -5,6 +5,14 @@ import { Mark, Node } from "prosemirror-model";
 //#region src/prosemirror/conversion/fromProseDoc.d.ts
 /** Convert a ProseMirror document to the document model. */
 declare function fromProseDoc(pmDoc: Node, baseDocument?: document_d_exports.Document): document_d_exports.Document;
+/**
+ * What a field carrying no stored result reports.
+ *
+ * `serializerFallback` writes the visible page number a save has always given a
+ * result-less PAGE/NUMPAGES field; `authored` reports the result the document
+ * actually holds, so a text read of a story reads the same loaded and unloaded.
+ */
+type EmptyFieldResultMode = "serializerFallback" | "authored";
 /**
  * Convert ProseMirror marks to TextFormatting
  */
@@ -28,6 +36,9 @@ declare function tableCellAttrsToFormatting(attrs: TableCellAttrs): document_d_e
  * Preserves all non-content parts of the original document
  */
 declare function updateDocumentContent(originalDocument: document_d_exports.Document, pmDoc: Node): document_d_exports.Document;
+type ProseDocToBlocksOptions = {
+  emptyFieldResult?: EmptyFieldResultMode;
+};
 /**
  * Convert a ProseMirror document back to an array of `BlockContent` blocks
  * (paragraphs, tables, and block-level content controls).
@@ -35,6 +46,6 @@ declare function updateDocumentContent(originalDocument: document_d_exports.Docu
  * Used for converting edited header/footer PM content back to the document
  * model.
  */
-declare function proseDocToBlocks(pmDoc: Node, baseContent?: document_d_exports.BlockContent[], styles?: NonNullable<document_d_exports.Document["package"]>["styles"]): document_d_exports.BlockContent[];
+declare function proseDocToBlocks(pmDoc: Node, baseContent?: document_d_exports.BlockContent[], styles?: NonNullable<document_d_exports.Document["package"]>["styles"], options?: ProseDocToBlocksOptions): document_d_exports.BlockContent[];
 //#endregion
-export { fromProseDoc, marksToTextFormatting, proseDocToBlocks, standaloneTableCellFromProseMirror, tableAttrsToFormatting, tableCellAttrsToFormatting, tableRowAttrsToFormatting, updateDocumentContent };
+export { EmptyFieldResultMode, ProseDocToBlocksOptions, fromProseDoc, marksToTextFormatting, proseDocToBlocks, standaloneTableCellFromProseMirror, tableAttrsToFormatting, tableCellAttrsToFormatting, tableRowAttrsToFormatting, updateDocumentContent };

package/dist/prosemirror/conversion/fromProseDoc.js

@@ -1,4 +1,4 @@
-import { imageRawXmlFingerprint } from "../../docx/imageRawXml.js";
+import { EDITED_PREVIEW_FINGERPRINT, imageRawXmlFingerprint } from "../../docx/imageRawXml.js";
 import { PROSE_PARAGRAPH_SOURCE_CONTRACT_ATTR, ParagraphPropertySourceValidationError, copyDocumentParagraphPropertySourceContract, copyDocumentParagraphPropertySources, copyParagraphPropertyCapture, copyParagraphPropertySource, decodeTableCellParagraphSourcePayload, getDocumentParagraphPropertySourceContract, getParagraphPropertySource, getParagraphPropertySourceCandidate, getParagraphPropertySourceToken, getParagraphPropertySourceTransferId, getProseDocumentParagraphPropertySourceContract, getProseParagraphPropertySourceToken, isParagraphPropertySourceToken, linkParagraphPropertySourceCandidate, paragraphPropertySourceBelongsToDocument, paragraphPropertySourceTokenMatchesContract, recreateProseNodeWithParagraphPropertySource, restoreTableCellsWithParagraphPropertySources, visitDocumentStoryParagraphs, visitTableCellParagraphPropertySourceBindings } from "../../docx/paragraphPropertySource.js";
 import { visitDocxParagraphs } from "../../docx/paragraphTraversal.js";
 import { ShapeOutlineStyleSchema, narrowEnum } from "../../docx/parserEnums.js";
@@ -429,9 +429,42 @@ function materializeNumberedRefValues(doc) {
 	};
 	return visit(doc);
 }
-function extractBlocks(inputDoc, refResolution = "resolve", styleResolver = null) {
+const SERIALIZER_EMPTY_PAGE_FIELD_RESULT = "1";
+const fieldResultHasExplicitPageBreak = (node) => extractParagraphContent(node, void 0, void 0, /* @__PURE__ */ new Map(), false).filter((content) => content.type === "run" || content.type === "hyperlink").some((content) => {
+	return (content.type === "run" ? [content] : content.children).some((run) => run.type === "run" && run.content.some((runContent) => runContent.type === "break" && runContent.breakType === "page"));
+});
+/**
+* PAGE and NUMPAGES have a stable visible fallback. Other empty fields may
+* intentionally have no result (for example an empty TOC); inventing a space
+* changes their authored result on every save/reopen cycle. A field whose
+* result already carries an explicit page break owns that break's run, so the
+* fallback would displace it.
+*/
+function materializeSerializerFieldFallbacks(doc) {
+	const visit = (node) => {
+		if (node.type.name === "field" || node.type.name === "structuredField") {
+			const attrs = expectFieldAttrs(node);
+			return (attrs.fieldType === "PAGE" || attrs.fieldType === "NUMPAGES") && !attrs.displayText && !fieldResultHasExplicitPageBreak(node) ? recreateProseNodeWithParagraphPropertySource(node, { attrs: {
+				...node.attrs,
+				displayText: SERIALIZER_EMPTY_PAGE_FIELD_RESULT
+			} }) : node;
+		}
+		if (node.childCount === 0) return node;
+		const children = [];
+		let changed = false;
+		node.forEach((child) => {
+			const mappedChild = visit(child);
+			children.push(mappedChild);
+			changed ||= mappedChild !== child;
+		});
+		return changed ? recreateProseNodeWithParagraphPropertySource(node, { content: Fragment.fromArray(children) }) : node;
+	};
+	return visit(doc);
+}
+function extractBlocks(inputDoc, refResolution = "resolve", styleResolver = null, emptyFieldResult = "serializerFallback") {
 	const strippedDoc = stripSuggestedProvenance(inputDoc, styleResolver);
-	const pmDoc = refResolution === "resolve" ? materializeNumberedRefValues(strippedDoc) : strippedDoc;
+	const refResolvedDoc = refResolution === "resolve" ? materializeNumberedRefValues(strippedDoc) : strippedDoc;
+	const pmDoc = emptyFieldResult === "serializerFallback" ? materializeSerializerFieldFallbacks(refResolvedDoc) : refResolvedDoc;
 	const blocks = [];
 	const textBoxAnchorMarkers = /* @__PURE__ */ new Map();
 	const documentCounts = buildDocumentTrackedChangeCounts(pmDoc);
@@ -474,7 +507,7 @@ function extractBlocks(inputDoc, refResolution = "resolve", styleResolver = null
 			pendingPageBreaks = 0;
 		} else if (node.type.name === "blockSdt") {
 			if (pendingPageBreaks > 0 && !appendPendingPageBreaksToPreviousParagraph()) flushPendingPageBreaks();
-			blocks.push(convertPMBlockSdt(node, styleResolver));
+			blocks.push(convertPMBlockSdt(node, styleResolver, emptyFieldResult));
 			previousStandaloneTextBox = null;
 		}
 	});
@@ -482,7 +515,7 @@ function extractBlocks(inputDoc, refResolution = "resolve", styleResolver = null
 	removeUnresolvedTextBoxAnchors(blocks, textBoxAnchorMarkers);
 	return blocks;
 }
-function convertPMBlockSdt(node, styleResolver) {
+function convertPMBlockSdt(node, styleResolver, emptyFieldResult) {
 	const attrs = expectBlockSdtAttrs(node);
 	const properties = { sdtType: attrs.sdtType };
 	if (attrs.alias) properties.alias = attrs.alias;
@@ -500,7 +533,7 @@ function convertPMBlockSdt(node, styleResolver) {
 	if (attrs.rawEndPropertiesXml) properties.rawEndPropertiesXml = attrs.rawEndPropertiesXml;
 	if (attrs.rawSdtChildrenBeforeContent) properties.rawSdtChildrenBeforeContent = attrs.rawSdtChildrenBeforeContent;
 	if (attrs.rawSdtChildrenAfterContent) properties.rawSdtChildrenAfterContent = attrs.rawSdtChildrenAfterContent;
-	const extracted = extractBlocks(node.type.schema.node("doc", null, node.content), "inherit", styleResolver);
+	const extracted = extractBlocks(node.type.schema.node("doc", null, node.content), "inherit", styleResolver, emptyFieldResult);
 	return {
 		type: "blockSdt",
 		properties,
@@ -1691,18 +1724,7 @@ function createFieldFromNode(node, { baseParagraphFormatting, inheritedFormattin
 		paragraphMarkPrecedesStyle: paragraphMarkPrecedesStyle ?? false,
 		styleResolver: styleResolver ?? null
 	}).filter((content) => content.type === "run" || content.type === "hyperlink");
-	const hasExplicitPageBreak = extractedContent.some((content) => {
-		return (content.type === "run" ? [content] : content.children).some((run) => run.type === "run" && run.content.some((runContent) => runContent.type === "break" && runContent.breakType === "page"));
-	});
-	let displayText = attrs.displayText ?? "";
-	if (!displayText && !hasExplicitPageBreak) switch (attrs.fieldType) {
-		case "PAGE":
-			displayText = "1";
-			break;
-		case "NUMPAGES":
-			displayText = "1";
-			break;
-	}
+	const displayText = attrs.displayText ?? "";
 	const displayRun = {
 		type: "run",
 		content: [{
@@ -1822,6 +1844,7 @@ function createImageRun(node) {
 	const imagePosition = imagePositionFromAttrs(attrs.position);
 	if (imagePosition) image.position = imagePosition;
 	if (attrs.layoutInCell !== void 0) image.layoutInCell = attrs.layoutInCell;
+	if (attrs.frameLocks !== void 0) image.frameLocks = { ...attrs.frameLocks };
 	if (attrs.borderWidth && attrs.borderWidth > 0) {
 		const outline = {
 			width: pixelsToEmu(attrs.borderWidth),
@@ -1853,21 +1876,51 @@ function createImageRun(node) {
 		if (cropLeft !== void 0) crop.left = cropLeft;
 		image.crop = crop;
 	}
+	const { paddingTop, paddingRight, paddingBottom, paddingLeft } = attrs;
+	if (paddingTop !== void 0 || paddingRight !== void 0 || paddingBottom !== void 0 || paddingLeft !== void 0) {
+		const padding = {};
+		if (paddingTop !== void 0) padding.top = paddingTop;
+		if (paddingRight !== void 0) padding.right = paddingRight;
+		if (paddingBottom !== void 0) padding.bottom = paddingBottom;
+		if (paddingLeft !== void 0) padding.left = paddingLeft;
+		image.padding = padding;
+	}
 	return {
 		type: "run",
-		content: [attrs._docxRawXmlMode === DRAWING_RAW_XML_MODES.PRESERVE_ONLY ? {
+		content: [drawingFromImageAttrs(image, attrs)]
+	};
+}
+/**
+* Rebuild the `DrawingContent` union member the image node came from.
+*
+* Each branch is listed in full rather than spread over a base object, so a
+* field from one mode cannot leak into another.
+*/
+const drawingFromImageAttrs = (image, attrs) => {
+	const mode = attrs._docxRawXmlMode;
+	switch (mode) {
+		case void 0: return {
+			type: "drawing",
+			image,
+			...attrs._docxRawXml ? { rawXml: attrs._docxRawXml } : {},
+			...attrs._docxRawXml ? { rawImageFingerprint: imageRawXmlFingerprint(image) } : {}
+		};
+		case DRAWING_RAW_XML_MODES.PRESERVE_ONLY: return {
 			type: "drawing",
 			image,
 			rawXml: attrs._docxRawXml ?? panic("Preservation-only ProseMirror image attrs must include raw XML."),
 			rawXmlMode: DRAWING_RAW_XML_MODES.PRESERVE_ONLY
-		} : {
+		};
+		case DRAWING_RAW_XML_MODES.PREVIEW_ONLY: return {
 			type: "drawing",
 			image,
-			...attrs._docxRawXml ? { rawXml: attrs._docxRawXml } : {},
-			...attrs._docxRawXml ? { rawImageFingerprint: imageRawXmlFingerprint(image) } : {}
-		}]
-	};
-}
+			rawXml: attrs._docxRawXml ?? panic("Preview-only ProseMirror image attrs must include raw XML."),
+			rawImageFingerprint: attrs._docxRawImageFingerprint === void 0 ? EDITED_PREVIEW_FINGERPRINT : imageRawXmlFingerprint(image),
+			rawXmlMode: DRAWING_RAW_XML_MODES.PREVIEW_ONLY
+		};
+		default: return mode;
+	}
+};
 /**
 * Create a Run from a ProseMirror shape node
 */
@@ -2973,8 +3026,8 @@ function updateDocumentContent(originalDocument, pmDoc) {
 * Used for converting edited header/footer PM content back to the document
 * model.
 */
-function proseDocToBlocks(pmDoc, baseContent, styles) {
-	const blocks = extractBlocks(pmDoc, "resolve", styles ? createStyleEngine(styles) : null);
+function proseDocToBlocks(pmDoc, baseContent, styles, options) {
+	const blocks = extractBlocks(pmDoc, "resolve", styles ? createStyleEngine(styles) : null, options?.emptyFieldResult ?? "serializerFallback");
 	const linkedSources = restoreLinkedParagraphPropertySources(blocks);
 	if (baseContent) restoreParagraphPropertySources(blocks, baseContent, linkedSources.targets, linkedSources.sources);
 	return blocks;

package/dist/prosemirror/conversion/index.d.ts

@@ -1,4 +1,4 @@
-import { fromProseDoc, proseDocToBlocks, updateDocumentContent } from "./fromProseDoc.js";
+import { EmptyFieldResultMode, ProseDocToBlocksOptions, fromProseDoc, proseDocToBlocks, updateDocumentContent } from "./fromProseDoc.js";
 import { ToProseDocOptions, createEmptyDoc, headerFooterToProseDoc, toProseDoc } from "./toProseDoc.js";
 import { ProseMirrorDocumentValidationIssue, ValidateProseMirrorDocumentResult, assertValidProseMirrorDocument, formatProseMirrorDocumentIssues, validateProseMirrorDocument } from "../validation.js";
-export { type ProseMirrorDocumentValidationIssue, type ToProseDocOptions, type ValidateProseMirrorDocumentResult, assertValidProseMirrorDocument, createEmptyDoc, formatProseMirrorDocumentIssues, fromProseDoc, headerFooterToProseDoc, proseDocToBlocks, toProseDoc, updateDocumentContent, validateProseMirrorDocument };
+export { type EmptyFieldResultMode, type ProseDocToBlocksOptions, type ProseMirrorDocumentValidationIssue, type ToProseDocOptions, type ValidateProseMirrorDocumentResult, assertValidProseMirrorDocument, createEmptyDoc, formatProseMirrorDocumentIssues, fromProseDoc, headerFooterToProseDoc, proseDocToBlocks, toProseDoc, updateDocumentContent, validateProseMirrorDocument };

package/dist/prosemirror/conversion/toProseDoc.js

@@ -24,6 +24,7 @@ import { resolveEffectiveTableCellFormatting } from "./effectiveTableCellFormatt
 import { shadingToRunShadingAttrs } from "./runShadingMark.js";
 import { sdtAttrsFromProperties } from "./sdtAttrs.js";
 import { TaggedError, panic } from "better-result";
+import { DRAWING_RAW_XML_MODES } from "@stll/docx-core/model";
 //#region src/prosemirror/conversion/toProseDoc.ts
 /** DOCX content that cannot be preserved by the editable ProseMirror model. */
 var UnsupportedDocxToProseMirrorConversionError = class extends TaggedError("UnsupportedDocxToProseMirrorConversionError") {};
@@ -1588,7 +1589,8 @@ function convertRunContent(content, marks, formatting, textBoxAnchors) {
 		case "drawing": return [withRunBoundaryMarks(convertImage({
 			image: content.image,
 			rawXml: content.rawXml,
-			rawXmlMode: content.rawXmlMode
+			rawXmlMode: content.rawXmlMode,
+			rawImageFingerprint: content.rawXmlMode === DRAWING_RAW_XML_MODES.PRESERVE_ONLY ? void 0 : content.rawImageFingerprint
 		}), marks)];
 		case "shape": {
 			const shp = content.shape;
@@ -1628,7 +1630,7 @@ function withRunBoundaryMarks(node, marks) {
 	if (!marks.some(({ type }) => type.name === "hyperlink" || type.name === "pageBreakRunOwner")) return node;
 	return node.mark(marks);
 }
-function convertImage({ image, rawXml, rawXmlMode }) {
+function convertImage({ image, rawXml, rawXmlMode, rawImageFingerprint }) {
 	const imageSize = image.size;
 	const widthPx = imageSize?.width ? emuToPixels(imageSize.width) : void 0;
 	const heightPx = imageSize?.height ? emuToPixels(imageSize.height) : void 0;
@@ -1720,8 +1722,13 @@ function convertImage({ image, rawXml, rawXmlMode }) {
 		cropRight: image.crop?.right,
 		cropBottom: image.crop?.bottom,
 		cropLeft: image.crop?.left,
+		paddingTop: image.padding?.top,
+		paddingRight: image.padding?.right,
+		paddingBottom: image.padding?.bottom,
+		paddingLeft: image.padding?.left,
 		position,
 		layoutInCell: image.layoutInCell,
+		frameLocks: image.frameLocks ? { ...image.frameLocks } : void 0,
 		borderWidth,
 		borderColor,
 		borderStyle,
@@ -1730,6 +1737,7 @@ function convertImage({ image, rawXml, rawXmlMode }) {
 		hlinkRId: image.hlinkRId,
 		_docxRawXml: rawXml,
 		_docxRawXmlMode: rawXmlMode,
+		_docxRawImageFingerprint: rawImageFingerprint,
 		_docxObjectPreview: rawXml !== void 0 && /<(?:[A-Za-z_][\w.-]*:)?object(?:\s|>)/u.test(rawXml)
 	});
 }

package/dist/prosemirror/extensions/nodes/ImageExtension.js

@@ -33,8 +33,13 @@ const ImageExtension = createNodeExtension({
 			cropRight: { default: null },
 			cropBottom: { default: null },
 			cropLeft: { default: null },
+			paddingTop: { default: null },
+			paddingRight: { default: null },
+			paddingBottom: { default: null },
+			paddingLeft: { default: null },
 			position: { default: null },
 			layoutInCell: { default: null },
+			frameLocks: { default: null },
 			borderWidth: { default: null },
 			borderColor: { default: null },
 			borderStyle: { default: null },
@@ -43,6 +48,7 @@ const ImageExtension = createNodeExtension({
 			hlinkRId: { default: null },
 			_docxRawXml: { default: null },
 			_docxRawXmlMode: { default: null },
+			_docxRawImageFingerprint: { default: null },
 			_docxObjectPreview: { default: null }
 		},
 		parseDOM: [{