@stll/folio-core 0.56.0 → 0.57.0

package/dist/controller/canonicalSession.js

@@ -1,4 +1,5 @@
 import { splitsGraphemeCluster, splitsSurrogatePair } from "../ai-edits/character-boundaries.js";
+import { rangedCommentIds, visitCommentMarkers } from "../docx/commentAnchorIndex.js";
 import { cloneDocumentWithParagraphPropertySources, copyDocumentParagraphPropertySourceContract, copyParagraphPropertySource } from "../docx/paragraphPropertySource.js";
 import { canonicalSelectionRange } from "../prosemirror/canonicalSelectionRange.js";
 import { collectPairedBookmarkIds, footnoteToProseDoc, headerFooterToProseDoc, toProseDoc } from "../prosemirror/conversion/toProseDoc.js";
@@ -6,11 +7,12 @@ import { markPackageChange } from "../prosemirror/extensions/features/ParagraphC
 import { runFormattingPatchFromMarks } from "../prosemirror/runFormattingFromMarks.js";
 import { CANONICAL_GAP } from "../types/canonicalCapabilities.js";
 import { canonicalInlineSourceIssue, canonicalNativeCells, projectCanonicalInline } from "./canonicalInlineProjection.js";
+import { restoreCanonicalSelection } from "./canonicalSelection.js";
 import { mapTocSelection } from "./canonicalTocSelection.js";
 import { Result, TaggedError, panic } from "better-result";
 import { hasIllegalXmlCharacters } from "@stll/docx-core";
 import { Fragment } from "prosemirror-model";
-import { DOCUMENT_OP_TYPES, OP_STORIES, applyDocumentOps, combineEdits, compileEditorIntent, createEditorIntentIdAllocator, documentStories, editorParagraphGroups, findStoryBody, normalizeForOps, packageParagraphIds, sameStory, validateOpsDocument } from "@stll/docx-core/ops";
+import { DOCUMENT_OP_TYPES, OP_STORIES, applyDocumentOps, combineEdits, commentDocumentIssue, compileEditorIntent, createEditorIntentIdAllocator, documentStories, editorParagraphGroups, findStoryBody, normalizeForOps, packageParagraphIds, sameStory, validateOpsDocument } from "@stll/docx-core/ops";
 import { AllSelection, TextSelection } from "prosemirror-state";
 //#region src/controller/canonicalSession.ts
 var CanonicalSessionError = class extends TaggedError("CanonicalSessionError") {};
@@ -24,8 +26,20 @@ const noChange = (message) => Result.err(new CanonicalSessionError({
 	message,
 	reason: "noChange"
 }));
+const COMMENT_OPERATION_TYPES = /* @__PURE__ */ new Set([
+	DOCUMENT_OP_TYPES.CREATE_COMMENT,
+	DOCUMENT_OP_TYPES.UPDATE_COMMENT_CONTENT,
+	DOCUMENT_OP_TYPES.SET_COMMENT_RESOLUTION,
+	DOCUMENT_OP_TYPES.DELETE_COMMENT,
+	DOCUMENT_OP_TYPES.RESTORE_COMMENT_STATE
+]);
 const operationChangesPackage = (op) => {
 	switch (op.type) {
+		case DOCUMENT_OP_TYPES.CREATE_COMMENT:
+		case DOCUMENT_OP_TYPES.UPDATE_COMMENT_CONTENT:
+		case DOCUMENT_OP_TYPES.SET_COMMENT_RESOLUTION:
+		case DOCUMENT_OP_TYPES.DELETE_COMMENT:
+		case DOCUMENT_OP_TYPES.RESTORE_COMMENT_STATE:
 		case DOCUMENT_OP_TYPES.CREATE_HEADER_FOOTER:
 		case DOCUMENT_OP_TYPES.REMOVE_HEADER_FOOTER:
 		case DOCUMENT_OP_TYPES.ADD_NOTE:
@@ -71,7 +85,7 @@ const operationChangesStructure = (op) => {
 		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.SET_SECTION_ENDPOINT: return true;
 		case DOCUMENT_OP_TYPES.INSERT_TEXT:
 		case DOCUMENT_OP_TYPES.INSERT_CONTENT:
 		case DOCUMENT_OP_TYPES.DELETE_RANGE:
@@ -84,12 +98,22 @@ const operationChangesStructure = (op) => {
 		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;
+		case DOCUMENT_OP_TYPES.SET_TABLE_PROPS:
+		case DOCUMENT_OP_TYPES.CREATE_COMMENT:
+		case DOCUMENT_OP_TYPES.UPDATE_COMMENT_CONTENT:
+		case DOCUMENT_OP_TYPES.SET_COMMENT_RESOLUTION:
+		case DOCUMENT_OP_TYPES.DELETE_COMMENT:
+		case DOCUMENT_OP_TYPES.RESTORE_COMMENT_STATE: return false;
 		default: return op;
 	}
 };
 const operationChangesBodyProjection = (op) => {
 	switch (op.type) {
+		case DOCUMENT_OP_TYPES.CREATE_COMMENT:
+		case DOCUMENT_OP_TYPES.UPDATE_COMMENT_CONTENT:
+		case DOCUMENT_OP_TYPES.SET_COMMENT_RESOLUTION:
+		case DOCUMENT_OP_TYPES.DELETE_COMMENT:
+		case DOCUMENT_OP_TYPES.RESTORE_COMMENT_STATE:
 		case DOCUMENT_OP_TYPES.CREATE_HEADER_FOOTER:
 		case DOCUMENT_OP_TYPES.REMOVE_HEADER_FOOTER:
 		case DOCUMENT_OP_TYPES.ADD_NOTE:
@@ -219,6 +243,8 @@ const preservePropertySources = ({ target, source, stories = documentStories(sou
 	copyDocumentParagraphPropertySourceContract(target, source);
 };
 const unsupportedSeedReason = (document, stories = documentStories(document)) => {
+	const commentIssue = commentDocumentIssue(document, "all");
+	if (commentIssue !== void 0) return commentIssue;
 	for (const story of stories) {
 		const body = findStoryBody(document, story);
 		if (story !== OP_STORIES.MAIN && (story.kind === "footnote" || story.kind === "endnote")) {
@@ -257,6 +283,14 @@ const project = ({ document, styles, story = OP_STORIES.MAIN }) => {
 	});
 	if (converted.isErr()) return converted;
 	const pairedBookmarkIds = collectPairedBookmarkIds(body.content);
+	const commentContext = {
+		rangedIds: rangedCommentIds(body.content),
+		pointIds: /* @__PURE__ */ new Set(),
+		openIds: /* @__PURE__ */ new Set()
+	};
+	visitCommentMarkers(body.content, ({ item }) => {
+		if (item.type === "commentReference" && !commentContext.rangedIds.has(item.id)) commentContext.pointIds.add(item.id);
+	});
 	const paragraphs = [];
 	let failure;
 	converted.value.forEach((node, offset, index) => {
@@ -280,7 +314,8 @@ const project = ({ document, styles, story = OP_STORIES.MAIN }) => {
 		const inline = projectCanonicalInline({
 			source,
 			paragraph: node,
-			pairedBookmarkIds
+			pairedBookmarkIds,
+			commentContext
 		});
 		if (inline.isErr()) {
 			failure = new CanonicalSessionError({
@@ -297,6 +332,10 @@ const project = ({ document, styles, story = OP_STORIES.MAIN }) => {
 			node,
 			source
 		});
+		visitCommentMarkers([source], ({ item }) => {
+			if (item.type === "commentRangeStart") commentContext.openIds.add(item.id);
+			if (item.type === "commentRangeEnd") commentContext.openIds.delete(item.id);
+		});
 	});
 	if (failure !== void 0) return Result.err(failure);
 	if (paragraphs.length !== body.content.length) return refuse("The projection changed paragraph structure.");
@@ -405,6 +444,10 @@ var CanonicalSession = class {
 		this.styles = styles == null ? styles : structuredClone(styles);
 		this.rememberSources(document);
 	}
+	/** Render only the committed comment projection while provisional IME blocks document snapshots. */
+	getCommittedComments() {
+		return structuredClone(this.currentDocument.package.document.comments ?? []);
+	}
 	setMode(mode) {
 		if (this.mode.type !== mode.type || this.mode.type === "suggesting" && mode.type === "suggesting" && this.mode.author !== mode.author) this.breakUndoGroup();
 		this.mode = mode.type === "editing" ? { type: "editing" } : {
@@ -994,26 +1037,15 @@ var CanonicalSession = class {
 			transaction.replaceWith(from, to, Fragment.fromArray(replacement));
 		}
 		if (!transaction.doc.eq(projected.value.doc)) transaction.replaceWith(0, transaction.doc.content.size, projected.value.doc.content);
-		if (sameStory(selection.anchor.story, story) && sameStory(selection.head.story, story)) {
-			const anchor = projected.value.positionAt(selection.anchor);
-			const head = projected.value.positionAt(selection.head);
-			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}`);
-				}
+		if (sameStory(selection.anchor.story, projectedStory) && sameStory(selection.head.story, projectedStory)) restoreCanonicalSelection({
+			transaction,
+			projection: projected.value,
+			selection,
+			unavailable: {
+				type: "near",
+				anchor: state.selection.anchor
 			}
-		}
+		});
 		transaction.setMeta(CANONICAL_PROJECTION_META, {
 			type: "canonical",
 			origin,
@@ -1033,6 +1065,7 @@ var CanonicalSession = class {
 			document: applied.value.document,
 			projection: projected.value,
 			bodyProjection: bodyProjection.value,
+			selection,
 			touched: applied.value.touched,
 			version: baseVersion + 1,
 			origin,
@@ -1061,7 +1094,8 @@ var CanonicalSession = class {
 					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";
+				const bodyOps = ops.filter((op) => !COMMENT_OPERATION_TYPES.has(op.type));
+				if (bodyOps.some(operationChangesStructure) || bodyOps.some(operationChangesPackage) || bodyOps.length > 0 && (applied.value.touched.inserted.length > 0 || applied.value.touched.removed.length > 0)) this.saveStructure = "changed";
 				this.currentVersion = baseVersion + 1;
 				onPublish(applied.value.inverse, this.currentVersion);
 				return Result.ok(void 0);

package/dist/controller/canonicalStoryEditor.d.ts

@@ -20,6 +20,8 @@ declare const createCanonicalStoryEditor: ({ story, getView, getApi, enabled, on
     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;

package/dist/controller/canonicalStoryEditor.js

@@ -1,6 +1,7 @@
 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 }) => {
@@ -24,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");
@@ -70,6 +82,14 @@ const createCanonicalStoryEditor = ({ story, getView, getApi, enabled, onRefusal
 			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/folioEditor.js

@@ -1,3 +1,4 @@
+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
@@ -14,6 +15,16 @@ 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,
@@ -22,6 +33,8 @@ const createFolioEditor = (deps) => {
 		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

@@ -20,7 +20,7 @@ type HeaderFooterEditorManagerDeps = {
   getDocument: () => document_d_exports.Document | null;
   getCanonicalApi?: (() => HiddenEditorApi | null) | undefined;
   getExperimentalSession?: (() => "canonical" | undefined) | undefined;
-  onSessionRefusal?: ((reason: string, gap: CanonicalGap) => 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,11 +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";
@@ -85,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 (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();
+		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;
@@ -105,7 +108,7 @@ const createHeaderFooterEditorManager = (deps) => {
 			const existing = mounted.get(part.rId);
 			if (existing) {
 				if (existing.mountNode.parentElement !== host) host.append(existing.mountNode);
-				if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories)) {
+				if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting)) {
 					const projected = deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
 						kind: part.kind,
 						rId: part.rId
@@ -155,7 +158,7 @@ const createHeaderFooterEditorManager = (deps) => {
 				},
 				getView: () => view,
 				getApi: () => deps.getCanonicalApi?.() ?? null,
-				enabled: () => usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories),
+				enabled: () => usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting),
 				onRefusal: deps.onSessionRefusal,
 				onSelectionChange: () => deps.onTransaction?.({
 					kind: part.kind,
@@ -165,11 +168,11 @@ const createHeaderFooterEditorManager = (deps) => {
 					selectionChanged: true
 				})
 			});
-			const canonicalProjection = usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories) ? deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
+			const canonicalProjection = usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting) ? deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
 				kind: part.kind,
 				rId: part.rId
 			}) : null;
-			if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories) && !canonicalProjection) {
+			if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting) && !canonicalProjection) {
 				manager.destroy();
 				mountNode.remove();
 				continue;
@@ -178,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,
@@ -218,7 +224,15 @@ const createHeaderFooterEditorManager = (deps) => {
 			rId
 		})),
 		snapshotDocument: (document) => {
-			if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories)) 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,13 +1,16 @@
 import { document_d_exports } from "../types/document.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;
@@ -31,6 +34,9 @@ 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. */
@@ -42,6 +48,9 @@ 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;
@@ -80,6 +89,8 @@ 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"];
@@ -87,7 +98,7 @@ type HiddenEditorApiDeps = {
   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" | "applyCanonicalDocumentOperations" | "undoCanonicalDocumentOperations">;
+  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,8 @@ 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: () => {
@@ -49,6 +51,8 @@ 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,

package/dist/controller/hiddenEditorManager.d.ts

@@ -65,7 +65,7 @@ type HiddenEditorManagerDeps = {
   getExperimentalSession?: () => "canonical" | undefined;
   getEditingMode?: () => EditorMode;
   getSuggestionAuthor?: () => string;
-  onSessionRefusal?: (reason: string, gap: CanonicalGap) => 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
@@ -99,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). */