@stll/folio-core 0.52.0 → 0.53.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.js

@@ -1331,7 +1331,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 +1339,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 };

package/dist/compare/inline-atoms.js

@@ -1,10 +1,14 @@
 import { buildCleanBlockText } from "../ai-edits/clean-text.js";
-import { sourceDocumentOf } from "../ai-edits/snapshot.js";
+import { noteReferenceOf } from "../ai-edits/note-references.js";
+import { collectNoteReferenceLabels, sourceDocumentOf } from "../ai-edits/snapshot.js";
+import { drawingXmlWithoutIdentity } from "../docx/drawingIdNormalization.js";
 import { resolveAllChangesInHeadlessStateWithMapping } from "../prosemirror/commands/comments.js";
 import { runFormattingInlineAtomResultText } from "../prosemirror/runFormattingInlineCarriers.js";
 import { canonicalJson } from "../utils/canonicalJson.js";
 import { prepareTargetInlineAtom } from "./inline-atom-resources.js";
 //#region src/compare/inline-atoms.ts
+/** A revised reference names a note the redline's package does not have. */
+const MISSING_NOTE_DETAIL = "a note reference names a footnote or endnote the base document does not have";
 const actionRangeCount = (action) => action.kind === "replace-text" && action.textDisposition === "retained" || action.kind === "replace-atom" && action.atomDisposition === "retained" ? 2 : 1;
 const MAX_INLINE_ATOM_LCS_CELLS = 16384;
 const isSupportedAtom = (node) => node.isInline && node.isAtom && (node.type.name === "field" || node.type.name === "image" || node.type.name === "pageBreakRun");
@@ -65,6 +69,11 @@ const offsetAt = ({ offsets, position }) => {
 */
 const CONVERSION_LOCAL_ATTRS = { textBoxAnchor: ["anchorId"] };
 const documentFactAttrs = (node) => {
+	if (node.type.name === "field" || node.type.name === "structuredField") {
+		const equivalentFieldForms = node.type.name === "field" && (node.attrs["fieldKind"] === "simple" || node.attrs["fieldKind"] === "complex") && node.attrs["fieldResultIsFallback"] == null;
+		return Object.fromEntries(Object.entries(node.attrs).filter(([name]) => name !== "_docxFieldCode" && (!equivalentFieldForms || name !== "fieldKind")));
+	}
+	if (node.type.name === "image") return Object.fromEntries(Object.entries(node.attrs).filter(([name]) => name !== "docPrId").map(([name, value]) => [name, name === "_docxRawXml" && typeof value === "string" ? drawingXmlWithoutIdentity(value) : value]));
 	const local = CONVERSION_LOCAL_ATTRS[node.type.name];
 	if (!local) return node.attrs;
 	return Object.fromEntries(Object.entries(node.attrs).filter(([name]) => !local.includes(name)));
@@ -74,8 +83,22 @@ const atomKey = (node) => canonicalJson({
 	attrs: documentFactAttrs(node),
 	content: node.content.toJSON()
 });
-const atomBlockOf = ({ node, from }, fieldResults) => {
-	const clean = buildCleanBlockText(node, from, { fieldResults });
+const atomBlockOf = ({ node, from }, fieldResults, noteReferences) => {
+	const clean = buildCleanBlockText(node, from, {
+		fieldResults,
+		noteReferences
+	});
+	const references = [];
+	for (const boundary of clean.structuralBoundaries) {
+		if (boundary.type !== "noteReference") continue;
+		references.push({
+			noteType: boundary.noteType,
+			noteId: boundary.noteId,
+			offset: boundary.offset,
+			length: boundary.length,
+			from: boundary.from
+		});
+	}
 	const supported = [];
 	const unsupportedTopology = [];
 	node.descendants((child, relativePosition) => {
@@ -116,7 +139,8 @@ const atomBlockOf = ({ node, from }, fieldResults) => {
 		cleanText: clean.text,
 		offsets: clean.offsets,
 		supported,
-		unsupportedTopology
+		unsupportedTopology,
+		noteReferences: references
 	};
 };
 const targetBlockIdLookup = (snapshot) => {
@@ -138,7 +162,44 @@ const targetBlockIdLookup = (snapshot) => {
 		return owner?.id;
 	};
 };
-const atomBlocksOf = (doc, fieldResults) => textBlocksOf(doc).map((block) => atomBlockOf(block, fieldResults));
+const atomBlocksOf = (doc, fieldResults, noteReferences = "sourceText") => textBlocksOf(doc).map((block) => atomBlockOf(block, fieldResults, noteReferences));
+const noteReferenceKey = ({ noteType, noteId }) => `${noteType}:${noteId}`;
+/** Every note a story references, tracked-deleted references included. */
+const referencedNotesOf = (doc) => {
+	const notes = /* @__PURE__ */ new Set();
+	doc.descendants((node) => {
+		const reference = noteReferenceOf(node);
+		if (reference) notes.add(noteReferenceKey(reference));
+		return !node.isText;
+	});
+	return notes;
+};
+const hasNoteReference = (doc) => {
+	let found = false;
+	doc.descendants((node) => {
+		if (found) return false;
+		if (noteReferenceOf(node)) found = true;
+		return !node.isText;
+	});
+	return found;
+};
+/**
+* Whether this comparison inserted text that may stand for a note reference.
+* Operations carry clean text, where a reference reads as its marker, so an
+* operation that brings a reference writes the marker as text.
+*/
+const wroteNoteReferenceMarker = (doc, originalRevisionIdSeed) => {
+	let found = false;
+	doc.descendants((node) => {
+		if (found) return false;
+		if (!node.isText) return true;
+		if (!node.text?.includes("[^") || noteReferenceOf(node)) return false;
+		const revisionId = node.marks.find(({ type }) => type.name === "insertion")?.attrs["revisionId"];
+		if (typeof revisionId === "number" && revisionId >= originalRevisionIdSeed) found = true;
+		return false;
+	});
+	return found;
+};
 const sameBlockTopology = (left, right) => {
 	if (left.node.type !== right.node.type || left.cleanText !== right.cleanText) return false;
 	const supportedOffsets = /* @__PURE__ */ new Set([...left.supported.map(({ offset }) => offset), ...right.supported.map(({ offset }) => offset)]);
@@ -279,12 +340,15 @@ const sourceTextBlockIds = (source) => {
 	}
 	return blocks;
 };
-const sameParagraphSourcePosition = ({ sourceBlocks, reviewed, offset, fieldResults }) => {
+const sameParagraphSourcePosition = ({ sourceBlocks, reviewed, offset, fieldResults, noteReferences }) => {
 	const paraId = reviewed.node.attrs["paraId"];
 	if (typeof paraId !== "string" || paraId.length === 0) return null;
 	const source = sourceBlocks.get(paraId);
 	if (!source || source.node.type !== reviewed.node.type) return null;
-	const clean = buildCleanBlockText(source.node, source.from, { fieldResults });
+	const clean = buildCleanBlockText(source.node, source.from, {
+		fieldResults,
+		noteReferences
+	});
 	return clean.text === reviewed.cleanText ? clean.offsets[offset] ?? null : null;
 };
 const textRangeDisposition = ({ doc, from, to, expectedText, originalRevisionIdSeed }) => {
@@ -332,14 +396,17 @@ const atomDisposition = ({ atom, originalRevisionIdSeed }) => {
 	return typeof revisionId === "number" && revisionId >= originalRevisionIdSeed ? "inserted" : null;
 };
 /**
-* 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.
 */
-const matchInlineAtoms = ({ state, targetSnapshot, revisionStamp, originalRevisionIdSeed, author, maxRanges }) => {
+const matchInlineAtoms = ({ state, targetSnapshot, revisionStamp, originalRevisionIdSeed, author, maxRanges, noteReferenceLabels, baseNotes }) => {
 	if (!Number.isSafeInteger(maxRanges) || maxRanges < 0) return { status: "budget-exceeded" };
 	const targetDocument = sourceDocumentOf(targetSnapshot);
-	if (!hasSupportedAtom(state.doc) && !hasSupportedAtom(targetDocument)) return {
+	const restoresNoteReferences = wroteNoteReferenceMarker(state.doc, originalRevisionIdSeed) && hasNoteReference(targetDocument);
+	const noteReferences = restoresNoteReferences ? noteReferenceLabels ?? collectNoteReferenceLabels(targetDocument) : "sourceText";
+	if (!restoresNoteReferences && !hasSupportedAtom(state.doc) && !hasSupportedAtom(targetDocument)) return {
 		status: "matched",
 		transaction: state.tr,
 		nextRevisionId: revisionStamp.idSeed,
@@ -349,8 +416,8 @@ const matchInlineAtoms = ({ state, targetSnapshot, revisionStamp, originalRevisi
 	const reviewed = resolveAllChangesInHeadlessStateWithMapping(state, "accept");
 	const targetBlockIdAt = targetBlockIdLookup(targetSnapshot);
 	let sourceBlocks;
-	const liveBlocks = atomBlocksOf(reviewed.state.doc, "text");
-	const targetBlocks = atomBlocksOf(targetDocument, "text");
+	const liveBlocks = atomBlocksOf(reviewed.state.doc, "text", noteReferences);
+	const targetBlocks = atomBlocksOf(targetDocument, "text", noteReferences);
 	if (liveBlocks.length !== targetBlocks.length) return { status: "unalignable" };
 	const actions = [];
 	let rangeCount = 0;
@@ -361,19 +428,63 @@ const matchInlineAtoms = ({ state, targetSnapshot, revisionStamp, originalRevisi
 		actions.push(action);
 		return true;
 	};
+	let referencedNotes;
 	let omittedLiveBlocks;
 	let omittedTargetBlocks;
 	for (const [index, fullLive] of liveBlocks.entries()) {
 		const fullTarget = targetBlocks[index];
 		if (!fullTarget) return { status: "unalignable" };
+		if ((fullLive.noteReferences.length > 0 || fullTarget.noteReferences.length > 0) && fullLive.cleanText === fullTarget.cleanText) {
+			const kept = new Map(fullLive.noteReferences.map((reference) => [reference.offset, reference]));
+			for (const reference of fullTarget.noteReferences) {
+				const live = kept.get(reference.offset);
+				if (live) {
+					kept.delete(reference.offset);
+					if (noteReferenceKey(live) !== noteReferenceKey(reference) || live.length !== reference.length) return { status: "unalignable" };
+					continue;
+				}
+				referencedNotes ??= baseNotes ?? referencedNotesOf(state.doc);
+				if (!referencedNotes.has(noteReferenceKey(reference))) return {
+					status: "unalignable",
+					detail: MISSING_NOTE_DETAIL
+				};
+				const node = targetDocument.nodeAt(reference.from);
+				const reviewedFrom = fullLive.offsets[reference.offset];
+				const reviewedLast = fullLive.offsets[reference.offset + reference.length - 1];
+				if (!node || !noteReferenceOf(node) || reviewedFrom === void 0 || reviewedLast === void 0) return { status: "unalignable" };
+				const from = mappedSourcePosition({
+					mapping: reviewed.mapping,
+					position: reviewedFrom
+				});
+				const to = mappedSourcePosition({
+					mapping: reviewed.mapping,
+					position: reviewedLast + 1
+				});
+				if (from === null || to === null || textRangeDisposition({
+					doc: state.doc,
+					from,
+					to,
+					expectedText: fullTarget.cleanText.slice(reference.offset, reference.offset + reference.length),
+					originalRevisionIdSeed
+				}) !== "inserted") return { status: "unalignable" };
+				if (!planAction({
+					kind: "note-reference",
+					from,
+					to,
+					node,
+					targetBlockId: targetBlockIdAt(fullTarget.from)
+				})) return { status: "budget-exceeded" };
+			}
+			if (kept.size > 0) return { status: "unalignable" };
+		}
 		if (fullLive.supported.length === 0 && fullTarget.supported.length === 0) continue;
 		if (sameSupportedAtoms(fullLive, fullTarget)) continue;
 		let live = fullLive;
 		let target = fullTarget;
 		let fieldResults = "text";
 		if (!sameBlockTopology(live, target)) {
-			omittedLiveBlocks ??= atomBlocksOf(reviewed.state.doc, "omitted");
-			omittedTargetBlocks ??= atomBlocksOf(targetDocument, "omitted");
+			omittedLiveBlocks ??= atomBlocksOf(reviewed.state.doc, "omitted", noteReferences);
+			omittedTargetBlocks ??= atomBlocksOf(targetDocument, "omitted", noteReferences);
 			const omittedLive = omittedLiveBlocks[index];
 			const omittedTarget = omittedTargetBlocks[index];
 			if (!omittedLive || !omittedTarget || !sameBlockTopology(omittedLive, omittedTarget)) return { status: "unalignable" };
@@ -441,7 +552,8 @@ const matchInlineAtoms = ({ state, targetSnapshot, revisionStamp, originalRevisi
 				sourceBlocks: sourceBlocks ??= sourceTextBlockIds(state.doc),
 				reviewed: live,
 				offset: atom.offset,
-				fieldResults
+				fieldResults,
+				noteReferences
 			});
 			if (from === null) return { status: "unalignable" };
 			const resultText = runFormattingInlineAtomResultText(atom.node);
@@ -520,6 +632,16 @@ const matchInlineAtoms = ({ state, targetSnapshot, revisionStamp, originalRevisi
 			if (action.targetBlockId) changedTargetBlockIds.add(action.targetBlockId);
 			continue;
 		}
+		if (action.kind === "note-reference") {
+			const from = transaction.mapping.map(action.from, 1);
+			const to = transaction.mapping.map(action.to, -1);
+			const written = transaction.doc.nodeAt(from);
+			const noteMark = action.node.marks.find(({ type }) => type.name === "footnoteRef");
+			if (from >= to || !written?.isText || !noteMark) return { status: "unalignable" };
+			transaction.replaceWith(from, to, state.schema.text(action.node.text ?? "", noteMark.addToSet(written.marks)));
+			if (action.targetBlockId) changedTargetBlockIds.add(action.targetBlockId);
+			continue;
+		}
 		if (action.kind === "replace-atom") {
 			const from = transaction.mapping.map(action.from, 1);
 			const to = transaction.mapping.map(action.to, -1);
@@ -581,4 +703,4 @@ const sameInlineAtoms = (leftDocument, rightDocument) => {
 	});
 };
 //#endregion
-export { matchInlineAtoms, sameInlineAtoms };
+export { MISSING_NOTE_DETAIL, matchInlineAtoms, sameInlineAtoms };

package/dist/compare/plan.js

@@ -223,6 +223,7 @@ const shareAContainer = (left, right) => {
 /** Narrow the neutral patch to the operation contract without explicit undefined fields. */
 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.alignment !== void 0 && { alignment: properties.alignment },
@@ -594,18 +595,22 @@ const planStoryCompare = ({ story, baseSnapshot, targetSnapshot, maxOperations,
 		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 shared = {
-			text: block.text,
-			...(block.text.includes("	") || block.text.includes("\n")) && { lineBreakMode: "inline" },
-			...moveSourceId !== void 0 && { moveId: moveIdOf(moveSourceId) },
-			...hardPageBreak !== void 0 && { hardPageBreak },
+		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
 		};
+		const shared = {
+			text: block.text,
+			...(block.text.includes("	") || block.text.includes("\n")) && { lineBreakMode: "inline" },
+			...moveSourceId !== void 0 && { moveId: moveIdOf(moveSourceId) },
+			...hardPageBreak !== void 0 && { hardPageBreak },
+			...paragraphProperties
+		};
 		if (anchorId !== null) {
 			operations.push({
 				id: nextOperationId(),