@stll/folio-core 0.55.0 → 0.57.0

package/dist/controller/canonicalClipboardResources.js

@@ -0,0 +1,382 @@
+import { visitParagraphRuns } from "../docx/paragraphTraversal.js";
+import { resolveStyleInheritance } from "../docx/styleParser.js";
+import { resolveParagraphBodyRunFormatting } from "../prosemirror/runStyleFormatting.js";
+import { cascadeStyleTextFormatting } from "../prosemirror/styles/styleToggleCascade.js";
+import { createStyleEngine } from "../style-engine/styleEngine.js";
+import { FONT_THEME_VALUES } from "../types/documentEnumValues.js";
+import { isValidHexColor, resolveColorToHex } from "../utils/colorResolver.js";
+import { resolveThemeFont } from "../utils/fontResolver.js";
+import { mergeParagraphFormatting } from "../utils/paragraphFormattingMerge.js";
+import { Result, panic } from "better-result";
+import { BODY_TEXT_OUTLINE_LEVEL, NO_PARAGRAPH_NUMBERING, isThemeColor, themeColorSlot } from "@stll/docx-core/model";
+import { DOCUMENT_OP_REFUSAL_REASONS, DOCUMENT_OP_TYPES, DocumentOpRefusal } from "@stll/docx-core/ops";
+//#region src/controller/canonicalClipboardResources.ts
+const STYLE_REFERENCE_FIELDS = /* @__PURE__ */ new Set([
+	"styleId",
+	"basedOn",
+	"next",
+	"link",
+	"pStyle",
+	"numStyleLink",
+	"styleLink"
+]);
+const visitReferences = (value, visitor) => {
+	if (typeof value !== "object" || value === null) return;
+	if (Array.isArray(value)) {
+		for (const item of value) visitReferences(item, visitor);
+		return;
+	}
+	for (const [key, item] of Object.entries(value)) {
+		if (key === "listRendering") continue;
+		visitor(key, item, value);
+		visitReferences(item, visitor);
+	}
+};
+/** Normalized HTML states effective CSS; foreign style names carry no package ownership. */
+const flattenClipboardStyleReferences = (paragraphs) => {
+	visitReferences(paragraphs, (key, _value, owner) => {
+		if (STYLE_REFERENCE_FIELDS.has(key)) Reflect.deleteProperty(owner, key);
+	});
+};
+const refused = (message) => Result.err(new DocumentOpRefusal({
+	opType: DOCUMENT_OP_TYPES.SET_PACKAGE_RESOURCES,
+	reason: DOCUMENT_OP_REFUSAL_REASONS.STRUCTURE_MISMATCH,
+	message
+}));
+const THEME_FONT_SLOTS = new Map(Object.entries({
+	asciiTheme: "ascii",
+	hAnsiTheme: "hAnsi",
+	eastAsiaTheme: "eastAsia",
+	csTheme: "cs"
+}));
+const THEME_FONT_REFERENCES = new Set(FONT_THEME_VALUES);
+const lowerSourceTheme = ({ value, source }) => {
+	let unavailable;
+	visitReferences(value, (key, item, owner) => {
+		if (unavailable !== void 0) return;
+		const fontSlot = THEME_FONT_SLOTS.get(key);
+		if (fontSlot !== void 0 && typeof item === "string") {
+			const explicit = Reflect.get(owner, fontSlot);
+			const font = (THEME_FONT_REFERENCES.has(item) ? resolveThemeFont(item, source.package.theme?.fontScheme) : null) || (typeof explicit === "string" ? explicit : void 0);
+			if (font === void 0 || font.length === 0) {
+				unavailable = `The source package does not resolve theme font ${item}.`;
+				return;
+			}
+			Reflect.set(owner, fontSlot, font);
+			Reflect.deleteProperty(owner, key);
+			return;
+		}
+		if (key !== "themeColor") return;
+		if (item === "none") return;
+		if (Reflect.get(owner, "auto") === true) {
+			Reflect.deleteProperty(owner, "themeColor");
+			Reflect.deleteProperty(owner, "themeTint");
+			Reflect.deleteProperty(owner, "themeShade");
+			return;
+		}
+		const rgb = Reflect.get(owner, "rgb");
+		const tint = Reflect.get(owner, "themeTint");
+		const shade = Reflect.get(owner, "themeShade");
+		if (typeof item !== "string" || !isThemeColor(item)) {
+			if (typeof rgb !== "string" || !isValidHexColor(rgb)) {
+				unavailable = "A source theme colour has no known slot or explicit RGB value.";
+				return;
+			}
+			Reflect.deleteProperty(owner, "themeColor");
+			Reflect.deleteProperty(owner, "themeTint");
+			Reflect.deleteProperty(owner, "themeShade");
+			return;
+		}
+		const slot = themeColorSlot(item);
+		const schemeColour = slot === void 0 ? void 0 : source.package.theme?.colorScheme?.[slot];
+		if (schemeColour === void 0 || !isValidHexColor(schemeColour)) {
+			unavailable = `The source package does not resolve theme colour ${item}.`;
+			return;
+		}
+		const resolved = resolveColorToHex({
+			themeColor: item,
+			...typeof rgb === "string" ? { rgb } : {},
+			...typeof tint === "string" ? { themeTint: tint } : {},
+			...typeof shade === "string" ? { themeShade: shade } : {}
+		}, source.package.theme);
+		if (resolved === void 0) {
+			unavailable = `The source package does not resolve theme colour ${item}.`;
+			return;
+		}
+		Reflect.set(owner, "rgb", resolved);
+		Reflect.deleteProperty(owner, "themeColor");
+		Reflect.deleteProperty(owner, "themeTint");
+		Reflect.deleteProperty(owner, "themeShade");
+	});
+	return unavailable === void 0 ? Result.ok(void 0) : refused(unavailable);
+};
+const NEUTRAL_PARAGRAPH_PROPERTIES = {
+	bidi: false,
+	keepNext: false,
+	keepLines: false,
+	widowControl: true,
+	pageBreakBefore: false,
+	contextualSpacing: false,
+	beforeAutospacing: false,
+	afterAutospacing: false,
+	hangingIndent: false,
+	suppressLineNumbers: false,
+	suppressAutoHyphens: false,
+	runInWithNext: false,
+	alignment: "start",
+	indentLeft: 0,
+	indentRight: 0,
+	indentFirstLine: 0,
+	outlineLevel: BODY_TEXT_OUTLINE_LEVEL,
+	numPr: NO_PARAGRAPH_NUMBERING,
+	tabs: [],
+	spaceBefore: 0,
+	spaceAfter: 0,
+	lineSpacing: 240,
+	lineSpacingRule: "auto"
+};
+const NEUTRAL_RUN_PROPERTIES = {
+	color: { auto: true },
+	highlight: "none",
+	underline: { style: "none" },
+	spacing: 0,
+	position: 0,
+	kerning: 0,
+	vertAlign: "baseline"
+};
+const materializeClipboardDefaults = ({ source, destination, paragraphs }) => {
+	const sourceDefinitions = structuredClone(source.package.styles);
+	if (sourceDefinitions !== void 0) {
+		const sourceMap = new Map(sourceDefinitions.styles.map((style) => [style.styleId, style]));
+		sourceDefinitions.styles = sourceDefinitions.styles.map((style) => resolveStyleInheritance(style, sourceMap));
+	}
+	const engine = createStyleEngine(sourceDefinitions);
+	const destinationDefaults = createStyleEngine(destination.package.styles).resolveParagraphStyle(void 0);
+	const neutralizeBooleanDefaults = (formatting, defaults) => {
+		for (const [key, value] of Object.entries(defaults ?? {})) if (typeof value === "boolean" && Reflect.get(formatting, key) === void 0) Reflect.set(formatting, key, false);
+	};
+	let unavailable;
+	const recordRefusal = (message) => {
+		unavailable ??= message;
+	};
+	for (const paragraph of paragraphs) {
+		const authored = paragraph.formatting;
+		const implicitStyle = engine.getDefaultParagraphStyle();
+		const styleId = authored?.styleId ?? implicitStyle?.styleId;
+		const resolved = engine.resolveParagraphStyle(styleId);
+		const formatting = mergeParagraphFormatting(resolved.paragraphFormatting, authored) ?? (destinationDefaults.paragraphFormatting === void 0 ? void 0 : {});
+		if (formatting !== void 0) {
+			if (authored?.numPr === void 0 && sourceDefinitions?.docDefaults?.pPr?.numPr === void 0) delete formatting.numPr;
+			if (authored?.numPrFromStyle === void 0) delete formatting.numPrFromStyle;
+			if (authored?.preserved !== void 0) formatting.preserved = authored.preserved;
+			for (const [key, value] of Object.entries(destinationDefaults.paragraphFormatting ?? {})) {
+				if (key === "preserved" || key === "styleId" || key === "runProperties" || key === "spacingExplicit" || value === void 0 || Reflect.get(formatting, key) !== void 0 || Reflect.get(resolved.paragraphFormatting ?? {}, key) !== void 0) continue;
+				const neutral = Reflect.get(NEUTRAL_PARAGRAPH_PROPERTIES, key);
+				if (neutral === void 0) {
+					recordRefusal(`The source package does not resolve inherited paragraph property ${key}.`);
+					continue;
+				}
+				Reflect.set(formatting, key, structuredClone(neutral));
+			}
+			if (authored?.styleId === void 0 && implicitStyle !== void 0 && engine.hasStyle(implicitStyle.styleId)) formatting.styleId = implicitStyle.styleId;
+			paragraph.formatting = formatting;
+		}
+		const inherited = resolveParagraphBodyRunFormatting({
+			styleId,
+			styleResolver: engine
+		});
+		const materializeRun = (direct) => {
+			const named = direct?.styleId;
+			const cascade = cascadeStyleTextFormatting([
+				{
+					cascade: named === void 0 ? inherited.defaultToggleCascade : inherited.baseToggleCascade,
+					type: "carried"
+				},
+				{
+					formatting: named === void 0 ? void 0 : engine.getRunStyleOwnProperties(named),
+					type: "style"
+				},
+				{
+					formatting: direct,
+					type: "direct"
+				}
+			]).formatting ?? {};
+			neutralizeBooleanDefaults(cascade, destinationDefaults.runFormatting);
+			const themeLowered = lowerSourceTheme({
+				value: cascade,
+				source
+			});
+			if (themeLowered.isErr()) recordRefusal(themeLowered.error.message);
+			for (const [slot, value] of Object.entries(destinationDefaults.runFormatting?.fontFamily ?? {})) {
+				const concreteSlot = THEME_FONT_SLOTS.get(slot) ?? slot;
+				if (value === void 0 || Reflect.get(cascade.fontFamily ?? {}, concreteSlot) !== void 0) continue;
+				if (slot === "hint") {
+					cascade.fontFamily = {
+						...cascade.fontFamily,
+						hint: "default"
+					};
+					continue;
+				}
+				recordRefusal(`The source package does not resolve inherited font slot ${slot}.`);
+			}
+			for (const [key, value] of Object.entries(destinationDefaults.runFormatting ?? {})) {
+				if (key === "preserved" || key === "styleId" || value === void 0 || Reflect.get(cascade, key) !== void 0) continue;
+				const neutral = Reflect.get(NEUTRAL_RUN_PROPERTIES, key);
+				if (neutral === void 0) {
+					recordRefusal(`The source package does not resolve inherited run property ${key}.`);
+					continue;
+				}
+				Reflect.set(cascade, key, structuredClone(neutral));
+			}
+			if (direct?.preserved !== void 0) cascade.preserved = direct.preserved;
+			return cascade;
+		};
+		visitParagraphRuns(paragraph, (run) => {
+			const runFormatting = materializeRun(run.formatting);
+			if (runFormatting !== void 0) run.formatting = runFormatting;
+			for (const change of run.propertyChanges ?? []) {
+				const previous = materializeRun(change.previousFormatting);
+				const current = materializeRun(change.currentFormatting);
+				if (previous !== void 0) change.previousFormatting = previous;
+				if (current !== void 0 && Object.hasOwn(change, "currentFormatting")) change.currentFormatting = current;
+			}
+		});
+		for (const change of paragraph.propertyChanges ?? []) {
+			const previous = change.previousFormatting;
+			const before = mergeParagraphFormatting(engine.resolveParagraphStyle(previous?.styleId).paragraphFormatting, previous);
+			if (before !== void 0) {
+				if (previous?.numPr === void 0) delete before.numPr;
+				if (previous?.preserved !== void 0) before.preserved = previous.preserved;
+				change.previousFormatting = before;
+			}
+		}
+		if (paragraph.content.length === 0) {
+			const markFormatting = materializeRun(paragraph.formatting?.runProperties);
+			if (markFormatting !== void 0) paragraph.formatting = {
+				...paragraph.formatting,
+				runProperties: markFormatting
+			};
+		}
+	}
+	return unavailable === void 0 ? Result.ok(void 0) : refused(unavailable);
+};
+/** Import the transitive style/numbering dependencies of the clipboard, retaining destination defaults. */
+const importClipboardStyles = ({ destination, source, paragraphs }) => {
+	const clonedParagraphs = structuredClone([...paragraphs]);
+	const materialized = materializeClipboardDefaults({
+		source,
+		destination,
+		paragraphs: clonedParagraphs
+	});
+	if (materialized.isErr()) return materialized;
+	const sourceStyles = /* @__PURE__ */ new Map();
+	for (const style of source.package.styles?.styles ?? []) {
+		if (sourceStyles.has(style.styleId)) return refused("The source package contains duplicate style identities.");
+		sourceStyles.set(style.styleId, style);
+	}
+	const styleQueue = [];
+	const numberingQueue = [];
+	const selectedStyles = /* @__PURE__ */ new Set();
+	const numberingIds = /* @__PURE__ */ new Set();
+	const selectReferences = (key, value) => {
+		if (STYLE_REFERENCE_FIELDS.has(key) && typeof value === "string" && !selectedStyles.has(value)) {
+			selectedStyles.add(value);
+			styleQueue.push(value);
+		}
+		if (key === "numId" && typeof value === "number" && !numberingIds.has(value)) {
+			numberingIds.add(value);
+			numberingQueue.push(value);
+		}
+	};
+	for (const paragraph of clonedParagraphs) visitReferences(paragraph, selectReferences);
+	const sourceNums = source.package.numbering?.nums ?? [];
+	const sourceAbstracts = source.package.numbering?.abstractNums ?? [];
+	const nums = new Map(sourceNums.map((num) => [num.numId, num]));
+	const abstracts = new Map(sourceAbstracts.map((abstract) => [abstract.abstractNumId, abstract]));
+	if (nums.size !== sourceNums.length || abstracts.size !== sourceAbstracts.length) return refused("The source package contains duplicate numbering identities.");
+	let styleIndex = 0;
+	let numberingIndex = 0;
+	while (styleIndex < styleQueue.length || numberingIndex < numberingQueue.length) {
+		while (styleIndex < styleQueue.length) {
+			const id = styleQueue.at(styleIndex++);
+			if (id === void 0) return refused("A clipboard style dependency was lost.");
+			const style = sourceStyles.get(id);
+			if (style === void 0) return refused(`The source package does not define clipboard style ${id}.`);
+			visitReferences(style, selectReferences);
+		}
+		while (numberingIndex < numberingQueue.length) {
+			const id = numberingQueue.at(numberingIndex++);
+			if (id === void 0) return refused("A clipboard numbering dependency was lost.");
+			const num = nums.get(id);
+			if (num === void 0) return refused(`The source package does not define clipboard numbering ${id}.`);
+			const abstract = abstracts.get(num.abstractNumId);
+			if (abstract === void 0) return refused("A clipboard numbering instance has no abstract definition.");
+			visitReferences(num, selectReferences);
+			visitReferences(abstract, selectReferences);
+		}
+	}
+	for (const id of selectedStyles) {
+		const ancestors = /* @__PURE__ */ new Set();
+		let ancestor = id;
+		while (ancestor !== void 0) {
+			if (ancestors.has(ancestor)) return refused("The source clipboard style inheritance contains a cycle.");
+			ancestors.add(ancestor);
+			ancestor = sourceStyles.get(ancestor)?.basedOn;
+		}
+	}
+	const occupied = new Set(destination.package.styles?.styles.map(({ styleId }) => styleId));
+	const reserved = /* @__PURE__ */ new Set([...occupied, ...selectedStyles]);
+	const styleIds = /* @__PURE__ */ new Map();
+	for (const id of [...selectedStyles].toSorted()) {
+		if (!occupied.has(id)) {
+			styleIds.set(id, id);
+			continue;
+		}
+		let ordinal = 1;
+		let importedId = `${id}_clipboard${ordinal}`;
+		while (reserved.has(importedId)) importedId = `${id}_clipboard${++ordinal}`;
+		reserved.add(importedId);
+		styleIds.set(id, importedId);
+	}
+	const remap = (key, value, owner) => {
+		if (!STYLE_REFERENCE_FIELDS.has(key) || typeof value !== "string") return;
+		const mapped = styleIds.get(value);
+		if (mapped === void 0) panic("A selected clipboard style has no allocated destination identity.");
+		Reflect.set(owner, key, mapped);
+	};
+	const importedStyles = [];
+	for (const id of [...selectedStyles].toSorted()) {
+		const style = sourceStyles.get(id);
+		if (style === void 0) return refused("A selected clipboard style has no source definition.");
+		const imported = structuredClone(style);
+		visitReferences(imported, remap);
+		const lowered = lowerSourceTheme({
+			value: imported,
+			source
+		});
+		if (lowered.isErr()) return lowered;
+		if (imported.default === true) delete imported.default;
+		importedStyles.push(imported);
+	}
+	for (const paragraph of clonedParagraphs) {
+		visitReferences(paragraph, remap);
+		const lowered = lowerSourceTheme({
+			value: paragraph,
+			source
+		});
+		if (lowered.isErr()) return lowered;
+	}
+	const prior = destination.package.styles;
+	const styles = importedStyles.length === 0 ? prior : {
+		...prior,
+		styles: [...prior?.styles ?? [], ...importedStyles]
+	};
+	return Result.ok({
+		styles,
+		paragraphs: clonedParagraphs,
+		styleIds,
+		numberingIds
+	});
+};
+//#endregion
+export { flattenClipboardStyleReferences, importClipboardStyles };

package/dist/controller/canonicalComments.d.ts

@@ -0,0 +1,41 @@
+import { document_d_exports } from "../types/document.js";
+import { CANONICAL_GAP } from "../types/canonicalCapabilities.js";
+import { Comment } from "../types/content.js";
+import { CreateCommentOp, DocumentOp } from "@stll/docx-core/ops";
+//#region src/controller/canonicalComments.d.ts
+declare const CanonicalCommentError_base: import("better-result").TaggedErrorClass<"CanonicalCommentError">;
+declare class CanonicalCommentError extends CanonicalCommentError_base<{
+  message: string;
+  gap: typeof CANONICAL_GAP.comments;
+}> {}
+type CanonicalCommentCommand = {
+  type: "create";
+  comment: CreateCommentOp["comment"];
+  anchor: CreateCommentOp["anchor"];
+} | {
+  type: "update";
+  id: number;
+  content: Comment["content"];
+} | {
+  type: "resolve";
+  id: number;
+  status: "open" | "resolved";
+} | {
+  type: "delete";
+  id: number;
+} | {
+  type: "replace";
+  comments: readonly Comment[];
+};
+type CompileCanonicalCommentsOptions = {
+  document: document_d_exports.Document;
+  command: CanonicalCommentCommand;
+};
+declare const compileCanonicalComments: ({ document, command }: CompileCanonicalCommentsOptions) => import("better-result").Err<never, CanonicalCommentError> | import("better-result").Ok<{
+  ops: DocumentOp[];
+  document: document_d_exports.Document;
+  commentId: number | undefined;
+}, never>;
+declare const canonicalCommentBody: (document: document_d_exports.Document, text: string) => Comment["content"];
+//#endregion
+export { CanonicalCommentCommand, CanonicalCommentError, canonicalCommentBody, compileCanonicalComments };

package/dist/controller/canonicalComments.js

@@ -0,0 +1,152 @@
+import { CANONICAL_GAP } from "../types/canonicalCapabilities.js";
+import { canonicalJson } from "../utils/canonicalJson.js";
+import { Result, TaggedError } from "better-result";
+import { DOCUMENT_OP_TYPES, allocateCommentAnchorIds, applyDocumentOps, packageParagraphIds } from "@stll/docx-core/ops";
+//#region src/controller/canonicalComments.ts
+/** The one semantic compiler for canonical sidebar, controlled and public comments. */
+var CanonicalCommentError = class extends TaggedError("CanonicalCommentError") {};
+const refuse = (message) => Result.err(new CanonicalCommentError({
+	message,
+	gap: CANONICAL_GAP.comments
+}));
+const compileCanonicalComments = ({ document, command }) => {
+	const current = document.package.document.comments ?? [];
+	const byId = new Map(current.map((comment) => [comment.id, comment]));
+	const ops = [];
+	let commentId;
+	switch (command.type) {
+		case "create":
+			ops.push({
+				type: DOCUMENT_OP_TYPES.CREATE_COMMENT,
+				comment: command.comment,
+				anchor: command.anchor
+			});
+			commentId = command.comment.id;
+			break;
+		case "update":
+			ops.push({
+				type: DOCUMENT_OP_TYPES.UPDATE_COMMENT_CONTENT,
+				id: command.id,
+				content: command.content
+			});
+			break;
+		case "resolve":
+			ops.push({
+				type: DOCUMENT_OP_TYPES.SET_COMMENT_RESOLUTION,
+				id: command.id,
+				status: command.status
+			});
+			break;
+		case "delete": {
+			const comment = byId.get(command.id);
+			if (!comment) return refuse("The comment no longer exists.");
+			ops.push({
+				type: DOCUMENT_OP_TYPES.DELETE_COMMENT,
+				id: command.id,
+				scope: comment.parentId !== void 0 && byId.has(comment.parentId) ? "reply" : "thread"
+			});
+			break;
+		}
+		case "replace": {
+			const nextById = new Map(command.comments.map((comment) => [comment.id, comment]));
+			if (nextById.size !== command.comments.length) return refuse("Comment ids must be unique.");
+			for (const comment of current) {
+				if (nextById.has(comment.id) && comment.parentId !== void 0 && byId.has(comment.parentId) && !nextById.has(comment.parentId)) return refuse("A retained reply requires its parent thread.");
+				if (nextById.has(comment.id)) continue;
+				if (comment.parentId !== void 0 && !nextById.has(comment.parentId) && byId.has(comment.parentId)) continue;
+				ops.push({
+					type: DOCUMENT_OP_TYPES.DELETE_COMMENT,
+					id: comment.id,
+					scope: comment.parentId !== void 0 && byId.has(comment.parentId) ? "reply" : "thread"
+				});
+			}
+			const pending = command.comments.filter((comment) => !byId.has(comment.id));
+			const available = new Set(current.filter((comment) => nextById.has(comment.id)).map((comment) => comment.id));
+			while (pending.length > 0) {
+				const index = pending.findIndex((comment) => comment.parentId !== void 0 && available.has(comment.parentId));
+				if (index < 0) return refuse("New controlled comments require an existing anchored parent without cycles.");
+				const next = pending.splice(index, 1).at(0);
+				if (next === void 0 || next.parentId === void 0) return refuse("The controlled reply is missing its parent.");
+				const { parentId, ...comment } = next;
+				ops.push({
+					type: DOCUMENT_OP_TYPES.CREATE_COMMENT,
+					comment,
+					anchor: {
+						kind: "reply",
+						parentId
+					}
+				});
+				available.add(next.id);
+			}
+			for (const next of command.comments) {
+				const previous = byId.get(next.id);
+				if (!previous) continue;
+				const { content: priorContent, done: priorDone, author: priorAuthor, initials: priorInitials, date: priorDate, ...priorMetadata } = previous;
+				const { content: nextContent, done: nextDone, author: nextAuthor, initials: nextInitials, date: nextDate, ...nextMetadata } = next;
+				if (canonicalJson(priorMetadata) !== canonicalJson(nextMetadata)) return refuse("Controlled comment identity and opaque metadata cannot be replaced.");
+				const patch = {
+					...priorAuthor === nextAuthor ? {} : { author: nextAuthor },
+					...priorInitials === nextInitials ? {} : { initials: Object.hasOwn(next, "initials") ? nextInitials : null },
+					...priorDate === nextDate ? {} : { date: Object.hasOwn(next, "date") ? nextDate : null }
+				};
+				if (canonicalJson(priorContent) !== canonicalJson(nextContent) || Object.keys(patch).length > 0) ops.push({
+					type: DOCUMENT_OP_TYPES.UPDATE_COMMENT_CONTENT,
+					id: next.id,
+					content: nextContent,
+					patch
+				});
+				if (priorDone !== nextDone) {
+					if (nextDone === void 0) return refuse("Resolution changes must name an open or resolved state.");
+					ops.push({
+						type: DOCUMENT_OP_TYPES.SET_COMMENT_RESOLUTION,
+						id: next.id,
+						status: nextDone ? "resolved" : "open"
+					});
+				}
+			}
+			break;
+		}
+		default: return command;
+	}
+	const compiled = [];
+	let draft = document;
+	for (const op of ops) {
+		const materialized = (() => {
+			if (op.type !== DOCUMENT_OP_TYPES.CREATE_COMMENT) return Result.ok(op);
+			const allocation = allocateCommentAnchorIds(draft, op);
+			if (allocation.isErr()) return Result.err(allocation.error);
+			return Result.ok({
+				...op,
+				newIds: allocation.value
+			});
+		})();
+		if (materialized.isErr()) return refuse(materialized.error.message);
+		const applied = applyDocumentOps(draft, [materialized.value]);
+		if (applied.isErr()) return refuse(applied.error.message);
+		compiled.push(materialized.value);
+		draft = applied.value.document;
+	}
+	return Result.ok({
+		ops: compiled,
+		document: draft,
+		commentId
+	});
+};
+const canonicalCommentBody = (document, text) => {
+	const occupied = new Set(packageParagraphIds(document.package).map((id) => id.toUpperCase()));
+	let id = 1;
+	while (occupied.has(id.toString(16).padStart(8, "0").toUpperCase())) id += 1;
+	return [{
+		type: "paragraph",
+		paraId: id.toString(16).padStart(8, "0").toUpperCase(),
+		content: [{
+			type: "run",
+			content: [{
+				type: "text",
+				text
+			}]
+		}]
+	}];
+};
+//#endregion
+export { CanonicalCommentError, canonicalCommentBody, compileCanonicalComments };

package/dist/controller/canonicalComposition.d.ts

@@ -9,26 +9,47 @@ type CompositionOptions = {
     to: number;
     text: string;
     semantic: "composition";
+    compositionPhase?: "correction";
   }) => void;
   refuse: (reason: string) => void;
 };
 type CompositionState = {
   type: "committed";
 } | {
-  type: "provisional" | "refused";
+  type: "provisional";
   baseline: EditorState;
+  view: EditorView;
   phase: "active" | "ended";
+} | {
+  type: "refused";
+  baseline: EditorState;
+  view: EditorView;
+  phase: "active" | "ended";
+  text: string | null;
+};
+type CompositionFinish = {
+  type: "idle" | "cancelled";
+} | {
+  type: "committed" | "refused";
+  text: string | null;
 };
 /** Native IME owns the provisional view; the captured canonical projection stays unchanged. */
 declare const createCanonicalComposition: (options: CompositionOptions) => {
   readonly status: CompositionState["type"];
   readonly active: boolean;
+  matchesCancellationRange: (view: EditorView, range: {
+    from: number;
+    to: number;
+  }) => boolean;
   start: (view: EditorView) => void;
   ended: (view: EditorView) => void;
+  forgetCompleted: () => void;
+  readonly pendingFinal: boolean;
+  authorizeLateFinal: (view: EditorView, text: string | null) => boolean;
   authorizeNative: (view: EditorView) => void;
   flushed: (view: EditorView) => void;
-  recover: (view: EditorView) => void;
-  cancel: (view: EditorView) => void;
+  recover: (view: EditorView) => CompositionFinish;
+  cancel: (view: EditorView) => CompositionFinish;
   reset: () => void;
   accept: (view: EditorView, transaction: Transaction) => boolean;
 };