@stll/folio-core 0.55.0 → 0.56.0

package/dist/controller/canonicalPublicOperations.js

@@ -0,0 +1,556 @@
+import { splitsGraphemeCluster, splitsSurrogatePair } from "../ai-edits/character-boundaries.js";
+import { buildCleanBlockText, resolveCleanTextRange } from "../ai-edits/clean-text.js";
+import { stripInlineEmphasisMarkers } from "../ai-edits/inline-emphasis.js";
+import { collectNoteReferenceLabels, hashFolioAIBlockText } from "../ai-edits/snapshot.js";
+import { wordDiffSessionFromOptions } from "../ai-edits/word-diff.js";
+import { getFolioDocumentOperationIssues, getFolioDocumentOperationReceiptsForStory, parseFolioDocumentOperationBatch } from "../document-operations.js";
+import { maxAnnotationIdInDoc } from "../prosemirror/plugins/revisionIds.js";
+import { CANONICAL_GAP } from "../types/canonicalCapabilities.js";
+import { Result, TaggedError, panic } from "better-result";
+import { Mark } from "prosemirror-model";
+import { OP_STORIES, applyDocumentOps, compileEditorIntent, createEditorIntentIdAllocator, documentStories } from "@stll/docx-core/ops";
+//#region src/controller/canonicalPublicOperations.ts
+/** Public batches compile against the read projection; only the canonical journal publishes. */
+/** A new public kind cannot bypass a canonical compiler/refusal decision. */
+const CANONICAL_PUBLIC_OPERATION_DISPOSITIONS = {
+	replaceInBlock: "compile",
+	replaceRange: "compile",
+	replaceBlock: "compile",
+	splitBlock: "compile",
+	formatRange: "compile",
+	mergeBlockWithNext: "compile",
+	setBlockParagraphProperties: CANONICAL_GAP.publicUnsupportedInline,
+	insertAfterBlock: CANONICAL_GAP.publicUnsupportedInline,
+	insertBeforeBlock: CANONICAL_GAP.publicUnsupportedInline,
+	deleteBlock: CANONICAL_GAP.publicUnsupportedInline,
+	commentOnBlock: CANONICAL_GAP.publicComments,
+	commentOnRange: CANONICAL_GAP.publicComments,
+	insertTable: CANONICAL_GAP.publicTableProjection,
+	insertSignatureTable: CANONICAL_GAP.publicTableProjection,
+	deleteTable: CANONICAL_GAP.publicTableProjection,
+	insertTableRow: CANONICAL_GAP.publicTableProjection,
+	deleteTableRow: CANONICAL_GAP.publicTableProjection,
+	insertTableColumn: CANONICAL_GAP.publicTableProjection,
+	deleteTableColumn: CANONICAL_GAP.publicTableProjection,
+	mergeTableCells: CANONICAL_GAP.publicTableProjection,
+	splitTableCell: CANONICAL_GAP.publicTableProjection
+};
+const compilePublicIntents = ({ document, intents, mode, author, date, nextRevisionId, allocate }) => {
+	const ops = [];
+	const revisions = [];
+	for (const sourceIntent of intents) {
+		const ids = allocate(document, sourceIntent);
+		const intent = sourceIntent.type === "splitParagraph" ? {
+			type: "splitParagraph",
+			at: sourceIntent.at,
+			...sourceIntent.to === void 0 ? {} : { to: sourceIntent.to },
+			newBlockId: ids.newBlockId
+		} : sourceIntent;
+		const firstRevisionId = nextRevisionId;
+		const compiled = compileEditorIntent(document, {
+			intent,
+			mode: mode === "direct" ? {
+				type: "editing",
+				newIds: ids.newIds
+			} : {
+				type: "suggesting",
+				revision: {
+					id: firstRevisionId,
+					author,
+					date
+				},
+				newIds: {
+					control: ids.newIds.control,
+					revision: ids.newIds.revision.map((_, index) => firstRevisionId + index + 1)
+				}
+			}
+		});
+		if (compiled.isErr()) return Result.err(compiled.error);
+		const applied = applyDocumentOps(document, compiled.value.ops);
+		if (applied.isErr()) return Result.err(applied.error);
+		document = applied.value.document;
+		ops.push(...compiled.value.ops);
+		revisions.push(...applied.value.revisions);
+		for (const id of applied.value.revisions) nextRevisionId = Math.max(nextRevisionId, id + 1);
+	}
+	return Result.ok({
+		document,
+		ops,
+		revisions,
+		nextRevisionId
+	});
+};
+var CanonicalPublicOperationResolutionError = class extends TaggedError("CanonicalPublicOperationResolutionError") {};
+const canonicalPublicStory = (story) => {
+	if (story === "main") return story;
+	switch (story.type) {
+		case "header":
+		case "footer": return {
+			kind: story.type,
+			rId: story.relationshipId
+		};
+		case "footnote":
+		case "endnote": return {
+			kind: story.type,
+			id: story.noteId
+		};
+		default: return panic(`Unknown public operation story ${story}`);
+	}
+};
+const batchStatus = (batch, skippedCount) => {
+	if (batch.dryRun) return "previewed";
+	if (batch.atomic && skippedCount > 0) return "rejected";
+	return "committed";
+};
+/** Handles address isolated journal groups; no second document or PM history is retained. */
+var CanonicalPublicOperations = class {
+	options;
+	handles = [];
+	nextHandle = 1;
+	handleNamespace = crypto.randomUUID();
+	constructor(options) {
+		this.options = options;
+	}
+	apply(options) {
+		const batch = parseFolioDocumentOperationBatch(options.batch);
+		const { session } = this.options;
+		const publicStory = options.story ?? "main";
+		const story = canonicalPublicStory(publicStory);
+		const state = this.options.getState(story);
+		const projected = session.projectStory(story);
+		const skipped = [];
+		const normalizations = [];
+		const refusals = /* @__PURE__ */ new Map();
+		const resolved = [];
+		const { diff } = wordDiffSessionFromOptions(options.wordDiff);
+		let nextRevisionId = options.revisionStamp?.idSeed ?? 1;
+		if (!session.isComposing && options.revisionStamp === void 0) for (const currentStory of documentStories(session.document)) {
+			const currentProjection = session.projectStory(currentStory);
+			if (currentProjection.isOk()) nextRevisionId = Math.max(nextRevisionId, maxAnnotationIdInDoc(currentProjection.value.doc) + 1);
+		}
+		const skip = (id, reason, message) => {
+			skipped.push({
+				id,
+				reason,
+				...message === void 0 ? {} : { message }
+			});
+		};
+		const result = (applied, undoHandle) => {
+			const failures = new Map(skipped.map((item) => [item.id, item]));
+			const ordered = batch.operations.flatMap(({ id }) => {
+				const failure = failures.get(id);
+				if (!failure) return [];
+				const canonicalRefusal = refusals.get(id);
+				return [canonicalRefusal ? {
+					...failure,
+					canonicalRefusal
+				} : failure];
+			});
+			return {
+				version: 1,
+				status: batchStatus(batch, ordered.length),
+				applied,
+				skipped: ordered,
+				issues: getFolioDocumentOperationIssues(batch.operations, ordered),
+				receipts: getFolioDocumentOperationReceiptsForStory({
+					operations: batch.operations,
+					applied,
+					story: publicStory
+				}),
+				undoHandle,
+				nextRevisionId,
+				...normalizations.length === 0 ? {} : { normalizations }
+			};
+		};
+		for (const operation of batch.operations) {
+			if (story !== OP_STORIES.MAIN) {
+				refusals.set(operation.id, { gap: CANONICAL_GAP.publicSecondaryStories });
+				skip(operation.id, "unsupportedBlock", "Canonical public secondary-story routing is unavailable.");
+				continue;
+			}
+			if (!state || projected.isErr() || session.isComposing) {
+				skip(operation.id, "documentNotEditable");
+				continue;
+			}
+			if (batch.mode === "suggested") {
+				refusals.set(operation.id, { gap: CANONICAL_GAP.publicSuggestedMode });
+				skip(operation.id, "unsupportedMode", "Canonical pending suggestions are unavailable.");
+				continue;
+			}
+			if (options.tableTemplates !== void 0 || options.undefinedStyles === "keep") {
+				refusals.set(operation.id, { gap: CANONICAL_GAP.publicUnsupportedInline });
+				skip(operation.id, "unsupportedBlock", "This canonical compiler does not support the supplied execution options.");
+				continue;
+			}
+			const disposition = CANONICAL_PUBLIC_OPERATION_DISPOSITIONS[operation.type];
+			if (disposition !== "compile" || "comment" in operation && operation.comment !== void 0) {
+				refusals.set(operation.id, { gap: disposition === "compile" ? CANONICAL_GAP.publicComments : disposition });
+				skip(operation.id, "unsupportedBlock");
+				continue;
+			}
+			const compiled = this.resolve({
+				operation,
+				options,
+				state,
+				story,
+				diff
+			});
+			if (compiled.isErr()) {
+				if (compiled.error.reason === "unsupportedBlock") refusals.set(operation.id, { gap: CANONICAL_GAP.publicUnsupportedInline });
+				skip(operation.id, compiled.error.reason, compiled.error.message);
+				continue;
+			}
+			if (resolved.some(({ from, to }) => compiled.value.from < to && compiled.value.to > from || from === to && compiled.value.from <= from && compiled.value.to >= from || compiled.value.from === compiled.value.to && compiled.value.from >= from && compiled.value.from <= to)) {
+				skip(operation.id, "overlappingOperation");
+				continue;
+			}
+			resolved.push(compiled.value);
+		}
+		if (batch.atomic && skipped.length > 0) {
+			for (const { operation } of resolved) skip(operation.id, "atomicBatchRejected");
+			return result([], null);
+		}
+		if (!state || projected.isErr() || session.isComposing) return result([], null);
+		resolved.sort((left, right) => right.from - left.from);
+		let document = session.document;
+		const ops = [];
+		const appliedById = /* @__PURE__ */ new Map();
+		const allocate = createEditorIntentIdAllocator();
+		const date = options.revisionStamp?.date ?? (/* @__PURE__ */ new Date()).toISOString();
+		for (const { operation, intents, normalizations: adjustments } of resolved) {
+			const compiled = compilePublicIntents({
+				document,
+				intents,
+				allocate,
+				nextRevisionId,
+				mode: batch.mode === "direct" ? "direct" : "tracked-changes",
+				author: options.author ?? "AI",
+				date
+			});
+			if (compiled.isErr()) {
+				refusals.set(operation.id, { gap: CANONICAL_GAP.publicUnsupportedInline });
+				skip(operation.id, "unsupportedBlock", compiled.error.message);
+				continue;
+			}
+			if (compiled.value.ops.length === 0) {
+				skip(operation.id, "noopOperation");
+				continue;
+			}
+			normalizations.push(...adjustments);
+			document = compiled.value.document;
+			ops.push(...compiled.value.ops);
+			nextRevisionId = compiled.value.nextRevisionId;
+			const revisionIds = compiled.value.revisions;
+			const revisionId = revisionIds.at(0);
+			appliedById.set(operation.id, {
+				id: operation.id,
+				...revisionId === void 0 ? {} : {
+					revisionId,
+					revisionIds
+				}
+			});
+		}
+		if (batch.atomic && skipped.length > 0) {
+			for (const { id } of appliedById.values()) skip(id, "atomicBatchRejected");
+			return result([], null);
+		}
+		if (ops.length === 0) return result([], null);
+		const selection = projected.value.selectionAt(state);
+		const prepared = selection.isErr() ? selection : session.prepareOps(state, ops, selection.value);
+		if (prepared.isErr()) {
+			for (const { id } of appliedById.values()) {
+				refusals.set(id, { gap: CANONICAL_GAP.publicUnsupportedInline });
+				skip(id, prepared.error.reason === "noChange" ? "noopOperation" : "unsupportedBlock", prepared.error.message);
+			}
+			return result([], null);
+		}
+		const applied = batch.operations.flatMap(({ id }) => {
+			const entry = appliedById.get(id);
+			return entry ? [batch.dryRun ? { id } : entry] : [];
+		});
+		if (batch.dryRun) return result(applied, null);
+		if (!this.options.publish(prepared.value)) {
+			for (const { id } of applied) skip(id, "documentNotEditable");
+			return result([], null);
+		}
+		const handle = {
+			type: "documentOperationUndo",
+			id: `canonical-${this.handleNamespace}-${String(this.nextHandle++)}`
+		};
+		this.handles.push({
+			handle,
+			version: session.version,
+			story
+		});
+		return result(applied, handle);
+	}
+	undo(handle) {
+		const index = this.handles.findIndex(({ handle: existing }) => existing.id === handle.id && existing.type === handle.type);
+		if (index < 0) return {
+			status: "rejected",
+			undoHandle: handle,
+			reason: "unknownHandle"
+		};
+		if (index !== this.handles.length - 1) return {
+			status: "rejected",
+			undoHandle: handle,
+			reason: "notLatest"
+		};
+		const entry = this.handles.at(-1);
+		const { session } = this.options;
+		if (!entry || entry.version !== session.version) return {
+			status: "rejected",
+			undoHandle: handle,
+			reason: "documentChanged"
+		};
+		const state = this.options.getState(entry.story);
+		if (!state) return {
+			status: "rejected",
+			undoHandle: handle,
+			reason: "documentChanged"
+		};
+		const prepared = session.prepareUndo(state, entry.story);
+		if (prepared.isErr() || !this.options.publish(prepared.value)) return {
+			status: "rejected",
+			undoHandle: handle,
+			reason: "documentChanged"
+		};
+		this.handles.pop();
+		const previous = this.handles.at(-1);
+		if (previous && previous.version === entry.version - 1) previous.version = session.version;
+		return {
+			status: "undone",
+			undoHandle: handle
+		};
+	}
+	resolve({ operation, options, state, story, diff }) {
+		const refusal = (reason, message) => Result.err(new CanonicalPublicOperationResolutionError({
+			reason,
+			message: message ?? `The operation was refused: ${reason}.`
+		}));
+		if ("comment" in operation) return refusal("unsupportedBlock", "Canonical comment operations are unavailable.");
+		switch (operation.type) {
+			case "replaceInBlock":
+			case "replaceRange":
+			case "replaceBlock":
+			case "splitBlock":
+			case "formatRange":
+			case "mergeBlockWithNext": break;
+			default: return refusal("unsupportedBlock", `Canonical public operation ${operation.type} is unavailable.`);
+		}
+		const blockId = operation.type === "replaceRange" || operation.type === "formatRange" ? operation.range.blockId : operation.blockId;
+		const anchor = Object.hasOwn(options.snapshot.anchors, blockId) ? options.snapshot.anchors[blockId] : void 0;
+		const projection = this.options.session.projectStory(story);
+		if (!anchor || projection.isErr()) return refusal("missingBlock");
+		const paragraph = projection.value.paragraph(blockId);
+		if (!paragraph) return refusal("missingBlock");
+		if (paragraph.source.pPrMark?.kind === "del" || paragraph.source.pPrMark?.kind === "moveFrom") return refusal("pendingDeletion");
+		const clean = buildCleanBlockText(paragraph.node, paragraph.start - 1, {
+			fieldResults: "text",
+			noteReferences: collectNoteReferenceLabels(state.doc)
+		});
+		const hash = hashFolioAIBlockText(clean.text);
+		if (operation.precondition && hash !== operation.precondition.blockTextHash) return refusal("preconditionFailed");
+		if (hash !== anchor.textHash) return refusal("changedBlock");
+		let start = 0;
+		let end = clean.text.length;
+		let text = "";
+		switch (operation.type) {
+			case "replaceInBlock":
+				if (operation.find === "") return refusal("emptyOperation");
+				start = clean.text.indexOf(operation.find);
+				if (start < 0) return refusal("missingFind");
+				if (clean.text.indexOf(operation.find, start + 1) >= 0) return refusal("ambiguousFind");
+				end = start + operation.find.length;
+				text = operation.replace;
+				break;
+			case "replaceRange":
+			case "formatRange":
+				start = operation.range.startOffset;
+				end = operation.range.endOffset;
+				if (hashFolioAIBlockText(clean.text.slice(start, end)) !== operation.range.selectedTextHash) return refusal("staleRange");
+				text = operation.type === "replaceRange" ? operation.replace : "";
+				break;
+			case "replaceBlock":
+				if (operation.styleId !== void 0 || operation.preserveFormatting === false) return refusal("unsupportedBlock", "Canonical replacement paragraph properties are unavailable.");
+				text = operation.text;
+				break;
+			case "splitBlock":
+				if (operation.firstParagraphProperties || operation.secondParagraphProperties) return refusal("unsupportedBlock", "Canonical split paragraph properties are unavailable.");
+				start = operation.offset;
+				end = start + (operation.separator?.length ?? 0);
+				if (start <= 0 || start >= clean.text.length || clean.text.slice(start, end) !== (operation.separator ?? "")) return refusal("staleRange");
+				break;
+			case "mergeBlockWithNext":
+				if (operation.mergedParagraphProperties || operation.separator) return refusal("unsupportedBlock", "Canonical public join properties and separators are unavailable.");
+				start = clean.text.length;
+				end = start;
+				break;
+			default: return operation;
+		}
+		if ([start, end].some((offset) => splitsSurrogatePair(clean.text, offset) || splitsGraphemeCluster(clean.text, offset))) return refusal("splitsCharacter");
+		if (clean.structuralBoundaries.some((boundary) => boundary.type === "noteReference" && start < boundary.offset + boundary.length && end > boundary.offset)) return refusal("protectedReference");
+		if (stripInlineEmphasisMarkers(text) !== text) return refusal("unsupportedBlock", "Canonical public emphasis replacements are unavailable.");
+		if (/\[\^(?:e)?\d+\]/u.test(text) || /[\t\r\n]/u.test(text)) return refusal("unsupportedBlock", "Canonical public replacements require plain text.");
+		const range = resolveCleanTextRange({
+			cleanBlock: clean,
+			startOffset: start,
+			endOffset: end
+		});
+		if (!range) return refusal("staleRange");
+		const from = projection.value.addressAt(range.from);
+		const to = projection.value.addressAt(range.to);
+		if (from.isErr() || to.isErr()) return refusal("unsupportedBlock");
+		if (operation.type !== "splitBlock" && operation.type !== "formatRange" && operation.type !== "mergeBlockWithNext" && clean.text.slice(start, end) === text) return refusal("noopOperation");
+		let intent;
+		switch (operation.type) {
+			case "splitBlock":
+				intent = {
+					type: "splitParagraph",
+					at: from.value,
+					to: to.value,
+					newBlockId: createEditorIntentIdAllocator()(this.options.session.document, {
+						type: "splitParagraph",
+						at: from.value,
+						to: to.value
+					}).newBlockId
+				};
+				break;
+			case "mergeBlockWithNext": {
+				const body = this.options.session.document.package.document.content;
+				if (story !== "main") return refusal("unsupportedBlock", "Canonical public joins currently require the main story.");
+				const next = body.at(body.findIndex((block) => block.type === "paragraph" && block.paraId === blockId) + 1);
+				if (next?.type !== "paragraph" || !next.paraId) return refusal("missingBlock");
+				intent = {
+					type: "joinParagraphs",
+					story,
+					blockId,
+					nextBlockId: next.paraId
+				};
+				break;
+			}
+			case "formatRange": {
+				const formatting = operation.formatting;
+				const patch = {
+					...formatting.bold === void 0 ? {} : { bold: formatting.bold },
+					...formatting.italic === void 0 ? {} : { italic: formatting.italic },
+					...formatting.underline === void 0 ? {} : { underline: formatting.underline === null ? null : { style: formatting.underline ? "single" : "none" } },
+					...formatting.strike === void 0 ? {} : {
+						strike: formatting.strike,
+						doubleStrike: null
+					},
+					...formatting.fontSizePt === void 0 ? {} : { fontSize: formatting.fontSizePt === null ? null : formatting.fontSizePt * 2 },
+					...formatting.fontFamily === void 0 ? {} : { fontFamily: formatting.fontFamily === null ? null : {
+						ascii: formatting.fontFamily,
+						hAnsi: formatting.fontFamily
+					} },
+					...formatting.color === void 0 ? {} : { color: formatting.color === null ? null : { rgb: formatting.color.replace(/^#/u, "").toUpperCase() } }
+				};
+				intent = {
+					type: "formatRun",
+					from: from.value,
+					to: to.value,
+					patch
+				};
+				break;
+			}
+			case "replaceInBlock":
+			case "replaceRange":
+			case "replaceBlock":
+				intent = {
+					type: "replaceText",
+					from: from.value,
+					to: to.value,
+					text,
+					...options.replacementBackground === "keep" ? {} : { runPropsPatch: {
+						highlight: null,
+						shading: null
+					} }
+				};
+				break;
+			default: return panic(`Unknown canonical public operation ${operation}`);
+		}
+		const intents = [];
+		const normalizations = [];
+		if (intent.type === "replaceText") {
+			let offset = start;
+			let pending = null;
+			const changes = [];
+			for (const segment of diff(clean.text.slice(start, end), text)) switch (segment.type) {
+				case "equal":
+					if (pending) changes.push(pending);
+					pending = null;
+					offset += segment.text.length;
+					break;
+				case "del":
+					pending ??= {
+						start: offset,
+						end: offset,
+						text: ""
+					};
+					offset += segment.text.length;
+					pending.end = offset;
+					break;
+				case "ins":
+					pending ??= {
+						start: offset,
+						end: offset,
+						text: ""
+					};
+					pending.text += segment.text;
+					break;
+				default: {
+					const unreachable = segment.type;
+					return panic(`Unknown replacement diff ${unreachable}`);
+				}
+			}
+			if (pending) changes.push(pending);
+			for (const change of changes.toReversed()) {
+				const gap = resolveCleanTextRange({
+					cleanBlock: clean,
+					startOffset: change.start,
+					endOffset: change.end
+				});
+				if (!gap) return refusal("unsupportedBlock");
+				if (change.text.length > 0 && gap.from < gap.to) {
+					let first = null;
+					let uniform = true;
+					paragraph.node.nodesBetween(gap.from - paragraph.start, gap.to - paragraph.start, (node) => {
+						if (!node.isText || node.marks.some((mark) => mark.type.name === "deletion")) return;
+						const marks = node.marks.filter((mark) => mark.type.name !== "insertion");
+						if (first === null) first = marks;
+						else if (!Mark.sameSet(first, marks)) uniform = false;
+					});
+					if (!uniform && normalizations.length === 0) normalizations.push({
+						id: operation.id,
+						code: "uniformReplacementFormatting"
+					});
+				}
+				const changeFrom = projection.value.addressAt(gap.from);
+				const changeTo = projection.value.addressAt(gap.to);
+				if (changeFrom.isErr() || changeTo.isErr()) return refusal("unsupportedBlock");
+				intents.push({
+					type: "replaceText",
+					from: changeFrom.value,
+					to: changeTo.value,
+					text: change.text,
+					...intent.runPropsPatch === void 0 ? {} : { runPropsPatch: intent.runPropsPatch }
+				});
+			}
+		} else intents.push(intent);
+		const structural = operation.type === "splitBlock" || operation.type === "mergeBlockWithNext";
+		const nextParagraph = operation.type === "mergeBlockWithNext" && intent.type === "joinParagraphs" ? projection.value.paragraph(intent.nextBlockId) : void 0;
+		let claimedTo = range.to;
+		if (structural) claimedTo = paragraph.start + paragraph.node.content.size;
+		if (nextParagraph) claimedTo = nextParagraph.start + nextParagraph.node.content.size;
+		return Result.ok({
+			operation,
+			intents,
+			normalizations,
+			from: structural ? paragraph.start : range.from,
+			to: claimedTo
+		});
+	}
+};
+//#endregion
+export { CANONICAL_PUBLIC_OPERATION_DISPOSITIONS, CanonicalPublicOperations };

package/dist/controller/canonicalSession.d.ts

@@ -1,4 +1,7 @@
 import { document_d_exports } from "../types/document.js";
+import { CanonicalGap } from "../types/canonicalCapabilities.js";
+import { CanonicalSaveSnapshot } from "../types/canonicalSave.js";
+import { CanonicalInlineGap } from "./canonicalInlineProjection.js";
 import { Node } from "prosemirror-model";
 import { EditorState, Transaction } from "prosemirror-state";
 import { Result } from "better-result";
@@ -7,9 +10,11 @@ import { DocumentOp, EditorIntent, OpStory, TextPosition, TouchedBlocks } from "
 declare const CanonicalSessionError_base: import("better-result").TaggedErrorClass<"CanonicalSessionError">;
 declare class CanonicalSessionError extends CanonicalSessionError_base<{
   message: string;
+  gap: CanonicalGap;
   reason: "refused" | "noChange";
 }> {}
 type CanonicalSelection = {
+  type: "text" | "all";
   anchor: TextPosition;
   head: TextPosition;
 };
@@ -25,7 +30,7 @@ type ParagraphAddress = {
   blockId: string;
   start: number;
   text: string;
-  boundaries: readonly (readonly number[])[];
+  boundaries: readonly (readonly CanonicalInlineGap[])[];
   node: Node;
   source: document_d_exports.Paragraph;
 };
@@ -34,7 +39,7 @@ type CanonicalProjectionOptions = {
   paragraphs: readonly ParagraphAddress[];
   story: OpStory;
 };
-/** Paragraph gaps map logical UTF-16 units and zero-width note marks to PM positions. */
+/** Paragraph gaps bind logical units and source zero-width ordinals to PM positions. */
 declare class CanonicalProjection {
   readonly doc: Node;
   readonly story: OpStory;
@@ -82,14 +87,22 @@ type CanonicalReplaceTextInput = {
   to: number;
   text: string;
   story?: OpStory;
-  semantic?: CanonicalInputSemantic;
   time?: number;
-};
+} & ({
+  semantic: "composition";
+  compositionPhase?: "correction";
+} | {
+  semantic?: Exclude<CanonicalInputSemantic, "composition">;
+  compositionPhase?: never;
+});
 /** Immutable model authority with a journal staged independently of the PM view. */
 declare class CanonicalSession {
   private currentDocument;
   private currentProjection;
+  private readonly sourceBlockIds;
   private currentVersion;
+  private readonly saveTouched;
+  private saveStructure;
   private readonly allocateIntentIds;
   private mode;
   private readonly allocatedBlockIds;
@@ -111,6 +124,7 @@ declare class CanonicalSession {
   private intentNeedsIdentityIds;
   private rememberSources;
   get document(): document_d_exports.Document;
+  captureSaveSnapshot(): CanonicalSaveSnapshot;
   get projection(): CanonicalProjection;
   get selection(): CanonicalSelection | null;
   get version(): number;
@@ -121,9 +135,13 @@ declare class CanonicalSession {
   beginComposition(): Result<void, CanonicalSessionError>;
   endComposition(): void;
   private checkState;
-  prepareReplace(state: EditorState, { from, to, text, story, semantic, time }: CanonicalReplaceTextInput): Result<CanonicalCommit, CanonicalSessionError>;
+  prepareReplace(state: EditorState, { from, to, text, story, semantic, compositionPhase, time }: CanonicalReplaceTextInput): Result<CanonicalCommit, CanonicalSessionError>;
   prepareIntent(state: EditorState, intent: EditorIntent): Result<CanonicalCommit, CanonicalSessionError>;
-  prepareIntents(state: EditorState, intents: readonly EditorIntent[]): Result<CanonicalCommit, CanonicalSessionError>;
+  prepareIntents(state: EditorState, { intents, resourceOps, semantic }: {
+    intents: readonly EditorIntent[];
+    resourceOps?: readonly DocumentOp[];
+    semantic?: CanonicalInputSemantic;
+  }): Result<CanonicalCommit, CanonicalSessionError>;
   prepareOps(state: EditorState, ops: readonly DocumentOp[], postSelection: CanonicalSelection): Result<CanonicalCommit, CanonicalSessionError>;
   private prepareJournalledOps;
   prepareSplit(state: EditorState): Result<CanonicalCommit, CanonicalSessionError>;