@stll/folio-core 0.55.0 → 0.56.0

package/dist/controller/hiddenEditorManager.js

@@ -2,6 +2,8 @@ import { recordHiddenEditorPhase, recordHiddenEditorStateCreate } from "../layou
 import { suppressHiddenEditorScrollToSelection } from "../paged-layout/hiddenEditorScroll.js";
 import { isReadOnlyEditKey } from "../paged-layout/readOnlyEditAttempt.js";
 import { getCanonicalCommandIntents } from "../prosemirror/canonicalCommands.js";
+import { registerClipboardIntentHandler } from "../prosemirror/clipboardIntent.js";
+import { pasteWithoutFormatting } from "../prosemirror/commands/pastePlainText.js";
 import { createEmptyDoc, toProseDoc } from "../prosemirror/conversion/toProseDoc.js";
 import { registerEditorCommandOwner } from "../prosemirror/executeEditorCommand.js";
 import { ensureBaseDirectionInState } from "../prosemirror/extensions/features/AutoBidiDetectionExtension.js";
@@ -13,13 +15,16 @@ import { createDocumentStylesPlugin } from "../prosemirror/plugins/documentStyle
 import { schema } from "../prosemirror/schema/index.js";
 import { createTextInputPlugin } from "../prosemirror/textInput.js";
 import { applyAttrSchemaMigrations, proseDocumentParagraphSourceContract, readYjsAttrSchemaVersion, readYjsParagraphSourceContract, withParagraphSourceContract, writeYjsDocumentMetadata } from "../prosemirror/yjsDocumentMetadata.js";
+import { CANONICAL_GAP, usesCanonicalSession } from "../types/canonicalCapabilities.js";
+import { prepareCanonicalPaste } from "./canonicalClipboard.js";
 import { createCanonicalInputBoundary } from "./canonicalInput.js";
+import { CanonicalPublicOperations } from "./canonicalPublicOperations.js";
 import { createCanonicalSession, publishCanonicalProjection } from "./canonicalSession.js";
 import { prepareCanonicalAutoformat, prepareCanonicalCommands } from "./canonicalStructure.js";
 import { createHiddenEditorApi } from "./hiddenEditorApi.js";
 import { Result, TaggedError, panic } from "better-result";
 import { OP_STORIES } from "@stll/docx-core/ops";
-import { EditorState } from "prosemirror-state";
+import { EditorState, Plugin } from "prosemirror-state";
 import { EditorView } from "prosemirror-view";
 //#region src/controller/hiddenEditorManager.ts
 var CanonicalSessionRefusalError = class extends TaggedError("CanonicalSessionRefusalError") {};
@@ -209,12 +214,16 @@ const createHiddenEditorManager = (deps) => {
 			author: deps.getSuggestionAuthor?.() ?? "User"
 		} : { type: "editing" }));
 	};
-	const refuse = (reason) => {
-		if (deps.onSessionRefusal) deps.onSessionRefusal(reason);
-		else throw new CanonicalSessionRefusalError({ message: reason });
+	const refuse = (reason, gap = CANONICAL_GAP.dispatch) => {
+		const message = reason;
+		if (deps.onSessionRefusal) deps.onSessionRefusal(message, gap);
+		else throw new CanonicalSessionRefusalError({
+			gap,
+			message
+		});
 	};
 	const seedSession = (document) => {
-		if (deps.getExperimentalSession?.() !== "canonical") {
+		if (!usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting)) {
 			editorSession = { type: "prosemirror" };
 			return true;
 		}
@@ -227,7 +236,7 @@ const createHiddenEditorManager = (deps) => {
 				reason,
 				documentIdentity
 			};
-			refuse(reason);
+			refuse(reason, CANONICAL_GAP.collaboration);
 			return false;
 		}
 		const result = createCanonicalSession(document, deps.getStyles());
@@ -237,7 +246,7 @@ const createHiddenEditorManager = (deps) => {
 				reason: result.error.message,
 				documentIdentity
 			};
-			refuse(result.error.message);
+			refuse(result.error.message, result.error.gap);
 			return false;
 		}
 		editorSession = {
@@ -253,7 +262,13 @@ const createHiddenEditorManager = (deps) => {
 		plugins: [
 			createParagraphChangeTrackerPlugin(),
 			createDocumentStylesPlugin(deps.getStyles() ?? session.document.package.styles),
-			createDocumentNumberingPlugin(session.document.package.numbering)
+			createDocumentNumberingPlugin(session.document.package.numbering),
+			...[...deps.getExtensionManager()?.getPlugins() ?? [], ...deps.getExternalPlugins()].flatMap(({ props }) => props.transformPastedHTML === void 0 && props.transformPasted === void 0 && props.transformCopied === void 0 && props.clipboardTextSerializer === void 0 ? [] : [new Plugin({ props: {
+				...props.transformCopied === void 0 ? {} : { transformCopied: props.transformCopied },
+				...props.clipboardTextSerializer === void 0 ? {} : { clipboardTextSerializer: props.clipboardTextSerializer },
+				...props.transformPastedHTML === void 0 ? {} : { transformPastedHTML: props.transformPastedHTML },
+				...props.transformPasted === void 0 ? {} : { transformPasted: props.transformPasted }
+			} })])
 		]
 	});
 	const publishCommit = (commit) => {
@@ -265,7 +280,7 @@ const createHiddenEditorManager = (deps) => {
 			session
 		});
 		if (result.isErr()) {
-			refuse(result.error.message);
+			refuse(result.error.message, result.error.gap);
 			return false;
 		}
 		const staged = result.value;
@@ -284,7 +299,7 @@ const createHiddenEditorManager = (deps) => {
 		if (direction === "undo" ? !session.canUndo : !session.canRedo) return false;
 		const prepared = direction === "undo" ? session.prepareUndo(view.state) : session.prepareRedo(view.state);
 		if (prepared.isErr()) {
-			if (prepared.error.reason !== "noChange") refuse(prepared.error.message);
+			if (prepared.error.reason !== "noChange") refuse(prepared.error.message, prepared.error.gap);
 			return false;
 		}
 		return publishCommit(prepared.value);
@@ -292,6 +307,7 @@ const createHiddenEditorManager = (deps) => {
 	const executeCanonicalCommand = (command) => {
 		if (!view || editorSession.type !== "canonical") return void 0;
 		if (deps.getReadOnly()) return false;
+		if (command === pasteWithoutFormatting) return command(view.state, (transaction) => view?.dispatch(transaction), view);
 		if (editorSession.session.isComposing) {
 			refuse("Composition must finish before formatting.");
 			return false;
@@ -305,11 +321,12 @@ const createHiddenEditorManager = (deps) => {
 		}, view);
 		const prepared = prepareCanonicalCommands(editorSession.session, view.state, intents);
 		if (prepared.isErr()) {
-			if (prepared.error.reason !== "noChange") refuse(prepared.error.message);
+			if (prepared.error.reason !== "noChange") refuse(prepared.error.message, prepared.error.gap);
 			return false;
 		}
 		return publishCommit(prepared.value);
 	};
+	let clipboardDrag = { type: "idle" };
 	let lastInputRule;
 	const canonicalStructuralInput = {
 		command: (name) => {
@@ -324,7 +341,7 @@ const createHiddenEditorManager = (deps) => {
 				if (mark !== void 0) command = name === "toggleUnderline" ? toggleUnderlineMark(mark) : toggleMarkForAllScripts(mark, name === "toggleBold" ? "bold" : "italic");
 			}
 			if (command === void 0) {
-				refuse("The formatting command is unavailable.");
+				refuse("The formatting command is unavailable.", CANONICAL_GAP.commands);
 				return;
 			}
 			if (executeCanonicalCommand(command) === void 0) command(view.state, (transaction) => view?.dispatch(transaction), view);
@@ -336,7 +353,7 @@ const createHiddenEditorManager = (deps) => {
 			const state = view.state;
 			const selection = session.projection.selectionAt(state);
 			if (selection.isErr()) {
-				refuse(selection.error.message);
+				refuse(selection.error.message, selection.error.gap);
 				return;
 			}
 			let prepared;
@@ -386,11 +403,11 @@ const createHiddenEditorManager = (deps) => {
 					const from = session.projection.addressAt(state.selection.from);
 					const to = session.projection.addressAt(state.selection.to);
 					if (from.isErr()) {
-						refuse(from.error.message);
+						refuse(from.error.message, from.error.gap);
 						return;
 					}
 					if (to.isErr()) {
-						refuse(to.error.message);
+						refuse(to.error.message, to.error.gap);
 						return;
 					}
 					prepared = session.prepareIntent(state, {
@@ -407,7 +424,7 @@ const createHiddenEditorManager = (deps) => {
 				default: return type;
 			}
 			if (prepared.isErr()) {
-				if (prepared.error.reason !== "noChange") refuse(prepared.error.message);
+				if (prepared.error.reason !== "noChange") refuse(prepared.error.message, prepared.error.gap);
 				return;
 			}
 			publishCommit(prepared.value);
@@ -421,7 +438,7 @@ const createHiddenEditorManager = (deps) => {
 			if (deps.getReadOnly() || editorSession.type !== "canonical") return false;
 			const begun = editorSession.session.beginComposition();
 			if (begun.isErr()) {
-				refuse(begun.error.message);
+				refuse(begun.error.message, begun.error.gap);
 				return false;
 			}
 			return true;
@@ -431,6 +448,52 @@ const createHiddenEditorManager = (deps) => {
 		}
 	};
 	const input = createCanonicalInputBoundary({
+		pastePlainText: (pmView) => {
+			if (deps.getReadOnly()) {
+				deps.onReadOnlyEditAttempt();
+				return;
+			}
+			pasteWithoutFormatting(pmView.state, (transaction) => pmView.dispatch(transaction), pmView);
+		},
+		cut: (pmView, event) => {
+			event.preventDefault();
+			if (deps.getReadOnly()) {
+				deps.onReadOnlyEditAttempt();
+				return true;
+			}
+			if (editorSession.type !== "canonical" || pmView.state.selection.empty) return true;
+			if (event.clipboardData === null) {
+				refuse("The clipboard cannot receive the cut content.");
+				return true;
+			}
+			syncCanonicalMode();
+			const session = editorSession.session;
+			const { from, to } = pmView.state.selection;
+			const prepared = session.prepareReplace(pmView.state, {
+				from,
+				to,
+				text: "",
+				semantic: "replacement"
+			});
+			if (prepared.isErr()) {
+				refuse(prepared.error.message, prepared.error.gap);
+				return true;
+			}
+			const copied = Result.try({
+				try: () => {
+					const serialized = pmView.serializeForClipboard(pmView.state.selection.content());
+					event.clipboardData?.setData("text/html", serialized.dom.innerHTML);
+					event.clipboardData?.setData("text/plain", serialized.text);
+				},
+				catch: () => new CanonicalSessionRefusalError({
+					gap: CANONICAL_GAP.dispatch,
+					message: "The clipboard could not receive the cut content."
+				})
+			});
+			if (copied.isErr()) refuse(copied.error.message, copied.error.gap);
+			else publishCommit(prepared.value);
+			return true;
+		},
 		...canonicalInputLifecycle,
 		...canonicalStructuralInput,
 		replace: (intent) => {
@@ -439,7 +502,7 @@ const createHiddenEditorManager = (deps) => {
 			const rule = prepareCanonicalAutoformat(editorSession.session, view.state, intent);
 			const prepared = rule ?? editorSession.session.prepareReplace(view.state, intent);
 			if (prepared.isErr()) {
-				if (prepared.error.reason !== "noChange") refuse(prepared.error.message);
+				if (prepared.error.reason !== "noChange") refuse(prepared.error.message, prepared.error.gap);
 				return;
 			}
 			const session = editorSession.session;
@@ -464,14 +527,14 @@ const createHiddenEditorManager = (deps) => {
 		if (!host) return;
 		const collaboration = deps.getCollaboration();
 		const collaborationModules = deps.getCollaborationModules();
-		if (collaboration && !collaborationModules && deps.getExperimentalSession?.() !== "canonical") return;
+		if (collaboration && !collaborationModules && !usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting)) return;
 		const precomputedInitialState = deps.getPrecomputedInitialState();
 		const document = deps.getDocument();
 		const styles = deps.getStyles();
 		const extensionManager = deps.getExtensionManager();
 		const externalPlugins = deps.getExternalPlugins();
-		if (!seedSession(document)) return;
 		input.reset();
+		if (!seedSession(document)) return;
 		const editorProps = {
 			state: (() => {
 				if (editorSession.type === "canonical") return canonicalState(editorSession.session);
@@ -533,16 +596,79 @@ const createHiddenEditorManager = (deps) => {
 				return deps.onKeyDown(pmView, event);
 			},
 			handleTextInput: (pmView, from, to, text) => editorSession.type === "canonical" ? input.handleTextInput(pmView, from, to, text) : false,
+			handlePaste: (pmView, _event, slice) => {
+				if (editorSession.type !== "canonical") return false;
+				if (deps.getReadOnly()) {
+					deps.onReadOnlyEditAttempt();
+					return true;
+				}
+				syncCanonicalMode();
+				const prepared = prepareCanonicalPaste({
+					session: editorSession.session,
+					state: pmView.state,
+					slice
+				});
+				if (prepared.isErr()) {
+					if (prepared.error.reason !== "noChange") refuse(prepared.error.message, prepared.error.gap);
+				} else publishCommit(prepared.value);
+				return true;
+			},
+			handleDrop: (pmView, event, slice, moved) => {
+				if (editorSession.type !== "canonical") return false;
+				if (deps.getReadOnly()) {
+					deps.onReadOnlyEditAttempt();
+					return true;
+				}
+				const target = pmView.posAtCoords({
+					left: event.clientX,
+					top: event.clientY
+				})?.pos;
+				if (target === void 0) {
+					refuse("The drop has no document destination.");
+					return true;
+				}
+				const captured = clipboardDrag;
+				clipboardDrag = { type: "idle" };
+				if (moved && (captured.type !== "dragging" || captured.session !== editorSession.session || captured.version !== editorSession.session.version)) {
+					refuse("The dragged content changed or has no captured source.");
+					return true;
+				}
+				const source = captured.type === "dragging" ? {
+					from: captured.from,
+					to: captured.to
+				} : pmView.state.selection;
+				if (moved && target >= source.from && target <= source.to) return true;
+				syncCanonicalMode();
+				const prepared = prepareCanonicalPaste({
+					session: editorSession.session,
+					state: pmView.state,
+					slice,
+					...moved ? {
+						moveTarget: target,
+						moveSource: {
+							from: source.from,
+							to: source.to
+						}
+					} : { pasteTarget: target }
+				});
+				if (prepared.isErr()) {
+					if (prepared.error.reason !== "noChange") refuse(prepared.error.message, prepared.error.gap);
+				} else publishCommit(prepared.value);
+				return true;
+			},
 			handleScrollToSelection: suppressHiddenEditorScrollToSelection,
 			handleDOMEvents: {
+				keydown: (pmView, event) => editorSession.type === "canonical" ? input.handleDOMEvents.keydown(pmView, event) : false,
 				focus: () => false,
 				blur: (pmView) => editorSession.type === "canonical" ? input.handleDOMEvents.blur(pmView) : false,
 				...createHiddenEditorClipboardHandlers(deps),
-				mousedown: (pmView) => editorSession.type === "canonical" ? input.handleDOMEvents.mousedown(pmView) : false,
 				compositionstart: (pmView) => editorSession.type === "canonical" ? input.handleDOMEvents.compositionstart(pmView) : false,
 				compositionend: (pmView) => editorSession.type === "canonical" ? input.handleDOMEvents.compositionend(pmView) : false,
 				input: (pmView) => editorSession.type === "canonical" ? input.handleDOMEvents.input(pmView) : false,
-				paste: (pmView, event) => editorSession.type === "canonical" ? input.handleDOMEvents.paste(pmView, event) : createHiddenEditorClipboardHandlers(deps).paste(pmView, event),
+				paste: (pmView, event) => {
+					if (editorSession.type === "canonical" && !deps.getReadOnly()) return input.handleDOMEvents.paste(pmView, event);
+					return createHiddenEditorClipboardHandlers(deps).paste(pmView, event);
+				},
 				cut: (pmView, event) => editorSession.type === "canonical" ? input.handleDOMEvents.cut(pmView, event) : createHiddenEditorClipboardHandlers(deps).cut(pmView, event),
 				beforeinput: (_view, event) => {
 					if (editorSession.type === "canonical" && !deps.getReadOnly()) return input.handleDOMEvents.beforeinput(_view, event);
@@ -551,8 +677,22 @@ const createHiddenEditorManager = (deps) => {
 					event.preventDefault();
 					return true;
 				},
+				dragstart: (pmView) => {
+					if (editorSession.type === "canonical") clipboardDrag = {
+						type: "dragging",
+						session: editorSession.session,
+						version: editorSession.session.version,
+						from: pmView.state.selection.from,
+						to: pmView.state.selection.to
+					};
+					return false;
+				},
+				dragend: () => {
+					clipboardDrag = { type: "idle" };
+					return false;
+				},
 				drop: (_view, event) => {
-					if (editorSession.type === "canonical") return input.handleDOMEvents.drop(_view, event);
+					if (editorSession.type === "canonical" && !deps.getReadOnly()) return input.handleDOMEvents.drop(_view, event);
 					if (!deps.getReadOnly()) return false;
 					deps.onReadOnlyEditAttempt();
 					event.preventDefault();
@@ -562,6 +702,25 @@ const createHiddenEditorManager = (deps) => {
 		};
 		const viewStartedAt = performance.now();
 		view = new EditorView(host, editorProps);
+		if (editorSession.type === "canonical") registerClipboardIntentHandler(view, (slice, plain) => {
+			if (!view || editorSession.type !== "canonical") return false;
+			if (deps.getReadOnly()) {
+				deps.onReadOnlyEditAttempt();
+				return false;
+			}
+			syncCanonicalMode();
+			const prepared = prepareCanonicalPaste({
+				session: editorSession.session,
+				state: view.state,
+				slice,
+				plain
+			});
+			if (prepared.isErr()) {
+				if (prepared.error.reason !== "noChange") refuse(prepared.error.message, prepared.error.gap);
+				return false;
+			}
+			return publishCommit(prepared.value);
+		});
 		releaseCommandOwner = registerEditorCommandOwner(view, executeCanonicalCommand);
 		recordHiddenEditorPhase("mount", "editor-view", performance.now() - viewStartedAt);
 		syncHiddenEditorAccessibility(view, deps.getReadOnly());
@@ -594,19 +753,19 @@ const createHiddenEditorManager = (deps) => {
 		if (!view || isDestroying) return;
 		const collaboration = deps.getCollaboration();
 		const collaborationModules = deps.getCollaborationModules();
-		if (collaboration && !collaborationModules && deps.getExperimentalSession?.() !== "canonical") return;
+		if (collaboration && !collaborationModules && !usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting)) return;
 		const document = deps.getDocument();
 		const currentDocId = deps.getDocumentIdentity();
 		const currentCollaborationFragment = collaboration?.yXmlFragment ?? null;
 		const collaborationSourceChanged = currentCollaborationFragment !== lastCollaborationFragment;
-		const sessionChanged = editorSession.type !== "prosemirror" !== (deps.getExperimentalSession?.() === "canonical");
+		const sessionChanged = editorSession.type !== "prosemirror" !== usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting);
 		if (collaboration && !collaborationSourceChanged && !sessionChanged) return;
 		if (isInitialized && currentDocId === lastDocumentId && !collaborationSourceChanged && !sessionChanged) return;
+		input.reset();
 		if (!seedSession(document)) {
 			destroyView();
 			return;
 		}
-		input.reset();
 		isInitialized = true;
 		lastDocumentId = currentDocId;
 		lastCollaborationFragment = currentCollaborationFragment;
@@ -632,7 +791,7 @@ const createHiddenEditorManager = (deps) => {
 	const publishStoryCommit = (storyView, commit) => {
 		if (!view || editorSession.type !== "canonical") return false;
 		if (deps.getEditingMode?.() === "suggesting") {
-			refuse("Suggesting is unavailable in the experimental canonical session.");
+			refuse("Suggesting is unavailable in the experimental canonical session.", CANONICAL_GAP.suggesting);
 			return false;
 		}
 		const session = editorSession.session;
@@ -651,7 +810,7 @@ const createHiddenEditorManager = (deps) => {
 			session
 		});
 		if (staged.isErr()) {
-			refuse(staged.error.message);
+			refuse(staged.error.message, staged.error.gap);
 			return false;
 		}
 		storyView.updateState(staged.value.state);
@@ -664,6 +823,22 @@ const createHiddenEditorManager = (deps) => {
 		deps.onSelectionChange(view.state);
 		return true;
 	};
+	let publicOperations = null;
+	const getPublicOperations = () => {
+		if (editorSession.type !== "canonical") return null;
+		const session = editorSession.session;
+		if (publicOperations?.session === session) return publicOperations.executor;
+		const executor = new CanonicalPublicOperations({
+			session,
+			getState: (story) => story === OP_STORIES.MAIN && !deps.getReadOnly() && !isDestroying ? view?.state ?? null : null,
+			publish: publishCommit
+		});
+		publicOperations = {
+			session,
+			executor
+		};
+		return executor;
+	};
 	return {
 		ensureView,
 		retryViewCreation,
@@ -676,6 +851,8 @@ const createHiddenEditorManager = (deps) => {
 		api: createHiddenEditorApi({
 			getView: () => view,
 			getDocumentContext: () => editorSession.type === "refused" ? null : deps.getDocumentContext(),
+			isCanonicalSaveCurrent: (version) => editorSession.type === "canonical" && !editorSession.session.isComposing && editorSession.session.version === version,
+			captureCanonicalSave: () => editorSession.type === "canonical" ? editorSession.session.captureSaveSnapshot() : null,
 			getCanonicalDocument: () => editorSession.type === "canonical" ? editorSession.session.document : null,
 			setCanonicalMode: (mode) => {
 				if (editorSession.type !== "canonical") return false;
@@ -690,7 +867,7 @@ const createHiddenEditorManager = (deps) => {
 					resolution
 				});
 				if (prepared.isErr()) {
-					if (prepared.error.reason !== "noChange") refuse(prepared.error.message);
+					if (prepared.error.reason !== "noChange") refuse(prepared.error.message, prepared.error.gap);
 					return false;
 				}
 				return publishCommit(prepared.value);
@@ -703,6 +880,11 @@ const createHiddenEditorManager = (deps) => {
 				canRedo: () => editorSession.type === "canonical" && editorSession.session.canRedo
 			} : null,
 			canonicalOperations: {
+				applyCanonicalDocumentOperations: (options) => {
+					ensureView();
+					return getPublicOperations()?.apply(options) ?? null;
+				},
+				undoCanonicalDocumentOperations: (handle) => getPublicOperations()?.undo(handle) ?? null,
 				updateCanonicalInputLifecycle: (action) => {
 					if (editorSession.type !== "canonical") return false;
 					switch (action) {
@@ -736,7 +918,7 @@ const createHiddenEditorManager = (deps) => {
 					if (direction === "undo" ? !session.canUndo : !session.canRedo) return false;
 					const prepared = direction === "undo" ? session.prepareUndo(storyView.state, story) : session.prepareRedo(storyView.state, story);
 					if (prepared.isErr()) {
-						refuse(prepared.error.message);
+						refuse(prepared.error.message, prepared.error.gap);
 						return false;
 					}
 					return publishStoryCommit(storyView, prepared.value);
@@ -746,17 +928,17 @@ const createHiddenEditorManager = (deps) => {
 					if (!view || editorSession.type !== "canonical" || deps.getReadOnly()) return false;
 					const prepared = editorSession.session.prepareOperations(view.state, ops);
 					if (prepared.isErr()) {
-						refuse(prepared.error.message);
+						refuse(prepared.error.message, prepared.error.gap);
 						return false;
 					}
 					return publishCommit(prepared.value);
 				},
 				getCanonicalStoryProjection: (story) => {
-					if (deps.getExperimentalSession?.() === "canonical") ensureView();
+					if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting)) ensureView();
 					if (editorSession.type !== "canonical" || editorSession.session.isComposing) return null;
 					const result = editorSession.session.projectStory(story);
 					if (result.isErr()) {
-						refuse(result.error.message);
+						refuse(result.error.message, result.error.gap);
 						return null;
 					}
 					return result.value.doc;
@@ -768,7 +950,7 @@ const createHiddenEditorManager = (deps) => {
 						story
 					});
 					if (prepared.isErr()) {
-						refuse(prepared.error.message);
+						refuse(prepared.error.message, prepared.error.gap);
 						return false;
 					}
 					return publishStoryCommit(storyView, prepared.value);

package/dist/controller/noteEditorManager.d.ts

@@ -1,4 +1,5 @@
 import { document_d_exports } from "../types/document.js";
+import { CanonicalGap } from "../types/canonicalCapabilities.js";
 import { HiddenEditorApi } from "./hiddenEditorApi.js";
 import { NoteStoryKey } from "../types/editor-story.js";
 import { Plugin } from "prosemirror-state";
@@ -15,7 +16,7 @@ type NoteEditorManagerDeps = {
   getDocument: () => document_d_exports.Document | null;
   getCanonicalApi?: (() => HiddenEditorApi | null) | undefined;
   getExperimentalSession?: (() => "canonical" | undefined) | undefined;
-  onSessionRefusal?: ((reason: string) => void) | undefined;
+  onSessionRefusal?: ((reason: string, gap: CanonicalGap) => void) | undefined;
   getHost: () => HTMLElement | null;
   getPlugins?: (() => Plugin[]) | undefined;
   getStyles: () => document_d_exports.StyleDefinitions | null | undefined;

package/dist/controller/noteEditorManager.js

@@ -11,6 +11,7 @@ import { createDocumentNumberingPlugin } from "../prosemirror/plugins/documentNu
 import { createDocumentStylesPlugin } from "../prosemirror/plugins/documentStyles.js";
 import { schema } from "../prosemirror/schema/index.js";
 import { storyListNumbering } from "../prosemirror/storyListNumbering.js";
+import { CANONICAL_GAP, usesCanonicalSession } from "../types/canonicalCapabilities.js";
 import { createCanonicalStoryEditor } from "./canonicalStoryEditor.js";
 import { OP_STORIES } from "@stll/docx-core/ops";
 import { EditorState, TextSelection } from "prosemirror-state";
@@ -90,8 +91,8 @@ const createNoteEditorManager = (deps) => {
 	const sync = () => {
 		const host = deps.getHost();
 		if (!host) return;
-		if (deps.getExperimentalSession?.() === "canonical" && !deps.getCanonicalApi?.()?.getCanonicalStoryProjection(OP_STORIES.MAIN)) return;
-		const document = deps.getExperimentalSession?.() === "canonical" ? deps.getCanonicalApi?.()?.getCanonicalDocument() ?? deps.getDocument() : deps.getDocument();
+		if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories) && !deps.getCanonicalApi?.()?.getCanonicalStoryProjection(OP_STORIES.MAIN)) return;
+		const document = usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories) ? deps.getCanonicalApi?.()?.getCanonicalDocument() ?? deps.getDocument() : deps.getDocument();
 		const styles = deps.getStyles();
 		const theme = deps.getTheme();
 		const numbering = document?.package.numbering;
@@ -115,7 +116,7 @@ const createNoteEditorManager = (deps) => {
 			const existing = mounted.get(key);
 			if (existing) {
 				if (existing.mountNode.parentElement !== host) host.append(existing.mountNode);
-				if (deps.getExperimentalSession?.() === "canonical") {
+				if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories)) {
 					const projected = deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
 						kind: storyKey.kind,
 						id: storyKey.noteId
@@ -175,7 +176,7 @@ const createNoteEditorManager = (deps) => {
 				},
 				getView: () => view,
 				getApi: () => deps.getCanonicalApi?.() ?? null,
-				enabled: () => deps.getExperimentalSession?.() === "canonical",
+				enabled: () => usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories),
 				onRefusal: deps.onSessionRefusal,
 				onSelectionChange: () => deps.onTransaction?.({
 					...storyKey,
@@ -184,11 +185,11 @@ const createNoteEditorManager = (deps) => {
 					selectionChanged: true
 				})
 			});
-			const canonicalProjection = deps.getExperimentalSession?.() === "canonical" ? deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
+			const canonicalProjection = usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories) ? deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
 				kind: storyKey.kind,
 				id: storyKey.noteId
 			}) : null;
-			if (deps.getExperimentalSession?.() === "canonical" && !canonicalProjection) {
+			if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories) && !canonicalProjection) {
 				manager.destroy();
 				mountNode.remove();
 				continue;
@@ -246,7 +247,7 @@ const createNoteEditorManager = (deps) => {
 		getView: (story) => mounted.get(storyMapKey(story))?.view ?? null,
 		listStories: () => enumerateDocumentNoteStories(deps.getDocument()),
 		snapshotDocument: (document) => {
-			if (deps.getExperimentalSession?.() === "canonical") return deps.getCanonicalApi?.()?.getCanonicalDocument() ?? document;
+			if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories)) return deps.getCanonicalApi?.()?.getCanonicalDocument() ?? document;
 			let footnotes = document.package.footnotes;
 			let endnotes = document.package.endnotes;
 			let footnotesChanged = false;

package/dist/document-operations.d.ts

@@ -132,6 +132,7 @@ type FolioDocumentOperationIssue = {
   code: FolioAIEditSkippedOperation["reason"];
   retryable: boolean;
   recovery: FolioDocumentOperationRecovery;
+  canonicalRefusal?: FolioAIEditSkippedOperation["canonicalRefusal"];
   /** The skip's detail, when it has one; see {@link FolioAIEditSkippedOperation.message}. */
   message?: string;
 };
@@ -264,6 +265,12 @@ type FolioDocumentOperationResult = (FolioDocumentOperationResultBase & {
 declare const getFolioDocumentOperationIssues: (operations: readonly FolioDocumentOperation[], skipped: readonly FolioAIEditSkippedOperation[]) => FolioDocumentOperationIssue[];
 /** Build deterministic affected-target receipts from operations and their applied entries. */
 declare const getFolioDocumentOperationReceipts: (operations: readonly FolioDocumentOperation[], applied: readonly FolioAIEditAppliedOperation[]) => FolioDocumentOperationReceipt[];
+type GetFolioDocumentOperationReceiptsForStoryOptions = {
+  operations: readonly FolioDocumentOperation[];
+  applied: readonly FolioAIEditAppliedOperation[];
+  story: FolioDocumentOperationStory;
+};
+declare const getFolioDocumentOperationReceiptsForStory: ({ operations, applied, story }: GetFolioDocumentOperationReceiptsForStoryOptions) => FolioDocumentOperationReceipt[];
 type ApplyFolioDocumentOperationsOptions = {
   view: FolioAIEditView;
   snapshot: FolioAIEditSnapshot;
@@ -301,4 +308,4 @@ type ApplyFolioDocumentOperationsOptions = {
 };
 declare const applyFolioDocumentOperations: ({ view, snapshot, batch, story, author, createCommentId, createUndoHandle, revisionStamp, wordDiff, tableTemplates, replacementBackground, undefinedStyles }: ApplyFolioDocumentOperationsOptions) => FolioDocumentOperationResult;
 //#endregion
-export { ApplyFolioDocumentOperationsOptions, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PAGE_BREAK_CLEAR_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationBatchPrecondition, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationQueuedOperation, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationResultBase, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };
+export { ApplyFolioDocumentOperationsOptions, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PAGE_BREAK_CLEAR_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationBatchPrecondition, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationQueuedOperation, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationResultBase, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOperationReceiptsForStory, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };

package/dist/document-operations.js

@@ -1072,22 +1072,24 @@ const recoveryByReason = {
 	missingStyle: "refreshDocument",
 	missingNumbering: "refreshDocument",
 	invalidResult: "refreshDocument",
-	pendingDeletion: "resolveTrackedChange"
+	pendingDeletion: "resolveTrackedChange",
+	pendingParagraphMarkDeletion: "resolveTrackedChange"
 };
 const getFolioDocumentOperationIssues = (operations, skipped) => {
 	const indexById = /* @__PURE__ */ new Map();
 	operations.forEach(({ id }, index) => {
 		indexById.set(id, index);
 	});
-	return skipped.map(({ id, reason, message }) => {
+	return skipped.map(({ id, reason, message, canonicalRefusal }) => {
 		const operationIndex = indexById.get(id) ?? -1;
 		return {
 			operationId: id,
 			operationIndex,
 			path: `$.operations[${operationIndex}]`,
 			code: reason,
-			retryable: reason !== "emptyOperation" && reason !== "noopOperation" && reason !== "pendingParagraphPropertyChange" && reason !== "pendingRunPropertyChange" && reason !== "pendingDeletion" && reason !== "payloadDoesNotFit" && reason !== "protectedReference" && reason !== "invalidResult",
+			retryable: reason !== "emptyOperation" && reason !== "noopOperation" && reason !== "pendingParagraphPropertyChange" && reason !== "pendingRunPropertyChange" && reason !== "pendingDeletion" && reason !== "pendingParagraphMarkDeletion" && reason !== "payloadDoesNotFit" && reason !== "protectedReference" && reason !== "invalidResult",
 			recovery: recoveryByReason[reason],
+			...canonicalRefusal === void 0 ? {} : { canonicalRefusal },
 			...message !== void 0 && { message }
 		};
 	});
@@ -1468,4 +1470,4 @@ const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", a
 	};
 };
 //#endregion
-export { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PAGE_BREAK_CLEAR_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };
+export { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PAGE_BREAK_CLEAR_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOperationReceiptsForStory, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };

package/dist/docx/blockPlainText.d.ts

@@ -1,6 +1,6 @@
 import { document_d_exports } from "../types/document.js";
 //#region src/docx/blockPlainText.d.ts
-/** One entry per block, so callers can join or count lines as they need. */
+/** One entry per accepted block; deleted breaks and table structure resolve together. */
 declare const collectBlockTexts: (blocks: readonly document_d_exports.BlockContent[]) => string[];
 declare const blockPlainText: (blocks: readonly document_d_exports.BlockContent[]) => string;
 //#endregion