@stll/folio-core 0.56.0 → 0.57.0

package/dist/prosemirror/textInput.js

@@ -19,7 +19,7 @@ const dispatchEditorTextInput = (view, input) => {
 	};
 	if (!view.someProp("handleTextInput", (handler) => handler(view, from, to, text, defaultTransaction))) view.dispatch(defaultTransaction());
 };
-const replacementSelection = (view, event) => {
+const getEditorInputTargetRange = (view, event) => {
 	if (typeof event.getTargetRanges !== "function") return null;
 	const ranges = event.getTargetRanges();
 	if (ranges.length !== 1) return null;
@@ -39,7 +39,7 @@ const handleEditorBeforeInput = (view, event) => {
 	if (event.inputType !== "insertText" && event.inputType !== "insertReplacementText") return false;
 	const text = event.data ?? (event.dataTransfer?.types.includes("text/plain") ? event.dataTransfer.getData("text/plain") : null);
 	if (text === null) return false;
-	const selection = event.inputType === "insertReplacementText" ? replacementSelection(view, event) : view.state.selection;
+	const selection = event.inputType === "insertReplacementText" ? getEditorInputTargetRange(view, event) : view.state.selection;
 	if (!selection) return false;
 	event.preventDefault();
 	dispatchEditorTextInput(view, {
@@ -78,4 +78,4 @@ const createTextInputPlugin = () => {
 	} } });
 };
 //#endregion
-export { afterNativeCompositionFlush, createTextInputPlugin, dispatchEditorTextInput, handleEditorBeforeInput };
+export { afterNativeCompositionFlush, createTextInputPlugin, dispatchEditorTextInput, getEditorInputTargetRange, handleEditorBeforeInput };

package/dist/prosemirror/trackedRevisionPath.d.ts

@@ -13,5 +13,9 @@ type EnclosingInsertionAncestorsOptions = {
 };
 /** The deletion's ancestor path, with the insertion it sits in as the outermost layer. */
 declare const enclosingInsertionAncestors: ({ insertionMark, ancestors, node }: EnclosingInsertionAncestorsOptions) => readonly TrackedRevisionAncestor[];
+/** The authored revision layers already owned by a mark, outermost first. */
+declare const trackedRevisionPathOf: (mark: Mark) => readonly TrackedRevisionAncestor[];
+/** Promote a surviving existing layer; callers cannot supply a fresh identity. */
+declare const retainedTrackedRevisionMark: (mark: Mark, keepLayer: (layer: TrackedRevisionAncestor) => boolean) => Mark | null;
 //#endregion
-export { enclosingInsertionAncestors, inlineWrapperStackOf, trackedRevisionLayerOf };
+export { enclosingInsertionAncestors, inlineWrapperStackOf, retainedTrackedRevisionMark, trackedRevisionLayerOf, trackedRevisionPathOf };

package/dist/prosemirror/trackedRevisionPath.js

@@ -1,5 +1,6 @@
 import { expectInlineWrapperMarkAttrs, expectTrackedChangeMarkAttrs } from "./attrs/index.js";
 import { INLINE_WRAPPER_MARK_NAME } from "./extensions/marks/InlineWrapperExtension.js";
+import { panic } from "better-result";
 //#region src/prosemirror/trackedRevisionPath.ts
 /** The wrappers `node` sits inside, outermost first; empty when it sits in none. */
 const inlineWrapperStackOf = (node) => {
@@ -29,5 +30,42 @@ const enclosingInsertionAncestors = ({ insertionMark, ancestors, node }) => {
 	if (ancestors.some(({ revisionId }) => revisionId === attrs.revisionId)) return ancestors;
 	return [trackedRevisionLayerOf(insertionMark, node), ...ancestors];
 };
+const revisionLayerOf = (mark) => {
+	const attrs = expectTrackedChangeMarkAttrs(mark);
+	let type;
+	if (mark.type.name === "insertion") type = attrs.moveKind === "moveTo" ? "moveTo" : "insertion";
+	else type = attrs.moveKind === "moveFrom" ? "moveFrom" : "deletion";
+	return {
+		type,
+		revisionId: attrs.revisionId,
+		author: attrs.author,
+		...attrs.date ? { date: attrs.date } : {},
+		...attrs.utcDate ? { utcDate: attrs.utcDate } : {},
+		...attrs.initials ? { initials: attrs.initials } : {},
+		outerWrapperCount: attrs._docxOuterWrapperCount ?? 0
+	};
+};
+/** The authored revision layers already owned by a mark, outermost first. */
+const trackedRevisionPathOf = (mark) => [...expectTrackedChangeMarkAttrs(mark)._docxRevisionAncestors ?? [], revisionLayerOf(mark)];
+/** Promote a surviving existing layer; callers cannot supply a fresh identity. */
+const retainedTrackedRevisionMark = (mark, keepLayer) => {
+	const remaining = trackedRevisionPathOf(mark).filter(keepLayer);
+	const active = remaining.at(-1);
+	if (!active) return null;
+	const name = active.type === "insertion" || active.type === "moveTo" ? "insertion" : "deletion";
+	const type = mark.type.schema.marks[name];
+	if (!type) panic("A nested tracked revision has no editor mark type");
+	return type.create({
+		revisionId: active.revisionId,
+		author: active.author,
+		date: active.date ?? null,
+		utcDate: active.utcDate ?? null,
+		initials: active.initials ?? null,
+		moveKind: active.type === "moveTo" || active.type === "moveFrom" ? active.type : null,
+		_historicalFormatting: active.type === "deletion" || active.type === "moveFrom" ? true : null,
+		_docxOuterWrapperCount: active.outerWrapperCount,
+		_docxRevisionAncestors: remaining.length > 1 ? remaining.slice(0, -1) : null
+	});
+};
 //#endregion
-export { enclosingInsertionAncestors, inlineWrapperStackOf, trackedRevisionLayerOf };
+export { enclosingInsertionAncestors, inlineWrapperStackOf, retainedTrackedRevisionMark, trackedRevisionLayerOf, trackedRevisionPathOf };

package/dist/prosemirror/validation.js

@@ -2,7 +2,7 @@ import { readNoteMarkerAttrs } from "../internal/noteMarkerAttrs.js";
 import { readBlockCustomXmlAttrs, readBlockSdtAttrs, readCharacterSpacingMarkAttrs, readCharacterStyleMarkAttrs, readCommentMarkAttrs, readEmphasisMarkAttrs, readFieldAttrs, readFontFamilyMarkAttrs, readFontSizeMarkAttrs, readFootnoteRefMarkAttrs, readHardBreakAttrs, readHighlightMarkAttrs, readHyperlinkMarkAttrs, readImageAttrs, readInlineWrapperMarkAttrs, readLanguageMarkAttrs, readMathAttrs, readPageBreakRunAttrs, readParagraphAttrs, readPreservedBlockAttrs, readPreservedXmlAttrs, readRunFormattingOverrideMarkAttrs, readRunIdentityMarkAttrs, readRunPropertyChangeMarkAttrs, readRunShadingMarkAttrs, readSdtAttrs, readShapeAttrs, readStrikeMarkAttrs, readSymbolAttrs, readTabAttrs, readTableAttrs, readTableCellAttrs, readTableRowAttrs, readTextBoxAttrs, readTextColorMarkAttrs, readTextEffectMarkAttrs, readTrackedChangeMarkAttrs, readUnderlineMarkAttrs } from "./attrs/index.js";
 import { readBookmarkBoundaryAttrs } from "./bookmarkBoundaryAttrs.js";
 import { readCommentReferenceAttrs } from "./commentReferenceAttrs.js";
-import { INLINE_WRAPPER_MARK_NAME } from "./extensions/marks/InlineWrapperExtension.js";
+import { fieldRequiresStructuredContent } from "./fieldRepresentation.js";
 import { readMoveRangeBoundaryAttrs } from "./moveRangeBoundaryAttrs.js";
 import { readRangeAnchorAttrs } from "./rangeAnchorAttrs.js";
 import { readTextBoxAnchorAttrs } from "./textBoxAnchorAttrs.js";
@@ -249,8 +249,6 @@ const validateNodeAttrs = (node, path, issues) => {
 				if (fieldAttrs.ok) {
 					const hasStructuredHyperlink = node.content.content.some((child) => child.marks.some((mark) => mark.type.name === "hyperlink"));
 					const hasPageBreakCarrier = node.content.content.some((child) => child.type.name === "pageBreakRun");
-					const hasPreservedCapture = node.content.content.some((child) => child.type.name === "preservedXml");
-					const hasInlineWrapper = node.content.content.some((child) => child.marks.some((mark) => mark.type.name === INLINE_WRAPPER_MARK_NAME));
 					if (fieldAttrs.value.fieldKind === "complex" && !hasPageBreakCarrier) issues.push({
 						path: `${path}.content`,
 						message: "Complex fields cannot contain structured result children."
@@ -259,9 +257,9 @@ const validateNodeAttrs = (node, path, issues) => {
 						path: `${path}.content`,
 						message: "Complex field results cannot contain hyperlink content."
 					});
-					else if (!hasStructuredHyperlink && !hasPageBreakCarrier && !hasPreservedCapture && !hasInlineWrapper) issues.push({
+					else if (!fieldRequiresStructuredContent(node.content.content)) issues.push({
 						path: `${path}.content`,
-						message: "Structured simple fields require hyperlink, page-break, preserved or wrapper content."
+						message: "Structured simple fields require non-text, hyperlink, wrapper or tracked content."
 					});
 					node.forEach((child, _offset, index) => {
 						const childPath = `${path}.content[${index}]`;

package/dist/prosemirror/yjsDocumentMetadata.d.ts

@@ -8,14 +8,20 @@ import * as Y from "yjs";
  */
 type AttrSchemaMigrationStep = (fragment: Y.XmlFragment) => number;
 /** Every attr-schema version this build reads, oldest first, with no gaps. */
-declare const FOLIO_YJS_ATTR_SCHEMA_VERSIONS: readonly [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11];
+declare const FOLIO_YJS_ATTR_SCHEMA_VERSIONS: readonly [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
 /** An attr-schema version this build can read. */
 type FolioYjsAttrSchemaVersion = (typeof FOLIO_YJS_ATTR_SCHEMA_VERSIONS)[number];
 /**
  * The attr-schema version this build writes. Derived against the migration map
  * so the constant and the map cannot disagree.
  */
-declare const FOLIO_YJS_ATTR_SCHEMA_VERSION = 11;
+declare const FOLIO_YJS_ATTR_SCHEMA_VERSION = 12;
+declare const FolioYjsNoteReferenceSchemaError_base: import("better-result").TaggedErrorClass<"FolioYjsNoteReferenceSchemaError">;
+declare class FolioYjsNoteReferenceSchemaError extends FolioYjsNoteReferenceSchemaError_base<{
+  message: string;
+  schemaVersion: FolioYjsAttrSchemaVersion;
+  requiredSchemaVersion: FolioYjsAttrSchemaVersion;
+}> {}
 /**
  * The steps that carry a snapshot written under `fromVersion` up to
  * {@link FOLIO_YJS_ATTR_SCHEMA_VERSION}, in order. Empty when the snapshot is
@@ -70,4 +76,4 @@ declare const writeYjsDocumentMetadata: (ydoc: Y.Doc, document: Node) => void;
 declare const readYjsParagraphSourceContract: (ydoc: Y.Doc) => string | null;
 declare const withParagraphSourceContract: (document: Node, contract: string) => Node;
 //#endregion
-export { FOLIO_YJS_ATTR_SCHEMA_VERSION, FolioYjsAttrSchemaVersion, FolioYjsAttrSchemaVersionError, applyAttrSchemaMigrations, attrSchemaMigrationSteps, proseDocumentParagraphSourceContract, readYjsAttrSchemaVersion, readYjsParagraphSourceContract, withParagraphSourceContract, writeYjsAttrSchemaVersion, writeYjsDocumentMetadata };
+export { FOLIO_YJS_ATTR_SCHEMA_VERSION, FolioYjsAttrSchemaVersion, FolioYjsAttrSchemaVersionError, FolioYjsNoteReferenceSchemaError, applyAttrSchemaMigrations, attrSchemaMigrationSteps, proseDocumentParagraphSourceContract, readYjsAttrSchemaVersion, readYjsParagraphSourceContract, withParagraphSourceContract, writeYjsAttrSchemaVersion, writeYjsDocumentMetadata };

package/dist/prosemirror/yjsDocumentMetadata.js

@@ -1,4 +1,5 @@
 import { PROSE_PARAGRAPH_SOURCE_CONTRACT_ATTR, getProseDocumentParagraphPropertySourceContract } from "../docx/paragraphPropertySource.js";
+import { isNoteReferenceOccurrenceId } from "./noteReferenceOccurrenceId.js";
 import { mintSectionProperties, parseSectionBreakType } from "./sectionCarrier.js";
 import { Result, TaggedError, panic } from "better-result";
 import { DRAWING_RAW_XML_MODES, outlineLevelFromStatedValue, paragraphNumberingFromSlots } from "@stll/docx-core/model";
@@ -473,7 +474,8 @@ const FOLIO_YJS_ATTR_SCHEMA_VERSIONS = [
 	8,
 	9,
 	10,
-	11
+	11,
+	12
 ];
 /**
 * The one place a persisted attr-shape change is decided.
@@ -497,13 +499,39 @@ const ATTR_SCHEMA_MIGRATIONS = {
 	8: mintSectionPropertiesFromBreakType,
 	9: dropUnstatedPlaceholderFlags,
 	10: renamePageBreakRunOwnerMarkAttr,
-	11: "current"
+	11: stampMarkerOnly,
+	12: "current"
 };
 /**
 * The attr-schema version this build writes. Derived against the migration map
 * so the constant and the map cannot disagree.
 */
-const FOLIO_YJS_ATTR_SCHEMA_VERSION = 11;
+const FOLIO_YJS_ATTR_SCHEMA_VERSION = 12;
+var FolioYjsNoteReferenceSchemaError = class extends TaggedError("FolioYjsNoteReferenceSchemaError") {};
+/** Check before any migration mutates the snapshot or any PM builder can drop text. */
+const requireNoteOccurrenceAttribution = (fragment, schemaVersion) => {
+	const visit = (node) => {
+		for (const child of node.toArray()) {
+			if (typeof child === "string") continue;
+			if (!isXmlText(child)) {
+				if ("toArray" in child) visit(child);
+				continue;
+			}
+			for (const op of child.toDelta()) {
+				const attributes = op.attributes;
+				if (!isRecord(attributes) || attributes["footnoteRef"] == null) continue;
+				const reference = attributes["footnoteRef"];
+				if (isRecord(reference) && isNoteReferenceOccurrenceId(reference["occurrenceId"])) continue;
+				throw new FolioYjsNoteReferenceSchemaError({
+					schemaVersion,
+					requiredSchemaVersion: 12,
+					message: `Yjs schema ${schemaVersion} has unattributed note references; schema 12 requires occurrence identities. Rebuild the collaboration state from the saved DOCX.`
+				});
+			}
+		}
+	};
+	visit(fragment);
+};
 /**
 * The steps that carry a snapshot written under `fromVersion` up to
 * {@link FOLIO_YJS_ATTR_SCHEMA_VERSION}, in order. Empty when the snapshot is
@@ -528,7 +556,8 @@ const attrSchemaMigrationSteps = (fromVersion) => FOLIO_YJS_ATTR_SCHEMA_VERSIONS
 * Returns how many elements the steps rewrote.
 */
 const applyAttrSchemaMigrations = (ydoc, fragment, fromVersion) => {
-	if (fromVersion === 11) return 0;
+	requireNoteOccurrenceAttribution(fragment, fromVersion);
+	if (fromVersion === 12) return 0;
 	let rewritten = 0;
 	ydoc.transact(() => {
 		for (const step of attrSchemaMigrationSteps(fromVersion)) rewritten += step(fragment);
@@ -538,7 +567,7 @@ const applyAttrSchemaMigrations = (ydoc, fragment, fromVersion) => {
 };
 /** Raised when a snapshot's attr-schema marker is ahead of the running code. */
 var FolioYjsAttrSchemaVersionError = class extends TaggedError("FolioYjsAttrSchemaVersionError") {};
-const isReadableVersion = (marker) => typeof marker === "number" && Number.isInteger(marker) && marker >= 0 && marker <= 11;
+const isReadableVersion = (marker) => typeof marker === "number" && Number.isInteger(marker) && marker >= 0 && marker <= 12;
 /**
 * The attr-schema version a collaboration document was written under.
 *
@@ -556,7 +585,7 @@ const readYjsAttrSchemaVersion = (ydoc) => {
 	return Result.err(new FolioYjsAttrSchemaVersionError({
 		marker,
 		message: "The collaboration snapshot was written by a newer Folio attr schema than this build reads.",
-		supportedVersion: 11
+		supportedVersion: 12
 	}));
 };
 const proseDocumentParagraphSourceContract = (document) => {
@@ -564,7 +593,7 @@ const proseDocumentParagraphSourceContract = (document) => {
 };
 /** Stamp the attr-schema version of the build that wrote the current fragment. */
 const writeYjsAttrSchemaVersion = (ydoc) => {
-	ydoc.getMap(FOLIO_YJS_METADATA_MAP_NAME).set(ATTR_SCHEMA_VERSION_KEY, 11);
+	ydoc.getMap(FOLIO_YJS_METADATA_MAP_NAME).set(ATTR_SCHEMA_VERSION_KEY, 12);
 };
 /**
 * Write both metadata bindings for a freshly seeded collaboration document.
@@ -589,4 +618,4 @@ const withParagraphSourceContract = (document, contract) => {
 	}, document.content, document.marks);
 };
 //#endregion
-export { FOLIO_YJS_ATTR_SCHEMA_VERSION, FolioYjsAttrSchemaVersionError, applyAttrSchemaMigrations, attrSchemaMigrationSteps, proseDocumentParagraphSourceContract, readYjsAttrSchemaVersion, readYjsParagraphSourceContract, withParagraphSourceContract, writeYjsAttrSchemaVersion, writeYjsDocumentMetadata };
+export { FOLIO_YJS_ATTR_SCHEMA_VERSION, FolioYjsAttrSchemaVersionError, FolioYjsNoteReferenceSchemaError, applyAttrSchemaMigrations, attrSchemaMigrationSteps, proseDocumentParagraphSourceContract, readYjsAttrSchemaVersion, readYjsParagraphSourceContract, withParagraphSourceContract, writeYjsAttrSchemaVersion, writeYjsDocumentMetadata };

package/dist/types/canonicalCapabilities.d.ts

@@ -3,13 +3,11 @@
 declare const CANONICAL_GAP: {
   readonly authorityRouting: "authority-routing";
   readonly commands: "command-descriptors";
-  readonly suggesting: "adapter-suggesting";
   readonly trackedHyperlinkResolution: "tracked-hyperlink-resolution";
   readonly comments: "comment-model-edits";
   readonly modelEdits: "direct-model-edits";
   readonly sectionProperties: "section-properties";
   readonly watermark: "watermark-model-edits";
-  readonly secondaryStories: "secondary-story-routing";
   readonly collaboration: "collaboration-session";
   readonly dispatch: "unclassified-transactions";
   readonly save: "pm-save-projection";
@@ -52,17 +50,11 @@ declare const CANONICAL_CAPABILITIES: {
     readonly adapters: readonly ["react", "vue"];
     readonly summary: "Hyperlink and TOC suggestions require serializable wrapper review provenance.";
   };
-  readonly "adapter-suggesting": {
-    readonly owner: "adapters";
-    readonly kind: "refusal";
-    readonly adapters: readonly ["react", "vue"];
-    readonly summary: "Adapter suggesting controls and tracked secondary-story edits remain gated.";
-  };
   readonly "comment-model-edits": {
     readonly owner: "adapters";
-    readonly kind: "refusal";
+    readonly kind: "routing";
     readonly adapters: readonly ["react", "vue"];
-    readonly summary: "Comment mutations still use direct model changes.";
+    readonly summary: "Default sessions retain comment model edits; canonical comments use semantic operations.";
   };
   readonly "direct-model-edits": {
     readonly owner: "adapters";
@@ -71,10 +63,10 @@ declare const CANONICAL_CAPABILITIES: {
     readonly summary: "Direct model and pending-suggestion snapshots bypass the canonical journal.";
   };
   readonly "section-properties": {
-    readonly owner: "adapters";
+    readonly owner: "controller";
     readonly kind: "routing";
     readonly adapters: readonly ["react", "vue"];
-    readonly summary: "Section properties select canonical operations or legacy model changes.";
+    readonly summary: "The shared controller journals section properties; default sessions keep model changes.";
   };
   readonly "watermark-model-edits": {
     readonly owner: "adapters";
@@ -82,12 +74,6 @@ declare const CANONICAL_CAPABILITIES: {
     readonly adapters: readonly ["vue"];
     readonly summary: "Vue watermark mutations still change the model directly.";
   };
-  readonly "secondary-story-routing": {
-    readonly owner: "controller";
-    readonly kind: "routing";
-    readonly adapters: readonly ["react", "vue"];
-    readonly summary: "Secondary-story creation, views and history still select their session authority.";
-  };
   readonly "collaboration-session": {
     readonly owner: "controller";
     readonly kind: "refusal";
@@ -152,9 +138,9 @@ declare const CANONICAL_CAPABILITIES: {
   readonly "publicOps.comments": {
     readonly owner: "document-operations";
     readonly defaultSessionMutation: "pm-public-operations";
-    readonly kind: "refusal";
+    readonly kind: "routing";
     readonly adapters: readonly ["react", "vue"];
-    readonly summary: "Public comment operations refuse in canonical sessions; legacy sessions retain PM comments.";
+    readonly summary: "Canonical public comments compile to semantic operations; default sessions retain PM comments.";
   };
   readonly "publicOps.suggestedMode": {
     readonly owner: "document-operations";

package/dist/types/canonicalCapabilities.js

@@ -3,13 +3,11 @@
 const CANONICAL_GAP = {
 	authorityRouting: "authority-routing",
 	commands: "command-descriptors",
-	suggesting: "adapter-suggesting",
 	trackedHyperlinkResolution: "tracked-hyperlink-resolution",
 	comments: "comment-model-edits",
 	modelEdits: "direct-model-edits",
 	sectionProperties: "section-properties",
 	watermark: "watermark-model-edits",
-	secondaryStories: "secondary-story-routing",
 	collaboration: "collaboration-session",
 	dispatch: "unclassified-transactions",
 	save: "pm-save-projection",
@@ -49,17 +47,11 @@ const CANONICAL_CAPABILITIES = {
 		adapters: ["react", "vue"],
 		summary: "Hyperlink and TOC suggestions require serializable wrapper review provenance."
 	},
-	[CANONICAL_GAP.suggesting]: {
-		owner: "adapters",
-		kind: "refusal",
-		adapters: ["react", "vue"],
-		summary: "Adapter suggesting controls and tracked secondary-story edits remain gated."
-	},
 	[CANONICAL_GAP.comments]: {
 		owner: "adapters",
-		kind: "refusal",
+		kind: "routing",
 		adapters: ["react", "vue"],
-		summary: "Comment mutations still use direct model changes."
+		summary: "Default sessions retain comment model edits; canonical comments use semantic operations."
 	},
 	[CANONICAL_GAP.modelEdits]: {
 		owner: "adapters",
@@ -68,10 +60,10 @@ const CANONICAL_CAPABILITIES = {
 		summary: "Direct model and pending-suggestion snapshots bypass the canonical journal."
 	},
 	[CANONICAL_GAP.sectionProperties]: {
-		owner: "adapters",
+		owner: "controller",
 		kind: "routing",
 		adapters: ["react", "vue"],
-		summary: "Section properties select canonical operations or legacy model changes."
+		summary: "The shared controller journals section properties; default sessions keep model changes."
 	},
 	[CANONICAL_GAP.watermark]: {
 		owner: "adapters",
@@ -79,12 +71,6 @@ const CANONICAL_CAPABILITIES = {
 		adapters: ["vue"],
 		summary: "Vue watermark mutations still change the model directly."
 	},
-	[CANONICAL_GAP.secondaryStories]: {
-		owner: "controller",
-		kind: "routing",
-		adapters: ["react", "vue"],
-		summary: "Secondary-story creation, views and history still select their session authority."
-	},
 	[CANONICAL_GAP.collaboration]: {
 		owner: "controller",
 		kind: "refusal",
@@ -149,9 +135,9 @@ const CANONICAL_CAPABILITIES = {
 	[CANONICAL_GAP.publicComments]: {
 		owner: "document-operations",
 		defaultSessionMutation: "pm-public-operations",
-		kind: "refusal",
+		kind: "routing",
 		adapters: ["react", "vue"],
-		summary: "Public comment operations refuse in canonical sessions; legacy sessions retain PM comments."
+		summary: "Canonical public comments compile to semantic operations; default sessions retain PM comments."
 	},
 	[CANONICAL_GAP.publicSuggestedMode]: {
 		owner: "document-operations",

package/dist/types/canonicalComments.d.ts

@@ -0,0 +1,51 @@
+import { CanonicalGap } from "./canonicalCapabilities.js";
+import { Comment } from "./content.js";
+import { OpStory } from "@stll/docx-core/ops";
+//#region src/types/canonicalComments.d.ts
+/** Requests name their anchor; comment metadata never creates an unanchored root. */
+type CanonicalCommentRequest = {
+  type: "create";
+  text: string;
+  author: string;
+  date?: string;
+  anchor: {
+    kind: "selection";
+    from: number;
+    to: number;
+    story: OpStory;
+  } | {
+    kind: "reply";
+    parentId: number;
+  } | {
+    kind: "revision";
+    story: OpStory;
+    revisionId: number;
+  };
+} | {
+  type: "update";
+  id: number;
+  content: Comment["content"];
+} | {
+  type: "resolve";
+  id: number;
+  status: "open" | "resolved";
+} | {
+  type: "delete";
+  id: number;
+} | {
+  type: "replace";
+  comments: readonly Comment[];
+};
+type CanonicalCommentResult = {
+  status: "applied";
+  comments: Comment[];
+  commentId?: number;
+} | {
+  status: "refused";
+  gap: CanonicalGap;
+  message: string;
+  /** Whether the same request can succeed once a pending composition settles. */
+  retry: "afterComposition" | "never";
+};
+//#endregion
+export { CanonicalCommentRequest, CanonicalCommentResult };

package/dist/types/canonicalSections.d.ts

@@ -0,0 +1,12 @@
+import { CANONICAL_GAP } from "./canonicalCapabilities.js";
+//#region src/types/canonicalSections.d.ts
+type CanonicalSectionPropertiesResult = {
+  status: "applied";
+  version: number;
+} | {
+  status: "refused";
+  gap: typeof CANONICAL_GAP.sectionProperties;
+  message: string;
+};
+//#endregion
+export { CanonicalSectionPropertiesResult };

package/dist/utils/headingCollector.js

@@ -1,6 +1,50 @@
 import { resolveHeadingLevel } from "../docx/builtInStyles.js";
 import { readOutlineLevelAttr } from "../prosemirror/outlineLevelAttr.js";
 //#region src/utils/headingCollector.ts
+const RUN_IN_TITLE_MARKS = /* @__PURE__ */ new Set([
+	"bold",
+	"italic",
+	"underline"
+]);
+const runInTitleFormat = (child) => {
+	const marks = child.marks.map(({ type }) => type.name).filter((name) => RUN_IN_TITLE_MARKS.has(name)).sort();
+	return marks.length > 0 ? marks.join("+") : void 0;
+};
+const headingText = (paragraph) => {
+	let text = "";
+	let capture = { status: "searching" };
+	for (let childIndex = 0; childIndex < paragraph.childCount; childIndex += 1) {
+		const child = paragraph.child(childIndex);
+		if (!child.isText) {
+			if (capture.status === "collecting") capture = {
+				status: "complete",
+				text: capture.text
+			};
+			continue;
+		}
+		const childText = child.text || "";
+		text += childText;
+		const format = runInTitleFormat(child);
+		if (capture.status === "searching" && format !== void 0) {
+			capture = {
+				status: "collecting",
+				format,
+				text: childText
+			};
+			continue;
+		}
+		if (capture.status !== "collecting") continue;
+		capture = format === capture.format ? {
+			status: "collecting",
+			format: capture.format,
+			text: capture.text + childText
+		} : {
+			status: "complete",
+			text: capture.text
+		};
+	}
+	return ((capture.status === "searching" ? "" : capture.text.trim()) || text).trim();
+};
 /**
 * Collect all headings from a ProseMirror document, in document order.
 *
@@ -19,10 +63,7 @@ function collectHeadings(doc, styles) {
 			styleId: typeof node.attrs["styleId"] === "string" ? node.attrs["styleId"] : null
 		}, styles);
 		if (level === void 0) return;
-		let text = "";
-		node.forEach((child) => {
-			if (child.isText) text += child.text || "";
-		});
+		const text = headingText(node);
 		if (text.trim()) headings.push({
 			text: text.trim(),
 			level,

package/dist/utils/outlineDepth.d.ts

@@ -0,0 +1,9 @@
+import { HeadingInfo } from "./headingCollector.js";
+//#region src/utils/outlineDepth.d.ts
+/** Maximum heading depth displayed in the document outline. */
+type OutlineDepth = 2 | 3 | "all";
+declare const DEFAULT_OUTLINE_DEPTH = 2;
+/** Filter headings for the outline without changing their document order. */
+declare const filterHeadingsByDepth: (headings: readonly HeadingInfo[], depth: OutlineDepth) => HeadingInfo[];
+//#endregion
+export { DEFAULT_OUTLINE_DEPTH, OutlineDepth, filterHeadingsByDepth };

package/dist/utils/outlineDepth.js

@@ -0,0 +1,9 @@
+//#region src/utils/outlineDepth.ts
+const DEFAULT_OUTLINE_DEPTH = 2;
+/** Filter headings for the outline without changing their document order. */
+const filterHeadingsByDepth = (headings, depth) => {
+	if (depth === "all") return [...headings];
+	return headings.filter((heading) => heading.level < depth);
+};
+//#endregion
+export { DEFAULT_OUTLINE_DEPTH, filterHeadingsByDepth };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-core",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "description": "Headless, framework-neutral core of folio: the OOXML (.docx) parser, document model, ProseMirror integration, and page-layout engine. No React.",
   "keywords": [
     "document-model",
@@ -146,7 +146,7 @@
     "perf": "bun scripts/profile-editor.ts"
   },
   "dependencies": {
-    "@stll/docx-core": "^0.32.0",
+    "@stll/docx-core": "^0.33.0",
     "@stll/docx-utils": "^0.1.0",
     "@stll/template-conditions": "^0.6.2",
     "better-result": "3.0.1",