@stll/folio-core 0.45.0 → 0.47.0

package/dist/docx/drawingUtils.js

@@ -1,51 +1,23 @@
-import { ImageHorizontalAlignmentSchema, ImageHorizontalRelativeToSchema, ImageVerticalAlignmentSchema, ImageVerticalRelativeToSchema, ImageWrapTextSchema, ShapeOutlineStyleSchema, narrowEnum } from "./parserEnums.js";
+import { WORDPROCESSING_DRAWING_NAMESPACE_URIS } from "./drawingAnchor.js";
+import { ImageHorizontalAlignmentSchema, ImageHorizontalRelativeToSchema, ImageVerticalAlignmentSchema, ImageVerticalRelativeToSchema, ImageWrapTextSchema, narrowEnum } from "./parserEnums.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
-import { findByFullName, findChildByLocalName, findChildrenByLocalName, getAttribute, getChildElements, getTextContent, parseNumericAttribute, parseOnOffValue } from "./xmlParser.js";
+import { findChildByLocalName, findChildByNamespaceUri, findChildrenByLocalName, getAttribute, getChildElements, getLocalName, getNamespaceUri, getTextContent, parseNumericAttribute, parseOnOffValue } from "./xmlParser.js";
+import { PARSE_WARNING_CODES, THEME_COLOR_BY_SCHEME_COLOR_VALUE, isPresetLineDashVal, isSchemeColorValue, presetLineDashFrom, themeColorSlot } from "@stll/docx-core/model";
 //#region src/docx/drawingUtils.ts
 /**
-* Map OOXML scheme names to standard theme color slots.
-* Used when parsing a:schemeClr elements in DrawingML.
+* Shared DrawingML Parsing Utilities
+*
+* Common functions used by imageParser and textBoxParser
+* for parsing DrawingML elements (positions, wrapping, colors, fills, outlines).
 */
-const SCHEME_TO_THEME_COLOR = {
-	accent1: "accent1",
-	accent2: "accent2",
-	accent3: "accent3",
-	accent4: "accent4",
-	accent5: "accent5",
-	accent6: "accent6",
-	dk1: "dk1",
-	lt1: "lt1",
-	dk2: "dk2",
-	lt2: "lt2",
-	tx1: "text1",
-	tx2: "text2",
-	bg1: "background1",
-	bg2: "background2",
-	hlink: "hlink",
-	folHlink: "folHlink"
-};
 /**
-* Map normalized theme color slots back to DrawingML scheme color names.
-* DrawingML uses bg1/bg2/tx1/tx2 where the document model uses descriptive names.
+* `a:schemeClr/@val` as a WordprocessingML theme colour, for the one DrawingML
+* reference a document part carries inline.
+*
+* Both directions live in `@stll/docx-core/model`, total over their schema
+* enumerations, so neither can omit a token.
 */
-const THEME_COLOR_TO_DRAWING_SCHEME = {
-	dk1: "dk1",
-	lt1: "lt1",
-	dk2: "dk2",
-	lt2: "lt2",
-	accent1: "accent1",
-	accent2: "accent2",
-	accent3: "accent3",
-	accent4: "accent4",
-	accent5: "accent5",
-	accent6: "accent6",
-	hlink: "hlink",
-	folHlink: "folHlink",
-	background1: "bg1",
-	text1: "tx1",
-	background2: "bg2",
-	text2: "tx2"
-};
+const schemeColorToThemeColor = (value) => isSchemeColorValue(value) ? THEME_COLOR_BY_SCHEME_COLOR_VALUE[value] ?? void 0 : void 0;
 /**
 * sRGB hex per OOXML (ST_HexColorRGB): exactly six hex digits, case-insensitive.
 * Anything else is rejected so untrusted DOCX input cannot smuggle markup through
@@ -101,8 +73,8 @@ function parseColorElement(element) {
 	}
 	const schemeClr = children.find((el) => el.name === "a:schemeClr");
 	if (schemeClr) {
-		const val = getAttribute(schemeClr, null, "val");
-		if (val) return applyColorModifiers({ themeColor: SCHEME_TO_THEME_COLOR[val] ?? "dk1" }, schemeClr);
+		const themeColor = schemeColorToThemeColor(getAttribute(schemeClr, null, "val") ?? "");
+		if (themeColor !== void 0) return applyColorModifiers({ themeColor }, schemeClr);
 	}
 	const sysClr = children.find((el) => el.name === "a:sysClr");
 	if (sysClr) {
@@ -174,7 +146,7 @@ function parseGradientFill(gradientFill) {
 /**
 * Parse outline from shape properties (a:ln).
 */
-function parseOutline(spPr) {
+function parseOutline(spPr, context) {
 	const ln = spPr ? findChildByLocalName(spPr, "ln") : null;
 	if (!ln) return;
 	if (findChildByLocalName(ln, "noFill")) return;
@@ -197,9 +169,14 @@ function parseOutline(spPr) {
 		if (color !== void 0) outline.color = color;
 	}
 	const prstDash = findChildByLocalName(ln, "prstDash");
-	if (prstDash) {
-		const val = narrowEnum(getAttribute(prstDash, null, "val"), ShapeOutlineStyleSchema);
-		if (val) outline.style = val;
+	const rawDash = prstDash ? getAttribute(prstDash, null, "val") : null;
+	if (rawDash) {
+		if (!isPresetLineDashVal(rawDash)) context?.warn({
+			code: PARSE_WARNING_CODES.outlineDashOutsideEnum,
+			element: prstDash?.name ?? "a:prstDash",
+			value: rawDash
+		});
+		outline.dash = presetLineDashFrom(rawDash);
 	}
 	const headEnd = findChildByLocalName(ln, "headEnd");
 	if (headEnd) outline.headEnd = parseLineEnd(headEnd);
@@ -231,10 +208,12 @@ function parseLineEnd(element) {
 /**
 * Parse horizontal position from wp:positionH element.
 */
+/** A child of a WordprocessingDrawing element, resolved by namespace. */
+const findDrawingChild = (parent, localName) => findChildByNamespaceUri(parent, WORDPROCESSING_DRAWING_NAMESPACE_URIS, localName);
 function parsePositionH(posH) {
 	if (!posH) return;
 	const relativeTo = narrowEnum(getAttribute(posH, null, "relativeFrom"), ImageHorizontalRelativeToSchema) ?? "column";
-	const alignEl = findByFullName(posH, "wp:align");
+	const alignEl = findDrawingChild(posH, "align");
 	if (alignEl) {
 		const alignment = narrowEnum(getTextContent(alignEl), ImageHorizontalAlignmentSchema);
 		if (alignment) return {
@@ -242,7 +221,7 @@ function parsePositionH(posH) {
 			alignment
 		};
 	}
-	const posOffsetEl = findByFullName(posH, "wp:posOffset");
+	const posOffsetEl = findDrawingChild(posH, "posOffset");
 	if (posOffsetEl) {
 		const text = getTextContent(posOffsetEl);
 		const posOffset = Number.parseInt(text, 10);
@@ -262,7 +241,7 @@ function parsePositionH(posH) {
 function parsePositionV(posV) {
 	if (!posV) return;
 	const relativeTo = narrowEnum(getAttribute(posV, null, "relativeFrom"), ImageVerticalRelativeToSchema) ?? "paragraph";
-	const alignEl = findByFullName(posV, "wp:align");
+	const alignEl = findDrawingChild(posV, "align");
 	if (alignEl) {
 		const alignment = narrowEnum(getTextContent(alignEl), ImageVerticalAlignmentSchema);
 		if (alignment) return {
@@ -270,7 +249,7 @@ function parsePositionV(posV) {
 			alignment
 		};
 	}
-	const posOffsetEl = findByFullName(posV, "wp:posOffset");
+	const posOffsetEl = findDrawingChild(posV, "posOffset");
 	if (posOffsetEl) {
 		const text = getTextContent(posOffsetEl);
 		const posOffset = Number.parseInt(text, 10);
@@ -288,8 +267,8 @@ function parsePositionV(posV) {
 * Parse position for anchored drawings (combines positionH + positionV).
 */
 function parseAnchorPosition(anchor) {
-	const positionH = findByFullName(anchor, "wp:positionH");
-	const positionV = findByFullName(anchor, "wp:positionV");
+	const positionH = findDrawingChild(anchor, "positionH");
+	const positionV = findDrawingChild(anchor, "positionV");
 	return {
 		horizontal: parsePositionH(positionH) ?? {
 			relativeTo: "column",
@@ -301,61 +280,176 @@ function parseAnchorPosition(anchor) {
 		}
 	};
 }
-/** Known wrap element names */
-const WRAP_ELEMENT_NAMES = [
-	"wp:wrapNone",
-	"wp:wrapSquare",
-	"wp:wrapTight",
-	"wp:wrapThrough",
-	"wp:wrapTopAndBottom"
+/**
+* `EG_WrapType`'s members, by local name: the `wp` prefix is the producer's
+* choice and a package free to bind the namespace elsewhere writes the same
+* wrap.
+*/
+const WRAP_ELEMENT_LOCAL_NAMES = {
+	wrapNone: "inFront",
+	wrapSquare: "square",
+	wrapTight: "tight",
+	wrapThrough: "through",
+	wrapTopAndBottom: "topAndBottom"
+};
+/** The `EG_WrapType` child of a `wp:anchor`, resolved by namespace. */
+function findWrapElement(anchor) {
+	for (const child of getChildElements(anchor)) if (getLocalName(child.name) in WRAP_ELEMENT_LOCAL_NAMES && WORDPROCESSING_DRAWING_NAMESPACE_URIS.has(getNamespaceUri(child) ?? "")) return child;
+	return null;
+}
+/** The inset attributes `CT_Inline`, `CT_Anchor` and the wrap children share. */
+const WRAP_DISTANCE_KEYS = [
+	"distT",
+	"distB",
+	"distL",
+	"distR"
 ];
 /**
+* The insets one element states, or undefined when it states none.
+*
+* A wrap child's type declares a subset — `CT_WrapTight` and `CT_WrapThrough`
+* only `distL`/`distR`, `CT_WrapTopBottom` only `distT`/`distB` — and an
+* attribute the type does not declare cannot be present to read.
+*/
+const parseWrapDistances = (el) => {
+	if (!el) return;
+	const distances = {};
+	let stated = false;
+	for (const key of WRAP_DISTANCE_KEYS) {
+		const value = parseNumericAttribute(el, null, key);
+		if (value !== void 0) {
+			distances[key] = value;
+			stated = true;
+		}
+	}
+	return stated ? distances : void 0;
+};
+/** The slot record for a drawing, or undefined when neither element stated an inset. */
+const wrapDistanceSlots = (drawing, wrapChild) => drawing === void 0 && wrapChild === void 0 ? void 0 : {
+	...drawing === void 0 ? {} : { drawing },
+	...wrapChild === void 0 ? {} : { wrapChild }
+};
+/**
+* `wp:effectExtent`'s four sides in EMU, exactly as the element states them.
+*
+* `CT_EffectExtent` requires all four, so a missing one is a malformed element
+* rather than an unstated side, and zero is its own value: an explicit all-zero
+* reservation on a wrap child says "this wrap reserves nothing", which is not
+* what an absent element says.
+*/
+const parseEffectExtent = (el) => el === null ? void 0 : {
+	left: parseNumericAttribute(el, null, "l") ?? 0,
+	top: parseNumericAttribute(el, null, "t") ?? 0,
+	right: parseNumericAttribute(el, null, "r") ?? 0,
+	bottom: parseNumericAttribute(el, null, "b") ?? 0
+};
+/**
+* The drawing's own `wp:effectExtent`, which is also what `Image.padding` holds.
+*
+* An all-zero reservation is what Word writes on a drawing with no effect, and
+* a rebuild writes zeros for a drawing the record holds none for, so the two
+* are the same document and neither the padding nor the slot keeps it. The wrap
+* child's is read as authored instead: an absent one there inherits the
+* drawing's, so an explicit all-zero says something an absent one does not.
+*/
+const parseDrawingEffectExtent = (el) => {
+	const extent = parseEffectExtent(el);
+	if (extent === void 0) return;
+	return extent.left === 0 && extent.top === 0 && extent.right === 0 && extent.bottom === 0 ? void 0 : extent;
+};
+/** The slot record, or undefined when neither element stated an effect extent. */
+const effectExtentSlots = (drawing, wrapChild) => drawing === void 0 && wrapChild === void 0 ? void 0 : {
+	...drawing === void 0 ? {} : { drawing },
+	...wrapChild === void 0 ? {} : { wrapChild }
+};
+/** The wrap insets `CT_Inline` carries, read the same way for every graphic. */
+function parseInlineWrap(inlineEl) {
+	const wrap = { type: "inline" };
+	const drawing = parseWrapDistances(inlineEl);
+	for (const key of WRAP_DISTANCE_KEYS) {
+		const value = drawing?.[key];
+		if (value !== void 0) wrap[key] = value;
+	}
+	const slots = wrapDistanceSlots(drawing, void 0);
+	if (slots !== void 0) wrap.distanceSlots = slots;
+	const extents = effectExtentSlots(parseDrawingEffectExtent(findDrawingChild(inlineEl, "effectExtent")), void 0);
+	if (extents !== void 0) wrap.effectExtentSlots = extents;
+	return wrap;
+}
+/** A `CT_Point2D`, which requires both coordinates. */
+const parseWrapPolygonPoint = (el) => {
+	const x = parseNumericAttribute(el, null, "x");
+	const y = parseNumericAttribute(el, null, "y");
+	return x === void 0 || y === void 0 ? void 0 : {
+		x,
+		y
+	};
+};
+/**
+* `wp:wrapPolygon`, the outline `wp:wrapTight` and `wp:wrapThrough` require.
+*
+* Undefined when the element is absent or states no `wp:start`, which
+* `CT_WrapPath` requires and a rebuild has nothing to write without. A path
+* with fewer `wp:lineTo` than the type admits is kept as it stands: reading it
+* as no polygon at all would hand the drawing the minted rectangle and move
+* text the source flows through the object.
+*/
+const parseWrapPolygon = (wrapEl) => {
+	const polygonEl = findDrawingChild(wrapEl, "wrapPolygon");
+	if (!polygonEl) return;
+	const startEl = findDrawingChild(polygonEl, "start");
+	const start = parseWrapPolygonPoint(startEl);
+	if (start === void 0) return;
+	const lineTo = getChildElements(polygonEl).filter((child) => getLocalName(child.name) === "lineTo" && WORDPROCESSING_DRAWING_NAMESPACE_URIS.has(getNamespaceUri(child) ?? "")).flatMap((child) => {
+		const point = parseWrapPolygonPoint(child);
+		return point === void 0 ? [] : [point];
+	});
+	const edited = parseOnOffValue(getAttribute(polygonEl, null, "edited"));
+	return {
+		...edited === void 0 ? {} : { edited },
+		start,
+		lineTo
+	};
+};
+/**
 * Parse wrap settings from a wrap element.
 *
-* Distance attributes (distT/distB/distL/distR) can appear on both
-* the anchor element and the wrap child. Wrap child values take priority;
-* anchor-level values are used as fallbacks.
+* Both the insets and the effect extent are declared twice over — on the
+* drawing and on the wrap child — and each is kept in the slot that stated it.
+* The insets differ in that the wrap child's take priority as the value in
+* force; the two effect extents are two values (the object's own reservation
+* and the one the text flow is computed against), so neither overrides the
+* other.
 */
-function parseWrapElement(wrapEl, behindDoc, anchorDistances) {
+function parseWrapElement({ wrapEl, behindDoc, anchorDistances, anchorEffectExtent }) {
+	const drawingDistances = anchorDistances !== void 0 && WRAP_DISTANCE_KEYS.some((key) => anchorDistances[key] != null) ? anchorDistances : void 0;
 	if (!wrapEl) {
 		const wrap = { type: behindDoc ? "behind" : "inFront" };
-		if (anchorDistances?.distT !== void 0) wrap.distT = anchorDistances.distT;
-		if (anchorDistances?.distB !== void 0) wrap.distB = anchorDistances.distB;
-		if (anchorDistances?.distL !== void 0) wrap.distL = anchorDistances.distL;
-		if (anchorDistances?.distR !== void 0) wrap.distR = anchorDistances.distR;
+		for (const key of WRAP_DISTANCE_KEYS) {
+			const value = drawingDistances?.[key];
+			if (value !== void 0) wrap[key] = value;
+		}
+		const slots = wrapDistanceSlots(drawingDistances, void 0);
+		if (slots !== void 0) wrap.distanceSlots = slots;
+		const extents = effectExtentSlots(anchorEffectExtent, void 0);
+		if (extents !== void 0) wrap.effectExtentSlots = extents;
 		return wrap;
 	}
-	const wrapType = (wrapEl.name || "").replace("wp:", "");
-	let type;
-	switch (wrapType) {
-		case "wrapNone":
-			type = behindDoc ? "behind" : "inFront";
-			break;
-		case "wrapSquare":
-			type = "square";
-			break;
-		case "wrapTight":
-			type = "tight";
-			break;
-		case "wrapThrough":
-			type = "through";
-			break;
-		case "wrapTopAndBottom":
-			type = "topAndBottom";
-			break;
-		default: type = "square";
-	}
-	const wrap = { type };
+	const named = WRAP_ELEMENT_LOCAL_NAMES[getLocalName(wrapEl.name)] ?? "square";
+	const wrap = { type: named === "inFront" && behindDoc ? "behind" : named };
 	const wrapText = narrowEnum(getAttribute(wrapEl, null, "wrapText"), ImageWrapTextSchema);
 	if (wrapText) wrap.wrapText = wrapText;
-	const distT = parseNumericAttribute(wrapEl, null, "distT") ?? anchorDistances?.distT;
-	const distB = parseNumericAttribute(wrapEl, null, "distB") ?? anchorDistances?.distB;
-	const distL = parseNumericAttribute(wrapEl, null, "distL") ?? anchorDistances?.distL;
-	const distR = parseNumericAttribute(wrapEl, null, "distR") ?? anchorDistances?.distR;
-	if (distT !== void 0) wrap.distT = distT;
-	if (distB !== void 0) wrap.distB = distB;
-	if (distL !== void 0) wrap.distL = distL;
-	if (distR !== void 0) wrap.distR = distR;
+	const wrapChildDistances = parseWrapDistances(wrapEl);
+	for (const key of WRAP_DISTANCE_KEYS) {
+		const value = wrapChildDistances?.[key] ?? drawingDistances?.[key];
+		if (value !== void 0) wrap[key] = value;
+	}
+	const slots = wrapDistanceSlots(drawingDistances, wrapChildDistances);
+	if (slots !== void 0) wrap.distanceSlots = slots;
+	const extents = effectExtentSlots(anchorEffectExtent, parseEffectExtent(findDrawingChild(wrapEl, "effectExtent")));
+	if (extents !== void 0) wrap.effectExtentSlots = extents;
+	const polygon = parseWrapPolygon(wrapEl);
+	if (polygon !== void 0) wrap.polygon = polygon;
 	return wrap;
 }
 /**
@@ -371,20 +465,14 @@ function parseAnchorBehindDoc(anchor) {
 	return parseOnOffValue(getAttribute(anchor, null, "behindDoc")) ?? false;
 }
 function parseAnchorWrap(anchor) {
-	const children = getChildElements(anchor);
-	const behindDoc = parseAnchorBehindDoc(anchor);
-	const wrapEl = children.find((el) => WRAP_ELEMENT_NAMES.includes(el.name ?? ""));
-	const distT = parseNumericAttribute(anchor, null, "distT");
-	const distB = parseNumericAttribute(anchor, null, "distB");
-	const distL = parseNumericAttribute(anchor, null, "distL");
-	const distR = parseNumericAttribute(anchor, null, "distR");
-	const anchorDistances = {
-		...distT != null ? { distT } : {},
-		...distB != null ? { distB } : {},
-		...distL != null ? { distL } : {},
-		...distR != null ? { distR } : {}
-	};
-	return parseWrapElement(wrapEl ?? null, behindDoc, anchorDistances);
+	const anchorDistances = parseWrapDistances(anchor);
+	const anchorEffectExtent = parseDrawingEffectExtent(findDrawingChild(anchor, "effectExtent"));
+	return parseWrapElement({
+		wrapEl: findWrapElement(anchor),
+		behindDoc: parseAnchorBehindDoc(anchor),
+		...anchorDistances === void 0 ? {} : { anchorDistances },
+		...anchorEffectExtent === void 0 ? {} : { anchorEffectExtent }
+	});
 }
 /**
 * Default theme color fallbacks (Office 2016 defaults).
@@ -401,10 +489,6 @@ const DEFAULT_THEME_COLOR_HEX = {
 	lt1: "FFFFFF",
 	dk2: "1F497D",
 	lt2: "EEECE1",
-	text1: "000000",
-	text2: "1F497D",
-	background1: "FFFFFF",
-	background2: "EEECE1",
 	hlink: "0563C1",
 	folHlink: "954F72"
 };
@@ -415,7 +499,10 @@ const DEFAULT_THEME_COLOR_HEX = {
 function resolveColorValueToHex(color) {
 	if (!color) return;
 	if (color.rgb) return `#${color.rgb}`;
-	if (color.themeColor) return `#${DEFAULT_THEME_COLOR_HEX[color.themeColor] ?? "000000"}`;
+	if (color.themeColor) {
+		const slot = themeColorSlot(color.themeColor);
+		return `#${slot === void 0 ? "000000" : DEFAULT_THEME_COLOR_HEX[slot]}`;
+	}
 }
 //#endregion
-export { THEME_COLOR_TO_DRAWING_SCHEME, WRAP_ELEMENT_NAMES, parseAnchorBehindDoc, parseAnchorPosition, parseAnchorWrap, parseColorElement, parseFill, parseOutline, parsePositionH, parsePositionV, parseWrapElement, resolveColorValueToHex };
+export { findWrapElement, parseAnchorBehindDoc, parseAnchorPosition, parseAnchorWrap, parseColorElement, parseDrawingEffectExtent, parseEffectExtent, parseFill, parseInlineWrap, parseOutline, parsePositionH, parsePositionV, parseWrapElement, resolveColorValueToHex };

package/dist/docx/ensureParaIds.js

@@ -1,5 +1,5 @@
 import { deterministicHexId } from "../utils/hexId.js";
-import { isXmlNameBoundary } from "./selectiveXmlPatch.js";
+import { isXmlNameBoundary, spliceXml } from "./selectiveXmlPatch.js";
 import { loadDocxArchive } from "./server/boundedArchive.js";
 import { TaggedError } from "better-result";
 import JSZip from "jszip";
@@ -97,11 +97,21 @@ const OPEN_TAG_TEXT_ID_PATTERN = /\sw(?:14)?:textId=(?<quote>["'])(?<id>[\s\S]*?
 const XMLNS_W14_PATTERN = /\sxmlns:w14=(?<quote>["'])(?<value>[\s\S]*?)\k<quote>/u;
 const XMLNS_MC_PATTERN = /\sxmlns:mc=(?<quote>["'])(?<value>[\s\S]*?)\k<quote>/u;
 const MC_IGNORABLE_PATTERN = /\smc:Ignorable=(?<quote>["'])(?<value>[\s\S]*?)\k<quote>/u;
-const applySplices = (xml, edits) => {
-	const ordered = [...edits].sort((a, b) => b.start - a.start);
-	let result = xml;
-	for (const { start, end, text } of ordered) result = result.slice(0, start) + text + result.slice(end);
-	return result;
+/**
+* Stamp the edits into the part through the splice owner, which refuses a
+* result that would leave a comment range with only one half. These edits
+* rewrite `<w:p …>` open tags and the root element's attributes, so they
+* should never cut across a range marker; the owner is what makes that
+* structural rather than a reading of the scanner.
+*/
+const applySplices = (xml, edits, partPath) => {
+	const patched = spliceXml(xml, edits.map(({ start, end, text }) => ({
+		start,
+		end,
+		newXml: text
+	})));
+	if (patched === null) throw createEnsureParaIdsError(`Stamping paragraph ids into ${partPath} broke a comment range`);
+	return patched;
 };
 const createEnsureParaIdsError = (message, cause) => new EnsureParaIdsError({
 	message,
@@ -382,7 +392,7 @@ const ensureParaIdsInternal = async (docx, options) => {
 		if (scan.edits.length === 0) continue;
 		assigned += scan.assigned;
 		deduplicated += scan.deduplicated;
-		updates.set(partPath, applySplices(xml, [...scan.edits, ...ensureRootNamespaces(xml, partPath)]));
+		updates.set(partPath, applySplices(xml, [...scan.edits, ...ensureRootNamespaces(xml, partPath)], partPath));
 	}
 	if (updates.size === 0) return {
 		docx: toUint8Array(docx),

package/dist/docx/fieldParser.d.ts

@@ -1,6 +1,6 @@
 import { document_d_exports } from "../types/document.js";
-import { StyleMap } from "./styleParser.js";
 import { XmlElement } from "./xmlParser.js";
+import { StyleMap } from "./styleParser.js";
 //#region src/docx/fieldParser.d.ts
 /**
  * All known field types from OOXML specification

package/dist/docx/fieldParser.js

@@ -1,7 +1,8 @@
+import { parseFieldState } from "./fieldState.js";
 import { formatOoxmlCounter } from "./ooxmlCounterFormatter.js";
 import { FieldTypeSchema, narrowEnum } from "./parserEnums.js";
 import { parseRun } from "./runParser.js";
-import { findChildren, getAttribute, parseOnOffAttribute } from "./xmlParser.js";
+import { findChildren, getAttribute } from "./xmlParser.js";
 //#region src/docx/fieldParser.ts
 /**
 * All known field types from OOXML specification
@@ -162,10 +163,9 @@ function parseSimpleField(node, styles, theme) {
 		type: "simpleField",
 		instruction,
 		fieldType: parseFieldType(instruction),
-		content: []
+		content: [],
+		...parseFieldState(node)
 	};
-	if (parseOnOffAttribute(node, "w", "fldLock") === true) field.fldLock = true;
-	if (parseOnOffAttribute(node, "w", "dirty") === true) field.dirty = true;
 	const children = findChildren(node, "w", "r");
 	for (const child of children) {
 		const run = parseRun(child, styles, theme);

package/dist/docx/fieldState.d.ts

@@ -0,0 +1,26 @@
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/fieldState.d.ts
+/** What a field element states about its lock and dirty flags. */
+type FieldState = {
+  fldLock?: boolean;
+  dirty?: boolean;
+};
+/** Read both attributes off a `w:fldSimple` or `w:fldChar`, keeping an explicit off. */
+declare const parseFieldState: (element: XmlElement) => FieldState;
+/**
+ * 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.
+ */
+declare const fieldStateOf: ({ fldLock, dirty }: FieldState) => FieldState;
+/**
+ * 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.
+ */
+declare const fieldStateAttributes: ({ fldLock, dirty }: FieldState) => string[];
+//#endregion
+export { FieldState, fieldStateAttributes, fieldStateOf, parseFieldState };

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 };