@stll/folio-core 0.55.0 → 0.57.0

package/dist/controller/canonicalSession.js

@@ -1,31 +1,52 @@
 import { splitsGraphemeCluster, splitsSurrogatePair } from "../ai-edits/character-boundaries.js";
+import { rangedCommentIds, visitCommentMarkers } from "../docx/commentAnchorIndex.js";
 import { cloneDocumentWithParagraphPropertySources, copyDocumentParagraphPropertySourceContract, copyParagraphPropertySource } from "../docx/paragraphPropertySource.js";
-import { footnoteToProseDoc, headerFooterToProseDoc, toProseDoc } from "../prosemirror/conversion/toProseDoc.js";
+import { canonicalSelectionRange } from "../prosemirror/canonicalSelectionRange.js";
+import { collectPairedBookmarkIds, footnoteToProseDoc, headerFooterToProseDoc, toProseDoc } from "../prosemirror/conversion/toProseDoc.js";
 import { markPackageChange } from "../prosemirror/extensions/features/ParagraphChangeTrackerExtension.js";
 import { runFormattingPatchFromMarks } from "../prosemirror/runFormattingFromMarks.js";
+import { CANONICAL_GAP } from "../types/canonicalCapabilities.js";
+import { canonicalInlineSourceIssue, canonicalNativeCells, projectCanonicalInline } from "./canonicalInlineProjection.js";
+import { restoreCanonicalSelection } from "./canonicalSelection.js";
+import { mapTocSelection } from "./canonicalTocSelection.js";
 import { Result, TaggedError, panic } from "better-result";
 import { hasIllegalXmlCharacters } from "@stll/docx-core";
 import { Fragment } from "prosemirror-model";
-import { DOCUMENT_OP_TYPES, OP_STORIES, applyDocumentOps, combineEdits, compileEditorIntent, createEditorIntentIdAllocator, documentStories, editorParagraphGroups, findStoryBody, normalizeForOps, packageParagraphIds, sameStory, validateOpsDocument } from "@stll/docx-core/ops";
-import { TextSelection } from "prosemirror-state";
+import { DOCUMENT_OP_TYPES, OP_STORIES, applyDocumentOps, combineEdits, commentDocumentIssue, compileEditorIntent, createEditorIntentIdAllocator, documentStories, editorParagraphGroups, findStoryBody, normalizeForOps, packageParagraphIds, sameStory, validateOpsDocument } from "@stll/docx-core/ops";
+import { AllSelection, TextSelection } from "prosemirror-state";
 //#region src/controller/canonicalSession.ts
 var CanonicalSessionError = class extends TaggedError("CanonicalSessionError") {};
 const refuse = (message) => Result.err(new CanonicalSessionError({
+	gap: CANONICAL_GAP.dispatch,
 	message,
 	reason: "refused"
 }));
 const noChange = (message) => Result.err(new CanonicalSessionError({
+	gap: CANONICAL_GAP.dispatch,
 	message,
 	reason: "noChange"
 }));
+const COMMENT_OPERATION_TYPES = /* @__PURE__ */ new Set([
+	DOCUMENT_OP_TYPES.CREATE_COMMENT,
+	DOCUMENT_OP_TYPES.UPDATE_COMMENT_CONTENT,
+	DOCUMENT_OP_TYPES.SET_COMMENT_RESOLUTION,
+	DOCUMENT_OP_TYPES.DELETE_COMMENT,
+	DOCUMENT_OP_TYPES.RESTORE_COMMENT_STATE
+]);
 const operationChangesPackage = (op) => {
 	switch (op.type) {
+		case DOCUMENT_OP_TYPES.CREATE_COMMENT:
+		case DOCUMENT_OP_TYPES.UPDATE_COMMENT_CONTENT:
+		case DOCUMENT_OP_TYPES.SET_COMMENT_RESOLUTION:
+		case DOCUMENT_OP_TYPES.DELETE_COMMENT:
+		case DOCUMENT_OP_TYPES.RESTORE_COMMENT_STATE:
 		case DOCUMENT_OP_TYPES.CREATE_HEADER_FOOTER:
 		case DOCUMENT_OP_TYPES.REMOVE_HEADER_FOOTER:
 		case DOCUMENT_OP_TYPES.ADD_NOTE:
 		case DOCUMENT_OP_TYPES.REMOVE_NOTE:
 		case DOCUMENT_OP_TYPES.SET_SECTION_PROPS:
 		case DOCUMENT_OP_TYPES.RESTORE_STORY_PARTS:
+		case DOCUMENT_OP_TYPES.SET_PACKAGE_RESOURCES:
 		case DOCUMENT_OP_TYPES.CREATE_NUMBERING_INSTANCE:
 		case DOCUMENT_OP_TYPES.DELETE_NUMBERING_INSTANCE:
 		case DOCUMENT_OP_TYPES.SET_SECTION_ENDPOINT: return true;
@@ -36,14 +57,70 @@ const operationChangesPackage = (op) => {
 			return op;
 	}
 };
+const operationChangesStructure = (op) => {
+	switch (op.type) {
+		case DOCUMENT_OP_TYPES.DELETE_BLOCKS:
+		case DOCUMENT_OP_TYPES.INSERT_BLOCKS:
+		case DOCUMENT_OP_TYPES.SPLIT_BLOCK:
+		case DOCUMENT_OP_TYPES.JOIN_BLOCKS:
+		case DOCUMENT_OP_TYPES.REPLACE_BLOCKS:
+		case DOCUMENT_OP_TYPES.INSERT_TABLE:
+		case DOCUMENT_OP_TYPES.DELETE_TABLE:
+		case DOCUMENT_OP_TYPES.SET_CONTAINER_BLOCKS:
+		case DOCUMENT_OP_TYPES.INSERT_ROW:
+		case DOCUMENT_OP_TYPES.DELETE_ROW:
+		case DOCUMENT_OP_TYPES.SET_TABLE_ROWS:
+		case DOCUMENT_OP_TYPES.INSERT_COLUMN:
+		case DOCUMENT_OP_TYPES.DELETE_COLUMN:
+		case DOCUMENT_OP_TYPES.MERGE_CELLS:
+		case DOCUMENT_OP_TYPES.SPLIT_CELL:
+		case DOCUMENT_OP_TYPES.SET_TABLE:
+		case DOCUMENT_OP_TYPES.RESOLVE_REVISION: return true;
+		case DOCUMENT_OP_TYPES.CREATE_HEADER_FOOTER:
+		case DOCUMENT_OP_TYPES.REMOVE_HEADER_FOOTER:
+		case DOCUMENT_OP_TYPES.ADD_NOTE:
+		case DOCUMENT_OP_TYPES.REMOVE_NOTE:
+		case DOCUMENT_OP_TYPES.SET_SECTION_PROPS:
+		case DOCUMENT_OP_TYPES.RESTORE_STORY_PARTS:
+		case DOCUMENT_OP_TYPES.SET_PACKAGE_RESOURCES:
+		case DOCUMENT_OP_TYPES.CREATE_NUMBERING_INSTANCE:
+		case DOCUMENT_OP_TYPES.DELETE_NUMBERING_INSTANCE:
+		case DOCUMENT_OP_TYPES.SET_SECTION_ENDPOINT: return true;
+		case DOCUMENT_OP_TYPES.INSERT_TEXT:
+		case DOCUMENT_OP_TYPES.INSERT_CONTENT:
+		case DOCUMENT_OP_TYPES.DELETE_RANGE:
+		case DOCUMENT_OP_TYPES.SPLIT_INLINE:
+		case DOCUMENT_OP_TYPES.JOIN_INLINE:
+		case DOCUMENT_OP_TYPES.SET_RUN_PROPS:
+		case DOCUMENT_OP_TYPES.SET_PARAGRAPH_PROPS:
+		case DOCUMENT_OP_TYPES.SET_PARAGRAPH_REVIEW:
+		case DOCUMENT_OP_TYPES.REPLACE_INLINE:
+		case DOCUMENT_OP_TYPES.SET_TABLE_GRID:
+		case DOCUMENT_OP_TYPES.SET_CELL_PROPS:
+		case DOCUMENT_OP_TYPES.SET_ROW_PROPS:
+		case DOCUMENT_OP_TYPES.SET_TABLE_PROPS:
+		case DOCUMENT_OP_TYPES.CREATE_COMMENT:
+		case DOCUMENT_OP_TYPES.UPDATE_COMMENT_CONTENT:
+		case DOCUMENT_OP_TYPES.SET_COMMENT_RESOLUTION:
+		case DOCUMENT_OP_TYPES.DELETE_COMMENT:
+		case DOCUMENT_OP_TYPES.RESTORE_COMMENT_STATE: return false;
+		default: return op;
+	}
+};
 const operationChangesBodyProjection = (op) => {
 	switch (op.type) {
+		case DOCUMENT_OP_TYPES.CREATE_COMMENT:
+		case DOCUMENT_OP_TYPES.UPDATE_COMMENT_CONTENT:
+		case DOCUMENT_OP_TYPES.SET_COMMENT_RESOLUTION:
+		case DOCUMENT_OP_TYPES.DELETE_COMMENT:
+		case DOCUMENT_OP_TYPES.RESTORE_COMMENT_STATE:
 		case DOCUMENT_OP_TYPES.CREATE_HEADER_FOOTER:
 		case DOCUMENT_OP_TYPES.REMOVE_HEADER_FOOTER:
 		case DOCUMENT_OP_TYPES.ADD_NOTE:
 		case DOCUMENT_OP_TYPES.REMOVE_NOTE:
 		case DOCUMENT_OP_TYPES.SET_SECTION_PROPS:
 		case DOCUMENT_OP_TYPES.RESTORE_STORY_PARTS:
+		case DOCUMENT_OP_TYPES.SET_PACKAGE_RESOURCES:
 		case DOCUMENT_OP_TYPES.CREATE_NUMBERING_INSTANCE:
 		case DOCUMENT_OP_TYPES.DELETE_NUMBERING_INSTANCE:
 		case DOCUMENT_OP_TYPES.SET_SECTION_ENDPOINT: return true;
@@ -55,7 +132,7 @@ const operationChangesBodyProjection = (op) => {
 	}
 };
 const CANONICAL_PROJECTION_META = "folioCanonicalProjection";
-/** 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. */
 var CanonicalProjection = class {
 	doc;
 	story;
@@ -72,15 +149,16 @@ var CanonicalProjection = class {
 		const paragraph = this.paragraphs.find(({ start, node }) => position >= start && position <= start + node.content.size);
 		if (paragraph === void 0) return refuse("The input is outside a plain paragraph.");
 		const relative = position - paragraph.start;
-		const offset = paragraph.boundaries.findIndex((gaps) => gaps.includes(relative));
-		if (offset < 0) return refuse("The input splits a note reference.");
+		const offset = paragraph.boundaries.findIndex((gaps) => gaps.some((gap) => gap.position === relative));
+		if (offset < 0) return refuse("The input splits an indivisible inline element.");
 		if (splitsSurrogatePair(paragraph.text, offset)) return refuse("The input would split a surrogate pair.");
 		const gaps = paragraph.boundaries.at(offset) ?? panic("Missing canonical boundary");
+		const gap = gaps.find((entry) => entry.position === relative) ?? panic("Missing canonical native gap");
 		return Result.ok({
 			story: this.story,
 			blockId: paragraph.blockId,
 			offset,
-			...gaps.length > 1 ? { zeroWidthBefore: gaps.indexOf(relative) } : {}
+			...gaps.length > 1 || gap.zeroWidthBefore > 0 ? { zeroWidthBefore: gap.zeroWidthBefore } : {}
 		});
 	}
 	inputAddressAt(position) {
@@ -88,30 +166,32 @@ var CanonicalProjection = class {
 		if (address.isErr()) return address;
 		const paragraph = this.paragraph(address.value.blockId);
 		if (paragraph === void 0) panic("Input lost its paragraph.");
-		let offset = address.value.offset;
+		let destination = position;
 		paragraph.node.forEach((node, start) => {
-			if (node.marks.some((mark) => mark.type.name === "deletion") && offset > start && offset < start + node.nodeSize) offset = start + node.nodeSize;
-		});
-		return Result.ok({
-			...address.value,
-			offset
+			if (node.marks.some((mark) => mark.type.name === "deletion") && position > paragraph.start + start && position < paragraph.start + start + node.nodeSize) destination = paragraph.start + start + node.nodeSize;
 		});
+		return destination === position ? address : this.addressAt(destination);
 	}
 	positionAt(address) {
 		const paragraph = this.paragraph(address.blockId);
 		if (!sameStory(address.story, this.story) || paragraph === void 0 || !Number.isInteger(address.offset) || address.offset < 0 || address.offset > paragraph.text.length || splitsSurrogatePair(paragraph.text, address.offset)) return refuse("The canonical selection is outside a plain paragraph.");
 		const gaps = paragraph.boundaries.at(address.offset) ?? panic("Missing canonical boundary");
-		const gapIndex = address.zeroWidthBefore ?? gaps.length - 1;
-		if (!Number.isInteger(gapIndex) || gapIndex < 0 || gapIndex >= gaps.length) return refuse("The canonical selection is outside a paragraph gap.");
-		return Result.ok(paragraph.start + (gaps.at(gapIndex) ?? panic("Missing canonical gap")));
+		const ordinal = address.zeroWidthBefore ?? (gaps.at(-1) ?? panic("Missing canonical gap")).zeroWidthBefore;
+		const gap = gaps.find(({ zeroWidthBefore }) => zeroWidthBefore === ordinal);
+		if (!Number.isInteger(ordinal) || ordinal < 0 || ordinal > (gaps.at(-1)?.zeroWidthBefore ?? 0)) return refuse("The canonical selection is outside a paragraph gap.");
+		if (gap === void 0) return refuse("This source gap is inside a collapsed or erased inline boundary and has no editor position.");
+		return Result.ok(paragraph.start + gap.position);
 	}
 	selectionAt(state) {
-		if (!(state.selection instanceof TextSelection)) return refuse("Canonical input requires a text selection.");
-		const anchor = this.addressAt(state.selection.anchor);
+		if (!(state.selection instanceof TextSelection) && !(state.selection instanceof AllSelection)) return refuse("Canonical input requires a text selection.");
+		const range = canonicalSelectionRange(state);
+		const type = state.selection instanceof AllSelection ? "all" : "text";
+		const anchor = this.addressAt(type === "all" ? range.from : state.selection.anchor);
 		if (anchor.isErr()) return anchor;
-		const head = this.addressAt(state.selection.head);
+		const head = this.addressAt(type === "all" ? range.to : state.selection.head);
 		if (head.isErr()) return head;
 		return Result.ok({
+			type,
 			anchor: anchor.value,
 			head: head.value
 		});
@@ -162,31 +242,31 @@ const preservePropertySources = ({ target, source, stories = documentStories(sou
 	}
 	copyDocumentParagraphPropertySourceContract(target, source);
 };
-const supportsTextContent = (content) => content.every((item) => {
-	switch (item.type) {
-		case "run": return item.content.every((child) => child.type === "text" && !hasIllegalXmlCharacters(child.text) && !/[\t\r\n]/u.test(child.text) || child.type === "noteMarker" || child.type === "footnoteRef" || child.type === "endnoteRef" || child.type === "tab" || child.type === "break");
-		case "insertion":
-		case "deletion": return supportsTextContent(item.content);
-		default: return false;
-	}
-});
-const supportsSeed = (document, stories = documentStories(document)) => {
-	if ((document.package.document.comments?.length ?? 0) > 0) return false;
-	return stories.every((story) => {
+const unsupportedSeedReason = (document, stories = documentStories(document)) => {
+	const commentIssue = commentDocumentIssue(document, "all");
+	if (commentIssue !== void 0) return commentIssue;
+	for (const story of stories) {
 		const body = findStoryBody(document, story);
 		if (story !== OP_STORIES.MAIN && (story.kind === "footnote" || story.kind === "endnote")) {
 			const note = (story.kind === "footnote" ? document.package.footnotes : document.package.endnotes)?.find(({ id }) => id === story.id);
-			if (note?.noteType !== void 0 && note.noteType !== "normal") return true;
+			if (note?.noteType !== void 0 && note.noteType !== "normal") continue;
 		}
 		const content = body?.content;
-		return content !== void 0 && content.length > 0 && content.every((paragraph) => paragraph.type === "paragraph" && paragraph.reviewCarrier === void 0 && supportsTextContent(paragraph.content));
-	});
+		if (!content || content.length === 0) return "Canonical sessions require a nonempty paragraph story.";
+		for (const paragraph of content) {
+			if (paragraph.type !== "paragraph" || paragraph.reviewCarrier !== void 0) return "Canonical sessions currently require plain paragraphs and supported inline atoms.";
+			const issue = canonicalInlineSourceIssue(paragraph.content);
+			if (issue !== null) return issue;
+		}
+	}
+	return null;
 };
 const project = ({ document, styles, story = OP_STORIES.MAIN }) => {
 	const body = findStoryBody(document, story);
 	if (!body) return refuse("The canonical story no longer exists.");
+	const currentStyles = Object.hasOwn(document.package, "styles") ? document.package.styles : styles;
 	const options = {
-		...styles == null ? {} : { styles },
+		...currentStyles == null ? {} : { styles: currentStyles },
 		...document.package.theme === void 0 ? {} : { theme: document.package.theme }
 	};
 	const converted = Result.try({
@@ -196,70 +276,66 @@ const project = ({ document, styles, story = OP_STORIES.MAIN }) => {
 			return footnoteToProseDoc(body.content, options);
 		},
 		catch: (cause) => new CanonicalSessionError({
+			gap: CANONICAL_GAP.dispatch,
 			reason: "refused",
 			message: `Canonical projection failed: ${cause instanceof Error ? cause.message : String(cause)}`
 		})
 	});
 	if (converted.isErr()) return converted;
+	const pairedBookmarkIds = collectPairedBookmarkIds(body.content);
+	const commentContext = {
+		rangedIds: rangedCommentIds(body.content),
+		pointIds: /* @__PURE__ */ new Set(),
+		openIds: /* @__PURE__ */ new Set()
+	};
+	visitCommentMarkers(body.content, ({ item }) => {
+		if (item.type === "commentReference" && !commentContext.rangedIds.has(item.id)) commentContext.pointIds.add(item.id);
+	});
 	const paragraphs = [];
 	let failure;
 	converted.value.forEach((node, offset, index) => {
 		const source = body.content.at(index);
 		if (source?.type !== "paragraph" || source.paraId === void 0) {
 			failure = new CanonicalSessionError({
+				gap: CANONICAL_GAP.dispatch,
 				reason: "refused",
 				message: "The projection changed paragraph structure."
 			});
 			return;
 		}
-		let text = "";
-		let renderedText = "";
-		let renderedSize = 0;
-		const boundaries = [[0]];
-		const appendContent = (content) => {
-			for (const run of content) {
-				if (run.type === "insertion" || run.type === "deletion") {
-					appendContent(run.content);
-					continue;
-				}
-				if (run.type !== "run") panic("Canonical projection encountered unsupported content");
-				for (const child of run.content) if (child.type === "text") for (const unit of child.text.split("")) {
-					text += unit;
-					renderedText += unit;
-					renderedSize += 1;
-					boundaries.push([renderedSize]);
-				}
-				else if (child.type === "footnoteRef" || child.type === "endnoteRef") {
-					text += "";
-					renderedText += String(child.id);
-					renderedSize += String(child.id).length;
-					boundaries.push([renderedSize]);
-				} else if (child.type === "tab" || child.type === "break") {
-					text += "";
-					renderedSize += 1;
-					boundaries.push([renderedSize]);
-				} else if (child.type === "noteMarker") {
-					renderedSize += 1;
-					(boundaries.at(-1) ?? panic("Missing canonical note gap")).push(renderedSize);
-				}
-			}
-		};
-		appendContent(source.content);
-		if (node.type.name !== "paragraph" || node.attrs["paraId"] !== source.paraId || node.textContent !== renderedText || node.content.size !== renderedSize) {
+		if (node.type.name !== "paragraph" || node.attrs["paraId"] !== source.paraId) {
+			failure = new CanonicalSessionError({
+				gap: CANONICAL_GAP.dispatch,
+				reason: "refused",
+				message: "The projection changed paragraph structure."
+			});
+			return;
+		}
+		const inline = projectCanonicalInline({
+			source,
+			paragraph: node,
+			pairedBookmarkIds,
+			commentContext
+		});
+		if (inline.isErr()) {
 			failure = new CanonicalSessionError({
+				gap: CANONICAL_GAP.dispatch,
 				reason: "refused",
-				message: "The paragraph cannot be projected as plain text."
+				message: inline.error.message
 			});
 			return;
 		}
 		paragraphs.push({
 			blockId: source.paraId,
 			start: offset + 1,
-			text,
-			boundaries,
+			...inline.value,
 			node,
 			source
 		});
+		visitCommentMarkers([source], ({ item }) => {
+			if (item.type === "commentRangeStart") commentContext.openIds.add(item.id);
+			if (item.type === "commentRangeEnd") commentContext.openIds.delete(item.id);
+		});
 	});
 	if (failure !== void 0) return Result.err(failure);
 	if (paragraphs.length !== body.content.length) return refuse("The projection changed paragraph structure.");
@@ -271,9 +347,15 @@ const project = ({ document, styles, story = OP_STORIES.MAIN }) => {
 };
 const intentStory = (intent) => {
 	switch (intent.type) {
+		case "setHyperlink":
+		case "removeHyperlink":
+		case "insertHyperlink":
+		case "replaceFragment":
+		case "moveFragment":
 		case "replaceText":
 		case "formatRun":
 		case "insertAtom": return intent.from.story;
+		case "generateTOC":
 		case "splitParagraph":
 		case "formatParagraph": return intent.at.story;
 		case "setList": return intent.items.at(0)?.at.story ?? panic("A list intent requires a paragraph.");
@@ -284,14 +366,14 @@ const intentStory = (intent) => {
 };
 const UNDO_GROUP_WINDOW_MS = 500;
 const samePosition = (left, right) => sameStory(left.story, right.story) && left.blockId === right.blockId && left.offset === right.offset && (left.zeroWidthBefore ?? 0) === (right.zeroWidthBefore ?? 0);
-const sameSelection = (left, right) => samePosition(left.anchor, right.anchor) && samePosition(left.head, right.head);
+const sameSelection = (left, right) => left.type === right.type && samePosition(left.anchor, right.anchor) && samePosition(left.head, right.head);
 const continuesGroup = (previous, next) => {
 	switch (next.semantic) {
 		case "typing":
 		case "deleteBackward":
 		case "deleteForward": return previous.grouping === "run" && next.grouping === "run" && previous.semantic === next.semantic && previous.boundary === next.boundary && next.time >= previous.time && next.time - previous.time <= UNDO_GROUP_WINDOW_MS && sameSelection(previous.postSelection, next.preSelection) && samePosition(next.preSelection.anchor, next.preSelection.head);
+		case "composition": return next.grouping === "compositionCorrection" && previous.semantic === "composition" && previous.boundary === next.boundary && sameSelection(previous.postSelection, next.preSelection);
 		case "paste":
-		case "composition":
 		case "replacement":
 		case "structure": return false;
 		default: {
@@ -312,6 +394,7 @@ const publishCanonicalProjection = ({ state, commit, session }) => {
 	const applied = Result.try({
 		try: () => state.applyTransaction(commit.transaction),
 		catch: (cause) => new CanonicalSessionError({
+			gap: CANONICAL_GAP.dispatch,
 			reason: "refused",
 			message: `Canonical plugin staging failed: ${cause instanceof Error ? cause.message : String(cause)}`
 		})
@@ -336,7 +419,10 @@ const storyProjectionKey = (story) => {
 var CanonicalSession = class {
 	currentDocument;
 	currentProjection;
+	sourceBlockIds;
 	currentVersion = 0;
+	saveTouched = /* @__PURE__ */ new Set();
+	saveStructure = "stable";
 	allocateIntentIds = createEditorIntentIdAllocator();
 	mode = { type: "editing" };
 	allocatedBlockIds = /* @__PURE__ */ new Set();
@@ -352,11 +438,16 @@ var CanonicalSession = class {
 	constructor({ document, projection, styles }) {
 		this.currentDocument = document;
 		this.currentProjection = projection;
+		this.sourceBlockIds = new Set(packageParagraphIds(document.package));
 		for (const blockId of packageParagraphIds(document.package)) this.allocatedBlockIds.add(blockId.toUpperCase());
 		this.advanceBlockId();
 		this.styles = styles == null ? styles : structuredClone(styles);
 		this.rememberSources(document);
 	}
+	/** Render only the committed comment projection while provisional IME blocks document snapshots. */
+	getCommittedComments() {
+		return structuredClone(this.currentDocument.package.document.comments ?? []);
+	}
 	setMode(mode) {
 		if (this.mode.type !== mode.type || this.mode.type === "suggesting" && mode.type === "suggesting" && this.mode.author !== mode.author) this.breakUndoGroup();
 		this.mode = mode.type === "editing" ? { type: "editing" } : {
@@ -375,13 +466,18 @@ var CanonicalSession = class {
 		return Result.ok(this.nextBlockId.toString(16).padStart(8, "0").toUpperCase());
 	}
 	intentMode(document, intent) {
-		if (this.mode.type === "editing" && !this.intentNeedsIdentityIds(document, intent)) return { type: "editing" };
+		if (this.mode.type === "editing" && !this.intentNeedsIdentityIds(document, intent)) return {
+			type: "editing",
+			reservedBlockIds: this.allocatedBlockIds
+		};
 		const ids = this.allocateIntentIds(document, intent);
 		return this.mode.type === "editing" ? {
 			type: "editing",
-			newIds: ids.newIds
+			newIds: ids.newIds,
+			reservedBlockIds: this.allocatedBlockIds
 		} : {
 			type: "suggesting",
+			reservedBlockIds: this.allocatedBlockIds,
 			revision: {
 				id: ids.revisionId,
 				author: this.mode.author,
@@ -394,8 +490,14 @@ var CanonicalSession = class {
 		let blockIds;
 		switch (intent.type) {
 			case "table": return true;
+			case "generateTOC":
 			case "setList":
 			case "formatParagraph": return false;
+			case "setHyperlink":
+			case "removeHyperlink":
+			case "insertHyperlink":
+			case "replaceFragment":
+			case "moveFragment": return true;
 			case "replaceText":
 			case "insertAtom":
 			case "formatRun":
@@ -428,11 +530,26 @@ var CanonicalSession = class {
 	}
 	get document() {
 		if (this.isComposing) throw new CanonicalSessionError({
+			gap: CANONICAL_GAP.dispatch,
 			reason: "refused",
 			message: "Composition must finish before taking a snapshot."
 		});
 		return this.currentDocument;
 	}
+	captureSaveSnapshot() {
+		if (this.isComposing) throw new CanonicalSessionError({
+			gap: CANONICAL_GAP.save,
+			reason: "refused",
+			message: "Composition must finish before saving the canonical document."
+		});
+		const retainedBlockIdKeys = new Set([...this.sourceBlockIds, ...packageParagraphIds(this.currentDocument.package)].map((blockId) => blockId.toUpperCase()));
+		return {
+			document: cloneDocumentWithParagraphPropertySources(this.currentDocument),
+			version: this.currentVersion,
+			changedBlockIds: [...this.saveTouched].filter((blockId) => retainedBlockIdKeys.has(blockId.toUpperCase())),
+			structure: this.saveStructure
+		};
+	}
 	get projection() {
 		return this.currentProjection;
 	}
@@ -469,7 +586,7 @@ var CanonicalSession = class {
 		if (!state.doc.eq(projection.doc)) return refuse("The input uses a stale canonical projection.");
 		return Result.ok(void 0);
 	}
-	prepareReplace(state, { from, to, text, story = OP_STORIES.MAIN, semantic = "replacement", time = Date.now() }) {
+	prepareReplace(state, { from, to, text, story = OP_STORIES.MAIN, semantic = "replacement", compositionPhase, time = Date.now() }) {
 		const projected = this.projectStory(story);
 		if (projected.isErr()) return projected;
 		const projection = projected.value;
@@ -498,11 +615,14 @@ var CanonicalSession = class {
 		if (compiled.isErr()) return refuse(compiled.error.message);
 		const { ops, selection: caret } = compiled.value;
 		const postSelection = {
+			type: "text",
 			anchor: caret,
 			head: caret
 		};
 		const preDocument = this.currentDocument;
-		const run = state.selection.empty && (semantic === "typing" && from === to && from === state.selection.head || semantic === "deleteBackward" && text.length === 0 && to === state.selection.head || semantic === "deleteForward" && text.length === 0 && from === state.selection.head);
+		const isCaret = state.selection.empty;
+		const deletion = isCaret && text.length === 0 && (semantic === "deleteBackward" || semantic === "deleteForward") ? deletionRange(state, semantic === "deleteBackward" ? "backward" : "forward") : null;
+		const grouping = isCaret && (semantic === "typing" && from === to && from === state.selection.head || deletion?.isOk() && deletion.value.from === from && deletion.value.to === to) ? "run" : "isolated";
 		return this.stage({
 			state,
 			story,
@@ -521,7 +641,7 @@ var CanonicalSession = class {
 					version,
 					origin: "input",
 					semantic,
-					grouping: run ? "run" : "isolated",
+					grouping: compositionPhase === "correction" ? "compositionCorrection" : grouping,
 					time,
 					boundary: this.groupingBoundary
 				};
@@ -541,9 +661,9 @@ var CanonicalSession = class {
 		});
 	}
 	prepareIntent(state, intent) {
-		return this.prepareIntents(state, [intent]);
+		return this.prepareIntents(state, { intents: [intent] });
 	}
-	prepareIntents(state, intents) {
+	prepareIntents(state, { intents, resourceOps = [], semantic = "structure" }) {
 		const first = intents.at(0);
 		if (first === void 0) return noChange("The intent batch is empty.");
 		const story = intentStory(first);
@@ -556,12 +676,24 @@ var CanonicalSession = class {
 		if (preSelection.isErr()) return preSelection;
 		let document = this.currentDocument;
 		let postSelection = preSelection.value;
-		const ops = [];
+		const ops = [...resourceOps];
 		const edits = [];
+		if (resourceOps.length > 0) {
+			const imported = applyDocumentOps(document, resourceOps);
+			if (imported.isErr()) return refuse(imported.error.message);
+			document = imported.value.document;
+			edits.push(imported.value);
+		}
 		for (const intent of intents) {
+			if (this.mode.type === "suggesting" && (intent.type === "setHyperlink" || intent.type === "removeHyperlink" || intent.type === "insertHyperlink" || intent.type === "generateTOC")) return Result.err(new CanonicalSessionError({
+				gap: CANONICAL_GAP.trackedHyperlinkResolution,
+				reason: "refused",
+				message: "Hyperlink and TOC suggestions require serializable wrapper review provenance."
+			}));
 			const compiled = compileEditorIntent(document, {
 				intent,
-				mode: this.intentMode(document, intent)
+				mode: this.intentMode(document, intent),
+				firstBlockId: this.nextBlockId
 			});
 			if (compiled.isErr()) return refuse(compiled.error.message);
 			const applied = applyDocumentOps(document, compiled.value.ops);
@@ -569,7 +701,18 @@ var CanonicalSession = class {
 			document = applied.value.document;
 			edits.push(applied.value);
 			ops.push(...compiled.value.ops);
-			if (intent.type !== "formatRun" && intent.type !== "formatParagraph" && intent.type !== "setList") postSelection = {
+			if (intent.type === "generateTOC") {
+				const mapping = {
+					at: intent.at,
+					after: compiled.value.selection,
+					ops: compiled.value.ops
+				};
+				postSelection = Object.assign({}, postSelection, {
+					anchor: mapTocSelection(postSelection.anchor, mapping),
+					head: mapTocSelection(postSelection.head, mapping)
+				});
+			} else if (intent.type !== "setHyperlink" && intent.type !== "removeHyperlink" && intent.type !== "formatRun" && intent.type !== "formatParagraph" && intent.type !== "setList") postSelection = {
+				type: "text",
 				anchor: compiled.value.selection,
 				head: compiled.value.selection
 			};
@@ -582,7 +725,8 @@ var CanonicalSession = class {
 			state,
 			ops,
 			postSelection,
-			stagedApplied
+			stagedApplied,
+			semantic
 		});
 	}
 	prepareOps(state, ops, postSelection) {
@@ -592,7 +736,7 @@ var CanonicalSession = class {
 			postSelection
 		});
 	}
-	prepareJournalledOps({ state, ops, postSelection, stagedApplied }) {
+	prepareJournalledOps({ state, ops, postSelection, stagedApplied, semantic = "structure" }) {
 		const story = postSelection.anchor.story;
 		const projected = this.projectStory(story);
 		if (projected.isErr()) return projected;
@@ -618,7 +762,7 @@ var CanonicalSession = class {
 					postDocument: this.currentDocument,
 					version,
 					origin: "input",
-					semantic: "structure",
+					semantic,
 					grouping: "isolated",
 					time: Date.now(),
 					boundary: this.groupingBoundary
@@ -656,7 +800,7 @@ var CanonicalSession = class {
 			},
 			patch: { styleId: nextStyle }
 		});
-		return this.prepareIntents(state, intents);
+		return this.prepareIntents(state, { intents });
 	}
 	prepareJoin(state, direction) {
 		const checked = this.checkState(state);
@@ -712,6 +856,7 @@ var CanonicalSession = class {
 			state,
 			ops,
 			postSelection: {
+				type: "text",
 				anchor: caret,
 				head: caret
 			},
@@ -836,7 +981,8 @@ var CanonicalSession = class {
 			document: applied.value.document,
 			previous: this.currentDocument
 		});
-		if (!supportsSeed(applied.value.document, changed)) return refuse("The operations produce unsupported canonical story content.");
+		const unsupported = unsupportedSeedReason(applied.value.document, changed);
+		if (unsupported !== null) return refuse(unsupported);
 		preservePropertySources({
 			target: applied.value.document,
 			source: this.currentDocument,
@@ -891,12 +1037,15 @@ var CanonicalSession = class {
 			transaction.replaceWith(from, to, Fragment.fromArray(replacement));
 		}
 		if (!transaction.doc.eq(projected.value.doc)) transaction.replaceWith(0, transaction.doc.content.size, projected.value.doc.content);
-		if (sameStory(selection.anchor.story, story) && sameStory(selection.head.story, story)) {
-			const anchor = projected.value.positionAt(selection.anchor);
-			const head = projected.value.positionAt(selection.head);
-			if (anchor.isOk() && head.isOk()) transaction.setSelection(TextSelection.create(transaction.doc, anchor.value, head.value));
-			else transaction.setSelection(TextSelection.near(transaction.doc.resolve(Math.min(state.selection.anchor, transaction.doc.content.size))));
-		}
+		if (sameStory(selection.anchor.story, projectedStory) && sameStory(selection.head.story, projectedStory)) restoreCanonicalSelection({
+			transaction,
+			projection: projected.value,
+			selection,
+			unavailable: {
+				type: "near",
+				anchor: state.selection.anchor
+			}
+		});
 		transaction.setMeta(CANONICAL_PROJECTION_META, {
 			type: "canonical",
 			origin,
@@ -916,6 +1065,7 @@ var CanonicalSession = class {
 			document: applied.value.document,
 			projection: projected.value,
 			bodyProjection: bodyProjection.value,
+			selection,
 			touched: applied.value.touched,
 			version: baseVersion + 1,
 			origin,
@@ -939,6 +1089,13 @@ var CanonicalSession = class {
 				this.currentSelection = selection;
 				this.currentDocument = applied.value.document;
 				this.currentProjection = bodyProjection.value;
+				for (const ids of [
+					applied.value.touched.modified,
+					applied.value.touched.inserted,
+					applied.value.touched.removed
+				]) for (const id of ids) this.saveTouched.add(id);
+				const bodyOps = ops.filter((op) => !COMMENT_OPERATION_TYPES.has(op.type));
+				if (bodyOps.some(operationChangesStructure) || bodyOps.some(operationChangesPackage) || bodyOps.length > 0 && (applied.value.touched.inserted.length > 0 || applied.value.touched.removed.length > 0)) this.saveStructure = "changed";
 				this.currentVersion = baseVersion + 1;
 				onPublish(applied.value.inverse, this.currentVersion);
 				return Result.ok(void 0);
@@ -947,7 +1104,8 @@ var CanonicalSession = class {
 	}
 };
 const createCanonicalSession = (document, styles) => {
-	if (!supportsSeed(document)) return refuse("Canonical sessions currently require plain paragraphs and supported inline atoms.");
+	const unsupported = unsupportedSeedReason(document);
+	if (unsupported !== null) return refuse(unsupported);
 	const owned = cloneDocumentWithParagraphPropertySources(document);
 	const normalized = normalizeForOps(owned);
 	preservePropertySources({
@@ -980,31 +1138,55 @@ const visibleDeletionContext = (state) => {
 	let last = index;
 	while (last + 1 < state.doc.childCount && hasDeletedParagraphMark(state.doc.child(last))) last += 1;
 	let text = "";
-	const physicalGaps = [];
+	const physicalStarts = [];
+	const physicalEnds = [];
 	let visibleOffset = 0;
+	let issue;
 	state.doc.forEach((paragraph, paragraphOffset, paragraphIndex) => {
 		if (paragraphIndex < first || paragraphIndex > last) return;
-		paragraph.forEach((node, offset) => {
-			if (node.marks.some((mark) => mark.type.name === "deletion")) return;
-			const value = node.isText ? node.text ?? "" : "";
+		const native = canonicalNativeCells(paragraph);
+		if (native.isErr()) {
+			issue = new CanonicalSessionError({
+				gap: CANONICAL_GAP.dispatch,
+				reason: "refused",
+				message: native.error.message
+			});
+			return;
+		}
+		for (const cell of native.value) {
+			if (cell.type === "zeroWidth" || cell.node.marks.some((mark) => mark.type.name === "deletion")) continue;
+			const value = cell.type === "text" ? cell.text : "";
+			const from = paragraphOffset + 1 + cell.from;
+			const to = paragraphOffset + 1 + cell.to;
+			if (cell.type !== "text" && selection.from > from && selection.from < to) {
+				issue = new CanonicalSessionError({
+					gap: CANONICAL_GAP.dispatch,
+					reason: "refused",
+					message: "Character deletion cannot start inside an inline atom."
+				});
+				return;
+			}
 			for (let unit = 0; unit < value.length; unit += 1) {
-				const position = paragraphOffset + 1 + offset + unit;
-				physicalGaps[text.length] = position;
+				const position = from + (cell.type === "text" ? unit : 0);
+				physicalStarts.push(position);
 				text += value.charAt(unit);
-				physicalGaps.push(position + (node.isText ? 1 : node.nodeSize));
+				physicalEnds.push(cell.type === "text" ? position + 1 : to);
 				if (position < selection.from) visibleOffset += 1;
 			}
-		});
+		}
 	});
-	return {
+	return issue === void 0 ? Result.ok({
 		text,
-		physicalGaps,
+		physicalStarts,
+		physicalEnds,
 		visibleOffset
-	};
+	}) : Result.err(issue);
 };
 const isCanonicalJoinBoundary = (state, direction) => {
 	if (!(state.selection instanceof TextSelection) || !state.selection.empty) return false;
-	const { text, visibleOffset } = visibleDeletionContext(state);
+	const context = visibleDeletionContext(state);
+	if (context.isErr()) return false;
+	const { text, visibleOffset } = context.value;
 	return visibleOffset === (direction === "backward" ? 0 : text.length);
 };
 /** Native character deletion consumes one whole visible grapheme. */
@@ -1018,20 +1200,20 @@ const deletionRange = (state, direction) => {
 	const parent = selection.$from.parent;
 	const offset = selection.$from.parentOffset;
 	if ((direction === "backward" ? parent.childBefore(offset).node : parent.childAfter(offset).node)?.type.name === "noteMarker") return refuse("Automatic note marks cannot be deleted as characters.");
-	const { text, physicalGaps, visibleOffset } = visibleDeletionContext(state);
+	const context = visibleDeletionContext(state);
+	if (context.isErr()) return context;
+	const { text, physicalStarts, physicalEnds, visibleOffset } = context.value;
 	if (splitsSurrogatePair(text, visibleOffset)) return refuse("The deletion would split a surrogate pair.");
 	if (splitsGraphemeCluster(text, visibleOffset)) return refuse("Character deletion requires a caret at a grapheme boundary.");
 	if (direction === "backward" && visibleOffset === 0 || direction === "forward" && visibleOffset === text.length) return refuse("There is no visible character to delete in this paragraph.");
 	let boundary = visibleOffset + (direction === "backward" ? -1 : 1);
 	while (splitsGraphemeCluster(text, boundary)) boundary += direction === "backward" ? -1 : 1;
-	const position = physicalGaps.at(boundary);
-	if (position === void 0) panic("Canonical deletion lost a grapheme boundary.");
-	return Result.ok(direction === "backward" ? {
-		from: position,
-		to: selection.to
-	} : {
-		from: selection.from,
-		to: position
+	const from = physicalStarts.at(direction === "backward" ? boundary : visibleOffset);
+	const to = physicalEnds.at((direction === "backward" ? visibleOffset : boundary) - 1);
+	if (from === void 0 || to === void 0) panic("Canonical deletion lost a grapheme boundary.");
+	return Result.ok({
+		from,
+		to
 	});
 };
 //#endregion