@stll/folio-core 0.45.0 → 0.47.0

package/dist/prosemirror/numberedRefFields.js

@@ -1,4 +1,4 @@
-import { isNumberingReference } from "../docx/numberingReference.js";
+import { paragraphNumberingLevel, paragraphNumberingReferenceId } from "../docx/numberingReference.js";
 import { expectFieldAttrs, expectParagraphAttrs } from "./attrs/index.js";
 import { expectBookmarkBoundaryAttrs } from "./bookmarkBoundaryAttrs.js";
 import { advanceVisibleListMarker, createListCounterState, resolveListTemplateWithComponents } from "./listMarker.js";
@@ -79,10 +79,10 @@ function numberTargetForParagraph(node, contextStreams, streams) {
 	return visibleTarget;
 }
 function numberTargetForAdvancedMarker(attrs, resolvedMarker, state, contexts) {
-	const numId = attrs.numPr?.numId;
-	if (!isNumberingReference(numId) || attrs.listIsBullet || attrs.listMarkerHidden || attrs.listNumFmt === "none" || !resolvedMarker) return null;
+	const numId = paragraphNumberingReferenceId(attrs.numPr);
+	if (numId === void 0 || attrs.listIsBullet || attrs.listMarkerHidden || attrs.listNumFmt === "none" || !resolvedMarker) return null;
 	const marker = attrs.listMarkerAllCaps ? resolvedMarker.toLocaleUpperCase() : resolvedMarker;
-	const level = attrs.numPr?.ilvl ?? 0;
+	const level = paragraphNumberingLevel(attrs.numPr) ?? 0;
 	if (!Number.isInteger(level) || level < 0 || level > 8) return null;
 	const counters = state.counters.get(numId)?.slice(0, level + 1);
 	const levelFormats = attrs.listLevelNumFmts ?? (attrs.listNumFmt ? [attrs.listNumFmt] : void 0);

package/dist/prosemirror/numberingAttr.d.ts

@@ -0,0 +1,55 @@
+import { ParagraphNumberingOverride } from "@stll/docx-core/model";
+//#region src/prosemirror/numberingAttr.d.ts
+declare const PARAGRAPH_NUMBERING_ATTR: unique symbol;
+/**
+ * The only value a persisted `numPr` attr slot may hold.
+ *
+ * It is the model's union, minted by {@link paragraphNumberingAttr} and by
+ * nothing else. The brand is what makes the mint unavoidable: a
+ * `ParagraphFormatting.numPr` read off a model object, or a record assembled
+ * by hand, does not carry it and so cannot be assigned to an attr. That is the
+ * defect the two tiers kept trading — a model value stored verbatim in an attr
+ * (`toProseDoc`'s `_propertyChanges` projection) and an attr value stored
+ * verbatim in the model-typed `_originalFormatting`
+ * (`paragraphRejectOriginalFormatting`) — each of which read as the other's
+ * shape on the far side.
+ *
+ * Reading needs no unbranding: the brand is a phantom property, so an attr
+ * value is already a `ParagraphNumberingOverride` to every consumer.
+ */
+type ParagraphNumberingAttr = ParagraphNumberingOverride & {
+  readonly [PARAGRAPH_NUMBERING_ATTR]: true;
+};
+/** Mint the attr value for a stated override: the one model-to-attr crossing. */
+declare const paragraphNumberingAttr: (numbering: ParagraphNumberingOverride) => ParagraphNumberingAttr;
+/**
+ * The one shape check over a persisted `numPr` attr.
+ *
+ * The attr validator and the readers that go straight to `node.attrs` share
+ * it, so a snapshot shape can be accepted in one place and rejected in the
+ * other only by deleting this function.
+ *
+ * It is deliberately strict. ProseMirror's `computeAttrs` copies whatever a
+ * stored document holds into the node without validating, so the pre-union
+ * shape — the two `<w:numPr>` slots, where `numId` 0 meant a cancellation —
+ * would otherwise arrive as a `numPr` whose `kind` is `undefined`, which every
+ * `switch` over the union reads as the arm it is not. Returning `null` for it
+ * is what lets the caller refuse.
+ *
+ * `ilvl` is bounded below and not above: real packages carry levels past the
+ * nine the format defines, and docx-core preserves them.
+ */
+declare const paragraphNumberingFromAttrValue: (value: unknown) => ParagraphNumberingAttr | null;
+/**
+ * A paragraph's stated numbering, read straight from an unvalidated attrs
+ * record. `null` is the attr's absent state, which is what the node spec's
+ * default stores.
+ *
+ * A value that is present and not a {@link ParagraphNumberingAttr} panics
+ * rather than being ignored: it can only come from a document written under an
+ * attr schema this build does not read, and `yjsDocumentMetadata`'s version
+ * gate exists to make that unreachable.
+ */
+declare const readParagraphNumberingAttr: (value: unknown) => ParagraphNumberingAttr | null;
+//#endregion
+export { ParagraphNumberingAttr, paragraphNumberingAttr, paragraphNumberingFromAttrValue, readParagraphNumberingAttr };

package/dist/prosemirror/numberingAttr.js

@@ -0,0 +1,74 @@
+import { panic } from "better-result";
+import { NO_PARAGRAPH_NUMBERING, paragraphNumberingFromSlots, paragraphNumberingReference } from "@stll/docx-core/model";
+//#region src/prosemirror/numberingAttr.ts
+const branded = (numbering) => numbering;
+/** Mint the attr value for a stated override: the one model-to-attr crossing. */
+const paragraphNumberingAttr = (numbering) => {
+	switch (numbering.kind) {
+		case "none": return branded(NO_PARAGRAPH_NUMBERING);
+		case "reference": return branded(paragraphNumberingReference({
+			numId: numbering.numId,
+			ilvl: numbering.ilvl
+		}));
+		case "levelOnly": return branded({
+			kind: "levelOnly",
+			ilvl: numbering.ilvl
+		});
+		default: return panic(`Unhandled paragraph numbering ${JSON.stringify(numbering)}`);
+	}
+};
+/** A `<w:numPr>` slot value: an ordinal, so a non-integer or a negative is not one. */
+const isNumberingSlot = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0;
+/**
+* The one shape check over a persisted `numPr` attr.
+*
+* The attr validator and the readers that go straight to `node.attrs` share
+* it, so a snapshot shape can be accepted in one place and rejected in the
+* other only by deleting this function.
+*
+* It is deliberately strict. ProseMirror's `computeAttrs` copies whatever a
+* stored document holds into the node without validating, so the pre-union
+* shape — the two `<w:numPr>` slots, where `numId` 0 meant a cancellation —
+* would otherwise arrive as a `numPr` whose `kind` is `undefined`, which every
+* `switch` over the union reads as the arm it is not. Returning `null` for it
+* is what lets the caller refuse.
+*
+* `ilvl` is bounded below and not above: real packages carry levels past the
+* nine the format defines, and docx-core preserves them.
+*/
+const paragraphNumberingFromAttrValue = (value) => {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+	const kind = Reflect.get(value, "kind");
+	if (kind === "none") return branded(NO_PARAGRAPH_NUMBERING);
+	const ilvl = Reflect.get(value, "ilvl");
+	if (kind === "levelOnly") return isNumberingSlot(ilvl) ? branded({
+		kind: "levelOnly",
+		ilvl
+	}) : null;
+	if (kind !== "reference") return null;
+	const numId = Reflect.get(value, "numId");
+	if (!isNumberingSlot(numId) || ilvl !== void 0 && !isNumberingSlot(ilvl)) return null;
+	const stated = paragraphNumberingFromSlots({
+		ilvl,
+		numId
+	});
+	return stated?.kind === "reference" ? branded(stated) : null;
+};
+/**
+* A paragraph's stated numbering, read straight from an unvalidated attrs
+* record. `null` is the attr's absent state, which is what the node spec's
+* default stores.
+*
+* A value that is present and not a {@link ParagraphNumberingAttr} panics
+* rather than being ignored: it can only come from a document written under an
+* attr schema this build does not read, and `yjsDocumentMetadata`'s version
+* gate exists to make that unreachable.
+*/
+const readParagraphNumberingAttr = (value) => {
+	if (value === void 0 || value === null) return null;
+	const numbering = paragraphNumberingFromAttrValue(value);
+	if (numbering === null) panic(`Invalid paragraph numPr attr: ${JSON.stringify(value)}`);
+	return numbering;
+};
+//#endregion
+export { paragraphNumberingAttr, paragraphNumberingFromAttrValue, readParagraphNumberingAttr };

package/dist/prosemirror/outlineLevelAttr.d.ts

@@ -0,0 +1,29 @@
+import { OutlineLevel } from "@stll/docx-core/model";
+//#region src/prosemirror/outlineLevelAttr.d.ts
+/**
+ * The one shape check over a persisted `outlineLevel` node attr.
+ *
+ * The attr validator and the readers that go straight to `node.attrs` share
+ * it, so a snapshot shape can be accepted in one place and rejected in the
+ * other only by deleting this function.
+ *
+ * It is deliberately strict. ProseMirror's `computeAttrs` copies whatever a
+ * stored document holds into the node without validating, so the pre-union
+ * shape — a bare `number`, where `9` meant body text — would otherwise arrive
+ * as an `outlineLevel` no consumer recognises and every consumer silently
+ * ignores. Returning `null` for it is what lets the caller refuse.
+ */
+declare const outlineLevelFromAttrValue: (value: unknown) => OutlineLevel | null;
+/**
+ * A paragraph's stated outline level, read straight from an unvalidated attrs
+ * record. `null` is the attr's absent state, which is what the node spec's
+ * default stores.
+ *
+ * A value that is present and not an {@link OutlineLevel} panics rather than
+ * being ignored: it can only come from a document written under an attr schema
+ * this build does not read, and `yjsDocumentMetadata`'s version gate exists to
+ * make that unreachable.
+ */
+declare const readOutlineLevelAttr: (value: unknown) => OutlineLevel | null;
+//#endregion
+export { outlineLevelFromAttrValue, readOutlineLevelAttr };

package/dist/prosemirror/outlineLevelAttr.js

@@ -0,0 +1,42 @@
+import { panic } from "better-result";
+import { headingOutlineLevel } from "@stll/docx-core/model";
+//#region src/prosemirror/outlineLevelAttr.ts
+/**
+* The one shape check over a persisted `outlineLevel` node attr.
+*
+* The attr validator and the readers that go straight to `node.attrs` share
+* it, so a snapshot shape can be accepted in one place and rejected in the
+* other only by deleting this function.
+*
+* It is deliberately strict. ProseMirror's `computeAttrs` copies whatever a
+* stored document holds into the node without validating, so the pre-union
+* shape — a bare `number`, where `9` meant body text — would otherwise arrive
+* as an `outlineLevel` no consumer recognises and every consumer silently
+* ignores. Returning `null` for it is what lets the caller refuse.
+*/
+const outlineLevelFromAttrValue = (value) => {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+	const kind = Reflect.get(value, "kind");
+	if (kind === "bodyText") return { kind: "bodyText" };
+	if (kind !== "heading") return null;
+	const level = Reflect.get(value, "level");
+	return typeof level === "number" ? headingOutlineLevel(level) ?? null : null;
+};
+/**
+* A paragraph's stated outline level, read straight from an unvalidated attrs
+* record. `null` is the attr's absent state, which is what the node spec's
+* default stores.
+*
+* A value that is present and not an {@link OutlineLevel} panics rather than
+* being ignored: it can only come from a document written under an attr schema
+* this build does not read, and `yjsDocumentMetadata`'s version gate exists to
+* make that unreachable.
+*/
+const readOutlineLevelAttr = (value) => {
+	if (value === void 0 || value === null) return null;
+	const outlineLevel = outlineLevelFromAttrValue(value);
+	if (outlineLevel === null) panic(`Invalid paragraph outlineLevel attr: ${JSON.stringify(value)}`);
+	return outlineLevel;
+};
+//#endregion
+export { outlineLevelFromAttrValue, readOutlineLevelAttr };

package/dist/prosemirror/pageBreakRunProjection.d.ts

@@ -2,17 +2,27 @@ import { document_d_exports } from "../types/document.js";
 import { ParagraphAttrs } from "./schema/nodes.js";
 import { Node } from "prosemirror-model";
 //#region src/prosemirror/pageBreakRunProjection.d.ts
+/**
+ * Paragraph shapes whose explicit page-break run the editor lays out
+ * approximately.
+ *
+ * Layout splits a paragraph into fragments at its breaks, and a paragraph
+ * property that describes the paragraph as a whole then applies to each
+ * fragment. That is an approximation, not a loss: the run is projected, it is
+ * saved, and the document opens. Folio used to refuse these instead, which
+ * meant a file Word opens could not be opened, laid out or exported at all.
+ */
 declare const PAGE_BREAK_RUN_PARAGRAPH_PROJECTION_MESSAGES: {
-  readonly borders: "A bordered paragraph containing an explicit page-break run cannot be projected";
-  readonly frame: "A framed paragraph containing an explicit page-break run cannot be projected";
-  readonly outline: "An outline paragraph containing an explicit page-break run cannot be projected";
-  readonly textBoxAnchor: "A paragraph whose text-box anchor follows an explicit page-break run cannot be projected";
+  readonly borders: "A bordered paragraph is split at its explicit page-break run, so its border is drawn around each part";
+  readonly frame: "A framed paragraph is split at its explicit page-break run, so its frame applies to each part";
+  readonly outline: "An outline paragraph is split at its explicit page-break run, so each part carries the outline level";
+  readonly textBoxAnchor: "A text-box anchor following an explicit page-break run is hosted by the paragraph's first part";
 };
 type PageBreakRunParagraphProjectionReason = keyof typeof PAGE_BREAK_RUN_PARAGRAPH_PROJECTION_MESSAGES;
 type PageBreakRunParagraphProjectionDisposition = {
-  status: "supported";
+  status: "exact";
 } | {
-  status: "unsupported";
+  status: "approximate";
   reason: PageBreakRunParagraphProjectionReason;
   message: (typeof PAGE_BREAK_RUN_PARAGRAPH_PROJECTION_MESSAGES)[keyof typeof PAGE_BREAK_RUN_PARAGRAPH_PROJECTION_MESSAGES];
 };
@@ -25,7 +35,7 @@ type PageBreakRunParagraphFeatures = {
    * Layout splits such a paragraph into fragments at its breaks, and only the
    * first fragment keeps the paragraph's block id, which is what an anchor
    * resolves its host through. An anchor before the first break is therefore
-   * projected faithfully; one after it would lose its host.
+   * laid out exactly; one after it falls back to the first fragment.
    */
   textBoxAnchorAfterPageBreak: boolean;
 };

package/dist/prosemirror/pageBreakRunProjection.js

@@ -1,34 +1,44 @@
 import { expectParagraphAttrs } from "./attrs/index.js";
 //#region src/prosemirror/pageBreakRunProjection.ts
+/**
+* Paragraph shapes whose explicit page-break run the editor lays out
+* approximately.
+*
+* Layout splits a paragraph into fragments at its breaks, and a paragraph
+* property that describes the paragraph as a whole then applies to each
+* fragment. That is an approximation, not a loss: the run is projected, it is
+* saved, and the document opens. Folio used to refuse these instead, which
+* meant a file Word opens could not be opened, laid out or exported at all.
+*/
 const PAGE_BREAK_RUN_PARAGRAPH_PROJECTION_MESSAGES = {
-	borders: "A bordered paragraph containing an explicit page-break run cannot be projected",
-	frame: "A framed paragraph containing an explicit page-break run cannot be projected",
-	outline: "An outline paragraph containing an explicit page-break run cannot be projected",
-	textBoxAnchor: "A paragraph whose text-box anchor follows an explicit page-break run cannot be projected"
+	borders: "A bordered paragraph is split at its explicit page-break run, so its border is drawn around each part",
+	frame: "A framed paragraph is split at its explicit page-break run, so its frame applies to each part",
+	outline: "An outline paragraph is split at its explicit page-break run, so each part carries the outline level",
+	textBoxAnchor: "A text-box anchor following an explicit page-break run is hosted by the paragraph's first part"
 };
 /** Keep source-import and ProseMirror-layout ownership decisions on one predicate. */
 const pageBreakRunParagraphProjectionDispositionForFeatures = ({ attrs, effectiveFrame, textBoxAnchorAfterPageBreak }) => {
 	if (effectiveFrame !== void 0 && effectiveFrame.dropCap !== "drop" && effectiveFrame.dropCap !== "margin") return {
-		status: "unsupported",
+		status: "approximate",
 		reason: "frame",
 		message: PAGE_BREAK_RUN_PARAGRAPH_PROJECTION_MESSAGES.frame
 	};
 	if (attrs.outlineLevel !== void 0) return {
-		status: "unsupported",
+		status: "approximate",
 		reason: "outline",
 		message: PAGE_BREAK_RUN_PARAGRAPH_PROJECTION_MESSAGES.outline
 	};
 	if (attrs.borders !== void 0 && Object.values(attrs.borders).some((border) => border !== void 0)) return {
-		status: "unsupported",
+		status: "approximate",
 		reason: "borders",
 		message: PAGE_BREAK_RUN_PARAGRAPH_PROJECTION_MESSAGES.borders
 	};
 	if (textBoxAnchorAfterPageBreak) return {
-		status: "unsupported",
+		status: "approximate",
 		reason: "textBoxAnchor",
 		message: PAGE_BREAK_RUN_PARAGRAPH_PROJECTION_MESSAGES.textBoxAnchor
 	};
-	return { status: "supported" };
+	return { status: "exact" };
 };
 const pageBreakRunParagraphProjectionDisposition = (paragraph) => {
 	const attrs = expectParagraphAttrs(paragraph);

package/dist/prosemirror/paragraphFormattingProvenance.d.ts

@@ -67,6 +67,9 @@ declare const PARAGRAPH_FORMATTING_WRITE_BACK: {
   readonly spacingExplicit: {
     readonly kind: "derived";
   };
+  readonly spacingPreservedAttributes: {
+    readonly kind: "original-only";
+  };
   readonly indentLeft: {
     readonly kind: "style-resolved-attr";
     readonly attr: "indentLeft";
@@ -82,6 +85,9 @@ declare const PARAGRAPH_FORMATTING_WRITE_BACK: {
   readonly hangingIndent: {
     readonly kind: "direct-provenance";
   };
+  readonly indentPreservedAttributes: {
+    readonly kind: "original-only";
+  };
   readonly borders: {
     readonly kind: "style-resolved-attr";
     readonly attr: "borders";
@@ -147,6 +153,9 @@ declare const PARAGRAPH_FORMATTING_WRITE_BACK: {
     readonly kind: "style-resolved-attr";
     readonly attr: "runInWithNext";
   };
+  readonly preserved: {
+    readonly kind: "original-only";
+  };
 };
 type StyleResolvedParagraphField = { [Field in keyof typeof PARAGRAPH_FORMATTING_WRITE_BACK]: (typeof PARAGRAPH_FORMATTING_WRITE_BACK)[Field] extends {
   kind: "style-resolved-attr";

package/dist/prosemirror/paragraphFormattingProvenance.js

@@ -28,6 +28,7 @@ const PARAGRAPH_FORMATTING_WRITE_BACK = {
 	beforeAutospacing: { kind: "direct-provenance" },
 	afterAutospacing: { kind: "direct-provenance" },
 	spacingExplicit: { kind: "derived" },
+	spacingPreservedAttributes: { kind: "original-only" },
 	indentLeft: {
 		kind: "style-resolved-attr",
 		attr: "indentLeft"
@@ -41,6 +42,7 @@ const PARAGRAPH_FORMATTING_WRITE_BACK = {
 		attr: "indentFirstLine"
 	},
 	hangingIndent: { kind: "direct-provenance" },
+	indentPreservedAttributes: { kind: "original-only" },
 	borders: {
 		kind: "style-resolved-attr",
 		attr: "borders"
@@ -91,7 +93,8 @@ const PARAGRAPH_FORMATTING_WRITE_BACK = {
 	runInWithNext: {
 		kind: "style-resolved-attr",
 		attr: "runInWithNext"
-	}
+	},
+	preserved: { kind: "original-only" }
 };
 const STYLE_RESOLVED_PARAGRAPH_FIELDS = Object.keys(PARAGRAPH_FORMATTING_WRITE_BACK).filter((field) => PARAGRAPH_FORMATTING_WRITE_BACK[field].kind === "style-resolved-attr");
 /**

package/dist/prosemirror/plugins/selectionTracker.d.ts

@@ -1,4 +1,5 @@
 import { document_d_exports } from "../../types/document.js";
+import { ListState } from "../listState.js";
 import { EditorState, Plugin, PluginKey } from "prosemirror-state";
 //#region src/prosemirror/plugins/selectionTracker.d.ts
 /**
@@ -17,12 +18,8 @@ type SelectionContext = {
   startParagraphIndex: number;
   /** End paragraph index */
   endParagraphIndex: number;
-  /** Whether cursor is in a list */
-  inList: boolean;
-  /** List type if in list */
-  listType?: "bullet" | "numbered";
-  /** List level (0-8) */
-  listLevel?: number;
+  /** Which list the cursor is in, resolved against the numbering definitions. */
+  listState: ListState;
   /** Active comment IDs at cursor position */
   activeCommentIds: number[];
   /** Whether cursor is inside a tracked insertion */

package/dist/prosemirror/plugins/selectionTracker.js

@@ -1,4 +1,5 @@
 import { expectCommentMarkAttrs, expectTrackedChangeMarkAttrs } from "../attrs/index.js";
+import { sameListState } from "../listState.js";
 import { extractSelectionSnapshot } from "../selectionState.js";
 import { Plugin, PluginKey } from "prosemirror-state";
 //#region src/prosemirror/plugins/selectionTracker.ts
@@ -26,12 +27,6 @@ function extractSelectionContext(state) {
 		...snapshot.paragraphFormatting,
 		styleId: snapshot.styleId
 	};
-	const numPr = snapshot.paragraphFormatting.numPr;
-	const inList = !!numPr?.numId;
-	let listType;
-	if (numPr?.numId === 1) listType = "bullet";
-	else if (numPr?.numId) listType = "numbered";
-	const listLevel = numPr?.ilvl;
 	const allMarks = state.storedMarks || (empty ? selection.$from.marks() : []);
 	const activeCommentIds = [];
 	let inInsertion = false;
@@ -54,9 +49,7 @@ function extractSelectionContext(state) {
 		paragraphFormatting,
 		startParagraphIndex: snapshot.startParagraphIndex,
 		endParagraphIndex: snapshot.endParagraphIndex,
-		inList,
-		...listType !== void 0 ? { listType } : {},
-		...listLevel !== void 0 ? { listLevel } : {},
+		listState: snapshot.listState,
 		activeCommentIds,
 		inInsertion,
 		inDeletion
@@ -99,7 +92,7 @@ function arraysEqual(a, b) {
 * Compare two selection contexts for equality
 */
 function contextsEqual(a, b) {
-	return a.hasSelection === b.hasSelection && a.isMultiParagraph === b.isMultiParagraph && a.startParagraphIndex === b.startParagraphIndex && a.endParagraphIndex === b.endParagraphIndex && a.inList === b.inList && a.listType === b.listType && a.listLevel === b.listLevel && a.inInsertion === b.inInsertion && a.inDeletion === b.inDeletion && arraysEqual(a.activeCommentIds, b.activeCommentIds) && JSON.stringify(a.textFormatting) === JSON.stringify(b.textFormatting) && JSON.stringify(a.paragraphFormatting) === JSON.stringify(b.paragraphFormatting);
+	return a.hasSelection === b.hasSelection && a.isMultiParagraph === b.isMultiParagraph && a.startParagraphIndex === b.startParagraphIndex && a.endParagraphIndex === b.endParagraphIndex && sameListState(a.listState, b.listState) && a.inInsertion === b.inInsertion && a.inDeletion === b.inDeletion && arraysEqual(a.activeCommentIds, b.activeCommentIds) && JSON.stringify(a.textFormatting) === JSON.stringify(b.textFormatting) && JSON.stringify(a.paragraphFormatting) === JSON.stringify(b.paragraphFormatting);
 }
 /**
 * Get current selection context from editor state

package/dist/prosemirror/rangeAnchorAttrs.d.ts

@@ -0,0 +1,14 @@
+import { ReadProseMirrorAttrsResult } from "./attrs/index.js";
+import { RangeAnchorAttrs } from "./emptyRangeAnchor.js";
+import { Node } from "prosemirror-model";
+//#region src/prosemirror/rangeAnchorAttrs.d.ts
+/** The two marker values, checked for every field the DOCX serializer reads. */
+declare const readRangeAnchorValues: (start: unknown, end: unknown) => ReadProseMirrorAttrsResult<RangeAnchorAttrs>;
+/**
+ * The anchor's attrs, checked before a save can call string methods or emit
+ * invalid range-marker XML.
+ */
+declare const readRangeAnchorAttrs: (node: Node) => ReadProseMirrorAttrsResult<RangeAnchorAttrs>;
+declare const expectRangeAnchorAttrs: (node: Node) => RangeAnchorAttrs;
+//#endregion
+export { expectRangeAnchorAttrs, readRangeAnchorAttrs, readRangeAnchorValues };

package/dist/prosemirror/rangeAnchorAttrs.js

@@ -0,0 +1,101 @@
+import { isDisplacedByCustomXml } from "./bookmarkBoundaryAttrs.js";
+import { RANGE_END_FOR_START } from "./emptyRangeAnchor.js";
+import { panic } from "better-result";
+//#region src/prosemirror/rangeAnchorAttrs.ts
+const attrsCache = /* @__PURE__ */ new WeakMap();
+const isRecord = (value) => typeof value === "object" && value !== null;
+const isMarkerId = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const isRangeStartType = (value) => typeof value === "string" && value in RANGE_END_FOR_START;
+const validateRangeMarkerAttrs = (marker, path, issues) => {
+	if (!isMarkerId(marker["id"])) issues.push({
+		path: `${path}.id`,
+		message: "Expected a non-negative integer."
+	});
+	const displacedByCustomXml = marker["displacedByCustomXml"];
+	if (displacedByCustomXml !== void 0 && !isDisplacedByCustomXml(displacedByCustomXml)) issues.push({
+		path: `${path}.displacedByCustomXml`,
+		message: "Expected \"next\" or \"prev\"."
+	});
+};
+const validateMoveRangeStartAttrs = (marker, path, issues) => {
+	for (const required of ["name", "author"]) if (typeof marker[required] !== "string" || marker[required].trim() === "") issues.push({
+		path: `${path}.${required}`,
+		message: "Expected a non-empty string on a move range start."
+	});
+	const date = marker["date"];
+	if (date !== void 0 && typeof date !== "string") issues.push({
+		path: `${path}.date`,
+		message: "Expected a string."
+	});
+	for (const column of ["colFirst", "colLast"]) {
+		const value = marker[column];
+		if (value !== void 0 && (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)) issues.push({
+			path: `${path}.${column}`,
+			message: "Expected a non-negative integer."
+		});
+	}
+};
+/** The two marker values, checked for every field the DOCX serializer reads. */
+const readRangeAnchorValues = (start, end) => {
+	const issues = [];
+	if (!isRecord(start) || !isRangeStartType(start["type"])) {
+		issues.push({
+			path: "rangeAnchor.attrs.start",
+			message: `Expected one of ${Object.keys(RANGE_END_FOR_START).join(", ")}.`
+		});
+		return {
+			ok: false,
+			issues
+		};
+	}
+	const expectedEndType = RANGE_END_FOR_START[start["type"]];
+	if (!isRecord(end) || end["type"] !== expectedEndType) issues.push({
+		path: "rangeAnchor.attrs.end",
+		message: `Expected ${expectedEndType}.`
+	});
+	validateRangeMarkerAttrs(start, "rangeAnchor.attrs.start", issues);
+	if (isRecord(end)) {
+		validateRangeMarkerAttrs(end, "rangeAnchor.attrs.end", issues);
+		if (end["id"] !== start["id"]) issues.push({
+			path: "rangeAnchor.attrs.end.id",
+			message: "Expected the id its start carries."
+		});
+	}
+	if (start["type"] !== "commentRangeStart") validateMoveRangeStartAttrs(start, "rangeAnchor.attrs.start", issues);
+	if (issues.length > 0) return {
+		ok: false,
+		issues
+	};
+	return {
+		ok: true,
+		value: {
+			start,
+			end
+		}
+	};
+};
+/**
+* The anchor's attrs, checked before a save can call string methods or emit
+* invalid range-marker XML.
+*/
+const readRangeAnchorAttrs = (node) => {
+	const result = readRangeAnchorValues(node.attrs["start"], node.attrs["end"]);
+	if (node.type.name === "rangeAnchor") return result;
+	return {
+		ok: false,
+		issues: [{
+			path: "rangeAnchor.type.name",
+			message: `Expected rangeAnchor, got ${node.type.name}.`
+		}, ...result.ok ? [] : result.issues]
+	};
+};
+const expectRangeAnchorAttrs = (node) => {
+	const cached = attrsCache.get(node);
+	if (cached) return cached;
+	const result = readRangeAnchorAttrs(node);
+	if (!result.ok) panic(`Invalid ProseMirror range anchor attrs:\n${result.issues.map((issue) => `${issue.path}: ${issue.message}`).join("\n")}`);
+	attrsCache.set(node, result.value);
+	return result.value;
+};
+//#endregion
+export { expectRangeAnchorAttrs, readRangeAnchorAttrs, readRangeAnchorValues };

package/dist/prosemirror/replacedAnnotations.d.ts

@@ -0,0 +1,59 @@
+import { Fragment, Mark, Node, Schema } from "prosemirror-model";
+//#region src/prosemirror/replacedAnnotations.d.ts
+/**
+ * What a replacement does with each mark the schema declares
+ * `inclusive: false`. Boundary inheritance already handles every other mark,
+ * so this table is exactly the set that needs a decision; a new
+ * non-inclusive mark that is missing from it fails
+ * `replacedAnnotations.test.ts` rather than silently following the text.
+ */
+declare const NON_INCLUSIVE_MARK_DISPOSITION: {
+  readonly comment: "carry";
+  readonly hyperlink: "carry";
+  readonly footnoteRef: "followsTheText";
+  readonly runIdentity: "followsTheText";
+  readonly insertion: "followsTheText";
+  readonly deletion: "followsTheText";
+  readonly runPropertyChange: "followsTheText";
+  readonly inlineWrapper: "followsTheText";
+};
+/** The mark names in the schema that a replacement must not silently drop. */
+declare const nonInclusiveMarkNames: (schema: Schema) => string[];
+type ReplacedAnnotations = {
+  /** Marks the replacement must carry, in document order. */
+  carried: readonly Mark[];
+  /** Anchors restored before the replacement, in their original order. */
+  leading: readonly Node[];
+  /** Anchors restored after the replacement, in their original order. */
+  trailing: readonly Node[];
+};
+declare const hasReplacedAnnotations: ({ carried, leading, trailing }: ReplacedAnnotations) => boolean;
+/**
+ * The annotations carried by `[from, to)`. An anchor counts only when the
+ * range covers it whole: a partially covered atom is not deleted by the
+ * replacement either.
+ */
+declare const surveyReplacedAnnotations: (doc: Node, from: number, to: number) => ReplacedAnnotations;
+type AnnotatedReplacementOptions = {
+  annotations: ReplacedAnnotations;
+  /** The replacement's own inline content, already carrying its formatting. */
+  content: Fragment;
+};
+type AnnotatedReplacement = {
+  fragment: Fragment;
+  /** Size of the anchors restored before the replacement's own content. */
+  leadingSize: number;
+  /** Size of the replacement's own content, once the marks are on it. */
+  contentSize: number;
+};
+/** `marks` with the carried marks added, each type's exclusions respected. */
+declare const addCarriedMarks: (marks: readonly Mark[], carried: readonly Mark[]) => readonly Mark[];
+/** `content` with the surveyed marks on it and the surveyed anchors around it. */
+declare const annotatedReplacement: ({ annotations: { carried, leading, trailing }, content }: AnnotatedReplacementOptions) => AnnotatedReplacement;
+/**
+ * The marks a replacement inherits at `[from, to)`, exactly as
+ * `Transaction.insertText` would compute them.
+ */
+declare const inheritedReplacementMarks: (doc: Node, from: number, to: number) => readonly Mark[];
+//#endregion
+export { NON_INCLUSIVE_MARK_DISPOSITION, ReplacedAnnotations, addCarriedMarks, annotatedReplacement, hasReplacedAnnotations, inheritedReplacementMarks, nonInclusiveMarkNames, surveyReplacedAnnotations };