@stll/folio-core 0.44.0 → 0.46.0

package/dist/docx/fieldState.js

@@ -0,0 +1,53 @@
+import { parseOnOffAttribute } from "./xmlParser.js";
+//#region src/docx/fieldState.ts
+/**
+* `@w:fldLock` and `@w:dirty`, the two `ST_OnOff` attributes every field form
+* carries.
+*
+* A simple field states them on `<w:fldSimple>`; a complex field states them on
+* the `<w:fldChar w:fldCharType="begin"/>` that opens it, and folio hoists them
+* from there onto the assembled `ComplexField`. Neither attribute has an XSD
+* default, so a field states one of three things about each: nothing, an
+* explicit off, an explicit on. `w:dirty="0"` on a field inside a `TOC` result
+* is the case that matters: it says "do not recompute this", which is not what
+* an absent attribute says.
+*
+* Three readers and three writers had drifted into the same `=== true` /
+* truthiness collapse, so both directions live here instead.
+*/
+/** Read both attributes off a `w:fldSimple` or `w:fldChar`, keeping an explicit off. */
+const parseFieldState = (element) => {
+	const state = {};
+	const fldLock = parseOnOffAttribute(element, "w", "fldLock");
+	if (fldLock !== void 0) state.fldLock = fldLock;
+	const dirty = parseOnOffAttribute(element, "w", "dirty");
+	if (dirty !== void 0) state.dirty = dirty;
+	return state;
+};
+/**
+* The stated flags of a field, without the rest of it.
+*
+* The complex-field assembly carries the begin `w:fldChar`'s state across the
+* runs between `begin` and `end`, and this is the one place that knows which
+* fields that state is made of.
+*/
+const fieldStateOf = ({ fldLock, dirty }) => {
+	const state = {};
+	if (fldLock !== void 0) state.fldLock = fldLock;
+	if (dirty !== void 0) state.dirty = dirty;
+	return state;
+};
+/**
+* The attributes to write for a field's stated flags, in schema order.
+*
+* `1`/`0` is what Word writes and what the table, section and border
+* serializers write.
+*/
+const fieldStateAttributes = ({ fldLock, dirty }) => {
+	const attrs = [];
+	if (fldLock !== void 0) attrs.push(`w:fldLock="${fldLock ? "1" : "0"}"`);
+	if (dirty !== void 0) attrs.push(`w:dirty="${dirty ? "1" : "0"}"`);
+	return attrs;
+};
+//#endregion
+export { fieldStateAttributes, fieldStateOf, parseFieldState };

package/dist/docx/footnoteParser.d.ts

@@ -1,7 +1,7 @@
 import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
-import { StyleMap } from "./styleParser.js";
 import { ParseContext } from "./parseContext.js";
+import { StyleMap } from "./styleParser.js";
 import { parseEndnoteProperties, parseFootnoteProperties } from "./notePropertiesParser.js";
 //#region src/docx/footnoteParser.d.ts
 /**

package/dist/docx/graphicFrameLocks.d.ts

@@ -12,11 +12,23 @@ declare const GRAPHIC_FRAME_LOCK_KEYS: ("noGrp" | "noDrilldown" | "noSelect" | "
  */
 declare const parseGraphicFrameLocks: (parent: XmlElement) => document_d_exports.ImageFrameLocks | undefined;
 /**
- * Emit the whole `wp:cNvGraphicFramePr` element for regenerated DrawingML.
+ * The locks folio gives a picture it creates itself, at the insert that creates
+ * it: Word writes `noChangeAspect="1"` on a picture inserted through its own
+ * UI, and an inserted picture should behave the same in both.
  *
- * Absent locks mean no authored frame was ever parsed (a Folio-created
- * picture), which keeps the historical `noChangeAspect="1"`.
+ * It lives here because it is a fact about this element, and it is applied at
+ * construction rather than at serialization, where "the author wrote no frame"
+ * and "folio made this picture" are the same `undefined`.
+ */
+declare const FOLIO_INSERTED_PICTURE_FRAME_LOCKS: document_d_exports.ImageFrameLocks;
+/**
+ * Emit `wp:cNvGraphicFramePr` for regenerated DrawingML, or nothing.
+ *
+ * Absent locks are the author's silence, and silence is written back as
+ * silence: a frame the source never carried is not invented on the rebuild
+ * path, where it would appear on every edited document and on none of the
+ * replayed ones.
  */
 declare const serializeGraphicFrameLocks: (locks: document_d_exports.ImageFrameLocks | undefined) => string;
 //#endregion
-export { GRAPHIC_FRAME_LOCK_KEYS, parseGraphicFrameLocks, serializeGraphicFrameLocks };
+export { FOLIO_INSERTED_PICTURE_FRAME_LOCKS, GRAPHIC_FRAME_LOCK_KEYS, parseGraphicFrameLocks, serializeGraphicFrameLocks };

package/dist/docx/graphicFrameLocks.js

@@ -38,18 +38,31 @@ const parseGraphicFrameLocks = (parent) => {
 	return present ? locks : void 0;
 };
 /**
-* Emit the whole `wp:cNvGraphicFramePr` element for regenerated DrawingML.
+* The locks folio gives a picture it creates itself, at the insert that creates
+* it: Word writes `noChangeAspect="1"` on a picture inserted through its own
+* UI, and an inserted picture should behave the same in both.
 *
-* Absent locks mean no authored frame was ever parsed (a Folio-created
-* picture), which keeps the historical `noChangeAspect="1"`.
+* It lives here because it is a fact about this element, and it is applied at
+* construction rather than at serialization, where "the author wrote no frame"
+* and "folio made this picture" are the same `undefined`.
+*/
+const FOLIO_INSERTED_PICTURE_FRAME_LOCKS = { noChangeAspect: true };
+/**
+* Emit `wp:cNvGraphicFramePr` for regenerated DrawingML, or nothing.
+*
+* Absent locks are the author's silence, and silence is written back as
+* silence: a frame the source never carried is not invented on the rebuild
+* path, where it would appear on every edited document and on none of the
+* replayed ones.
 */
 const serializeGraphicFrameLocks = (locks) => {
-	const attrs = locks ? GRAPHIC_FRAME_LOCK_KEYS.flatMap((key) => {
+	if (!locks) return "";
+	const attrs = 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 };
+export { FOLIO_INSERTED_PICTURE_FRAME_LOCKS, GRAPHIC_FRAME_LOCK_KEYS, parseGraphicFrameLocks, serializeGraphicFrameLocks };

package/dist/docx/groupDrawingParser.js

@@ -1,6 +1,7 @@
 import { emuToPixels } from "../utils/units.js";
 import { parseImage, resolveImageData } from "./imageParser.js";
 import { findAllDeep, findChildByLocalName, findChildrenByLocalName, getAttribute, getChildElements, getLocalName, getTextContent, parseNumericAttribute } from "./xmlParser.js";
+import { escapeXmlAttribute, escapeXmlText } from "@stll/docx-core";
 //#region src/docx/groupDrawingParser.ts
 const HEX_COLOR = /^[0-9A-Fa-f]{6}$/u;
 const DEFAULT_TEXT_COLOR = "000000";
@@ -12,7 +13,6 @@ const CROP_SCALE = 1e5;
 const MAX_PATH_COMMANDS = 1e4;
 const MAX_TEXT_CHARACTERS = 2e4;
 const MAX_SVG_CHARACTERS = 1e6;
-const escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
 const numericAttr = (element, name) => {
 	const direct = parseNumericAttribute(element, null, name);
 	if (direct !== void 0) return direct;
@@ -108,7 +108,7 @@ const renderTextBox = (wsp) => {
 	const color = colorFrom(findAllDeep(wsp, "w", "color").at(0) ?? null, DEFAULT_TEXT_COLOR);
 	const fontSize = halfPoints * HALF_POINT_TO_EMU;
 	const maxCharacters = Math.max(1, Math.floor(width / (fontSize * .38)));
-	const lines = paragraphs.flatMap((paragraph) => wrapLine(getTextContent(paragraph).slice(0, MAX_TEXT_CHARACTERS), maxCharacters)).map(escapeXml);
+	const lines = paragraphs.flatMap((paragraph) => wrapLine(getTextContent(paragraph).slice(0, MAX_TEXT_CHARACTERS), maxCharacters)).map(escapeXmlText);
 	if (lines.length === 0) return "";
 	const lineHeight = fontSize * 1.15;
 	const svgFontSize = 1e3;
@@ -131,7 +131,7 @@ const renderPicture = (picture, index, rels, media) => {
 	const visibleWidth = 1 - left - right;
 	const visibleHeight = 1 - top - bottom;
 	if (visibleWidth <= 0 || visibleHeight <= 0) return "";
-	const image = `<image x="${x - width * left / visibleWidth}" y="${y - height * top / visibleHeight}" width="${width / visibleWidth}" height="${height / visibleHeight}" href="${escapeXml(src)}" preserveAspectRatio="none"/>`;
+	const image = `<image x="${x - width * left / visibleWidth}" y="${y - height * top / visibleHeight}" width="${width / visibleWidth}" height="${height / visibleHeight}" href="${escapeXmlAttribute(src)}" preserveAspectRatio="none"/>`;
 	if (left === 0 && top === 0 && right === 0 && bottom === 0) return image;
 	const clipId = `group-picture-${index}`;
 	return `<defs><clipPath id="${clipId}"><rect x="${x}" y="${y}" width="${width}" height="${height}"/></clipPath></defs><g clip-path="url(#${clipId})">${image}</g>`;

package/dist/docx/headerFooterParser.js

@@ -155,7 +155,7 @@ function getHeaderFooterText(hf) {
 function isEmptyHeaderFooter(hf) {
 	if (hf.content.length === 0) return true;
 	for (const item of hf.content) {
-		if (item.type === "table") return false;
+		if (item.type !== "paragraph") return false;
 		if (item.content.length > 0) for (const content of item.content) {
 			if (content.type !== "run") return false;
 			for (const rc of content.content) {

package/dist/docx/headerFooterReferenceNormalization.js

@@ -38,6 +38,7 @@ const normalizeHeaderFooterReferences = ({ documentBody, headers, footers }) =>
 			normalizeTable(block);
 			return;
 		}
+		if (block.type === "preservedBlock") return;
 		normalizeBlocks(block.content);
 	};
 	const normalizeBlocks = (blocks) => {

package/dist/docx/hyperlinkParser.d.ts

@@ -1,6 +1,7 @@
 import { document_d_exports } from "../types/document.js";
-import { StyleMap } from "./styleParser.js";
 import { XmlElement } from "./xmlParser.js";
+import { StyleMap } from "./styleParser.js";
+import { ChildHandlers } from "./containerChildren.js";
 //#region src/docx/hyperlinkParser.d.ts
 /**
  * Parse a hyperlink element (w:hyperlink)
@@ -16,14 +17,32 @@ import { XmlElement } from "./xmlParser.js";
  * @returns Parsed Hyperlink object
  */
 declare function parseHyperlink(node: XmlElement, rels: document_d_exports.RelationshipMap | null, styles?: StyleMap | null, theme?: document_d_exports.Theme | null, media?: Map<string, document_d_exports.MediaFile> | null, rootXmlns?: Record<string, string>): document_d_exports.Hyperlink;
+/** What {@link hyperlinkChildHandlers} needs to read one child of a link. */
+type HyperlinkChildContext = {
+  /** Where a parsed or captured child lands, in source order. */
+  push: (child: document_d_exports.Hyperlink["children"][number]) => void;
+  styles: StyleMap | null;
+  theme: document_d_exports.Theme | null;
+  rels: document_d_exports.RelationshipMap | null;
+  media: Map<string, document_d_exports.MediaFile> | null;
+  inScopeXmlns: Record<string, string>;
+};
 /**
- * One `w:hyperlink` child, or `null` for markup the model does not carry.
- *
- * Exposed so a caller that has to segment a hyperlink — one holding revision
- * wrappers, which the model nests the other way round — parses its plain
- * children exactly as {@link parseHyperlink} does.
+ * What a `w:hyperlink` does with every child its content model declares.
+ *
+ * `CT_Hyperlink` is `EG_PContent`, so a link may hold a permission range, a
+ * proofing error, a nested field or one of the eight custom-XML revision
+ * ranges between its runs; folio models three of the thirty-two names and
+ * used to drop the other twenty-nine off the end of a `switch`.
+ *
+ * Two callers read this one map: {@link parseHyperlink}, and the paragraph
+ * parser's revision-segmenting walk, which overrides the four
+ * `CT_RunTrackChange` wrappers because OOXML nests a revision inside a link
+ * and the model nests the link inside the revision. Everything else is
+ * decided here once, so a child one caller starts recognising is recognised
+ * by both rather than by whichever list somebody remembered to update.
  */
-declare function parseHyperlinkChild(node: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, inScopeXmlns: Record<string, string>): document_d_exports.Hyperlink["children"][number] | null;
+declare const hyperlinkChildHandlers: ({ push, styles, theme, rels, media, inScopeXmlns }: HyperlinkChildContext) => ChildHandlers<"w:hyperlink">;
 /**
  * Get the display text of a hyperlink
  *
@@ -112,4 +131,4 @@ declare function createExternalHyperlink(url: string, children: document_d_expor
   target?: string;
 }): document_d_exports.Hyperlink;
 //#endregion
-export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, isExternalLink, isInternalLink, parseHyperlink, parseHyperlinkChild, resolveHyperlinkUrl };
+export { HyperlinkChildContext, createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, hyperlinkChildHandlers, isExternalLink, isInternalLink, parseHyperlink, resolveHyperlinkUrl };

package/dist/docx/hyperlinkParser.js

@@ -1,7 +1,9 @@
-import { sanitizeExternalUrl, sanitizeLinkTarget } from "../utils/urlSecurity.js";
+import { sanitizeExternalUrl } from "../utils/urlSecurity.js";
+import { CAPTURE, dispatchChildren, withPreservedChildren } from "./containerChildren.js";
+import { preserveInlineChild, preservedInlineCapture } from "./preservedRunContent.js";
 import { RELATIONSHIP_TYPES, resolveRelationshipIdOfType } from "./relsParser.js";
 import { parseRun } from "./runParser.js";
-import { getAttribute, getChildElements, getLocalName, mergeXmlnsDeclarations, parseNumericAttribute, parseOnOffAttribute } from "./xmlParser.js";
+import { getAttribute, mergeXmlnsDeclarations, parseNumericAttribute, parseOnOffAttribute } from "./xmlParser.js";
 //#region src/docx/hyperlinkParser.ts
 /**
 * Parse bookmark start (w:bookmarkStart)
@@ -63,32 +65,88 @@ function parseHyperlink(node, rels, styles = null, theme = null, media = null, r
 	const tooltip = getAttribute(node, "w", "tooltip");
 	if (tooltip) hyperlink.tooltip = tooltip;
 	const tgtFrame = getAttribute(node, "w", "tgtFrame");
-	if (tgtFrame) hyperlink.target = sanitizeLinkTarget(tgtFrame);
+	if (tgtFrame) hyperlink.target = tgtFrame;
 	if (parseOnOffAttribute(node, "w", "history") === true) hyperlink.history = true;
 	const docLocation = getAttribute(node, "w", "docLocation");
 	if (docLocation) hyperlink.docLocation = docLocation;
 	const inScopeXmlns = mergeXmlnsDeclarations(rootXmlns, node);
-	for (const child of getChildElements(node)) {
-		const parsed = parseHyperlinkChild(child, styles, theme, rels, media, inScopeXmlns);
-		if (parsed) hyperlink.children.push(parsed);
-	}
+	const children = [];
+	hyperlink.children = withPreservedChildren(children, dispatchChildren({
+		element: node,
+		container: "w:hyperlink",
+		modelledCount: () => children.length,
+		handlers: hyperlinkChildHandlers({
+			push: (child) => {
+				children.push(child);
+			},
+			styles,
+			theme,
+			rels,
+			media,
+			inScopeXmlns
+		})
+	}), preservedInlineCapture);
 	return hyperlink;
 }
 /**
-* One `w:hyperlink` child, or `null` for markup the model does not carry.
+* What a `w:hyperlink` does with every child its content model declares.
+*
+* `CT_Hyperlink` is `EG_PContent`, so a link may hold a permission range, a
+* proofing error, a nested field or one of the eight custom-XML revision
+* ranges between its runs; folio models three of the thirty-two names and
+* used to drop the other twenty-nine off the end of a `switch`.
 *
-* Exposed so a caller that has to segment a hyperlink — one holding revision
-* wrappers, which the model nests the other way round — parses its plain
-* children exactly as {@link parseHyperlink} does.
+* Two callers read this one map: {@link parseHyperlink}, and the paragraph
+* parser's revision-segmenting walk, which overrides the four
+* `CT_RunTrackChange` wrappers because OOXML nests a revision inside a link
+* and the model nests the link inside the revision. Everything else is
+* decided here once, so a child one caller starts recognising is recognised
+* by both rather than by whichever list somebody remembered to update.
 */
-function parseHyperlinkChild(node, styles, theme, rels, media, inScopeXmlns) {
-	switch (getLocalName(node.name)) {
-		case "r": return parseRun(node, styles, theme, rels, media, inScopeXmlns);
-		case "bookmarkStart": return parseBookmarkStart(node);
-		case "bookmarkEnd": return parseBookmarkEnd(node);
-		default: return null;
-	}
-}
+const hyperlinkChildHandlers = ({ push, styles, theme, rels, media, inScopeXmlns }) => ({
+	r: (child) => {
+		push(parseRun(child, styles, theme, rels, media, inScopeXmlns));
+	},
+	bookmarkStart: (child) => {
+		push(parseBookmarkStart(child));
+	},
+	bookmarkEnd: (child) => {
+		push(parseBookmarkEnd(child));
+	},
+	customXml: (child) => {
+		push(preserveInlineChild(child));
+	},
+	smartTag: (child) => {
+		push(preserveInlineChild(child));
+	},
+	del: CAPTURE,
+	ins: CAPTURE,
+	moveFrom: CAPTURE,
+	moveTo: CAPTURE,
+	bdo: CAPTURE,
+	commentRangeEnd: CAPTURE,
+	commentRangeStart: CAPTURE,
+	customXmlDelRangeEnd: CAPTURE,
+	customXmlDelRangeStart: CAPTURE,
+	customXmlInsRangeEnd: CAPTURE,
+	customXmlInsRangeStart: CAPTURE,
+	customXmlMoveFromRangeEnd: CAPTURE,
+	customXmlMoveFromRangeStart: CAPTURE,
+	customXmlMoveToRangeEnd: CAPTURE,
+	customXmlMoveToRangeStart: CAPTURE,
+	dir: CAPTURE,
+	fldSimple: CAPTURE,
+	hyperlink: CAPTURE,
+	moveFromRangeEnd: CAPTURE,
+	moveFromRangeStart: CAPTURE,
+	moveToRangeEnd: CAPTURE,
+	moveToRangeStart: CAPTURE,
+	permEnd: CAPTURE,
+	permStart: CAPTURE,
+	proofErr: CAPTURE,
+	sdt: CAPTURE,
+	subDoc: CAPTURE
+});
 /**
 * Get the display text of a hyperlink
 *
@@ -219,4 +277,4 @@ function createExternalHyperlink(url, children, options) {
 	};
 }
 //#endregion
-export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, isExternalLink, isInternalLink, parseHyperlink, parseHyperlinkChild, resolveHyperlinkUrl };
+export { createExternalHyperlink, createInternalHyperlink, getHyperlinkRuns, getHyperlinkText, getHyperlinkUrl, hasContent, hyperlinkChildHandlers, isExternalLink, isInternalLink, parseHyperlink, resolveHyperlinkUrl };

package/dist/docx/imageParser.d.ts

@@ -1,6 +1,14 @@
 import { document_d_exports } from "../types/document.js";
 import { XmlElement } from "./xmlParser.js";
 //#region src/docx/imageParser.d.ts
+/**
+ * The `a:ext` uri under which Word records that a drawing is decorative. The
+ * extension holds `<adec:decorative val="…"/>`; `CT_NonVisualDrawingProps` has
+ * no `@decorative` attribute for it to be written as.
+ */
+declare const DECORATIVE_EXTENSION_URI = "{C183D7F6-B498-43B3-948B-1728B52AA6E4}";
+/** The namespace the decorative extension's element is bound to. */
+declare const DECORATIVE_NAMESPACE = "http://schemas.microsoft.com/office/drawing/2017/decorative";
 /**
  * Resolve image data from relationships and media map
  *
@@ -89,4 +97,4 @@ declare function getWrapDistancesPx(image: document_d_exports.Image): {
  */
 declare function needsTextWrapping(image: document_d_exports.Image): boolean;
 //#endregion
-export { getImageDimensionsPx, getImageHeightPx, getImageWidthPx, getWrapDistancesPx, hasAltText, isBehindText, isDecorativeImage, isFloatingImage, isInFrontOfText, isInlineImage, needsTextWrapping, parseDrawing, parseImage, resolveImageData };
+export { DECORATIVE_EXTENSION_URI, DECORATIVE_NAMESPACE, getImageDimensionsPx, getImageHeightPx, getImageWidthPx, getWrapDistancesPx, hasAltText, isBehindText, isDecorativeImage, isFloatingImage, isInFrontOfText, isInlineImage, needsTextWrapping, parseDrawing, parseImage, resolveImageData };

package/dist/docx/imageParser.js

@@ -1,12 +1,18 @@
+import { normalizeImageLuminancePercent } from "../utils/imageLuminance.js";
 import { sanitizeImageSrc } from "../utils/sanitizeImageSrc.js";
 import { emuToPixels } from "../utils/units.js";
 import { sanitizeExternalUrl } from "../utils/urlSecurity.js";
 import { WRAP_ELEMENT_NAMES, parseAnchorBehindDoc, parsePositionH, parsePositionV, parseWrapElement } from "./drawingUtils.js";
 import { parseGraphicFrameLocks } from "./graphicFrameLocks.js";
+import { parseNonVisualDrawingNames } from "./nonVisualDrawingProps.js";
 import { RELATIONSHIP_TYPES, resolveRelationshipIdOfType } from "./relsParser.js";
 import { isTextBoxDrawing } from "./textBoxParser.js";
-import { findByFullName, findChild, getAttribute, getChildElements, parseNumericAttribute, parseOnOffValue } from "./xmlParser.js";
+import { percentageSpelling } from "./transitionalSpelling.js";
+import { captureVerbatimXml } from "./verbatimCapture.js";
+import { findByFullName, findChild, findChildByNamespaceUri, findChildrenByNamespaceUri, getAttribute, getChildElements, getLocalName, getNamespaceUri, parseNumericAttribute, parseOnOffAttribute, parseOnOffValue } from "./xmlParser.js";
 //#region src/docx/imageParser.ts
+const DRAWINGML_MAIN_NAMESPACE_URIS = /* @__PURE__ */ new Set(["http://schemas.openxmlformats.org/drawingml/2006/main", "http://purl.oclc.org/ooxml/drawingml/main"]);
+const FIXED_PERCENTAGE = /^-?\d+$/u;
 /**
 * Convert rotation value (1/60000 of a degree) to degrees
 *
@@ -14,7 +20,7 @@ import { findByFullName, findChild, getAttribute, getChildElements, parseNumeric
 * @returns Rotation in degrees
 */
 function rotToDegrees(rot) {
-	if (!rot) return;
+	if (rot === null || rot === void 0) return;
 	const val = Number.parseInt(rot, 10);
 	if (Number.isNaN(val)) return;
 	return val / 6e4;
@@ -64,6 +70,47 @@ function parseEffectExtent(effectExtent) {
 	};
 }
 /**
+* The `a:ext` uri under which Word records that a drawing is decorative. The
+* extension holds `<adec:decorative val="…"/>`; `CT_NonVisualDrawingProps` has
+* no `@decorative` attribute for it to be written as.
+*/
+const DECORATIVE_EXTENSION_URI = "{C183D7F6-B498-43B3-948B-1728B52AA6E4}";
+/** The namespace the decorative extension's element is bound to. */
+const DECORATIVE_NAMESPACE = "http://schemas.microsoft.com/office/drawing/2017/decorative";
+/**
+* `wp:docPr`'s extension list is DrawingML's (`a:extLst` holding `a:ext`), in
+* the Transitional or the Strict namespace. Matching on the local name alone
+* would take an `extLst` some other namespace owns and replay its children
+* inside an `a:extLst`, which is a different container than the source wrote.
+*/
+const DRAWINGML_NAMESPACE_URIS = /* @__PURE__ */ new Set(["http://schemas.openxmlformats.org/drawingml/2006/main", "http://purl.oclc.org/ooxml/drawingml/main"]);
+/**
+* Read the `wp:docPr` extension list.
+*
+* Only the decorative extension is modeled. The rest — a creation id, a
+* local-DPI hint, whatever a later Word writes — are captured as they were
+* written so the save path can put them back: an extension folio drops is a
+* fact the document had and no longer does.
+*/
+const parseDocPropsExtensions = (docPr) => {
+	const extLst = findChildByNamespaceUri(docPr, DRAWINGML_NAMESPACE_URIS, "extLst");
+	if (!extLst) return { other: [] };
+	const result = { other: [] };
+	for (const ext of findChildrenByNamespaceUri(extLst, DRAWINGML_NAMESPACE_URIS, "ext")) {
+		if (getAttribute(ext, null, "uri")?.toUpperCase() !== "{C183D7F6-B498-43B3-948B-1728B52AA6E4}") {
+			result.other.push(captureVerbatimXml(ext));
+			continue;
+		}
+		const flag = getChildElements(ext).find((child) => getLocalName(child.name) === "decorative" && getNamespaceUri(child) === "http://schemas.microsoft.com/office/drawing/2017/decorative");
+		if (!flag) {
+			result.other.push(captureVerbatimXml(ext));
+			continue;
+		}
+		result.decorative = parseOnOffValue(getAttribute(flag, null, "val")) ?? true;
+	}
+	return result;
+};
+/**
 * Parse document properties (wp:docPr)
 *
 * @param docPr - wp:docPr element
@@ -72,18 +119,17 @@ function parseEffectExtent(effectExtent) {
 function parseDocProps(docPr) {
 	if (!docPr) return {};
 	const id = getAttribute(docPr, null, "id");
-	const name = getAttribute(docPr, null, "name");
-	const descr = getAttribute(docPr, null, "descr");
-	const title = getAttribute(docPr, null, "title");
-	const decorative = parseOnOffValue(getAttribute(docPr, null, "decorative")) === true;
+	const names = parseNonVisualDrawingNames(docPr);
+	const hidden = parseOnOffAttribute(docPr, null, "hidden");
+	const { decorative, other: docPrExtensions } = parseDocPropsExtensions(docPr);
 	const hlinkClickEl = findChild(docPr, "a", "hlinkClick");
 	const hlinkRId = hlinkClickEl ? getAttribute(hlinkClickEl, "r", "id") : null;
 	return {
 		...id != null ? { id } : {},
-		...name != null ? { name } : {},
-		...descr != null ? { alt: descr } : {},
-		...title != null ? { title } : {},
-		...decorative ? { decorative } : {},
+		...names,
+		...decorative === void 0 ? {} : { decorative },
+		...hidden === void 0 ? {} : { hidden },
+		...docPrExtensions.length > 0 ? { docPrExtensions } : {},
 		...hlinkRId != null ? { hlinkRId } : {}
 	};
 }
@@ -92,15 +138,14 @@ function parseDocProps(docPr) {
 */
 function parseTransform(xfrm) {
 	if (!xfrm) return;
-	const rot = getAttribute(xfrm, null, "rot");
-	const flipH = parseOnOffValue(getAttribute(xfrm, null, "flipH")) === true;
-	const flipV = parseOnOffValue(getAttribute(xfrm, null, "flipV")) === true;
-	const rotation = rotToDegrees(rot);
-	if (rotation === void 0 && !flipH && !flipV) return;
+	const flipH = parseOnOffValue(getAttribute(xfrm, null, "flipH"));
+	const flipV = parseOnOffValue(getAttribute(xfrm, null, "flipV"));
+	const rotation = rotToDegrees(getAttribute(xfrm, null, "rot"));
+	if (rotation === void 0 && flipH === void 0 && flipV === void 0) return;
 	const transform = {};
 	if (rotation !== void 0) transform.rotation = rotation;
-	if (flipH) transform.flipH = true;
-	if (flipV) transform.flipV = true;
+	if (flipH !== void 0) transform.flipH = flipH;
+	if (flipV !== void 0) transform.flipV = flipV;
 	return transform;
 }
 /**
@@ -177,6 +222,24 @@ function parseImageOpacity(blip) {
 	if (amt === void 0 || amt >= 1e5) return;
 	return Math.max(0, amt / 1e5);
 }
+const parseLuminancePercent = (luminance, attribute) => {
+	const raw = getAttribute(luminance, null, attribute);
+	if (raw === null) return;
+	const percent = percentageSpelling(raw) ?? (FIXED_PERCENTAGE.test(raw.trim()) ? Number(raw) / 1e3 : void 0);
+	return percent === void 0 || !Number.isFinite(percent) ? void 0 : normalizeImageLuminancePercent(percent);
+};
+/** Parse DrawingML `a:lum` into signed percentage values, preserving explicit zeroes. */
+function parseImageLuminance(blip) {
+	const luminance = findChildByNamespaceUri(blip, DRAWINGML_MAIN_NAMESPACE_URIS, "lum");
+	if (!luminance) return;
+	const brightness = parseLuminancePercent(luminance, "bright");
+	const contrast = parseLuminancePercent(luminance, "contrast");
+	if (brightness === void 0 && contrast === void 0) return;
+	return {
+		...brightness === void 0 ? {} : { brightness },
+		...contrast === void 0 ? {} : { contrast }
+	};
+}
 /**
 * Extract rId from a:blip element.
 *
@@ -308,6 +371,7 @@ function parseInline(inlineEl, rels, media) {
 	const rId = extractBlipRId(blip);
 	const crop = parseImageCrop(blipFill);
 	const opacity = parseImageOpacity(blip);
+	const effects = parseImageLuminance(blip);
 	const imageData = resolveImageData(rId, rels, media);
 	const transform = parseTransform(findPictureTransform(inlineEl));
 	const distT = parseNumericAttribute(inlineEl, null, "distT") ?? void 0;
@@ -329,7 +393,9 @@ function parseInline(inlineEl, rels, media) {
 	if (props.name !== void 0) image.docPrName = props.name;
 	if (props.alt !== void 0) image.alt = props.alt;
 	if (props.title !== void 0) image.title = props.title;
-	if (props.decorative) image.decorative = true;
+	if (props.decorative !== void 0) image.decorative = props.decorative;
+	if (props.hidden !== void 0) image.hidden = props.hidden;
+	if (props.docPrExtensions !== void 0) image.docPrExtensions = props.docPrExtensions;
 	const safeSrc = sanitizeImageSrc(imageData.src);
 	if (safeSrc) image.src = safeSrc;
 	if (imageData.mimeType) image.mimeType = imageData.mimeType;
@@ -338,6 +404,7 @@ function parseInline(inlineEl, rels, media) {
 	if (transform) image.transform = transform;
 	if (crop) image.crop = crop;
 	if (opacity !== void 0) image.opacity = opacity;
+	if (effects !== void 0) image.effects = effects;
 	if (frameLocks) image.frameLocks = frameLocks;
 	const hlink = resolveRelationshipIdOfType(rels, props.hlinkRId, RELATIONSHIP_TYPES.hyperlink);
 	if (hlink.status === "resolved") {
@@ -390,6 +457,7 @@ function parseAnchor(anchorEl, rels, media) {
 	const rId = extractBlipRId(blip);
 	const crop = parseImageCrop(blipFill);
 	const opacity = parseImageOpacity(blip);
+	const effects = parseImageLuminance(blip);
 	const imageData = resolveImageData(rId, rels, media);
 	const transform = parseTransform(findPictureTransform(anchorEl));
 	const image = {
@@ -402,7 +470,9 @@ function parseAnchor(anchorEl, rels, media) {
 	if (props.name !== void 0) image.docPrName = props.name;
 	if (props.alt !== void 0) image.alt = props.alt;
 	if (props.title !== void 0) image.title = props.title;
-	if (props.decorative) image.decorative = true;
+	if (props.decorative !== void 0) image.decorative = props.decorative;
+	if (props.hidden !== void 0) image.hidden = props.hidden;
+	if (props.docPrExtensions !== void 0) image.docPrExtensions = props.docPrExtensions;
 	const safeSrc = sanitizeImageSrc(imageData.src);
 	if (safeSrc) image.src = safeSrc;
 	if (imageData.mimeType) image.mimeType = imageData.mimeType;
@@ -412,6 +482,7 @@ function parseAnchor(anchorEl, rels, media) {
 	if (transform) image.transform = transform;
 	if (crop) image.crop = crop;
 	if (opacity !== void 0) image.opacity = opacity;
+	if (effects !== void 0) image.effects = effects;
 	if (frameLocks) image.frameLocks = frameLocks;
 	if (layoutInCell !== void 0) image.layoutInCell = layoutInCell;
 	if (allowOverlap !== void 0) image.allowOverlap = allowOverlap;
@@ -537,4 +608,4 @@ function needsTextWrapping(image) {
 	].includes(image.wrap.type);
 }
 //#endregion
-export { getImageDimensionsPx, getImageHeightPx, getImageWidthPx, getWrapDistancesPx, hasAltText, isBehindText, isDecorativeImage, isFloatingImage, isInFrontOfText, isInlineImage, needsTextWrapping, parseDrawing, parseImage, resolveImageData };
+export { DECORATIVE_EXTENSION_URI, DECORATIVE_NAMESPACE, getImageDimensionsPx, getImageHeightPx, getImageWidthPx, getWrapDistancesPx, hasAltText, isBehindText, isDecorativeImage, isFloatingImage, isInFrontOfText, isInlineImage, needsTextWrapping, parseDrawing, parseImage, resolveImageData };

package/dist/docx/imageRawXml.d.ts

@@ -12,7 +12,20 @@ declare const isDrawingRawXmlMode: (value: unknown) => value is document_d_expor
 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. */
+/**
+ * Whether the serializer writes the captured raw XML back.
+ *
+ * For an unclassified drawing the capture is a cache of the model, so it
+ * replays only while the two agree. For a classified one the capture *is* the
+ * drawing: a preserve-only drawing has a placeholder image, and a preview-only
+ * group has a raster render of shapes the model cannot hold. Regenerating
+ * either writes something the source never contained — for the group, at best
+ * the one child picture the rasterizer saw first under that child's
+ * relationship, in place of the whole group. So a classified capture is always
+ * written back; a stale fingerprint means the edit that made it stale is lost,
+ * which {@link classifyDrawingSafety} reports as `opaque`, and never that
+ * folio may build a replacement.
+ */
 declare const canReplayEditableImageRawXml: (drawing: document_d_exports.DrawingContent) => boolean;
 /**
  * What a drawing costs the document when Folio writes it back.