@stll/folio-core 0.44.0 → 0.46.0

package/dist/prosemirror/schema/nodes.d.ts

@@ -21,6 +21,35 @@ type SymbolAttrs = {
   font: string;
   char: string;
 };
+/** A run child folio does not model, carried through the editor untouched. */
+/**
+ * Which container the captured markup came out of, and goes back into.
+ *
+ * `w:ruby` is a run child and has to be written back inside a `w:r`;
+ * `w:permStart` is a paragraph child and the schema admits none inside a run,
+ * so writing one there would produce a package Word repairs. One atom serves
+ * both because the editor treats them identically — opaque, zero-width unless
+ * the markup shows text, carrying whatever marks surround it — and only the
+ * save path has to tell them apart.
+ */
+declare const PRESERVED_XML_LEVELS: {
+  readonly run: "run";
+  readonly inline: "inline";
+};
+type PreservedXmlLevel = (typeof PRESERVED_XML_LEVELS)[keyof typeof PRESERVED_XML_LEVELS];
+/** A run or inline child folio does not model, carried through the editor untouched. */
+type PreservedXmlAttrs = {
+  /** Replayable markup, as `captureVerbatimXml` wrote it. */
+  xml: string;
+  /** The visible text the markup puts on the line, empty when it shows none. */
+  text: string;
+  level: PreservedXmlLevel;
+};
+/** A block child folio does not model, carried through the editor untouched. */
+type PreservedBlockAttrs = {
+  /** Replayable markup, as `captureVerbatimXml` wrote it. */
+  xml: string;
+};
 type BookmarkBoundaryAttrs = {
   type: "start";
   id: number;
@@ -33,6 +62,14 @@ type BookmarkBoundaryAttrs = {
   id: number;
   displacedByCustomXml?: document_d_exports.DisplacedByCustomXml;
 };
+/**
+ * The position of a comment's `w:commentReference`: the run that paints the
+ * visible comment mark. It is authored data, not a consequence of where the
+ * range ends, so the editor carries it as a node of its own.
+ */
+type CommentReferenceAttrs = {
+  commentId: number;
+};
 /**
  * Paragraph node attributes - maps to ParagraphFormatting
  */
@@ -213,6 +250,17 @@ type ParagraphAttrs = {
   /** Full section properties for paragraphs that end a section.
    *  Used by layout engine for per-section column/page config and round-trip. */
   _sectionProperties?: document_d_exports.SectionProperties;
+  /**
+   * Attributes the authored `w:p` carried and the model has no field for
+   * (`w:rsidR` and its family), carried opaquely so an edit does not rewrite
+   * the document's revision history.
+   *
+   * The remainder follows the record. ProseMirror copies a node's attrs to
+   * both halves of a split, so `fromProseDoc` gives it to the first paragraph
+   * that carries it and to no other: a paragraph the editor created never had
+   * those attributes and must not inherit them from a neighbour.
+   */
+  _preservedAttributes?: document_d_exports.PreservedAttribute[];
   /** Paragraph-property-change tracking entries (`w:pPrChange`).
    *  Preserved opaquely through ProseMirror — the editor does not surface
    *  them in UI today, but stripping them on every edit would corrupt the
@@ -264,6 +312,25 @@ type ImagePositionAttrs = {
     align?: NonNullable<document_d_exports.ImagePosition["vertical"]["alignment"]>;
   };
 };
+/**
+ * The EMUs a drawing's pixel attributes were projected from, keyed by the
+ * pixel attribute each one became.
+ *
+ * EMU → px → EMU does not land back on the same number: a size rounds to whole
+ * pixels, a stroke or an inset to two. Without the authored value beside the
+ * projected one, opening a document and saving it again moved every drawing
+ * off the number its author wrote. `fromProseDoc` writes the authored EMU back
+ * while the pixel attribute still projects from it, and converts the pixel
+ * attribute once an editor command has moved it.
+ *
+ * A key carries `undefined` when the source authored no such value, so an
+ * absent value stays absent rather than acquiring one the document never had.
+ */
+type AuthoredEmuAttrs<Key extends string> = { readonly [K in Key]?: number | undefined; };
+/** The pixel attributes a drawing's `wp:wrap*` insets are projected into. */
+type WrapDistanceAttr = "distTop" | "distBottom" | "distLeft" | "distRight";
+/** The pixel attributes a text box's internal margins are projected into. */
+type TextBoxMarginAttr = "marginTop" | "marginBottom" | "marginLeft" | "marginRight";
 /**
  * Image node attributes
  */
@@ -283,13 +350,23 @@ type ImageAttrs = {
   displayMode?: "inline" | "float" | "block";
   /** CSS float direction for floating images */
   cssFloat?: "left" | "right" | "none";
-  /** CSS transform string (rotation, flip) */
+  /** CSS transform string, derived from the authored transform below. */
   transform?: string;
+  /** Authored `a:xfrm@rot` in degrees; `null` when the drawing states none. */
+  docxRotation?: number | null;
+  /** Authored `a:xfrm@flipH`; `null` when the drawing states none. */
+  docxFlipH?: boolean | null;
+  /** Authored `a:xfrm@flipV`; `null` when the drawing states none. */
+  docxFlipV?: boolean | null;
   /**
    * Opacity in [0, 1] from `<a:alphaModFix amt>`. Undefined / 1 means fully
    * opaque (no CSS `opacity` emitted). eigenpal #424.
    */
   opacity?: number;
+  /** DrawingML `a:lum@bright` as a signed percentage in [-100, 100]. */
+  brightness?: number;
+  /** DrawingML `a:lum@contrast` as a signed percentage in [-100, 100]. */
+  contrast?: number;
   /** Distance from text above (pixels) */
   distTop?: number;
   /** Distance from text below (pixels) */
@@ -320,6 +397,16 @@ type ImageAttrs = {
   position?: ImagePositionAttrs;
   /** Use the containing table cell as the anchor's positioning scope (the OOXML default). */
   layoutInCell?: boolean;
+  /**
+   * The image carries no information, so assistive technology skips it
+   * (`wp:docPr`'s decorative extension). Not {@link hidden}: a decorative
+   * image is still displayed.
+   */
+  decorative?: boolean;
+  /** `wp:docPr @hidden`: the drawing is not displayed. */
+  hidden?: boolean;
+  /** `wp:docPr` extensions folio does not model, carried through verbatim. */
+  docPrExtensions?: string[];
   /**
    * Authored `a:graphicFrameLocks`. Carried through the editor so a resize,
    * which forces the serializer to regenerate DrawingML, cannot silently
@@ -328,6 +415,8 @@ type ImageAttrs = {
   frameLocks?: document_d_exports.ImageFrameLocks;
   /** Border width in pixels */
   borderWidth?: number;
+  /** The EMUs behind `width`, `height`, `borderWidth` and the wrap insets. */
+  _docxAuthoredEmu?: AuthoredEmuAttrs<"width" | "height" | "borderWidth" | WrapDistanceAttr>;
   /** Border color as CSS color string */
   borderColor?: string;
   /** Border style (CSS border-style value) */
@@ -468,6 +557,12 @@ type ShapeAttrs = {
   geometryAdjustments?: string;
   /** Unique identifier */
   shapeId?: string;
+  /** Authored non-visual drawing name (`wp:docPr@name` / `wps:cNvPr@name`) */
+  shapeName?: string;
+  /** Alt text for accessibility (`wp:docPr@descr`) */
+  alt?: string;
+  /** Authored non-visual drawing title (`wp:docPr@title`) */
+  title?: string;
   /** Width in pixels */
   width?: number;
   /** Height in pixels */
@@ -494,12 +589,20 @@ type ShapeAttrs = {
   outlineStyle?: OutlineStyleAttr;
   /** Line cap */
   outlineCap?: NonNullable<document_d_exports.ShapeOutline["cap"]>;
+  /** Line join */
+  outlineJoin?: NonNullable<document_d_exports.ShapeOutline["join"]>;
   /** Head arrow/end marker */
   outlineHeadEnd?: NonNullable<document_d_exports.ShapeOutline["headEnd"]>;
   /** Tail arrow/end marker */
   outlineTailEnd?: NonNullable<document_d_exports.ShapeOutline["tailEnd"]>;
-  /** CSS transform */
+  /** CSS transform, derived from the authored transform below. */
   transform?: string;
+  /** Authored `a:xfrm@rot` in degrees; `null` when the drawing states none. */
+  docxRotation?: number | null;
+  /** Authored `a:xfrm@flipH`; `null` when the drawing states none. */
+  docxFlipH?: boolean | null;
+  /** Authored `a:xfrm@flipV`; `null` when the drawing states none. */
+  docxFlipV?: boolean | null;
   /** Display mode */
   displayMode?: "inline" | "float" | "block";
   /** CSS float */
@@ -538,6 +641,8 @@ type ShapeAttrs = {
    * census).
    */
   _docxRunFormatting?: document_d_exports.TextFormatting;
+  /** The EMUs behind `width`, `height`, `outlineWidth` and the wrap insets. */
+  _docxAuthoredEmu?: AuthoredEmuAttrs<"width" | "height" | "outlineWidth" | WrapDistanceAttr>;
 };
 /**
  * Text box node attributes
@@ -551,6 +656,8 @@ type TextBoxAttrs = {
   width?: number;
   /** Height in pixels */
   height?: number;
+  /** The EMUs behind the size, `outlineWidth`, the wrap insets and the margins. */
+  _docxAuthoredEmu?: AuthoredEmuAttrs<"width" | "height" | "outlineWidth" | WrapDistanceAttr | TextBoxMarginAttr>;
   /** Text fitting behavior */
   autoFit?: document_d_exports.ShapeTextBody["autoFit"];
   /** Authored DrawingML WordArt metadata. */
@@ -559,6 +666,12 @@ type TextBoxAttrs = {
   textWrap?: document_d_exports.ShapeTextBody["textWrap"];
   /** Unique identifier */
   textBoxId?: string;
+  /** Authored non-visual drawing name (`wp:docPr@name` / `wps:cNvPr@name`) */
+  textBoxName?: string;
+  /** Alt text for accessibility (`wp:docPr@descr`) */
+  alt?: string;
+  /** Authored non-visual drawing title (`wp:docPr@title`) */
+  title?: string;
   /** Fill color as CSS color */
   fillColor?: string;
   /** Outline width in pixels */
@@ -569,6 +682,12 @@ type TextBoxAttrs = {
   outlineStyle?: OutlineStyleAttr;
   /** DrawingML rotation and/or flips, serialized as CSS transform functions. */
   transform?: string;
+  /** Authored `a:xfrm@rot` in degrees; `null` when the drawing states none. */
+  docxRotation?: number | null;
+  /** Authored `a:xfrm@flipH`; `null` when the drawing states none. */
+  docxFlipH?: boolean | null;
+  /** Authored `a:xfrm@flipV`; `null` when the drawing states none. */
+  docxFlipV?: boolean | null;
   /** Internal margin top in pixels */
   marginTop?: number;
   /** Internal margin bottom in pixels */
@@ -625,6 +744,17 @@ type TextBoxAttrs = {
   };
   /** Original inline content-control ancestry for save-path reconstruction. */
   _docxInlineSdts?: SdtAttrs[];
+  /**
+   * The attribute remainder of the `w:p` this node was lifted out of.
+   *
+   * A paragraph whose only content was an anchored drawing has no paragraph
+   * node in the editor: this node stands in for it, so it carries the host's
+   * remainder the way `ParagraphAttrs._preservedAttributes` carries a
+   * paragraph's own. Only a `"standalone"` placement has a host to speak for;
+   * an `"inlineWithPrevious"` text box sits in a paragraph that is projected
+   * itself and keeps its own.
+   */
+  _preservedAttributes?: document_d_exports.PreservedAttribute[];
 };
 /** Internal inline position marker for an extracted text box block. */
 type TextBoxAnchorAttrs = {
@@ -699,6 +829,12 @@ type TableRowAttrs = {
   _originalFormatting?: document_d_exports.TableRowFormatting;
   /** Tracked row property changes (w:trPrChange) for round-trip + accept/reject */
   trPrChange?: document_d_exports.TableRowPropertyChange[];
+  /**
+   * Attributes the authored `w:tr` carried and the model has no field for
+   * (`w:rsidR`, `w:rsidDel`, `w:rsidTr`, `w:rsidRPr`), carried opaquely for
+   * the reason `ParagraphAttrs._preservedAttributes` gives.
+   */
+  _preservedAttributes?: document_d_exports.PreservedAttribute[];
 } & ({
   /**
    * Tracked structural row insertion (w:trPr/w:ins). A `"suggested"`
@@ -836,4 +972,4 @@ type TableCellAttrs = {
   _docxVMergeContinuationCells?: unknown;
 };
 //#endregion
-export { BlockSdtAttrs, BookmarkBoundaryAttrs, FieldAttrs, HardBreakAttrs, ImageAttrs, ImagePositionAttrs, MathAttrs, PageBreakRunAttrs, ParagraphAttrs, ParagraphPropertyChangeAttrs, SdtAttrs, ShapeAttrs, SuggestedStructuralMarker, SymbolAttrs, TEXT_BOX_TEXT_BODY_CONTENT_STATE_TYPES, TabAttrs, TableAttrs, TableCellAttrs, TableRowAttrs, TextBoxAnchorAttrs, TextBoxAttrs, TextBoxTextBodyContentState };
+export { AuthoredEmuAttrs, BlockSdtAttrs, BookmarkBoundaryAttrs, CommentReferenceAttrs, FieldAttrs, HardBreakAttrs, ImageAttrs, ImagePositionAttrs, MathAttrs, PRESERVED_XML_LEVELS, PageBreakRunAttrs, ParagraphAttrs, ParagraphPropertyChangeAttrs, PreservedBlockAttrs, PreservedXmlAttrs, PreservedXmlLevel, SdtAttrs, ShapeAttrs, SuggestedStructuralMarker, SymbolAttrs, TEXT_BOX_TEXT_BODY_CONTENT_STATE_TYPES, TabAttrs, TableAttrs, TableCellAttrs, TableRowAttrs, TextBoxAnchorAttrs, TextBoxAttrs, TextBoxTextBodyContentState };

package/dist/prosemirror/schema/nodes.js

@@ -1,7 +1,22 @@
 //#region src/prosemirror/schema/nodes.ts
+/** A run child folio does not model, carried through the editor untouched. */
+/**
+* Which container the captured markup came out of, and goes back into.
+*
+* `w:ruby` is a run child and has to be written back inside a `w:r`;
+* `w:permStart` is a paragraph child and the schema admits none inside a run,
+* so writing one there would produce a package Word repairs. One atom serves
+* both because the editor treats them identically — opaque, zero-width unless
+* the markup shows text, carrying whatever marks surround it — and only the
+* save path has to tell them apart.
+*/
+const PRESERVED_XML_LEVELS = {
+	run: "run",
+	inline: "inline"
+};
 /**
 * Text box node attributes
 */
 const TEXT_BOX_TEXT_BODY_CONTENT_STATE_TYPES = Object.freeze(["source-empty", "authored"]);
 //#endregion
-export { TEXT_BOX_TEXT_BODY_CONTENT_STATE_TYPES };
+export { PRESERVED_XML_LEVELS, TEXT_BOX_TEXT_BODY_CONTENT_STATE_TYPES };

package/dist/prosemirror/trackedRunInlineAtoms.d.ts

@@ -11,11 +11,13 @@ type TrackedRunInlineAtomDisposition = "carry" | "field-carrier" | "outside-wrap
  */
 declare const TRACKED_RUN_INLINE_ATOM_DISPOSITIONS: Readonly<{
   readonly bookmarkBoundary: "carry";
+  readonly commentReference: "transparent";
   readonly field: "field-carrier";
   readonly hardBreak: "carry";
   readonly image: "carry";
   readonly math: "carry";
   readonly pageBreakRun: "page-break-carrier";
+  readonly preservedXml: "carry";
   readonly renderedPageBreak: "transparent";
   readonly shape: "carry";
   readonly structuredField: "carry";

package/dist/prosemirror/trackedRunInlineAtoms.js

@@ -10,11 +10,13 @@ import { panic } from "better-result";
 */
 const TRACKED_RUN_INLINE_ATOM_DISPOSITIONS = Object.freeze({
 	bookmarkBoundary: "carry",
+	commentReference: "transparent",
 	field: "field-carrier",
 	hardBreak: "carry",
 	image: "carry",
 	math: "carry",
 	pageBreakRun: "page-break-carrier",
+	preservedXml: "carry",
 	renderedPageBreak: "transparent",
 	shape: "carry",
 	structuredField: "carry",

package/dist/prosemirror/validation.js

@@ -1,5 +1,6 @@
-import { readBlockSdtAttrs, readCharacterSpacingMarkAttrs, readCharacterStyleMarkAttrs, readCommentMarkAttrs, readEmphasisMarkAttrs, readFieldAttrs, readFontFamilyMarkAttrs, readFontSizeMarkAttrs, readFootnoteRefMarkAttrs, readHardBreakAttrs, readHighlightMarkAttrs, readHyperlinkMarkAttrs, readImageAttrs, readLanguageMarkAttrs, readMathAttrs, readPageBreakRunAttrs, readPageBreakRunOwnerMarkAttrs, readParagraphAttrs, readRunFormattingOverrideMarkAttrs, readRunPropertyChangeMarkAttrs, readRunShadingMarkAttrs, readSdtAttrs, readShapeAttrs, readStrikeMarkAttrs, readSymbolAttrs, readTabAttrs, readTableAttrs, readTableCellAttrs, readTableRowAttrs, readTextBoxAttrs, readTextColorMarkAttrs, readTextEffectMarkAttrs, readTrackedChangeMarkAttrs, readUnderlineMarkAttrs } from "./attrs/index.js";
+import { readBlockSdtAttrs, readCharacterSpacingMarkAttrs, readCharacterStyleMarkAttrs, readCommentMarkAttrs, readEmphasisMarkAttrs, readFieldAttrs, readFontFamilyMarkAttrs, readFontSizeMarkAttrs, readFootnoteRefMarkAttrs, readHardBreakAttrs, readHighlightMarkAttrs, readHyperlinkMarkAttrs, readImageAttrs, readInlineWrapperMarkAttrs, readLanguageMarkAttrs, readMathAttrs, readPageBreakRunAttrs, readPageBreakRunOwnerMarkAttrs, readParagraphAttrs, readPreservedBlockAttrs, readPreservedXmlAttrs, readRunFormattingOverrideMarkAttrs, 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 { readTextBoxAnchorAttrs } from "./textBoxAnchorAttrs.js";
 //#region src/prosemirror/validation.ts
 var ProseMirrorDocumentValidationError = class extends Error {
@@ -142,12 +143,21 @@ const validateNodeAttrs = (node, path, issues) => {
 		case "bookmarkBoundary":
 			appendAttrIssues(path, readBookmarkBoundaryAttrs(node), issues);
 			return;
+		case "commentReference":
+			appendAttrIssues(path, readCommentReferenceAttrs(node), issues);
+			return;
 		case "tab":
 			appendAttrIssues(path, readTabAttrs(node), issues);
 			return;
 		case "symbol":
 			appendAttrIssues(path, readSymbolAttrs(node), issues);
 			return;
+		case "preservedXml":
+			appendAttrIssues(path, readPreservedXmlAttrs(node), issues);
+			return;
+		case "preservedBlock":
+			appendAttrIssues(path, readPreservedBlockAttrs(node), issues);
+			return;
 		case "hardBreak":
 			appendAttrIssues(path, readHardBreakAttrs(node), issues);
 			return;
@@ -184,6 +194,7 @@ 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");
 					if (fieldAttrs.value.fieldKind === "complex" && !hasPageBreakCarrier) issues.push({
 						path: `${path}.content`,
 						message: "Complex fields cannot contain structured result children."
@@ -192,7 +203,7 @@ const validateNodeAttrs = (node, path, issues) => {
 						path: `${path}.content`,
 						message: "Complex field results cannot contain hyperlink content."
 					});
-					else if (!hasStructuredHyperlink && !hasPageBreakCarrier) issues.push({
+					else if (!hasStructuredHyperlink && !hasPageBreakCarrier && !hasPreservedCapture) issues.push({
 						path: `${path}.content`,
 						message: "Structured simple fields require hyperlink content."
 					});
@@ -314,6 +325,9 @@ const validateMarks = (marks, path, issues) => {
 			case "hyperlink":
 				appendAttrIssues(markPath, readHyperlinkMarkAttrs(mark), issues);
 				continue;
+			case "inlineWrapper":
+				appendAttrIssues(markPath, readInlineWrapperMarkAttrs(mark), issues);
+				continue;
 			default: issues.push({
 				path: `${markPath}.type.name`,
 				message: `Unsupported ProseMirror mark type ${mark.type.name}.`

package/dist/prosemirror/yjsDocumentMetadata.d.ts

@@ -0,0 +1,73 @@
+import { Node } from "prosemirror-model";
+import { Result } from "better-result";
+import * as Y from "yjs";
+//#region src/prosemirror/yjsDocumentMetadata.d.ts
+/**
+ * Carry a snapshot written under `version` forward to the next version,
+ * rewriting the fragment in place and answering how many paragraphs changed.
+ */
+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];
+/** 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 = 3;
+/**
+ * The steps that carry a snapshot written under `fromVersion` up to
+ * {@link FOLIO_YJS_ATTR_SCHEMA_VERSION}, in order. Empty when the snapshot is
+ * already current.
+ */
+declare const attrSchemaMigrationSteps: (fromVersion: FolioYjsAttrSchemaVersion) => readonly AttrSchemaMigrationStep[];
+/**
+ * Carry a fragment this build is about to read or write up to the attr shape
+ * this build writes, and stamp the marker.
+ *
+ * Every entry point that hands a fragment to `initProseMirrorDoc` calls this,
+ * for two reasons that are the same reason. A step that rewrites values has to
+ * run before a node is built from them, or the build reads the old shape as
+ * the new one. And the marker has to say what the fragment may now hold before
+ * the first edit writes an attr of this build's shape into it, because an
+ * older build reading an unmarked snapshot drops what it does not know without
+ * a trace.
+ *
+ * Returns how many elements the steps rewrote.
+ */
+declare const applyAttrSchemaMigrations: (ydoc: Y.Doc, fragment: Y.XmlFragment, fromVersion: FolioYjsAttrSchemaVersion) => number;
+declare const FolioYjsAttrSchemaVersionError_base: import("better-result").TaggedErrorClass<"FolioYjsAttrSchemaVersionError">;
+/** Raised when a snapshot's attr-schema marker is ahead of the running code. */
+declare class FolioYjsAttrSchemaVersionError extends FolioYjsAttrSchemaVersionError_base<{
+  message: string;
+  /** The marker exactly as stored, so the host can log what it refused. */
+  marker: unknown;
+  /** The newest attr-schema version this build understands. */
+  supportedVersion: FolioYjsAttrSchemaVersion;
+}> {}
+/**
+ * The attr-schema version a collaboration document was written under.
+ *
+ * An absent marker is version 0: every snapshot predates the marker, so no
+ * backfill is needed to classify one. An older version loads, because
+ * {@link attrSchemaMigrationSteps} says what it means. A marker this
+ * build does not know is a snapshot written by newer code, and reading it would
+ * be a silent misread: ProseMirror copies unknown attr values into the node
+ * verbatim and drops unknown keys without a trace. It fails instead.
+ */
+declare const readYjsAttrSchemaVersion: (ydoc: Y.Doc) => Result<FolioYjsAttrSchemaVersion, FolioYjsAttrSchemaVersionError>;
+declare const proseDocumentParagraphSourceContract: (document: Node) => string | null;
+/** Stamp the attr-schema version of the build that wrote the current fragment. */
+declare const writeYjsAttrSchemaVersion: (ydoc: Y.Doc) => void;
+/**
+ * Write both metadata bindings for a freshly seeded collaboration document.
+ * The attr-schema version is written unconditionally; the paragraph-source
+ * contract only when the seeding document carries one, because a document
+ * built in memory rather than parsed from a package has no source to bind to.
+ */
+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 };

package/dist/prosemirror/yjsDocumentMetadata.js

@@ -0,0 +1,171 @@
+import { PROSE_PARAGRAPH_SOURCE_CONTRACT_ATTR, getProseDocumentParagraphPropertySourceContract } from "../docx/paragraphPropertySource.js";
+import { Result, TaggedError, panic } from "better-result";
+//#region src/prosemirror/yjsDocumentMetadata.ts
+/**
+* Folio's own keys inside a collaboration document: one map, two independent
+* bindings.
+*
+* `paragraphSourceContract` binds the snapshot to the exact bytes of the DOCX
+* it was seeded from. `attrSchemaVersion` binds it to the shape of the node
+* attrs Folio persists. A snapshot can be current on one and stale on the
+* other, so neither key may be derived from the other.
+*/
+const FOLIO_YJS_METADATA_MAP_NAME = "folio:document-metadata";
+const PARAGRAPH_SOURCE_CONTRACT_KEY = "paragraphSourceContract";
+const ATTR_SCHEMA_VERSION_KEY = "attrSchemaVersion";
+/**
+* Version 0 is every snapshot written before the marker existed. The marker
+* shipped without changing a single attr, so carrying a v0 snapshot to v1 is
+* the identity: it only stamps the key.
+*/
+const stampMarkerOnly = () => 0;
+/** The node types whose `fldLock` and `dirty` attrs version 2 rewrites. */
+const FIELD_ELEMENT_NAMES = /* @__PURE__ */ new Set(["field", "structuredField"]);
+const STATED_FLAG_ATTRS = ["fldLock", "dirty"];
+/**
+* Version 1 stored `fldLock` and `dirty` as booleans defaulting to `false`,
+* because the reader that filled them tested `=== true`. A field that authored
+* an explicit `w:fldLock="0"` and one that authored nothing were both stored as
+* `false`, so `false` never meant an explicit off and cannot be kept as one now
+* that `null` is the absence: a v1 snapshot's `false` would start writing an
+* attribute the document never carried.
+*/
+const dropUnstatedFieldFlags = (fragment) => {
+	let rewritten = 0;
+	const visit = (node) => {
+		if ("nodeName" in node && FIELD_ELEMENT_NAMES.has(node.nodeName)) {
+			const attributes = node.getAttributes();
+			let changed = false;
+			for (const attr of STATED_FLAG_ATTRS) if (attributes[attr] === false) {
+				node.removeAttribute(attr);
+				changed = true;
+			}
+			if (changed) rewritten += 1;
+		}
+		for (const child of node.toArray()) if (typeof child !== "string" && "toArray" in child) visit(child);
+	};
+	visit(fragment);
+	return rewritten;
+};
+/**
+* Version 3 adds `docxRotation`, `docxFlipH` and `docxFlipV` to the drawing
+* nodes. A v2 snapshot states none of them, and `readAuthoredTransform` reads
+* such a node from its `transform` CSS, which is the only record it ever had,
+* so nothing has to be rewritten. The marker still moves: a v3 snapshot read
+* by a v2 build would have the three attrs dropped without a trace.
+*/
+const drawingTransformAttrsAreAdditive = () => 0;
+/** Every attr-schema version this build reads, oldest first, with no gaps. */
+const FOLIO_YJS_ATTR_SCHEMA_VERSIONS = [
+	0,
+	1,
+	2,
+	3
+];
+/**
+* The one place a persisted attr-shape change is decided.
+*
+* Changing the shape of any node or mark attr Folio persists means: append the
+* new version to {@link FOLIO_YJS_ATTR_SCHEMA_VERSIONS}, map the previous
+* version to the step that rewrites it, and map the new version to `"current"`.
+* The map is total over the version union, so a version added without a
+* decision does not compile, and `migrateFolioYjsSnapshot` picks the new step
+* up without being touched.
+*/
+const ATTR_SCHEMA_MIGRATIONS = {
+	0: stampMarkerOnly,
+	1: dropUnstatedFieldFlags,
+	2: drawingTransformAttrsAreAdditive,
+	3: "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 = 3;
+/**
+* The steps that carry a snapshot written under `fromVersion` up to
+* {@link FOLIO_YJS_ATTR_SCHEMA_VERSION}, in order. Empty when the snapshot is
+* already current.
+*/
+const attrSchemaMigrationSteps = (fromVersion) => FOLIO_YJS_ATTR_SCHEMA_VERSIONS.filter((version) => version >= fromVersion).flatMap((version) => {
+	const step = ATTR_SCHEMA_MIGRATIONS[version];
+	return step === "current" ? [] : [step];
+});
+/**
+* Carry a fragment this build is about to read or write up to the attr shape
+* this build writes, and stamp the marker.
+*
+* Every entry point that hands a fragment to `initProseMirrorDoc` calls this,
+* for two reasons that are the same reason. A step that rewrites values has to
+* run before a node is built from them, or the build reads the old shape as
+* the new one. And the marker has to say what the fragment may now hold before
+* the first edit writes an attr of this build's shape into it, because an
+* older build reading an unmarked snapshot drops what it does not know without
+* a trace.
+*
+* Returns how many elements the steps rewrote.
+*/
+const applyAttrSchemaMigrations = (ydoc, fragment, fromVersion) => {
+	if (fromVersion === 3) return 0;
+	let rewritten = 0;
+	ydoc.transact(() => {
+		for (const step of attrSchemaMigrationSteps(fromVersion)) rewritten += step(fragment);
+		writeYjsAttrSchemaVersion(ydoc);
+	});
+	return rewritten;
+};
+/** 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 <= 3;
+/**
+* The attr-schema version a collaboration document was written under.
+*
+* An absent marker is version 0: every snapshot predates the marker, so no
+* backfill is needed to classify one. An older version loads, because
+* {@link attrSchemaMigrationSteps} says what it means. A marker this
+* build does not know is a snapshot written by newer code, and reading it would
+* be a silent misread: ProseMirror copies unknown attr values into the node
+* verbatim and drops unknown keys without a trace. It fails instead.
+*/
+const readYjsAttrSchemaVersion = (ydoc) => {
+	const marker = ydoc.getMap(FOLIO_YJS_METADATA_MAP_NAME).get(ATTR_SCHEMA_VERSION_KEY);
+	if (marker === void 0) return Result.ok(0);
+	if (isReadableVersion(marker)) return Result.ok(marker);
+	return Result.err(new FolioYjsAttrSchemaVersionError({
+		marker,
+		message: "The collaboration snapshot was written by a newer Folio attr schema than this build reads.",
+		supportedVersion: 3
+	}));
+};
+const proseDocumentParagraphSourceContract = (document) => {
+	return getProseDocumentParagraphPropertySourceContract(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, 3);
+};
+/**
+* Write both metadata bindings for a freshly seeded collaboration document.
+* The attr-schema version is written unconditionally; the paragraph-source
+* contract only when the seeding document carries one, because a document
+* built in memory rather than parsed from a package has no source to bind to.
+*/
+const writeYjsDocumentMetadata = (ydoc, document) => {
+	writeYjsAttrSchemaVersion(ydoc);
+	const contract = proseDocumentParagraphSourceContract(document);
+	if (contract) ydoc.getMap(FOLIO_YJS_METADATA_MAP_NAME).set(PARAGRAPH_SOURCE_CONTRACT_KEY, contract);
+};
+const readYjsParagraphSourceContract = (ydoc) => {
+	const contract = ydoc.getMap(FOLIO_YJS_METADATA_MAP_NAME).get(PARAGRAPH_SOURCE_CONTRACT_KEY);
+	return typeof contract === "string" ? contract : null;
+};
+const withParagraphSourceContract = (document, contract) => {
+	if (document.type.name !== "doc") panic("A paragraph-property source contract can only attach to a document node");
+	return document.type.create({
+		...document.attrs,
+		[PROSE_PARAGRAPH_SOURCE_CONTRACT_ATTR]: contract
+	}, document.content, document.marks);
+};
+//#endregion
+export { FOLIO_YJS_ATTR_SCHEMA_VERSION, FolioYjsAttrSchemaVersionError, applyAttrSchemaMigrations, attrSchemaMigrationSteps, proseDocumentParagraphSourceContract, readYjsAttrSchemaVersion, readYjsParagraphSourceContract, withParagraphSourceContract, writeYjsAttrSchemaVersion, writeYjsDocumentMetadata };

package/dist/prosemirror/zeroWidthAnchors.js

@@ -1,9 +1,11 @@
 import { BOOKMARK_BOUNDARY_NODE_NAME } from "./extensions/nodes/BookmarkBoundaryExtension.js";
+import { COMMENT_REFERENCE_NODE_NAME } from "./extensions/nodes/CommentReferenceExtension.js";
 import { RENDERED_PAGE_BREAK_NODE_NAME } from "./extensions/nodes/RenderedPageBreakExtension.js";
 import { TEXT_BOX_ANCHOR_NODE_NAME } from "./extensions/nodes/TextBoxAnchorExtension.js";
 //#region src/prosemirror/zeroWidthAnchors.ts
 const ZERO_WIDTH_ANCHOR_NODE_NAMES = /* @__PURE__ */ new Set([
 	BOOKMARK_BOUNDARY_NODE_NAME,
+	COMMENT_REFERENCE_NODE_NAME,
 	RENDERED_PAGE_BREAK_NODE_NAME,
 	TEXT_BOX_ANCHOR_NODE_NAME
 ]);

package/dist/render-dom/commentAnchorAttributes.d.ts

@@ -0,0 +1,37 @@
+//#region src/render-dom/commentAnchorAttributes.d.ts
+/**
+ * How a painted run advertises which comments it sits inside.
+ *
+ * Comment ranges overlap: a run covered by two `w:commentRangeStart` /
+ * `w:commentRangeEnd` pairs belongs to both, and hover styling, the active
+ * highlight and the sidebar anchor all have to see both memberships.
+ *
+ * `data-comment-id` carries the first id, which is what every existing reader
+ * scrolls to and what keeps a single-range run's DOM exactly as the painter
+ * emitted it before. `data-comment-ids` carries the whole membership and is
+ * written only when there is more than one id. Readers ask through the
+ * helpers here instead of reading either attribute, so the two spellings
+ * cannot come to answer differently.
+ */
+/** The painted anchors inside a container, whichever comment they belong to. */
+declare const COMMENT_ANCHOR_SELECTOR = "[data-comment-id]";
+/** What a painter, a reader and their test fakes all offer. */
+type CommentAnchor = {
+  dataset: Record<string, string | undefined>;
+};
+/** Record the comments a painted run sits inside. */
+declare const writeCommentAnchorIds: (element: CommentAnchor, commentIds: readonly number[]) => void;
+/** Every comment id a painted anchor sits inside, first id first. */
+declare const commentAnchorIds: (element: CommentAnchor) => readonly string[];
+/**
+ * Selector for every painted anchor inside one comment, optionally scoped.
+ *
+ * `comment.id` is typed as a number, but a controlled `comments` prop supplied
+ * by the host app is not runtime-checked, so the value is escaped before it is
+ * spliced into the selector.
+ */
+declare const commentAnchorSelector: (id: string | number, scope?: string) => string;
+/** First painted anchor per comment id, in one pass over `container`. */
+declare const indexCommentAnchors: (container: ParentNode) => Map<string, HTMLElement>;
+//#endregion
+export { COMMENT_ANCHOR_SELECTOR, commentAnchorIds, commentAnchorSelector, indexCommentAnchors, writeCommentAnchorIds };