@stll/folio-core 0.46.0 → 0.47.0

package/dist/document-operations.js

@@ -1,4 +1,5 @@
 import { applyFolioAIEditOperations, previewFolioAIEditOperations } from "./ai-edits/apply.js";
+import { isNumberingReference } from "./docx/numberingReference.js";
 import { LINE_SPACING_RULE_VALUES, PARAGRAPH_ALIGNMENT_VALUES } from "./types/documentEnumValues.js";
 import { TaggedError } from "better-result";
 import { sanitizeXmlCharacters } from "@stll/docx-core";
@@ -299,7 +300,7 @@ const readClearableNumbering = ({ value, key, path }) => {
 	if (!isPlainObject(candidate)) return invalidBatch(numberingPath, "expected an object or null when provided");
 	assertAllowedKeys(candidate, numberingPath, ["numId", "level"]);
 	const numId = readNonNegativeInteger(candidate, "numId", numberingPath);
-	if (numId === 0) return invalidBatch(`${numberingPath}.numId`, "expected a positive integer");
+	if (!isNumberingReference(numId)) return invalidBatch(`${numberingPath}.numId`, "expected a positive integer");
 	return {
 		numId,
 		level: readNonNegativeInteger(candidate, "level", numberingPath)

package/dist/docx/attributeRemainder.d.ts

@@ -1,6 +1,14 @@
+import { ModelledAttributes } from "./propertyElementAttributes.js";
 import { XmlElement } from "./xmlParser.js";
 import { PreservedAttribute } from "@stll/docx-core/model";
 //#region src/docx/attributeRemainder.d.ts
+declare const InvalidPreservedAttributeError_base: import("better-result").TaggedErrorClass<"InvalidPreservedAttributeError">;
+declare class InvalidPreservedAttributeError extends InvalidPreservedAttributeError_base<{
+  message: string;
+  name: string;
+}> {}
+/** Whether an attribute remainder can be emitted under a bound canonical name. */
+declare const isSerializablePreservedAttribute: ({ namespace, name }: Pick<PreservedAttribute, "namespace" | "name">) => boolean;
 /**
  * The modelled set of an element whose serializer writes no attribute at all.
  *
@@ -10,6 +18,18 @@ import { PreservedAttribute } from "@stll/docx-core/model";
  * one of them gains a modelled attribute.
  */
 declare const NO_MODELLED_ATTRIBUTES: ReadonlySet<string>;
+/**
+ * What a part's root element states rather than carries, so the remainder skips it.
+ *
+ * `mc:Ignorable` is a projection of the root's own `xmlns:*` bindings — it
+ * lists which of them a consumer may skip — and `serializePartElement` derives
+ * both from the prefixes the rebuilt body actually uses. Replaying the
+ * source's would name prefixes the rebuilt root does not bind, which no
+ * consumer accepts, and the writer appends its own, so the part would carry
+ * the attribute twice. This is the same rule namespace declarations already
+ * follow, one attribute further on.
+ */
+declare const DERIVED_PART_ROOT_ATTRIBUTES: ReadonlySet<string>;
 type AttributeRemainderOptions = {
   /** The element, as the source wrote it. */
   element: XmlElement;
@@ -31,6 +51,19 @@ type AttributeRemainderOptions = {
  *   in the model.
  */
 declare const attributeRemainder: ({ element, modelled }: AttributeRemainderOptions) => PreservedAttribute[] | undefined;
+/**
+ * The remainder of an attribute bag, with the modelled set derived from the
+ * record's own fields.
+ *
+ * `w:ind`, `w:spacing`, `w:framePr`, `w:tab`, a border side and `w:shd` are
+ * bags rather than containers: the child dispatcher decides each of them
+ * whole, so an attribute the record has no field for is kept only while the
+ * reader takes nothing from the element at all. Passing the record's table
+ * from `propertyElementAttributes.ts` rather than a set spelled at the call
+ * site is what keeps the predicate derived from the model: a field added
+ * without an attribute to name does not compile.
+ */
+declare const readAttributeBag: (element: XmlElement, modelled: ModelledAttributes<string>) => PreservedAttribute[] | undefined;
 /**
  * The element's attributes, modelled first and the remainder after them.
  *
@@ -40,4 +73,4 @@ declare const attributeRemainder: ({ element, modelled }: AttributeRemainderOpti
  */
 declare const serializePreservedAttributes: (modelled: readonly string[], preserved: readonly PreservedAttribute[] | undefined) => string[];
 //#endregion
-export { NO_MODELLED_ATTRIBUTES, attributeRemainder, serializePreservedAttributes };
+export { DERIVED_PART_ROOT_ATTRIBUTES, InvalidPreservedAttributeError, NO_MODELLED_ATTRIBUTES, attributeRemainder, isSerializablePreservedAttribute, readAttributeBag, serializePreservedAttributes };

package/dist/docx/attributeRemainder.js

@@ -1,9 +1,15 @@
+import { modelledAttributeNames } from "./propertyElementAttributes.js";
 import { OOXML_NAMESPACES } from "./serializer/partNamespaces.js";
 import { getLocalName, resolveAttributeNamespaceUri } from "./xmlParser.js";
+import { TaggedError } from "better-result";
 import { escapeXmlAttribute } from "@stll/docx-core";
 //#region src/docx/attributeRemainder.ts
 /** Namespace URI to the prefix a rebuilt part binds for it. */
 const CANONICAL_PREFIX = new Map(Object.entries(OOXML_NAMESPACES).map(([prefix, { uri }]) => [uri, prefix]));
+const XML_LOCAL_NAME = /^[\p{L}_][\p{L}\p{M}\p{N}._\-\u{00B7}\u{203F}-\u{2040}]*$/u;
+var InvalidPreservedAttributeError = class extends TaggedError("InvalidPreservedAttributeError") {};
+/** Whether an attribute remainder can be emitted under a bound canonical name. */
+const isSerializablePreservedAttribute = ({ namespace, name }) => name !== "xmlns" && XML_LOCAL_NAME.test(name) && (namespace === void 0 || CANONICAL_PREFIX.has(namespace));
 /**
 * The modelled set of an element whose serializer writes no attribute at all.
 *
@@ -14,6 +20,18 @@ const CANONICAL_PREFIX = new Map(Object.entries(OOXML_NAMESPACES).map(([prefix,
 */
 const NO_MODELLED_ATTRIBUTES = /* @__PURE__ */ new Set();
 /**
+* What a part's root element states rather than carries, so the remainder skips it.
+*
+* `mc:Ignorable` is a projection of the root's own `xmlns:*` bindings — it
+* lists which of them a consumer may skip — and `serializePartElement` derives
+* both from the prefixes the rebuilt body actually uses. Replaying the
+* source's would name prefixes the rebuilt root does not bind, which no
+* consumer accepts, and the writer appends its own, so the part would carry
+* the attribute twice. This is the same rule namespace declarations already
+* follow, one attribute further on.
+*/
+const DERIVED_PART_ROOT_ATTRIBUTES = /* @__PURE__ */ new Set(["Ignorable"]);
+/**
 * Every attribute on the element the model has no field for.
 *
 * @returns the remainder, or `undefined` when the parser read them all — an
@@ -38,6 +56,30 @@ const attributeRemainder = ({ element, modelled }) => {
 	}
 	return remainder.length === 0 ? void 0 : remainder;
 };
+const NAMES_BY_TABLE = /* @__PURE__ */ new WeakMap();
+/**
+* The remainder of an attribute bag, with the modelled set derived from the
+* record's own fields.
+*
+* `w:ind`, `w:spacing`, `w:framePr`, `w:tab`, a border side and `w:shd` are
+* bags rather than containers: the child dispatcher decides each of them
+* whole, so an attribute the record has no field for is kept only while the
+* reader takes nothing from the element at all. Passing the record's table
+* from `propertyElementAttributes.ts` rather than a set spelled at the call
+* site is what keeps the predicate derived from the model: a field added
+* without an attribute to name does not compile.
+*/
+const readAttributeBag = (element, modelled) => {
+	let names = NAMES_BY_TABLE.get(modelled);
+	if (names === void 0) {
+		names = new Set(modelledAttributeNames(modelled));
+		NAMES_BY_TABLE.set(modelled, names);
+	}
+	return attributeRemainder({
+		element,
+		modelled: names
+	});
+};
 /** The name a fragment such as `w14:paraId="1F2E"` writes. */
 const spelledName = (fragment) => fragment.slice(0, fragment.indexOf("="));
 /**
@@ -51,9 +93,13 @@ const serializePreservedAttributes = (modelled, preserved) => {
 	if (preserved === void 0 || preserved.length === 0) return [...modelled];
 	const written = new Set(modelled.map(spelledName));
 	const fragments = [...modelled];
-	for (const { namespace, name, value } of preserved) {
+	for (const attribute of preserved) {
+		const { namespace, name, value } = attribute;
+		if (!isSerializablePreservedAttribute(attribute)) throw new InvalidPreservedAttributeError({
+			message: "A preserved attribute must have an XML local name and a bound namespace",
+			name
+		});
 		const prefix = namespace === void 0 ? void 0 : CANONICAL_PREFIX.get(namespace);
-		if (namespace !== void 0 && prefix === void 0) continue;
 		const spelling = prefix === void 0 ? name : `${prefix}:${name}`;
 		if (written.has(spelling)) continue;
 		written.add(spelling);
@@ -62,4 +108,4 @@ const serializePreservedAttributes = (modelled, preserved) => {
 	return fragments;
 };
 //#endregion
-export { NO_MODELLED_ATTRIBUTES, attributeRemainder, serializePreservedAttributes };
+export { DERIVED_PART_ROOT_ATTRIBUTES, InvalidPreservedAttributeError, NO_MODELLED_ATTRIBUTES, attributeRemainder, isSerializablePreservedAttribute, readAttributeBag, serializePreservedAttributes };

package/dist/docx/blockContentParser.d.ts

@@ -1,11 +1,13 @@
 import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
+import { ParseContext } from "./parseContext.js";
 import { XmlElement } from "./xmlParser.js";
 import { StyleMap } from "./styleParser.js";
 //#region src/docx/blockContentParser.d.ts
 type ParseBlockContentOptions = {
   inHeaderFooter?: boolean;
   rootXmlns?: Record<string, string>;
+  context?: ParseContext | undefined;
 };
 declare const parseBlockContent: (parent: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, numbering: NumberingMap | null, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, options?: ParseBlockContentOptions) => document_d_exports.BlockContent[];
 //#endregion

package/dist/docx/blockContentParser.js

@@ -1,15 +1,13 @@
 import { parseBookmarkEnd, parseBookmarkStart } from "./bookmarkParser.js";
-import { appendBookmarkMarkerToLastParagraphInBlocks, prependBookmarkMarkersToFirstParagraphInBlocks } from "./bookmarkPlacement.js";
 import { convertBulletToUnicode } from "./bulletMarkers.js";
-import { CAPTURE, OWNED_ELSEWHERE, dispatchChildren, withPreservedChildren } from "./containerChildren.js";
+import { CAPTURE, dispatchChildren, ownedElsewhere, withPreservedChildren } from "./containerChildren.js";
 import { isNumberingReference } from "./numberingReference.js";
 import { formatOoxmlCounter } from "./ooxmlCounterFormatter.js";
 import { parseParagraph } from "./paragraphParser.js";
 import { enrichParagraphTextBoxes } from "./paragraphTextBoxEnrichment.js";
-import { parseSdtProperties } from "./sdtProperties.js";
+import { captureSdtSiblingMarkers, parseSdtProperties } from "./sdtProperties.js";
 import { parseTable } from "./tableParser.js";
-import { captureVerbatimXml } from "./verbatimCapture.js";
-import { findChild, getLocalName, mergeXmlnsDeclarations, selectAlternateContentBranch } from "./xmlParser.js";
+import { findWordprocessingChild, mergeXmlnsDeclarations, selectAlternateContentBranch } from "./xmlParser.js";
 //#region src/docx/blockContentParser.ts
 const computeListMarker = (paragraph, { numbering, listCounters, abstractCounters, restartedNumIds, previousList }) => {
 	const listRendering = paragraph.listRendering;
@@ -89,6 +87,29 @@ const withContainerXmlns = (state, element) => ({
 		rootXmlns: mergeXmlnsDeclarations(state.options?.rootXmlns ?? {}, element)
 	}
 });
+/**
+* The two block children this walk skips, and who reads them instead.
+*
+* Both are read off the container element rather than met here: the body's own
+* `w:sectPr` by the document parser, a cell's `w:tcPr` by the table parser.
+* They are in this map because it is total over the union every block
+* container shares, not because this walk reads them.
+*
+* Declared at module scope so the claim is registered when the module loads,
+* rather than the first time a document is parsed.
+*/
+const BLOCK_CHILD_OWNERS = {
+	sectPr: ownedElsewhere({
+		container: "block-content",
+		child: "sectPr",
+		reader: "documentParser#parseDocumentBody"
+	}),
+	tcPr: ownedElsewhere({
+		container: "block-content",
+		child: "tcPr",
+		reader: "tableParser#parseTableCell"
+	})
+};
 const parseBlockContent = (parent, styles, theme, numbering, rels, media, options) => parseBlockContentWithState(parent, styles, theme, numbering, rels, media, {
 	listCounters: /* @__PURE__ */ new Map(),
 	abstractCounters: /* @__PURE__ */ new Map(),
@@ -105,11 +126,10 @@ const parseBlockContent = (parent, styles, theme, numbering, rels, media, option
 });
 const parseBlockContentWithState = (parent, styles, theme, numbering, rels, media, state) => {
 	const modelled = [];
-	const pendingBookmarkMarkers = [];
-	const content = withPreservedChildren(modelled, dispatchChildren({
+	return withPreservedChildren(modelled, dispatchChildren({
 		element: parent,
 		container: "block-content",
-		modelledCount: () => modelled.length,
+		capturePosition: () => modelled.length,
 		undeclared: { AlternateContent: (child) => {
 			const selectedBranch = selectAlternateContentBranch(child);
 			if (!selectedBranch) return;
@@ -117,9 +137,11 @@ const parseBlockContentWithState = (parent, styles, theme, numbering, rels, medi
 		} },
 		handlers: {
 			p: (child) => {
-				const paragraph = parseParagraph(child, styles, theme, numbering, rels, media, state.options);
-				prependPendingBookmarkMarkers(paragraph, pendingBookmarkMarkers);
-				enrichParagraphTextBoxes(paragraph, child, styles, theme, numbering, rels, media, parseTable);
+				const paragraph = parseParagraph(child, styles, theme, numbering, rels, media, {
+					...state.options,
+					runConsolidation: "deferred"
+				});
+				enrichParagraphTextBoxes(paragraph, child, styles, theme, numbering, rels, media, parseTable, state.options?.context);
 				computeListMarker(paragraph, {
 					numbering,
 					listCounters: state.listCounters,
@@ -132,22 +154,18 @@ const parseBlockContentWithState = (parent, styles, theme, numbering, rels, medi
 			tbl: (child) => {
 				const table = parseTable(child, styles, theme, numbering, rels, media, state.options);
 				if (!table) return;
-				if (prependBookmarkMarkersToFirstParagraphInBlocks([table], pendingBookmarkMarkers)) pendingBookmarkMarkers.length = 0;
 				modelled.push(table);
 			},
 			sdt: (child) => {
-				const blockSdt = parseBlockSdt(child, styles, theme, numbering, rels, media, state);
-				if (prependBookmarkMarkersToFirstParagraphInBlocks(blockSdt.content, pendingBookmarkMarkers)) pendingBookmarkMarkers.length = 0;
-				modelled.push(blockSdt);
+				modelled.push(parseBlockSdt(child, styles, theme, numbering, rels, media, state));
 			},
 			bookmarkStart: (child) => {
-				collectBookmarkMarker(child, "bookmarkStart", modelled, pendingBookmarkMarkers);
+				modelled.push(parseBookmarkStart(child));
 			},
 			bookmarkEnd: (child) => {
-				collectBookmarkMarker(child, "bookmarkEnd", modelled, pendingBookmarkMarkers);
+				modelled.push(parseBookmarkEnd(child));
 			},
-			sectPr: OWNED_ELSEWHERE,
-			tcPr: OWNED_ELSEWHERE,
+			...BLOCK_CHILD_OWNERS,
 			altChunk: CAPTURE,
 			commentRangeEnd: CAPTURE,
 			commentRangeStart: CAPTURE,
@@ -176,15 +194,10 @@ const parseBlockContentWithState = (parent, styles, theme, numbering, rels, medi
 		type: "preservedBlock",
 		xml
 	}));
-	if (pendingBookmarkMarkers.length > 0) content.push({
-		type: "paragraph",
-		content: [...pendingBookmarkMarkers]
-	});
-	return content;
 };
 const parseBlockSdt = (child, styles, theme, numbering, rels, media, state) => {
-	const sdtContent = findChild(child, "w", "sdtContent");
-	const properties = parseSdtProperties(findChild(child, "w", "sdtPr"), findChild(child, "w", "sdtEndPr"));
+	const sdtContent = findWordprocessingChild(child, "sdtContent");
+	const properties = parseSdtProperties(findWordprocessingChild(child, "sdtPr"), findWordprocessingChild(child, "sdtEndPr"));
 	const captured = captureSdtSiblingMarkers(child);
 	if (captured.before.length > 0) properties.rawSdtChildrenBeforeContent = captured.before;
 	if (captured.after.length > 0) properties.rawSdtChildrenAfterContent = captured.after;
@@ -194,46 +207,5 @@ const parseBlockSdt = (child, styles, theme, numbering, rels, media, state) => {
 		content: sdtContent ? parseBlockContentWithState(sdtContent, styles, theme, numbering, rels, media, withContainerXmlns(withContainerXmlns(state, child), sdtContent)) : []
 	};
 };
-const collectBookmarkMarker = (child, localName, content, pending) => {
-	const marker = localName === "bookmarkStart" ? parseBookmarkStart(child) : parseBookmarkEnd(child);
-	if (!appendBookmarkMarkerToLastParagraphInBlocks(content, marker)) pending.push(marker);
-};
-/**
-* Walk a `<w:sdt>` element's direct children and return the verbatim XML
-* for every child that is NOT `<w:sdtPr>`, `<w:sdtEndPr>`, or
-* `<w:sdtContent>` — split by position relative to sdtContent.
-*
-* Per MS-OE376 §2.5.2.30, Word emits 16 range-marker elements (bookmark,
-* comment, custom XML, tracked-change ranges) as direct sdt siblings of
-* sdtContent. Without preserving them, a comment thread or tracked
-* change that crosses an SDT boundary loses a delimiter when folio
-* serializes the parsed model back out.
-*/
-const captureSdtSiblingMarkers = (sdt) => {
-	const beforeParts = [];
-	const afterParts = [];
-	let sawContent = false;
-	for (const ch of sdt.elements ?? []) {
-		if (ch.type !== "element" || !ch.name) continue;
-		const local = getLocalName(ch.name);
-		if (local === "sdtPr" || local === "sdtEndPr") continue;
-		if (local === "sdtContent") {
-			sawContent = true;
-			continue;
-		}
-		const xml = captureVerbatimXml(ch);
-		if (sawContent) afterParts.push(xml);
-		else beforeParts.push(xml);
-	}
-	return {
-		before: beforeParts.join(""),
-		after: afterParts.join("")
-	};
-};
-const prependPendingBookmarkMarkers = (paragraph, pendingBookmarkMarkers) => {
-	if (pendingBookmarkMarkers.length === 0) return;
-	paragraph.content.unshift(...pendingBookmarkMarkers);
-	pendingBookmarkMarkers.length = 0;
-};
 //#endregion
 export { parseBlockContent };

package/dist/docx/blockPlainText.js

@@ -31,7 +31,9 @@ const collectBlockTexts = (blocks) => {
 		case "blockSdt":
 			texts.push(...collectBlockTexts(block.content));
 			break;
-		case "preservedBlock": break;
+		case "preservedBlock":
+		case "bookmarkStart":
+		case "bookmarkEnd": break;
 		default: panic(`Unsupported block in plain-text extraction: ${JSON.stringify(block)}`);
 	}
 	return texts;

package/dist/docx/borderParser.js

@@ -1,6 +1,8 @@
-import { BorderStyleSchema, ThemeColorSlotSchema, narrowEnum } from "./parserEnums.js";
+import { readAttributeBag } from "./attributeRemainder.js";
+import { BORDER_ATTRIBUTES } from "./propertyElementAttributes.js";
+import { parseThemeColorAttribute } from "./themeColorAttribute.js";
 import { getAttribute, parseNumericAttribute, parseOnOffAttribute } from "./xmlParser.js";
-import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
+import { PARSE_WARNING_CODES, borderStyleFrom, isBorderStyle } from "@stll/docx-core/model";
 //#region src/docx/borderParser.ts
 /**
 * The one reader for `CT_Border`, shared by the paragraph (`w:pBdr`), style,
@@ -9,21 +11,27 @@ import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 * `w:val` is `ST_Border`, whose 193 members include two distinct "no border"
 * tokens: `nil` and `none`. They are not interchangeable downstream, and an
 * explicit one overrides a border inherited from the container, so the member
-* the author wrote is preserved exactly. Members outside the model's known
-* union survive verbatim rather than collapsing to a default, which is how the
-* repo already treats `w:numFmt`, `w:suff` and `w:tab`.
+* the author wrote is preserved exactly. A token outside the enumeration is
+* kept verbatim and reported, which is how the repo already treats `w:numFmt`,
+* `w:suff` and `w:tab`.
 */
-const parseBorderColor = (border) => {
+/** `ST_HexColor`'s reserved "let the consumer decide" token, as `shadingParser` spells it. */
+const AUTOMATIC_COLOR = "auto";
+const parseBorderColor = (border, context) => {
 	const rgb = getAttribute(border, "w", "color");
 	const themeColor = getAttribute(border, "w", "themeColor");
 	const themeTint = getAttribute(border, "w", "themeTint");
 	const themeShade = getAttribute(border, "w", "themeShade");
 	if (rgb === null && themeColor === null && themeTint === null && themeShade === null) return;
 	const color = {};
-	if (rgb === "auto") color.auto = true;
+	if (rgb === AUTOMATIC_COLOR) color.auto = true;
 	else if (rgb) color.rgb = rgb;
-	const validatedThemeColor = narrowEnum(themeColor, ThemeColorSlotSchema);
-	if (validatedThemeColor) color.themeColor = validatedThemeColor;
+	const parsedThemeColor = parseThemeColorAttribute({
+		raw: themeColor,
+		element: border.name ?? "border",
+		context
+	});
+	if (parsedThemeColor !== void 0) color.themeColor = parsedThemeColor;
 	if (themeTint) color.themeTint = themeTint;
 	if (themeShade) color.themeShade = themeShade;
 	return color;
@@ -44,8 +52,13 @@ function parseBorderSpec(border, context) {
 		});
 		return;
 	}
-	const spec = { style: narrowEnum(rawStyle, BorderStyleSchema) ?? rawStyle };
-	const color = parseBorderColor(border);
+	if (!isBorderStyle(rawStyle)) context?.warn({
+		code: PARSE_WARNING_CODES.borderStyleOutsideEnum,
+		element: border.name ?? "border",
+		value: rawStyle
+	});
+	const spec = { style: borderStyleFrom(rawStyle) };
+	const color = parseBorderColor(border, context);
 	if (color) spec.color = color;
 	const size = parseNumericAttribute(border, "w", "sz");
 	if (size !== void 0) spec.size = size;
@@ -65,6 +78,8 @@ function parseBorderSpec(border, context) {
 	if (bottomLeftArtRelationshipId) spec.bottomLeftArtRelationshipId = bottomLeftArtRelationshipId;
 	const bottomRightArtRelationshipId = getAttribute(border, "r", "bottomRight")?.trim();
 	if (bottomRightArtRelationshipId) spec.bottomRightArtRelationshipId = bottomRightArtRelationshipId;
+	const preservedAttributes = readAttributeBag(border, BORDER_ATTRIBUTES);
+	if (preservedAttributes) spec.preservedAttributes = preservedAttributes;
 	return spec;
 }
 //#endregion

package/dist/docx/builtInStyles.d.ts

@@ -1,24 +1,16 @@
 import { document_d_exports } from "../types/document.js";
+import { OutlineLevel } from "@stll/docx-core/model";
 //#region src/docx/builtInStyles.d.ts
 /**
- * The tenth `w:outlineLvl` value. 17.3.1.20: "the val attribute … can be from
- * 0 to 9, where 9 specifically indicates that there is no outline level
- * specifically applied to this paragraph." It is a deliberate "not a heading",
- * not a tenth level. Every range test goes through
- * {@link isHeadingOutlineLevel} so the reserved value keeps one meaning across
- * the codebase.
- *
- * The same clause adds that an omitted element "is assumed to be 9". That
+ * 17.3.1.20 adds that an omitted `w:outlineLvl` "is assumed to be 9". That
  * default cannot be applied to a *style* definition, because 17.7.1 tells
  * producers not to write a property "already been set by a previous level of
  * the style hierarchy": a document that names a style `heading 1` and omits
  * the level is inheriting the consumer's built-in definition, which carries
  * level 0. An absent level therefore means "unspecified, ask the name", and
- * only a written 9 means body text.
+ * only {@link BODY_TEXT_OUTLINE_LEVEL} means body text — which is why the
+ * model keeps absence and the body-text arm apart.
  */
-declare const BODY_TEXT_OUTLINE_LEVEL = 9;
-/** True when an outline level names a heading rather than body text. */
-declare const isHeadingOutlineLevel: (level: number | null | undefined) => level is number;
 /**
  * Compare style names the way producers actually write them. The corpus shows
  * both `heading 1` (Annex L, 94.8%) and `Heading 1` (5.2%), and LibreOffice
@@ -84,8 +76,8 @@ declare const builtInTableOfContentsStyleName: (level: number) => string;
  * quadratic.
  */
 type BuiltInStyleIndex = {
-  /** The style's effective `w:outlineLvl`, including 9, or undefined. */
-  outlineLevelOf: (styleId: string | null | undefined) => number | undefined;
+  /** The style's effective `w:outlineLvl`, body text included, or undefined. */
+  outlineLevelOf: (styleId: string | null | undefined) => OutlineLevel | undefined;
   /** The zero-based level a built-in heading *name* implies, or undefined. */
   headingLevelFromNameOf: (styleId: string | null | undefined) => number | undefined;
   /** The built-in this style is, by name, or undefined for a custom style. */
@@ -113,7 +105,7 @@ declare const EMPTY_BUILT_IN_STYLE_INDEX: BuiltInStyleIndex;
  */
 type ParagraphOutlineSource = {
   styleId?: string | null | undefined;
-  outlineLevel?: number | null | undefined;
+  outlineLevel?: OutlineLevel | null | undefined;
 };
 /**
  * The heading level a paragraph carries, zero-based (`heading 1` is 0), or
@@ -162,4 +154,4 @@ declare const resolveHeadingLevel: (paragraph: ParagraphOutlineSource, index: Bu
 /** True when the paragraph's style is Word's `Quote` or `Intense Quote`. */
 declare const isQuoteStyle: (styleId: string | null | undefined, index: BuiltInStyleIndex) => boolean;
 //#endregion
-export { BODY_TEXT_OUTLINE_LEVEL, BUILT_IN_STYLE_NAME, BuiltInStyleIndex, EMPTY_BUILT_IN_STYLE_INDEX, ParagraphOutlineSource, builtInHeadingStyleName, builtInTableOfContentsStyleName, createBuiltInStyleIndex, isHeadingOutlineLevel, isQuoteStyle, normalizeStyleName, resolveHeadingLevel };
+export { BUILT_IN_STYLE_NAME, BuiltInStyleIndex, EMPTY_BUILT_IN_STYLE_INDEX, ParagraphOutlineSource, builtInHeadingStyleName, builtInTableOfContentsStyleName, createBuiltInStyleIndex, isQuoteStyle, normalizeStyleName, resolveHeadingLevel };

package/dist/docx/builtInStyles.js

@@ -1,26 +1,57 @@
 import { BUILT_IN_DEFAULT_PARAGRAPH_STYLE_NAME, resolveDefaultParagraphStyle } from "./defaultParagraphStyle.js";
+import { headingLevelOf } from "@stll/docx-core/model";
 //#region src/docx/builtInStyles.ts
 /**
-* The tenth `w:outlineLvl` value. 17.3.1.20: "the val attribute … can be from
-* 0 to 9, where 9 specifically indicates that there is no outline level
-* specifically applied to this paragraph." It is a deliberate "not a heading",
-* not a tenth level. Every range test goes through
-* {@link isHeadingOutlineLevel} so the reserved value keeps one meaning across
-* the codebase.
+* Whether a paragraph is a heading, and of which level, without reading the
+* style id.
 *
-* The same clause adds that an omitted element "is assumed to be 9". That
+* A style id is opaque. ECMA-376 17.7.4.17 says a style id "can be assigned in
+* any manner desired" and only requires it to be unique within the document,
+* and Word fills it by stripping spaces and non-ASCII characters out of the
+* *localized* UI name. The same built-in heading therefore arrives as
+* `Heading1`, `berschrift1` (de), `Nadpis1` (cs), `Titre1` (fr), `Nagwek1`
+* (pl), `Cmsor1` (hu), `Ttulo1` (es), `Overskrift1` (da) or a bare `1`.
+* Matching the id finds English Word output and nothing else, the same trap
+* `defaultParagraphStyle.ts` documents for `Normal`.
+*
+* Two signals survive localisation, in this order:
+*
+* 1. The effective `w:outlineLvl` — direct paragraph formatting, else the
+*    style chain (`styleParser` flattens `w:basedOn` into `style.pPr` per
+*    17.7.1). 17.3.1.20 gives it the range 0..9 and says it "shall be used to
+*    calculate the TOC field", which is what a `TOC \u` field and the
+*    navigation pane read. So a custom style with an outline level *is* a
+*    heading, and a heading-named style reset to
+*    {@link BODY_TEXT_OUTLINE_LEVEL} is *not* (folio's own `TOCHeading`, based
+*    on `Heading1`, does exactly that).
+* 2. The style's `w:name`. Part 1 has no normative list of built-in names, but
+*    it keys latent styles by name alone: a `w:lsdException` carries no style
+*    id, and 17.7.4.8 defines its `w:name` as "the primary name for the style
+*    which shall inherit this set of latent style property exceptions",
+*    ignored when "the current application does not know of an internal
+*    primary style with the current name". Annex L writes those names in
+*    English (`heading 1`…`heading 9`) with no locale qualification.
+*
+* The id is never a signal on its own.
+*
+* Measured over the 5,341-file public corpus: 207 files define a heading whose
+* id is not `HeadingN` while the name is English, covering 123 distinct ids;
+* only 4 documents localise the *name*, all ODF→OOXML exports (LibreOffice
+* writing its ODF display names verbatim). Names are not case-stable (5.2% are
+* `Heading 1` rather than the Annex L `heading 1`) and not space-stable
+* (LibreOffice 25.8 writes `Heading1`, and `IntenseQuote` for `Intense
+* Quote`), which is why {@link normalizeStyleName} ignores both.
+*/
+/**
+* 17.3.1.20 adds that an omitted `w:outlineLvl` "is assumed to be 9". That
 * default cannot be applied to a *style* definition, because 17.7.1 tells
 * producers not to write a property "already been set by a previous level of
 * the style hierarchy": a document that names a style `heading 1` and omits
 * the level is inheriting the consumer's built-in definition, which carries
 * level 0. An absent level therefore means "unspecified, ask the name", and
-* only a written 9 means body text.
+* only {@link BODY_TEXT_OUTLINE_LEVEL} means body text — which is why the
+* model keeps absence and the body-text arm apart.
 */
-const BODY_TEXT_OUTLINE_LEVEL = 9;
-/** The highest `w:outlineLvl` that still names a heading (outline level nine). */
-const MAX_HEADING_OUTLINE_LEVEL = 8;
-/** True when an outline level names a heading rather than body text. */
-const isHeadingOutlineLevel = (level) => typeof level === "number" && Number.isInteger(level) && level >= 0 && level <= MAX_HEADING_OUTLINE_LEVEL;
 /**
 * Compare style names the way producers actually write them. The corpus shows
 * both `heading 1` (Annex L, 94.8%) and `Heading 1` (5.2%), and LibreOffice
@@ -118,6 +149,11 @@ const inheritedOutlineLevel = (style, styleById) => {
 		current = current.basedOn === void 0 ? void 0 : styleById.get(current.basedOn);
 	}
 };
+/** The level a heading style is indexed under, or undefined if it is not one. */
+const headingLevelForIndex = (namedLevel, statedLevel) => {
+	if (namedLevel === void 0) return;
+	return statedLevel === void 0 ? namedLevel : headingLevelOf(statedLevel);
+};
 const createBuiltInStyleIndex = (styles, docDefaults) => {
 	const styleIdByHeadingLevel = /* @__PURE__ */ new Map();
 	const styleIdByTableOfContentsLevel = /* @__PURE__ */ new Map();
@@ -136,8 +172,9 @@ const createBuiltInStyleIndex = (styles, docDefaults) => {
 	for (const style of paragraphStyles) {
 		if (style.name === void 0) continue;
 		const namedLevel = headingOutlineLevelFromStyleName(style.name);
-		const headingLevel = namedLevel === void 0 ? void 0 : inheritedOutlineLevel(style, styleById) ?? docDefaultOutlineLevel ?? namedLevel;
-		if (headingLevel !== void 0 && isHeadingOutlineLevel(headingLevel) && !styleIdByHeadingLevel.has(headingLevel)) {
+		const statedLevel = inheritedOutlineLevel(style, styleById) ?? docDefaultOutlineLevel;
+		const headingLevel = headingLevelForIndex(namedLevel, statedLevel);
+		if (headingLevel !== void 0 && !styleIdByHeadingLevel.has(headingLevel)) {
 			styleIdByHeadingLevel.set(headingLevel, style.styleId);
 			continue;
 		}
@@ -227,7 +264,7 @@ const EMPTY_BUILT_IN_STYLE_INDEX = createBuiltInStyleIndex([]);
 */
 const resolveHeadingLevel = (paragraph, index) => {
 	const effective = paragraph.outlineLevel ?? index.outlineLevelOf(paragraph.styleId);
-	if (effective !== null && effective !== void 0) return isHeadingOutlineLevel(effective) ? effective : void 0;
+	if (effective !== null && effective !== void 0) return headingLevelOf(effective);
 	return index.headingLevelFromNameOf(paragraph.styleId) ?? index.undefinedBuiltInHeadingLevelOf(paragraph.styleId);
 };
 /** True when the paragraph's style is Word's `Quote` or `Intense Quote`. */
@@ -236,4 +273,4 @@ const isQuoteStyle = (styleId, index) => {
 	return name === BUILT_IN_STYLE_NAME.quote || name === BUILT_IN_STYLE_NAME.intenseQuote;
 };
 //#endregion
-export { BODY_TEXT_OUTLINE_LEVEL, BUILT_IN_STYLE_NAME, EMPTY_BUILT_IN_STYLE_INDEX, builtInHeadingStyleName, builtInTableOfContentsStyleName, createBuiltInStyleIndex, isHeadingOutlineLevel, isQuoteStyle, normalizeStyleName, resolveHeadingLevel };
+export { BUILT_IN_STYLE_NAME, EMPTY_BUILT_IN_STYLE_INDEX, builtInHeadingStyleName, builtInTableOfContentsStyleName, createBuiltInStyleIndex, isQuoteStyle, normalizeStyleName, resolveHeadingLevel };

package/dist/docx/commentAnchorIndex.js

@@ -19,7 +19,7 @@ const visitCommentMarkers = (blocks, visit) => {
 			for (const row of block.rows) for (const cell of row.cells) visitBlocks(cell.content);
 			return;
 		}
-		if (block.type === "preservedBlock") return;
+		if (block.type !== "blockSdt") return;
 		visitBlocks(block.content);
 	};
 	const visitBlocks = (nested) => {

package/dist/docx/commentParser.js

@@ -3,7 +3,7 @@ import { CAPTURE, dispatchChildren } from "./containerChildren.js";
 import { PARA_ID_NAMESPACE_URIS, paraIdAttribute, paraIdParentAttribute } from "./paraIdAttribute.js";
 import { parseParagraph } from "./paragraphParser.js";
 import { cloneParagraphWithPropertySource } from "./paragraphPropertySource.js";
-import { parseRunProperties } from "./runParser.js";
+import { RUN_PROPERTY_OWNERS, parseRunProperties } from "./runParser.js";
 import { findChild, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, parseOnOffValue, parseXml } from "./xmlParser.js";
 import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/commentParser.ts
@@ -36,7 +36,7 @@ const normalizeFirstCommentParagraph = (paragraphElement, paragraph, theme) => {
 	const firstContentElement = getChildElements(paragraphElement).find((element) => getLocalName(element.name) !== "pPr");
 	if (!firstContentElement || getLocalName(firstContentElement.name) !== "r" || !findChild(firstContentElement, "w", "annotationRef")) return { paragraph };
 	const runProperties = findChild(firstContentElement, "w", "rPr");
-	const annotationReferenceFormatting = normalizeAnnotationReferenceFormatting(runProperties ? parseRunProperties(runProperties, theme) : void 0);
+	const annotationReferenceFormatting = normalizeAnnotationReferenceFormatting(runProperties ? parseRunProperties(runProperties, theme, RUN_PROPERTY_OWNERS.standalone) : void 0);
 	const firstParsedContent = paragraph.content.at(0);
 	return {
 		paragraph: firstParsedContent?.type === "run" && firstParsedContent.content.every((item) => item.type === "preservedXml" && item.text === "") ? cloneParagraphWithPropertySource(paragraph, { content: paragraph.content.slice(1) }) : paragraph,
@@ -140,7 +140,7 @@ function parseComments(commentsXml, styles, theme, rels, media, commentsExtensib
 		const preserved = dispatchChildren({
 			element: child,
 			container: "w:comment",
-			modelledCount: () => paragraphs.length,
+			capturePosition: () => paragraphs.length,
 			handlers: {
 				p: (contentChild) => {
 					const paragraph = parseParagraph(contentChild, styles, theme, null, rels, media);

package/dist/docx/commentRangeIntegrity.js

@@ -147,7 +147,7 @@ const withoutOrphanBlockMarkers = (blocks, validCommentIds) => {
 const withoutOrphanBlockMarker = (block, validCommentIds) => {
 	if (block.type === "paragraph") return withoutOrphanParagraphMarkers(block, validCommentIds);
 	if (block.type === "table") return withoutOrphanTableMarkers(block, validCommentIds);
-	if (block.type === "preservedBlock") return block;
+	if (block.type !== "blockSdt") return block;
 	const content = withoutOrphanBlockMarkers(block.content, validCommentIds);
 	if (!content) return block;
 	return {