@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

package/dist/ai-edits/apply.js

@@ -0,0 +1,683 @@
+import { getFolioParaIdFromBlockId } from "../types/block-id.js";
+import { buildCleanBlockText } from "./clean-text.js";
+import { hasInlineEmphasis, parseInlineEmphasisRuns, stripInlineEmphasisMarkers } from "./inline-emphasis.js";
+import { hashFolioAIBlockText, normalizeFolioAIBlockText } from "./snapshot.js";
+import { diffWordSegments } from "./word-diff.js";
+//#region src/ai-edits/apply.ts
+/**
+* Block attrs that identify a block instance (Word's
+* `w14:paraId` / `w14:textId`, future tracked-change identifiers).
+* Reuse during inheritFormatting would create duplicate IDs, so
+* we strip them when synthesising a sibling.
+*/
+const IDENTITY_BLOCK_ATTRS = /* @__PURE__ */ new Set(["paraId", "textId"]);
+const stripIdentityAttrs = (attrs) => {
+	const next = {};
+	for (const [key, value] of Object.entries(attrs)) {
+		if (IDENTITY_BLOCK_ATTRS.has(key)) {
+			next[key] = null;
+			continue;
+		}
+		next[key] = value;
+	}
+	return next;
+};
+const applyReplaceBlockStyleId = ({ item, tr }) => {
+	if (item.operation.type !== "replaceBlock" || item.operation.styleId === void 0) return tr;
+	const block = tr.doc.nodeAt(item.blockFrom);
+	if (!block) return tr;
+	return tr.setNodeMarkup(item.blockFrom, void 0, {
+		...block.attrs,
+		styleId: item.operation.styleId
+	});
+};
+/**
+* Module-scoped monotonic counter for tracked-change revision ids.
+* Seeded once from `Date.now()` so ids are roughly time-ordered for
+* humans reading raw DOCX, then incremented per allocation. A bare
+* `Date.now()` seed per applyAIEditOperations call would collide
+* across batches that fire within the same millisecond (the panel's
+* Accept-all loop does exactly that — multiple calls in tight
+* succession). Reserving a contiguous range up front guarantees
+* uniqueness across overlapping calls in the same JS realm.
+*/
+let revisionIdCursor = Date.now() * 1e3;
+const nextRevisionSeed = (count) => {
+	const start = revisionIdCursor;
+	revisionIdCursor += Math.max(count, 1) * 4;
+	return start;
+};
+/**
+* Walk the live doc once and bucket every textblock by its
+* normalised text hash. Resolution then maps each snapshot anchor
+* to the live block at the same ordinal among same-hash siblings —
+* unrelated edits that shift absolute positions no longer break
+* the lookup, and a sibling sharing text content with the target
+* doesn't trigger a false "changed" skip either.
+*/
+const collectLiveBlocksByHash = (doc) => {
+	const byHash = /* @__PURE__ */ new Map();
+	doc.descendants((node, pos) => {
+		if (!node.isTextblock) return;
+		const cleanText = buildCleanBlockText(node, pos).text;
+		const hash = hashFolioAIBlockText(normalizeFolioAIBlockText(cleanText));
+		const bucket = byHash.get(hash) ?? [];
+		bucket.push({
+			from: pos,
+			to: pos + node.nodeSize,
+			node
+		});
+		byHash.set(hash, bucket);
+	});
+	return byHash;
+};
+/**
+* Index live textblocks by their `w14:paraId`. Used by the resolver
+* to prefer a paraId-anchored lookup when the snapshot id encodes
+* one. Direct lookup avoids
+* the hash+ordinal failure mode where an earlier-in-document
+* duplicate of the same text gets picked instead of the actual
+* referenced paragraph.
+*/
+const collectLiveBlocksByParaId = (doc) => {
+	const byParaId = /* @__PURE__ */ new Map();
+	doc.descendants((node, pos) => {
+		if (!node.isTextblock) return;
+		const paraId = node.attrs["paraId"];
+		if (typeof paraId !== "string" || paraId.length === 0) return;
+		if (!byParaId.has(paraId)) byParaId.set(paraId, {
+			from: pos,
+			to: pos + node.nodeSize,
+			node
+		});
+	});
+	return byParaId;
+};
+const findEnclosingTableBoundary = (doc, blockFrom) => {
+	const resolved = doc.resolve(blockFrom);
+	for (let depth = resolved.depth; depth > 0; depth--) if (resolved.node(depth).type.name === "table") return {
+		before: resolved.before(depth),
+		after: resolved.after(depth)
+	};
+	return null;
+};
+/**
+* The snapshot recorded an `hashOccurrenceCount` per anchor but
+* not which ordinal within that bucket the block was — recompute
+* on demand from the snapshot's anchor map. Stable iteration
+* (object insertion order) means anchors with the same hash come
+* out in document order, which is what we want.
+*/
+const ordinalAmongSameHash = (snapshot, blockId) => {
+	const target = snapshot.anchors[blockId];
+	if (!target) return -1;
+	let ordinal = 0;
+	for (const anchor of Object.values(snapshot.anchors)) {
+		if (anchor.id === blockId) return ordinal;
+		if (anchor.textHash === target.textHash) ordinal += 1;
+	}
+	return -1;
+};
+/**
+* Length of the underscore signature rule. Mirrors the constant
+* in `docx-core/legal-source/compile.ts` so the on-screen signature
+* line matches what `create-document` produces.
+*/
+const SIGNATURE_LINE = "_".repeat(28);
+/**
+* Build a borderless PM table mirroring docx-core's
+* `signatureTable` helper: one row, one cell per party, each cell
+* containing party name (bold), two spacer paragraphs, a signature
+* rule, then optional signatory and italic title lines.
+*
+* Returns `null` when the editor schema is missing one of the
+* required node types — callers should surface the op as a skip
+* rather than crashing.
+*/
+const buildSignatureTableNode = ({ schema, parties }) => {
+	const paragraphType = schema.nodes["paragraph"];
+	const cellType = schema.nodes["tableCell"];
+	const rowType = schema.nodes["tableRow"];
+	const tableType = schema.nodes["table"];
+	if (!paragraphType || !cellType || !rowType || !tableType) return null;
+	const boldType = schema.marks["bold"];
+	const italicType = schema.marks["italic"];
+	const buildParagraph = (text, options) => {
+		const marks = [];
+		if (options.bold && boldType) marks.push(boldType.create());
+		if (options.italic && italicType) marks.push(italicType.create());
+		const content = text.length > 0 ? schema.text(text, marks) : null;
+		return paragraphType.create({ styleId: options.styleId }, content);
+	};
+	const buildCell = (party) => {
+		const cellContent = [
+			buildParagraph(party.name, {
+				styleId: "SignatureParty",
+				bold: true
+			}),
+			buildParagraph("", { styleId: "SignatureSpacer" }),
+			buildParagraph("", { styleId: "SignatureSpacer" }),
+			buildParagraph(SIGNATURE_LINE, { styleId: "SignatureRule" })
+		];
+		if (party.signatory && party.signatory.length > 0) cellContent.push(buildParagraph(party.signatory, { styleId: "SignatureField" }));
+		if (party.title && party.title.length > 0) cellContent.push(buildParagraph(party.title, {
+			styleId: "SignatureField",
+			italic: true
+		}));
+		return cellType.create({}, cellContent);
+	};
+	const cells = parties.map(buildCell);
+	const row = rowType.create({}, cells);
+	return tableType.create({}, row);
+};
+/**
+* Build the inline content for an inserted or replaced block, promoting the
+* model's `**bold**` / `***bold italic***` markdown into real Word marks (the
+* edit-tool schema has no inline-format channel, so the model improvises with
+* markdown that would otherwise land as literal asterisks). Falls back to a
+* single verbatim text node when no emphasis is present, so plain prose is
+* never reshaped. `baseMarks` (insertion / comment) ride on every run.
+*/
+const buildEmphasisInlineContent = (schema, text, baseMarks) => {
+	const runs = parseInlineEmphasisRuns(text);
+	if (!runs.some((run) => run.bold || run.italic)) return [schema.text(text, [...baseMarks])];
+	const boldType = schema.marks["bold"];
+	const italicType = schema.marks["italic"];
+	const nodes = [];
+	for (const run of runs) {
+		if (run.text.length === 0) continue;
+		const marks = [...baseMarks];
+		if (run.bold && boldType) marks.push(boldType.create());
+		if (run.italic && italicType) marks.push(italicType.create());
+		nodes.push(schema.text(run.text, marks));
+	}
+	return nodes.length > 0 ? nodes : [schema.text(text, [...baseMarks])];
+};
+const applyFolioAIEditOperations = ({ view, snapshot, operations, mode = "tracked-changes", author = "AI", createCommentId }) => {
+	const applied = [];
+	const skipped = [];
+	const resolved = [];
+	const insertionType = view.state.schema.marks["insertion"];
+	const deletionType = view.state.schema.marks["deletion"];
+	const commentType = view.state.schema.marks["comment"];
+	if (mode === "tracked-changes" && (!insertionType || !deletionType)) return {
+		applied,
+		skipped: operations.map((operation) => ({
+			id: operation.id,
+			reason: "unsupportedBlock"
+		}))
+	};
+	const liveBlocks = collectLiveBlocksByHash(view.state.doc);
+	const liveBlocksByParaId = collectLiveBlocksByParaId(view.state.doc);
+	for (const [index, operation] of operations.entries()) {
+		const commentText = getOperationCommentText(operation);
+		if (commentText !== void 0 && (!commentType || createCommentId === void 0)) {
+			skipped.push({
+				id: operation.id,
+				reason: "unsupportedBlock"
+			});
+			continue;
+		}
+		const resolution = resolveOperation({
+			snapshot,
+			operation,
+			liveBlocks,
+			liveBlocksByParaId,
+			doc: view.state.doc
+		});
+		if (resolution.type === "skip") {
+			skipped.push({
+				id: operation.id,
+				reason: resolution.reason
+			});
+			continue;
+		}
+		const commentId = commentText !== void 0 ? createCommentId?.(commentText) : void 0;
+		resolved.push({
+			...resolution.operation,
+			originalIndex: index,
+			...commentId !== void 0 && { commentId }
+		});
+	}
+	if (resolved.length === 0) return {
+		applied,
+		skipped
+	};
+	let tr = view.state.tr;
+	let revisionSeed = nextRevisionSeed(resolved.length);
+	const date = (/* @__PURE__ */ new Date()).toISOString();
+	for (const item of resolved.toSorted((left, right) => {
+		if (left.from !== right.from) return right.from - left.from;
+		return right.originalIndex - left.originalIndex;
+	})) {
+		const commentMark = item.commentId !== void 0 && commentType ? commentType.create({ commentId: item.commentId }) : null;
+		const stepsBefore = tr.steps.length;
+		let appliedRevisionIds;
+		switch (item.operation.type) {
+			case "replaceInBlock": {
+				const revisionIdDelete = revisionSeed++;
+				const revisionIdInsert = revisionSeed++;
+				tr = applyTextReplacement({
+					tr,
+					item,
+					mode,
+					author,
+					date,
+					revisionIdDelete,
+					revisionIdInsert,
+					commentMark
+				});
+				if (mode === "tracked-changes") appliedRevisionIds = [revisionIdDelete, revisionIdInsert];
+				break;
+			}
+			case "replaceBlock": {
+				const revisionIdDelete = revisionSeed++;
+				const revisionIdInsert = revisionSeed++;
+				if (item.operation.preserveFormatting === false && mode === "direct") {
+					const replacement = item.operation.text;
+					const paragraphType = view.state.schema.nodes["paragraph"];
+					if (paragraphType) {
+						const replaceAttrs = item.operation.styleId !== void 0 ? { styleId: item.operation.styleId } : null;
+						const node = paragraphType.create(replaceAttrs, replacement.length === 0 ? null : buildEmphasisInlineContent(view.state.schema, replacement, []));
+						tr = tr.replaceWith(item.blockFrom, item.blockTo, node);
+						break;
+					}
+				}
+				if (mode === "direct" && hasInlineEmphasis(item.operation.text)) {
+					const attrs = item.operation.styleId !== void 0 ? {
+						...item.blockNode.attrs,
+						styleId: item.operation.styleId
+					} : { ...item.blockNode.attrs };
+					const node = item.blockNode.type.create(attrs, buildEmphasisInlineContent(view.state.schema, item.operation.text, commentMark ? [commentMark] : []));
+					tr = tr.replaceWith(item.blockFrom, item.blockTo, node);
+					break;
+				}
+				tr = applyTextReplacement({
+					tr,
+					item,
+					mode,
+					author,
+					date,
+					revisionIdDelete,
+					revisionIdInsert,
+					commentMark
+				});
+				tr = applyReplaceBlockStyleId({
+					item,
+					tr
+				});
+				if (mode === "tracked-changes") appliedRevisionIds = [revisionIdDelete, revisionIdInsert];
+				break;
+			}
+			case "insertAfterBlock":
+			case "insertBeforeBlock": {
+				if (mode === "tracked-changes" && item.operation.pageBreakBefore === true && (!item.insertText || item.insertText.length === 0)) {
+					skipped.push({
+						id: item.operation.id,
+						reason: "unsupportedBlock"
+					});
+					continue;
+				}
+				const marks = [];
+				if (mode === "tracked-changes" && insertionType) {
+					const revisionId = revisionSeed++;
+					marks.push(insertionType.create({
+						revisionId,
+						author,
+						date
+					}));
+					appliedRevisionIds = [revisionId];
+				}
+				if (commentMark) marks.push(commentMark);
+				const content = item.insertText && item.insertText.length > 0 ? buildEmphasisInlineContent(view.state.schema, item.insertText, marks) : null;
+				const attrs = { ...item.operation.inheritFormatting === false ? {} : stripIdentityAttrs(item.blockNode.attrs) };
+				if (item.operation.pageBreakBefore === true) attrs["pageBreakBefore"] = true;
+				if (item.operation.styleId !== void 0) {
+					attrs["styleId"] = item.operation.styleId;
+					if (item.operation.inheritFormatting !== false) {
+						attrs["listMarker"] = null;
+						attrs["listMarkerHidden"] = null;
+						attrs["listLevelNumFmts"] = null;
+						attrs["listAbstractNumId"] = null;
+						attrs["listStartOverride"] = null;
+					}
+				}
+				const node = item.blockNode.type.create(attrs, content);
+				tr = tr.insert(item.from, node);
+				break;
+			}
+			case "insertSignatureTable": {
+				if (mode === "tracked-changes") {
+					skipped.push({
+						id: item.operation.id,
+						reason: "unsupportedBlock"
+					});
+					continue;
+				}
+				const node = buildSignatureTableNode({
+					schema: view.state.schema,
+					parties: item.operation.parties
+				});
+				if (!node) {
+					skipped.push({
+						id: item.operation.id,
+						reason: "unsupportedBlock"
+					});
+					continue;
+				}
+				tr = tr.insert(item.from, node);
+				break;
+			}
+			case "deleteBlock":
+				if (mode === "direct") {
+					tr = tr.delete(item.blockFrom, item.blockTo);
+					break;
+				}
+				if (deletionType) {
+					const revisionId = revisionSeed++;
+					tr = tr.addMark(item.from, item.to, deletionType.create({
+						revisionId,
+						author,
+						date
+					}));
+					appliedRevisionIds = [revisionId];
+				}
+				if (commentMark) tr = tr.addMark(item.from, item.to, commentMark);
+				break;
+			case "commentOnBlock":
+				if (commentMark) tr = tr.addMark(item.from, item.to, commentMark);
+				break;
+			default: break;
+		}
+		if (tr.steps.length === stepsBefore) {
+			skipped.push({
+				id: item.operation.id,
+				reason: "noopOperation"
+			});
+			continue;
+		}
+		applied.push({
+			id: item.operation.id,
+			...item.commentId !== void 0 && { commentId: item.commentId },
+			...appliedRevisionIds !== void 0 && appliedRevisionIds[0] !== void 0 && {
+				revisionId: appliedRevisionIds[0],
+				revisionIds: appliedRevisionIds
+			}
+		});
+	}
+	if (tr.docChanged) view.dispatch(tr);
+	return {
+		applied,
+		skipped
+	};
+};
+const applyTextReplacement = ({ tr, item, mode, author, date, revisionIdDelete, revisionIdInsert, commentMark }) => {
+	let nextTr = tr;
+	const replacement = stripInlineEmphasisMarkers((() => {
+		if (item.operation.type === "replaceInBlock") return item.operation.replace;
+		if (item.operation.type === "replaceBlock") return item.operation.text;
+		return "";
+	})());
+	if (mode === "direct") {
+		if (item.operation.type === "replaceInBlock" && hasInlineEmphasis(item.operation.replace)) {
+			const content = buildEmphasisInlineContent(nextTr.doc.type.schema, item.operation.replace, commentMark ? [commentMark] : []);
+			return nextTr.replaceWith(item.from, item.to, content);
+		}
+		nextTr = nextTr.insertText(replacement, item.from, item.to);
+		if (commentMark && replacement.length > 0) nextTr = nextTr.addMark(item.from, item.from + replacement.length, commentMark);
+		return nextTr;
+	}
+	const insertionType = nextTr.doc.type.schema.marks["insertion"];
+	const deletionType = nextTr.doc.type.schema.marks["deletion"];
+	const delAttrs = {
+		revisionId: revisionIdDelete,
+		author,
+		date
+	};
+	const insAttrs = {
+		revisionId: revisionIdInsert,
+		author,
+		date
+	};
+	const cleanBlock = item.blockNode.content.size === item.blockNode.textContent.length ? buildCleanBlockText(item.blockNode, item.blockFrom) : null;
+	let sourceText = null;
+	let sourceCleanStart = 0;
+	if (cleanBlock !== null) {
+		if (item.operation.type === "replaceInBlock") {
+			sourceText = item.operation.find;
+			sourceCleanStart = cleanBlock.text.indexOf(item.operation.find);
+			if (sourceCleanStart === -1) sourceText = null;
+		} else if (item.operation.type === "replaceBlock") {
+			sourceText = cleanBlock.text;
+			sourceCleanStart = 0;
+		}
+	}
+	if (sourceText !== null && cleanBlock !== null) {
+		const segments = diffWordSegments(sourceText, replacement);
+		const offsets = cleanBlock.offsets;
+		const offsetAt = (cleanOffset) => offsets[cleanOffset] ?? null;
+		const steps = [];
+		let cursor = 0;
+		let allPositionsResolved = true;
+		for (const seg of segments) {
+			if (seg.type === "equal") {
+				cursor += seg.text.length;
+				continue;
+			}
+			if (seg.type === "del") {
+				const pmFrom = offsetAt(sourceCleanStart + cursor);
+				const pmTo = offsetAt(sourceCleanStart + cursor + seg.text.length);
+				if (pmFrom === null || pmTo === null) {
+					allPositionsResolved = false;
+					break;
+				}
+				steps.push({
+					kind: "del",
+					from: pmFrom,
+					to: pmTo
+				});
+				cursor += seg.text.length;
+				continue;
+			}
+			const pmAt = offsetAt(sourceCleanStart + cursor);
+			if (pmAt === null) {
+				allPositionsResolved = false;
+				break;
+			}
+			steps.push({
+				kind: "ins",
+				at: pmAt,
+				text: seg.text
+			});
+		}
+		if (allPositionsResolved) {
+			for (const step of steps.toReversed()) {
+				if (step.kind === "del" && deletionType) {
+					nextTr = nextTr.addMark(step.from, step.to, deletionType.create(delAttrs));
+					if (commentMark) nextTr = nextTr.addMark(step.from, step.to, commentMark);
+					continue;
+				}
+				if (step.kind === "ins" && insertionType) {
+					nextTr = nextTr.insertText(step.text, step.at, step.at);
+					nextTr = nextTr.addMark(step.at, step.at + step.text.length, insertionType.create(insAttrs));
+					if (commentMark) nextTr = nextTr.addMark(step.at, step.at + step.text.length, commentMark);
+				}
+			}
+			return nextTr;
+		}
+	}
+	if (replacement.length > 0 && insertionType) {
+		nextTr = nextTr.insertText(replacement, item.to, item.to);
+		nextTr = nextTr.addMark(item.to, item.to + replacement.length, insertionType.create(insAttrs));
+		if (commentMark) nextTr = nextTr.addMark(item.to, item.to + replacement.length, commentMark);
+	}
+	if (item.to > item.from && deletionType) {
+		nextTr = nextTr.addMark(item.from, item.to, deletionType.create(delAttrs));
+		if (commentMark && replacement.length === 0) nextTr = nextTr.addMark(item.from, item.to, commentMark);
+	}
+	return nextTr;
+};
+const resolveOperation = ({ snapshot, operation, liveBlocks, liveBlocksByParaId, doc }) => {
+	const anchor = snapshot.anchors[operation.blockId];
+	if (!anchor) return {
+		type: "skip",
+		reason: "missingBlock"
+	};
+	const encodedParaId = getFolioParaIdFromBlockId(operation.blockId);
+	let live;
+	if (encodedParaId !== null) {
+		live = liveBlocksByParaId.get(encodedParaId);
+		if (!live) return {
+			type: "skip",
+			reason: "missingBlock"
+		};
+	} else {
+		const ordinal = ordinalAmongSameHash(snapshot, operation.blockId);
+		if (ordinal < 0) return {
+			type: "skip",
+			reason: "missingBlock"
+		};
+		live = liveBlocks.get(anchor.textHash)?.[ordinal];
+	}
+	if (!live || !live.node.isTextblock) return {
+		type: "skip",
+		reason: "changedBlock"
+	};
+	const blockNode = live.node;
+	const blockFrom = live.from;
+	const blockTo = live.to;
+	const cleanBlock = buildCleanBlockText(blockNode, blockFrom);
+	const currentText = cleanBlock.text;
+	if (hashFolioAIBlockText(normalizeFolioAIBlockText(currentText)) !== anchor.textHash) return {
+		type: "skip",
+		reason: "changedBlock"
+	};
+	if (operation.type === "insertAfterBlock" || operation.type === "insertBeforeBlock") {
+		if (operation.text.length === 0 && operation.pageBreakBefore !== true) return {
+			type: "skip",
+			reason: "emptyOperation"
+		};
+		const tableBoundary = findEnclosingTableBoundary(doc, blockFrom);
+		const isInsertAfter = operation.type === "insertAfterBlock";
+		let insertFrom;
+		if (tableBoundary) insertFrom = isInsertAfter ? tableBoundary.after : tableBoundary.before;
+		else insertFrom = isInsertAfter ? blockTo : blockFrom;
+		return {
+			type: "resolved",
+			operation: {
+				operation,
+				from: insertFrom,
+				to: insertFrom,
+				blockFrom,
+				blockTo,
+				blockNode,
+				insertText: operation.text
+			}
+		};
+	}
+	if (operation.type === "insertSignatureTable") {
+		if (operation.parties.length === 0) return {
+			type: "skip",
+			reason: "emptyOperation"
+		};
+		const position = operation.position ?? "after";
+		const tableBoundary = findEnclosingTableBoundary(doc, blockFrom);
+		let insertFrom;
+		if (tableBoundary) insertFrom = position === "after" ? tableBoundary.after : tableBoundary.before;
+		else insertFrom = position === "after" ? blockTo : blockFrom;
+		return {
+			type: "resolved",
+			operation: {
+				operation,
+				from: insertFrom,
+				to: insertFrom,
+				blockFrom,
+				blockTo,
+				blockNode
+			}
+		};
+	}
+	if (operation.type === "deleteBlock" || operation.type === "replaceBlock") {
+		const range = getTextRangeFromCleanBlock(cleanBlock);
+		if (!range) return {
+			type: "skip",
+			reason: "unsupportedBlock"
+		};
+		if (operation.type === "replaceBlock" && operation.text === currentText) return {
+			type: "skip",
+			reason: "noopOperation"
+		};
+		return {
+			type: "resolved",
+			operation: {
+				operation,
+				from: range.from,
+				to: range.to,
+				blockFrom,
+				blockTo,
+				blockNode
+			}
+		};
+	}
+	if (operation.type === "replaceInBlock" && operation.find === operation.replace) return {
+		type: "skip",
+		reason: "noopOperation"
+	};
+	const range = resolveTextInCleanBlock(cleanBlock, getOperationQuote(operation) || currentText);
+	if (range.type !== "resolved") return range;
+	return {
+		type: "resolved",
+		operation: {
+			operation,
+			from: range.from,
+			to: range.to,
+			blockFrom,
+			blockTo,
+			blockNode
+		}
+	};
+};
+const resolveTextInCleanBlock = (cleanBlock, find) => {
+	if (find.length === 0) return {
+		type: "skip",
+		reason: "emptyOperation"
+	};
+	const { text, offsets } = cleanBlock;
+	const firstIndex = text.indexOf(find);
+	if (firstIndex === -1) return {
+		type: "skip",
+		reason: "missingFind"
+	};
+	if (text.includes(find, firstIndex + 1)) return {
+		type: "skip",
+		reason: "ambiguousFind"
+	};
+	const from = offsets[firstIndex];
+	const to = offsets[firstIndex + find.length];
+	if (from === void 0 || to === void 0) return {
+		type: "skip",
+		reason: "unsupportedBlock"
+	};
+	return {
+		type: "resolved",
+		from,
+		to
+	};
+};
+const getTextRangeFromCleanBlock = (cleanBlock) => {
+	if (cleanBlock.text.length === 0) return null;
+	const from = cleanBlock.offsets[0];
+	const to = cleanBlock.offsets[cleanBlock.text.length];
+	if (from === void 0 || to === void 0) return null;
+	return {
+		from,
+		to
+	};
+};
+const getOperationCommentText = (operation) => operation.comment?.text;
+const getOperationQuote = (operation) => {
+	if (operation.type === "replaceInBlock") return operation.find;
+	if (operation.type === "commentOnBlock") return operation.quote;
+};
+//#endregion
+export { applyFolioAIEditOperations };

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

@@ -0,0 +1,28 @@
+import { Node } from "prosemirror-model";
+
+//#region src/ai-edits/clean-text.d.ts
+/**
+ * "Post-tracked-changes" view of a textblock: the string the user
+ * would see if every existing tracked change were accepted.
+ * `deletion`-marked text is skipped, `insertion`-marked text is
+ * included as plain text, everything else is included as-is.
+ *
+ * `offsets[i]` is the absolute ProseMirror position to use when you
+ * want to anchor at the character at clean-offset `i`. `offsets`
+ * has length `text.length + 1` so callers can ask for the position
+ * immediately after the last character, which is the right anchor
+ * for an insertion at end-of-block.
+ *
+ * This is the view the AI should reason against (so it doesn't see
+ * `"shallmust"` smashed together) and the view the apply engine's
+ * find-string lookup should run against (so the same offsets it
+ * sent us still resolve to the right PM positions on a doc with
+ * pending tracked changes).
+ */
+type CleanBlockText = {
+  text: string;
+  offsets: number[];
+};
+declare const buildCleanBlockText: (blockNode: Node, blockFrom: number) => CleanBlockText;
+//#endregion
+export { CleanBlockText, buildCleanBlockText };