@stll/folio-core 0.56.0 → 0.58.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,12 +7,13 @@ 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 { AllSelection, TextSelection } from "prosemirror-state";
+import { DOCUMENT_OP_REFUSAL_REASONS, DOCUMENT_OP_TYPES, OP_STORIES, applyDocumentOps, combineEdits, commentDocumentIssue, compileEditorIntent, createEditorIntentIdAllocator, documentStories, editorParagraphGroups, findStoryBody, normalizeForOps, packageParagraphIds, sameStory, validateOpsDocument } from "@stll/docx-core/ops";
+import { AllSelection, NodeSelection, TextSelection } from "prosemirror-state";
 //#region src/controller/canonicalSession.ts
 var CanonicalSessionError = class extends TaggedError("CanonicalSessionError") {};
 const refuse = (message) => Result.err(new 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:
@@ -159,12 +183,21 @@ var CanonicalProjection = class {
 		return Result.ok(paragraph.start + gap.position);
 	}
 	selectionAt(state) {
-		if (!(state.selection instanceof TextSelection) && !(state.selection instanceof AllSelection)) return refuse("Canonical input requires a text selection.");
-		const range = canonicalSelectionRange(state);
-		const type = state.selection instanceof AllSelection ? "all" : "text";
-		const anchor = this.addressAt(type === "all" ? range.from : state.selection.anchor);
+		const selection = state.selection;
+		let type;
+		let anchorPosition = selection.anchor;
+		let headPosition = selection.head;
+		if (selection instanceof TextSelection) type = "text";
+		else if (selection instanceof NodeSelection && selection.node.isInline && selection.node.isAtom && selection.node.type.name !== "noteMarker") type = "inlineNode";
+		else if (selection instanceof AllSelection) {
+			type = "all";
+			const range = canonicalSelectionRange(state);
+			anchorPosition = range.from;
+			headPosition = range.to;
+		} else return refuse("Canonical input requires text, an inline atom, or the whole document selection.");
+		const anchor = this.addressAt(anchorPosition);
 		if (anchor.isErr()) return anchor;
-		const head = this.addressAt(type === "all" ? range.to : state.selection.head);
+		const head = this.addressAt(headPosition);
 		if (head.isErr()) return head;
 		return Result.ok({
 			type,
@@ -219,6 +252,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,9 +292,18 @@ 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) => {
+		if (failure !== void 0) return;
 		const source = body.content.at(index);
 		if (source?.type !== "paragraph" || source.paraId === void 0) {
 			failure = new CanonicalSessionError({
@@ -271,7 +315,7 @@ const project = ({ document, styles, story = OP_STORIES.MAIN }) => {
 		}
 		if (node.type.name !== "paragraph" || node.attrs["paraId"] !== source.paraId) {
 			failure = new CanonicalSessionError({
-				gap: CANONICAL_GAP.dispatch,
+				gap: CANONICAL_GAP.storyContentProjection,
 				reason: "refused",
 				message: "The projection changed paragraph structure."
 			});
@@ -280,7 +324,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 +342,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 +454,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" } : {
@@ -552,9 +605,13 @@ var CanonicalSession = class {
 		if (!Number.isFinite(time)) return refuse("The input time is invalid.");
 		if (from > to || hasIllegalXmlCharacters(text) || /[\t\r\n]/u.test(text)) return refuse("Canonical input accepts a well-formed text replacement.");
 		if (from === to && text.length === 0) return noChange("The input makes no text change.");
-		const start = projection.inputAddressAt(from);
+		const replacesAll = state.selection instanceof AllSelection && from === state.selection.from && to === state.selection.to;
+		const range = canonicalSelectionRange(state);
+		const inputFrom = replacesAll ? range.from : from;
+		const inputTo = replacesAll ? range.to : to;
+		const start = projection.inputAddressAt(inputFrom);
 		if (start.isErr()) return start;
-		const end = projection.inputAddressAt(to);
+		const end = projection.inputAddressAt(inputTo);
 		if (end.isErr()) return end;
 		const preSelection = projection.selectionAt(state);
 		if (preSelection.isErr()) return preSelection;
@@ -652,7 +709,14 @@ var CanonicalSession = class {
 				mode: this.intentMode(document, intent),
 				firstBlockId: this.nextBlockId
 			});
-			if (compiled.isErr()) return refuse(compiled.error.message);
+			if (compiled.isErr()) {
+				if (compiled.error.reason === DOCUMENT_OP_REFUSAL_REASONS.UNTRACKABLE && (intent.type === "setHyperlink" || intent.type === "removeHyperlink" || intent.type === "insertHyperlink")) return Result.err(new CanonicalSessionError({
+					gap: CANONICAL_GAP.trackedHyperlinkResolution,
+					reason: "refused",
+					message: compiled.error.message
+				}));
+				return refuse(compiled.error.message);
+			}
 			const applied = applyDocumentOps(document, compiled.value.ops);
 			if (applied.isErr()) return refuse(applied.error.message);
 			document = applied.value.document;
@@ -938,8 +1002,11 @@ var CanonicalSession = class {
 			document: applied.value.document,
 			previous: this.currentDocument
 		});
-		const unsupported = unsupportedSeedReason(applied.value.document, changed);
-		if (unsupported !== null) return refuse(unsupported);
+		if (unsupportedSeedReason(applied.value.document, changed) !== null) return Result.err(new CanonicalSessionError({
+			gap: CANONICAL_GAP.storyContentProjection,
+			reason: "refused",
+			message: "The operations produce unsupported canonical story content."
+		}));
 		preservePropertySources({
 			target: applied.value.document,
 			source: this.currentDocument,
@@ -994,25 +1061,16 @@ 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)) {
+			if (!restoreCanonicalSelection({
+				transaction,
+				projection: projected.value,
+				selection,
+				unavailable: {
+					type: "near",
+					anchor: state.selection.anchor
 				}
-			}
+			})) return refuse("Canonical history cannot restore the selected inline atom.");
 		}
 		transaction.setMeta(CANONICAL_PROJECTION_META, {
 			type: "canonical",
@@ -1033,6 +1091,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 +1120,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);
@@ -1070,6 +1130,11 @@ var CanonicalSession = class {
 	}
 };
 const createCanonicalSession = (document, styles) => {
+	if (documentStories(document).some((story) => findStoryBody(document, story)?.content.some((block) => block.type === "table"))) return Result.err(new CanonicalSessionError({
+		gap: CANONICAL_GAP.tableActivation,
+		reason: "refused",
+		message: "Canonical sessions cannot activate documents containing tables."
+	}));
 	const unsupported = unsupportedSeedReason(document);
 	if (unsupported !== null) return refuse(unsupported);
 	const owned = cloneDocumentWithParagraphPropertySources(document);
@@ -1158,7 +1223,12 @@ const isCanonicalJoinBoundary = (state, direction) => {
 /** Native character deletion consumes one whole visible grapheme. */
 const deletionRange = (state, direction) => {
 	const { selection } = state;
-	if (!(selection instanceof TextSelection)) return refuse("Canonical deletion requires a text selection.");
+	if (selection instanceof NodeSelection && selection.node.isInline && selection.node.isAtom && selection.node.type.name !== "noteMarker") return Result.ok({
+		from: selection.from,
+		to: selection.to
+	});
+	if (selection instanceof AllSelection) return Result.ok(canonicalSelectionRange(state));
+	if (!(selection instanceof TextSelection)) return refuse("Canonical deletion requires text, an inline atom, or the whole document selection.");
 	if (!selection.empty) return Result.ok({
 		from: selection.from,
 		to: selection.to

package/dist/controller/canonicalStoryEditor.d.ts

@@ -20,10 +20,12 @@ 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;
-      compositionend: (view: EditorView) => boolean;
+      compositionend: (view: EditorView, event: Event) => boolean;
       input: (view: EditorView) => boolean;
       blur: (view: EditorView) => boolean;
       paste: (view: EditorView, event: ClipboardEvent) => 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,10 +82,18 @@ 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),
-				compositionend: (view) => enabled() && boundary.handleDOMEvents.compositionend(view),
+				compositionend: (view, event) => enabled() && boundary.handleDOMEvents.compositionend(view, event),
 				input: (view) => enabled() && boundary.handleDOMEvents.input(view),
 				blur: (view) => enabled() && boundary.handleDOMEvents.blur(view),
 				paste: (view, event) => enabled() && boundary.handleDOMEvents.paste(view, event),

package/dist/controller/canonicalStructure.js

@@ -15,6 +15,11 @@ const refuse = (message) => Result.err(new CanonicalSessionError({
 	message,
 	reason: "refused"
 }));
+const noChange = (message) => Result.err(new CanonicalSessionError({
+	gap: CANONICAL_GAP.commands,
+	message,
+	reason: "noChange"
+}));
 const selectedParagraphs = (session, state) => {
 	const ids = /* @__PURE__ */ new Set();
 	state.doc.nodesBetween(state.selection.from, state.selection.to, (node) => {
@@ -218,7 +223,7 @@ const prepareCanonicalCommands = (session, state, commands) => {
 					offset: 0
 				};
 				const level = (numPr.ilvl ?? 0) + (command.direction === "increase" ? 1 : -1);
-				if (level > 8) return refuse("The list is already at its deepest level.");
+				if (level > 8) return noChange("The list is already at its deepest level.");
 				intents.push({
 					type: "formatParagraph",
 					at,
@@ -234,7 +239,7 @@ const prepareCanonicalCommands = (session, state, commands) => {
 			const source = paragraphs.at(0);
 			const numPr = source?.formatting?.numPr;
 			const definitions = session.document.package.numbering;
-			if (source === void 0 || numPr?.kind !== "reference" || definitions === void 0) return refuse("Numbering changes require a list paragraph.");
+			if (source === void 0 || numPr?.kind !== "reference" || definitions === void 0) return noChange("Numbering changes require a list paragraph.");
 			const body = session.document.package.document.content;
 			const index = body.findIndex((item) => item === source);
 			const affected = body.slice(index).filter((item) => item.type === "paragraph" && item.formatting?.numPr?.kind === "reference" && item.formatting.numPr.numId === numPr.numId);
@@ -244,7 +249,7 @@ const prepareCanonicalCommands = (session, state, commands) => {
 				const map = getCachedNumberingMap(definitions);
 				const bullet = numberingLevelUsesBulletMarker(map.getLevel(numPr.numId, numPr.ilvl ?? 0));
 				const earlier = body.slice(0, index).findLast((item) => item.type === "paragraph" && item.formatting?.numPr?.kind === "reference" && item.formatting.numPr.numId !== numPr.numId && numberingLevelUsesBulletMarker(map.getLevel(item.formatting.numPr.numId, item.formatting.numPr.ilvl ?? 0)) === bullet);
-				if (earlier?.type !== "paragraph" || earlier.formatting?.numPr?.kind !== "reference") return refuse("There is no preceding compatible list.");
+				if (earlier?.type !== "paragraph" || earlier.formatting?.numPr?.kind !== "reference") return noChange("There is no preceding compatible list.");
 				targetId = earlier.formatting.numPr.numId;
 				target = {
 					type: "existing",

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

@@ -9,7 +9,7 @@ import { redo, undo } from "prosemirror-history";
 */
 const stateToDocument = (state, originalDoc) => {
 	if (!originalDoc) return null;
-	return fromProseDoc(state.doc, originalDoc);
+	return fromProseDoc(state.doc, originalDoc, { stylesheetSource: { type: "package" } });
 };
 const createHiddenEditorApi = (deps) => {
 	const dispatchTr = (view, tr) => {
@@ -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). */