@stll/folio-core 0.45.0 → 0.47.0

package/dist/docx/attributeRemainder.js

@@ -0,0 +1,111 @@
+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.
+*
+* `w:r`, `w:tr` and `w:sectPr` are rebuilt as bare start tags, so everything
+* their source wrote is the remainder. Named rather than spelled `new Set()`
+* at each call site, so the claim is visible and one place has to change when
+* one of them gains a modelled attribute.
+*/
+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
+*   empty list is never written, so a fully modelled element stays identical
+*   in the model.
+*/
+const attributeRemainder = ({ element, modelled }) => {
+	const attributes = element.attributes;
+	if (!attributes) return;
+	const remainder = [];
+	for (const [spelling, value] of Object.entries(attributes)) {
+		if (value === void 0 || spelling === "xmlns" || spelling.startsWith("xmlns:")) continue;
+		const name = getLocalName(spelling);
+		if (modelled.has(name)) continue;
+		const namespace = resolveAttributeNamespaceUri(element, spelling);
+		if (namespace !== void 0 && !CANONICAL_PREFIX.has(namespace)) continue;
+		remainder.push({
+			...namespace === void 0 ? {} : { namespace },
+			name,
+			value: String(value)
+		});
+	}
+	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("="));
+/**
+* The element's attributes, modelled first and the remainder after them.
+*
+* @param modelled the fragments the serializer is about to emit, already
+*   spelled — they win a collision, because the model is the editable copy
+* @returns the fragments to write, so an element with neither writes nothing
+*/
+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 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);
+		const spelling = prefix === void 0 ? name : `${prefix}:${name}`;
+		if (written.has(spelling)) continue;
+		written.add(spelling);
+		fragments.push(`${spelling}="${escapeXmlAttribute(value)}"`);
+	}
+	return fragments;
+};
+//#endregion
+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 { StyleMap } from "./styleParser.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 { attachPendingRangeMarkers, attachTrailingRangeMarkers, isBlockRangeMarker } from "./blockRangeMarkers.js";
 import { parseBookmarkEnd, parseBookmarkStart } from "./bookmarkParser.js";
-import { appendBookmarkMarkerToLastParagraphInBlocks, prependBookmarkMarkersToFirstParagraphInBlocks } from "./bookmarkPlacement.js";
 import { convertBulletToUnicode } from "./bulletMarkers.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, getChildElements, 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(),
@@ -104,112 +125,87 @@ const parseBlockContent = (parent, styles, theme, numbering, rels, media, option
 	}
 });
 const parseBlockContentWithState = (parent, styles, theme, numbering, rels, media, state) => {
-	const content = [];
-	const children = getChildElements(parent);
-	const pendingBookmarkMarkers = [];
-	const pendingRangeMarkers = [];
-	for (const child of children) {
-		const localName = getLocalName(child.name ?? "");
-		if (localName === "p") {
-			const paragraph = parseParagraph(child, styles, theme, numbering, rels, media, state.options);
-			prependPendingBookmarkMarkers(paragraph, pendingBookmarkMarkers);
-			enrichParagraphTextBoxes(paragraph, child, styles, theme, numbering, rels, media, parseTable);
-			computeListMarker(paragraph, {
-				numbering,
-				listCounters: state.listCounters,
-				abstractCounters: state.abstractCounters,
-				restartedNumIds: state.restartedNumIds,
-				previousList: state.previousList
-			});
-			attachPendingRangeMarkers(paragraph, pendingRangeMarkers);
-			content.push(paragraph);
-			continue;
-		}
-		if (localName === "tbl") {
-			const table = parseTable(child, styles, theme, numbering, rels, media, state.options);
-			if (!table) continue;
-			if (prependBookmarkMarkersToFirstParagraphInBlocks([table], pendingBookmarkMarkers)) pendingBookmarkMarkers.length = 0;
-			attachPendingRangeMarkers(table, pendingRangeMarkers);
-			content.push(table);
-			continue;
-		}
-		if (localName === "sdt") {
-			const sdtPr = findChild(child, "w", "sdtPr");
-			const sdtEndPr = findChild(child, "w", "sdtEndPr");
-			const sdtContent = findChild(child, "w", "sdtContent");
-			const properties = parseSdtProperties(sdtPr, sdtEndPr);
-			const captured = captureSdtSiblingMarkers(child);
-			if (captured.before.length > 0) properties.rawSdtChildrenBeforeContent = captured.before;
-			if (captured.after.length > 0) properties.rawSdtChildrenAfterContent = captured.after;
-			const blockSdt = {
-				type: "blockSdt",
-				properties,
-				content: sdtContent ? parseBlockContentWithState(sdtContent, styles, theme, numbering, rels, media, withContainerXmlns(withContainerXmlns(state, child), sdtContent)) : []
-			};
-			if (prependBookmarkMarkersToFirstParagraphInBlocks(blockSdt.content, pendingBookmarkMarkers)) pendingBookmarkMarkers.length = 0;
-			attachPendingRangeMarkers(blockSdt, pendingRangeMarkers);
-			content.push(blockSdt);
-			continue;
-		}
-		if (localName === "AlternateContent") {
+	const modelled = [];
+	return withPreservedChildren(modelled, dispatchChildren({
+		element: parent,
+		container: "block-content",
+		capturePosition: () => modelled.length,
+		undeclared: { AlternateContent: (child) => {
 			const selectedBranch = selectAlternateContentBranch(child);
-			if (selectedBranch) content.push(...parseBlockContentWithState(selectedBranch, styles, theme, numbering, rels, media, withContainerXmlns(withContainerXmlns(state, child), selectedBranch)));
-			continue;
-		}
-		if (localName === "bookmarkStart" || localName === "bookmarkEnd") {
-			const marker = parseBookmarkMarker(child, localName);
-			if (!appendBookmarkMarkerToLastParagraphInBlocks(content, marker)) pendingBookmarkMarkers.push(marker);
-			continue;
+			if (!selectedBranch) return;
+			modelled.push(...parseBlockContentWithState(selectedBranch, styles, theme, numbering, rels, media, withContainerXmlns(withContainerXmlns(state, child), selectedBranch)));
+		} },
+		handlers: {
+			p: (child) => {
+				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,
+					abstractCounters: state.abstractCounters,
+					restartedNumIds: state.restartedNumIds,
+					previousList: state.previousList
+				});
+				modelled.push(paragraph);
+			},
+			tbl: (child) => {
+				const table = parseTable(child, styles, theme, numbering, rels, media, state.options);
+				if (!table) return;
+				modelled.push(table);
+			},
+			sdt: (child) => {
+				modelled.push(parseBlockSdt(child, styles, theme, numbering, rels, media, state));
+			},
+			bookmarkStart: (child) => {
+				modelled.push(parseBookmarkStart(child));
+			},
+			bookmarkEnd: (child) => {
+				modelled.push(parseBookmarkEnd(child));
+			},
+			...BLOCK_CHILD_OWNERS,
+			altChunk: CAPTURE,
+			commentRangeEnd: CAPTURE,
+			commentRangeStart: CAPTURE,
+			customXml: CAPTURE,
+			customXmlDelRangeEnd: CAPTURE,
+			customXmlDelRangeStart: CAPTURE,
+			customXmlInsRangeEnd: CAPTURE,
+			customXmlInsRangeStart: CAPTURE,
+			customXmlMoveFromRangeEnd: CAPTURE,
+			customXmlMoveFromRangeStart: CAPTURE,
+			customXmlMoveToRangeEnd: CAPTURE,
+			customXmlMoveToRangeStart: CAPTURE,
+			del: CAPTURE,
+			ins: CAPTURE,
+			moveFrom: CAPTURE,
+			moveFromRangeEnd: CAPTURE,
+			moveFromRangeStart: CAPTURE,
+			moveTo: CAPTURE,
+			moveToRangeEnd: CAPTURE,
+			moveToRangeStart: CAPTURE,
+			permEnd: CAPTURE,
+			permStart: CAPTURE,
+			proofErr: CAPTURE
 		}
-		if (isBlockRangeMarker(localName)) pendingRangeMarkers.push(captureVerbatimXml(child));
-	}
-	if (pendingBookmarkMarkers.length > 0) content.push({
-		type: "paragraph",
-		content: [...pendingBookmarkMarkers]
-	});
-	attachTrailingRangeMarkers(content, pendingRangeMarkers);
-	return content;
+	}), (xml) => ({
+		type: "preservedBlock",
+		xml
+	}));
 };
-/**
-* 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);
-	}
+const parseBlockSdt = (child, styles, theme, numbering, rels, media, state) => {
+	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;
 	return {
-		before: beforeParts.join(""),
-		after: afterParts.join("")
+		type: "blockSdt",
+		properties,
+		content: sdtContent ? parseBlockContentWithState(sdtContent, styles, theme, numbering, rels, media, withContainerXmlns(withContainerXmlns(state, child), sdtContent)) : []
 	};
 };
-const parseBookmarkMarker = (child, localName) => {
-	if (localName === "bookmarkStart") return parseBookmarkStart(child);
-	return parseBookmarkEnd(child);
-};
-const prependPendingBookmarkMarkers = (paragraph, pendingBookmarkMarkers) => {
-	if (pendingBookmarkMarkers.length === 0) return;
-	paragraph.content.unshift(...pendingBookmarkMarkers);
-	pendingBookmarkMarkers.length = 0;
-};
 //#endregion
 export { parseBlockContent };

package/dist/docx/blockPlainText.d.ts

@@ -1,8 +1,7 @@
 import { document_d_exports } from "../types/document.js";
 //#region src/docx/blockPlainText.d.ts
-type PlainTextBlock = document_d_exports.Paragraph | document_d_exports.Table | document_d_exports.BlockSdt;
 /** One entry per block, so callers can join or count lines as they need. */
-declare const collectBlockTexts: (blocks: readonly PlainTextBlock[]) => string[];
-declare const blockPlainText: (blocks: readonly PlainTextBlock[]) => string;
+declare const collectBlockTexts: (blocks: readonly document_d_exports.BlockContent[]) => string[];
+declare const blockPlainText: (blocks: readonly document_d_exports.BlockContent[]) => string;
 //#endregion
-export { PlainTextBlock, blockPlainText, collectBlockTexts };
+export { blockPlainText, collectBlockTexts };

package/dist/docx/blockPlainText.js

@@ -31,6 +31,9 @@ const collectBlockTexts = (blocks) => {
 		case "blockSdt":
 			texts.push(...collectBlockTexts(block.content));
 			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.d.ts

@@ -0,0 +1,30 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/commentAnchorIndex.d.ts
+type CommentMarkerSlot = {
+  /** The inline-content array the marker sits in, so a caller can splice it. */
+  content: document_d_exports.ParagraphContent[];
+  index: number;
+  item: Extract<document_d_exports.ParagraphContent, {
+    type: "commentRangeStart";
+  } | {
+    type: "commentRangeEnd";
+  } | {
+    type: "commentReference";
+  }>;
+};
+declare const visitCommentMarkers: (blocks: readonly document_d_exports.BlockContent[], visit: (slot: CommentMarkerSlot) => void) => void;
+/**
+ * Comments that open a range anywhere in these blocks.
+ *
+ * A `commentReference` whose id is absent has no highlight of its own — the
+ * point-comment shape the model's `CommentReference` documents — and only that
+ * one needs its mark anchored onto neighbouring text. Anchoring one whose range
+ * exists stretches that range to wherever the reference sits, which is how a
+ * comment on one word came back covering the rest of the sentence. The range
+ * and the reference need not share a paragraph, so the question is asked of the
+ * whole story: a reference that trails the end of a range three paragraphs back
+ * is still not a point comment.
+ */
+declare const rangedCommentIds: (blocks: readonly document_d_exports.BlockContent[]) => ReadonlySet<number>;
+//#endregion
+export { CommentMarkerSlot, rangedCommentIds, visitCommentMarkers };