@stll/folio-core 0.54.2 → 0.56.0

package/dist/controller/canonicalSession.js

@@ -0,0 +1,1186 @@
+import { splitsGraphemeCluster, splitsSurrogatePair } from "../ai-edits/character-boundaries.js";
+import { cloneDocumentWithParagraphPropertySources, copyDocumentParagraphPropertySourceContract, copyParagraphPropertySource } from "../docx/paragraphPropertySource.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 { 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 { 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 operationChangesPackage = (op) => {
+	switch (op.type) {
+		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;
+		default:
+			if ("story" in op) return !sameStory(op.story, OP_STORIES.MAIN);
+			if ("at" in op) return !sameStory(op.at.story, OP_STORIES.MAIN);
+			if ("from" in op) return !sameStory(op.from.story, OP_STORIES.MAIN);
+			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:
+		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: return false;
+		default: return op;
+	}
+};
+const operationChangesBodyProjection = (op) => {
+	switch (op.type) {
+		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;
+		default:
+			if ("story" in op) return sameStory(op.story, OP_STORIES.MAIN);
+			if ("at" in op) return sameStory(op.at.story, OP_STORIES.MAIN);
+			if ("from" in op) return sameStory(op.from.story, OP_STORIES.MAIN);
+			return op;
+	}
+};
+const CANONICAL_PROJECTION_META = "folioCanonicalProjection";
+/** Paragraph gaps bind logical units and source zero-width ordinals to PM positions. */
+var CanonicalProjection = class {
+	doc;
+	story;
+	paragraphs;
+	paragraphsById;
+	constructor({ doc, paragraphs, story }) {
+		this.story = story;
+		this.doc = doc;
+		this.paragraphs = paragraphs;
+		this.paragraphsById = new Map(paragraphs.map((paragraph) => [paragraph.blockId, paragraph]));
+	}
+	addressAt(position) {
+		if (!Number.isInteger(position)) return refuse("The input position is not an integer.");
+		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.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 || gap.zeroWidthBefore > 0 ? { zeroWidthBefore: gap.zeroWidthBefore } : {}
+		});
+	}
+	inputAddressAt(position) {
+		const address = this.addressAt(position);
+		if (address.isErr()) return address;
+		const paragraph = this.paragraph(address.value.blockId);
+		if (paragraph === void 0) panic("Input lost its paragraph.");
+		let destination = position;
+		paragraph.node.forEach((node, start) => {
+			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 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) && !(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(type === "all" ? range.to : state.selection.head);
+		if (head.isErr()) return head;
+		return Result.ok({
+			type,
+			anchor: anchor.value,
+			head: head.value
+		});
+	}
+	paragraph(blockId) {
+		return this.paragraphsById.get(blockId);
+	}
+};
+/** Immutable operations retain content identities for every untouched story. */
+const changedStories = ({ document, previous }) => {
+	const stories = [];
+	if (document.package.document.content !== previous.package.document.content) stories.push(OP_STORIES.MAIN);
+	for (const kind of ["header", "footer"]) {
+		const parts = kind === "header" ? document.package.headers : document.package.footers;
+		const prior = kind === "header" ? previous.package.headers : previous.package.footers;
+		if (parts === prior) continue;
+		for (const [rId, body] of parts ?? []) if (body.content !== prior?.get(rId)?.content) stories.push({
+			kind,
+			rId
+		});
+	}
+	for (const kind of ["footnote", "endnote"]) {
+		const notes = kind === "footnote" ? document.package.footnotes : document.package.endnotes;
+		const prior = kind === "footnote" ? previous.package.footnotes : previous.package.endnotes;
+		if (notes === prior) continue;
+		const priorById = new Map(prior?.map((note) => [note.id, note]));
+		for (const note of notes ?? []) {
+			const original = priorById.get(note.id);
+			if (note.content !== original?.content || note.noteType !== original?.noteType) stories.push({
+				kind,
+				id: note.id
+			});
+		}
+	}
+	return stories;
+};
+const preservePropertySources = ({ target, source, stories = documentStories(source) }) => {
+	for (const story of stories) {
+		const originals = findStoryBody(source, story)?.content ?? [];
+		const derived = findStoryBody(target, story)?.content ?? [];
+		if (originals === derived) continue;
+		const paragraphs = new Map(derived.flatMap((block) => block.type === "paragraph" ? [[block.paraId, block]] : []));
+		for (const [index, original] of originals.entries()) {
+			if (original.type !== "paragraph") continue;
+			const next = original.paraId === void 0 ? derived.at(index) : paragraphs.get(original.paraId);
+			if (next?.type === "paragraph" && next !== original) copyParagraphPropertySource(next, original);
+		}
+	}
+	copyDocumentParagraphPropertySourceContract(target, source);
+};
+const unsupportedSeedReason = (document, stories = documentStories(document)) => {
+	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") continue;
+		}
+		const content = body?.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 = {
+		...currentStyles == null ? {} : { styles: currentStyles },
+		...document.package.theme === void 0 ? {} : { theme: document.package.theme }
+	};
+	const converted = Result.try({
+		try: () => {
+			if (story === OP_STORIES.MAIN) return toProseDoc(document, options);
+			if (story.kind === "header" || story.kind === "footer") return headerFooterToProseDoc(body.content, options);
+			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 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;
+		}
+		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
+		});
+		if (inline.isErr()) {
+			failure = new CanonicalSessionError({
+				gap: CANONICAL_GAP.dispatch,
+				reason: "refused",
+				message: inline.error.message
+			});
+			return;
+		}
+		paragraphs.push({
+			blockId: source.paraId,
+			start: offset + 1,
+			...inline.value,
+			node,
+			source
+		});
+	});
+	if (failure !== void 0) return Result.err(failure);
+	if (paragraphs.length !== body.content.length) return refuse("The projection changed paragraph structure.");
+	return Result.ok(new CanonicalProjection({
+		doc: converted.value,
+		paragraphs,
+		story
+	}));
+};
+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.");
+		case "joinParagraphs": return intent.story;
+		case "table": return intent.operation.story;
+		default: return 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) => 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 "replacement":
+		case "structure": return false;
+		default: {
+			const unreachable = next.semantic;
+			return panic(`Unknown canonical input semantic ${unreachable}`);
+		}
+	}
+};
+const authorizedProjections = /* @__PURE__ */ new WeakMap();
+/** Metadata is descriptive; transaction identity and session version authorize mutations. */
+const isCanonicalProjectionTransaction = (transaction, session) => {
+	const authorization = authorizedProjections.get(transaction);
+	return authorization?.session === session && authorization.version === session.version && transaction.doc.eq(authorization.doc);
+};
+/** The model publishes only after PM and every plugin accept its exact projection. */
+const publishCanonicalProjection = ({ state, commit, session }) => {
+	if (!isCanonicalProjectionTransaction(commit.transaction, session)) return refuse("The staged canonical projection is unauthorized.");
+	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)}`
+		})
+	});
+	if (applied.isErr()) return applied;
+	const staged = applied.value;
+	if (!staged.transactions.includes(commit.transaction) || !staged.state.doc.eq(commit.projection.doc) || staged.transactions.some((transaction) => transaction.docChanged && !isCanonicalProjectionTransaction(transaction, session))) return refuse("A plugin refused or changed the canonical projection.");
+	const published = commit.publish();
+	if (published.isErr()) return published;
+	return Result.ok(staged);
+};
+const storyProjectionKey = (story) => {
+	switch (story.kind) {
+		case "header":
+		case "footer": return `${story.kind}:${story.rId}`;
+		case "footnote":
+		case "endnote": return `${story.kind}:${story.id}`;
+		default: return panic(`Unknown canonical story ${story}`);
+	}
+};
+/** Immutable model authority with a journal staged independently of the PM view. */
+var CanonicalSession = class {
+	currentDocument;
+	currentProjection;
+	sourceBlockIds;
+	currentVersion = 0;
+	saveTouched = /* @__PURE__ */ new Set();
+	saveStructure = "stable";
+	allocateIntentIds = createEditorIntentIdAllocator();
+	mode = { type: "editing" };
+	allocatedBlockIds = /* @__PURE__ */ new Set();
+	nextBlockId = 1;
+	sourceOwners = /* @__PURE__ */ new Map();
+	storyProjections = /* @__PURE__ */ new Map();
+	currentSelection = null;
+	applied = [];
+	groupingBoundary = 0;
+	lifecycle = { type: "committed" };
+	undone = [];
+	styles;
+	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);
+	}
+	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" } : {
+			type: "suggesting",
+			author: mode.author
+		};
+	}
+	hasStyle(styleId) {
+		return (this.styles ?? this.currentDocument.package.styles)?.styles.some((style) => style.styleId === styleId) ?? false;
+	}
+	advanceBlockId() {
+		while (this.allocatedBlockIds.has(this.nextBlockId.toString(16).padStart(8, "0").toUpperCase())) this.nextBlockId += 1;
+	}
+	freshBlockId() {
+		if (this.nextBlockId > 2147483647) return refuse("The paragraph identity space is exhausted.");
+		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",
+			reservedBlockIds: this.allocatedBlockIds
+		};
+		const ids = this.allocateIntentIds(document, intent);
+		return this.mode.type === "editing" ? {
+			type: "editing",
+			newIds: ids.newIds,
+			reservedBlockIds: this.allocatedBlockIds
+		} : {
+			type: "suggesting",
+			reservedBlockIds: this.allocatedBlockIds,
+			revision: {
+				id: ids.revisionId,
+				author: this.mode.author,
+				date: (/* @__PURE__ */ new Date()).toISOString()
+			},
+			newIds: ids.newIds
+		};
+	}
+	intentNeedsIdentityIds(document, intent) {
+		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":
+				if (intent.from.blockId !== intent.to.blockId) return true;
+				blockIds = [intent.from.blockId];
+				break;
+			case "splitParagraph":
+				if (intent.to !== void 0 && intent.at.blockId !== intent.to.blockId) return true;
+				blockIds = [intent.at.blockId];
+				break;
+			case "joinParagraphs":
+				blockIds = [intent.blockId, intent.nextBlockId];
+				break;
+			default: return intent;
+		}
+		const hasIdentity = (value) => {
+			if (typeof value !== "object" || value === null) return false;
+			if (Array.isArray(value)) return value.some(hasIdentity);
+			if ("id" in value && typeof value.id === "number" && ("author" in value || "sdtType" in value)) return true;
+			return Object.values(value).some(hasIdentity);
+		};
+		const story = intentStory(intent);
+		return blockIds.some((blockId) => {
+			const paragraph = document === this.currentDocument && story === OP_STORIES.MAIN ? this.currentProjection.paragraph(blockId)?.source : findStoryBody(document, story)?.content.find((block) => block.type === "paragraph" && block.paraId === blockId);
+			return paragraph !== void 0 && hasIdentity(paragraph);
+		});
+	}
+	rememberSources(document) {
+		for (const block of document.package.document.content) if (block.type === "paragraph" && block.paraId !== void 0) this.sourceOwners.set(block.paraId, block);
+	}
+	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;
+	}
+	get selection() {
+		return this.currentSelection;
+	}
+	get version() {
+		return this.currentVersion;
+	}
+	get canUndo() {
+		return this.applied.length > 0;
+	}
+	get canRedo() {
+		return this.undone.length > 0;
+	}
+	get isComposing() {
+		return this.lifecycle.type === "composing";
+	}
+	breakUndoGroup() {
+		this.groupingBoundary += 1;
+	}
+	beginComposition() {
+		if (this.isComposing) return refuse("A canonical composition is already pending.");
+		this.lifecycle = { type: "composing" };
+		this.breakUndoGroup();
+		return Result.ok(void 0);
+	}
+	endComposition() {
+		this.lifecycle = { type: "committed" };
+		this.breakUndoGroup();
+	}
+	checkState(state, projection = this.projection) {
+		if (this.isComposing) return refuse("Composition must finish before committing another edit.");
+		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", compositionPhase, time = Date.now() }) {
+		const projected = this.projectStory(story);
+		if (projected.isErr()) return projected;
+		const projection = projected.value;
+		const checked = this.checkState(state, projection);
+		if (checked.isErr()) return checked;
+		if (!Number.isFinite(time)) return refuse("The input time is invalid.");
+		if (from > to || hasIllegalXmlCharacters(text) || /[\t\r\n]/u.test(text)) return refuse("Canonical input accepts a well-formed text replacement.");
+		if (from === to && text.length === 0) return noChange("The input makes no text change.");
+		const start = projection.inputAddressAt(from);
+		if (start.isErr()) return start;
+		const end = projection.inputAddressAt(to);
+		if (end.isErr()) return end;
+		const preSelection = projection.selectionAt(state);
+		if (preSelection.isErr()) return preSelection;
+		const intent = {
+			type: "replaceText",
+			from: start.value,
+			to: end.value,
+			text,
+			...state.storedMarks === null ? {} : { runPropsPatch: runFormattingPatchFromMarks(state.selection.$from.marks(), state.storedMarks) }
+		};
+		const compiled = compileEditorIntent(this.currentDocument, {
+			intent,
+			mode: this.intentMode(this.currentDocument, intent)
+		});
+		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 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,
+			ops,
+			selection: postSelection,
+			origin: "input",
+			onPublish: (inverse, version) => {
+				const entry = {
+					type: "applied",
+					ops,
+					inverse,
+					preSelection: preSelection.value,
+					postSelection,
+					preDocument,
+					postDocument: this.currentDocument,
+					version,
+					origin: "input",
+					semantic,
+					grouping: compositionPhase === "correction" ? "compositionCorrection" : grouping,
+					time,
+					boundary: this.groupingBoundary
+				};
+				const group = this.applied.at(-1);
+				const previous = group?.entries.at(-1);
+				if (group !== void 0 && previous !== void 0 && continuesGroup(previous, entry)) {
+					group.entries.push(entry);
+					group.postSelection = postSelection;
+				} else this.applied.push({
+					entries: [entry],
+					undo: { type: "entries" },
+					preSelection: preSelection.value,
+					postSelection
+				});
+				this.undone.length = 0;
+			}
+		});
+	}
+	prepareIntent(state, intent) {
+		return this.prepareIntents(state, { intents: [intent] });
+	}
+	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);
+		if (intents.some((intent) => !sameStory(story, intentStory(intent)))) return refuse("A compound input must address one story.");
+		const projected = this.projectStory(story);
+		if (projected.isErr()) return projected;
+		const checked = this.checkState(state, projected.value);
+		if (checked.isErr()) return checked;
+		const preSelection = projected.value.selectionAt(state);
+		if (preSelection.isErr()) return preSelection;
+		let document = this.currentDocument;
+		let postSelection = preSelection.value;
+		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),
+				firstBlockId: this.nextBlockId
+			});
+			if (compiled.isErr()) return refuse(compiled.error.message);
+			const applied = applyDocumentOps(document, compiled.value.ops);
+			if (applied.isErr()) return refuse(applied.error.message);
+			document = applied.value.document;
+			edits.push(applied.value);
+			ops.push(...compiled.value.ops);
+			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
+			};
+		}
+		const stagedApplied = {
+			...combineEdits(this.currentDocument, edits),
+			revisions: edits.flatMap(({ revisions }) => revisions)
+		};
+		return this.prepareJournalledOps({
+			state,
+			ops,
+			postSelection,
+			stagedApplied,
+			semantic
+		});
+	}
+	prepareOps(state, ops, postSelection) {
+		return this.prepareJournalledOps({
+			state,
+			ops,
+			postSelection
+		});
+	}
+	prepareJournalledOps({ state, ops, postSelection, stagedApplied, semantic = "structure" }) {
+		const story = postSelection.anchor.story;
+		const projected = this.projectStory(story);
+		if (projected.isErr()) return projected;
+		const preSelection = projected.value.selectionAt(state);
+		if (preSelection.isErr()) return preSelection;
+		if (ops.length === 0 || stagedApplied?.inverse.length === 0) return noChange("The intent makes no document change.");
+		const preDocument = this.currentDocument;
+		return this.stage({
+			state,
+			story,
+			ops,
+			selection: postSelection,
+			origin: "input",
+			...stagedApplied === void 0 ? {} : { stagedApplied },
+			onPublish: (inverse, version) => {
+				const entry = {
+					type: "applied",
+					ops,
+					inverse,
+					preSelection: preSelection.value,
+					postSelection,
+					preDocument,
+					postDocument: this.currentDocument,
+					version,
+					origin: "input",
+					semantic,
+					grouping: "isolated",
+					time: Date.now(),
+					boundary: this.groupingBoundary
+				};
+				this.applied.push({
+					entries: [entry],
+					undo: { type: "entries" },
+					preSelection: preSelection.value,
+					postSelection
+				});
+				this.undone.length = 0;
+			}
+		});
+	}
+	prepareSplit(state) {
+		const from = this.projection.inputAddressAt(state.selection.from);
+		if (from.isErr()) return from;
+		const to = this.projection.inputAddressAt(state.selection.to);
+		if (to.isErr()) return to;
+		const source = this.projection.paragraph(from.value.blockId);
+		const nextStyle = (this.styles ?? this.currentDocument.package.styles)?.styles.find(({ styleId }) => styleId === source?.source.formatting?.styleId)?.next;
+		const fresh = this.freshBlockId();
+		if (fresh.isErr()) return fresh;
+		const intents = [{
+			type: "splitParagraph",
+			at: from.value,
+			to: to.value,
+			newBlockId: fresh.value
+		}];
+		if (state.selection.empty && source !== void 0 && from.value.offset === source.text.length && nextStyle !== void 0 && nextStyle !== source.source.formatting?.styleId) intents.push({
+			type: "formatParagraph",
+			at: {
+				...from.value,
+				offset: 0
+			},
+			patch: { styleId: nextStyle }
+		});
+		return this.prepareIntents(state, { intents });
+	}
+	prepareJoin(state, direction) {
+		const checked = this.checkState(state);
+		if (checked.isErr()) return checked;
+		if (!state.selection.empty) return refuse("Join requires a collapsed text selection.");
+		const at = this.projection.inputAddressAt(state.selection.from);
+		if (at.isErr()) return at;
+		const groups = editorParagraphGroups(this.currentDocument, at.value.story);
+		const index = groups.findIndex(({ paragraphs }) => paragraphs.some((paragraph) => paragraph.paraId === at.value.blockId));
+		if (index < 0 || direction === "backward" && index === 0) return noChange("There is no adjacent paragraph to join.");
+		const firstGroup = groups.at(direction === "backward" ? index - 1 : index);
+		const secondGroup = groups.at(direction === "backward" ? index : index + 1);
+		const first = firstGroup?.paragraphs.at(-1);
+		const second = secondGroup?.paragraphs.at(0);
+		if (!first?.paraId || !second?.paraId) return noChange("There is no adjacent paragraph to join.");
+		if (!isCanonicalJoinBoundary(state, direction)) return refuse("Join requires a caret at a paragraph boundary.");
+		return this.prepareIntent(state, {
+			type: "joinParagraphs",
+			story: at.value.story,
+			blockId: first.paraId,
+			nextBlockId: second.paraId
+		});
+	}
+	prepareResolve(state, { revisionIds, resolution }) {
+		const checked = this.checkState(state);
+		if (checked.isErr()) return checked;
+		const preSelection = this.projection.selectionAt(state);
+		if (preSelection.isErr()) return preSelection;
+		const ops = [{
+			type: DOCUMENT_OP_TYPES.RESOLVE_REVISION,
+			story: OP_STORIES.MAIN,
+			revisionIds,
+			decision: resolution
+		}];
+		const applied = applyDocumentOps(this.currentDocument, ops);
+		if (applied.isErr()) return refuse(applied.error.message);
+		const projected = project({
+			document: applied.value.document,
+			styles: this.styles
+		});
+		if (projected.isErr()) return projected;
+		const surviving = projected.value.paragraph(preSelection.value.head.blockId);
+		const first = applied.value.document.package.document.content.at(0);
+		if (first?.type !== "paragraph" || first.paraId === void 0) return refuse("Resolution left no paragraph.");
+		let offset = surviving ? Math.min(preSelection.value.head.offset, surviving.text.length) : 0;
+		if (surviving && splitsSurrogatePair(surviving.text, offset)) offset -= 1;
+		const caret = {
+			story: OP_STORIES.MAIN,
+			blockId: surviving?.blockId ?? first.paraId,
+			offset
+		};
+		return this.prepareJournalledOps({
+			state,
+			ops,
+			postSelection: {
+				type: "text",
+				anchor: caret,
+				head: caret
+			},
+			stagedApplied: applied.value
+		});
+	}
+	projectStory(story) {
+		if (story === OP_STORIES.MAIN) return Result.ok(this.projection);
+		const key = storyProjectionKey(story);
+		const body = findStoryBody(this.currentDocument, story);
+		if (body === void 0) {
+			this.storyProjections.delete(key);
+			return refuse("The canonical story no longer exists.");
+		}
+		const cached = this.storyProjections.get(key);
+		const theme = this.currentDocument.package.theme;
+		if (cached?.content === body.content && cached.theme === theme) return Result.ok(cached.projection);
+		const projected = project({
+			document: this.currentDocument,
+			styles: this.styles,
+			story
+		});
+		if (projected.isOk()) this.storyProjections.set(key, {
+			content: body.content,
+			theme,
+			projection: projected.value
+		});
+		return projected;
+	}
+	prepareOperations(state, ops) {
+		if (ops.length === 0) return refuse("The operation batch is empty.");
+		const selected = this.projection.selectionAt(state);
+		if (selected.isErr()) return selected;
+		const preDocument = this.currentDocument;
+		return this.stage({
+			state,
+			ops,
+			selection: selected.value,
+			origin: "input",
+			onPublish: (inverse, version) => {
+				this.applied.push({
+					entries: [{
+						type: "applied",
+						ops,
+						inverse,
+						preSelection: selected.value,
+						postSelection: selected.value,
+						preDocument,
+						postDocument: this.currentDocument,
+						version,
+						origin: "input",
+						semantic: "structure",
+						grouping: "isolated",
+						time: Date.now(),
+						boundary: this.groupingBoundary
+					}],
+					undo: { type: "entries" },
+					preSelection: selected.value,
+					postSelection: selected.value
+				});
+				this.undone.length = 0;
+			}
+		});
+	}
+	prepareUndo(state, story = OP_STORIES.MAIN) {
+		const group = this.applied.at(-1);
+		if (group === void 0) return refuse("There is no canonical edit to undo.");
+		const propertySourceDocument = group.entries.at(0)?.preDocument;
+		return this.stage({
+			state,
+			story,
+			ops: group.undo.type === "replayed" ? group.undo.inverse : group.entries.toReversed().flatMap((entry) => entry.inverse),
+			selection: group.preSelection,
+			origin: "undo",
+			...propertySourceDocument === void 0 ? {} : { propertySourceDocument },
+			onPublish: (redoOps) => {
+				this.applied.pop();
+				this.undone.push({
+					type: "undone",
+					group,
+					redoOps
+				});
+				this.breakUndoGroup();
+			}
+		});
+	}
+	prepareRedo(state, story = OP_STORIES.MAIN) {
+		const undone = this.undone.at(-1);
+		if (undone === void 0) return refuse("There is no canonical edit to redo.");
+		const propertySourceDocument = undone.group.entries.at(-1)?.postDocument;
+		return this.stage({
+			state,
+			story,
+			ops: undone.redoOps,
+			selection: undone.group.postSelection,
+			origin: "redo",
+			...propertySourceDocument === void 0 ? {} : { propertySourceDocument },
+			onPublish: (inverse) => {
+				this.undone.pop();
+				this.applied.push({
+					entries: undone.group.entries,
+					undo: {
+						type: "replayed",
+						inverse
+					},
+					preSelection: undone.group.preSelection,
+					postSelection: undone.group.postSelection
+				});
+				this.breakUndoGroup();
+			}
+		});
+	}
+	stage({ state, ops, selection, origin, onPublish, propertySourceDocument, stagedApplied, story = OP_STORIES.MAIN, previousProjection }) {
+		const previous = previousProjection === void 0 ? this.projectStory(story) : Result.ok(previousProjection);
+		if (previous.isErr()) return previous;
+		const checked = this.checkState(state, previous.value);
+		if (checked.isErr()) return checked;
+		const applied = stagedApplied === void 0 ? applyDocumentOps(this.currentDocument, ops) : Result.ok(stagedApplied);
+		if (applied.isErr()) return refuse(applied.error.message);
+		if (applied.value.inverse.length === 0) return noChange("The intent makes no document change.");
+		const changed = changedStories({
+			document: applied.value.document,
+			previous: this.currentDocument
+		});
+		const unsupported = unsupportedSeedReason(applied.value.document, changed);
+		if (unsupported !== null) return refuse(unsupported);
+		preservePropertySources({
+			target: applied.value.document,
+			source: this.currentDocument,
+			stories: changed
+		});
+		if (propertySourceDocument !== void 0) preservePropertySources({
+			target: applied.value.document,
+			source: propertySourceDocument
+		});
+		const stagedSources = new Map(this.sourceOwners);
+		for (const block of applied.value.document.package.document.content) {
+			if (block.type !== "paragraph" || block.paraId === void 0) continue;
+			const source = stagedSources.get(block.paraId);
+			if (source && block !== source) copyParagraphPropertySource(block, source);
+		}
+		const projectedStory = findStoryBody(applied.value.document, story) ? story : OP_STORIES.MAIN;
+		const projected = project({
+			document: applied.value.document,
+			styles: this.styles,
+			story: projectedStory
+		});
+		if (projected.isErr()) return projected;
+		const bodyProjection = (() => {
+			if (sameStory(projectedStory, OP_STORIES.MAIN)) return projected;
+			if (ops.some(operationChangesBodyProjection)) return project({
+				document: applied.value.document,
+				styles: this.styles
+			});
+			return Result.ok(this.currentProjection);
+		})();
+		if (bodyProjection.isErr()) return bodyProjection;
+		const transaction = state.tr;
+		const before = state.doc;
+		const after = projected.value.doc;
+		let prefix = 0;
+		let from = 0;
+		while (prefix < before.childCount && prefix < after.childCount && before.child(prefix).eq(after.child(prefix))) {
+			from += before.child(prefix).nodeSize;
+			prefix += 1;
+		}
+		let oldEnd = before.childCount;
+		let newEnd = after.childCount;
+		let to = before.content.size;
+		while (oldEnd > prefix && newEnd > prefix && before.child(oldEnd - 1).eq(after.child(newEnd - 1))) {
+			oldEnd -= 1;
+			newEnd -= 1;
+			to -= before.child(oldEnd).nodeSize;
+		}
+		if (oldEnd !== prefix || newEnd !== prefix) {
+			const replacement = [];
+			for (let index = prefix; index < newEnd; index += 1) replacement.push(after.child(index));
+			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);
+			switch (selection.type) {
+				case "all":
+					transaction.setSelection(new AllSelection(transaction.doc));
+					break;
+				case "text":
+					if (anchor.isOk() && head.isOk()) {
+						transaction.setSelection(TextSelection.create(transaction.doc, anchor.value, head.value));
+						break;
+					}
+					transaction.setSelection(TextSelection.near(transaction.doc.resolve(Math.min(state.selection.anchor, transaction.doc.content.size))));
+					break;
+				default: {
+					const exhaustive = selection.type;
+					return panic(`Unknown canonical selection type: ${exhaustive}`);
+				}
+			}
+		}
+		transaction.setMeta(CANONICAL_PROJECTION_META, {
+			type: "canonical",
+			origin,
+			version: this.version + 1
+		});
+		if (ops.some(operationChangesPackage)) markPackageChange(transaction);
+		transaction.setMeta("addToHistory", false);
+		const baseVersion = this.version;
+		const baseBoundary = this.groupingBoundary;
+		authorizedProjections.set(transaction, {
+			session: this,
+			version: baseVersion,
+			doc: projected.value.doc
+		});
+		return Result.ok({
+			transaction,
+			document: applied.value.document,
+			projection: projected.value,
+			bodyProjection: bodyProjection.value,
+			touched: applied.value.touched,
+			version: baseVersion + 1,
+			origin,
+			publish: () => {
+				if (this.isComposing || this.groupingBoundary !== baseBoundary) return refuse("The staged canonical commit crossed a composition or selection boundary.");
+				if (this.version !== baseVersion) return refuse("The staged canonical commit is stale.");
+				if (!isCanonicalProjectionTransaction(transaction, this)) return refuse("The staged canonical projection was changed after preparation.");
+				for (const blockId of applied.value.touched.inserted) this.allocatedBlockIds.add(blockId.toUpperCase());
+				for (const op of ops) if (op.type === DOCUMENT_OP_TYPES.SPLIT_BLOCK) this.allocatedBlockIds.add(op.newBlockId.toUpperCase());
+				this.advanceBlockId();
+				this.rememberSources(applied.value.document);
+				if (projectedStory !== OP_STORIES.MAIN) {
+					const body = findStoryBody(applied.value.document, projectedStory);
+					if (body === void 0) panic("A staged story projection lost its source.");
+					this.storyProjections.set(storyProjectionKey(projectedStory), {
+						content: body.content,
+						theme: applied.value.document.package.theme,
+						projection: projected.value
+					});
+				}
+				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);
+				if (applied.value.touched.inserted.length > 0 || applied.value.touched.removed.length > 0 || ops.some(operationChangesPackage) || ops.some(operationChangesStructure)) this.saveStructure = "changed";
+				this.currentVersion = baseVersion + 1;
+				onPublish(applied.value.inverse, this.currentVersion);
+				return Result.ok(void 0);
+			}
+		});
+	}
+};
+const createCanonicalSession = (document, styles) => {
+	const unsupported = unsupportedSeedReason(document);
+	if (unsupported !== null) return refuse(unsupported);
+	const owned = cloneDocumentWithParagraphPropertySources(document);
+	const normalized = normalizeForOps(owned);
+	preservePropertySources({
+		target: normalized,
+		source: owned
+	});
+	const validated = validateOpsDocument(normalized);
+	if (validated.isErr()) return refuse(validated.error.message);
+	const projected = project({
+		document: normalized,
+		styles
+	});
+	if (projected.isErr()) return projected;
+	return Result.ok(new CanonicalSession({
+		document: normalized,
+		projection: projected.value,
+		styles
+	}));
+};
+const hasDeletedParagraphMark = (node) => {
+	const mark = node.attrs["pPrMark"];
+	return typeof mark === "object" && mark !== null && "kind" in mark && (mark.kind === "del" || mark.kind === "moveFrom");
+};
+/** Visible graphemes concatenate across retained deletions and deleted paragraph marks. */
+const visibleDeletionContext = (state) => {
+	const { selection } = state;
+	const index = selection.$from.index(0);
+	let first = index;
+	while (first > 0 && hasDeletedParagraphMark(state.doc.child(first - 1))) first -= 1;
+	let last = index;
+	while (last + 1 < state.doc.childCount && hasDeletedParagraphMark(state.doc.child(last))) last += 1;
+	let text = "";
+	const physicalStarts = [];
+	const physicalEnds = [];
+	let visibleOffset = 0;
+	let issue;
+	state.doc.forEach((paragraph, paragraphOffset, paragraphIndex) => {
+		if (paragraphIndex < first || paragraphIndex > last) return;
+		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 = from + (cell.type === "text" ? unit : 0);
+				physicalStarts.push(position);
+				text += value.charAt(unit);
+				physicalEnds.push(cell.type === "text" ? position + 1 : to);
+				if (position < selection.from) visibleOffset += 1;
+			}
+		}
+	});
+	return issue === void 0 ? Result.ok({
+		text,
+		physicalStarts,
+		physicalEnds,
+		visibleOffset
+	}) : Result.err(issue);
+};
+const isCanonicalJoinBoundary = (state, direction) => {
+	if (!(state.selection instanceof TextSelection) || !state.selection.empty) return false;
+	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. */
+const deletionRange = (state, direction) => {
+	const { selection } = state;
+	if (!(selection instanceof TextSelection)) return refuse("Canonical deletion requires a text selection.");
+	if (!selection.empty) return Result.ok({
+		from: selection.from,
+		to: selection.to
+	});
+	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 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 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
+export { CANONICAL_PROJECTION_META, CanonicalSessionError, createCanonicalSession, deletionRange, isCanonicalJoinBoundary, isCanonicalProjectionTransaction, publishCanonicalProjection };