@stll/folio-core 0.52.0 → 0.53.0

package/dist/ai-edits/batch-claims.d.ts

@@ -0,0 +1,130 @@
+//#region src/ai-edits/batch-claims.d.ts
+/**
+ * Which operations of one batch may not share their targets.
+ *
+ * A batch resolves every operation against the document as it was read and
+ * applies them from the end of the document backwards, so an operation never
+ * moves the positions an earlier-placed one resolved to. That holds only while
+ * the operations' targets are disjoint. Two operations on the same stretch of
+ * text, or an operation inside a paragraph another one deletes, rewrites,
+ * splits or merges away, are applied against coordinates the first one has
+ * already invalidated — and the second then edits whatever now sits there,
+ * which can be a paragraph neither operation named.
+ *
+ * Each operation therefore states what it claims before anything is applied,
+ * and the later of two operations whose claims conflict is refused
+ * (`overlappingOperation`). The caller re-reads the document after the batch
+ * and sends the refused operation again against the result. What remains
+ * applies exactly as the same operations applied one at a time, from the end
+ * of the document backwards, would.
+ *
+ * Positions are the ones the batch resolved against. A block is keyed by the
+ * position before its node.
+ */
+type PositionRange = {
+  from: number;
+  to: number;
+};
+/** The text an operation rewrites (`text`), only marks (`annotation`), or breaks (`split`). */
+type InlineClaim = {
+  type: "text" | "annotation" | "split";
+  block: number;
+  from: number;
+  to: number;
+};
+type BatchClaim = InlineClaim |
+/** Every character of the block: `replaceBlock` changing its text. */
+{
+  type: "rewriteBlock";
+  block: number;
+} |
+/** The block's paragraph properties, and nothing of its text. */
+{
+  type: "paragraphProperties";
+  block: number;
+} | {
+  type: "deleteBlock";
+  block: number;
+  /** Where the node ends. */
+  end: number;
+  /**
+   * The paragraph survives, emptied: it ends its container. A block the
+   * batch inserts at `end` lands first (the batch runs backwards), so the
+   * paragraph no longer ends anything when the deletion runs and goes as
+   * any other does — see `followedByInsertion`.
+   */
+  keepsParagraph: boolean;
+  /** The node leaves the document while the batch is still applying. */
+  removesNode: boolean;
+  /** Applied directly rather than tracked. */
+  direct: boolean;
+} |
+/**
+ * Joins `block` with the block starting at `next`, where `block` ends.
+ * Applied directly the two nodes become one while the batch is still
+ * applying (`joinsNow`); tracked, only `block`'s paragraph mark is marked
+ * deleted and both paragraphs stay as they are until the change is accepted.
+ */
+{
+  type: "merge";
+  block: number;
+  next: number;
+  joinsNow: boolean;
+} |
+/** A new block between two others, at `at`. */
+{
+  type: "insertion";
+  at: number;
+} |
+/**
+ * A table, a row or a column's cells, removed. A removed row or column
+ * leaves the table to the other structural operations of the batch; a
+ * removed table leaves nothing to them.
+ */
+{
+  type: "tableRemoval";
+  table: number;
+  wholeTable: boolean;
+  axis: "row" | "column" | "table";
+  ranges: readonly PositionRange[];
+} |
+/** Any other change to a table's grid: rows or columns added, cells merged or split. */
+{
+  type: "tableStructure";
+  table: number;
+  axis: "row" | "column" | "cell";
+} | {
+  type: "unclaimed";
+};
+/**
+ * The claims of the operations a batch has accepted so far, indexed so a
+ * batch of thousands of operations checks each one against its neighbours
+ * rather than against every other operation.
+ */
+declare class BatchClaims {
+  private readonly blocks;
+  private readonly insertions;
+  private readonly joins;
+  private readonly removals;
+  private readonly tables;
+  private readonly rowInsertions;
+  private readonly columnInsertions;
+  /** Accepted deletions that keep their paragraph, by where the paragraph ends. */
+  private readonly keptParagraphs;
+  /** `claim`'s roles, given the insertions accepted so far. */
+  private rolesOf;
+  /**
+   * The operation an insertion at `at` conflicts with through a deletion it
+   * would stop keeping its paragraph: one the deleted paragraph then no
+   * longer allows.
+   */
+  private conflictOfFollowing;
+  /**
+   * The id of an accepted operation `claim` conflicts with, or `null` when it
+   * conflicts with none.
+   */
+  conflictOf(claim: BatchClaim): string | null;
+  add(operationId: string, claim: BatchClaim): void;
+}
+//#endregion
+export { BatchClaim, BatchClaims };

package/dist/ai-edits/batch-claims.js

@@ -0,0 +1,244 @@
+//#region src/ai-edits/batch-claims.ts
+const blockRolesOf = (claim) => {
+	switch (claim.type) {
+		case "text":
+		case "annotation":
+		case "split": return [{
+			block: claim.block,
+			role: {
+				kind: claim.type,
+				claim
+			}
+		}];
+		case "rewriteBlock":
+		case "paragraphProperties": return [{
+			block: claim.block,
+			role: { kind: claim.type }
+		}];
+		case "deleteBlock": return [{
+			block: claim.block,
+			role: {
+				kind: "deleteBlock",
+				keepsParagraph: claim.keepsParagraph,
+				removesNode: claim.removesNode,
+				direct: claim.direct
+			}
+		}];
+		case "merge": return [{
+			block: claim.block,
+			role: {
+				kind: "mergeOwn",
+				joinsNow: claim.joinsNow
+			}
+		}, {
+			block: claim.next,
+			role: {
+				kind: "mergeNext",
+				joinsNow: claim.joinsNow
+			}
+		}];
+		default: return [];
+	}
+};
+/**
+* A deletion of the paragraph that ends its container, once the batch inserts
+* a block after it: the insertion lands first, the paragraph then ends
+* nothing, and it goes as any other — tracked, its mark is deleted into the
+* inserted block and its properties with it; directly, the node goes.
+*/
+const followedByInsertion = (role) => ({
+	...role,
+	keepsParagraph: false,
+	removesNode: role.direct
+});
+const isPoint = ({ from, to }) => from === to;
+/**
+* Two stretches of one block conflict when they overlap, or start at the same
+* position: applied from the end backwards, the one applied second would then
+* find the first one's text where its own range begins. Two insertions at one
+* point are the exception — each writes new text and keeps the other's order.
+*/
+const inlineRangesConflict = (left, right) => left.from < right.to && right.from < left.to || left.from === right.from && !(isPoint(left) && isPoint(right));
+const contains = (outer, inner) => outer.from <= inner.from && inner.to <= outer.to;
+/** Whether two claims on the SAME block conflict; symmetric. */
+/**
+* Which of two roles the rules below are written from: the one ranked
+* higher is put on the left, so each pair is decided in one place.
+*/
+const ROLE_RANK = {
+	deleteBlock: 4,
+	rewriteBlock: 3,
+	mergeOwn: 2,
+	mergeNext: 2,
+	paragraphProperties: 1,
+	split: 0,
+	text: 0,
+	annotation: 0
+};
+const rolesConflict = (left, right) => {
+	if (ROLE_RANK[right.kind] > ROLE_RANK[left.kind]) return rolesConflict(right, left);
+	switch (left.kind) {
+		case "deleteBlock": switch (right.kind) {
+			case "paragraphProperties": return !left.keepsParagraph;
+			case "mergeNext": return left.removesNode;
+			default: return true;
+		}
+		case "rewriteBlock": switch (right.kind) {
+			case "paragraphProperties":
+			case "mergeNext": return false;
+			case "mergeOwn": return right.joinsNow;
+			default: return true;
+		}
+		case "mergeOwn": switch (right.kind) {
+			case "text":
+			case "annotation":
+			case "paragraphProperties":
+			case "mergeNext": return false;
+			default: return true;
+		}
+		case "mergeNext": return right.kind === "paragraphProperties" && left.joinsNow;
+		case "paragraphProperties": return right.kind === "split" || right.kind === "paragraphProperties";
+		case "split":
+		case "text":
+		case "annotation":
+			if (right.kind === "paragraphProperties") return left.kind === "split";
+			if (right.kind !== "split" && right.kind !== "text" && right.kind !== "annotation") return true;
+			if (left.kind === "split" && right.kind === "split") return true;
+			if (left.kind === "annotation" && right.kind === "annotation") return false;
+			if (left.kind === "annotation" && contains(left.claim, right.claim)) return false;
+			if (right.kind === "annotation" && contains(right.claim, left.claim)) return false;
+			return inlineRangesConflict(left.claim, right.claim);
+	}
+};
+const insideAny = (ranges, position) => ranges.some(({ from, to }) => from <= position && position < to);
+const strictlyInsideAny = (ranges, position) => ranges.some(({ from, to }) => from < position && position < to);
+/**
+* The claims of the operations a batch has accepted so far, indexed so a
+* batch of thousands of operations checks each one against its neighbours
+* rather than against every other operation.
+*/
+var BatchClaims = class {
+	blocks = /* @__PURE__ */ new Map();
+	insertions = /* @__PURE__ */ new Map();
+	joins = /* @__PURE__ */ new Map();
+	removals = [];
+	tables = /* @__PURE__ */ new Map();
+	rowInsertions = /* @__PURE__ */ new Map();
+	columnInsertions = /* @__PURE__ */ new Map();
+	/** Accepted deletions that keep their paragraph, by where the paragraph ends. */
+	keptParagraphs = /* @__PURE__ */ new Map();
+	/** `claim`'s roles, given the insertions accepted so far. */
+	rolesOf(claim) {
+		return blockRolesOf(claim).map(({ block, role }) => role.kind === "deleteBlock" && role.keepsParagraph && claim.type === "deleteBlock" && this.insertions.has(claim.end) ? {
+			block,
+			role: followedByInsertion(role)
+		} : {
+			block,
+			role
+		});
+	}
+	/**
+	* The operation an insertion at `at` conflicts with through a deletion it
+	* would stop keeping its paragraph: one the deleted paragraph then no
+	* longer allows.
+	*/
+	conflictOfFollowing(at) {
+		const kept = this.keptParagraphs.get(at);
+		if (kept === void 0) return null;
+		const entries = this.blocks.get(kept.block) ?? [];
+		const deletion = entries.find(({ operationId }) => operationId === kept.operationId);
+		if (deletion?.role.kind !== "deleteBlock") return null;
+		const followed = followedByInsertion(deletion.role);
+		return entries.find(({ operationId, role }) => operationId !== kept.operationId && rolesConflict(followed, role))?.operationId ?? null;
+	}
+	/**
+	* The id of an accepted operation `claim` conflicts with, or `null` when it
+	* conflicts with none.
+	*/
+	conflictOf(claim) {
+		for (const { block, role } of this.rolesOf(claim)) {
+			for (const entry of this.blocks.get(block) ?? []) if (rolesConflict(entry.role, role)) return entry.operationId;
+			if (role.kind === "deleteBlock") continue;
+			for (const removal of this.removals) if (insideAny(removal.claim.ranges, block)) return removal.operationId;
+		}
+		switch (claim.type) {
+			case "merge": return this.insertions.get(claim.next) ?? null;
+			case "insertion": {
+				const join = this.joins.get(claim.at);
+				if (join !== void 0) return join;
+				const following = this.conflictOfFollowing(claim.at);
+				if (following !== null) return following;
+				return this.removals.find(({ claim: removed }) => strictlyInsideAny(removed.ranges, claim.at))?.operationId ?? null;
+			}
+			case "tableStructure": return this.removals.find(({ claim: removed }) => insideAny(removed.ranges, claim.table) || removed.table === claim.table && removed.axis !== claim.axis && (removed.axis === "row" || removed.axis === "column"))?.operationId ?? this.removals.find(({ claim: removed }) => removed.wholeTable && removed.table === claim.table)?.operationId ?? null;
+			case "tableRemoval":
+				if (claim.axis === "row") {
+					const columnInsertion = this.columnInsertions.get(claim.table);
+					if (columnInsertion !== void 0) return columnInsertion;
+				}
+				if (claim.axis === "column") {
+					const rowInsertion = this.rowInsertions.get(claim.table);
+					if (rowInsertion !== void 0) return rowInsertion;
+				}
+				if (claim.wholeTable) {
+					const structural = this.tables.get(claim.table);
+					if (structural !== void 0) return structural;
+				}
+				for (const removal of this.removals) if (insideAny(removal.claim.ranges, claim.table) || insideAny(claim.ranges, removal.claim.table) || removal.claim.table === claim.table && (removal.claim.wholeTable || claim.wholeTable || removal.claim.axis !== claim.axis)) return removal.operationId;
+				for (const [table, operationId] of this.tables) if (strictlyInsideAny(claim.ranges, table)) return operationId;
+				for (const [block, entries] of this.blocks) {
+					const editor = entries.find(({ role }) => role.kind !== "deleteBlock");
+					if (editor !== void 0 && insideAny(claim.ranges, block)) return editor.operationId;
+				}
+				for (const [at, operationId] of this.insertions) if (strictlyInsideAny(claim.ranges, at)) return operationId;
+				return null;
+			default: return null;
+		}
+	}
+	add(operationId, claim) {
+		for (const { block, role } of this.rolesOf(claim)) {
+			const entries = this.blocks.get(block);
+			if (entries) entries.push({
+				operationId,
+				role
+			});
+			else this.blocks.set(block, [{
+				operationId,
+				role
+			}]);
+			if (claim.type === "deleteBlock" && role.kind === "deleteBlock" && role.keepsParagraph) this.keptParagraphs.set(claim.end, {
+				block,
+				operationId
+			});
+		}
+		switch (claim.type) {
+			case "merge":
+				this.joins.set(claim.next, operationId);
+				break;
+			case "insertion": {
+				if (!this.insertions.has(claim.at)) this.insertions.set(claim.at, operationId);
+				const kept = this.keptParagraphs.get(claim.at);
+				if (kept !== void 0) {
+					this.keptParagraphs.delete(claim.at);
+					for (const entry of this.blocks.get(kept.block) ?? []) if (entry.operationId === kept.operationId && entry.role.kind === "deleteBlock") entry.role = followedByInsertion(entry.role);
+				}
+				break;
+			}
+			case "tableStructure":
+				if (!this.tables.has(claim.table)) this.tables.set(claim.table, operationId);
+				if (claim.axis === "row" && !this.rowInsertions.has(claim.table)) this.rowInsertions.set(claim.table, operationId);
+				if (claim.axis === "column" && !this.columnInsertions.has(claim.table)) this.columnInsertions.set(claim.table, operationId);
+				break;
+			case "tableRemoval":
+				this.removals.push({
+					operationId,
+					claim
+				});
+				if (!this.tables.has(claim.table)) this.tables.set(claim.table, operationId);
+				break;
+			default: break;
+		}
+	}
+};
+//#endregion
+export { BatchClaims };

package/dist/ai-edits/blockRange.js

@@ -1,7 +1,7 @@
 import { findParagraphByParaId } from "../prosemirror/utils/findParagraphByParaId.js";
 import { getFolioParaIdFromBlockId, getSequentialFolioBlockIdIndex } from "../types/block-id.js";
 import { buildCleanBlockText, resolveCleanTextRange } from "./clean-text.js";
-import { createFolioAIEditSnapshot, hashFolioAIBlockText, isFolioAIContentBlock } from "./snapshot.js";
+import { collectNoteReferenceLabels, createFolioAIEditSnapshot, hashFolioAIBlockText, isFolioAIContentBlock } from "./snapshot.js";
 //#region src/ai-edits/blockRange.ts
 const resolveFolioAIBlockRange = ({ blockId, doc, snapshot }) => {
 	const paraId = getFolioParaIdFromBlockId(blockId);
@@ -27,7 +27,10 @@ const resolveFolioAITextRange = ({ range, doc, snapshot }) => {
 	if (blockRange === null) return null;
 	const blockNode = doc.nodeAt(blockRange.from);
 	if (!blockNode?.isTextblock) return null;
-	const cleanBlock = buildCleanBlockText(blockNode, blockRange.from);
+	const cleanBlock = buildCleanBlockText(blockNode, blockRange.from, {
+		fieldResults: "text",
+		noteReferences: collectNoteReferenceLabels(doc)
+	});
 	const resolved = resolveCleanTextRange({
 		cleanBlock,
 		startOffset: range.startOffset,
@@ -63,7 +66,10 @@ const resolvePassageRange = ({ blockId, text, doc, snapshot }) => {
 	if (!blockNode?.isTextblock) return null;
 	const needleSource = buildPassageNeedleSource(text);
 	if (needleSource === null) return null;
-	const cleanBlock = buildCleanBlockText(blockNode, blockRange.from);
+	const cleanBlock = buildCleanBlockText(blockNode, blockRange.from, {
+		fieldResults: "text",
+		noteReferences: collectNoteReferenceLabels(doc)
+	});
 	const match = matchPassage(cleanBlock.text, needleSource);
 	if (match === null) return null;
 	const resolved = resolveCleanTextRange({

package/dist/ai-edits/character-boundaries.d.ts

@@ -0,0 +1,43 @@
+//#region src/ai-edits/character-boundaries.d.ts
+/**
+ * Where an offset into a block's clean text may fall.
+ *
+ * Offsets count UTF-16 code units, as JavaScript strings do. One character a
+ * reader sees can span several: a character outside the Basic Multilingual
+ * Plane is two (a surrogate pair), and a grapheme cluster — a letter and its
+ * combining marks, an emoji joined with zero-width joiners, a flag's two
+ * regional indicators — is several code points. An editing caret stands
+ * only between two clusters.
+ *
+ * An offset between the two halves of a surrogate pair names no character at
+ * all, and text cut there cannot be written: each half becomes a lone
+ * surrogate, which XML cannot hold, so the save drops both and the character
+ * disappears. Every offset an operation takes is refused there.
+ *
+ * An offset inside a grapheme cluster names a code point, and marks may start
+ * there — a document can itself format a combining mark apart from its base,
+ * and a comparison reproducing that formatting needs the same boundary — but
+ * text written or broken there changes a character nobody named: the accent
+ * of `é` moves onto the replacement, a family emoji falls apart into people.
+ * Operations that change text or break a paragraph are refused there as well.
+ */
+/** Whether `offset` falls between the two halves of one surrogate pair of `text`. */
+declare const splitsSurrogatePair: (text: string, offset: number) => boolean;
+/**
+ * Whether `offset` falls inside one grapheme cluster of `text`, or between
+ * the halves of a surrogate pair. Without `Intl.Segmenter` only the surrogate
+ * pair is recognised.
+ */
+declare const splitsGraphemeCluster: (text: string, offset: number) => boolean;
+type CharacterBoundaryStrictness =
+/** Refuse only an offset inside a surrogate pair: annotations. */
+"codePoint" |
+/** Refuse any offset inside a grapheme cluster: edits of text and breaks. */
+"grapheme";
+/**
+ * Why `offsets` do not all stand on a character boundary of `text`, naming
+ * the first that does not and the character it cuts; `null` when they all do.
+ */
+declare const describeCharacterSplit: (text: string, offsets: readonly number[], strictness: CharacterBoundaryStrictness) => string | null;
+//#endregion
+export { CharacterBoundaryStrictness, describeCharacterSplit, splitsGraphemeCluster, splitsSurrogatePair };

package/dist/ai-edits/character-boundaries.js

@@ -0,0 +1,95 @@
+//#region src/ai-edits/character-boundaries.ts
+/**
+* Where an offset into a block's clean text may fall.
+*
+* Offsets count UTF-16 code units, as JavaScript strings do. One character a
+* reader sees can span several: a character outside the Basic Multilingual
+* Plane is two (a surrogate pair), and a grapheme cluster — a letter and its
+* combining marks, an emoji joined with zero-width joiners, a flag's two
+* regional indicators — is several code points. An editing caret stands
+* only between two clusters.
+*
+* An offset between the two halves of a surrogate pair names no character at
+* all, and text cut there cannot be written: each half becomes a lone
+* surrogate, which XML cannot hold, so the save drops both and the character
+* disappears. Every offset an operation takes is refused there.
+*
+* An offset inside a grapheme cluster names a code point, and marks may start
+* there — a document can itself format a combining mark apart from its base,
+* and a comparison reproducing that formatting needs the same boundary — but
+* text written or broken there changes a character nobody named: the accent
+* of `é` moves onto the replacement, a family emoji falls apart into people.
+* Operations that change text or break a paragraph are refused there as well.
+*/
+const isHighSurrogate = (code) => code >= 55296 && code <= 56319;
+const isLowSurrogate = (code) => code >= 56320 && code <= 57343;
+/** Whether `offset` falls between the two halves of one surrogate pair of `text`. */
+const splitsSurrogatePair = (text, offset) => offset > 0 && offset < text.length && isHighSurrogate(text.charCodeAt(offset - 1)) && isLowSurrogate(text.charCodeAt(offset));
+let graphemeSegmenter;
+const getGraphemeSegmenter = () => {
+	if (graphemeSegmenter === void 0) graphemeSegmenter = typeof Intl === "object" && typeof Intl.Segmenter === "function" ? new Intl.Segmenter(void 0, { granularity: "grapheme" }) : null;
+	return graphemeSegmenter;
+};
+const MAX_CACHED_TEXTS = 16;
+const graphemeStartsByText = /* @__PURE__ */ new Map();
+/**
+* The offsets at which a grapheme cluster of `text` starts. A batch asks about
+* the same block for each of its operations, so the last few answers are kept.
+*/
+const graphemeStarts = (text, segmenter) => {
+	const cached = graphemeStartsByText.get(text);
+	if (cached !== void 0) return cached;
+	const starts = /* @__PURE__ */ new Set();
+	for (const { index } of segmenter.segment(text)) starts.add(index);
+	if (graphemeStartsByText.size >= MAX_CACHED_TEXTS) {
+		const oldest = graphemeStartsByText.keys().next();
+		if (oldest.done !== true) graphemeStartsByText.delete(oldest.value);
+	}
+	graphemeStartsByText.set(text, starts);
+	return starts;
+};
+/**
+* Whether `offset` falls inside one grapheme cluster of `text`, or between
+* the halves of a surrogate pair. Without `Intl.Segmenter` only the surrogate
+* pair is recognised.
+*/
+const splitsGraphemeCluster = (text, offset) => {
+	if (offset <= 0 || offset >= text.length) return false;
+	if (splitsSurrogatePair(text, offset)) return true;
+	const segmenter = getGraphemeSegmenter();
+	return segmenter !== null && !graphemeStarts(text, segmenter).has(offset);
+};
+const splitsCharacter = (text, offset, strictness) => strictness === "grapheme" ? splitsGraphemeCluster(text, offset) : splitsSurrogatePair(text, offset);
+/**
+* The character a split `offset` falls inside, as the offsets of its ends: the
+* whole grapheme cluster, or — without `Intl.Segmenter`, which leaves only a
+* surrogate pair recognisable — the pair.
+*/
+const enclosingCharacter = (text, offset) => {
+	const segmenter = getGraphemeSegmenter();
+	if (segmenter === null) return {
+		start: offset - 1,
+		end: offset + 1
+	};
+	const starts = graphemeStarts(text, segmenter);
+	let start = offset;
+	while (start > 0 && !starts.has(start)) start--;
+	let end = offset;
+	while (end < text.length && !starts.has(end)) end++;
+	return {
+		start,
+		end
+	};
+};
+/**
+* Why `offsets` do not all stand on a character boundary of `text`, naming
+* the first that does not and the character it cuts; `null` when they all do.
+*/
+const describeCharacterSplit = (text, offsets, strictness) => {
+	const offset = offsets.find((candidate) => splitsCharacter(text, candidate, strictness));
+	if (offset === void 0) return null;
+	const { start, end } = enclosingCharacter(text, offset);
+	return `offset ${String(offset)} falls inside ${JSON.stringify(text.slice(start, end))}, which spans offsets ${String(start)} to ${String(end)}; use ${String(start)} or ${String(end)}.`;
+};
+//#endregion
+export { describeCharacterSplit, splitsGraphemeCluster, splitsSurrogatePair };

package/dist/ai-edits/clean-text.d.ts

@@ -1,4 +1,6 @@
 import { PageBreakRunAttrs } from "../prosemirror/schema/nodes.js";
+import { NoteReferenceKind } from "../utils/noteReferenceLabels.js";
+import { NoteReferenceLabels } from "./note-references.js";
 import { Node } from "prosemirror-model";
 //#region src/ai-edits/clean-text.d.ts
 /**
@@ -56,6 +58,20 @@ type CleanTextStructuralBoundary = {
   length: number;
   from: number;
   to: number;
+} | {
+  /**
+   * A footnote or endnote reference, read as its marker (`[^1]`). The
+   * marker is not text: a range may start or end at its edges but never
+   * inside it, and no text change may rewrite or remove it.
+   */
+  type: "noteReference";
+  offset: number;
+  /** Characters the marker contributes. */
+  length: number;
+  from: number;
+  to: number;
+  noteType: NoteReferenceKind;
+  noteId: string;
 };
 type ResolveCleanTextRangeOptions = {
   cleanBlock: CleanBlockText;
@@ -82,8 +98,16 @@ type BuildCleanBlockTextOptions = {
    * offsets that locate it.
    */
   fieldResults: "text" | "omitted";
+  /**
+   * How a footnote/endnote reference reads. Labels numbered over the whole
+   * story (`collectNoteReferenceLabels`) give the marker every other reader
+   * shows; without them a block numbers its own references. `"sourceText"` is
+   * the editor's own text for the reference, which only a comparison of two
+   * documents' editor text wants.
+   */
+  noteReferences?: NoteReferenceLabels | "sourceText";
 };
-declare const buildCleanBlockText: (blockNode: Node, blockFrom: number, { fieldResults }?: BuildCleanBlockTextOptions) => CleanBlockText;
+declare const buildCleanBlockText: (blockNode: Node, blockFrom: number, { fieldResults, noteReferences }?: BuildCleanBlockTextOptions) => CleanBlockText;
 /**
  * A "redline-aware" view of a textblock: the same left-to-right traversal as
  * {@link buildCleanBlockText}, but every tracked change and comment anchor is
@@ -101,8 +125,14 @@ declare const buildCleanBlockText: (blockNode: Node, blockFrom: number, { fieldR
  *
  * This is the view a consumer embeds when it wants the model to reason about
  * the redline itself, in contrast to {@link buildCleanBlockText}'s
- * post-tracked-changes view.
+ * post-tracked-changes view. A footnote or endnote reference reads as its
+ * marker (`[^1]`), numbered within the block.
  */
 declare const buildAnnotatedBlockText: (blockNode: Node) => string;
+/**
+ * {@link buildAnnotatedBlockText} with a story's reference numbering, so a
+ * reference reads as the marker every other reader of the story shows.
+ */
+declare const buildAnnotatedBlockTextWithNoteReferences: (blockNode: Node, noteReferences: NoteReferenceLabels | undefined) => string;
 //#endregion
-export { BuildCleanBlockTextOptions, CleanBlockText, CleanTextStructuralBoundary, buildAnnotatedBlockText, buildCleanBlockText, resolveCleanTextRange };
+export { BuildCleanBlockTextOptions, CleanBlockText, CleanTextStructuralBoundary, buildAnnotatedBlockText, buildAnnotatedBlockTextWithNoteReferences, buildCleanBlockText, resolveCleanTextRange };