@stll/folio-core 0.52.0 → 0.54.0

package/dist/compare/compare.js

@@ -1,16 +1,19 @@
 import { FolioDocxReviewer, getFolioDocxComparisonAccess } from "../ai-edits/headless.js";
-import { detachFolioAIEditSnapshotExternalHyperlinks, numberingReferenceKeysOf, remapFolioAIEditSnapshotNumberingReferences, remapFolioAIEditSnapshotStyleReferences, sourceDocumentOf, storyTablesOf } from "../ai-edits/snapshot.js";
+import { withComparisonNoteReferenceEdits } from "../ai-edits/note-references.js";
+import { alignedNoteReferenceLabels, detachFolioAIEditSnapshotExternalHyperlinks, numberingReferenceKeysOf, relabelFolioAIEditSnapshotNoteReferences, remapFolioAIEditSnapshotNumberingReferences, remapFolioAIEditSnapshotStyleReferences, sourceDocumentOf, storyTablesOf } from "../ai-edits/snapshot.js";
 import { projectTableGeometry } from "../ai-edits/table-geometry.js";
 import { tableTemplateCanCrossPackageLosslessly } from "../ai-edits/table-template.js";
 import { createScopedWordDiffOptions } from "../ai-edits/word-diff.js";
 import "../document-operations.js";
 import { pairFolioDocumentStories } from "../document-stories.js";
+import { isAltChunkMarkup } from "../docx/altChunk.js";
+import { isOpaqueNestedRowMarkup, opaqueRevisionCarrierName } from "../docx/opaqueCarrier.js";
 import { sectionReferenceHistory } from "../docx/sectionReferenceHistory.js";
 import { sameCanonicalInlinePresentation } from "../internal/compare/inline-presentation.js";
 import { createStyleResolver } from "../prosemirror/styles/styleResolver.js";
 import { canonicalJson } from "../utils/canonicalJson.js";
 import { createContentComparisonWorkSession } from "./content.js";
-import { sameInlineAtoms } from "./inline-atoms.js";
+import { MISSING_NOTE_DETAIL, sameInlineAtoms } from "./inline-atoms.js";
 import { sameAuthoredInlineProvenance } from "./inline-provenance.js";
 import { planStoryCompare } from "./plan.js";
 import { withFixedPackageDates } from "./reproducible-package.js";
@@ -67,6 +70,26 @@ const parseSide = async (buffer, side, author) => await Result.tryPromise({
 		cause
 	})
 });
+const snapshotContainsUnsupportedCarrier = (snapshot) => {
+	let found = false;
+	sourceDocumentOf(snapshot).descendants((node) => {
+		if (node.type.name === "preservedBlock") {
+			const xml = node.attrs["xml"];
+			if (typeof xml === "string" && (isAltChunkMarkup(xml) || opaqueRevisionCarrierName(xml) !== void 0 || isOpaqueNestedRowMarkup(xml))) found = true;
+		}
+		const preserved = node.attrs["_preserved"];
+		if (preserved !== null && typeof preserved === "object" && "children" in preserved) {
+			const children = preserved.children;
+			if (!Array.isArray(children)) return;
+			for (const child of children) {
+				if (child === null || typeof child !== "object" || !("xml" in child)) continue;
+				const xml = child.xml;
+				if (typeof xml === "string" && (opaqueRevisionCarrierName(xml) !== void 0 || isOpaqueNestedRowMarkup(xml))) found = true;
+			}
+		}
+	});
+	return found;
+};
 /** Verify formatting only where the plan claims a text-equal formatting change. */
 const formattingRoundTripFailure = ({ invariant, story, changes, actualBlocks, expectedBlocks, expectedBlockId }) => {
 	const expectedIndexById = new Map(expectedBlocks.map(({ id }, index) => [id, index]));
@@ -286,6 +309,14 @@ const parseComparison = async (base, target, options) => {
 			});
 			continue;
 		}
+		if (snapshotContainsUnsupportedCarrier(baseSnapshot) || snapshotContainsUnsupportedCarrier(targetSnapshot)) {
+			unsupported.push({
+				reason: "unsupported-content",
+				baseStory,
+				targetStory
+			});
+			continue;
+		}
 		const rawBaseSnapshot = baseSnapshot;
 		if (revisionFormat === "folio-exact" && baseStory.type === "main" && getFolioDocxComparisonAccess(reviewer).stageTerminalTableReviewCarrier(sourceDocumentOf(targetSnapshot))) {
 			const staged = reviewer.snapshotStory(baseStory);
@@ -368,6 +399,8 @@ const parseComparison = async (base, target, options) => {
 		unsupported
 	});
 };
+/** The note-reference markers a story's plan is written in: the base's, then the target's new notes. */
+const noteReferenceLabelsOf = (pair) => alignedNoteReferenceLabels(sourceDocumentOf(pair.baseSnapshot), sourceDocumentOf(pair.targetSnapshot));
 const planCopiesNonPortableWholeTable = (pair, plan) => {
 	const targetTables = new Map(storyTablesOf(pair.targetSnapshot).map(({ index, node }) => [index, node]));
 	return plan.tableTemplates.some(({ targetRowIndex, targetTableIndex }) => {
@@ -389,10 +422,11 @@ const planComparison = ({ pairs }) => {
 		const remainingStructuralTokenLookups = workSession.alignment.remainingStructuralTokenLookups;
 		const remainingMoveComparisons = workSession.remainingMoveComparisons;
 		const remainingMoveTokenLookups = workSession.remainingMoveTokenLookups;
+		const planningTarget = relabelFolioAIEditSnapshotNoteReferences(pair.targetSnapshot, noteReferenceLabelsOf(pair));
 		let plan = planStoryCompare({
 			story: pair.baseStory,
 			baseSnapshot: pair.baseSnapshot,
-			targetSnapshot: pair.targetSnapshot,
+			targetSnapshot: planningTarget,
 			maxOperations: remainingOperations,
 			wholeTableReplacement: "allow",
 			workSession
@@ -405,7 +439,7 @@ const planComparison = ({ pairs }) => {
 			plan = planStoryCompare({
 				story: pair.baseStory,
 				baseSnapshot: pair.baseSnapshot,
-				targetSnapshot: pair.targetSnapshot,
+				targetSnapshot: planningTarget,
 				maxOperations: remainingOperations,
 				wholeTableReplacement: "avoid",
 				workSession
@@ -454,7 +488,15 @@ const COMPARE_SKIP_DISPOSITION = {
 	pendingRunPropertyChange: "unwritable",
 	noopOperation: "unwritable",
 	documentVersionMismatch: "fatal",
-	documentNotEditable: "fatal"
+	documentNotEditable: "fatal",
+	payloadDoesNotFit: "unwritable",
+	overlappingOperation: "fatal",
+	splitsCharacter: "unwritable",
+	protectedReference: "unwritable",
+	missingStyle: "fatal",
+	missingNumbering: "fatal",
+	invalidResult: "fatal",
+	pendingDeletion: "unwritable"
 };
 const getCompareSkipDisposition = (reason) => COMPARE_SKIP_DISPOSITION[reason];
 /**
@@ -494,8 +536,10 @@ const resolveTableTemplates = (targetTables, requests) => {
 * what you could not represent" and "give me nothing unless you can prove it"
 * are both legitimate asks and only the caller knows which one it is making.
 */
-const applyComparison = ({ reviewer, revisionStamp, granularity, revisionFormat, terminalTableCarrierStaged, numberingChanges, targetNumbering, targetNumberingReferences, targetNumberingReferenceMap, finalSectionComparison, styleImportFailure, pairs }, planned) => {
+const applyComparison = ({ reviewer, revisionStamp, granularity, revisionFormat, terminalTableCarrierStaged, numberingChanges, targetNumbering, targetNumberingReferences, targetNumberingReferenceMap, finalSectionComparison, styleImportFailure, pairs, unsupported }, planned) => {
 	const relationshipIds = sectionRelationshipMap(pairs);
+	const baseNotes = /* @__PURE__ */ new Set();
+	for (const { baseStory } of [...pairs, ...unsupported]) if (baseStory?.type === "footnote" || baseStory?.type === "endnote") baseNotes.add(`${baseStory.type}:${String(baseStory.noteId)}`);
 	const plannedOperationCount = planned.reduce((count, { plan }) => count + plan.operations.length, 0);
 	const finalSectionOperationCount = finalSectionComparison.status === "stage" ? 1 : 0;
 	if (plannedOperationCount + finalSectionOperationCount > 1e4) return Result.err(new CompareDocxOperationLimitError({
@@ -560,13 +604,14 @@ const applyComparison = ({ reviewer, revisionStamp, granularity, revisionFormat,
 		documentChanged ||= geometryChanged;
 		idSeed = afterGeometry;
 		if (plan.operations.length > 0) {
-			const { skipped, nextRevisionId } = reviewer.applyDocumentOperationsToStory({
+			const operationRevisionStamp = {
+				date: revisionStamp.date,
+				idSeed
+			};
+			const { skipped, nextRevisionId } = withComparisonNoteReferenceEdits(() => reviewer.applyDocumentOperationsToStory({
 				story: pair.baseStory,
 				snapshot: pair.baseSnapshot,
-				revisionStamp: {
-					date: revisionStamp.date,
-					idSeed
-				},
+				revisionStamp: operationRevisionStamp,
 				wordDiff,
 				batch: {
 					version: 1,
@@ -574,8 +619,9 @@ const applyComparison = ({ reviewer, revisionStamp, granularity, revisionFormat,
 					operations: plan.operations
 				},
 				tableTemplates: resolveTableTemplates(targetTables, plan.tableTemplates),
-				replacementBackground: "keep"
-			});
+				replacementBackground: "keep",
+				undefinedStyles: "keep"
+			}));
 			if (nextRevisionId === void 0) panic("The applier did not report where it left the revision-id counter", { story: pair.baseStory });
 			idSeed = nextRevisionId;
 			documentChanged = true;
@@ -614,6 +660,8 @@ const applyComparison = ({ reviewer, revisionStamp, granularity, revisionFormat,
 		const atoms = comparisonAccess.matchInlineAtoms({
 			story: pair.baseStory,
 			targetSnapshot: pair.targetSnapshot,
+			noteReferenceLabels: noteReferenceLabelsOf(pair),
+			baseNotes,
 			revisionStamp: {
 				date: revisionStamp.date,
 				idSeed
@@ -646,7 +694,7 @@ const applyComparison = ({ reviewer, revisionStamp, granularity, revisionFormat,
 					invariant: "accept-reproduces-target",
 					cause: "inline-structure",
 					story: pair.baseStory,
-					detail: "supported inline atoms could not be aligned to the revised content"
+					detail: atoms.detail ?? "supported inline atoms could not be aligned to the revised content"
 				});
 				break;
 			case "budget-exceeded": return Result.err(new CompareDocxOperationLimitError({
@@ -927,8 +975,9 @@ const compareDocx = async (base, target, options) => {
 	const applied = applyComparison(parsed.value, planned.value);
 	if (applied.isErr()) return Result.err(applied.error);
 	const { changes, verification } = applied.value;
-	if (verification.status === "unverified" && (options.onUnverified ?? "refuse") === "refuse") {
-		const [firstFailure] = verification.failures;
+	const missingNote = verification.status === "unverified" ? verification.failures.find(({ detail }) => detail === MISSING_NOTE_DETAIL) : void 0;
+	if (verification.status === "unverified" && (missingNote !== void 0 || (options.onUnverified ?? "refuse") === "refuse")) {
+		const firstFailure = missingNote ?? verification.failures[0];
 		if (firstFailure === void 0) panic("An unverified comparison reported no failing invariant");
 		return Result.err(new CompareDocxRoundTripError({
 			message: `The generated tracked changes do not satisfy ${firstFailure.invariant}: ${firstFailure.detail}`,

package/dist/compare/content-alignment.d.ts

@@ -17,6 +17,10 @@ type FolioContentBlockPair = {
   baseIndex: number;
   revisedIndex: number;
 };
+type IncreasingPairOptions = {
+  priority?: (pair: FolioContentBlockPair) => number;
+  tieBreak?: "earliest" | "minimum-tail";
+};
 /**
  * Longest strictly increasing subsequence by revised index.
  *
@@ -24,7 +28,7 @@ type FolioContentBlockPair = {
  * preserving the historical deterministic tie break while reducing the
  * stable-anchor pass from quadratic to O(n log n).
  */
-declare const longestIncreasingFolioContentPairs: (pairs: readonly FolioContentBlockPair[]) => FolioContentBlockPair[];
+declare const longestIncreasingFolioContentPairs: (pairs: readonly FolioContentBlockPair[], options?: IncreasingPairOptions) => FolioContentBlockPair[];
 type FolioContentAlignedBlockEvent<Block extends FolioContentBlock = FolioContentBlock> = {
   type: "pair";
   baseBlock: Block;

package/dist/compare/content-alignment.js

@@ -45,15 +45,29 @@ const folioContentIdStability = (block) => block.idStability ?? "stable";
 * preserving the historical deterministic tie break while reducing the
 * stable-anchor pass from quadratic to O(n log n).
 */
-const longestIncreasingFolioContentPairs = (pairs) => {
+const longestIncreasingFolioContentPairs = (pairs, options = {}) => {
 	if (pairs.length === 0) return [];
 	const coordinates = [...new Set(pairs.map(({ revisedIndex }) => revisedIndex))].toSorted((left, right) => left - right);
 	const rankByCoordinate = new Map(coordinates.map((coordinate, index) => [coordinate, index + 1]));
-	const treeLengths = new Int32Array(coordinates.length + 1);
 	const treeIndexes = new Int32Array(coordinates.length + 1).fill(-1);
 	const lengths = new Int32Array(pairs.length).fill(1);
 	const predecessors = new Int32Array(pairs.length).fill(-1);
-	const earlier = (leftLength, leftIndex, rightLength, rightIndex) => leftLength > rightLength || leftLength === rightLength && leftLength > 0 && leftIndex < rightIndex;
+	const priorities = new Int32Array(pairs.length);
+	const earlier = ({ leftIndex, rightIndex }) => {
+		const leftLength = lengths[leftIndex] ?? 0;
+		const rightLength = lengths[rightIndex] ?? 0;
+		if (leftLength !== rightLength) return leftLength > rightLength;
+		if (leftLength === 0) return false;
+		const leftPriority = priorities[leftIndex] ?? 0;
+		const rightPriority = priorities[rightIndex] ?? 0;
+		if (leftPriority !== rightPriority) return leftPriority > rightPriority;
+		if (options.tieBreak === "minimum-tail") {
+			const leftTail = pairs[leftIndex]?.revisedIndex ?? Number.POSITIVE_INFINITY;
+			const rightTail = pairs[rightIndex]?.revisedIndex ?? Number.POSITIVE_INFINITY;
+			if (leftTail !== rightTail) return leftTail < rightTail;
+		}
+		return leftIndex < rightIndex;
+	};
 	let bestEnd = 0;
 	let groupStart = 0;
 	while (groupStart < pairs.length) {
@@ -63,32 +77,38 @@ const longestIncreasingFolioContentPairs = (pairs) => {
 		for (let pairIndex = groupStart; pairIndex < groupEnd; pairIndex++) {
 			const pair = pairs[pairIndex];
 			const rank = pair === void 0 ? void 0 : rankByCoordinate.get(pair.revisedIndex);
-			if (rank === void 0) continue;
+			if (rank === void 0 || pair === void 0) continue;
 			let predecessorLength = 0;
 			let predecessorIndex = -1;
 			for (let cursor = rank - 1; cursor > 0; cursor -= cursor & -cursor) {
-				const candidateLength = treeLengths[cursor] ?? 0;
 				const candidateIndex = treeIndexes[cursor] ?? -1;
-				if (earlier(candidateLength, candidateIndex, predecessorLength, predecessorIndex)) {
+				const candidateLength = lengths[candidateIndex] ?? 0;
+				if (earlier({
+					leftIndex: candidateIndex,
+					rightIndex: predecessorIndex
+				})) {
 					predecessorLength = candidateLength;
 					predecessorIndex = candidateIndex;
 				}
 			}
 			lengths[pairIndex] = predecessorLength + 1;
 			predecessors[pairIndex] = predecessorIndex;
-			if ((lengths[pairIndex] ?? 0) > (lengths[bestEnd] ?? 0)) bestEnd = pairIndex;
+			priorities[pairIndex] = (priorities[predecessorIndex] ?? 0) + (options.priority?.(pair) ?? 0);
+			if (earlier({
+				leftIndex: pairIndex,
+				rightIndex: bestEnd
+			})) bestEnd = pairIndex;
 		}
 		for (let pairIndex = groupStart; pairIndex < groupEnd; pairIndex++) {
 			const pair = pairs[pairIndex];
 			const rank = pair === void 0 ? void 0 : rankByCoordinate.get(pair.revisedIndex);
 			if (rank === void 0) continue;
-			for (let cursor = rank; cursor < treeLengths.length; cursor += cursor & -cursor) {
-				const currentLength = treeLengths[cursor] ?? 0;
+			for (let cursor = rank; cursor < treeIndexes.length; cursor += cursor & -cursor) {
 				const currentIndex = treeIndexes[cursor] ?? -1;
-				if (earlier(lengths[pairIndex] ?? 0, pairIndex, currentLength, currentIndex)) {
-					treeLengths[cursor] = lengths[pairIndex] ?? 0;
-					treeIndexes[cursor] = pairIndex;
-				}
+				if (earlier({
+					leftIndex: pairIndex,
+					rightIndex: currentIndex
+				})) treeIndexes[cursor] = pairIndex;
 			}
 		}
 		groupStart = groupEnd;
@@ -238,27 +258,14 @@ const pairByUniqueExactText = ({ base, revised, baseFrom, baseTo, revisedFrom, r
 	}
 	const orderedCandidates = candidates.toSorted((left, right) => left.baseIndex - right.baseIndex || left.revisedIndex - right.revisedIndex);
 	if (orderedCandidates.length === 0) return [];
-	const tailRevisedIndexes = [];
-	const tailCandidateIndexes = [];
-	const predecessors = new Int32Array(orderedCandidates.length).fill(-1);
-	orderedCandidates.forEach((candidate, candidateIndex) => {
-		let lower = 0;
-		let upper = tailRevisedIndexes.length;
-		while (lower < upper) {
-			const middle = lower + Math.floor((upper - lower) / 2);
-			if ((tailRevisedIndexes[middle] ?? Number.POSITIVE_INFINITY) < candidate.revisedIndex) lower = middle + 1;
-			else upper = middle;
+	return longestIncreasingFolioContentPairs(orderedCandidates, {
+		tieBreak: "minimum-tail",
+		priority: ({ baseIndex, revisedIndex }) => {
+			const baseBlock = base[baseIndex];
+			const revisedBlock = revised[revisedIndex];
+			return baseBlock && revisedBlock && baseBlock.pairingFacts.id === revisedBlock.pairingFacts.id && baseBlock.pairingFacts.idStability !== revisedBlock.pairingFacts.idStability ? 1 : 0;
 		}
-		predecessors[candidateIndex] = lower === 0 ? -1 : tailCandidateIndexes[lower - 1] ?? -1;
-		tailRevisedIndexes[lower] = candidate.revisedIndex;
-		tailCandidateIndexes[lower] = candidateIndex;
 	});
-	const pairs = [];
-	for (let candidateIndex = tailCandidateIndexes.at(-1) ?? -1; candidateIndex !== -1; candidateIndex = predecessors[candidateIndex] ?? -1) {
-		const candidate = orderedCandidates[candidateIndex];
-		if (candidate) pairs.push(candidate);
-	}
-	return pairs.toReversed();
 };
 /**
 * Unique exact text anchors, then again inside every sub-gap they leave:
@@ -1331,7 +1338,7 @@ const pairTableRows = ({ baseRows, revisedRows, workSession, idStability }) => {
 		item: row,
 		profile: rowStructureProfile(row, idStability)
 	});
-	return alignProfiledContentSequence({
+	const aligned = alignProfiledContentSequence({
 		base: baseRows.map(profile),
 		revised: revisedRows.map(profile),
 		workSession,
@@ -1339,7 +1346,18 @@ const pairTableRows = ({ baseRows, revisedRows, workSession, idStability }) => {
 		soleShiftedPairResiduePolicy: "row-count-evidence",
 		primaryEvidence: "exact",
 		similarityFactor: (base, revised) => base.profile.physicalCellCount === revised.profile.physicalCellCount ? 1 : .5
-	}).map((alignment) => {
+	});
+	const baseRow = baseRows.at(0);
+	const revisedRow = revisedRows.at(0);
+	if (baseRows.length === 1 && baseRow !== void 0 && revisedRow !== void 0 && !aligned.some(({ type }) => type === "pair")) return [{
+		type: "pair",
+		baseRow,
+		revisedRow
+	}, ...revisedRows.slice(1).map((row) => ({
+		type: "revisedOnly",
+		row
+	}))];
+	return aligned.map((alignment) => {
 		switch (alignment.type) {
 			case "pair": return {
 				type: "pair",

package/dist/compare/content-types.d.ts

@@ -116,8 +116,15 @@ type FolioContentBlock<Kind extends string = string> = {
   idStability?: FolioContentIdStability;
   /** One-based heading depth when the block has outline semantics. */
   headingLevel?: number;
+  /**
+   * The number or bullet the block shows beside its text (`2.1.`, `a)`, `•`),
+   * a numbered heading's included; an unnumbered heading's style id. Absent
+   * when the block shows neither, a marker its level hides included.
+   */
   displayLabel?: string;
   styleId?: string;
+  /** Authored `w:outlineLvl`; absent when heading depth comes only from a style. */
+  directOutlineLevel?: document_d_exports.OutlineLevel;
   /** Direct paragraph alignment; absent when alignment comes only from a style. */
   directAlignment?: FolioContentParagraphAlignment;
   /** Direct paragraph spacing; absent when every spacing value is inherited. */

package/dist/compare/content.d.ts

@@ -55,12 +55,15 @@ type FolioContentTextSegment = {
 /** Target-side paragraph properties that differ from the base block. */
 type FolioContentParagraphFormattingPatch = {
   styleId?: string | null;
+  outlineLevel?: FolioContentBlock["directOutlineLevel"] | null;
   listLevel?: number | null;
   listReference?: FolioContentListReference | null;
   alignment?: FolioContentBlock["directAlignment"] | null;
   spacing?: FolioContentParagraphSpacing | null;
   indentation?: FolioContentParagraphIndentation | null;
 };
+/** Authored outline identity, including the distinction between heading and body text. */
+declare const sameFolioContentOutlineLevel: (left: FolioContentBlock["directOutlineLevel"], right: FolioContentBlock["directOutlineLevel"]) => boolean;
 /** Presentation differences for one text-aligned block pair. */
 type FolioContentFormattingChange = {
   paragraph?: FolioContentParagraphFormattingPatch;
@@ -210,4 +213,4 @@ declare const compareAlignedFolioContent: <Block extends FolioContentBlock>({ ba
 /** Compare two representation-neutral ordered content snapshots. */
 declare const compareContent: <Block extends FolioContentBlock = FolioContentBlock>(options: CompareContentOptions<Block>) => Result<FolioContentComparison<Block>, FolioContentComparisonError>;
 //#endregion
-export { CompareContentOptions, FOLIO_CONTENT_COMPARISON_LIMITS, FolioContentBlockProperty, FolioContentComparison, FolioContentComparisonError, FolioContentComparisonEvent, FolioContentComparisonLimit, FolioContentComparisonLimitError, FolioContentComparisonWorkSession, type FolioContentFormatRange, FolioContentFormattingChange, FolioContentInlinePresentationProjectionError, FolioContentParagraphFormattingPatch, FolioContentStructuralChange, FolioContentTextSegment, InvalidFolioContentComparisonError, changedFolioContentParagraphFormatting, compareAlignedFolioContent, compareContent, createContentComparisonWorkSession, detectFolioContentMoves, detectFolioContentParagraphMarkPlans };
+export { CompareContentOptions, FOLIO_CONTENT_COMPARISON_LIMITS, FolioContentBlockProperty, FolioContentComparison, FolioContentComparisonError, FolioContentComparisonEvent, FolioContentComparisonLimit, FolioContentComparisonLimitError, FolioContentComparisonWorkSession, type FolioContentFormatRange, FolioContentFormattingChange, FolioContentInlinePresentationProjectionError, FolioContentParagraphFormattingPatch, FolioContentStructuralChange, FolioContentTextSegment, InvalidFolioContentComparisonError, changedFolioContentParagraphFormatting, compareAlignedFolioContent, compareContent, createContentComparisonWorkSession, detectFolioContentMoves, detectFolioContentParagraphMarkPlans, sameFolioContentOutlineLevel };

package/dist/compare/content.js

@@ -1,4 +1,5 @@
 import { WORD_DIFF_GRANULARITIES, createWordDiffSession } from "../ai-edits/word-diff.js";
+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";
@@ -43,6 +44,8 @@ const MAX_MOVE_PROFILE_CODE_UNITS = 1048576;
 var InvalidFolioContentComparisonError = class extends TaggedError("InvalidFolioContentComparisonError") {};
 var FolioContentComparisonLimitError = class extends TaggedError("FolioContentComparisonLimitError") {};
 var FolioContentInlinePresentationProjectionError = class extends TaggedError("FolioContentInlinePresentationProjectionError") {};
+/** Authored outline identity, including the distinction between heading and body text. */
+const sameFolioContentOutlineLevel = (left, right) => left?.kind === right?.kind && (left?.kind !== "heading" || right?.kind === "heading" && left.level === right.level);
 const createContentComparisonWorkSession = (granularity) => ({
 	alignment: createFolioContentAlignmentWorkSession(),
 	remainingMoveComparisons: MAX_MOVE_SIMILARITY_COMPARISONS,
@@ -99,6 +102,7 @@ const validateParagraphFormatting = (block, side, 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.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;
 	if (!isRecord(spacing)) return invalidInput(side, `blocks[${String(blockIndex)}].directSpacing`, "Direct paragraph spacing must be an object.", blockIndex);
@@ -409,6 +413,7 @@ const paragraphSpacingEqual = (base, revised) => base?.spaceBefore === revised?.
 const changedFolioContentParagraphFormatting = (base, revised) => {
 	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;
@@ -950,4 +955,4 @@ const compareContent = (options) => {
 	});
 };
 //#endregion
-export { FOLIO_CONTENT_COMPARISON_LIMITS, FolioContentComparisonLimitError, FolioContentInlinePresentationProjectionError, InvalidFolioContentComparisonError, changedFolioContentParagraphFormatting, compareAlignedFolioContent, compareContent, createContentComparisonWorkSession, detectFolioContentMoves, detectFolioContentParagraphMarkPlans };
+export { FOLIO_CONTENT_COMPARISON_LIMITS, FolioContentComparisonLimitError, FolioContentInlinePresentationProjectionError, InvalidFolioContentComparisonError, changedFolioContentParagraphFormatting, compareAlignedFolioContent, compareContent, createContentComparisonWorkSession, detectFolioContentMoves, detectFolioContentParagraphMarkPlans, sameFolioContentOutlineLevel };

package/dist/compare/formatting.js

@@ -5,7 +5,8 @@ import { canonicalInlinePresentationSegments } from "../internal/compare/inline-
 const inlineFormattingSegments = ({ baseBlock, targetBlock, maxSegments }) => canonicalInlinePresentationSegments({
 	baseBlock,
 	revisedBlock: targetBlock,
-	maxSegments
+	maxSegments,
+	presentationBasis: baseBlock.styleId === targetBlock.styleId ? "full" : "authored"
 });
 //#endregion
 export { inlineFormattingSegments };

package/dist/compare/inline-atoms.d.ts

@@ -1,7 +1,8 @@
 import { FolioAIEditSnapshot } from "../ai-edits/types.js";
 import { FolioRevisionStamp } from "../ai-edits/apply.js";
-import { EditorState, Transaction } from "prosemirror-state";
+import { NoteReferenceLabels } from "../ai-edits/note-references.js";
 import { Node } from "prosemirror-model";
+import { EditorState, Transaction } from "prosemirror-state";
 //#region src/compare/inline-atoms.d.ts
 type MatchInlineAtomsOptions = {
   state: EditorState;
@@ -11,6 +12,17 @@ type MatchInlineAtomsOptions = {
   originalRevisionIdSeed: number;
   author: string;
   maxRanges: number;
+  /**
+   * The markers the comparison's operations wrote note references as.
+   * Defaults to the target story's own numbering.
+   */
+  noteReferenceLabels?: NoteReferenceLabels;
+  /**
+   * The notes the base package defines, as `footnote:<id>` / `endnote:<id>`.
+   * A reference the comparison writes may only name one of them. Defaults to
+   * the notes the story already references.
+   */
+  baseNotes?: ReadonlySet<string>;
 };
 type MatchInlineAtomsResult = {
   status: "matched";
@@ -20,16 +32,21 @@ type MatchInlineAtomsResult = {
   rangeCount: number;
 } | {
   status: "unalignable";
+  /** Why, when the cause is more specific than an alignment failure. */
+  detail?: string;
 } | {
   status: "budget-exceeded";
 };
+/** A revised reference names a note the redline's package does not have. */
+declare const MISSING_NOTE_DETAIL = "a note reference names a footnote or endnote the base document does not have";
 /**
- * Restore field, image, and page-break atoms omitted by text-only comparison operations.
+ * Restore field, image, and page-break atoms omitted by text-only comparison
+ * operations, and the note references whose markers they wrote as text.
  * Positions come from the legacy review resolver's mapping, never a guessed
  * paragraph correspondence: paragraph-mark deletions can merge paragraphs.
  */
-declare const matchInlineAtoms: ({ state, targetSnapshot, revisionStamp, originalRevisionIdSeed, author, maxRanges }: MatchInlineAtomsOptions) => MatchInlineAtomsResult;
+declare const matchInlineAtoms: ({ state, targetSnapshot, revisionStamp, originalRevisionIdSeed, author, maxRanges, noteReferenceLabels, baseNotes }: MatchInlineAtomsOptions) => MatchInlineAtomsResult;
 /** Compare supported inline atom identity after accept or reject projection. */
 declare const sameInlineAtoms: (leftDocument: Node, rightDocument: Node) => boolean;
 //#endregion
-export { MatchInlineAtomsOptions, MatchInlineAtomsResult, matchInlineAtoms, sameInlineAtoms };
+export { MISSING_NOTE_DETAIL, MatchInlineAtomsOptions, MatchInlineAtomsResult, matchInlineAtoms, sameInlineAtoms };