@stll/folio-core 0.43.0 → 0.45.0

package/dist/document-operations.js

@@ -1,6 +1,7 @@
 import { applyFolioAIEditOperations, previewFolioAIEditOperations } from "./ai-edits/apply.js";
 import { LINE_SPACING_RULE_VALUES, PARAGRAPH_ALIGNMENT_VALUES } from "./types/documentEnumValues.js";
 import { TaggedError } from "better-result";
+import { sanitizeXmlCharacters } from "@stll/docx-core";
 //#region src/document-operations.ts
 const FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION = 1;
 /** Direct paragraph-alignment values accepted by the operation contract. */
@@ -138,15 +139,25 @@ const assertAllowedKeys = (value, path, allowedKeys) => {
 	const unexpected = Object.keys(value).find((key) => !allowedKeys.includes(key));
 	if (unexpected !== void 0) invalidBatch(`${path}.${unexpected}`, "unexpected property");
 };
+/**
+* Every string in a batch passes through here, so this is where a value an
+* agent sent stops being able to corrupt the package it lands in: XML 1.0
+* admits none of the C0 controls but tab, LF and CR, and no escape can carry
+* one into a document. The batch is otherwise held to exactly what it says, so
+* the rule is the narrowest one that keeps the request usable — drop what
+* cannot be written, map an unpaired surrogate to U+FFFD — rather than
+* rejecting a whole edit over a stray control character. The parsed batch is
+* both what folio applies and what the receipt reports, so the two agree.
+*/
 const readString = (value, key, path) => {
 	const candidate = value[key];
-	if (typeof candidate === "string") return candidate;
+	if (typeof candidate === "string") return sanitizeXmlCharacters(candidate);
 	return invalidBatch(`${path}.${key}`, "expected a string");
 };
 const readOptionalString = (value, key, path) => {
 	const candidate = value[key];
 	if (candidate === void 0) return;
-	if (typeof candidate === "string") return candidate;
+	if (typeof candidate === "string") return sanitizeXmlCharacters(candidate);
 	return invalidBatch(`${path}.${key}`, "expected a string when provided");
 };
 const readOptionalBoolean = (value, key, path) => {
@@ -184,7 +195,7 @@ const readOptionalStringArray = (value, key, path) => {
 	if (candidate === void 0) return;
 	if (!Array.isArray(candidate)) return invalidBatch(`${path}.${key}`, "expected an array when provided");
 	return candidate.map((item, index) => {
-		if (typeof item === "string") return item;
+		if (typeof item === "string") return sanitizeXmlCharacters(item);
 		return invalidBatch(`${path}.${key}[${index}]`, "expected a string");
 	});
 };

package/dist/docx/appVersionNormalization.d.ts

@@ -1,22 +1,4 @@
 //#region src/docx/appVersionNormalization.d.ts
-/**
- * Keep the application version a package states about itself in the form the
- * schema gives it.
- *
- * `AppVersion` in the extended-properties part is `XX.YYYY`: a one- or
- * two-digit integer, a dot, and four digits. Producers exist that write a
- * three-part version there instead, and folio copies `docProps/app.xml`
- * through verbatim when it saves a document it did not create — so a package
- * can carry a value with two dots in, and a save that copies it out hands a
- * consumer a package it refuses to open at all.
- *
- * {@link appVersionInSchemaForm} is the one mapping, and it is a pure function
- * of the value alone: it keeps the leading integer where the value opens with
- * one the form allows, and writes the build digits the form requires. Nothing
- * else in the part is touched, and a package that carries no extended
- * properties keeps carrying none — synthesizing metadata a document never
- * stated is a different decision.
- */
 declare const AppVersionSchemaError_base: import("better-result").TaggedErrorClass<"AppVersionSchemaError">;
 /**
  * A value reached the package that the schema form does not accept.

package/dist/docx/blockContentParser.js

@@ -1,3 +1,4 @@
+import { attachPendingRangeMarkers, attachTrailingRangeMarkers, isBlockRangeMarker } from "./blockRangeMarkers.js";
 import { parseBookmarkEnd, parseBookmarkStart } from "./bookmarkParser.js";
 import { appendBookmarkMarkerToLastParagraphInBlocks, prependBookmarkMarkersToFirstParagraphInBlocks } from "./bookmarkPlacement.js";
 import { convertBulletToUnicode } from "./bulletMarkers.js";
@@ -106,6 +107,7 @@ const parseBlockContentWithState = (parent, styles, theme, numbering, rels, medi
 	const content = [];
 	const children = getChildElements(parent);
 	const pendingBookmarkMarkers = [];
+	const pendingRangeMarkers = [];
 	for (const child of children) {
 		const localName = getLocalName(child.name ?? "");
 		if (localName === "p") {
@@ -119,6 +121,7 @@ const parseBlockContentWithState = (parent, styles, theme, numbering, rels, medi
 				restartedNumIds: state.restartedNumIds,
 				previousList: state.previousList
 			});
+			attachPendingRangeMarkers(paragraph, pendingRangeMarkers);
 			content.push(paragraph);
 			continue;
 		}
@@ -126,6 +129,7 @@ const parseBlockContentWithState = (parent, styles, theme, numbering, rels, medi
 			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;
 		}
@@ -143,6 +147,7 @@ const parseBlockContentWithState = (parent, styles, theme, numbering, rels, medi
 				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;
 		}
@@ -154,12 +159,15 @@ const parseBlockContentWithState = (parent, styles, theme, numbering, rels, medi
 		if (localName === "bookmarkStart" || localName === "bookmarkEnd") {
 			const marker = parseBookmarkMarker(child, localName);
 			if (!appendBookmarkMarkerToLastParagraphInBlocks(content, marker)) pendingBookmarkMarkers.push(marker);
+			continue;
 		}
+		if (isBlockRangeMarker(localName)) pendingRangeMarkers.push(captureVerbatimXml(child));
 	}
 	if (pendingBookmarkMarkers.length > 0) content.push({
 		type: "paragraph",
 		content: [...pendingBookmarkMarkers]
 	});
+	attachTrailingRangeMarkers(content, pendingRangeMarkers);
 	return content;
 };
 /**

package/dist/docx/blockRangeMarkers.d.ts

@@ -0,0 +1,36 @@
+//#region src/docx/blockRangeMarkers.d.ts
+/**
+ * Range markers that stand between two blocks.
+ *
+ * `w:body`, `w:tc`, a header and an SDT's content all admit
+ * `EG_RunLevelElts` and `EG_RangeMarkupElements` beside their paragraphs, and
+ * every block container dropped them: a `w:permStart` between two paragraphs
+ * is the whole of a document-protection range, so losing it removes the
+ * protection from the saved file without a word. folio models none of these,
+ * and their position is their meaning, so they are captured verbatim and
+ * replayed where they stood — the same treatment `w:sdt`'s sibling markers
+ * already get (MS-OE376 §2.5.2.30).
+ *
+ * Bookmarks are absent from the set on purpose: they are modelled, and the
+ * block containers already relocate them into the neighbouring paragraph.
+ */
+declare const isBlockRangeMarker: (localName: string) => boolean;
+/** Hand the markers collected so far to the block they stood before. */
+declare const attachPendingRangeMarkers: (block: {
+  rawMarkersBefore?: string;
+}, pending: string[]) => void;
+/**
+ * Markers after the last block ride on it, since there is no block after them.
+ * With no block at all they are dropped: a container holding markers and no
+ * content has nothing for them to delimit.
+ */
+declare const attachTrailingRangeMarkers: (blocks: readonly {
+  rawMarkersAfter?: string;
+}[], pending: string[]) => void;
+/** Wrap a serialized block in the markup that stood around it. */
+declare const withBlockRangeMarkers: (block: {
+  rawMarkersBefore?: string;
+  rawMarkersAfter?: string;
+}, xml: string) => string;
+//#endregion
+export { attachPendingRangeMarkers, attachTrailingRangeMarkers, isBlockRangeMarker, withBlockRangeMarkers };

package/dist/docx/blockRangeMarkers.js

@@ -0,0 +1,59 @@
+//#region src/docx/blockRangeMarkers.ts
+/**
+* Range markers that stand between two blocks.
+*
+* `w:body`, `w:tc`, a header and an SDT's content all admit
+* `EG_RunLevelElts` and `EG_RangeMarkupElements` beside their paragraphs, and
+* every block container dropped them: a `w:permStart` between two paragraphs
+* is the whole of a document-protection range, so losing it removes the
+* protection from the saved file without a word. folio models none of these,
+* and their position is their meaning, so they are captured verbatim and
+* replayed where they stood — the same treatment `w:sdt`'s sibling markers
+* already get (MS-OE376 §2.5.2.30).
+*
+* Bookmarks are absent from the set on purpose: they are modelled, and the
+* block containers already relocate them into the neighbouring paragraph.
+*/
+const BLOCK_RANGE_MARKER_NAMES = /* @__PURE__ */ new Set([
+	"commentRangeEnd",
+	"commentRangeStart",
+	"customXmlDelRangeEnd",
+	"customXmlDelRangeStart",
+	"customXmlInsRangeEnd",
+	"customXmlInsRangeStart",
+	"customXmlMoveFromRangeEnd",
+	"customXmlMoveFromRangeStart",
+	"customXmlMoveToRangeEnd",
+	"customXmlMoveToRangeStart",
+	"moveFromRangeEnd",
+	"moveFromRangeStart",
+	"moveToRangeEnd",
+	"moveToRangeStart",
+	"permEnd",
+	"permStart"
+]);
+const isBlockRangeMarker = (localName) => BLOCK_RANGE_MARKER_NAMES.has(localName);
+/** Hand the markers collected so far to the block they stood before. */
+const attachPendingRangeMarkers = (block, pending) => {
+	if (pending.length === 0) return;
+	block.rawMarkersBefore = pending.join("");
+	pending.length = 0;
+};
+/**
+* Markers after the last block ride on it, since there is no block after them.
+* With no block at all they are dropped: a container holding markers and no
+* content has nothing for them to delimit.
+*/
+const attachTrailingRangeMarkers = (blocks, pending) => {
+	const last = blocks.at(-1);
+	if (pending.length === 0 || last === void 0) {
+		pending.length = 0;
+		return;
+	}
+	last.rawMarkersAfter = pending.join("");
+	pending.length = 0;
+};
+/** Wrap a serialized block in the markup that stood around it. */
+const withBlockRangeMarkers = (block, xml) => `${block.rawMarkersBefore ?? ""}${xml}${block.rawMarkersAfter ?? ""}`;
+//#endregion
+export { attachPendingRangeMarkers, attachTrailingRangeMarkers, isBlockRangeMarker, withBlockRangeMarkers };

package/dist/docx/bookmarkParser.d.ts

@@ -1,27 +1,9 @@
 import { document_d_exports } from "../types/document.js";
 import { XmlElement } from "./xmlParser.js";
 //#region src/docx/bookmarkParser.d.ts
-/**
- * Parse a bookmark start element (w:bookmarkStart)
- *
- * Extracts:
- * - id: Numeric identifier (required, matches with bookmarkEnd)
- * - name: Bookmark name (required, used by hyperlinks)
- * - colFirst: First column for table bookmarks (optional)
- * - colLast: Last column for table bookmarks (optional)
- *
- * @param node - The w:bookmarkStart XML element
- * @returns Parsed BookmarkStart object
- */
+/** Parse a bookmark start element (w:bookmarkStart, CT_Bookmark). */
 declare function parseBookmarkStart(node: XmlElement): document_d_exports.BookmarkStart;
-/**
- * Parse a bookmark end element (w:bookmarkEnd)
- *
- * Bookmark ends only contain an ID that matches the corresponding start marker.
- *
- * @param node - The w:bookmarkEnd XML element
- * @returns Parsed BookmarkEnd object
- */
+/** Parse a bookmark end element (w:bookmarkEnd, CT_MarkupRange). */
 declare function parseBookmarkEnd(node: XmlElement): document_d_exports.BookmarkEnd;
 /**
  * Bookmark map for quick lookup by ID or name

package/dist/docx/bookmarkParser.js

@@ -1,41 +1,17 @@
-import { getAttribute, parseNumericAttribute } from "./xmlParser.js";
+import { parseBookmarkRangeMarker, parseMarkupRangeMarker } from "./markupRangeMarker.js";
 //#region src/docx/bookmarkParser.ts
-/**
-* Parse a bookmark start element (w:bookmarkStart)
-*
-* Extracts:
-* - id: Numeric identifier (required, matches with bookmarkEnd)
-* - name: Bookmark name (required, used by hyperlinks)
-* - colFirst: First column for table bookmarks (optional)
-* - colLast: Last column for table bookmarks (optional)
-*
-* @param node - The w:bookmarkStart XML element
-* @returns Parsed BookmarkStart object
-*/
+/** Parse a bookmark start element (w:bookmarkStart, CT_Bookmark). */
 function parseBookmarkStart(node) {
-	const bookmark = {
+	return {
 		type: "bookmarkStart",
-		id: parseNumericAttribute(node, "w", "id") ?? 0,
-		name: getAttribute(node, "w", "name") ?? ""
+		...parseBookmarkRangeMarker(node)
 	};
-	const colFirst = parseNumericAttribute(node, "w", "colFirst");
-	if (colFirst !== void 0) bookmark.colFirst = colFirst;
-	const colLast = parseNumericAttribute(node, "w", "colLast");
-	if (colLast !== void 0) bookmark.colLast = colLast;
-	return bookmark;
 }
-/**
-* Parse a bookmark end element (w:bookmarkEnd)
-*
-* Bookmark ends only contain an ID that matches the corresponding start marker.
-*
-* @param node - The w:bookmarkEnd XML element
-* @returns Parsed BookmarkEnd object
-*/
+/** Parse a bookmark end element (w:bookmarkEnd, CT_MarkupRange). */
 function parseBookmarkEnd(node) {
 	return {
 		type: "bookmarkEnd",
-		id: parseNumericAttribute(node, "w", "id") ?? 0
+		...parseMarkupRangeMarker(node)
 	};
 }
 /**

package/dist/docx/borderParser.d.ts

@@ -0,0 +1,13 @@
+import { document_d_exports } from "../types/document.js";
+import { ParseContext } from "./parseContext.js";
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/borderParser.d.ts
+/**
+ * `w:val` is `use="required"` on `CT_Border`. An element without it states no
+ * style at all, so the border is dropped rather than invented as `none`:
+ * `none` is an authored token that cancels an inherited border, and a
+ * malformed element is not evidence the author wanted that.
+ */
+declare function parseBorderSpec(border: XmlElement | null, context?: ParseContext): document_d_exports.BorderSpec | undefined;
+//#endregion
+export { parseBorderSpec };

package/dist/docx/borderParser.js

@@ -0,0 +1,71 @@
+import { BorderStyleSchema, ThemeColorSlotSchema, narrowEnum } from "./parserEnums.js";
+import { getAttribute, parseNumericAttribute, parseOnOffAttribute } from "./xmlParser.js";
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
+//#region src/docx/borderParser.ts
+/**
+* The one reader for `CT_Border`, shared by the paragraph (`w:pBdr`), style,
+* table (`w:tblBorders`/`w:tcBorders`) and page (`w:pgBorders`) tiers.
+*
+* `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`.
+*/
+const parseBorderColor = (border) => {
+	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;
+	else if (rgb) color.rgb = rgb;
+	const validatedThemeColor = narrowEnum(themeColor, ThemeColorSlotSchema);
+	if (validatedThemeColor) color.themeColor = validatedThemeColor;
+	if (themeTint) color.themeTint = themeTint;
+	if (themeShade) color.themeShade = themeShade;
+	return color;
+};
+/**
+* `w:val` is `use="required"` on `CT_Border`. An element without it states no
+* style at all, so the border is dropped rather than invented as `none`:
+* `none` is an authored token that cancels an inherited border, and a
+* malformed element is not evidence the author wanted that.
+*/
+function parseBorderSpec(border, context) {
+	if (!border) return;
+	const rawStyle = getAttribute(border, "w", "val");
+	if (!rawStyle) {
+		context?.warn({
+			code: PARSE_WARNING_CODES.borderWithoutValue,
+			element: border.name ?? "border"
+		});
+		return;
+	}
+	const spec = { style: narrowEnum(rawStyle, BorderStyleSchema) ?? rawStyle };
+	const color = parseBorderColor(border);
+	if (color) spec.color = color;
+	const size = parseNumericAttribute(border, "w", "sz");
+	if (size !== void 0) spec.size = size;
+	const space = parseNumericAttribute(border, "w", "space");
+	if (space !== void 0) spec.space = space;
+	const shadow = parseOnOffAttribute(border, "w", "shadow");
+	if (shadow !== void 0) spec.shadow = shadow;
+	const frame = parseOnOffAttribute(border, "w", "frame");
+	if (frame !== void 0) spec.frame = frame;
+	const artRelationshipId = getAttribute(border, "r", "id")?.trim();
+	if (artRelationshipId) spec.artRelationshipId = artRelationshipId;
+	const topLeftArtRelationshipId = getAttribute(border, "r", "topLeft")?.trim();
+	if (topLeftArtRelationshipId) spec.topLeftArtRelationshipId = topLeftArtRelationshipId;
+	const topRightArtRelationshipId = getAttribute(border, "r", "topRight")?.trim();
+	if (topRightArtRelationshipId) spec.topRightArtRelationshipId = topRightArtRelationshipId;
+	const bottomLeftArtRelationshipId = getAttribute(border, "r", "bottomLeft")?.trim();
+	if (bottomLeftArtRelationshipId) spec.bottomLeftArtRelationshipId = bottomLeftArtRelationshipId;
+	const bottomRightArtRelationshipId = getAttribute(border, "r", "bottomRight")?.trim();
+	if (bottomRightArtRelationshipId) spec.bottomRightArtRelationshipId = bottomRightArtRelationshipId;
+	return spec;
+}
+//#endregion
+export { parseBorderSpec };

package/dist/docx/builtInStyles.d.ts

@@ -0,0 +1,165 @@
+import { document_d_exports } from "../types/document.js";
+//#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
+ * 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.
+ */
+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
+ * drops the space entirely (`Heading1`, `IntenseQuote`), so case and
+ * whitespace are the tolerance. A name is otherwise matched whole: a style a
+ * Czech template calls `Nadpis 1` stays a custom style.
+ */
+declare const normalizeStyleName: (name: string) => string;
+/**
+ * The `w:name` Word itself writes for each built-in, and therefore the
+ * spelling every style table folio authors must use. One owner: a style set and
+ * the classifier that reads it cannot drift apart if both name the same
+ * constant.
+ *
+ * Word is not uniformly cased and guessing gets it wrong, so each value is the
+ * spelling that dominates Microsoft Word output in the public corpus:
+ * `footnote text` 375 against 49 `Footnote Text`, `footer` 1145 against 2,
+ * `caption` 390 against 60 — but `Body Text` 424 against 2, `Title` 621
+ * against 2, and the auto-generated linked character styles (`Footnote Text
+ * Char` 248, `Endnote Text Char` 116) title-cased without exception.
+ * {@link normalizeStyleName} makes matching tolerant of all of it; this map is
+ * about what folio *writes*.
+ */
+declare const BUILT_IN_STYLE_NAME: {
+  /** 4,515 Word occurrences against 3 lowercase. */
+  readonly normal: "Normal";
+  readonly bodyText: "Body Text";
+  readonly title: "Title";
+  readonly subtitle: "Subtitle";
+  readonly quote: "Quote";
+  readonly intenseQuote: "Intense Quote";
+  readonly listParagraph: "List Paragraph";
+  readonly tocHeading: "TOC Heading";
+  readonly caption: "caption";
+  readonly header: "header";
+  readonly footer: "footer";
+  readonly footnoteText: "footnote text";
+  readonly commentReference: "annotation reference";
+  readonly footnoteReference: "footnote reference";
+  readonly footnoteTextChar: "Footnote Text Char";
+  readonly endnoteText: "endnote text";
+  readonly endnoteReference: "endnote reference";
+  readonly endnoteTextChar: "Endnote Text Char";
+  readonly hyperlink: "Hyperlink";
+  readonly defaultParagraphFont: "Default Paragraph Font";
+  readonly noList: "No List";
+  readonly normalTable: "Normal Table";
+  readonly tableGrid: "Table Grid";
+};
+type BuiltInStyleName = (typeof BUILT_IN_STYLE_NAME)[keyof typeof BUILT_IN_STYLE_NAME];
+/**
+ * The name of a built-in heading, from its zero-based outline level.
+ * Lowercase: 1,066 Word occurrences of `heading 1` against 13 `Heading 1`, and
+ * Annex L writes the latent-style exceptions the same way.
+ */
+declare const builtInHeadingStyleName: (outlineLevel: number) => string;
+/** The name of a built-in TOC entry style, from its one-based level (`toc 1`). */
+declare const builtInTableOfContentsStyleName: (level: number) => string;
+/**
+ * A document's styles indexed by what they *are* rather than by what they are
+ * called. Built once per document: the consumers below classify every
+ * paragraph, and rebuilding the maps per paragraph would make each of them
+ * quadratic.
+ */
+type BuiltInStyleIndex = {
+  /** The style's effective `w:outlineLvl`, including 9, or undefined. */
+  outlineLevelOf: (styleId: string | null | undefined) => number | 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. */
+  builtInNameOf: (styleId: string | null | undefined) => BuiltInStyleName | undefined;
+  /**
+   * The level an English built-in heading *id* implies, and only when the
+   * package defines no style under it. See {@link resolveHeadingLevel} tier 3.
+   */
+  undefinedBuiltInHeadingLevelOf: (styleId: string | null | undefined) => number | undefined;
+  /** The document's style id for a built-in heading level (zero-based). */
+  styleIdForHeadingLevel: (level: number) => string | undefined;
+  /** The document's style id for a built-in TOC entry level (one-based, `toc 1`). */
+  styleIdForTableOfContentsLevel: (level: number) => string | undefined;
+  /** The document's style id for a named built-in, e.g. `TOC Heading`. */
+  styleIdForBuiltInName: (name: BuiltInStyleName) => string | undefined;
+};
+declare const createBuiltInStyleIndex: (styles: Iterable<document_d_exports.Style>, docDefaults?: document_d_exports.DocDefaults | undefined) => BuiltInStyleIndex;
+/** An index over a document that defines no styles: every lookup misses. */
+declare const EMPTY_BUILT_IN_STYLE_INDEX: BuiltInStyleIndex;
+/**
+ * What a consumer knows about a paragraph: its style id and whatever
+ * `w:outlineLvl` applies to it. The ProseMirror `outlineLevel` attr already
+ * holds direct-else-style resolution, so passing it here agrees with passing
+ * direct formatting from the DOCX model.
+ */
+type ParagraphOutlineSource = {
+  styleId?: string | null | undefined;
+  outlineLevel?: number | null | undefined;
+};
+/**
+ * The heading level a paragraph carries, zero-based (`heading 1` is 0), or
+ * undefined when it is not a heading.
+ *
+ * Precedence:
+ *
+ * 1. An effective outline level decides on its own, including
+ *    {@link BODY_TEXT_OUTLINE_LEVEL}, which means "not a heading". A style
+ *    named `heading 5` whose outline level is 0 is a level-1 heading; a style
+ *    named `heading 3` reset to 9 is body text. The format gives the outline
+ *    level to field calculation (17.3.1.20) and leaves the name to the UI
+ *    (17.7.4.9), so the level is the one the document asserts.
+ * 2. Only when no outline level is set anywhere does the built-in `w:name`
+ *    decide — the style is then inheriting the consumer's own built-in
+ *    definition, which supplies the level.
+ * 3. Last resort, and only for a `w:pStyle` the package defines no style for:
+ *    the id itself, read as the English built-in id. 17.7.4.17 makes a style
+ *    without `w:customStyle` a built-in and lets an application recognise it
+ *    "if the associated style ID is known", which is the one case where the id
+ *    is all the information left. `defaultParagraphStyle.ts` keeps the same
+ *    last tier for `Normal`. A document that defines its heading styles never
+ *    reaches this, so it cannot override a name or an outline level — and a
+ *    localized package never writes an English id to begin with.
+ *
+ * Two consequences of rule 1 are deliberate, not oversights.
+ *
+ * **An outline level on a style that is not a heading still makes a heading.**
+ * The corpus has 680 such occurrences across 161 files, including `Title` at
+ * level 0 (42×) and `Subtitle` at level 1 (23×), plus `H1`, `Sub-heading`,
+ * `index heading` and a `DSTOC1-1`…`DSTOC8-8` family. Setting the level is how
+ * a document asks for a paragraph to be outlined, and Word's navigation pane
+ * and a `TOC \u` field both honour it, so folio does not second-guess a
+ * document that asked. Suppressing `Title` here would mean folio deciding a
+ * document's outline differs from Word's.
+ *
+ * **An outline level that disagrees with a built-in heading name wins.** 26
+ * corpus styles do this (`heading 5` at level 0, `heading 3` at level 1, and
+ * so on), all from non-Word producers or hand-authored fixtures. The format
+ * gives the level to field calculation (17.3.1.20) and the name to the user
+ * interface (17.7.4.9), so the level is the machine-readable claim and the
+ * name is a label. This is the one rule below that was not confirmed against
+ * Word itself.
+ */
+declare const resolveHeadingLevel: (paragraph: ParagraphOutlineSource, index: BuiltInStyleIndex) => number | undefined;
+/** 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 };