@stll/folio-core 0.55.0 → 0.57.0

package/dist/controller/canonicalStoryEditor.d.ts

@@ -1,3 +1,4 @@
+import { CanonicalGap } from "../types/canonicalCapabilities.js";
 import { HiddenEditorApi } from "./hiddenEditorApi.js";
 import { Transaction } from "prosemirror-state";
 import { EditorView } from "prosemirror-view";
@@ -9,7 +10,7 @@ type CanonicalStoryEditorOptions = {
   getApi: () => HiddenEditorApi | null;
   enabled: () => boolean;
   onSelectionChange: () => void;
-  onRefusal: ((reason: string) => void) | undefined;
+  onRefusal: ((reason: string, gap: CanonicalGap) => void) | undefined;
 };
 /** Secondary views compile classified native input into the shared Document journal. */
 declare const createCanonicalStoryEditor: ({ story, getView, getApi, enabled, onRefusal, onSelectionChange }: CanonicalStoryEditorOptions) => {
@@ -18,14 +19,17 @@ declare const createCanonicalStoryEditor: ({ story, getView, getApi, enabled, on
     handleKeyDown: (view: EditorView, event: KeyboardEvent) => boolean;
     handleTextInput: (view: EditorView, from: number, to: number, text: string) => boolean;
     handleDOMEvents: {
+      keydown: (view: EditorView, event: KeyboardEvent) => boolean;
+      keyup: (view: EditorView, event: KeyboardEvent) => boolean;
+      mouseup: (view: EditorView) => boolean;
       beforeinput: (view: EditorView, event: InputEvent) => boolean;
       mousedown: (view: EditorView) => boolean;
       compositionstart: (view: EditorView) => boolean;
       compositionend: (view: EditorView) => boolean;
       input: (view: EditorView) => boolean;
       blur: (view: EditorView) => boolean;
-      paste: (view: EditorView, event: Event) => boolean;
-      cut: (view: EditorView, event: Event) => boolean;
+      paste: (view: EditorView, event: ClipboardEvent) => boolean;
+      cut: (view: EditorView, event: ClipboardEvent) => boolean;
       drop: (view: EditorView, event: Event) => boolean;
     };
   };

package/dist/controller/canonicalStoryEditor.js

@@ -1,11 +1,16 @@
+import { CANONICAL_GAP } from "../types/canonicalCapabilities.js";
 import { createCanonicalInputBoundary } from "./canonicalInput.js";
 import { CanonicalSessionError } from "./canonicalSession.js";
+import { AllSelection, TextSelection } from "prosemirror-state";
 //#region src/controller/canonicalStoryEditor.ts
 /** Secondary views compile classified native input into the shared Document journal. */
 const createCanonicalStoryEditor = ({ story, getView, getApi, enabled, onRefusal, onSelectionChange }) => {
-	const refuse = (message) => {
-		if (onRefusal) onRefusal(message);
+	const refuse = (reason) => {
+		const gap = CANONICAL_GAP.dispatch;
+		const message = reason;
+		if (onRefusal) onRefusal(message, gap);
 		else throw new CanonicalSessionError({
+			gap,
 			message,
 			reason: "refused"
 		});
@@ -20,6 +25,17 @@ const createCanonicalStoryEditor = ({ story, getView, getApi, enabled, onRefusal
 		if (accepted && !view.isDestroyed) onSelectionChange();
 		return accepted;
 	};
+	const syncNativeSelection = (view) => {
+		if (boundary.isComposing || view.composing) return;
+		const selection = view.dom.ownerDocument.getSelection();
+		if (!selection?.anchorNode || !selection.focusNode || !view.dom.contains(selection.anchorNode) || !view.dom.contains(selection.focusNode)) return;
+		const anchor = view.posAtDOM(selection.anchorNode, selection.anchorOffset);
+		const head = view.posAtDOM(selection.focusNode, selection.focusOffset);
+		if (view.state.selection instanceof AllSelection && Math.min(anchor, head) === 0 && Math.max(anchor, head) === view.state.doc.content.size) return;
+		if (anchor === view.state.selection.anchor && head === view.state.selection.head) return;
+		if (!view.state.doc.resolve(anchor).parent.inlineContent || !view.state.doc.resolve(head).parent.inlineContent) return;
+		view.dispatch(view.state.tr.setSelection(TextSelection.create(view.state.doc, anchor, head)));
+	};
 	const boundary = createCanonicalInputBoundary({
 		breakUndoGroup: () => {
 			getApi()?.updateCanonicalInputLifecycle("breakUndoGroup");
@@ -65,6 +81,15 @@ const createCanonicalStoryEditor = ({ story, getView, getApi, enabled, onRefusal
 			handleKeyDown: (view, event) => enabled() && boundary.handleKeyDown(view, event),
 			handleTextInput: (view, from, to, text) => enabled() && boundary.handleTextInput(view, from, to, text),
 			handleDOMEvents: {
+				keydown: (view, event) => enabled() && boundary.handleDOMEvents.keydown(view, event),
+				keyup: (view, event) => {
+					if (enabled() && /^(?:Arrow|Home$|End$|Page)/u.test(event.key)) syncNativeSelection(view);
+					return false;
+				},
+				mouseup: (view) => {
+					if (enabled()) syncNativeSelection(view);
+					return false;
+				},
 				beforeinput: (view, event) => enabled() && boundary.handleDOMEvents.beforeinput(view, event),
 				mousedown: (view) => enabled() && boundary.handleDOMEvents.mousedown(view),
 				compositionstart: (view) => enabled() && boundary.handleDOMEvents.compositionstart(view),

package/dist/controller/canonicalStructure.js

@@ -1,11 +1,17 @@
+import { BUILT_IN_STYLE_NAME, createBuiltInStyleIndex } from "../docx/builtInStyles.js";
 import { getCachedNumberingMap, numberingLevelUsesBulletMarker } from "../docx/numberingParser.js";
 import { listRequestsForMarker } from "../prosemirror/listAutoformatMarkers.js";
+import { CANONICAL_GAP } from "../types/canonicalCapabilities.js";
+import { collectHeadings } from "../utils/headingCollector.js";
 import { CanonicalSessionError } from "./canonicalSession.js";
 import { Result } from "better-result";
-import { paragraphNumberingReference } from "@stll/docx-core/model";
+import { headingOutlineLevel, paragraphNumberingReference } from "@stll/docx-core/model";
 import { OP_STORIES } from "@stll/docx-core/ops";
 //#region src/controller/canonicalStructure.ts
+const DEFAULT_TOC_PAGE_WIDTH_TWIPS = 12240;
+const DEFAULT_TOC_MARGIN_TWIPS = 1440;
 const refuse = (message) => Result.err(new CanonicalSessionError({
+	gap: CANONICAL_GAP.commands,
 	message,
 	reason: "refused"
 }));
@@ -84,6 +90,53 @@ const prepareCanonicalCommands = (session, state, commands) => {
 	const intents = [];
 	const paragraphs = selectedParagraphs(session, state);
 	for (const command of commands) switch (command.type) {
+		case "generateTOC": {
+			const at = session.projection.addressAt(command.at);
+			if (at.isErr()) return at;
+			const definitions = session.document.package.styles;
+			const styles = createBuiltInStyleIndex(definitions?.styles ?? [], definitions?.docDefaults);
+			const headings = [];
+			for (const heading of collectHeadings(session.projection.doc, styles)) {
+				const address = session.projection.addressAt(heading.pmPos + 1);
+				if (address.isErr()) return address;
+				const outline = headingOutlineLevel(heading.level);
+				if (outline?.kind !== "heading") return refuse("A TOC heading has an invalid outline level.");
+				const styleId = styles.styleIdForTableOfContentsLevel(outline.level + 1);
+				headings.push({
+					blockId: address.value.blockId,
+					text: heading.text,
+					level: outline.level,
+					...styleId === void 0 ? {} : { styleId }
+				});
+			}
+			if (headings.length === 0) break;
+			const titleStyleId = styles.styleIdForBuiltInName(BUILT_IN_STYLE_NAME.tocHeading);
+			const section = session.document.package.document.content.find((item) => item.type === "paragraph" && (item.sectionProperties?.pageWidth ?? 0) > 0);
+			const properties = section?.type === "paragraph" ? section.sectionProperties : void 0;
+			intents.push({
+				type: "generateTOC",
+				at: at.value,
+				title: command.title,
+				headings,
+				tabPosition: (properties?.pageWidth ?? DEFAULT_TOC_PAGE_WIDTH_TWIPS) - (properties?.marginLeft ?? DEFAULT_TOC_MARGIN_TWIPS) - (properties?.marginRight ?? DEFAULT_TOC_MARGIN_TWIPS),
+				...titleStyleId === void 0 ? {} : { titleStyleId }
+			});
+			break;
+		}
+		case "setHyperlink":
+		case "removeHyperlink":
+		case "insertHyperlink": {
+			const from = session.projection.addressAt(command.from);
+			if (from.isErr()) return from;
+			const to = session.projection.addressAt(command.to);
+			if (to.isErr()) return to;
+			intents.push({
+				...command,
+				from: from.value,
+				to: to.value
+			});
+			break;
+		}
 		case "insertBreak": {
 			const from = session.projection.addressAt(command.from);
 			if (from.isErr()) return from;
@@ -233,7 +286,7 @@ const prepareCanonicalCommands = (session, state, commands) => {
 		}
 		default: return command;
 	}
-	return session.prepareIntents(state, intents);
+	return session.prepareIntents(state, { intents });
 };
 /** Rules compile their replacement and paragraph change as one atomic edit. */
 const prepareCanonicalAutoformat = (session, state, { from, to, text }) => {
@@ -254,7 +307,7 @@ const prepareCanonicalAutoformat = (session, state, { from, to, text }) => {
 	const request = requests?.at(0);
 	const styleId = `Heading${heading?.length ?? 1}`;
 	if (request === void 0 && !session.hasStyle(styleId)) return void 0;
-	return session.prepareIntents(state, [{
+	return session.prepareIntents(state, { intents: [{
 		type: "replaceText",
 		from: start,
 		to: at.value,
@@ -263,7 +316,7 @@ const prepareCanonicalAutoformat = (session, state, { from, to, text }) => {
 		type: "formatParagraph",
 		at: start,
 		patch: { styleId }
-	} : numberingIntent(session, [source], request)]);
+	} : numberingIntent(session, [source], request)] });
 };
 //#endregion
 export { prepareCanonicalAutoformat, prepareCanonicalCommands };

package/dist/controller/canonicalTocSelection.d.ts

@@ -0,0 +1,11 @@
+import { DocumentOp, TextPosition } from "@stll/docx-core/ops";
+//#region src/controller/canonicalTocSelection.d.ts
+type TocSelectionMapping = {
+  at: TextPosition;
+  after: TextPosition;
+  ops: readonly DocumentOp[];
+};
+/** TOC insertion retains the selected text and maps its endpoints through the canonical split. */
+declare const mapTocSelection: (point: TextPosition, { at, after, ops }: TocSelectionMapping) => TextPosition;
+//#endregion
+export { mapTocSelection };

package/dist/controller/canonicalTocSelection.js

@@ -0,0 +1,43 @@
+import { panic } from "better-result";
+import { DOCUMENT_OP_TYPES, SPLIT_HALVES, compareGaps, idKey, mapTocBookmarkPosition, sameStory } from "@stll/docx-core/ops";
+//#region src/controller/canonicalTocSelection.ts
+/** TOC insertion retains the selected text and maps its endpoints through the canonical split. */
+const mapTocSelection = (point, { at, after, ops }) => {
+	if (!sameStory(point.story, at.story)) return point;
+	point = mapTocBookmarkPosition({
+		...point,
+		zeroWidthBefore: point.zeroWidthBefore ?? 0
+	}, ops);
+	at = mapTocBookmarkPosition({
+		...at,
+		zeroWidthBefore: at.zeroWidthBefore ?? 0
+	}, ops);
+	if (idKey(point.blockId) !== idKey(at.blockId)) return point;
+	const split = ops.find((op) => op.type === DOCUMENT_OP_TYPES.SPLIT_BLOCK);
+	if (split === void 0) return point;
+	if (point.offset === at.offset && (point.zeroWidthBefore ?? 0) === (at.zeroWidthBefore ?? 0)) return after;
+	if (split.type !== DOCUMENT_OP_TYPES.SPLIT_BLOCK || split.newHalf !== SPLIT_HALVES.FIRST) return panic("TOC insertion must retain its following paragraph identity.");
+	const pointGap = {
+		offset: point.offset,
+		zeroWidthBefore: point.zeroWidthBefore ?? 0
+	};
+	const splitGap = {
+		offset: split.at.offset,
+		zeroWidthBefore: split.at.zeroWidthBefore ?? 0
+	};
+	if (compareGaps(pointGap, splitGap) < 0) return {
+		...point,
+		blockId: split.newBlockId
+	};
+	if (point.offset === split.at.offset) return {
+		...point,
+		offset: 0,
+		zeroWidthBefore: pointGap.zeroWidthBefore - splitGap.zeroWidthBefore
+	};
+	return {
+		...point,
+		offset: point.offset - split.at.offset
+	};
+};
+//#endregion
+export { mapTocSelection };

package/dist/controller/folioEditor.d.ts

@@ -1,5 +1,6 @@
 import { document_d_exports } from "../types/document.js";
 import { DocxInput } from "../utils/docxInput.js";
+import { FOLIO_DOCX_SERIALIZATION_MODE, FolioDocxSerializationMode, FolioGetDocxOptions } from "../types/docxSerialization.js";
 import { Layout } from "../layout-engine/types.js";
 import { FolioEditorEmitter } from "./folioEditorEvents.js";
 import { HiddenEditorApi } from "./hiddenEditorApi.js";
@@ -14,14 +15,6 @@ type FolioEditorDeps = {
   getDocumentIO?: () => FolioEditorDocumentIO;
   emitter: FolioEditorEmitter;
 };
-declare const FOLIO_DOCX_SERIALIZATION_MODE: Readonly<{
-  readonly full: "full";
-  readonly preferSelective: "prefer-selective";
-}>;
-type FolioDocxSerializationMode = (typeof FOLIO_DOCX_SERIALIZATION_MODE)[keyof typeof FOLIO_DOCX_SERIALIZATION_MODE];
-type FolioGetDocxOptions = {
-  mode?: FolioDocxSerializationMode;
-};
 /**
  * Document lifecycle operations supplied by a host integration.
  *
@@ -45,4 +38,4 @@ type FolioEditor = HiddenEditorApi & {
 };
 declare const createFolioEditor: (deps: FolioEditorDeps) => FolioEditor;
 //#endregion
-export { FOLIO_DOCX_SERIALIZATION_MODE, FolioDocxSerializationMode, FolioEditor, FolioEditorDeps, FolioEditorDocumentIO, FolioGetDocxOptions, createFolioEditor };
+export { FOLIO_DOCX_SERIALIZATION_MODE, type FolioDocxSerializationMode, FolioEditor, FolioEditorDeps, FolioEditorDocumentIO, type FolioGetDocxOptions, createFolioEditor };

package/dist/controller/folioEditor.js

@@ -1,9 +1,7 @@
+import { CANONICAL_GAP } from "../types/canonicalCapabilities.js";
+import { FOLIO_DOCX_SERIALIZATION_MODE } from "../types/docxSerialization.js";
 import { panic } from "better-result";
 //#region src/controller/folioEditor.ts
-const FOLIO_DOCX_SERIALIZATION_MODE = Object.freeze({
-	full: "full",
-	preferSelective: "prefer-selective"
-});
 const createFolioEditor = (deps) => {
 	const getDocumentIO = () => deps.getDocumentIO?.() ?? panic("FolioEditor document I/O requires a getDocumentIO dependency");
 	return {
@@ -17,10 +15,26 @@ const createFolioEditor = (deps) => {
 		getDocument: () => deps.getEditorApi()?.getDocument() ?? null,
 		updateCanonicalInputLifecycle: (action) => deps.getEditorApi()?.updateCanonicalInputLifecycle(action) ?? false,
 		applyCanonicalStoryHistory: (options) => deps.getEditorApi()?.applyCanonicalStoryHistory(options) ?? false,
+		applyCanonicalComment: (request) => deps.getEditorApi()?.applyCanonicalComment(request) ?? null,
+		applyCanonicalSectionProperties: (patch) => {
+			const api = deps.getEditorApi();
+			if (!api) return {
+				status: "refused",
+				gap: CANONICAL_GAP.sectionProperties,
+				message: "The editor is not ready for section changes."
+			};
+			return api.applyCanonicalSectionProperties(patch);
+		},
 		applyCanonicalOperations: (ops) => deps.getEditorApi()?.applyCanonicalOperations(ops) ?? false,
 		getCanonicalStorySelection: (story) => deps.getEditorApi()?.getCanonicalStorySelection(story) ?? null,
 		getCanonicalStoryProjection: (story) => deps.getEditorApi()?.getCanonicalStoryProjection(story) ?? null,
 		replaceCanonicalStoryText: (options) => deps.getEditorApi()?.replaceCanonicalStoryText(options) ?? false,
+		isCanonicalSaveCurrent: (version) => deps.getEditorApi()?.isCanonicalSaveCurrent(version) ?? false,
+		captureCanonicalSave: () => deps.getEditorApi()?.captureCanonicalSave() ?? null,
+		applyCanonicalDocumentOperations: (options) => deps.getEditorApi()?.applyCanonicalDocumentOperations(options) ?? null,
+		undoCanonicalDocumentOperations: (handle) => deps.getEditorApi()?.undoCanonicalDocumentOperations(handle) ?? null,
+		getCanonicalComments: () => deps.getEditorApi()?.getCanonicalComments() ?? null,
+		getCanonicalCommittedVersion: () => deps.getEditorApi()?.getCanonicalCommittedVersion() ?? null,
 		getCanonicalDocument: () => deps.getEditorApi()?.getCanonicalDocument() ?? null,
 		setCanonicalMode: (mode) => deps.getEditorApi()?.setCanonicalMode(mode) ?? false,
 		resolveCanonicalRevisions: (revisionIds, resolution) => deps.getEditorApi()?.resolveCanonicalRevisions(revisionIds, resolution) ?? false,

package/dist/controller/headerFooterEditorManager.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 { DirectEditorProps, EditorView } from "prosemirror-view";
 //#region src/controller/headerFooterEditorManager.d.ts
@@ -19,7 +20,7 @@ type HeaderFooterEditorManagerDeps = {
   getDocument: () => document_d_exports.Document | null;
   getCanonicalApi?: (() => HiddenEditorApi | null) | undefined;
   getExperimentalSession?: (() => "canonical" | undefined) | undefined;
-  onSessionRefusal?: ((reason: string) => void) | undefined;
+  onSessionRefusal?: ((reason: string, gap: CanonicalGap, error?: Error) => void) | undefined;
   getHost: () => HTMLElement | null;
   getStyles: () => document_d_exports.StyleDefinitions | null | undefined;
   getTheme: () => document_d_exports.Theme | null | undefined;

package/dist/controller/headerFooterEditorManager.js

@@ -6,10 +6,13 @@ import { ExtensionManager } from "../prosemirror/extensions/ExtensionManager.js"
 import { createStarterKit } from "../prosemirror/extensions/StarterKit.js";
 import { ensureBaseDirectionInState } from "../prosemirror/extensions/features/AutoBidiDetectionExtension.js";
 import { ensureParaIdsInState } from "../prosemirror/extensions/features/ParaIdAllocatorExtension.js";
+import { noteReferenceTransactionIssue } from "../prosemirror/noteReferenceOccurrences.js";
 import { createDocumentNumberingPlugin } from "../prosemirror/plugins/documentNumbering.js";
-import { createDocumentStylesPlugin } from "../prosemirror/plugins/documentStyles.js";
+import { createDocumentStyleContextPlugin, 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 { CanonicalSessionError } from "./canonicalSession.js";
 import { createCanonicalStoryEditor } from "./canonicalStoryEditor.js";
 import { OP_STORIES } from "@stll/docx-core/ops";
 import { EditorState, TextSelection } from "prosemirror-state";
@@ -84,11 +87,12 @@ const createHeaderFooterEditorManager = (deps) => {
 		for (const part of mounted.values()) destroyMounted(part);
 		mounted.clear();
 	};
+	const getOwnedDocument = () => usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting) ? deps.getCanonicalApi?.()?.getCanonicalDocument() ?? null : deps.getDocument();
 	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.authorityRouting) && !deps.getCanonicalApi?.()?.getCanonicalStoryProjection(OP_STORIES.MAIN)) return;
+		const document = getOwnedDocument();
 		const styles = deps.getStyles();
 		const theme = deps.getTheme();
 		const numbering = document?.package.numbering;
@@ -104,7 +108,7 @@ const createHeaderFooterEditorManager = (deps) => {
 			const existing = mounted.get(part.rId);
 			if (existing) {
 				if (existing.mountNode.parentElement !== host) host.append(existing.mountNode);
-				if (deps.getExperimentalSession?.() === "canonical") {
+				if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting)) {
 					const projected = deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
 						kind: part.kind,
 						rId: part.rId
@@ -154,7 +158,7 @@ const createHeaderFooterEditorManager = (deps) => {
 				},
 				getView: () => view,
 				getApi: () => deps.getCanonicalApi?.() ?? null,
-				enabled: () => deps.getExperimentalSession?.() === "canonical",
+				enabled: () => usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting),
 				onRefusal: deps.onSessionRefusal,
 				onSelectionChange: () => deps.onTransaction?.({
 					kind: part.kind,
@@ -164,11 +168,11 @@ const createHeaderFooterEditorManager = (deps) => {
 					selectionChanged: true
 				})
 			});
-			const canonicalProjection = deps.getExperimentalSession?.() === "canonical" ? deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
+			const canonicalProjection = usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting) ? deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
 				kind: part.kind,
 				rId: part.rId
 			}) : null;
-			if (deps.getExperimentalSession?.() === "canonical" && !canonicalProjection) {
+			if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting) && !canonicalProjection) {
 				manager.destroy();
 				mountNode.remove();
 				continue;
@@ -177,16 +181,19 @@ const createHeaderFooterEditorManager = (deps) => {
 				...canonical.props,
 				state: canonicalProjection ? EditorState.create({
 					doc: canonicalProjection,
-					plugins: [createDocumentStylesPlugin(styles), createDocumentNumberingPlugin(numbering)]
+					plugins: [createDocumentStyleContextPlugin(styles), createDocumentNumberingPlugin(numbering)]
 				}) : buildInitialState(headerFooter, styles, theme, numbering, manager),
 				dispatchTransaction(transaction) {
 					if (canonical.dispatch(transaction)) return;
 					const nextState = view.state.apply(transaction);
+					const docChanged = !nextState.doc.eq(view.state.doc);
+					const noteIssue = noteReferenceTransactionIssue(transaction);
+					if (noteIssue) deps.onSessionRefusal?.(noteIssue.message, CANONICAL_GAP.dispatch, noteIssue);
 					view.updateState(nextState);
 					const mountedPart = mounted.get(part.rId);
-					if (mountedPart && transaction.docChanged) mountedPart.dirty = true;
+					if (mountedPart && docChanged) mountedPart.dirty = true;
 					deps.onTransaction?.({
-						docChanged: transaction.docChanged,
+						docChanged,
 						kind: part.kind,
 						rId: part.rId,
 						selectionChanged: transaction.selectionSet,
@@ -217,7 +224,15 @@ const createHeaderFooterEditorManager = (deps) => {
 			rId
 		})),
 		snapshotDocument: (document) => {
-			if (deps.getExperimentalSession?.() === "canonical") return deps.getCanonicalApi?.()?.getCanonicalDocument() ?? document;
+			if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting)) {
+				const canonical = deps.getCanonicalApi?.()?.getCanonicalDocument();
+				if (canonical) return canonical;
+				throw new CanonicalSessionError({
+					gap: CANONICAL_GAP.authorityRouting,
+					reason: "refused",
+					message: "Canonical story snapshot is unavailable."
+				});
+			}
 			let headers = document.package.headers;
 			let footers = document.package.footers;
 			let headersChanged = false;

package/dist/controller/hiddenEditorApi.d.ts

@@ -1,10 +1,16 @@
 import { document_d_exports } from "../types/document.js";
-import { createCanonicalInputBoundary } from "./canonicalInput.js";
+import { FolioDocumentOperationResult, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult } from "../document-operations.js";
+import { Comment } from "../types/content.js";
+import { CanonicalSaveSnapshot } from "../types/canonicalSave.js";
 import { CanonicalSessionMode } from "./canonicalSession.js";
+import { createCanonicalInputBoundary } from "./canonicalInput.js";
+import { CanonicalPublicOperationOptions } from "./canonicalPublicOperations.js";
+import { CanonicalSectionPropertiesResult } from "../types/canonicalSections.js";
+import { CanonicalCommentRequest, CanonicalCommentResult } from "../types/canonicalComments.js";
 import { Node } from "prosemirror-model";
 import { Command, EditorState, Transaction } from "prosemirror-state";
 import { EditorView } from "prosemirror-view";
-import { DocumentOp, OpStory } from "@stll/docx-core/ops";
+import { DocumentOp, FormattingPatch, OpStory } from "@stll/docx-core/ops";
 //#region src/controller/hiddenEditorApi.d.ts
 type CanonicalStoryHistoryOptions = {
   view: EditorView;
@@ -28,7 +34,13 @@ type HiddenEditorApi = {
   /** Get the current Document from PM state */
   getDocument: () => document_d_exports.Document | null;
   /** Canonical snapshot, or null in the default session. */
+  getCanonicalComments: () => Comment[] | null;
+  /** Committed session/version identity; safe during provisional composition. */
+  getCanonicalCommittedVersion: () => string | null;
   getCanonicalDocument: () => document_d_exports.Document | null;
+  captureCanonicalSave: () => CanonicalSaveSnapshot | null;
+  /** A save cannot acknowledge newer edits or an unfinished composition. */
+  isCanonicalSaveCurrent: (version: number) => boolean;
   /** Set the explicit mode for an active canonical session. */
   setCanonicalMode: (mode: CanonicalSessionMode) => boolean;
   /** Resolve canonical revisions as one batch and journal its exact inverse. */
@@ -36,12 +48,17 @@ type HiddenEditorApi = {
   updateCanonicalInputLifecycle: (action: "beginComposition" | "endComposition" | "breakUndoGroup") => boolean;
   applyCanonicalStoryHistory: (options: CanonicalStoryHistoryOptions) => boolean;
   applyCanonicalOperations: (ops: readonly DocumentOp[]) => boolean;
+  applyCanonicalComment: (request: CanonicalCommentRequest) => CanonicalCommentResult | null;
+  /** Apply a final-section patch; null is reserved for default sessions. */
+  applyCanonicalSectionProperties: (patch: FormattingPatch<document_d_exports.SectionProperties>) => CanonicalSectionPropertiesResult | null;
   getCanonicalStorySelection: (story: OpStory) => {
     anchor: number;
     head: number;
   } | null;
   getCanonicalStoryProjection: (story: OpStory) => Node | null;
   replaceCanonicalStoryText: (options: CanonicalStoryTextOptions) => boolean;
+  applyCanonicalDocumentOperations: (options: CanonicalPublicOperationOptions) => FolioDocumentOperationResult | null;
+  undoCanonicalDocumentOperations: (handle: FolioDocumentOperationUndoHandle) => FolioDocumentOperationUndoResult | null;
   /** Focus the hidden editor */
   focus: () => void;
   /** Blur the hidden editor */
@@ -72,12 +89,16 @@ type HiddenEditorApi = {
 type HiddenEditorApiDeps = {
   getView: () => EditorView | null;
   getDocumentContext: () => document_d_exports.Document | null;
+  getCanonicalComments?: () => Comment[] | null;
+  getCanonicalCommittedVersion?: HiddenEditorApi["getCanonicalCommittedVersion"];
   getCanonicalDocument?: () => document_d_exports.Document | null;
+  captureCanonicalSave?: HiddenEditorApi["captureCanonicalSave"];
+  isCanonicalSaveCurrent?: HiddenEditorApi["isCanonicalSaveCurrent"];
   setCanonicalMode?: HiddenEditorApi["setCanonicalMode"];
   resolveCanonicalRevisions?: HiddenEditorApi["resolveCanonicalRevisions"];
   executeCanonicalCommand?: (command: Command) => boolean | undefined;
   getCanonicalHistory?: () => Pick<HiddenEditorApi, "undo" | "redo" | "canUndo" | "canRedo"> | null;
-  canonicalOperations?: Pick<HiddenEditorApi, "updateCanonicalInputLifecycle" | "applyCanonicalOperations" | "getCanonicalStoryProjection" | "replaceCanonicalStoryText" | "applyCanonicalStoryHistory" | "getCanonicalStorySelection">;
+  canonicalOperations?: Pick<HiddenEditorApi, "updateCanonicalInputLifecycle" | "applyCanonicalOperations" | "applyCanonicalComment" | "applyCanonicalSectionProperties" | "getCanonicalStoryProjection" | "replaceCanonicalStoryText" | "applyCanonicalStoryHistory" | "getCanonicalStorySelection" | "applyCanonicalDocumentOperations" | "undoCanonicalDocumentOperations">;
   isDestroying: () => boolean;
   ensureView: () => void;
   isViewRequested: () => boolean;

package/dist/controller/hiddenEditorApi.js

@@ -34,6 +34,10 @@ const createHiddenEditorApi = (deps) => {
 		getView: () => deps.getView() ?? null,
 		setCanonicalMode: (mode) => !deps.isDestroying() && (deps.setCanonicalMode?.(mode) ?? false),
 		resolveCanonicalRevisions: (revisionIds, resolution) => !deps.isDestroying() && (deps.resolveCanonicalRevisions?.(revisionIds, resolution) ?? false),
+		getCanonicalComments: () => deps.getCanonicalComments?.() ?? null,
+		getCanonicalCommittedVersion: () => deps.getCanonicalCommittedVersion?.() ?? null,
+		captureCanonicalSave: () => deps.captureCanonicalSave?.() ?? null,
+		isCanonicalSaveCurrent: (version) => deps.isCanonicalSaveCurrent?.(version) ?? false,
 		getCanonicalDocument: () => {
 			const canonical = deps.getCanonicalDocument?.();
 			return canonical ? cloneDocumentWithParagraphPropertySources(canonical) : null;
@@ -47,10 +51,14 @@ const createHiddenEditorApi = (deps) => {
 		},
 		updateCanonicalInputLifecycle: (action) => deps.canonicalOperations?.updateCanonicalInputLifecycle(action) ?? false,
 		applyCanonicalStoryHistory: (options) => deps.canonicalOperations?.applyCanonicalStoryHistory(options) ?? false,
+		applyCanonicalComment: (request) => deps.canonicalOperations?.applyCanonicalComment(request) ?? null,
+		applyCanonicalSectionProperties: (patch) => deps.canonicalOperations?.applyCanonicalSectionProperties(patch) ?? null,
 		applyCanonicalOperations: (ops) => deps.canonicalOperations?.applyCanonicalOperations(ops) ?? false,
 		getCanonicalStorySelection: (story) => deps.canonicalOperations?.getCanonicalStorySelection(story) ?? null,
 		getCanonicalStoryProjection: (story) => deps.canonicalOperations?.getCanonicalStoryProjection(story) ?? null,
 		replaceCanonicalStoryText: (options) => deps.canonicalOperations?.replaceCanonicalStoryText(options) ?? false,
+		applyCanonicalDocumentOperations: (options) => deps.canonicalOperations?.applyCanonicalDocumentOperations(options) ?? null,
+		undoCanonicalDocumentOperations: (handle) => deps.canonicalOperations?.undoCanonicalDocumentOperations(handle) ?? null,
 		focus: () => {
 			const view = deps.getView();
 			if (!view || view.hasFocus()) return;

package/dist/controller/hiddenEditorManager.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 { HiddenEditorStateReason } from "../layout-engine/layoutInstrumentation.js";
 import { ExtensionManager } from "../prosemirror/extensions/ExtensionManager.js";
@@ -12,6 +13,7 @@ import * as YProseMirror from "y-prosemirror";
 //#region src/controller/hiddenEditorManager.d.ts
 declare const CanonicalSessionRefusalError_base: import("better-result").TaggedErrorClass<"CanonicalSessionRefusalError">;
 declare class CanonicalSessionRefusalError extends CanonicalSessionRefusalError_base<{
+  gap: CanonicalGap;
   message: string;
 }> {}
 type YProseMirrorModule = typeof YProseMirror;
@@ -63,7 +65,7 @@ type HiddenEditorManagerDeps = {
   getExperimentalSession?: () => "canonical" | undefined;
   getEditingMode?: () => EditorMode;
   getSuggestionAuthor?: () => string;
-  onSessionRefusal?: (reason: string) => void;
+  onSessionRefusal?: (reason: string, gap: CanonicalGap, error?: Error) => void;
   /**
    * Identity of the loaded document as tracked by the adapter's loader: the
    * same value across internal edits (so typing does not trigger an external
@@ -97,6 +99,8 @@ declare const createHiddenEditorClipboardHandlers: (deps: Pick<HiddenEditorManag
   paste: (_view: unknown, event: PreventableDomEvent) => boolean;
 };
 type HiddenEditorManager = {
+  /** Whether the canonical owner still holds a provisional composition. */
+  isCanonicalComposing: () => boolean;
   /** Request the view (sets the requested flag, then attempts creation). */
   ensureView: () => void;
   /** Re-attempt a previously-requested-but-deferred creation (no-op otherwise). */