@stll/folio-core 0.54.1 → 0.55.0

package/dist/controller/canonicalStoryEditor.d.ts

@@ -0,0 +1,34 @@
+import { HiddenEditorApi } from "./hiddenEditorApi.js";
+import { Transaction } from "prosemirror-state";
+import { EditorView } from "prosemirror-view";
+import { OpStory } from "@stll/docx-core/ops";
+//#region src/controller/canonicalStoryEditor.d.ts
+type CanonicalStoryEditorOptions = {
+  story: OpStory;
+  getView: () => EditorView;
+  getApi: () => HiddenEditorApi | null;
+  enabled: () => boolean;
+  onSelectionChange: () => void;
+  onRefusal: ((reason: string) => void) | undefined;
+};
+/** Secondary views compile classified native input into the shared Document journal. */
+declare const createCanonicalStoryEditor: ({ story, getView, getApi, enabled, onRefusal, onSelectionChange }: CanonicalStoryEditorOptions) => {
+  dispatch: (transaction: Transaction) => boolean;
+  props: {
+    handleKeyDown: (view: EditorView, event: KeyboardEvent) => boolean;
+    handleTextInput: (view: EditorView, from: number, to: number, text: string) => boolean;
+    handleDOMEvents: {
+      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;
+      drop: (view: EditorView, event: Event) => boolean;
+    };
+  };
+};
+//#endregion
+export { createCanonicalStoryEditor };

package/dist/controller/canonicalStoryEditor.js

@@ -0,0 +1,82 @@
+import { createCanonicalInputBoundary } from "./canonicalInput.js";
+import { CanonicalSessionError } from "./canonicalSession.js";
+//#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);
+		else throw new CanonicalSessionError({
+			message,
+			reason: "refused"
+		});
+	};
+	const history = (direction) => {
+		const view = getView();
+		const accepted = getApi()?.applyCanonicalStoryHistory({
+			view,
+			story,
+			direction
+		}) ?? false;
+		if (accepted && !view.isDestroyed) onSelectionChange();
+		return accepted;
+	};
+	const boundary = createCanonicalInputBoundary({
+		breakUndoGroup: () => {
+			getApi()?.updateCanonicalInputLifecycle("breakUndoGroup");
+		},
+		beginComposition: () => getApi()?.updateCanonicalInputLifecycle("beginComposition") ?? false,
+		endComposition: () => {
+			getApi()?.updateCanonicalInputLifecycle("endComposition");
+		},
+		replace: (intent) => {
+			const view = getView();
+			if (getApi()?.replaceCanonicalStoryText({
+				view,
+				story,
+				intent
+			}) && !view.isDestroyed) onSelectionChange();
+		},
+		undo: () => history("undo"),
+		redo: () => history("redo"),
+		refuse
+	});
+	return {
+		dispatch: (transaction) => {
+			if (!enabled()) return false;
+			const view = getView();
+			if (transaction.docChanged) {
+				if (boundary.acceptComposition(view, transaction)) return true;
+				if (!boundary.commitNativeProposal(view, transaction)) boundary.refuseNativeMutation(view);
+				view.updateState(view.state);
+				return true;
+			}
+			if (transaction.selectionSet && !boundary.isComposing) getApi()?.updateCanonicalInputLifecycle("breakUndoGroup");
+			const applied = view.state.applyTransaction(transaction);
+			if (!applied.state.doc.eq(view.state.doc)) {
+				refuse("A plugin attempted an unclassified canonical story mutation.");
+				view.updateState(view.state);
+				return true;
+			}
+			view.updateState(applied.state);
+			if (applied.transactions.some((step) => step.selectionSet)) onSelectionChange();
+			return true;
+		},
+		props: {
+			handleKeyDown: (view, event) => enabled() && boundary.handleKeyDown(view, event),
+			handleTextInput: (view, from, to, text) => enabled() && boundary.handleTextInput(view, from, to, text),
+			handleDOMEvents: {
+				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),
+				input: (view) => enabled() && boundary.handleDOMEvents.input(view),
+				blur: (view) => enabled() && boundary.handleDOMEvents.blur(view),
+				paste: (view, event) => enabled() && boundary.handleDOMEvents.paste(view, event),
+				cut: (view, event) => enabled() && boundary.handleDOMEvents.cut(view, event),
+				drop: (view, event) => enabled() && boundary.handleDOMEvents.drop(view, event)
+			}
+		}
+	};
+};
+//#endregion
+export { createCanonicalStoryEditor };

package/dist/controller/canonicalStructure.d.ts

@@ -0,0 +1,16 @@
+import { CanonicalCommit, CanonicalSession, CanonicalSessionError } from "./canonicalSession.js";
+import { CanonicalCommandIntent } from "../prosemirror/canonicalCommands.js";
+import { EditorState } from "prosemirror-state";
+import { Result } from "better-result";
+//#region src/controller/canonicalStructure.d.ts
+/** Toolbar meanings enter the same operation journal as native input. */
+declare const prepareCanonicalCommands: (session: CanonicalSession, state: EditorState, commands: readonly CanonicalCommandIntent[]) => Result<CanonicalCommit, CanonicalSessionError>;
+type CanonicalAutoformatInput = {
+  from: number;
+  to: number;
+  text: string;
+};
+/** Rules compile their replacement and paragraph change as one atomic edit. */
+declare const prepareCanonicalAutoformat: (session: CanonicalSession, state: EditorState, { from, to, text }: CanonicalAutoformatInput) => Result<CanonicalCommit, CanonicalSessionError> | undefined;
+//#endregion
+export { prepareCanonicalAutoformat, prepareCanonicalCommands };

package/dist/controller/canonicalStructure.js

@@ -0,0 +1,269 @@
+import { getCachedNumberingMap, numberingLevelUsesBulletMarker } from "../docx/numberingParser.js";
+import { listRequestsForMarker } from "../prosemirror/listAutoformatMarkers.js";
+import { CanonicalSessionError } from "./canonicalSession.js";
+import { Result } from "better-result";
+import { paragraphNumberingReference } from "@stll/docx-core/model";
+import { OP_STORIES } from "@stll/docx-core/ops";
+//#region src/controller/canonicalStructure.ts
+const refuse = (message) => Result.err(new CanonicalSessionError({
+	message,
+	reason: "refused"
+}));
+const selectedParagraphs = (session, state) => {
+	const ids = /* @__PURE__ */ new Set();
+	state.doc.nodesBetween(state.selection.from, state.selection.to, (node) => {
+		if (node.type.name === "paragraph" && typeof node.attrs["paraId"] === "string") ids.add(node.attrs["paraId"]);
+	});
+	return session.document.package.document.content.filter((paragraph) => paragraph.type === "paragraph" && ids.has(paragraph.paraId ?? ""));
+};
+const numberingIntent = (session, paragraphs, request) => {
+	const definitions = session.document.package.numbering;
+	const map = definitions === void 0 ? void 0 : getCachedNumberingMap(definitions);
+	const body = session.document.package.document.content;
+	const first = body.findIndex((item) => item === paragraphs.at(0));
+	const last = body.findIndex((item) => item === paragraphs.at(-1));
+	const neighbor = [first > 0 ? body.at(first - 1) : void 0, body.at(last + 1)].find((item) => {
+		if (item?.type !== "paragraph" || item.formatting?.numPr?.kind !== "reference" || item.formatting.numPrFromStyle !== void 0) return false;
+		const level = map?.getLevel(item.formatting.numPr.numId, item.formatting.numPr.ilvl ?? 0);
+		if (level == null || numberingLevelUsesBulletMarker(level) !== (request.kind === "bullet")) return false;
+		return request.format === void 0 || level.numFmt === request.format.numFmt && level.lvlText === request.format.lvlText;
+	});
+	let numId;
+	let ilvl = 0;
+	let target;
+	if (neighbor?.type === "paragraph" && neighbor.formatting?.numPr?.kind === "reference") {
+		numId = neighbor.formatting.numPr.numId;
+		ilvl = neighbor.formatting.numPr.ilvl ?? 0;
+		target = {
+			type: "existing",
+			numId
+		};
+	} else {
+		numId = Math.max(0, ...definitions?.nums.map((num) => num.numId) ?? []) + 1;
+		const abstractNumId = Math.max(-1, ...definitions?.abstractNums.map((num) => num.abstractNumId) ?? []) + 1;
+		const levels = Array.from({ length: 9 }, (_, level) => ({
+			ilvl: level,
+			start: level === 0 ? request.start ?? 1 : 1,
+			numFmt: request.kind === "bullet" ? "bullet" : request.format?.numFmt ?? "decimal",
+			lvlText: request.kind === "bullet" ? "•" : (request.format?.lvlText ?? "%1.").replaceAll("%1", `%${level + 1}`),
+			suffix: "tab",
+			pPr: {
+				indentLeft: (level + 1) * 720,
+				indentFirstLine: 360,
+				hangingIndent: true
+			}
+		}));
+		target = {
+			type: "new",
+			num: {
+				numId,
+				abstractNumId
+			},
+			abstractNum: {
+				abstractNumId,
+				multiLevelType: "multilevel",
+				levels
+			}
+		};
+	}
+	return {
+		type: "setList",
+		target,
+		items: paragraphs.map((paragraph) => ({
+			at: {
+				story: OP_STORIES.MAIN,
+				blockId: paragraph.paraId ?? "",
+				offset: 0
+			},
+			ilvl
+		}))
+	};
+};
+/** Toolbar meanings enter the same operation journal as native input. */
+const prepareCanonicalCommands = (session, state, commands) => {
+	const intents = [];
+	const paragraphs = selectedParagraphs(session, state);
+	for (const command of commands) switch (command.type) {
+		case "insertBreak": {
+			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({
+				type: "insertAtom",
+				from: from.value,
+				to: to.value,
+				atom: {
+					type: "break",
+					breakType: command.breakType
+				}
+			});
+			break;
+		}
+		case "formatRun": {
+			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({
+				type: "formatRun",
+				from: from.value,
+				to: to.value,
+				patch: command.patch
+			});
+			break;
+		}
+		case "formatParagraph": {
+			const at = session.projection.addressAt(command.at);
+			if (at.isErr()) return at;
+			intents.push({
+				type: "formatParagraph",
+				at: at.value,
+				patch: command.patch
+			});
+			break;
+		}
+		case "toggleList": {
+			const definitions = session.document.package.numbering;
+			const map = definitions === void 0 ? void 0 : getCachedNumberingMap(definitions);
+			if (!(paragraphs.length > 0 && paragraphs.every(({ formatting }) => {
+				const numPr = formatting?.numPr;
+				return numPr?.kind === "reference" && numberingLevelUsesBulletMarker(map?.getLevel(numPr.numId, numPr.ilvl ?? 0)) === (command.kind === "bullet");
+			}))) {
+				intents.push(numberingIntent(session, paragraphs, { kind: command.kind === "bullet" ? "bullet" : "numbered" }));
+				break;
+			}
+			for (const paragraph of paragraphs) intents.push({
+				type: "formatParagraph",
+				at: {
+					story: OP_STORIES.MAIN,
+					blockId: paragraph.paraId ?? "",
+					offset: 0
+				},
+				patch: { numPr: { kind: "none" } }
+			});
+			break;
+		}
+		case "removeList":
+			for (const paragraph of paragraphs) intents.push({
+				type: "formatParagraph",
+				at: {
+					story: OP_STORIES.MAIN,
+					blockId: paragraph.paraId ?? "",
+					offset: 0
+				},
+				patch: { numPr: { kind: "none" } }
+			});
+			break;
+		case "changeListLevel":
+			for (const paragraph of paragraphs) {
+				const numPr = paragraph.formatting?.numPr;
+				if (numPr?.kind !== "reference") continue;
+				const at = {
+					story: OP_STORIES.MAIN,
+					blockId: paragraph.paraId ?? "",
+					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.");
+				intents.push({
+					type: "formatParagraph",
+					at,
+					patch: { numPr: level < 0 ? { kind: "none" } : paragraphNumberingReference({
+						numId: numPr.numId,
+						ilvl: level
+					}) }
+				});
+			}
+			break;
+		case "restartNumbering":
+		case "continueNumbering": {
+			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.");
+			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);
+			let targetId;
+			let target;
+			if (command.type === "continueNumbering") {
+				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.");
+				targetId = earlier.formatting.numPr.numId;
+				target = {
+					type: "existing",
+					numId: targetId
+				};
+			} else {
+				const start = command.start ?? 1;
+				if (!Number.isSafeInteger(start) || start < 0) return refuse("The numbering start must be a non-negative integer.");
+				const original = definitions.nums.find((num) => num.numId === numPr.numId);
+				if (original === void 0) return refuse("The numbering instance does not exist.");
+				targetId = Math.max(0, ...definitions.nums.map((num) => num.numId)) + 1;
+				const level = numPr.ilvl ?? 0;
+				target = {
+					type: "new",
+					num: {
+						...original,
+						numId: targetId,
+						levelOverrides: [...(original.levelOverrides ?? []).filter(({ ilvl }) => ilvl !== level), {
+							...original.levelOverrides?.find(({ ilvl }) => ilvl === level),
+							ilvl: level,
+							startOverride: start
+						}]
+					}
+				};
+			}
+			intents.push({
+				type: "setList",
+				target,
+				items: affected.map((paragraph) => ({
+					at: {
+						story: OP_STORIES.MAIN,
+						blockId: paragraph.paraId ?? "",
+						offset: 0
+					},
+					ilvl: paragraph.formatting?.numPr?.kind === "reference" ? paragraph.formatting.numPr.ilvl ?? 0 : 0
+				}))
+			});
+			break;
+		}
+		default: return command;
+	}
+	return session.prepareIntents(state, intents);
+};
+/** Rules compile their replacement and paragraph change as one atomic edit. */
+const prepareCanonicalAutoformat = (session, state, { from, to, text }) => {
+	if (text !== " " || from !== to) return void 0;
+	const at = session.projection.addressAt(from);
+	if (at.isErr()) return void 0;
+	const address = session.projection.paragraph(at.value.blockId);
+	if (address === void 0 || address.source.formatting?.numPr?.kind === "reference") return void 0;
+	const source = address.source;
+	const prefix = address.text.slice(0, at.value.offset) + text;
+	const requests = listRequestsForMarker(prefix);
+	const heading = /^(?<hashes>#{1,6}) $/u.exec(prefix)?.groups?.["hashes"];
+	if (requests === null && heading === void 0) return void 0;
+	const start = {
+		...at.value,
+		offset: 0
+	};
+	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, [{
+		type: "replaceText",
+		from: start,
+		to: at.value,
+		text: ""
+	}, request === void 0 ? {
+		type: "formatParagraph",
+		at: start,
+		patch: { styleId }
+	} : numberingIntent(session, [source], request)]);
+};
+//#endregion
+export { prepareCanonicalAutoformat, prepareCanonicalCommands };

package/dist/controller/folioEditor.d.ts

@@ -1,8 +1,8 @@
 import { document_d_exports } from "../types/document.js";
 import { DocxInput } from "../utils/docxInput.js";
 import { Layout } from "../layout-engine/types.js";
-import { HiddenEditorApi } from "./hiddenEditorApi.js";
 import { FolioEditorEmitter } from "./folioEditorEvents.js";
+import { HiddenEditorApi } from "./hiddenEditorApi.js";
 import { LayoutRunOptions } from "./layoutRunOptions.js";
 import { EditorState } from "prosemirror-state";
 //#region src/controller/folioEditor.d.ts

package/dist/controller/folioEditor.js

@@ -15,6 +15,15 @@ const createFolioEditor = (deps) => {
 		getState: () => deps.getEditorApi()?.getState() ?? null,
 		getView: () => deps.getEditorApi()?.getView() ?? null,
 		getDocument: () => deps.getEditorApi()?.getDocument() ?? null,
+		updateCanonicalInputLifecycle: (action) => deps.getEditorApi()?.updateCanonicalInputLifecycle(action) ?? false,
+		applyCanonicalStoryHistory: (options) => deps.getEditorApi()?.applyCanonicalStoryHistory(options) ?? false,
+		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,
+		getCanonicalDocument: () => deps.getEditorApi()?.getCanonicalDocument() ?? null,
+		setCanonicalMode: (mode) => deps.getEditorApi()?.setCanonicalMode(mode) ?? false,
+		resolveCanonicalRevisions: (revisionIds, resolution) => deps.getEditorApi()?.resolveCanonicalRevisions(revisionIds, resolution) ?? false,
 		focus: () => deps.getEditorApi()?.focus(),
 		blur: () => deps.getEditorApi()?.blur(),
 		isFocused: () => deps.getEditorApi()?.isFocused() ?? false,

package/dist/controller/headerFooterEditorManager.d.ts

@@ -1,4 +1,5 @@
 import { document_d_exports } from "../types/document.js";
+import { HiddenEditorApi } from "./hiddenEditorApi.js";
 import { DirectEditorProps, EditorView } from "prosemirror-view";
 //#region src/controller/headerFooterEditorManager.d.ts
 type HeaderFooterPartKind = "header" | "footer";
@@ -16,6 +17,9 @@ type HeaderFooterEditorTransaction = {
 type HeaderFooterEditorManagerDeps = {
   createView?: ((mountNode: HTMLElement, props: DirectEditorProps) => EditorView) | undefined;
   getDocument: () => document_d_exports.Document | null;
+  getCanonicalApi?: (() => HiddenEditorApi | null) | undefined;
+  getExperimentalSession?: (() => "canonical" | undefined) | undefined;
+  onSessionRefusal?: ((reason: string) => void) | undefined;
   getHost: () => HTMLElement | null;
   getStyles: () => document_d_exports.StyleDefinitions | null | undefined;
   getTheme: () => document_d_exports.Theme | null | undefined;

package/dist/controller/headerFooterEditorManager.js

@@ -10,9 +10,19 @@ import { createDocumentNumberingPlugin } from "../prosemirror/plugins/documentNu
 import { createDocumentStylesPlugin } from "../prosemirror/plugins/documentStyles.js";
 import { schema } from "../prosemirror/schema/index.js";
 import { storyListNumbering } from "../prosemirror/storyListNumbering.js";
-import { EditorState } from "prosemirror-state";
+import { createCanonicalStoryEditor } from "./canonicalStoryEditor.js";
+import { OP_STORIES } from "@stll/docx-core/ops";
+import { EditorState, TextSelection } from "prosemirror-state";
 import { EditorView } from "prosemirror-view";
 //#region src/controller/headerFooterEditorManager.ts
+/**
+* Framework-neutral lifecycle owner for persistent header/footer EditorViews.
+*
+* Each distinct relationship id owns one off-screen ProseMirror view. Painted
+* header/footer instances that share that relationship therefore share live
+* editor state, and adapters only decide when to synchronize or destroy the
+* manager.
+*/
 const createEditorView = (mountNode, props) => new EditorView(mountNode, props);
 const DETACHED_WATERMARK_HOST = Symbol.for("stll.detachedWatermarkHost");
 const headerFooterToProseDocWithDetachedWatermarkHost = (headerFooter, options) => {
@@ -27,6 +37,7 @@ const buildInitialState = (headerFooter, styles, theme, numbering, manager) => {
 	const proseDocOptions = {};
 	if (styles) proseDocOptions.styles = styles;
 	if (theme !== void 0) proseDocOptions.theme = theme;
+	if (numbering != null) proseDocOptions.numbering = numbering;
 	const document = headerFooter.watermarkBlockIndex === void 0 ? headerFooterToProseDoc(headerFooter.content, proseDocOptions) : headerFooterToProseDocWithDetachedWatermarkHost(headerFooter, proseDocOptions);
 	return ensureBaseDirectionInState(ensureParaIdsInState(EditorState.create({
 		doc: document,
@@ -76,7 +87,8 @@ const createHeaderFooterEditorManager = (deps) => {
 	const sync = () => {
 		const host = deps.getHost();
 		if (!host) return;
-		const document = deps.getDocument();
+		if (deps.getExperimentalSession?.() === "canonical" && !deps.getCanonicalApi?.()?.getCanonicalStoryProjection(OP_STORIES.MAIN)) return;
+		const document = deps.getExperimentalSession?.() === "canonical" ? deps.getCanonicalApi?.()?.getCanonicalDocument() ?? deps.getDocument() : deps.getDocument();
 		const styles = deps.getStyles();
 		const theme = deps.getTheme();
 		const numbering = document?.package.numbering;
@@ -92,6 +104,30 @@ const createHeaderFooterEditorManager = (deps) => {
 			const existing = mounted.get(part.rId);
 			if (existing) {
 				if (existing.mountNode.parentElement !== host) host.append(existing.mountNode);
+				if (deps.getExperimentalSession?.() === "canonical") {
+					const projected = deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
+						kind: part.kind,
+						rId: part.rId
+					});
+					if (projected && !existing.view.state.doc.eq(projected)) {
+						const transaction = existing.view.state.tr.replaceWith(0, existing.view.state.doc.content.size, projected.content);
+						const restored = deps.getCanonicalApi?.()?.getCanonicalStorySelection({
+							kind: part.kind,
+							rId: part.rId
+						});
+						const anchor = Math.min(existing.view.state.selection.anchor, projected.content.size);
+						transaction.setSelection(restored ? TextSelection.create(transaction.doc, restored.anchor, restored.head) : TextSelection.near(transaction.doc.resolve(anchor)));
+						transaction.setMeta("addToHistory", false);
+						existing.view.updateState(existing.view.state.apply(transaction));
+					}
+					existing.appliedHeaderFooter = headerFooter;
+					existing.appliedContent = headerFooter.content;
+					existing.appliedStyles = styles;
+					existing.appliedTheme = theme;
+					existing.appliedNumbering = numbering;
+					existing.dirty = false;
+					continue;
+				}
 				const contentIsCurrent = existing.appliedHeaderFooter === headerFooter && existing.appliedContent === headerFooter.content;
 				const contextIsCurrent = existing.appliedStyles === styles && existing.appliedTheme === theme && existing.appliedNumbering === numbering;
 				if (contentIsCurrent && contextIsCurrent) continue;
@@ -111,9 +147,40 @@ const createHeaderFooterEditorManager = (deps) => {
 			mountNode.dataset["hfRId"] = part.rId;
 			mountNode.dataset["hfKind"] = part.kind;
 			host.append(mountNode);
+			const canonical = createCanonicalStoryEditor({
+				story: {
+					kind: part.kind,
+					rId: part.rId
+				},
+				getView: () => view,
+				getApi: () => deps.getCanonicalApi?.() ?? null,
+				enabled: () => deps.getExperimentalSession?.() === "canonical",
+				onRefusal: deps.onSessionRefusal,
+				onSelectionChange: () => deps.onTransaction?.({
+					kind: part.kind,
+					rId: part.rId,
+					view,
+					docChanged: false,
+					selectionChanged: true
+				})
+			});
+			const canonicalProjection = deps.getExperimentalSession?.() === "canonical" ? deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
+				kind: part.kind,
+				rId: part.rId
+			}) : null;
+			if (deps.getExperimentalSession?.() === "canonical" && !canonicalProjection) {
+				manager.destroy();
+				mountNode.remove();
+				continue;
+			}
 			const view = (deps.createView ?? createEditorView)(mountNode, {
-				state: buildInitialState(headerFooter, styles, theme, numbering, manager),
+				...canonical.props,
+				state: canonicalProjection ? EditorState.create({
+					doc: canonicalProjection,
+					plugins: [createDocumentStylesPlugin(styles), createDocumentNumberingPlugin(numbering)]
+				}) : buildInitialState(headerFooter, styles, theme, numbering, manager),
 				dispatchTransaction(transaction) {
+					if (canonical.dispatch(transaction)) return;
 					const nextState = view.state.apply(transaction);
 					view.updateState(nextState);
 					const mountedPart = mounted.get(part.rId);
@@ -150,6 +217,7 @@ const createHeaderFooterEditorManager = (deps) => {
 			rId
 		})),
 		snapshotDocument: (document) => {
+			if (deps.getExperimentalSession?.() === "canonical") return deps.getCanonicalApi?.()?.getCanonicalDocument() ?? document;
 			let headers = document.package.headers;
 			let footers = document.package.footers;
 			let headersChanged = false;

package/dist/controller/hiddenEditorApi.d.ts

@@ -1,7 +1,21 @@
 import { document_d_exports } from "../types/document.js";
+import { createCanonicalInputBoundary } from "./canonicalInput.js";
+import { CanonicalSessionMode } from "./canonicalSession.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";
 //#region src/controller/hiddenEditorApi.d.ts
+type CanonicalStoryHistoryOptions = {
+  view: EditorView;
+  story: OpStory;
+  direction: "undo" | "redo";
+};
+type CanonicalStoryTextOptions = {
+  view: EditorView;
+  story: OpStory;
+  intent: Parameters<Parameters<typeof createCanonicalInputBoundary>[0]["replace"]>[0];
+};
 type HiddenEditorApi = {
   /** Request the off-screen EditorView (idempotent; creates it when possible). */
   ensureView: () => void;
@@ -13,6 +27,21 @@ type HiddenEditorApi = {
   getView: () => EditorView | null;
   /** Get the current Document from PM state */
   getDocument: () => document_d_exports.Document | null;
+  /** Canonical snapshot, or null in the default session. */
+  getCanonicalDocument: () => document_d_exports.Document | null;
+  /** Set the explicit mode for an active canonical session. */
+  setCanonicalMode: (mode: CanonicalSessionMode) => boolean;
+  /** Resolve canonical revisions as one batch and journal its exact inverse. */
+  resolveCanonicalRevisions: (revisionIds: readonly number[], resolution: "accept" | "reject") => boolean;
+  updateCanonicalInputLifecycle: (action: "beginComposition" | "endComposition" | "breakUndoGroup") => boolean;
+  applyCanonicalStoryHistory: (options: CanonicalStoryHistoryOptions) => boolean;
+  applyCanonicalOperations: (ops: readonly DocumentOp[]) => boolean;
+  getCanonicalStorySelection: (story: OpStory) => {
+    anchor: number;
+    head: number;
+  } | null;
+  getCanonicalStoryProjection: (story: OpStory) => Node | null;
+  replaceCanonicalStoryText: (options: CanonicalStoryTextOptions) => boolean;
   /** Focus the hidden editor */
   focus: () => void;
   /** Blur the hidden editor */
@@ -43,6 +72,12 @@ type HiddenEditorApi = {
 type HiddenEditorApiDeps = {
   getView: () => EditorView | null;
   getDocumentContext: () => document_d_exports.Document | null;
+  getCanonicalDocument?: () => document_d_exports.Document | null;
+  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">;
   isDestroying: () => boolean;
   ensureView: () => void;
   isViewRequested: () => boolean;