@stll/folio-core 0.42.0 → 0.44.0

package/dist/prosemirror/utils/visualLineNavigation.js

@@ -1,7 +1,8 @@
+import { findCollapsedLineEdgeCaretTarget } from "../../layout-bridge/dom/clickToPositionDom.js";
 import { findBodyEmptyRuns, findBodyPmSpans } from "../../layout-bridge/dom/findBodyPmSpans.js";
 import { createTextStreamRange, descendantTextNodes, totalTextLength } from "../../layout-bridge/dom/textStreamDom.js";
 import { findVerticalScrollParent } from "../../utils/findVerticalScrollParent.js";
-import { TextSelection } from "prosemirror-state";
+import { Selection, TextSelection } from "prosemirror-state";
 //#region src/prosemirror/utils/visualLineNavigation.ts
 /**
 * Visual line navigation helpers — implements Word/Google-Docs-style
@@ -17,12 +18,10 @@ import { TextSelection } from "prosemirror-state";
 * @internal
 */
 const CONTENT_LINE_SELECTOR = ".layout-page-content .layout-line";
+const PM_SPAN_SELECTOR = "span[data-pm-start][data-pm-end]";
 /** @internal */
 function createVisualLineState() {
-	return {
-		stickyX: null,
-		lastVisualLineIndex: -1
-	};
+	return { step: null };
 }
 function scrollIntoViewIfNeeded(el) {
 	const container = findVerticalScrollParent(el);
@@ -35,7 +34,10 @@ function scrollIntoViewIfNeeded(el) {
 }
 /** @internal */
 function getCaretClientX(container, pmPos) {
-	for (const spanEl of findBodyPmSpans(container)) {
+	const spans = findBodyPmSpans(container);
+	const collapsedTarget = findCollapsedLineEdgeCaretTarget(spans, pmPos);
+	if (collapsedTarget) return collapsedTarget.geometry.left;
+	for (const spanEl of spans) {
 		const pmStart = Number(spanEl.dataset["pmStart"]);
 		const pmEnd = Number(spanEl.dataset["pmEnd"]);
 		if (spanEl.classList.contains("layout-run-tab")) {
@@ -58,21 +60,24 @@ function getCaretClientX(container, pmPos) {
 	}
 	return null;
 }
+/**
+* Whether one painted line carries `pmPos`. Span endpoints are inclusive, so a
+* soft-wrap boundary answers true for both the line it ends and the line it
+* starts.
+*/
+const lineCarriesPosition = (lineEl, pmPos) => {
+	for (const span of Array.from(lineEl.querySelectorAll(PM_SPAN_SELECTOR))) {
+		const start = Number(span.dataset["pmStart"]);
+		const end = Number(span.dataset["pmEnd"]);
+		if (pmPos >= start && pmPos <= end) return true;
+	}
+	return false;
+};
 /** @internal */
 function findLineElementAtPosition(container, pmPos) {
 	const allLines = container.querySelectorAll(CONTENT_LINE_SELECTOR);
-	for (const line of Array.from(allLines)) {
-		const lineEl = line;
-		const spans = lineEl.querySelectorAll("span[data-pm-start][data-pm-end]");
-		for (const span of Array.from(spans)) {
-			const s = span;
-			const start = Number(s.dataset["pmStart"]);
-			const end = Number(s.dataset["pmEnd"]);
-			if (pmPos >= start && pmPos <= end) return lineEl;
-		}
-	}
-	for (const line of Array.from(allLines)) {
-		const lineEl = line;
+	for (const lineEl of Array.from(allLines)) if (lineCarriesPosition(lineEl, pmPos)) return lineEl;
+	for (const lineEl of Array.from(allLines)) {
 		const paragraph = lineEl.closest(".layout-paragraph");
 		if (!paragraph) continue;
 		const pStart = Number(paragraph.dataset["pmStart"]);
@@ -145,6 +150,36 @@ function findPositionOnLineAtClientX(lineEl, clientX) {
 	return clientX < closestSpan.getBoundingClientRect().left ? Number(closestSpan.dataset["pmStart"]) : Number(closestSpan.dataset["pmEnd"]);
 }
 /**
+* The step the next vertical move continues from: the remembered one while the
+* caret is still where that move left it, the caret's own painted geometry
+* otherwise.
+*/
+const resolveVisualLineStep = ({ state, container, allLines, pmPos }) => {
+	const remembered = state.step;
+	if (remembered?.pmPos === pmPos) {
+		const rememberedLine = allLines[remembered.lineIndex];
+		if (rememberedLine && lineCarriesPosition(rememberedLine, pmPos)) return remembered;
+	}
+	const currentLine = findLineElementAtPosition(container, pmPos);
+	if (!currentLine) return null;
+	const lineIndex = allLines.indexOf(currentLine);
+	if (lineIndex === -1) return null;
+	const stickyX = getCaretClientX(container, pmPos);
+	return stickyX === null ? null : {
+		stickyX,
+		lineIndex,
+		pmPos
+	};
+};
+const createVerticalSelection = ({ doc, anchor, head, extend }) => {
+	try {
+		return extend ? TextSelection.create(doc, anchor, head) : TextSelection.create(doc, head);
+	} catch {
+		const $head = doc.resolve(head);
+		return extend ? TextSelection.between(doc.resolve(anchor), $head) : Selection.near($head);
+	}
+};
+/**
 * Handle PM ArrowUp / ArrowDown with visual-line awareness + sticky
 * X. Returns true if the event was handled and PM should not run
 * its default behaviour. Mutates `state` so consecutive presses
@@ -153,59 +188,41 @@ function findPositionOnLineAtClientX(lineEl, clientX) {
 * @internal
 */
 function handleVisualLineKeyDown(state, view, event, container) {
-	if (event.key !== "ArrowUp" && event.key !== "ArrowDown") {
-		if ([
-			"ArrowLeft",
-			"ArrowRight",
-			"Home",
-			"End"
-		].includes(event.key) || event.key.length === 1 && !event.ctrlKey && !event.metaKey) {
-			state.stickyX = null;
-			state.lastVisualLineIndex = -1;
-		}
-		return false;
-	}
-	if (event.ctrlKey || event.metaKey) {
-		state.stickyX = null;
-		state.lastVisualLineIndex = -1;
-		return false;
-	}
+	if (event.key !== "ArrowUp" && event.key !== "ArrowDown") return false;
+	if (event.ctrlKey || event.metaKey) return false;
 	if (!container) return false;
 	const allLines = Array.from(container.querySelectorAll(CONTENT_LINE_SELECTOR));
 	if (allLines.length === 0) return false;
-	const { from, anchor } = view.state.selection;
-	if (state.stickyX === null) {
-		const clientX = getCaretClientX(container, from);
-		if (clientX === null) return false;
-		state.stickyX = clientX;
-	}
-	let currentIndex;
-	if (state.lastVisualLineIndex >= 0 && state.lastVisualLineIndex < allLines.length) currentIndex = state.lastVisualLineIndex;
-	else {
-		const currentLine = findLineElementAtPosition(container, from);
-		if (!currentLine) return false;
-		currentIndex = allLines.indexOf(currentLine);
-		if (currentIndex === -1) return false;
-	}
-	const targetIndex = event.key === "ArrowUp" ? currentIndex - 1 : currentIndex + 1;
-	if (targetIndex < 0 || targetIndex >= allLines.length) {
-		state.lastVisualLineIndex = -1;
+	const { head, anchor } = view.state.selection;
+	const step = resolveVisualLineStep({
+		state,
+		container,
+		allLines,
+		pmPos: head
+	});
+	if (!step) return false;
+	const targetIndex = event.key === "ArrowUp" ? step.lineIndex - 1 : step.lineIndex + 1;
+	const targetLine = allLines[targetIndex];
+	if (!targetLine) {
+		state.step = null;
 		return false;
 	}
-	const targetLine = allLines[targetIndex];
-	const newPos = findPositionOnLineAtClientX(targetLine, state.stickyX);
+	const newPos = findPositionOnLineAtClientX(targetLine, step.stickyX);
 	if (newPos === null) return false;
-	state.lastVisualLineIndex = targetIndex;
 	const { state: pmState, dispatch } = view;
 	const clampedPos = Math.max(0, Math.min(newPos, pmState.doc.content.size));
-	try {
-		const sel = event.shiftKey ? TextSelection.create(pmState.doc, anchor, clampedPos) : TextSelection.create(pmState.doc, clampedPos);
-		dispatch(pmState.tr.setSelection(sel));
-	} catch {
-		const $newPos = pmState.doc.resolve(clampedPos);
-		const sel = event.shiftKey ? TextSelection.between(pmState.doc.resolve(anchor), $newPos) : TextSelection.near($newPos);
-		dispatch(pmState.tr.setSelection(sel));
-	}
+	const selection = createVerticalSelection({
+		doc: pmState.doc,
+		anchor,
+		head: clampedPos,
+		extend: event.shiftKey
+	});
+	dispatch(pmState.tr.setSelection(selection));
+	state.step = {
+		stickyX: step.stickyX,
+		lineIndex: targetIndex,
+		pmPos: selection.head
+	};
 	scrollIntoViewIfNeeded(targetLine);
 	return true;
 }

package/dist/style-engine/styleEngine.d.ts

@@ -1,4 +1,5 @@
 import { document_d_exports } from "../types/document.js";
+import { BuiltInStyleIndex } from "../docx/builtInStyles.js";
 import { ResolvedParagraphStyle, TableCellParagraphSpacingOverlay } from "../prosemirror/styles/styleResolver.js";
 //#region src/style-engine/styleEngine.d.ts
 /** Engine construction options. */
@@ -34,7 +35,7 @@ type StyleEngine = {
   hasStyle: (styleId: string) => boolean;
   /** Return the document-wide defaults (`w:docDefaults`). */
   getDocDefaults: () => document_d_exports.DocDefaults | undefined;
-  /** The style flagged `w:default="1"` for paragraphs, else "Normal". */
+  /** The paragraph default per ECMA-376 17.7.4.17, else the built-in Normal. */
   getDefaultParagraphStyle: () => document_d_exports.Style | undefined;
   /** The style flagged `w:default="1"` for character styles. */
   getDefaultCharacterStyle: () => document_d_exports.Style | undefined;
@@ -44,6 +45,8 @@ type StyleEngine = {
   getParagraphStyles: () => document_d_exports.Style[];
   /** All visible table styles, sorted for the table-style gallery. */
   getTableStyles: () => document_d_exports.Style[];
+  /** The document's styles indexed by the built-in they are — see {@link StyleResolver.builtInStyles}. */
+  builtInStyles: BuiltInStyleIndex;
   /**
    * Resolve the full paragraph cascade for a given styleId.
    * Returned object is cached and must not be mutated.

package/dist/style-engine/styleEngine.js

@@ -62,6 +62,9 @@ function createStyleEngine(styleDefinitions, options) {
 		getDefaultTableStyle: () => resolver.getDefaultTableStyle(),
 		getParagraphStyles: () => resolver.getParagraphStyles(),
 		getTableStyles: () => resolver.getTableStyles(),
+		get builtInStyles() {
+			return resolver.builtInStyles;
+		},
 		resolveParagraphStyle: (styleId) => memoize(paragraphCache, cacheKey(styleId), () => resolver.resolveParagraphStyle(styleId)),
 		resolveParagraphStyleInTable: (styleId, tableParagraphOverlay) => tableParagraphOverlay === void 0 ? memoize(paragraphCache, cacheKey(styleId), () => resolver.resolveParagraphStyleInTable(styleId, void 0)) : memoizeInTable(styleId, tableParagraphOverlay),
 		resolveRunStyle: (styleId) => memoize(runCache, cacheKey(styleId), () => resolver.resolveRunStyle(styleId)),

package/dist/style-sets/extract.js

@@ -1,10 +1,14 @@
+import { mintDefaultParagraphStyle, resolveDefaultParagraphStyle } from "../docx/defaultParagraphStyle.js";
+import { getCachedNumberingMap } from "../docx/numberingParser.js";
+import { isNumberingReference } from "../docx/numberingReference.js";
+import { normalizeStyleNumberingReferences } from "../docx/numberingReferenceNormalization.js";
 import { parseDocx } from "../docx/parser.js";
 import "./types.js";
 import { panic } from "better-result";
 //#region src/style-sets/extract.ts
 const inspectDocumentStyles = (document) => {
 	const styles = document.package.styles?.styles ?? [];
-	const defaultParagraphStyleId = styles.find((style) => style.type === "paragraph" && style.default)?.styleId;
+	const defaultParagraphStyleId = resolveDefaultParagraphStyle(styles)?.styleId;
 	return {
 		...defaultParagraphStyleId ? { defaultParagraphStyleId } : {},
 		styles: styles.map(toCatalogEntry)
@@ -24,15 +28,21 @@ const inspectDocumentStylesFromDocx = async (input) => inspectDocumentStyles(awa
 * are retained. No source content or package relationship can enter the result.
 */
 const extractDocumentStyleSet = (document, options) => {
+	if (options.styleIds?.length === 0) return panic("Cannot extract an empty style set");
 	const definitions = document.package.styles;
-	if (!definitions || definitions.styles.length === 0) return panic("Cannot extract a style set from a document without styles");
-	const stylesById = new Map(definitions.styles.map((style) => [style.styleId, style]));
+	const sourceStyles = definitions?.styles ?? [];
+	const stylesById = new Map(sourceStyles.map((style) => [style.styleId, style]));
 	const selectedStyleIds = options.styleIds === void 0 ? new Set(stylesById.keys()) : collectStyleDependencyClosure(stylesById, options.styleIds);
-	const styles = definitions.styles.filter((style) => selectedStyleIds.has(style.styleId));
-	if (styles.length === 0) return panic("Cannot extract an empty style set");
-	const defaultParagraphStyle = styles.find((style) => style.type === "paragraph" && style.default);
-	const initialParagraphStyleId = options.initialParagraphStyleId ?? defaultParagraphStyle?.styleId ?? "Normal";
-	if (!styles.find((style) => style.styleId === initialParagraphStyleId && style.type === "paragraph")) return panic(`Initial paragraph style "${initialParagraphStyleId}" is not present in the extracted set`);
+	const styles = structuredClone(sourceStyles.filter((style) => selectedStyleIds.has(style.styleId)));
+	normalizeStyleNumberingReferences({
+		styles,
+		numbering: document.package.numbering ? getCachedNumberingMap(document.package.numbering) : void 0
+	});
+	const initialParagraphStyleId = ensureInitialParagraphStyle({
+		styles,
+		requested: options.initialParagraphStyleId,
+		hasDocDefaults: definitions?.docDefaults !== void 0
+	});
 	const numbering = extractReferencedNumbering(styles, document);
 	const fontTable = sanitizeFontTable(document.package.fontTable);
 	return structuredClone({
@@ -40,8 +50,8 @@ const extractDocumentStyleSet = (document, options) => {
 		name: options.name,
 		initialParagraphStyleId,
 		styles: {
-			...definitions.docDefaults ? { docDefaults: definitions.docDefaults } : {},
-			...definitions.latentStyles ? { latentStyles: definitions.latentStyles } : {},
+			...definitions?.docDefaults ? { docDefaults: definitions.docDefaults } : {},
+			...definitions?.latentStyles ? { latentStyles: definitions.latentStyles } : {},
 			styles
 		},
 		...numbering ? { numbering } : {},
@@ -59,6 +69,20 @@ const extractDocumentStyleSetFromDocx = async (input, options) => {
 	});
 	return extractDocumentStyleSet(document, options);
 };
+const ensureInitialParagraphStyle = ({ styles, requested, hasDocDefaults }) => {
+	if (requested !== void 0) {
+		if (!styles.find((style) => style.styleId === requested && style.type === "paragraph")) return panic(`Initial paragraph style "${requested}" is not present in the extracted set`);
+		return requested;
+	}
+	const resolved = resolveDefaultParagraphStyle(styles);
+	if (resolved) return resolved.styleId;
+	const minted = mintDefaultParagraphStyle({
+		takenStyleIds: new Set(styles.map((style) => style.styleId)),
+		hasDocDefaults
+	});
+	styles.push(minted);
+	return minted.styleId;
+};
 const collectStyleDependencyClosure = (stylesById, requestedStyleIds) => {
 	const selected = /* @__PURE__ */ new Set();
 	const pending = [...requestedStyleIds];
@@ -82,7 +106,7 @@ const extractReferencedNumbering = (styles, document) => {
 	const referencedNumIds = /* @__PURE__ */ new Set();
 	for (const style of styles) {
 		const numId = style.pPr?.numPr?.numId;
-		if (numId !== void 0) referencedNumIds.add(numId);
+		if (isNumberingReference(numId)) referencedNumIds.add(numId);
 	}
 	if (referencedNumIds.size === 0) return;
 	const nums = source.nums.filter((numbering) => referencedNumIds.has(numbering.numId));

package/dist/style-sets/stellaStyle.js

@@ -1,3 +1,4 @@
+import { BUILT_IN_STYLE_NAME, builtInHeadingStyleName, builtInTableOfContentsStyleName } from "../docx/builtInStyles.js";
 import "./types.js";
 //#region src/style-sets/stellaStyle.ts
 const CLAUSE_NUMBERING_ID = 1;
@@ -43,7 +44,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "Normal",
 				type: "paragraph",
-				name: "Normal",
+				name: BUILT_IN_STYLE_NAME.normal,
 				default: true,
 				qFormat: true,
 				uiPriority: 0,
@@ -64,7 +65,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "DefaultParagraphFont",
 				type: "character",
-				name: "Default Paragraph Font",
+				name: BUILT_IN_STYLE_NAME.defaultParagraphFont,
 				default: true,
 				semiHidden: true,
 				unhideWhenUsed: true
@@ -72,7 +73,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "BodyText",
 				type: "paragraph",
-				name: "Body Text",
+				name: BUILT_IN_STYLE_NAME.bodyText,
 				basedOn: "Normal",
 				qFormat: true,
 				uiPriority: 1
@@ -80,7 +81,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "Title",
 				type: "paragraph",
-				name: "Title",
+				name: BUILT_IN_STYLE_NAME.title,
 				basedOn: "BodyText",
 				next: "BodyText",
 				qFormat: true,
@@ -109,7 +110,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "Subtitle",
 				type: "paragraph",
-				name: "Subtitle",
+				name: BUILT_IN_STYLE_NAME.subtitle,
 				basedOn: "Title",
 				next: "BodyText",
 				qFormat: true,
@@ -131,7 +132,10 @@ const createStellaStyleSet = () => ({
 				next: "Recital",
 				qFormat: true,
 				uiPriority: 5,
-				pPr: { keepNext: true },
+				pPr: {
+					keepNext: true,
+					outlineLevel: 0
+				},
 				rPr: { bold: true }
 			},
 			{
@@ -179,7 +183,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "ListParagraph",
 				type: "paragraph",
-				name: "List Paragraph",
+				name: BUILT_IN_STYLE_NAME.listParagraph,
 				basedOn: "BodyText",
 				qFormat: true,
 				uiPriority: 31,
@@ -208,13 +212,14 @@ const createStellaStyleSet = () => ({
 				pPr: {
 					pageBreakBefore: true,
 					keepNext: true,
-					spaceAfter: 240
+					spaceAfter: 240,
+					outlineLevel: 0
 				}
 			},
 			{
 				styleId: "FootnoteText",
 				type: "paragraph",
-				name: "Footnote Text",
+				name: BUILT_IN_STYLE_NAME.footnoteText,
 				basedOn: "Normal",
 				link: "FootnoteTextChar",
 				semiHidden: true,
@@ -229,7 +234,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "FootnoteTextChar",
 				type: "character",
-				name: "Footnote Text Char",
+				name: BUILT_IN_STYLE_NAME.footnoteTextChar,
 				basedOn: "DefaultParagraphFont",
 				link: "FootnoteText",
 				semiHidden: true,
@@ -243,7 +248,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "FootnoteReference",
 				type: "character",
-				name: "Footnote Reference",
+				name: BUILT_IN_STYLE_NAME.footnoteReference,
 				basedOn: "DefaultParagraphFont",
 				semiHidden: true,
 				unhideWhenUsed: true,
@@ -253,7 +258,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "EndnoteText",
 				type: "paragraph",
-				name: "Endnote Text",
+				name: BUILT_IN_STYLE_NAME.endnoteText,
 				basedOn: "Normal",
 				link: "EndnoteTextChar",
 				semiHidden: true,
@@ -268,7 +273,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "EndnoteTextChar",
 				type: "character",
-				name: "Endnote Text Char",
+				name: BUILT_IN_STYLE_NAME.endnoteTextChar,
 				basedOn: "DefaultParagraphFont",
 				link: "EndnoteText",
 				semiHidden: true,
@@ -282,7 +287,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "EndnoteReference",
 				type: "character",
-				name: "Endnote Reference",
+				name: BUILT_IN_STYLE_NAME.endnoteReference,
 				basedOn: "DefaultParagraphFont",
 				semiHidden: true,
 				unhideWhenUsed: true,
@@ -292,7 +297,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "Footer",
 				type: "paragraph",
-				name: "Footer",
+				name: BUILT_IN_STYLE_NAME.footer,
 				basedOn: "Normal",
 				pPr: {
 					alignment: "right",
@@ -307,7 +312,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "Hyperlink",
 				type: "character",
-				name: "Hyperlink",
+				name: BUILT_IN_STYLE_NAME.hyperlink,
 				basedOn: "DefaultParagraphFont",
 				unhideWhenUsed: true,
 				uiPriority: 99,
@@ -319,7 +324,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "TableNormal",
 				type: "table",
-				name: "Normal Table",
+				name: BUILT_IN_STYLE_NAME.normalTable,
 				default: true,
 				semiHidden: true,
 				unhideWhenUsed: true,
@@ -328,7 +333,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "TableGrid",
 				type: "table",
-				name: "Table Grid",
+				name: BUILT_IN_STYLE_NAME.tableGrid,
 				basedOn: "TableNormal",
 				qFormat: true,
 				uiPriority: 59,
@@ -399,37 +404,37 @@ const createHeadingStyles = () => {
 	return [
 		{
 			styleId: "Heading1",
-			name: "heading 1",
+			name: builtInHeadingStyleName(0),
 			fontSize: 28,
 			spaceBefore: 360
 		},
 		{
 			styleId: "Heading2",
-			name: "heading 2",
+			name: builtInHeadingStyleName(1),
 			fontSize: 24,
 			spaceBefore: 240
 		},
 		{
 			styleId: "Heading3",
-			name: "heading 3",
+			name: builtInHeadingStyleName(2),
 			fontSize: 22,
 			spaceBefore: 240
 		},
 		{
 			styleId: "Heading4",
-			name: "heading 4",
+			name: builtInHeadingStyleName(3),
 			fontSize: 20,
 			spaceBefore: 120
 		},
 		{
 			styleId: "Heading5",
-			name: "heading 5",
+			name: builtInHeadingStyleName(4),
 			fontSize: 20,
 			spaceBefore: 120
 		},
 		{
 			styleId: "Heading6",
-			name: "heading 6",
+			name: builtInHeadingStyleName(5),
 			fontSize: 20,
 			spaceBefore: 120
 		}
@@ -457,32 +462,33 @@ const createHeadingStyles = () => {
 };
 /** `TOCHeading` plus `TOC1`..`TOC3`, the styles a `TOC \o "1-3"` field fills. */
 const createTableOfContentsStyles = () => {
-	return [{
-		styleId: "TOCHeading",
-		type: "paragraph",
-		name: "TOC Heading",
-		basedOn: "Heading1",
-		next: "BodyText",
-		unhideWhenUsed: true,
-		uiPriority: 39,
-		pPr: { outlineLevel: 9 }
-	}, ...[
+	const levels = [
 		{
 			styleId: "TOC1",
-			name: "toc 1",
+			name: builtInTableOfContentsStyleName(1),
 			indent: 0
 		},
 		{
 			styleId: "TOC2",
-			name: "toc 2",
+			name: builtInTableOfContentsStyleName(2),
 			indent: 220
 		},
 		{
 			styleId: "TOC3",
-			name: "toc 3",
+			name: builtInTableOfContentsStyleName(3),
 			indent: 440
 		}
-	].map(({ styleId, name, indent }) => ({
+	];
+	return [{
+		styleId: "TOCHeading",
+		type: "paragraph",
+		name: BUILT_IN_STYLE_NAME.tocHeading,
+		basedOn: "Heading1",
+		next: "BodyText",
+		unhideWhenUsed: true,
+		uiPriority: 39,
+		pPr: { outlineLevel: 9 }
+	}, ...levels.map(({ styleId, name, indent }) => ({
 		styleId,
 		type: "paragraph",
 		name,
@@ -548,7 +554,8 @@ const createClauseStyles = () => {
 					ilvl: level
 				},
 				keepNext: level < 2,
-				spaceBefore: clauseSpaceBefore(level)
+				spaceBefore: clauseSpaceBefore(level),
+				outlineLevel: level === 0 ? 0 : 9
 			}
 		};
 		if (bold) return Object.assign(style, { rPr: { bold: true } });

package/dist/style-sets/styleSetNormalization.d.ts

@@ -0,0 +1,19 @@
+import { DocumentStyleSet } from "./types.js";
+import { ParseContext } from "../docx/parseContext.js";
+//#region src/style-sets/styleSetNormalization.d.ts
+/** The codes this normalisation is reported under, owned here, not at the caller. */
+declare const DUPLICATE_STYLE_ID_WARNING: "style-set-duplicate-style-id";
+declare const INITIAL_PARAGRAPH_STYLE_WARNING: "style-set-initial-style-missing";
+declare const UNNUMBERED_STYLE_SET_STYLE_WARNING: "unnumbered-style";
+/** The part a style-set normalisation names: the set itself, not a package. */
+declare const STYLE_SET_PART = "style-set";
+/**
+ * A normalised copy of the set, leaving the caller's value untouched.
+ *
+ * The version is the one thing still refused rather than repaired: a value
+ * folio has no reader for is programmer misuse, not a document defect, and
+ * guessing at its meaning would be worse than saying so.
+ */
+declare const normalizeDocumentStyleSet: (styleSet: DocumentStyleSet, context?: ParseContext) => DocumentStyleSet;
+//#endregion
+export { DUPLICATE_STYLE_ID_WARNING, INITIAL_PARAGRAPH_STYLE_WARNING, STYLE_SET_PART, UNNUMBERED_STYLE_SET_STYLE_WARNING, normalizeDocumentStyleSet };