@stll/folio-core 0.56.0 → 0.57.0

package/dist/controller/canonicalComposition.d.ts

@@ -37,6 +37,10 @@ type CompositionFinish = {
 declare const createCanonicalComposition: (options: CompositionOptions) => {
   readonly status: CompositionState["type"];
   readonly active: boolean;
+  matchesCancellationRange: (view: EditorView, range: {
+    from: number;
+    to: number;
+  }) => boolean;
   start: (view: EditorView) => void;
   ended: (view: EditorView) => void;
   forgetCompleted: () => void;

package/dist/controller/canonicalComposition.js

@@ -5,7 +5,6 @@ import { CanonicalSessionError } from "./canonicalSession.js";
 import { Result } from "better-result";
 import { EditorState, TextSelection } from "prosemirror-state";
 //#region src/controller/canonicalComposition.ts
-const COMPOSITION_FLUSH_DELAY_MS = 25;
 /** Native IME owns the provisional view; the captured canonical projection stays unchanged. */
 const createCanonicalComposition = (options) => {
 	let state = { type: "committed" };
@@ -50,23 +49,44 @@ const createCanonicalComposition = (options) => {
 		if (!$from.sameParent($to)) return null;
 		const start = $from.start();
 		const next = proposed.doc.nodeAt(start - 1);
-		if (!next || next.type !== $from.parent.type || next.content.size !== next.textContent.length) return null;
-		const before = $from.parent.textContent;
-		const after = next.textContent;
-		let from = 0;
-		while (from < before.length && from < after.length && before[from] === after[from]) from++;
-		while (splitsSurrogatePair(before, from) || splitsSurrogatePair(after, from)) from--;
-		let oldEnd = before.length;
-		let newEnd = after.length;
+		if (!next || next.type !== $from.parent.type) return null;
+		const previous = $from.parent.content;
+		const changedFrom = previous.findDiffStart(next.content);
+		if (changedFrom === null) {
+			if (!baseline.doc.eq(proposed.doc)) return null;
+			return {
+				from: baseline.selection.from,
+				to: baseline.selection.from,
+				text: "",
+				semantic: "composition"
+			};
+		}
+		const changedEnd = previous.findDiffEnd(next.content);
+		if (changedEnd === null) return null;
+		let from = changedFrom;
+		let oldEnd = changedEnd.a;
+		let newEnd = changedEnd.b;
+		const overlap = from - Math.min(oldEnd, newEnd);
+		if (overlap > 0) {
+			oldEnd += overlap;
+			newEnd += overlap;
+		}
+		const before = previous.textBetween(0, previous.size, "", "");
+		const after = next.content.textBetween(0, next.content.size, "", "");
+		while (from < oldEnd && from < newEnd && before[from] === after[from]) from++;
 		while (oldEnd > from && newEnd > from && before[oldEnd - 1] === after[newEnd - 1]) {
 			oldEnd--;
 			newEnd--;
 		}
+		while (splitsSurrogatePair(before, from) || splitsSurrogatePair(after, from)) from--;
 		while (splitsSurrogatePair(before, oldEnd) || splitsSurrogatePair(after, newEnd)) {
 			oldEnd++;
 			newEnd++;
 		}
-		const text = after.slice(from, newEnd);
+		const removed = previous.cut(from, oldEnd);
+		const inserted = next.content.cut(from, newEnd);
+		const text = inserted.textBetween(0, inserted.size, "", "");
+		if (removed.textBetween(0, removed.size, "", "").length !== removed.size || text.length !== inserted.size) return null;
 		if (!baseline.tr.insertText(text, start + from, start + oldEnd).doc.eq(proposed.doc)) return null;
 		return {
 			from: start + from,
@@ -130,7 +150,7 @@ const createCanonicalComposition = (options) => {
 	};
 	const schedule = (view) => {
 		clearTimer();
-		timer = setCanonicalInputTimer(() => finish(view, true), COMPOSITION_FLUSH_DELAY_MS);
+		timer = setCanonicalInputTimer(() => finish(view, true), 25);
 	};
 	return {
 		get status() {
@@ -139,6 +159,18 @@ const createCanonicalComposition = (options) => {
 		get active() {
 			return state.type !== "committed";
 		},
+		matchesCancellationRange: (view, range) => {
+			if (state.type === "committed" || state.view !== view) return false;
+			const text = selectedText(state.baseline, view.state);
+			if (text === null || text.length === 0) return false;
+			const from = state.baseline.selection.from;
+			if (range.from !== from || range.to !== from + text.length) return false;
+			const selection = view.dom.ownerDocument.getSelection();
+			if (!selection || selection.rangeCount !== 1) return false;
+			const selected = selection.getRangeAt(0);
+			if (!view.dom.contains(selected.startContainer) || !view.dom.contains(selected.endContainer)) return false;
+			return view.posAtDOM(selected.startContainer, selected.startOffset) === range.from && view.posAtDOM(selected.endContainer, selected.endOffset) === range.to;
+		},
 		start: (view) => {
 			if (state.type !== "committed") return;
 			if (!options.begin()) return;

package/dist/controller/canonicalInlineProjection.d.ts

@@ -106,8 +106,13 @@ type CanonicalInlineProjectionArgs = {
   source: document_d_exports.Paragraph;
   paragraph: Node;
   pairedBookmarkIds: ReadonlySet<number>;
+  commentContext?: {
+    rangedIds: ReadonlySet<number>;
+    pointIds: ReadonlySet<number>;
+    openIds: ReadonlySet<number>;
+  };
 };
 /** Bind rendered gaps to the operation owner's source leaf ordinals, including collapsed pairs. */
-declare const projectCanonicalInline: ({ source, paragraph, pairedBookmarkIds }: CanonicalInlineProjectionArgs) => Result<InlineProjection, InlineProjectionError>;
+declare const projectCanonicalInline: ({ source, paragraph, pairedBookmarkIds, commentContext }: CanonicalInlineProjectionArgs) => Result<InlineProjection, InlineProjectionError>;
 //#endregion
 export { CANONICAL_NATIVE_INLINE_POLICIES, CANONICAL_SOURCE_INLINE_POLICIES, CanonicalInlineGap, canonicalInlineSourceIssue, canonicalNativeCells, projectCanonicalInline };

package/dist/controller/canonicalInlineProjection.js

@@ -1,5 +1,5 @@
 import { readNoteMarkerAttrs } from "../internal/noteMarkerAttrs.js";
-import { readFootnoteRefMarkAttrs, readPreservedXmlAttrs } from "../prosemirror/attrs/index.js";
+import { readCommentMarkAttrs, readFootnoteRefMarkAttrs, readPreservedXmlAttrs } from "../prosemirror/attrs/index.js";
 import { bookmarkMarkerFromAttrs, readBookmarkBoundaryAttrs } from "../prosemirror/bookmarkBoundaryAttrs.js";
 import { HYPHEN_TEXT_CARRIERS } from "../prosemirror/conversion/hyphenTextCarriers.js";
 import { readMoveRangeBoundaryAttrs } from "../prosemirror/moveRangeBoundaryAttrs.js";
@@ -279,10 +279,62 @@ const sameSourceMarker = (left, right) => {
 		default: return false;
 	}
 };
+/** Marks carry nonempty ranges; explicit range anchors carry empty ranges. */
+const commentMarkTransitions = ({ source, paragraph, commentContext }) => {
+	const spans = inlineLeafSpans(source.content);
+	const rangedIds = new Set(commentContext?.rangedIds);
+	const pointIds = new Set(commentContext?.pointIds);
+	const finalIds = new Set(commentContext?.openIds);
+	for (const { node } of spans) {
+		if (node.type === "commentRangeStart" || node.type === "commentRangeEnd") rangedIds.add(node.id);
+		if (node.type === "commentReference") pointIds.add(node.id);
+		if (node.type === "commentRangeStart") finalIds.add(node.id);
+		if (node.type === "commentRangeEnd") finalIds.delete(node.id);
+	}
+	const transitions = /* @__PURE__ */ new Map();
+	let previous = new Set(commentContext?.openIds);
+	let issue;
+	const record = (position, current) => {
+		const starts = new Set([...current].filter((id) => !previous.has(id)));
+		const ends = new Set([...previous].filter((id) => !current.has(id)));
+		if (starts.size > 0 || ends.size > 0) transitions.set(position, {
+			starts,
+			ends
+		});
+		previous = current;
+	};
+	paragraph.forEach((node, position) => {
+		if (issue !== void 0) return;
+		const current = /* @__PURE__ */ new Set();
+		for (const mark of node.marks) {
+			if (mark.type.name !== "comment") continue;
+			const attrs = readCommentMarkAttrs(mark);
+			if (!attrs.ok) {
+				issue = "Canonical editing requires valid comment mark attributes.";
+				return;
+			}
+			const id = attrs.value.commentId;
+			if (rangedIds.has(id)) current.add(id);
+			else if (!pointIds.has(id)) {
+				issue = "Canonical editing cannot attribute a comment mark to its source.";
+				return;
+			}
+		}
+		record(position, current);
+	});
+	record(paragraph.content.size, finalIds);
+	return issue === void 0 ? Result.ok(transitions) : refuse(issue);
+};
 /** Bind rendered gaps to the operation owner's source leaf ordinals, including collapsed pairs. */
-const projectCanonicalInline = ({ source, paragraph, pairedBookmarkIds }) => {
+const projectCanonicalInline = ({ source, paragraph, pairedBookmarkIds, commentContext }) => {
 	const native = canonicalNativeCells(paragraph);
 	if (native.isErr()) return native;
+	const comments = commentMarkTransitions({
+		source,
+		paragraph,
+		...commentContext === void 0 ? {} : { commentContext }
+	});
+	if (comments.isErr()) return comments;
 	const spans = inlineLeafSpans(source.content);
 	const erasedBookmarks = /* @__PURE__ */ new Set();
 	const collectErasedBookmarks = (items, context) => {
@@ -296,6 +348,28 @@ const projectCanonicalInline = ({ source, paragraph, pairedBookmarkIds }) => {
 		}
 	};
 	collectErasedBookmarks(source.content, "paragraph");
+	const markedCommentIds = /* @__PURE__ */ new Set();
+	paragraph.descendants((node) => {
+		for (const mark of node.marks) {
+			if (mark.type.name !== "comment") continue;
+			const attrs = readCommentMarkAttrs(mark);
+			if (attrs.ok) markedCommentIds.add(attrs.value.commentId);
+		}
+	});
+	const commentRangeOffsets = /* @__PURE__ */ new Map();
+	for (const { node, before } of spans) {
+		if (node.type !== "commentRangeStart" && node.type !== "commentRangeEnd") continue;
+		const offsets = commentRangeOffsets.get(node.id) ?? {};
+		if (node.type === "commentRangeStart") offsets.start = before.offset;
+		else offsets.end = before.offset;
+		commentRangeOffsets.set(node.id, offsets);
+	}
+	const erasedCommentMarkers = /* @__PURE__ */ new Set();
+	for (const { node } of spans) {
+		if (node.type !== "commentRangeStart" && node.type !== "commentRangeEnd") continue;
+		const offsets = commentRangeOffsets.get(node.id);
+		if (!(offsets?.start !== void 0 && offsets.end !== void 0 && offsets.start === offsets.end) && markedCommentIds.has(node.id)) erasedCommentMarkers.add(node);
+	}
 	const text = paragraphLogicalText(source);
 	const boundaries = Array.from({ length: text.length + 1 }, () => []);
 	let index = 0;
@@ -314,7 +388,15 @@ const projectCanonicalInline = ({ source, paragraph, pairedBookmarkIds }) => {
 	const consumeErasedLeaves = (position) => {
 		while (consumed === 0) {
 			const span = spans.at(index);
-			if (!span || span.before.offset !== span.after.offset || !(erasedBookmarks.has(span.node) || CANONICAL_SOURCE_INLINE_POLICIES[span.node.type] === "container" && sourceContainerChildren(span.node).length === 0)) break;
+			if (position !== null && span && (span.node.type === "commentRangeStart" || span.node.type === "commentRangeEnd")) {
+				const transition = comments.value.get(position);
+				if ((span.node.type === "commentRangeStart" ? transition?.starts : transition?.ends)?.delete(span.node.id)) {
+					index += 1;
+					addGap(position, span.after);
+					continue;
+				}
+			}
+			if (!span || span.before.offset !== span.after.offset || !(erasedBookmarks.has(span.node) || erasedCommentMarkers.has(span.node) || CANONICAL_SOURCE_INLINE_POLICIES[span.node.type] === "container" && sourceContainerChildren(span.node).length === 0)) break;
 			index += 1;
 			if (position !== null) addGap(position, span.after);
 		}
@@ -381,6 +463,7 @@ const projectCanonicalInline = ({ source, paragraph, pairedBookmarkIds }) => {
 		}
 	}
 	consumeErasedLeaves(paragraph.content.size);
+	if ([...comments.value.values()].some(({ starts, ends }) => starts.size > 0 || ends.size > 0)) return refuse("Canonical editing cannot attribute a comment mark transition to its source.");
 	const missing = spans.at(index);
 	if (missing || consumed !== 0) return refuse(`Canonical editing cannot display the source positions of ${missing?.node.type ?? "incomplete text"}.`);
 	if (boundaries.some((gaps) => gaps.length === 0)) return refuse("Canonical editing lost a source character boundary.");

package/dist/controller/canonicalInput.js

@@ -1,4 +1,4 @@
-import { handleEditorBeforeInput } from "../prosemirror/textInput.js";
+import { getEditorInputTargetRange, handleEditorBeforeInput } from "../prosemirror/textInput.js";
 import { createCanonicalComposition } from "./canonicalComposition.js";
 import { deletionRange, isCanonicalJoinBoundary } from "./canonicalSession.js";
 import { ReplaceStep } from "prosemirror-transform";
@@ -237,6 +237,15 @@ const createCanonicalInputBoundary = (options) => {
 					return refuseEvent(event, "Composition has no captured canonical baseline.");
 				}
 				if (composition.active) {
+					if (view.composing && (event.inputType === "deleteContentBackward" || event.inputType === "deleteContentForward")) {
+						const range = getEditorInputTargetRange(view, event);
+						if (range && composition.matchesCancellationRange(view, range)) {
+							event.preventDefault();
+							composition.cancel(view);
+							closeGroup();
+							return true;
+						}
+					}
 					const nativeFinal = view.composing && (event.inputType === "insertText" || event.inputType === "insertReplacementText");
 					const nativeStillComposing = view.composing;
 					const recovered = composition.recover(view);

package/dist/controller/canonicalInputTimer.d.ts

@@ -1,7 +1,16 @@
+import { EditorView } from "prosemirror-view";
 //#region src/controller/canonicalInputTimer.d.ts
 /** Shared by timer producers and browser diagnostics, regardless of bundling. */
 declare const CANONICAL_INPUT_TIMER_OWNER = "folio.canonical-input-timer";
+/** Delay after native composition end before the canonical session settles it. */
+declare const CANONICAL_COMPOSITION_FLUSH_DELAY_MS = 25;
 /** Mark the scheduled wrapper, never the caller's potentially shared callback. */
 declare const setCanonicalInputTimer: (callback: () => void, delay: number) => NodeJS.Timeout;
+/**
+ * Run `retry` once the view's canonical composition has settled. The session
+ * settles on an equal-delay timer armed at native composition end, so a retry
+ * armed at or after that point runs after it. Returns a disposer.
+ */
+declare const afterCanonicalCompositionSettles: (view: EditorView, retry: () => void) => (() => void);
 //#endregion
-export { CANONICAL_INPUT_TIMER_OWNER, setCanonicalInputTimer };
+export { CANONICAL_COMPOSITION_FLUSH_DELAY_MS, CANONICAL_INPUT_TIMER_OWNER, afterCanonicalCompositionSettles, setCanonicalInputTimer };

package/dist/controller/canonicalInputTimer.js

@@ -1,11 +1,34 @@
 //#region src/controller/canonicalInputTimer.ts
 /** Shared by timer producers and browser diagnostics, regardless of bundling. */
 const CANONICAL_INPUT_TIMER_OWNER = "folio.canonical-input-timer";
+/** Delay after native composition end before the canonical session settles it. */
+const CANONICAL_COMPOSITION_FLUSH_DELAY_MS = 25;
 /** Mark the scheduled wrapper, never the caller's potentially shared callback. */
 const setCanonicalInputTimer = (callback, delay) => {
 	const ownedCallback = () => callback();
 	Object.defineProperty(ownedCallback, Symbol.for(CANONICAL_INPUT_TIMER_OWNER), { value: true });
 	return setTimeout(ownedCallback, delay);
 };
+/**
+* Run `retry` once the view's canonical composition has settled. The session
+* settles on an equal-delay timer armed at native composition end, so a retry
+* armed at or after that point runs after it. Returns a disposer.
+*/
+const afterCanonicalCompositionSettles = (view, retry) => {
+	let timer;
+	const schedule = () => {
+		timer = setCanonicalInputTimer(retry, 25);
+	};
+	const onEnd = () => {
+		view.dom.removeEventListener("compositionend", onEnd);
+		schedule();
+	};
+	if (view.composing) view.dom.addEventListener("compositionend", onEnd);
+	else schedule();
+	return () => {
+		view.dom.removeEventListener("compositionend", onEnd);
+		if (timer !== void 0) clearTimeout(timer);
+	};
+};
 //#endregion
-export { CANONICAL_INPUT_TIMER_OWNER, setCanonicalInputTimer };
+export { CANONICAL_COMPOSITION_FLUSH_DELAY_MS, CANONICAL_INPUT_TIMER_OWNER, afterCanonicalCompositionSettles, setCanonicalInputTimer };

package/dist/controller/canonicalPublicOperations.d.ts

@@ -15,8 +15,8 @@ declare const CANONICAL_PUBLIC_OPERATION_DISPOSITIONS: {
   readonly insertAfterBlock: "publicOps.unsupportedInline";
   readonly insertBeforeBlock: "publicOps.unsupportedInline";
   readonly deleteBlock: "publicOps.unsupportedInline";
-  readonly commentOnBlock: "publicOps.comments";
-  readonly commentOnRange: "publicOps.comments";
+  readonly commentOnBlock: "compile";
+  readonly commentOnRange: "compile";
   readonly insertTable: "publicOps.tableProjection";
   readonly insertSignatureTable: "publicOps.tableProjection";
   readonly deleteTable: "publicOps.tableProjection";

package/dist/controller/canonicalPublicOperations.js

@@ -6,9 +6,10 @@ 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 { canonicalCommentBody, compileCanonicalComments } from "./canonicalComments.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";
+import { OP_STORIES, applyDocumentOps, compileEditorIntent, createEditorIntentIdAllocator, documentStories, findStoryBody, freshCommentId, paragraphLength } 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. */
@@ -23,8 +24,8 @@ const CANONICAL_PUBLIC_OPERATION_DISPOSITIONS = {
 	insertAfterBlock: CANONICAL_GAP.publicUnsupportedInline,
 	insertBeforeBlock: CANONICAL_GAP.publicUnsupportedInline,
 	deleteBlock: CANONICAL_GAP.publicUnsupportedInline,
-	commentOnBlock: CANONICAL_GAP.publicComments,
-	commentOnRange: CANONICAL_GAP.publicComments,
+	commentOnBlock: "compile",
+	commentOnRange: "compile",
 	insertTable: CANONICAL_GAP.publicTableProjection,
 	insertSignatureTable: CANONICAL_GAP.publicTableProjection,
 	deleteTable: CANONICAL_GAP.publicTableProjection,
@@ -35,6 +36,21 @@ const CANONICAL_PUBLIC_OPERATION_DISPOSITIONS = {
 	mergeTableCells: CANONICAL_GAP.publicTableProjection,
 	splitTableCell: CANONICAL_GAP.publicTableProjection
 };
+const resolveComment = ({ operation, from, to }) => {
+	if ("comment" in operation && operation.comment !== void 0) return {
+		type: "commented",
+		operation,
+		comment: {
+			text: operation.comment.text,
+			from,
+			to
+		}
+	};
+	return {
+		type: "plain",
+		operation
+	};
+};
 const compilePublicIntents = ({ document, intents, mode, author, date, nextRevisionId, allocate }) => {
 	const ops = [];
 	const revisions = [];
@@ -183,8 +199,8 @@ var CanonicalPublicOperations = class {
 				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 });
+			if (disposition !== "compile") {
+				refusals.set(operation.id, { gap: disposition });
 				skip(operation.id, "unsupportedBlock");
 				continue;
 			}
@@ -217,7 +233,8 @@ var CanonicalPublicOperations = class {
 		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) {
+		for (const resolvedOperation of resolved) {
+			const { operation, intents, normalizations: adjustments } = resolvedOperation;
 			const compiled = compilePublicIntents({
 				document,
 				intents,
@@ -232,18 +249,71 @@ var CanonicalPublicOperations = class {
 				skip(operation.id, "unsupportedBlock", compiled.error.message);
 				continue;
 			}
-			if (compiled.value.ops.length === 0) {
+			let nextDocument = compiled.value.document;
+			const operationOps = [...compiled.value.ops];
+			let commentId;
+			switch (resolvedOperation.type) {
+				case "plain": break;
+				case "commented": {
+					const { comment } = resolvedOperation;
+					const id = freshCommentId(nextDocument);
+					const before = findStoryBody(document, story)?.content.find((block) => block.type === "paragraph" && block.paraId === comment.from.blockId);
+					const after = findStoryBody(nextDocument, story)?.content.find((block) => block.type === "paragraph" && block.paraId === comment.from.blockId);
+					if (id.isErr() || before?.type !== "paragraph" || after?.type !== "paragraph") {
+						refusals.set(operation.id, { gap: CANONICAL_GAP.publicComments });
+						skip(operation.id, "unsupportedBlock", id.isErr() ? id.error.message : "The comment anchor no longer exists.");
+						continue;
+					}
+					const to = {
+						...comment.to,
+						offset: comment.to.offset + paragraphLength(after) - paragraphLength(before)
+					};
+					const commented = compileCanonicalComments({
+						document: nextDocument,
+						command: {
+							type: "create",
+							comment: {
+								id: id.value,
+								author: options.author ?? "AI",
+								date,
+								done: false,
+								content: canonicalCommentBody(nextDocument, comment.text)
+							},
+							anchor: to.offset === comment.from.offset ? {
+								kind: "point",
+								at: comment.from
+							} : {
+								kind: "range",
+								from: comment.from,
+								to
+							}
+						}
+					});
+					if (commented.isErr()) {
+						refusals.set(operation.id, { gap: CANONICAL_GAP.publicComments });
+						skip(operation.id, "unsupportedBlock", commented.error.message);
+						continue;
+					}
+					nextDocument = commented.value.document;
+					operationOps.push(...commented.value.ops);
+					commentId = id.value;
+					break;
+				}
+				default: panic(`Unknown resolved operation ${resolvedOperation}`);
+			}
+			if (operationOps.length === 0) {
 				skip(operation.id, "noopOperation");
 				continue;
 			}
 			normalizations.push(...adjustments);
-			document = compiled.value.document;
-			ops.push(...compiled.value.ops);
-			nextRevisionId = compiled.value.nextRevisionId;
+			document = nextDocument;
+			ops.push(...operationOps);
+			nextRevisionId = Math.max(compiled.value.nextRevisionId, (commentId ?? -1) + 1);
 			const revisionIds = compiled.value.revisions;
 			const revisionId = revisionIds.at(0);
 			appliedById.set(operation.id, {
 				id: operation.id,
+				...commentId === void 0 ? {} : { commentId },
 				...revisionId === void 0 ? {} : {
 					revisionId,
 					revisionIds
@@ -328,17 +398,18 @@ var CanonicalPublicOperations = class {
 			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;
+			case "mergeBlockWithNext":
+			case "commentOnRange":
+			case "commentOnBlock": 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 blockId = operation.type === "replaceRange" || operation.type === "formatRange" || operation.type === "commentOnRange" ? 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");
@@ -364,8 +435,17 @@ var CanonicalPublicOperations = class {
 				end = start + operation.find.length;
 				text = operation.replace;
 				break;
+			case "commentOnBlock":
+				if (operation.quote !== void 0) {
+					start = clean.text.indexOf(operation.quote);
+					if (start < 0) return refusal("missingFind");
+					if (clean.text.indexOf(operation.quote, start + 1) >= 0) return refusal("ambiguousFind");
+					end = start + operation.quote.length;
+				}
+				break;
 			case "replaceRange":
 			case "formatRange":
+			case "commentOnRange":
 				start = operation.range.startOffset;
 				end = operation.range.endOffset;
 				if (hashFolioAIBlockText(clean.text.slice(start, end)) !== operation.range.selectedTextHash) return refusal("staleRange");
@@ -401,7 +481,19 @@ var CanonicalPublicOperations = class {
 		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");
+		const resolvedComment = resolveComment({
+			operation,
+			from: from.value,
+			to: to.value
+		});
+		if (operation.type === "commentOnBlock" || operation.type === "commentOnRange") return Result.ok({
+			...resolvedComment,
+			intents: [],
+			normalizations: [],
+			from: range.from,
+			to: range.to
+		});
+		if (resolvedComment.type === "plain" && 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":
@@ -544,7 +636,7 @@ var CanonicalPublicOperations = class {
 		if (structural) claimedTo = paragraph.start + paragraph.node.content.size;
 		if (nextParagraph) claimedTo = nextParagraph.start + nextParagraph.node.content.size;
 		return Result.ok({
-			operation,
+			...resolvedComment,
 			intents,
 			normalizations,
 			from: structural ? paragraph.start : range.from,

package/dist/controller/canonicalSelection.d.ts

@@ -0,0 +1,18 @@
+import { CanonicalProjection, CanonicalSelection } from "./canonicalSession.js";
+import { Transaction } from "prosemirror-state";
+//#region src/controller/canonicalSelection.d.ts
+type RestoreCanonicalSelectionOptions = {
+  transaction: Transaction;
+  projection: CanonicalProjection;
+  selection: CanonicalSelection;
+  unavailable: {
+    type: "refuse";
+  } | {
+    type: "near";
+    anchor: number;
+  };
+};
+/** Restore the admitted selection kind after a canonical projection changes. */
+declare const restoreCanonicalSelection: ({ transaction, projection, selection, unavailable }: RestoreCanonicalSelectionOptions) => boolean;
+//#endregion
+export { restoreCanonicalSelection };

package/dist/controller/canonicalSelection.js

@@ -0,0 +1,32 @@
+import { panic } from "better-result";
+import { AllSelection, TextSelection } from "prosemirror-state";
+//#region src/controller/canonicalSelection.ts
+/** Restore the admitted selection kind after a canonical projection changes. */
+const restoreCanonicalSelection = ({ transaction, projection, selection, unavailable }) => {
+	switch (selection.type) {
+		case "all":
+			transaction.setSelection(new AllSelection(transaction.doc));
+			return true;
+		case "text": {
+			const anchor = projection.positionAt(selection.anchor);
+			const head = projection.positionAt(selection.head);
+			if (anchor.isOk() && head.isOk()) {
+				transaction.setSelection(TextSelection.create(transaction.doc, anchor.value, head.value));
+				return true;
+			}
+			switch (unavailable.type) {
+				case "refuse": return false;
+				case "near":
+					transaction.setSelection(TextSelection.near(transaction.doc.resolve(Math.min(unavailable.anchor, transaction.doc.content.size))));
+					return true;
+				default: return panic(`Unknown selection restoration policy: ${unavailable}`);
+			}
+		}
+		default: {
+			const exhaustive = selection.type;
+			return panic(`Unknown canonical selection type: ${exhaustive}`);
+		}
+	}
+};
+//#endregion
+export { restoreCanonicalSelection };

package/dist/controller/canonicalSession.d.ts

@@ -59,6 +59,7 @@ type CanonicalCommit = {
   document: document_d_exports.Document;
   projection: CanonicalProjection;
   bodyProjection: CanonicalProjection;
+  selection: CanonicalSelection;
   touched: TouchedBlocks;
   version: number;
   origin: CanonicalOrigin;
@@ -116,6 +117,8 @@ declare class CanonicalSession {
   private readonly undone;
   private readonly styles;
   constructor({ document, projection, styles }: CanonicalSessionSeedOptions);
+  /** Render only the committed comment projection while provisional IME blocks document snapshots. */
+  getCommittedComments(): import("@stll/docx-core/model").Comment[];
   setMode(mode: CanonicalSessionMode): void;
   hasStyle(styleId: string): boolean;
   private advanceBlockId;