@stll/folio-core 0.58.4 → 0.59.0

package/dist/compare/content.js

@@ -3,8 +3,10 @@ import { outlineLevelFromAttrValue } from "../prosemirror/outlineLevelAttr.js";
 import { paragraphIndentationEqual } from "../prosemirror/paragraphIndentation.js";
 import { PARAGRAPH_ALIGNMENT_VALUES } from "../types/documentEnumValues.js";
 import { alignFolioContentStructure, contentBlocksShareContainer, createFolioContentAlignmentWorkSession } from "./content-alignment.js";
+import { sameFolioContentStatedNumbering } from "./content-types.js";
 import { inlineFormattingSegments } from "./formatting.js";
 import { Result, TaggedError, panic } from "better-result";
+import { isNumberingReference } from "@stll/docx-core/model";
 //#region src/compare/content.ts
 /**
 * Pure comparison of two ordered, representation-neutral content snapshots.
@@ -68,10 +70,29 @@ const limitExceeded = ({ input, limit, maximum, actual, blockIndex, field }) =>
 	...field !== void 0 && { field }
 });
 const isFiniteInteger = (value) => typeof value === "number" && Number.isSafeInteger(value);
+const isNonNegativeInteger = (value) => isFiniteInteger(value) && value >= 0;
 const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const validStatedNumbering = (value) => {
+	if (!isRecord(value) || typeof value["kind"] !== "string") return false;
+	switch (value["kind"]) {
+		case "inherit":
+		case "none": return true;
+		case "levelOnly": return isFiniteInteger(value["ilvl"]) && value["ilvl"] >= 0;
+		case "reference": return isNonNegativeInteger(value["numId"]) && isNumberingReference(value["numId"]) && (value["ilvl"] === void 0 || isFiniteInteger(value["ilvl"]) && value["ilvl"] >= 0);
+		default: return false;
+	}
+};
 const hasRecordShape = (value) => isRecord(value);
-const PARAGRAPH_ALIGNMENTS = new Set(PARAGRAPH_ALIGNMENT_VALUES);
+const PARAGRAPH_ALIGNMENTS$1 = new Set(PARAGRAPH_ALIGNMENT_VALUES);
+const isParagraphContentBlock = (block) => {
+	switch (block.kind) {
+		case "paragraph":
+		case "heading":
+		case "listItem": return "statedNumbering" in block;
+		default: return false;
+	}
+};
 const validateRunFormatting = (block, side, blockIndex) => {
 	for (const [runIndex, run] of (block.previewRuns ?? []).entries()) {
 		if (run.directFormatting !== void 0 && !isRecord(run.directFormatting)) return invalidInput(side, `blocks[${String(blockIndex)}].previewRuns[${String(runIndex)}].directFormatting`, "Direct inline formatting must be an object.", blockIndex);
@@ -100,8 +121,12 @@ const validateRunFormatting = (block, side, blockIndex) => {
 const validateParagraphFormatting = (block, side, blockIndex) => {
 	for (const property of ["styleId", "displayLabel"]) if (block[property] !== void 0 && typeof block[property] !== "string") return invalidInput(side, `blocks[${String(blockIndex)}].${property}`, "Optional block labels and style ids must be strings.", blockIndex);
 	if (block.headingLevel !== void 0 && (!isFiniteInteger(block.headingLevel) || block.headingLevel < 1)) return invalidInput(side, `blocks[${String(blockIndex)}].headingLevel`, "Heading levels must be positive integers.", blockIndex);
-	if (block.listLevel !== void 0 && (!isFiniteInteger(block.listLevel) || block.listLevel < 0)) return invalidInput(side, `blocks[${String(blockIndex)}].listLevel`, "List levels must be non-negative integers.", blockIndex);
-	if (block.directAlignment !== void 0 && !PARAGRAPH_ALIGNMENTS.has(block.directAlignment)) return invalidInput(side, `blocks[${String(blockIndex)}].directAlignment`, "Paragraph alignment is not recognized.", blockIndex);
+	if (block.kind === "diagnostic") {
+		for (const field of ["statedNumbering", "listReference"]) if (Object.hasOwn(block, field)) return invalidInput(side, `blocks[${String(blockIndex)}].${field}`, "Diagnostics cannot state paragraph numbering.", blockIndex);
+		return null;
+	}
+	if (!isParagraphContentBlock(block) || !validStatedNumbering(block.statedNumbering)) return invalidInput(side, `blocks[${String(blockIndex)}].statedNumbering`, "Stated paragraph numbering must be a recognized authored override or inherit.", blockIndex);
+	if (block.directAlignment !== void 0 && !PARAGRAPH_ALIGNMENTS$1.has(block.directAlignment)) return invalidInput(side, `blocks[${String(blockIndex)}].directAlignment`, "Paragraph alignment is not recognized.", blockIndex);
 	if (block.directOutlineLevel !== void 0 && outlineLevelFromAttrValue(block.directOutlineLevel) === null) return invalidInput(side, `blocks[${String(blockIndex)}].directOutlineLevel`, "Direct outline level is not recognized.", blockIndex);
 	const spacing = block.directSpacing;
 	if (spacing === void 0) return null;
@@ -411,13 +436,11 @@ const withTextOffsets = (segments) => {
 };
 const paragraphSpacingEqual = (base, revised) => base?.spaceBefore === revised?.spaceBefore && base?.spaceAfter === revised?.spaceAfter && base?.lineSpacing === revised?.lineSpacing && base?.lineSpacingRule === revised?.lineSpacingRule && base?.beforeAutospacing === revised?.beforeAutospacing && base?.afterAutospacing === revised?.afterAutospacing;
 const changedFolioContentParagraphFormatting = (base, revised) => {
+	if (!isParagraphContentBlock(base) || !isParagraphContentBlock(revised)) return null;
 	const patch = {};
 	if ((base.styleId ?? null) !== (revised.styleId ?? null)) patch.styleId = revised.styleId ?? null;
 	if (!sameFolioContentOutlineLevel(base.directOutlineLevel, revised.directOutlineLevel)) patch.outlineLevel = revised.directOutlineLevel ?? null;
-	const listReferenceChanged = base.listReference?.numId !== revised.listReference?.numId;
-	const targetOmitsLevelOnChangedReference = listReferenceChanged && revised.listReference !== void 0 && revised.listLevel === void 0;
-	if (base.listLevel !== revised.listLevel || targetOmitsLevelOnChangedReference) patch.listLevel = revised.listLevel ?? null;
-	if (listReferenceChanged || base.listLevel !== revised.listLevel && revised.listLevel === void 0 && revised.listReference !== void 0) patch.listReference = revised.listReference ?? null;
+	if (!sameFolioContentStatedNumbering(base.statedNumbering, revised.statedNumbering)) patch.numbering = revised.statedNumbering;
 	if (base.directAlignment !== revised.directAlignment) patch.alignment = revised.directAlignment ?? null;
 	if (!paragraphSpacingEqual(base.directSpacing, revised.directSpacing)) patch.spacing = revised.directSpacing ?? null;
 	if (!paragraphIndentationEqual(base.directIndentation, revised.directIndentation)) patch.indentation = revised.directIndentation ?? null;

package/dist/compare/formatting.d.ts

@@ -1,8 +1,8 @@
-import { FolioContentBlock, FolioContentInlineComparisonResult } from "./content-types.js";
+import { FolioContentBlockIdentity, FolioContentInlineComparisonResult } from "./content-types.js";
 //#region src/compare/formatting.d.ts
 type InlineFormattingSegmentsOptions = {
-  baseBlock: FolioContentBlock;
-  targetBlock: FolioContentBlock;
+  baseBlock: FolioContentBlockIdentity;
+  targetBlock: FolioContentBlockIdentity;
   maxSegments: number;
 };
 /** Malformed run streams take precedence over the output budget. */

package/dist/compare/import-style-closure.d.ts

@@ -0,0 +1,22 @@
+import { FolioAIEditSnapshot } from "../ai-edits/types.js";
+import { ImportReferencedStyleDefinitionsResult } from "./style-resources.js";
+import { FolioDocxReviewer } from "../ai-edits/headless.js";
+//#region src/compare/import-style-closure.d.ts
+type ImportStyleClosureWithNumberingOptions = {
+  destination: FolioDocxReviewer;
+  source: FolioDocxReviewer;
+  snapshots: readonly FolioAIEditSnapshot[];
+  importedHeaderFooterSnapshots: readonly FolioAIEditSnapshot[];
+  numberingReferences: readonly {
+    numId: number;
+    level: number;
+  }[];
+};
+/** Import numbering before styles bind to it, then rebind the source snapshots once. */
+declare const importStyleClosureWithNumbering: ({ destination, source, snapshots, importedHeaderFooterSnapshots, numberingReferences }: ImportStyleClosureWithNumberingOptions) => {
+  styleImport: ImportReferencedStyleDefinitionsResult;
+  numberingStage: "unchanged" | "staged" | "conflict";
+  snapshots: FolioAIEditSnapshot[];
+};
+//#endregion
+export { importStyleClosureWithNumbering };

package/dist/compare/import-style-closure.js

@@ -0,0 +1,33 @@
+import { getFolioDocxComparisonAccess } from "../ai-edits/headless.js";
+import { remapFolioAIEditSnapshotNumberingReferences, remapFolioAIEditSnapshotStyleReferences } from "../ai-edits/snapshot.js";
+import { createStyleResolver } from "../prosemirror/styles/styleResolver.js";
+//#region src/compare/import-style-closure.ts
+/** Import numbering before styles bind to it, then rebind the source snapshots once. */
+const importStyleClosureWithNumbering = ({ destination, source, snapshots, importedHeaderFooterSnapshots, numberingReferences }) => {
+	const access = getFolioDocxComparisonAccess(destination);
+	const numbering = getFolioDocxComparisonAccess(source).numberingDefinitions();
+	const numberingReferenceMap = access.planTargetNumberingReferences(numbering, numberingReferences);
+	const numberingStage = numberingReferenceMap === null ? "conflict" : access.stageTargetNumbering(numbering, numberingReferences, numberingReferenceMap);
+	const styleImport = access.stageTargetStyles({
+		source,
+		snapshots,
+		importedHeaderFooterSnapshots,
+		...numberingReferenceMap !== null && { numberingReferenceMap }
+	});
+	return {
+		styleImport,
+		numberingStage,
+		snapshots: snapshots.map((snapshot) => {
+			const styleRebound = styleImport.status === "unalignable" ? snapshot : remapFolioAIEditSnapshotStyleReferences({
+				snapshot,
+				styleIdMap: styleImport.styleIdMap,
+				defaultParagraphStyleId: styleImport.defaultParagraphStyleId,
+				importedStyleResolver: createStyleResolver(styleImport.styles),
+				reconcileAuthoredFormatting: true
+			});
+			return numberingReferenceMap === null ? styleRebound : remapFolioAIEditSnapshotNumberingReferences(styleRebound, numberingReferenceMap);
+		})
+	};
+};
+//#endregion
+export { importStyleClosureWithNumbering };

package/dist/compare/inserted-resource-snapshot.d.ts

@@ -0,0 +1,15 @@
+import { FolioAIBlock, FolioAIEditSnapshot } from "../ai-edits/types.js";
+//#region src/compare/inserted-resource-snapshot.d.ts
+type CreateInsertedResourceProjectionOptions = {
+  base: FolioAIEditSnapshot;
+  revised: FolioAIEditSnapshot;
+};
+/** Select resource nodes with their identities from the full revised snapshot. */
+declare const createInsertedResourceProjection: ({ base, revised }: CreateInsertedResourceProjectionOptions) => {
+  snapshot: FolioAIEditSnapshot;
+  revisedBlockIds: string[];
+};
+/** Subset projection IDs never participate in rebinding the full revised snapshot. */
+declare const rebindInsertedResourceBlocks: (projection: ReturnType<typeof createInsertedResourceProjection>, rebound: FolioAIEditSnapshot) => Map<string, FolioAIBlock>;
+//#endregion
+export { createInsertedResourceProjection, rebindInsertedResourceBlocks };

package/dist/compare/inserted-resource-snapshot.js

@@ -0,0 +1,63 @@
+import { createFolioAIEditSnapshotWithStyleResolver, sourceDocumentOf, styleResolverOf } from "../ai-edits/snapshot.js";
+import { alignFolioBlocks } from "../version-comparison.js";
+import { panic } from "better-result";
+import { Fragment } from "prosemirror-model";
+//#region src/compare/inserted-resource-snapshot.ts
+/** Select resource nodes with their identities from the full revised snapshot. */
+const createInsertedResourceProjection = ({ base, revised }) => {
+	const document = sourceDocumentOf(revised);
+	const insertions = alignFolioBlocks(base.blocks, revised.blocks).flatMap((event) => {
+		if (event.type === "pair" || event.type === "baseOnly") return [];
+		const anchor = revised.anchors[event.block.id] ?? panic("An inserted block lost its source anchor");
+		const node = document.nodeAt(anchor.from) ?? panic("An inserted block lost its source paragraph");
+		return [{
+			from: anchor.from,
+			to: anchor.to,
+			node
+		}];
+	}).toSorted((left, right) => left.from - right.from);
+	const carriers = [];
+	let projectionFrom = 0;
+	for (const insertion of insertions) {
+		if (insertion.from < (carriers.at(-1)?.to ?? -1)) continue;
+		carriers.push({
+			...insertion,
+			projectionFrom
+		});
+		projectionFrom += insertion.node.nodeSize;
+	}
+	const revisedIdsByProjectionPosition = /* @__PURE__ */ new Map();
+	let carrierIndex = 0;
+	for (const block of revised.blocks) {
+		const anchor = revised.anchors[block.id];
+		if (anchor === void 0) continue;
+		while (anchor.from >= (carriers.at(carrierIndex)?.to ?? Number.POSITIVE_INFINITY)) carrierIndex++;
+		const carrier = carriers.at(carrierIndex);
+		if (carrier === void 0 || anchor.from < carrier.from || anchor.to > carrier.to) continue;
+		revisedIdsByProjectionPosition.set(carrier.projectionFrom + anchor.from - carrier.from, block.id);
+	}
+	const snapshot = createFolioAIEditSnapshotWithStyleResolver(document.copy(Fragment.from(carriers.map(({ node }) => node))), styleResolverOf(revised));
+	if (snapshot.blocks.length !== revisedIdsByProjectionPosition.size) return panic("A redline resource projection must preserve its maximal carriers' blocks");
+	return {
+		snapshot,
+		revisedBlockIds: snapshot.blocks.map((block) => {
+			const anchor = snapshot.anchors[block.id] ?? panic("A projected resource block lost its anchor");
+			return revisedIdsByProjectionPosition.get(anchor.from) ?? panic("A projected resource block lost its carried source identity");
+		})
+	};
+};
+/** Subset projection IDs never participate in rebinding the full revised snapshot. */
+const rebindInsertedResourceBlocks = (projection, rebound) => {
+	if (rebound.blocks.length !== projection.revisedBlockIds.length) return panic("A redline resource import changed the carried insertion count");
+	const blocks = /* @__PURE__ */ new Map();
+	for (const [index, id] of projection.revisedBlockIds.entries()) {
+		const block = rebound.blocks.at(index) ?? panic("A redline import lost a carried insertion");
+		blocks.set(id, {
+			...block,
+			id
+		});
+	}
+	return blocks;
+};
+//#endregion
+export { createInsertedResourceProjection, rebindInsertedResourceBlocks };

package/dist/compare/plan.js

@@ -224,8 +224,7 @@ const shareAContainer = (left, right) => {
 const toFolioAIBlockParagraphProperties = (properties) => ({
 	...properties.styleId !== void 0 && { styleId: properties.styleId },
 	...properties.outlineLevel !== void 0 && { outlineLevel: properties.outlineLevel },
-	...properties.listLevel !== void 0 && { listLevel: properties.listLevel },
-	...properties.listReference !== void 0 && { numbering: properties.listReference },
+	...properties.numbering !== void 0 && { numbering: properties.numbering },
 	...properties.alignment !== void 0 && { alignment: properties.alignment },
 	...properties.spacing !== void 0 && { spacing: properties.spacing },
 	...properties.indentation !== void 0 && { indentation: properties.indentation }
@@ -489,8 +488,7 @@ const withTrailingDeletionRules = ({ baseSnapshot, targetSnapshot, operations, t
 					text: insert.text,
 					...insert.moveId !== void 0 && { moveId: insert.moveId },
 					styleId: insert.styleId ?? null,
-					listLevel: insert.listLevel ?? null,
-					numbering: insert.numbering ?? null,
+					...insert.numbering !== void 0 && { numbering: insert.numbering },
 					indentation: insert.indentation ?? null,
 					...insert.lineBreakMode !== void 0 && { lineBreakMode: insert.lineBreakMode },
 					...insert.hardPageBreak !== void 0 && { hardPageBreak: insert.hardPageBreak },
@@ -592,17 +590,26 @@ const planStoryCompare = ({ story, baseSnapshot, targetSnapshot, maxOperations,
 	*/
 	const moveIdOf = (baseBlockId) => `move-${baseBlockId}`;
 	const pushInsertOperation = (block, anchorId) => {
+		let paragraph;
+		switch (block.kind) {
+			case "paragraph":
+			case "heading":
+			case "listItem":
+				paragraph = block;
+				break;
+			case "diagnostic": return;
+			default: return panic("Unhandled comparison block kind", { block });
+		}
 		const moveSourceId = moveSourceByTargetBlockId.get(block.id);
-		const structuralBoundary = block.structuralBoundaries?.at(0);
-		const hardPageBreak = block.text.length === 0 && block.structuralBoundaries?.length === 1 && structuralBoundary?.type === "pageBreak" && structuralBoundary.offset === 0 ? { ...structuralBoundary.clear !== void 0 && { clear: structuralBoundary.clear } } : void 0;
+		const structuralBoundary = paragraph.structuralBoundaries?.at(0);
+		const hardPageBreak = block.text.length === 0 && paragraph.structuralBoundaries?.length === 1 && structuralBoundary?.type === "pageBreak" && structuralBoundary.offset === 0 ? { ...structuralBoundary.clear !== void 0 && { clear: structuralBoundary.clear } } : void 0;
 		const paragraphProperties = {
-			styleId: block.styleId ?? null,
-			outlineLevel: block.directOutlineLevel ?? null,
-			listLevel: block.listLevel ?? null,
-			numbering: block.listReference ?? null,
-			alignment: block.directAlignment ?? null,
-			spacing: block.directSpacing ?? null,
-			indentation: block.directIndentation ?? null
+			styleId: paragraph.styleId ?? null,
+			outlineLevel: paragraph.directOutlineLevel ?? null,
+			numbering: paragraph.statedNumbering,
+			alignment: paragraph.directAlignment ?? null,
+			spacing: paragraph.directSpacing ?? null,
+			indentation: paragraph.directIndentation ?? null
 		};
 		const shared = {
 			text: block.text,

package/dist/compare/scenario.js

@@ -38,6 +38,15 @@ const EDIT_SCRIPT_UNRESOLVED_REASONS = Object.freeze([
 	"refused"
 ]);
 const blockAt = (blocks, index) => Number.isInteger(index) && index >= 0 ? blocks.at(index) : void 0;
+const statedNumberingOf = (block) => {
+	switch (block.kind) {
+		case "paragraph":
+		case "heading":
+		case "listItem": return block.statedNumbering;
+		case "diagnostic": return;
+		default: return panic("Unhandled scenario block kind", { block });
+	}
+};
 const planStep = ({ step, blocks, nextOperationId }) => {
 	const block = blockAt(blocks, step.blockIndex);
 	if (!block) return {
@@ -81,6 +90,7 @@ const planStep = ({ step, blocks, nextOperationId }) => {
 				status: "unresolved",
 				reason: "block-out-of-range"
 			};
+			const statedNumbering = statedNumberingOf(block);
 			return {
 				status: "planned",
 				operations: [{
@@ -93,7 +103,7 @@ const planStep = ({ step, blocks, nextOperationId }) => {
 					blockId: destination.id,
 					text: block.text,
 					styleId: block.styleId ?? null,
-					listLevel: block.listLevel ?? null
+					...statedNumbering !== void 0 && { numbering: statedNumbering }
 				}]
 			};
 		}
@@ -243,7 +253,7 @@ const applyEditScript = async (base, script) => {
 			operations: planned.flatMap(({ operations }) => [...operations])
 		},
 		snapshot,
-		undefinedStyles: "keep"
+		undefinedReferences: "keep"
 	});
 	const skippedIds = new Set(skipped.map(({ id }) => id));
 	const applied = [];

package/dist/compare/style-resources.d.ts

@@ -8,6 +8,7 @@ type ImportReferencedStyleDefinitionsOptions = {
   referencedStyleIds: readonly string[];
   reservedStyleIds?: readonly string[];
   materializeDefaultParagraphStyle?: boolean;
+  numberingReferenceMap?: ReadonlyMap<number, number>;
 };
 type ImportReferencedStyleDefinitionsResult = {
   status: "unchanged" | "imported";
@@ -19,12 +20,17 @@ type ImportReferencedStyleDefinitionsResult = {
   status: "unalignable";
   detail: string;
 };
+/** Numbering resources in the same transitive closure the style importer owns. */
+declare const styleClosureNumberingReferences: (styles: document_d_exports.StyleDefinitions | undefined, referencedStyleIds: readonly string[]) => {
+  numId: number;
+  level: number;
+}[];
 /**
  * Add the target style definitions required by a comparison without changing
  * existing package resources. A referenced style is only portable when both
  * packages have the same document defaults and theme: those resources take
  * part in OOXML style resolution even when a style definition itself is new.
  */
-declare const importReferencedStyleDefinitions: ({ sourceStyles, destinationStyles, sourceTheme, destinationTheme, referencedStyleIds, reservedStyleIds, materializeDefaultParagraphStyle }: ImportReferencedStyleDefinitionsOptions) => ImportReferencedStyleDefinitionsResult;
+declare const importReferencedStyleDefinitions: ({ sourceStyles: originalSourceStyles, destinationStyles, sourceTheme, destinationTheme, referencedStyleIds, reservedStyleIds, materializeDefaultParagraphStyle, numberingReferenceMap }: ImportReferencedStyleDefinitionsOptions) => ImportReferencedStyleDefinitionsResult;
 //#endregion
-export { ImportReferencedStyleDefinitionsOptions, ImportReferencedStyleDefinitionsResult, importReferencedStyleDefinitions };
+export { ImportReferencedStyleDefinitionsOptions, ImportReferencedStyleDefinitionsResult, importReferencedStyleDefinitions, styleClosureNumberingReferences };

package/dist/compare/style-resources.js

@@ -2,12 +2,34 @@ import { createStyleResolver } from "../prosemirror/styles/styleResolver.js";
 import { canonicalJson } from "../utils/canonicalJson.js";
 import { resolveColorToHex } from "../utils/colorResolver.js";
 import { resolveThemeFont } from "../utils/fontResolver.js";
+import { paragraphNumberingReference } from "@stll/docx-core/model";
 //#region src/compare/style-resources.ts
 const styleDependencies = ({ basedOn, link, next }) => [
 	basedOn,
 	link,
 	next
 ].filter((styleId) => styleId !== void 0);
+/** Numbering resources in the same transitive closure the style importer owns. */
+const styleClosureNumberingReferences = (styles, referencedStyleIds) => {
+	const definitions = new Map(styles?.styles.map((style) => [style.styleId, style]));
+	const pending = [...referencedStyleIds];
+	const seen = /* @__PURE__ */ new Set();
+	const references = [];
+	while (pending.length > 0) {
+		const id = pending.pop();
+		if (id === void 0 || seen.has(id)) continue;
+		seen.add(id);
+		const style = definitions.get(id);
+		if (style === void 0) continue;
+		const numbering = style.pPr?.numPr;
+		if (numbering?.kind === "reference") references.push({
+			numId: numbering.numId,
+			level: numbering.ilvl ?? 0
+		});
+		pending.push(...styleDependencies(style));
+	}
+	return references;
+};
 const themesMatch = (sourceTheme, destinationTheme) => canonicalJson(sourceTheme) === canonicalJson(destinationTheme);
 const hasThemeReference = (value) => {
 	if (Array.isArray(value)) return value.some(hasThemeReference);
@@ -205,7 +227,25 @@ const remapImportedStyle = ({ style, styleIdMap, isolatedDefaultStyleIds }) => {
 * packages have the same document defaults and theme: those resources take
 * part in OOXML style resolution even when a style definition itself is new.
 */
-const importReferencedStyleDefinitions = ({ sourceStyles, destinationStyles, sourceTheme, destinationTheme, referencedStyleIds, reservedStyleIds = [], materializeDefaultParagraphStyle = false }) => {
+const importReferencedStyleDefinitions = ({ sourceStyles: originalSourceStyles, destinationStyles, sourceTheme, destinationTheme, referencedStyleIds, reservedStyleIds = [], materializeDefaultParagraphStyle = false, numberingReferenceMap }) => {
+	const sourceStyles = originalSourceStyles && numberingReferenceMap && numberingReferenceMap.size > 0 ? {
+		...originalSourceStyles,
+		styles: originalSourceStyles.styles.map((style) => {
+			const numbering = style.pPr?.numPr;
+			const numId = numbering?.kind === "reference" ? numberingReferenceMap.get(numbering.numId) : void 0;
+			if (numId === void 0 || numbering?.kind !== "reference") return style;
+			return {
+				...style,
+				pPr: {
+					...style.pPr,
+					numPr: paragraphNumberingReference({
+						numId,
+						...numbering.ilvl !== void 0 && { ilvl: numbering.ilvl }
+					})
+				}
+			};
+		})
+	} : originalSourceStyles;
 	const requested = [...new Set(referencedStyleIds)].toSorted();
 	if (requested.length === 0 && !materializeDefaultParagraphStyle) return {
 		status: "unchanged",
@@ -238,7 +278,7 @@ const importReferencedStyleDefinitions = ({ sourceStyles, destinationStyles, sou
 		const source = sourceById.get(styleId);
 		if (!source) return {
 			status: "unalignable",
-			detail: "a referenced target style is missing"
+			detail: `referenced target style ${styleId} is missing`
 		};
 		required.add(styleId);
 		pending.push(...styleDependencies(source));
@@ -257,7 +297,7 @@ const importReferencedStyleDefinitions = ({ sourceStyles, destinationStyles, sou
 		const destination = destinationById.get(styleId);
 		if (!source) return {
 			status: "unalignable",
-			detail: "a referenced target style is missing"
+			detail: `referenced target style ${styleId} is missing`
 		};
 		if (destination !== void 0 && canonicalJson(source) !== canonicalJson(destination) || !destination && (reserved.has(styleId) || source.default)) {
 			const alias = nextAvailableStyleAlias({
@@ -275,7 +315,14 @@ const importReferencedStyleDefinitions = ({ sourceStyles, destinationStyles, sou
 	const contextMatches = canonicalJson(sourceStyles.docDefaults) === canonicalJson(destinationStyles.docDefaults) && themesMatch(sourceTheme, destinationTheme);
 	const materializeThemeReferences = !themesMatch(sourceTheme, destinationTheme);
 	const additions = sourceStyles.styles.filter(({ styleId }) => required.has(styleId) && (!destinationById.has(styleId) || styleIdMap.get(styleId) !== styleId));
-	if (contextMatches) {
+	const needsDefaultParagraphStyle = materializeDefaultParagraphStyle && !effectiveDefaultParagraphFormattingMatches({
+		sourceStyles,
+		destinationStyles,
+		sourceTheme,
+		destinationTheme,
+		materializeThemeReferences
+	});
+	if (contextMatches && !needsDefaultParagraphStyle) {
 		if (additions.length === 0) return {
 			status: "unchanged",
 			styles: destinationStyles,
@@ -298,6 +345,14 @@ const importReferencedStyleDefinitions = ({ sourceStyles, destinationStyles, sou
 	}
 	const materializedStyles = [];
 	for (const style of additions) {
+		if (contextMatches) {
+			materializedStyles.push(remapImportedStyle({
+				style,
+				styleIdMap,
+				isolatedDefaultStyleIds
+			}));
+			continue;
+		}
 		const result = materializeEffectiveStyle({
 			style,
 			styles: sourceStyles,
@@ -306,7 +361,7 @@ const importReferencedStyleDefinitions = ({ sourceStyles, destinationStyles, sou
 		});
 		if (result.status === "unalignable") return {
 			status: "unalignable",
-			detail: "a referenced style has formatting that cannot be materialized"
+			detail: `referenced style ${style.styleId} has formatting that cannot be materialized`
 		};
 		materializedStyles.push(remapImportedStyle({
 			style: result.style,
@@ -316,13 +371,7 @@ const importReferencedStyleDefinitions = ({ sourceStyles, destinationStyles, sou
 	}
 	let defaultParagraphStyleId;
 	let materializedDefaultParagraphStyle;
-	if (materializeDefaultParagraphStyle && !effectiveDefaultParagraphFormattingMatches({
-		sourceStyles,
-		destinationStyles,
-		sourceTheme,
-		destinationTheme,
-		materializeThemeReferences
-	})) {
+	if (needsDefaultParagraphStyle) {
 		defaultParagraphStyleId = nextAvailableStyleAlias({
 			taken,
 			sequence: aliasSequence
@@ -373,7 +422,7 @@ const importReferencedStyleDefinitions = ({ sourceStyles, destinationStyles, sou
 			rPr: candidateRunFormatting.formatting
 		})) return {
 			status: "unalignable",
-			detail: "a referenced style differs after materializing its formatting"
+			detail: `referenced style ${style.styleId} differs after materializing its formatting`
 		};
 	}
 	if (defaultParagraphStyleId !== void 0) {
@@ -407,4 +456,4 @@ const importReferencedStyleDefinitions = ({ sourceStyles, destinationStyles, sou
 	};
 };
 //#endregion
-export { importReferencedStyleDefinitions };
+export { importReferencedStyleDefinitions, styleClosureNumberingReferences };

package/dist/compare/verification.d.ts

@@ -1,4 +1,4 @@
-import { FolioAIBlock } from "../ai-edits/types.js";
+import { FolioAIDiagnosticBlock, FolioAIParagraphBlock } from "../ai-edits/types.js";
 import { FolioDocumentStoryHandle } from "../ai-edits/headless.js";
 import { ParagraphMarkChangeKind } from "@stll/docx-core/model";
 //#region src/compare/verification.d.ts
@@ -10,7 +10,7 @@ type CompareVerificationInvariant = (typeof COMPARE_VERIFICATION_INVARIANTS)[num
  * that fits is the one reported, because a block in the wrong container is a
  * different finding from a block whose words are wrong even when both are true.
  */
-declare const COMPARE_VERIFICATION_CAUSES: readonly ["invisible-structure", "block-count", "container", "inline-structure", "table-geometry", "section-properties", "style", "list-level", "alignment", "spacing", "indentation", "inline-formatting", "whitespace", "text"];
+declare const COMPARE_VERIFICATION_CAUSES: readonly ["invisible-structure", "block-count", "container", "inline-structure", "table-geometry", "section-properties", "style", "list-level", "numbering-source", "alignment", "spacing", "indentation", "inline-formatting", "whitespace", "text"];
 type CompareVerificationCause = (typeof COMPARE_VERIFICATION_CAUSES)[number];
 /** One invariant that did not hold, in one story. */
 type CompareVerificationFailure = {
@@ -33,7 +33,19 @@ type CompareVerification = {
   status: "unverified";
   failures: readonly CompareVerificationFailure[];
 };
-type ProjectedBlock = Pick<FolioAIBlock, "kind" | "headingLevel" | "text" | "table" | "styleId" | "directOutlineLevel" | "listLevel" | "listReference" | "directAlignment" | "directSpacing" | "directIndentation" | "structuralBoundaries">;
+type ProjectedBlockFields = Omit<Pick<FolioAIParagraphBlock, "kind" | "headingLevel" | "text" | "table" | "styleId">, "kind">;
+type ProjectedBlock = ProjectedBlockFields & ({
+  kind: FolioAIDiagnosticBlock["kind"];
+} | {
+  kind: FolioAIParagraphBlock["kind"];
+  statedNumbering: FolioAIParagraphBlock["statedNumbering"];
+  listReference?: FolioAIParagraphBlock["listReference"];
+  structuralBoundaries?: FolioAIParagraphBlock["structuralBoundaries"];
+  directOutlineLevel?: FolioAIParagraphBlock["directOutlineLevel"];
+  directAlignment?: FolioAIParagraphBlock["directAlignment"];
+  directSpacing?: FolioAIParagraphBlock["directSpacing"];
+  directIndentation?: FolioAIParagraphBlock["directIndentation"];
+});
 type ClassifyOptions<T> = {
   invariant: CompareVerificationInvariant;
   story: FolioDocumentStoryHandle;

package/dist/compare/verification.js

@@ -1,6 +1,8 @@
 import { paragraphIndentationEqual } from "../prosemirror/paragraphIndentation.js";
 import { paragraphSpacingEqual } from "../prosemirror/paragraphSpacing.js";
+import { sameFolioContentStatedNumbering } from "./content-types.js";
 import { sameFolioContentOutlineLevel } from "./content.js";
+import { panic } from "better-result";
 import { PARAGRAPH_MARK_CHANGE_KINDS } from "@stll/docx-core/model";
 //#region src/compare/verification.ts
 /**
@@ -38,6 +40,7 @@ const COMPARE_VERIFICATION_CAUSES = Object.freeze([
 	"section-properties",
 	"style",
 	"list-level",
+	"numbering-source",
 	"alignment",
 	"spacing",
 	"indentation",
@@ -65,7 +68,43 @@ const sameStructuralBoundaries = (left, right) => {
 	return true;
 };
 const sameClassification = (left, right) => left.kind === right.kind && left.headingLevel === right.headingLevel;
-const sameProjectedBlock = (left, right) => sameContainer(left.table, right.table) && sameClassification(left, right) && sameStructuralBoundaries(left.structuralBoundaries, right.structuralBoundaries) && left.styleId === right.styleId && sameFolioContentOutlineLevel(left.directOutlineLevel, right.directOutlineLevel) && left.listLevel === right.listLevel && left.listReference?.numId === right.listReference?.numId && left.listReference?.level === right.listReference?.level && left.directAlignment === right.directAlignment && paragraphSpacingEqual(left.directSpacing, right.directSpacing) && paragraphIndentationEqual(left.directIndentation, right.directIndentation) && left.text === right.text;
+const sameProjectedNumbering = (left, right) => {
+	switch (left.kind) {
+		case "diagnostic": return right.kind === "diagnostic";
+		case "paragraph":
+		case "heading":
+		case "listItem": return right.kind !== "diagnostic" && sameFolioContentStatedNumbering(left.statedNumbering, right.statedNumbering);
+		default: return panic("Unhandled projected block kind", { block: left });
+	}
+};
+const sameProjectedListReference = (left, right) => {
+	switch (left.kind) {
+		case "diagnostic": return right.kind === "diagnostic";
+		case "paragraph":
+		case "heading":
+		case "listItem": return right.kind !== "diagnostic" && left.listReference?.numId === right.listReference?.numId && left.listReference?.level === right.listReference?.level;
+		default: return panic("Unhandled projected block kind", { block: left });
+	}
+};
+const sameProjectedStructuralBoundaries = (left, right) => {
+	switch (left.kind) {
+		case "diagnostic": return right.kind === "diagnostic";
+		case "paragraph":
+		case "heading":
+		case "listItem": return right.kind !== "diagnostic" && sameStructuralBoundaries(left.structuralBoundaries, right.structuralBoundaries);
+		default: return panic("Unhandled projected block kind", { block: left });
+	}
+};
+const sameProjectedParagraphFormatting = (left, right, compare) => {
+	switch (left.kind) {
+		case "diagnostic": return right.kind === "diagnostic";
+		case "paragraph":
+		case "heading":
+		case "listItem": return right.kind !== "diagnostic" && compare(left, right);
+		default: return panic("Unhandled projected block kind", { block: left });
+	}
+};
+const sameProjectedBlock = (left, right) => sameContainer(left.table, right.table) && sameClassification(left, right) && sameProjectedStructuralBoundaries(left, right) && left.styleId === right.styleId && sameProjectedParagraphFormatting(left, right, (a, b) => sameFolioContentOutlineLevel(a.directOutlineLevel, b.directOutlineLevel)) && sameProjectedListReference(left, right) && sameProjectedNumbering(left, right) && sameProjectedParagraphFormatting(left, right, (a, b) => a.directAlignment === b.directAlignment) && sameProjectedParagraphFormatting(left, right, (a, b) => paragraphSpacingEqual(a.directSpacing, b.directSpacing)) && sameProjectedParagraphFormatting(left, right, (a, b) => paragraphIndentationEqual(a.directIndentation, b.directIndentation)) && left.text === right.text;
 const containerKind = (container) => container ? "cell" : "body";
 const collapseWhitespace = (text) => text.replace(/\s+/gu, " ").trim();
 const sameBlockProjection = (left, right) => left.length === right.length && left.every((entry, index) => {
@@ -180,15 +219,15 @@ const classifyProjectionMismatch = ({ invariant, story, actual, expected }) => {
 	if (divergence.actual === null || divergence.expected === null) return failure("block-count", `${actual.length > expected.length ? "more" : "fewer"} blocks than expected (${counts}), diverging ${at}`);
 	const { actual: left, expected: right } = divergence;
 	if (!sameContainer(left.table, right.table)) return failure("container", `a block sits in a ${containerKind(left.table)} where it is expected in a ${containerKind(right.table)}, ${at} (${counts})`);
-	if (!sameStructuralBoundaries(left.structuralBoundaries, right.structuralBoundaries)) return failure("inline-structure", `a block's zero-width inline structure does not match ${at} (${counts})`);
+	if (left.kind === right.kind && !sameProjectedStructuralBoundaries(left, right)) return failure("inline-structure", `a block's zero-width inline structure does not match ${at} (${counts})`);
 	if (left.text === right.text && left.styleId !== right.styleId) return failure("style", `the paragraph style did not move ${at} (${counts})`);
-	if (left.text === right.text && !sameFolioContentOutlineLevel(left.directOutlineLevel, right.directOutlineLevel)) return failure("style", `the direct outline level did not move ${at} (${counts})`);
-	if (left.text === right.text && left.listLevel !== right.listLevel) return failure("list-level", `the list level did not move ${at} (${counts})`);
-	if (left.text === right.text && (left.listReference?.numId !== right.listReference?.numId || left.listReference?.level !== right.listReference?.level)) return failure("list-level", `the numbering reference did not move ${at} (${counts})`);
+	if (left.kind === right.kind && left.text === right.text && !sameProjectedParagraphFormatting(left, right, (a, b) => sameFolioContentOutlineLevel(a.directOutlineLevel, b.directOutlineLevel))) return failure("style", `the direct outline level did not move ${at} (${counts})`);
+	if (left.kind === right.kind && left.text === right.text && !sameProjectedListReference(left, right)) return failure("list-level", `the numbering reference did not move ${at} (${counts})`);
+	if (left.kind === right.kind && left.text === right.text && !sameProjectedNumbering(left, right)) return failure("numbering-source", `the authored numbering state did not move ${at} (${counts})`);
 	if (left.text === right.text && !sameClassification(left, right)) return left.kind === "heading" || right.kind === "heading" ? failure("style", `the heading classification did not move ${at} (${counts})`) : failure("list-level", `the list membership did not move ${at} (${counts})`);
-	if (left.text === right.text && left.directAlignment !== right.directAlignment) return failure("alignment", `the direct paragraph alignment did not move ${at} (${counts})`);
-	if (left.text === right.text && !paragraphSpacingEqual(left.directSpacing, right.directSpacing)) return failure("spacing", `the direct paragraph spacing did not move ${at} (${counts})`);
-	if (left.text === right.text && !paragraphIndentationEqual(left.directIndentation, right.directIndentation)) return failure("indentation", `the direct paragraph indentation did not move ${at} (${counts})`);
+	if (left.kind === right.kind && left.text === right.text && !sameProjectedParagraphFormatting(left, right, (a, b) => a.directAlignment === b.directAlignment)) return failure("alignment", `the direct paragraph alignment did not move ${at} (${counts})`);
+	if (left.kind === right.kind && left.text === right.text && !sameProjectedParagraphFormatting(left, right, (a, b) => paragraphSpacingEqual(a.directSpacing, b.directSpacing))) return failure("spacing", `the direct paragraph spacing did not move ${at} (${counts})`);
+	if (left.kind === right.kind && left.text === right.text && !sameProjectedParagraphFormatting(left, right, (a, b) => paragraphIndentationEqual(a.directIndentation, b.directIndentation))) return failure("indentation", `the direct paragraph indentation did not move ${at} (${counts})`);
 	if (collapseWhitespace(left.text) === collapseWhitespace(right.text)) return failure("whitespace", `a block's text differs only in whitespace ${at} (${counts})`);
 	if (actual.length !== expected.length) return failure("block-count", `${counts}, first differing ${at}`);
 	return failure("text", `a ${containerKind(left.table)} block's text does not match ${at}, length ${String(left.text.length)} against ${String(right.text.length)} (${counts})`);