@stll/folio-core 0.43.0 → 0.44.0

package/dist/docx/markupRangeMarker.js

@@ -0,0 +1,44 @@
+import { getAttribute, parseNumericAttribute } from "./xmlParser.js";
+//#region src/docx/markupRangeMarker.ts
+/** ST_DisplacedByCustomXml. A value outside it is not a placement folio can honour. */
+const DISPLACED_BY_CUSTOM_XML = /* @__PURE__ */ new Set(["next", "prev"]);
+const parseDisplacedByCustomXml = (node) => {
+	const value = getAttribute(node, "w", "displacedByCustomXml") ?? "";
+	return DISPLACED_BY_CUSTOM_XML.has(value) ? value : void 0;
+};
+const parseMarkupRangeMarker = (node) => {
+	const marker = { id: parseNumericAttribute(node, "w", "id") ?? 0 };
+	const displacedByCustomXml = parseDisplacedByCustomXml(node);
+	if (displacedByCustomXml !== void 0) marker.displacedByCustomXml = displacedByCustomXml;
+	return marker;
+};
+const parseBookmarkRangeMarker = (node) => {
+	const marker = {
+		...parseMarkupRangeMarker(node),
+		name: getAttribute(node, "w", "name") ?? ""
+	};
+	const colFirst = parseNumericAttribute(node, "w", "colFirst");
+	if (colFirst !== void 0) marker.colFirst = colFirst;
+	const colLast = parseNumericAttribute(node, "w", "colLast");
+	if (colLast !== void 0) marker.colLast = colLast;
+	return marker;
+};
+/**
+* `w:author` is required on `CT_MoveBookmark`, so an absent one takes the same
+* `Unknown` fallback a tracked change takes rather than leaving the saved
+* package short of an attribute the schema demands. `w:date` is required too,
+* but inventing a timestamp would state a fact about the document that is not
+* true, so an absent date stays absent.
+*/
+const parseMoveBookmarkMarker = (node) => {
+	const author = (getAttribute(node, "w", "author") ?? "").trim();
+	const marker = {
+		...parseBookmarkRangeMarker(node),
+		author: author.length > 0 ? author : "Unknown"
+	};
+	const date = (getAttribute(node, "w", "date") ?? "").trim();
+	if (date.length > 0) marker.date = date;
+	return marker;
+};
+//#endregion
+export { parseBookmarkRangeMarker, parseMarkupRangeMarker, parseMoveBookmarkMarker };

package/dist/docx/noteReferenceStyles.d.ts

@@ -0,0 +1,29 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/noteReferenceStyles.d.ts
+/** The id `commentSerializer` and `paragraphSerializer` write. */
+declare const COMMENT_REFERENCE_STYLE_ID = "CommentReference";
+/** The ids `noteSerializer` writes for the two note kinds. */
+declare const FOOTNOTE_REFERENCE_STYLE_ID = "FootnoteReference";
+declare const ENDNOTE_REFERENCE_STYLE_ID = "EndnoteReference";
+/** Which reference marks a package actually contains. */
+type NoteReferenceNeeds = {
+  comments: boolean;
+  footnotes: boolean;
+  endnotes: boolean;
+};
+/** What a package's content requires, read off the model rather than guessed. */
+declare const noteReferenceNeeds: (pkg: {
+  comments?: unknown[] | undefined;
+  footnotes?: unknown[] | undefined;
+  endnotes?: unknown[] | undefined;
+}) => NoteReferenceNeeds;
+/**
+ * The reference styles a package needs and does not already define, by id.
+ *
+ * Returns the definitions to append rather than a mutated style table: the
+ * caller owns the document, and a document that already defines the style
+ * (under any id folio recognises) keeps its own.
+ */
+declare const missingNoteReferenceStyles: (styles: document_d_exports.StyleDefinitions | undefined, needs: NoteReferenceNeeds) => document_d_exports.Style[];
+//#endregion
+export { COMMENT_REFERENCE_STYLE_ID, ENDNOTE_REFERENCE_STYLE_ID, FOOTNOTE_REFERENCE_STYLE_ID, NoteReferenceNeeds, missingNoteReferenceStyles, noteReferenceNeeds };

package/dist/docx/noteReferenceStyles.js

@@ -0,0 +1,70 @@
+import { BUILT_IN_STYLE_NAME } from "./builtInStyles.js";
+//#region src/docx/noteReferenceStyles.ts
+/**
+* The character styles folio's serializers write into every document that
+* carries a comment or a note, and the definitions that keep those references
+* from dangling.
+*
+* `commentSerializer`, `paragraphSerializer` and `noteSerializer` each emit
+* `<w:rStyle w:val="…"/>` for the reference mark, because that is what Word
+* writes and what makes the mark superscript. Nothing guaranteed the document
+* *defined* those styles: a package folio assembled from the generic style set
+* referenced `FootnoteReference` while declaring only seven paragraph styles,
+* so the mark rendered as body text. One owner here, so a serializer and the
+* style table cannot disagree about the id.
+*/
+/** The id `commentSerializer` and `paragraphSerializer` write. */
+const COMMENT_REFERENCE_STYLE_ID = "CommentReference";
+/** The ids `noteSerializer` writes for the two note kinds. */
+const FOOTNOTE_REFERENCE_STYLE_ID = "FootnoteReference";
+const ENDNOTE_REFERENCE_STYLE_ID = "EndnoteReference";
+/** The default character style Word bases these on, when the package has one. */
+const DEFAULT_CHARACTER_STYLE_ID = "DefaultParagraphFont";
+const referenceStyle = (styleId, name, superscript) => ({
+	styleId,
+	type: "character",
+	name,
+	uiPriority: 99,
+	semiHidden: true,
+	unhideWhenUsed: true,
+	rPr: superscript ? { vertAlign: "superscript" } : { fontSize: 16 }
+});
+/**
+* The definition for each reference style, keyed by the need that requires it.
+* Word's comment reference is 8pt body text; the note references are
+* superscript.
+*/
+const REFERENCE_STYLES = {
+	comments: () => referenceStyle(COMMENT_REFERENCE_STYLE_ID, BUILT_IN_STYLE_NAME.commentReference, false),
+	footnotes: () => referenceStyle(FOOTNOTE_REFERENCE_STYLE_ID, BUILT_IN_STYLE_NAME.footnoteReference, true),
+	endnotes: () => referenceStyle(ENDNOTE_REFERENCE_STYLE_ID, BUILT_IN_STYLE_NAME.endnoteReference, true)
+};
+/** What a package's content requires, read off the model rather than guessed. */
+const noteReferenceNeeds = (pkg) => ({
+	comments: (pkg.comments?.length ?? 0) > 0,
+	footnotes: (pkg.footnotes?.length ?? 0) > 0,
+	endnotes: (pkg.endnotes?.length ?? 0) > 0
+});
+/**
+* The reference styles a package needs and does not already define, by id.
+*
+* Returns the definitions to append rather than a mutated style table: the
+* caller owns the document, and a document that already defines the style
+* (under any id folio recognises) keeps its own.
+*/
+const missingNoteReferenceStyles = (styles, needs) => {
+	const defined = new Set((styles?.styles ?? []).map((style) => style.styleId));
+	const basedOn = defined.has(DEFAULT_CHARACTER_STYLE_ID) ? DEFAULT_CHARACTER_STYLE_ID : void 0;
+	const missing = [];
+	for (const [need, create] of Object.entries(REFERENCE_STYLES)) {
+		if (!needs[need]) continue;
+		const style = create();
+		if (!defined.has(style.styleId)) missing.push(basedOn === void 0 ? style : {
+			...style,
+			basedOn
+		});
+	}
+	return missing;
+};
+//#endregion
+export { COMMENT_REFERENCE_STYLE_ID, ENDNOTE_REFERENCE_STYLE_ID, FOOTNOTE_REFERENCE_STYLE_ID, missingNoteReferenceStyles, noteReferenceNeeds };

package/dist/docx/numberingReferenceNormalization.d.ts

@@ -1,6 +1,9 @@
 import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
 //#region src/docx/numberingReferenceNormalization.d.ts
+/** The codes this normalisation is reported under, owned here, not at the caller. */
+declare const UNNUMBERED_PARAGRAPH_WARNING: "unnumbered-paragraph";
+declare const UNNUMBERED_STYLE_WARNING: "unnumbered-style";
 type NormalizeNumberingReferencesInput = {
   documentBody: document_d_exports.DocumentBody;
   numbering: NumberingMap;
@@ -23,4 +26,4 @@ type NormalizeStyleNumberingReferencesResult = {
 };
 declare const normalizeStyleNumberingReferences: ({ styles, numbering }: NormalizeStyleNumberingReferencesInput) => NormalizeStyleNumberingReferencesResult;
 //#endregion
-export { normalizeNumberingReferences, normalizeStyleNumberingReferences };
+export { UNNUMBERED_PARAGRAPH_WARNING, UNNUMBERED_STYLE_WARNING, normalizeNumberingReferences, normalizeStyleNumberingReferences };

package/dist/docx/numberingReferenceNormalization.js

@@ -1,7 +1,23 @@
 import { isNumberingReference } from "./numberingReference.js";
 import { visitDocxParagraphs } from "./paragraphTraversal.js";
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/numberingReferenceNormalization.ts
 /**
+* Parse-boundary tolerance for `w:numPr` numbering references.
+*
+* A file Word opens must never reach a panic, so a reference that resolves to
+* nothing is repaired here, on both tiers that can carry one: the paragraph and
+* the paragraph style. Downstream code (and `assertStyleNumberingReferences` in
+* particular) can then treat a numbering reference as resolvable.
+*
+* The repair writes the sentinel rather than deleting the `w:numPr`. ECMA-376
+* 17.9.18 reserves `w:numId w:val="0"` for "the removal of numbering properties
+* at a particular level in the style hierarchy"; deleting the element instead
+* removes nothing, it only uncovers the tier below, handing the paragraph its
+* `w:pStyle` numbering or the style its `w:basedOn` numbering. A source that
+* shows no number would come back numbered.
+*/
+/**
 * Whether a `w:numId` still reaches a level definition: a `w:num` that names a
 * `w:abstractNum` the numbering part defines. Both hops can dangle, and a
 * `w:num` with no `w:abstractNum` numbers nothing just as a missing one does.
@@ -11,6 +27,9 @@ const resolvesNumbering = (numId, numbering) => {
 	const abstractNumId = numbering.getAbstractNumId(numId);
 	return abstractNumId !== null && numbering.getAbstract(abstractNumId) !== null;
 };
+/** The codes this normalisation is reported under, owned here, not at the caller. */
+const UNNUMBERED_PARAGRAPH_WARNING = PARSE_WARNING_CODES.unnumberedParagraph;
+const UNNUMBERED_STYLE_WARNING = PARSE_WARNING_CODES.unnumberedStyle;
 const normalizeNumberingReferences = ({ documentBody, numbering, headers, footers, footnotes, endnotes }) => {
 	let unnumberedDanglingReferences = 0;
 	visitDocxParagraphs({
@@ -42,4 +61,4 @@ const normalizeStyleNumberingReferences = ({ styles, numbering }) => {
 	return { unnumberedStyleIds };
 };
 //#endregion
-export { normalizeNumberingReferences, normalizeStyleNumberingReferences };
+export { UNNUMBERED_PARAGRAPH_WARNING, UNNUMBERED_STYLE_WARNING, normalizeNumberingReferences, normalizeStyleNumberingReferences };

package/dist/docx/paraIdRangeNormalization.d.ts

@@ -1,23 +1,4 @@
 //#region src/docx/paraIdRangeNormalization.d.ts
-/**
- * Keep every paragraph id a package carries inside the range the schema gives
- * it.
- *
- * `w14:paraId`, `w14:textId` and the comment-part ids that reference a
- * paragraph are `ST_LongHexNumber` with a maximum: the value has to be below
- * `0x80000000`, so the ids are 31-bit. Producers exist that write eight hex
- * digits without that bound, and folio preserves the ids a document arrives
- * with — so a package can carry an out-of-range id in, and a save that copies
- * it through hands a consumer a package it will refuse.
- *
- * {@link paraIdInRange} is the one mapping, and it is a pure function of the
- * value alone. That is what lets the parser and the save agree without
- * consulting each other: a paragraph's id in the model is the id the file gets,
- * so bringing an id into range does not make a document's own identity move
- * under it between reading and writing. The package pass below is the same
- * mapping applied to every attribute that carries such an id, so a paragraph
- * and every reference to it move together.
- */
 /**
  * `value` when it already fits, and a value derived from it when it does not.
  *

package/dist/docx/paragraphParser.js

@@ -1,22 +1,24 @@
-import { isValidHexColor } from "../utils/colorResolver.js";
 import { isValidHexId } from "../utils/hexId.js";
 import { parseBookmarkEnd as parseBookmarkEnd$1, parseBookmarkStart as parseBookmarkStart$1 } from "./bookmarkParser.js";
+import { parseBorderSpec } from "./borderParser.js";
 import { parseFieldType } from "./fieldParser.js";
 import { parseHyperlink as parseHyperlink$1, parseHyperlinkChild } from "./hyperlinkParser.js";
+import { parseMarkupRangeMarker, parseMoveBookmarkMarker } from "./markupRangeMarker.js";
 import { markerFormattingFromLevel, numberingLevelHasMarkerSlot } from "./numberingParser.js";
 import { isNumberingReference } from "./numberingReference.js";
 import { paraIdInRange } from "./paraIdRangeNormalization.js";
 import { assignParagraphPropertySource } from "./paragraphPropertySource.js";
-import { BorderStyleSchema, FrameWrapSchema, FrameXAlignSchema, FrameYAlignSchema, LineSpacingRuleSchema, ParagraphAlignmentSchema, ShadingPatternSchema, TabLeaderSchema, TabStopAlignmentSchema, ThemeColorSlotSchema, narrowEnum } from "./parserEnums.js";
+import { FrameWrapSchema, FrameXAlignSchema, FrameYAlignSchema, LineSpacingRuleSchema, ParagraphAlignmentSchema, TabLeaderSchema, TabStopAlignmentSchema, narrowEnum } from "./parserEnums.js";
 import { consolidateParagraphContent } from "./runConsolidator.js";
 import { parseRun, parseRunProperties } from "./runParser.js";
 import { parseSdtProperties } from "./sdtProperties.js";
 import { parseSectionProperties } from "./sectionParser.js";
+import { parseShading } from "./shadingParser.js";
 import { parsePropertyChangeInfo, parseTrackedChangeInfo } from "./trackedChangeInfo.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
-import { WORDPROCESSINGML_NAMESPACE_URIS, cloneElement, findChild, findChildByNamespaceUri, findChildren, findChildrenByNamespaceUri, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseNumberingLevelAttribute, parseNumericAttribute, selectAlternateContentBranch } from "./xmlParser.js";
+import { WORDPROCESSINGML_NAMESPACE_URIS, cloneElement, findChild, findChildByNamespaceUri, findChildren, findChildrenByNamespaceUri, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, getNamespaceUri, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffAttribute, selectAlternateContentBranch } from "./xmlParser.js";
 import { panic } from "better-result";
-import { PARAGRAPH_MARK_CHANGE_KINDS, REVIEW_CARRIERS } from "@stll/docx-core/model";
+import { BIDI_CONTROLS, PARAGRAPH_MARK_CHANGE_KINDS, REVIEW_CARRIERS } from "@stll/docx-core/model";
 //#region src/docx/paragraphParser.ts
 const FOLIO_REVIEW_HISTORY_NAMESPACES = /* @__PURE__ */ new Set(["urn:stella:folio:review-history:1"]);
 /**
@@ -36,63 +38,6 @@ function extractMathText(el) {
 	return text;
 }
 /**
-* Parse color value from attributes
-*/
-function parseColorValue(rgb, themeColor, themeTint, themeShade) {
-	const color = {};
-	if (rgb && rgb !== "auto") color.rgb = rgb;
-	else if (rgb === "auto") color.auto = true;
-	const validatedThemeColor = narrowEnum(themeColor, ThemeColorSlotSchema);
-	if (validatedThemeColor) color.themeColor = validatedThemeColor;
-	if (themeTint) color.themeTint = themeTint;
-	if (themeShade) color.themeShade = themeShade;
-	return color;
-}
-/**
-* Parse shading properties (w:shd)
-*/
-function parseShadingProperties(shd) {
-	if (!shd) return;
-	const props = {};
-	const color = getAttribute(shd, "w", "color");
-	if (color && color !== "auto" && isValidHexColor(color)) props.color = { rgb: color };
-	const fill = getAttribute(shd, "w", "fill");
-	if (fill && fill !== "auto" && isValidHexColor(fill)) props.fill = { rgb: fill };
-	const validatedThemeFill = narrowEnum(getAttribute(shd, "w", "themeFill"), ThemeColorSlotSchema);
-	if (validatedThemeFill) {
-		props.fill = props.fill || {};
-		props.fill.themeColor = validatedThemeFill;
-	}
-	const themeFillTint = getAttribute(shd, "w", "themeFillTint");
-	if (themeFillTint && props.fill) props.fill.themeTint = themeFillTint;
-	const themeFillShade = getAttribute(shd, "w", "themeFillShade");
-	if (themeFillShade && props.fill) props.fill.themeShade = themeFillShade;
-	const pattern = narrowEnum(getAttribute(shd, "w", "val"), ShadingPatternSchema);
-	if (pattern) props.pattern = pattern;
-	return Object.keys(props).length > 0 ? props : void 0;
-}
-/**
-* Parse border specification (w:top, w:bottom, w:left, w:right, etc.)
-*/
-function parseBorderSpec(border) {
-	if (!border) return;
-	const rawStyle = getAttribute(border, "w", "val");
-	if (!rawStyle) return;
-	const spec = { style: narrowEnum(rawStyle, BorderStyleSchema) ?? rawStyle };
-	const colorVal = getAttribute(border, "w", "color");
-	const themeColor = getAttribute(border, "w", "themeColor");
-	if (colorVal || themeColor) spec.color = parseColorValue(colorVal, themeColor, getAttribute(border, "w", "themeTint"), getAttribute(border, "w", "themeShade"));
-	const sz = parseNumericAttribute(border, "w", "sz");
-	if (sz !== void 0) spec.size = sz;
-	const space = parseNumericAttribute(border, "w", "space");
-	if (space !== void 0) spec.space = space;
-	const shadowAttr = getAttribute(border, "w", "shadow");
-	if (shadowAttr) spec.shadow = shadowAttr === "1" || shadowAttr === "true";
-	const frame = getAttribute(border, "w", "frame");
-	if (frame) spec.frame = frame === "1" || frame === "true";
-	return spec;
-}
-/**
 * Parse tab stops (w:tabs)
 */
 function parseTabStops(tabs) {
@@ -273,10 +218,10 @@ function parseParagraphProperties(pPr, theme, styles) {
 		if (spacingExplicit.before || spacingExplicit.after) formatting.spacingExplicit = spacingExplicit;
 		const lineRule = narrowEnum(getAttribute(spacing, "w", "lineRule"), LineSpacingRuleSchema);
 		if (lineRule) formatting.lineSpacingRule = lineRule;
-		const beforeAuto = getAttribute(spacing, "w", "beforeAutospacing");
-		if (beforeAuto) formatting.beforeAutospacing = beforeAuto === "1" || beforeAuto === "true";
-		const afterAuto = getAttribute(spacing, "w", "afterAutospacing");
-		if (afterAuto) formatting.afterAutospacing = afterAuto === "1" || afterAuto === "true";
+		const beforeAutospacing = parseOnOffAttribute(spacing, "w", "beforeAutospacing");
+		if (beforeAutospacing !== void 0) formatting.beforeAutospacing = beforeAutospacing;
+		const afterAutospacing = parseOnOffAttribute(spacing, "w", "afterAutospacing");
+		if (afterAutospacing !== void 0) formatting.afterAutospacing = afterAutospacing;
 	}
 	const ind = propertyChildren.ind;
 	if (ind) {
@@ -315,7 +260,7 @@ function parseParagraphProperties(pPr, theme, styles) {
 	}
 	const shd = propertyChildren.shd;
 	if (shd) {
-		const shadingResult = parseShadingProperties(shd);
+		const shadingResult = parseShading(shd);
 		if (shadingResult !== void 0) formatting.shading = shadingResult;
 	}
 	const tabs = propertyChildren.tabs;
@@ -348,6 +293,8 @@ function parseParagraphProperties(pPr, theme, styles) {
 				if (val !== void 0) formatting.numPr.ilvl = val;
 			}
 		}
+		const numberingChange = findChild(numPr, "w", "numberingChange");
+		if (numberingChange) formatting.numberingChangeXml = captureVerbatimXml(numberingChange);
 	}
 	const outlineLvl = propertyChildren.outlineLvl;
 	if (outlineLvl) {
@@ -653,6 +600,27 @@ const hyperlinkRevisionWrapperType = (node) => {
 		default: return;
 	}
 };
+const OMML_NAMESPACE = "http://schemas.openxmlformats.org/officeDocument/2006/math";
+/**
+* A bare OMML element as an inline equation, or nothing when the child is not one.
+*
+* `m:oMath` and `m:oMathPara` have branches of their own. This is for the rest
+* of `m:EG_OMathMathElements` — `m:f`, `m:acc`, `m:rad` and their siblings —
+* which the schema admits wherever `m:oMath` is admitted. They carry no
+* structure the editable model holds, so they travel as the markup they
+* arrived as, exactly like the equations that do have a wrapper.
+*/
+const mathContentOf = (child) => {
+	if (getNamespaceUri(child) !== OMML_NAMESPACE) return;
+	const equation = {
+		type: "mathEquation",
+		display: "inline",
+		ommlXml: captureVerbatimXml(child)
+	};
+	const plainText = extractMathText(child);
+	if (plainText) equation.plainText = plainText;
+	return equation;
+};
 const isHyperlinkChildContent = (content) => content.type === "run" || content.type === "bookmarkStart" || content.type === "bookmarkEnd";
 /**
 * A `w:hyperlink` as paragraph content, with any revision wrapper it holds
@@ -742,10 +710,8 @@ function parseSimpleField(node, styles, theme, rels, media, rootXmlns = {}) {
 		fieldType: parseFieldType(instruction),
 		content: []
 	};
-	const fldLock = getAttribute(node, "w", "fldLock");
-	if (fldLock === "1" || fldLock === "true") field.fldLock = true;
-	const dirty = getAttribute(node, "w", "dirty");
-	if (dirty === "1" || dirty === "true") field.dirty = true;
+	if (parseOnOffAttribute(node, "w", "fldLock") === true) field.fldLock = true;
+	if (parseOnOffAttribute(node, "w", "dirty") === true) field.dirty = true;
 	const inScopeXmlns = mergeXmlnsDeclarations(rootXmlns, node);
 	const children = getChildElements(node);
 	for (const child of children) {
@@ -986,57 +952,53 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 				contents.push(...inner);
 				break;
 			}
-			case "moveFromRangeStart": {
-				const id = Number.parseInt(getAttribute(child, "w", "id") ?? "0", 10);
-				const name = getAttribute(child, "w", "name") ?? "";
+			case "moveFromRangeStart":
 				contents.push({
 					type: "moveFromRangeStart",
-					id,
-					name
+					...parseMoveBookmarkMarker(child)
 				});
 				break;
-			}
-			case "moveFromRangeEnd": {
-				const id = Number.parseInt(getAttribute(child, "w", "id") ?? "0", 10);
+			case "moveFromRangeEnd":
 				contents.push({
 					type: "moveFromRangeEnd",
-					id
+					...parseMarkupRangeMarker(child)
 				});
 				break;
-			}
-			case "moveToRangeStart": {
-				const id = Number.parseInt(getAttribute(child, "w", "id") ?? "0", 10);
-				const name = getAttribute(child, "w", "name") ?? "";
+			case "moveToRangeStart":
 				contents.push({
 					type: "moveToRangeStart",
-					id,
-					name
+					...parseMoveBookmarkMarker(child)
 				});
 				break;
-			}
-			case "moveToRangeEnd": {
-				const id = Number.parseInt(getAttribute(child, "w", "id") ?? "0", 10);
+			case "moveToRangeEnd":
 				contents.push({
 					type: "moveToRangeEnd",
-					id
+					...parseMarkupRangeMarker(child)
 				});
 				break;
-			}
-			case "commentRangeStart": {
-				const commentId = Number.parseInt(getAttribute(child, "w", "id") ?? "0", 10);
+			case "commentRangeStart":
 				contents.push({
 					type: "commentRangeStart",
-					id: commentId
+					...parseMarkupRangeMarker(child)
 				});
 				break;
-			}
-			case "commentRangeEnd": {
-				const commentId = Number.parseInt(getAttribute(child, "w", "id") ?? "0", 10);
+			case "commentRangeEnd":
 				contents.push({
 					type: "commentRangeEnd",
-					id: commentId
+					...parseMarkupRangeMarker(child)
 				});
 				break;
+			case "bdo":
+			case "dir": {
+				const direction = getAttribute(child, "w", "val");
+				const wrapper = {
+					type: "bidiWrapper",
+					control: localName === "bdo" ? BIDI_CONTROLS.override : BIDI_CONTROLS.embedding,
+					content: parseParagraphContents(child, styles, theme, null, rels, media, trackedContext, inScopeXmlns)
+				};
+				if (direction === "ltr" || direction === "rtl") wrapper.direction = direction;
+				contents.push(wrapper);
+				break;
 			}
 			case "oMath":
 			case "oMathPara": {
@@ -1052,7 +1014,11 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 				contents.push(mathEq);
 				break;
 			}
-			default: break;
+			default: {
+				const mathElement = mathContentOf(child);
+				if (mathElement !== void 0) contents.push(mathElement);
+				break;
+			}
 		}
 	}
 	if (inComplexField && afterSeparator) contents.push(...complexFieldResultRuns);
@@ -1270,7 +1236,8 @@ const getParagraphContentText = (content) => {
 		case "complexField": return content.fieldResult.map(getRunText).join("");
 		case "inlineSdt": return content.content.map(getParagraphContentText).join("");
 		case "insertion":
-		case "moveTo": return content.content.map(getParagraphContentText).join("");
+		case "moveTo":
+		case "bidiWrapper": return content.content.map(getParagraphContentText).join("");
 		case "deletion":
 		case "moveFrom": return "";
 		case "mathEquation": return content.plainText ?? "";

package/dist/docx/paragraphPropertySource.js

@@ -265,6 +265,7 @@ const tableCellBlockTraversalByType = {
 	table: "table"
 };
 const tableCellParagraphContentTraversalByType = {
+	bidiWrapper: "content",
 	bookmarkEnd: "leaf",
 	bookmarkStart: "leaf",
 	commentRangeEnd: "leaf",

package/dist/docx/paragraphTraversal.d.ts

@@ -9,6 +9,42 @@ type DocxParagraphSurfaces = {
 };
 /** Visit every run directly owned by a paragraph's inline-content tree. */
 declare const visitParagraphRuns: (paragraph: document_d_exports.Paragraph, visit: (run: document_d_exports.Run) => void) => void;
+/**
+ * One position in an inline-content array: the array itself, the index, and
+ * what sits there. A normaliser that drops or rewrites a marker needs the
+ * array and the index, not only the value.
+ */
+type InlineContentSlot = {
+  content: document_d_exports.ParagraphContent[];
+  index: number;
+  item: document_d_exports.ParagraphContent;
+};
+/**
+ * Visit every inline-content position a paragraph owns, in document order,
+ * descending through every wrapper that is transparent to a range marker.
+ *
+ * The model validator walks the whole inline tree; a normaliser that walks
+ * only `paragraph.content` sees a different document from the one the
+ * validator judges, and a marker inside `w:ins`, `w:hyperlink`, `w:sdt`,
+ * `w:bdo` or `w:dir` then reaches the validator unnormalised. Both sides read
+ * the tree through this one traversal so they cannot disagree again.
+ *
+ * A complex field's runs are skipped: `fieldCode` and `fieldResult` hold runs
+ * only, and a run is not a marker position.
+ */
+declare const visitInlineContentSlots: (paragraph: document_d_exports.Paragraph, visit: (slot: InlineContentSlot) => void) => void;
+/**
+ * Positions marked for removal, per inline-content array.
+ *
+ * Removal shifts every later index in that array, so a normaliser records the
+ * positions while it reads and drops them once, after it has finished reading.
+ */
+declare class InlineContentRemovals {
+  #private;
+  mark({ content, index }: Pick<InlineContentSlot, "content" | "index">): void;
+  /** Applies every marked removal and answers how many items were dropped. */
+  apply(): number;
+}
 declare const visitDocxParagraphs: ({ documentBody, headers, footers, footnotes, endnotes }: DocxParagraphSurfaces, visit: (paragraph: document_d_exports.Paragraph) => void) => void;
 //#endregion
-export { DocxParagraphSurfaces, visitDocxParagraphs, visitParagraphRuns };
+export { DocxParagraphSurfaces, InlineContentRemovals, InlineContentSlot, visitDocxParagraphs, visitInlineContentSlots, visitParagraphRuns };

package/dist/docx/paragraphTraversal.js

@@ -1,3 +1,4 @@
+import { panic } from "better-result";
 //#region src/docx/paragraphTraversal.ts
 /** Visit every run directly owned by a paragraph's inline-content tree. */
 const visitParagraphRuns = (paragraph, visit) => {
@@ -15,6 +16,7 @@ const visitParagraphRuns = (paragraph, visit) => {
 			case "moveFrom":
 			case "moveTo":
 			case "inlineSdt":
+			case "bidiWrapper":
 				for (const child of content.content) visitParagraphContent(child);
 				return;
 			case "complexField":
@@ -36,6 +38,87 @@ const visitParagraphRuns = (paragraph, visit) => {
 	};
 	for (const content of paragraph.content) visitParagraphContent(content);
 };
+/**
+* Visit every inline-content position a paragraph owns, in document order,
+* descending through every wrapper that is transparent to a range marker.
+*
+* The model validator walks the whole inline tree; a normaliser that walks
+* only `paragraph.content` sees a different document from the one the
+* validator judges, and a marker inside `w:ins`, `w:hyperlink`, `w:sdt`,
+* `w:bdo` or `w:dir` then reaches the validator unnormalised. Both sides read
+* the tree through this one traversal so they cannot disagree again.
+*
+* A complex field's runs are skipped: `fieldCode` and `fieldResult` hold runs
+* only, and a run is not a marker position.
+*/
+const visitInlineContentSlots = (paragraph, visit) => {
+	const visitContent = (content) => {
+		for (const [index, item] of content.entries()) {
+			visit({
+				content,
+				index,
+				item
+			});
+			switch (item.type) {
+				case "hyperlink":
+					visitContent(item.children);
+					break;
+				case "simpleField":
+				case "inlineSdt":
+				case "insertion":
+				case "deletion":
+				case "moveFrom":
+				case "moveTo":
+				case "bidiWrapper":
+					visitContent(item.content);
+					break;
+				case "run":
+				case "complexField":
+				case "bookmarkStart":
+				case "bookmarkEnd":
+				case "commentRangeStart":
+				case "commentRangeEnd":
+				case "commentReference":
+				case "moveFromRangeStart":
+				case "moveFromRangeEnd":
+				case "moveToRangeStart":
+				case "moveToRangeEnd":
+				case "mathEquation": break;
+				default: panic(`Unsupported paragraph content: ${JSON.stringify(item)}`);
+			}
+		}
+	};
+	visitContent(paragraph.content);
+};
+/**
+* Positions marked for removal, per inline-content array.
+*
+* Removal shifts every later index in that array, so a normaliser records the
+* positions while it reads and drops them once, after it has finished reading.
+*/
+var InlineContentRemovals = class {
+	#byContent = /* @__PURE__ */ new Map();
+	mark({ content, index }) {
+		const indexes = this.#byContent.get(content);
+		if (indexes) {
+			indexes.add(index);
+			return;
+		}
+		this.#byContent.set(content, /* @__PURE__ */ new Set([index]));
+	}
+	/** Applies every marked removal and answers how many items were dropped. */
+	apply() {
+		let removed = 0;
+		for (const [content, indexes] of this.#byContent) {
+			if (indexes.size === 0) continue;
+			const next = content.filter((_, index) => !indexes.has(index));
+			removed += content.length - next.length;
+			content.length = 0;
+			content.push(...next);
+		}
+		return removed;
+	}
+};
 const visitDocxParagraphs = ({ documentBody, headers, footers, footnotes, endnotes }, visit) => {
 	const seenParagraphs = /* @__PURE__ */ new WeakSet();
 	const visitParagraph = (paragraph) => {
@@ -76,4 +159,4 @@ const visitDocxParagraphs = ({ documentBody, headers, footers, footnotes, endnot
 	for (const comment of documentBody.comments ?? []) for (const paragraph of comment.content) visitParagraph(paragraph);
 };
 //#endregion
-export { visitDocxParagraphs, visitParagraphRuns };
+export { InlineContentRemovals, visitDocxParagraphs, visitInlineContentSlots, visitParagraphRuns };