@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

package/src/features/comments/index.js

@@ -0,0 +1,1727 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) if (e.indexOf(p[i]) < 0)
+            t[p[i]] = s[p[i]];
+    return t;
+};
+var __values = (this && this.__values) || function (o) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator], i = 0;
+    if (m) return m.call(o);
+    return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spread = (this && this.__spread) || function () {
+    for (var ar = [], i = 0; i < arguments.length; i++) ar = ar.concat(__read(arguments[i]));
+    return ar;
+};
+export * from './comment-extensions';
+import { DetachedObjectError, DocxError } from '../../core/errors/docx-error';
+import { registerAlwaysOnBodyFeatureBootstrap } from '../document/body-always-on';
+import { parseBodyBlocks, serializeBodyBlocks } from '../document/body-blocks';
+import { WordDocument } from '../document/document';
+import { Paragraph } from '../document/paragraph';
+import { FeatureInlineParagraphItem, FeatureRunParagraphItem, TextRange, WireRunGroup, } from '../document/text-range';
+import { elementChildren, isWml, wmlAttr, wmlElement } from '../document/wml';
+import { allocateRelationshipId } from '../../core/opc/relationships';
+import { partByName, relationshipsForPart } from '../../core/opc/package';
+import { partName, partNameKey, resolveInternalTarget } from '../../core/opc/part-name';
+import { featureId, isFeatureRegistered, registerFeature, registerFeatureInlineHandler, registerFeatureMultiPartHandler, registerFeatureRunLeafHandler, } from '../../core/registry/index';
+import { replaceOrAddPackagePart } from '../../core/registry/multi-part-handlers';
+import { parseXml, serializeXml, WML_TRANSITIONAL_NAMESPACE } from '../../core/xml/index';
+import { WORDML_2010_NAMESPACE } from '../content-controls/index';
+import { CommentExtensionParts, loadCommentExtensionMetadata } from './comment-extensions';
+var COMMENTS = featureId('comments');
+var WML = WML_TRANSITIONAL_NAMESPACE;
+var utf8Decoder = new TextDecoder('utf-8');
+var utf8 = new TextEncoder();
+/**
+ * @private Transitional comments relationship (ECMA-376-4). */
+export var COMMENTS_RELATIONSHIP_TYPE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments';
+/**
+ * @private Strict comments relationship. */
+export var STRICT_COMMENTS_RELATIONSHIP_TYPE = 'http://purl.oclc.org/ooxml/officeDocument/relationships/comments';
+/** @private */
+export var COMMENTS_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml';
+var COMMENTS_RELATIONSHIP_TYPES = [
+    COMMENTS_RELATIONSHIP_TYPE,
+    STRICT_COMMENTS_RELATIONSHIP_TYPE,
+];
+function wmlAttribute(el, localName) {
+    var __ts33_0;
+    return ((__ts33_0 = el.attributes.find(function (a) { return a.localName === localName && (a.namespaceUri === '' || a.prefix === 'w'); })), __ts33_0 == null ? undefined : __ts33_0.value);
+}
+function parseCommentId(raw) {
+    if (raw === undefined || !/^\d+$/.test(raw)) {
+        return undefined;
+    }
+    return Number.parseInt(raw, 10);
+}
+var detachedParagraphOwner = {
+    assertAttachedParagraph: function () {
+        return;
+    },
+    owningDocument: function () {
+        throw new DetachedObjectError('Comment content is not in a WordDocument');
+    },
+};
+/** Ephemeral owner for building default elevated comment reference formatting. */
+var detachedTextRangeOwner = {
+    assertAttachedItem: function () {
+        return;
+    },
+};
+/** Word character style commonly applied to sole-purpose `w:commentReference` runs. */
+var COMMENT_REFERENCE_STYLE_ID = 'CommentReference';
+function formattingFromWireGroup(group) {
+    var cf = group.snapshotCharacterFormat();
+    return {
+        extraAttributes: group.extraAttributes,
+        rPrExtra: cf.rPrExtra,
+        styleIdValue: cf.styleIdValue,
+        boldValue: cf.boldValue,
+        italicValue: cf.italicValue,
+        strikeValue: cf.strikeValue,
+        doubleStrikeValue: cf.doubleStrikeValue,
+        vanishValue: cf.vanishValue,
+        legacyHiddenValue: cf.legacyHiddenValue,
+        noProofValue: cf.noProofValue,
+        fontSizeValue: cf.fontSizeValue,
+        fontSizeBidiValue: cf.fontSizeBidiValue,
+        textColorValue: cf.textColorValue,
+        textColorTheme: cf.textColorTheme,
+        highlightValue: cf.highlightValue,
+        shadingValue: cf.shadingValue,
+        underlineStyleValue: cf.underlineStyleValue,
+        underlineColorValue: cf.underlineColorValue,
+        vertAlignValue: cf.vertAlignValue,
+        smallCapsValue: cf.smallCapsValue,
+        allCapsValue: cf.allCapsValue,
+        fontsValue: cf.fontsValue,
+        characterScaleValue: cf.characterScaleValue,
+        kerningValue: cf.kerningValue,
+        characterSpacingValue: cf.characterSpacingValue,
+        positionValue: cf.positionValue,
+        borderValue: cf.borderValue,
+        languageValue: cf.languageValue,
+        embossValue: cf.embossValue,
+        imprintValue: cf.imprintValue,
+        outlineValue: cf.outlineValue,
+        shadowValue: cf.shadowValue,
+        webHiddenValue: cf.webHiddenValue,
+        bidiValue: cf.bidiValue,
+        complexScriptValue: cf.complexScriptValue,
+        boldBidiValue: cf.boldBidiValue,
+        italicBidiValue: cf.italicBidiValue,
+        emphasisValue: cf.emphasisValue,
+        textEffectValue: cf.textEffectValue,
+        specVanishValue: cf.specVanishValue,
+        snapToGridValue: cf.snapToGridValue,
+    };
+}
+function emptyReferenceRunFormatting(styleId) {
+    var group = new WireRunGroup();
+    // Attach a transient TextRange so CharacterFormat host paths stay consistent.
+    void new TextRange(detachedTextRangeOwner, group);
+    if (styleId !== undefined) {
+        group.characterFormat.characterStyle = styleId;
+    }
+    return formattingFromWireGroup(group);
+}
+function serializeElevatedCommentReference(commentId, formatting) {
+    var group = new WireRunGroup(formatting.extraAttributes);
+    var _extraAttributes = formatting.extraAttributes, characterFormatData = __rest(formatting, ["extraAttributes"]);
+    void _extraAttributes;
+    group.hydrateCharacterFormat(characterFormatData);
+    var rPrChildren = group.characterFormat.buildRPrChildren();
+    var children = [];
+    if (rPrChildren.length > 0) {
+        children.push(wmlElement('rPr', { children: rPrChildren }));
+    }
+    children.push(wmlElement('commentReference', { attributes: [wmlAttr('id', String(commentId))] }));
+    return wmlElement('r', { attributes: group.extraAttributes, children: children });
+}
+function blocksWithSimpleText(text) {
+    var paragraph = wmlElement('p', {
+        children: [wmlElement('r', { children: [wmlElement('t', { children: [{ kind: 'text', value: text }] })] })],
+    });
+    return parseBodyBlocks([paragraph], detachedParagraphOwner);
+}
+function firstParagraphText(blocks) {
+    var e_1, _a, e_2, _b;
+    try {
+        for (var blocks_1 = __values(blocks), blocks_1_1 = blocks_1.next(); !blocks_1_1.done; blocks_1_1 = blocks_1.next()) {
+            var block = blocks_1_1.value;
+            if (block.type !== 'paragraph') {
+                continue;
+            }
+            try {
+                for (var _c = __values(block.paragraph.items), _d = _c.next(); !_d.done; _d = _c.next()) {
+                    var inline = _d.value;
+                    if (inline instanceof TextRange) {
+                        var text = inline.text;
+                        if (text.length > 0) {
+                            return text;
+                        }
+                    }
+                }
+            }
+            catch (e_2_1) { e_2 = { error: e_2_1 }; }
+            finally {
+                try {
+                    if (_d && !_d.done && (_b = _c.return)) _b.call(_c);
+                }
+                finally { if (e_2) throw e_2.error; }
+            }
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (blocks_1_1 && !blocks_1_1.done && (_a = blocks_1.return)) _a.call(blocks_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return undefined;
+}
+/**
+ * Parse a Comments-part `w:date` / ST_DateTime string into a `Date`.
+ *
+ * Returns `undefined` when the value is missing, empty, or not parseable.
+ */
+function parseCommentDateTime(value) {
+    if (value === undefined || value.length === 0) {
+        return undefined;
+    }
+    var ms = Date.parse(value);
+    if (Number.isNaN(ms)) {
+        return undefined;
+    }
+    return new Date(ms);
+}
+function relativeTarget(partNameValue) {
+    return partNameValue.slice('/word/'.length);
+}
+function kindForRelationshipType(type) {
+    return COMMENTS_RELATIONSHIP_TYPES.indexOf(type) !== -1;
+}
+/**
+ * Comment range start marker (`w:commentRangeStart`).
+ *
+ * @public
+ */
+var CommentRangeStart = /** @class */ (function () {
+    /** @private */
+    function CommentRangeStart(commentId) {
+        this.commentId = commentId;
+    }
+    /** @private */
+    CommentRangeStart.prototype.releaseContent = function () {
+        return;
+    };
+    /** @private */
+    CommentRangeStart.prototype.toOpenXml = function () {
+        return wmlElement('commentRangeStart', { attributes: [wmlAttr('id', String(this.commentId))] });
+    };
+    return CommentRangeStart;
+}());
+export { CommentRangeStart };
+/**
+ * Comment range end marker (`w:commentRangeEnd`).
+ *
+ * @public
+ */
+var CommentRangeEnd = /** @class */ (function () {
+    /** @private */
+    function CommentRangeEnd(commentId) {
+        this.commentId = commentId;
+    }
+    /** @private */
+    CommentRangeEnd.prototype.releaseContent = function () {
+        return;
+    };
+    /** @private */
+    CommentRangeEnd.prototype.toOpenXml = function () {
+        return wmlElement('commentRangeEnd', { attributes: [wmlAttr('id', String(this.commentId))] });
+    };
+    return CommentRangeEnd;
+}());
+export { CommentRangeEnd };
+/**
+ * Comment reference run leaf (`w:commentReference`).
+ *
+ * @private
+ */
+var CommentReference = /** @class */ (function () {
+    /** @private */
+    function CommentReference(commentId) {
+        this.commentId = commentId;
+    }
+    /** @private */
+    CommentReference.prototype.toOpenXml = function () {
+        return wmlElement('commentReference', { attributes: [wmlAttr('id', String(this.commentId))] });
+    };
+    return CommentReference;
+}());
+export { CommentReference };
+/**
+ * A comment anchor in a paragraph linked to a Comments part entry.
+ *
+ * Range markers and the reference leaf share the same internal comment id with the
+ * matching {@link Comment} body in the Comments part.
+ *
+ * @private
+ */
+var CommentAnchor = /** @class */ (function () {
+    /** @private */
+    function CommentAnchor(commentId, author, date, anchorRuns, reference) {
+        this.commentId = commentId;
+        this.author = author;
+        this.date = typeof date === 'string' ? parseCommentDateTime(date) : date;
+        this.anchorRuns = anchorRuns;
+        this.reference = reference;
+    }
+    return CommentAnchor;
+}());
+export { CommentAnchor };
+/**
+ * Live view of a comment body in the Comments part (`w:comment`).
+ *
+ * Bound to a WordDocument and comment id; reads go through {@link CommentsCollection}.
+ * Does not expose raw OOXML. Opaque/`preservedXml` entries yield empty paragraphs
+ * until a later modeling slice.
+ *
+ * After main-story elevation (TASK-8055), the same interned instance may also
+ * appear in `paragraph.items` as a feature inline at the former
+ * `w:commentReference` position. Serialize emits one `w:r` + optional `w:rPr` +
+ * `w:commentReference` (ECMA-376-1 §17.13.4.5 / `CT_Markup` in `EG_RunInnerContent`).
+ *
+ * **Identity:** {@link commentFor}, {@link commentForAnchor},
+ * {@link CommentsCollection.comments}, {@link Comment.ancestor}, and elevated
+ * `paragraph.items` slots return the same interned instance per modeled
+ * `(WordDocument, commentId)` for the lifetime of that collection entry (`===` holds).
+ *
+ * @public
+ */
+var Comment = /** @class */ (function () {
+    /** @private */
+    function Comment(WordDocument, commentId) {
+        this.WordDocument = WordDocument;
+        this.id = commentId;
+    }
+    Object.defineProperty(Comment.prototype, "commentId", {
+        /**
+         * Comment id matching range markers and {@link CommentReference.commentId}.
+         *
+         * @private
+         */
+        get: function () {
+            return this.id;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Comment.prototype, "author", {
+        /**
+         * Author of this comment (`w:comment/@w:author`).
+         *
+         * Returns the modeled attribute value when the Comments part entry is known;
+         * empty string when the entry is missing or opaque.
+         * Read-only — set author at insert via {@link appendComment} / {@link insertComment}.
+         */
+        get: function () {
+            var __ts33_1, __ts33_2;
+            return ((__ts33_2 = ((__ts33_1 = commentsFor(this.WordDocument).entryFor(this.id)), __ts33_1 == null ? undefined : __ts33_1.author)), __ts33_2 != null ? __ts33_2 : '');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Comment.prototype, "initials", {
+        /**
+         * Optional `w:comment/@w:initials` (`ST_String`) when present on a modeled entry.
+         *
+         * Undefined when the attribute is absent or the entry is opaque/preserved.
+         * Empty-string values are treated as absent on serialize.
+         */
+        get: function () {
+            var __ts33_3;
+            return ((__ts33_3 = commentsFor(this.WordDocument).entryFor(this.id)), __ts33_3 == null ? undefined : __ts33_3.initials);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Comment.prototype, "date", {
+        /**
+         * Optional comment timestamp (`w:comment/@w:date`, ST_DateTime) as a `Date`.
+         *
+         * `undefined` when the attribute is absent, the entry is opaque, or the stored
+         * value is not parseable. Package storage remains the original ST_DateTime
+         * string for round-trip; this getter does not expose the raw attribute.
+         * Read-only — supply `date` on {@link AppendCommentOptions} when authoring.
+         */
+        get: function () {
+            var __ts33_4;
+            return parseCommentDateTime(((__ts33_4 = commentsFor(this.WordDocument).entryFor(this.id)), __ts33_4 == null ? undefined : __ts33_4.date));
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Comment.prototype, "paragraphs", {
+        /**
+         * Modeled body paragraphs for this comment (`EG_BlockLevelElts` paragraph children).
+         *
+         * Empty when the entry is missing or preserved as opaque XML. Paragraph content
+         * is live — mutate via {@link Paragraph} APIs on the returned instances; there is
+         * no separate setter on this property.
+         */
+        get: function () {
+            return commentsFor(this.WordDocument).paragraphsFor(this.id);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Comment.prototype, "ancestor", {
+        /**
+         * Parent comment when this comment is a reply (`commentsExtended` / `commentEx/@paraIdParent`).
+         *
+         * Top-level comments and replies whose parent cannot be resolved return `undefined`.
+         * Read-only; DocIO-aligned (`WComment.Ancestor`). The returned instance is the
+         * collection-interned {@link Comment} for the parent id when resolved.
+         */
+        get: function () {
+            return commentsFor(this.WordDocument).ancestorFor(this.WordDocument, this.id);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Comment.prototype, "done", {
+        /**
+         * Whether this comment is marked done (`commentsExtended` / `commentEx/@done`).
+         *
+         * Joined from `[MS-DOCX]` `CT_CommentEx/@done` (`ST_OnOff`) onto the same interned
+         * {@link Comment} used by {@link commentFor}. After join: attribute absent or `"0"` →
+         * `false`; other present values → `true`. No matching `commentEx` row → `false`
+         * (MS default 0). Read-only in this slice; mutation is `comments-resolved-state`.
+         */
+        get: function () {
+            var __ts33_5, __ts33_6;
+            return ((__ts33_6 = ((__ts33_5 = commentsFor(this.WordDocument).entryFor(this.id)), __ts33_5 == null ? undefined : __ts33_5.done)), __ts33_6 != null ? __ts33_6 : false);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Capture `w:rPr` from the wire group of the featureRun being elevated.
+     *
+     * @private
+     */
+    Comment.prototype.captureReferenceRunFormatting = function (group) {
+        this.referenceRunFormatting = formattingFromWireGroup(group);
+    };
+    /**
+     * Default character style for newly authored elevated references.
+     *
+     * @private
+     */
+    Comment.prototype.applyDefaultReferenceRunStyle = function () {
+        if (this.referenceRunFormatting === undefined) {
+            this.referenceRunFormatting = emptyReferenceRunFormatting(COMMENT_REFERENCE_STYLE_ID);
+        }
+    };
+    /** @private */
+    Comment.prototype.releaseContent = function () {
+        return;
+    };
+    /**
+     * @private
+     * Serialize as `w:r` + modeled `w:rPr` + `w:commentReference` (D6). Does not emit a
+     * dual legacy leaf for the same elevated occurrence (D10).
+     */
+    Comment.prototype.toOpenXml = function () {
+        var formatting = this.referenceRunFormatting != null ? this.referenceRunFormatting : emptyReferenceRunFormatting();
+        return serializeElevatedCommentReference(this.id, formatting);
+    };
+    return Comment;
+}());
+export { Comment };
+function optionalNonEmptyAttribute(value) {
+    return value !== undefined && value.length > 0 ? value : undefined;
+}
+function serializeCommentsPart(state) {
+    var e_3, _a;
+    var children = [];
+    try {
+        for (var _b = __values(state.entries), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var entry = _c.value;
+            if (entry.preservedXml !== undefined) {
+                children.push(entry.preservedXml);
+                continue;
+            }
+            var attributes = [wmlAttr('id', String(entry.commentId)), wmlAttr('author', entry.author)];
+            var initials = optionalNonEmptyAttribute(entry.initials);
+            if (initials !== undefined) {
+                attributes.push(wmlAttr('initials', initials));
+            }
+            var date = optionalNonEmptyAttribute(entry.date);
+            if (date !== undefined) {
+                attributes.push(wmlAttr('date', date));
+            }
+            children.push(wmlElement('comment', {
+                attributes: attributes,
+                children: serializeBodyBlocks(entry.blocks),
+            }));
+        }
+    }
+    catch (e_3_1) { e_3 = { error: e_3_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_3) throw e_3.error; }
+    }
+    var root = wmlElement('comments', {
+        attributes: state.rootExtra.attributes,
+        namespaceDeclarations: state.rootExtra.namespaceDeclarations.length > 0
+            ? state.rootExtra.namespaceDeclarations
+            : [{ prefix: 'w', namespaceUri: WML }],
+        children: children,
+    });
+    return utf8.encode(serializeXml(root));
+}
+function parseCommentsPart(part, relationship) {
+    var e_4, _a;
+    var root = parseXml(utf8Decoder.decode(part.data));
+    if (!isWml(root, 'comments')) {
+        return undefined;
+    }
+    var entries = [];
+    try {
+        for (var _b = __values(elementChildren(root)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var child = _c.value;
+            if (!isWml(child, 'comment')) {
+                continue;
+            }
+            var commentId = parseCommentId(wmlAttribute(child, 'id'));
+            var author = wmlAttribute(child, 'author');
+            var initials = optionalNonEmptyAttribute(wmlAttribute(child, 'initials'));
+            var date = optionalNonEmptyAttribute(wmlAttribute(child, 'date'));
+            if (commentId === undefined || author === undefined || author.length === 0) {
+                entries.push({
+                    commentId: commentId != null ? commentId : -1,
+                    author: author != null ? author : '',
+                    initials: initials,
+                    date: date,
+                    blocks: [],
+                    preservedXml: child,
+                    lastParaId: undefined,
+                    parentParaId: undefined,
+                    done: undefined,
+                });
+                continue;
+            }
+            var blocks = parseBodyBlocks(child.children, detachedParagraphOwner);
+            entries.push({
+                commentId: commentId,
+                author: author,
+                initials: initials,
+                date: date,
+                blocks: blocks,
+                preservedXml: undefined,
+                lastParaId: lastParagraphParaId(blocks),
+                parentParaId: undefined,
+                done: undefined,
+            });
+        }
+    }
+    catch (e_4_1) { e_4 = { error: e_4_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_4) throw e_4.error; }
+    }
+    return {
+        partName: part.name,
+        relationshipId: relationship.id,
+        relationshipType: relationship.type,
+        rootExtra: {
+            attributes: root.attributes,
+            namespaceDeclarations: root.namespaceDeclarations.length > 0
+                ? root.namespaceDeclarations
+                : [{ prefix: 'w', namespaceUri: WML }],
+        },
+        entries: entries,
+        dirty: false,
+        pendingRelationship: undefined,
+    };
+}
+function allocatePartName(used) {
+    var primary = partName('/word/comments.xml');
+    if (!used.has(partNameKey(primary))) {
+        return primary;
+    }
+    var index = 2;
+    while (used.has(partNameKey(partName("/word/comments" + String(index) + ".xml")))) {
+        index += 1;
+    }
+    return partName("/word/comments" + String(index) + ".xml");
+}
+function allocateCommentId(entries, WordDocument) {
+    var e_5, _a, e_6, _b;
+    var used = new Set();
+    try {
+        for (var entries_1 = __values(entries), entries_1_1 = entries_1.next(); !entries_1_1.done; entries_1_1 = entries_1.next()) {
+            var entry = entries_1_1.value;
+            if (entry.commentId >= 0) {
+                used.add(entry.commentId);
+            }
+        }
+    }
+    catch (e_5_1) { e_5 = { error: e_5_1 }; }
+    finally {
+        try {
+            if (entries_1_1 && !entries_1_1.done && (_a = entries_1.return)) _a.call(entries_1);
+        }
+        finally { if (e_5) throw e_5.error; }
+    }
+    try {
+        for (var _c = __values(WordDocument.listParagraphs()), _d = _c.next(); !_d.done; _d = _c.next()) {
+            var paragraph = _d.value;
+            collectCommentIdsInParagraph(paragraph, used);
+        }
+    }
+    catch (e_6_1) { e_6 = { error: e_6_1 }; }
+    finally {
+        try {
+            if (_d && !_d.done && (_b = _c.return)) _b.call(_c);
+        }
+        finally { if (e_6) throw e_6.error; }
+    }
+    var candidate = 0;
+    while (used.has(candidate)) {
+        candidate += 1;
+    }
+    return candidate;
+}
+function collectCommentIdsInParagraph(paragraph, used) {
+    var e_7, _a;
+    try {
+        for (var _b = __values(paragraph.items), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var inline = _c.value;
+            if (inline instanceof FeatureInlineParagraphItem) {
+                if (inline.value instanceof CommentRangeStart ||
+                    inline.value instanceof CommentRangeEnd ||
+                    inline.value instanceof Comment) {
+                    used.add(inline.value.commentId);
+                }
+                continue;
+            }
+            if (inline instanceof FeatureRunParagraphItem &&
+                inline.value instanceof CommentReference) {
+                used.add(inline.value.commentId);
+            }
+        }
+    }
+    catch (e_7_1) { e_7 = { error: e_7_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_7) throw e_7.error; }
+    }
+}
+function isModeledElevatableComment(catalog, commentId) {
+    var entry = catalog.entryFor(commentId);
+    return entry !== undefined && entry.preservedXml === undefined;
+}
+function isElevatableCommentReferenceItem(item, catalog, elevatedIds) {
+    return (item instanceof FeatureRunParagraphItem &&
+        item.value instanceof CommentReference &&
+        isModeledElevatableComment(catalog, item.value.commentId) &&
+        !elevatedIds.has(item.value.commentId));
+}
+/**
+ * Elevate modeled main-story `w:commentReference` featureRun items to live
+ * {@link Comment} featureInlines. Parse already flattens each `w:r` child into
+ * sibling paragraph items sharing a {@link WireRunGroup}, so residual siblings
+ * stay in place without cloning runs.
+ */
+function elevateCommentReferencesInParagraph(WordDocument, paragraph, catalog, elevatedIds) {
+    var nextItems = [];
+    var changed = false;
+    // Use storage wrappers (snapshot), not projected public leaves — projected
+    // Picture/Shape values are not ParagraphItems and have no attach().
+    var stored = paragraph.snapshot().items;
+    for (var i = 0; i < stored.length; i += 1) {
+        var item = stored[i];
+        if (!isElevatableCommentReferenceItem(item, catalog, elevatedIds)) {
+            nextItems.push(item);
+            continue;
+        }
+        var commentId = item.value.commentId;
+        var comment = catalog.commentInstanceFor(WordDocument, commentId);
+        comment.captureReferenceRunFormatting(item.wireGroup);
+        elevatedIds.add(commentId);
+        changed = true;
+        nextItems.push(new FeatureInlineParagraphItem(COMMENTS, comment));
+    }
+    if (!changed) {
+        return false;
+    }
+    paragraph.hydrate(__assign({}, paragraph.snapshot(), { items: nextItems }));
+    return true;
+}
+/**
+ * Elevate modeled comment references across the main story.
+ *
+ * @private
+ */
+export function elevateCommentReferencesInDocument(WordDocument) {
+    var catalog = commentsFor(WordDocument);
+    catalog.elevateMainStoryReferences(WordDocument);
+}
+/**
+ * Type guard: paragraph feature-inline value is an elevated {@link Comment}.
+ *
+ * @private
+ */
+export function isCommentInline(inline) {
+    return (inline instanceof FeatureInlineParagraphItem &&
+        inline.featureId === COMMENTS &&
+        inline.value instanceof Comment);
+}
+/**
+ * Comments part linked from the Main WordDocument.
+ *
+ * @private
+ */
+var CommentsCollection = /** @class */ (function () {
+    /** @private */
+    function CommentsCollection(state, extensionParts) {
+        /** Interned live Comment views keyed by comment id (per collection / WordDocument). */
+        this.commentViews = new Map();
+        this.state = state;
+        this.extensionParts = extensionParts;
+    }
+    /**
+     * MS-DOCX comment extension metadata discovered from Main WordDocument relationships.
+     *
+     * @private
+     */
+    CommentsCollection.prototype.extensions = function () {
+        return this.extensionParts;
+    };
+    /**
+     * Main-story `commentReference` → elevated {@link Comment} (TASK-8055 / D14).
+     *
+     * Invoked from {@link WordDocument.fromPackage} via duck-typed `afterMainDocumentLoad`
+     * so core/document does not value-import this module (avoids Paragraph TDZ cycles).
+     *
+     * @private
+     */
+    CommentsCollection.prototype.elevateMainStoryReferences = function (WordDocument) {
+        var e_8, _a;
+        var elevatedIds = new Set();
+        try {
+            for (var _b = __values(WordDocument.listParagraphs()), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var paragraph = _c.value;
+                elevateCommentReferencesInParagraph(WordDocument, paragraph, this, elevatedIds);
+            }
+        }
+        catch (e_8_1) { e_8 = { error: e_8_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_8) throw e_8.error; }
+        }
+    };
+    /**
+     * Post-load hook for {@link WordDocument.fromPackage} (duck-typed on feature parts).
+     *
+     * @private
+     */
+    CommentsCollection.prototype.afterMainDocumentLoad = function (WordDocument) {
+        this.elevateMainStoryReferences(WordDocument);
+    };
+    /**
+     * Interned live {@link Comment} for a modeled comment id.
+     *
+     * @private
+     */
+    CommentsCollection.prototype.commentInstanceFor = function (WordDocument, commentId) {
+        var existing = this.commentViews.get(commentId);
+        if (existing !== undefined) {
+            return existing;
+        }
+        var created = new Comment(WordDocument, commentId);
+        this.commentViews.set(commentId, created);
+        return created;
+    };
+    /** @private */
+    CommentsCollection.prototype.isDirty = function () {
+        return (this.state == null ? undefined : this.state.dirty) === true || (this.state == null ? undefined : this.state.pendingRelationship) !== undefined;
+    };
+    /** @private */
+    CommentsCollection.prototype.applyToPackage = function (pkg, mainPartName) {
+        var part = this.state;
+        if (part === undefined || (!part.dirty && part.pendingRelationship === undefined)) {
+            return pkg;
+        }
+        var data = serializeCommentsPart(part);
+        var rel = part.pendingRelationship != null ? part.pendingRelationship : relationshipsForPart(pkg, mainPartName).items.find(function (item) { return item.id === part.relationshipId; });
+        var next = replaceOrAddPackagePart(pkg, mainPartName, part.partName, COMMENTS_CONTENT_TYPE, data, rel);
+        part.dirty = false;
+        part.pendingRelationship = undefined;
+        return next;
+    };
+    /** @private */
+    CommentsCollection.prototype.ensurePart = function (usedRelIds, usedPartNames) {
+        if (this.state !== undefined) {
+            return this.state;
+        }
+        var partNameValue = allocatePartName(usedPartNames);
+        var relId = allocateRelationshipId(usedRelIds);
+        var created = {
+            partName: partNameValue,
+            relationshipId: relId,
+            relationshipType: COMMENTS_RELATIONSHIP_TYPE,
+            rootExtra: {
+                attributes: [],
+                namespaceDeclarations: [{ prefix: 'w', namespaceUri: WML }],
+            },
+            entries: [],
+            dirty: true,
+            pendingRelationship: {
+                id: relId,
+                type: COMMENTS_RELATIONSHIP_TYPE,
+                target: relativeTarget(partNameValue),
+                extraAttributes: [],
+                children: [],
+            },
+        };
+        this.state = created;
+        return created;
+    };
+    /**
+     * Allocate a new modeled comment entry (unique id) and mark the part dirty.
+     *
+     * @param WordDocument - Owning WordDocument (id allocation scans main-story markers).
+     * @param author - `w:author` (may be empty string).
+     * @param commentText - Initial body text (first paragraph / first run).
+     * @param date - Optional `w:date` (ST_DateTime string); empty/omitted → attribute absent.
+     * @param initials - Optional `w:initials`; empty/omitted → attribute absent.
+     * @private
+     */
+    CommentsCollection.prototype.addEntry = function (WordDocument, author, commentText, date, initials) {
+        var part = this.state;
+        if (part === undefined) {
+            throw new DocxError('content/unknown-comment', 'Comments part is not loaded');
+        }
+        var commentId = allocateCommentId(part.entries, WordDocument);
+        part.entries = __spread(part.entries, [
+            {
+                commentId: commentId,
+                author: author,
+                initials: optionalNonEmptyAttribute(initials),
+                date: optionalNonEmptyAttribute(date),
+                blocks: blocksWithSimpleText(commentText),
+                preservedXml: undefined,
+                done: undefined,
+                lastParaId: undefined,
+                parentParaId: undefined,
+            },
+        ]);
+        part.dirty = true;
+        return commentId;
+    };
+    /** @private */
+    CommentsCollection.prototype.entryFor = function (commentId) {
+        return (this.state == null ? undefined : this.state.entries).find(function (entry) { return entry.commentId === commentId; });
+    };
+    /**
+     * Resolve parent comment via DocIO-aligned reverse scan on prior Comments part entries.
+     *
+     * @private
+     */
+    CommentsCollection.prototype.ancestorFor = function (WordDocument, commentId) {
+        var part = this.state;
+        if (part === undefined) {
+            return undefined;
+        }
+        var index = part.entries.findIndex(function (entry) { return entry.commentId === commentId; });
+        if (index < 0) {
+            return undefined;
+        }
+        var parentParaId = part.entries[index] == null ? undefined : part.entries[index].parentParaId;
+        if (parentParaId === undefined || parentParaId.length === 0) {
+            return undefined;
+        }
+        for (var prior = index - 1; prior >= 0; prior -= 1) {
+            var candidate = part.entries[prior];
+            if (candidate === undefined || candidate.preservedXml !== undefined) {
+                continue;
+            }
+            if (candidate.lastParaId === parentParaId) {
+                return this.commentInstanceFor(WordDocument, candidate.commentId);
+            }
+        }
+        return undefined;
+    };
+    /**
+     * Modeled comment ids in Comments part order (opaque preserved entries omitted).
+     *
+     * @private
+     */
+    CommentsCollection.prototype.commentIds = function () {
+        var e_9, _a;
+        if (this.state === undefined) {
+            return [];
+        }
+        var ids = [];
+        try {
+            for (var _b = __values(this.state.entries), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var entry = _c.value;
+                if (entry.preservedXml !== undefined) {
+                    continue;
+                }
+                ids.push(entry.commentId);
+            }
+        }
+        catch (e_9_1) { e_9 = { error: e_9_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_9) throw e_9.error; }
+        }
+        return ids;
+    };
+    /**
+     * Live {@link Comment} views for every modeled Comments part entry, in part order.
+     *
+     * Each id is interned: repeated collection / lookup APIs return the same instance.
+     *
+     * @private
+     */
+    CommentsCollection.prototype.comments = function (WordDocument) {
+        var _this = this;
+        return this.commentIds().map(function (commentId) { return _this.commentInstanceFor(WordDocument, commentId); });
+    };
+    /**
+     * Body paragraphs of a modeled comment, when present.
+     *
+     * @private
+     */
+    CommentsCollection.prototype.paragraphsFor = function (commentId) {
+        var e_10, _a;
+        var entry = this.entryFor(commentId);
+        if (entry === undefined || entry.preservedXml !== undefined) {
+            return [];
+        }
+        var paragraphs = [];
+        try {
+            for (var _b = __values(entry.blocks), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var block = _c.value;
+                if (block.type === 'paragraph') {
+                    paragraphs.push(block.paragraph);
+                }
+            }
+        }
+        catch (e_10_1) { e_10 = { error: e_10_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_10) throw e_10.error; }
+        }
+        return paragraphs;
+    };
+    /** @private */
+    CommentsCollection.prototype.textFor = function (commentId) {
+        var entry = this.entryFor(commentId);
+        if (entry === undefined || entry.preservedXml !== undefined) {
+            return undefined;
+        }
+        return firstParagraphText(entry.blocks);
+    };
+    /** @private */
+    CommentsCollection.prototype.removeEntry = function (commentId) {
+        var part = this.state;
+        if (part === undefined) {
+            throw new DocxError('content/unknown-comment', 'Comments part is not loaded');
+        }
+        var next = part.entries.filter(function (entry) { return entry.commentId !== commentId; });
+        if (next.length === part.entries.length) {
+            throw new DocxError('content/unknown-comment', "Comment id " + String(commentId) + " is not in this WordDocument");
+        }
+        part.entries = next;
+        this.commentViews.delete(commentId);
+        part.dirty = true;
+    };
+    return CommentsCollection;
+}());
+export { CommentsCollection };
+/**
+ * Read `w14:paraId` (Word 2010) from paragraph OpenXml attributes.
+ * Matches DocIO `WParagraph.ParaId` used to join `commentEx`.
+ */
+function paragraphParaIdFromAttributes(attributes) {
+    var found = attributes.find(function (attribute) { return attribute.localName === 'paraId' &&
+        (attribute.namespaceUri === WORDML_2010_NAMESPACE ||
+            attribute.namespaceUri === '' ||
+            attribute.prefix === 'w14'); });
+    var value = found == null ? undefined : found.value;
+    return value !== undefined && value.length > 0 ? value : undefined;
+}
+function lastParagraphParaId(blocks) {
+    for (var index = blocks.length - 1; index >= 0; index -= 1) {
+        var block = blocks[index];
+        // TS 3.3 does not narrow through `(x == null ? undefined : x.type)`.
+        if (block === undefined || block.type !== 'paragraph') {
+            continue;
+        }
+        return paragraphParaIdFromAttributes(block.paragraph.toOpenXml().attributes);
+    }
+    return undefined;
+}
+/**
+ * Join Comments part entries to `commentsExtended` rows by last body paragraph paraId
+ * (DocIO `SetParentParaIdAndIsResolved`).
+ *
+ * Copies `paraIdParent` and `done` onto the same catalog entry used by interned
+ * {@link Comment} views. Read default for absent `@done` after join is `false`
+ * (`[MS-DOCX]` §2.5.3.1 default 0).
+ */
+function applyCommentExRelationships(entries, extendedEntries) {
+    var e_11, _a, e_12, _b;
+    if (extendedEntries.length === 0) {
+        return;
+    }
+    var byParaId = new Map();
+    try {
+        for (var extendedEntries_1 = __values(extendedEntries), extendedEntries_1_1 = extendedEntries_1.next(); !extendedEntries_1_1.done; extendedEntries_1_1 = extendedEntries_1.next()) {
+            var extended = extendedEntries_1_1.value;
+            byParaId.set(extended.paraId, extended);
+        }
+    }
+    catch (e_11_1) { e_11 = { error: e_11_1 }; }
+    finally {
+        try {
+            if (extendedEntries_1_1 && !extendedEntries_1_1.done && (_a = extendedEntries_1.return)) _a.call(extendedEntries_1);
+        }
+        finally { if (e_11) throw e_11.error; }
+    }
+    try {
+        for (var entries_2 = __values(entries), entries_2_1 = entries_2.next(); !entries_2_1.done; entries_2_1 = entries_2.next()) {
+            var entry = entries_2_1.value;
+            if (entry.preservedXml !== undefined || entry.lastParaId === undefined) {
+                continue;
+            }
+            var extended = byParaId.get(entry.lastParaId);
+            if (extended === undefined) {
+                continue;
+            }
+            // Parse keeps raw absent as undefined on CommentExEntry; read API defaults to false.
+            entry.done = extended.done === undefined ? false : extended.done;
+            entry.parentParaId = extended.paraIdParent;
+        }
+    }
+    catch (e_12_1) { e_12 = { error: e_12_1 }; }
+    finally {
+        try {
+            if (entries_2_1 && !entries_2_1.done && (_b = entries_2.return)) _b.call(entries_2);
+        }
+        finally { if (e_12) throw e_12.error; }
+    }
+}
+function loadCatalog(pkg, mainPartName) {
+    var e_13, _a;
+    var extensionParts = new CommentExtensionParts(loadCommentExtensionMetadata(pkg, mainPartName));
+    try {
+        for (var _b = __values(relationshipsForPart(pkg, mainPartName).items), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var rel = _c.value;
+            if (!kindForRelationshipType(rel.type)) {
+                continue;
+            }
+            var target = resolveInternalTarget(rel.target, mainPartName);
+            var part = partByName(pkg, target);
+            if (part === undefined) {
+                continue;
+            }
+            var parsed = parseCommentsPart(part, rel);
+            if (parsed !== undefined) {
+                applyCommentExRelationships(parsed.entries, extensionParts.extendedEntries());
+                return new CommentsCollection(parsed, extensionParts);
+            }
+        }
+    }
+    catch (e_13_1) { e_13 = { error: e_13_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_13) throw e_13.error; }
+    }
+    return new CommentsCollection(undefined, extensionParts);
+}
+function usedRelationshipIds(WordDocument) {
+    var e_14, _a;
+    var main = partName('/word/WordDocument.xml');
+    var used = new Set();
+    try {
+        for (var _b = __values(relationshipsForPart(WordDocument.opcPackage(), main).items), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var rel = _c.value;
+            used.add(rel.id);
+        }
+    }
+    catch (e_14_1) { e_14 = { error: e_14_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_14) throw e_14.error; }
+    }
+    return used;
+}
+function usedPartNameKeys(WordDocument) {
+    var e_15, _a;
+    var used = new Set();
+    try {
+        for (var _b = __values(WordDocument.opcPackage().parts), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var part = _c.value;
+            used.add(partNameKey(part.name));
+        }
+    }
+    catch (e_15_1) { e_15 = { error: e_15_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_15) throw e_15.error; }
+    }
+    return used;
+}
+function anchorRunsForReference(content, referenceIndex, commentId) {
+    var startIndex = -1;
+    for (var index = referenceIndex - 1; index >= 0; index -= 1) {
+        var inline = content[index];
+        // TS 3.3 does not narrow InlineContent through `(x == null ? undefined : x.type)`.
+        if (inline === undefined ||
+            !(inline instanceof FeatureInlineParagraphItem) ||
+            !(inline.value instanceof CommentRangeEnd)) {
+            continue;
+        }
+        if (inline.value.commentId !== commentId) {
+            break;
+        }
+        for (var scan = index - 1; scan >= 0; scan -= 1) {
+            var candidate = content[scan];
+            if (candidate === undefined ||
+                !(candidate instanceof FeatureInlineParagraphItem) ||
+                !(candidate.value instanceof CommentRangeStart) ||
+                candidate.value.commentId !== commentId) {
+                continue;
+            }
+            startIndex = scan;
+            break;
+        }
+        break;
+    }
+    if (startIndex < 0) {
+        return [];
+    }
+    var runs = [];
+    for (var index = startIndex + 1; index < referenceIndex; index += 1) {
+        var inline = content[index];
+        if (inline === undefined || !(inline instanceof TextRange)) {
+            continue;
+        }
+        runs.push(inline);
+    }
+    return runs;
+}
+function findAnchorsInParagraph(paragraph, catalog) {
+    var __ts33_7, __ts33_8;
+    var found = [];
+    var content = paragraph.items.toArray();
+    for (var index = 0; index < content.length; index += 1) {
+        var inline = content[index];
+        // TS 3.3 does not narrow InlineContent through `(x == null ? undefined : x.type)`.
+        if (inline !== undefined &&
+            inline instanceof FeatureInlineParagraphItem &&
+            inline.value instanceof Comment) {
+            var commentId = inline.value.commentId;
+            var entry_1 = catalog.entryFor(commentId);
+            var reference_1 = new CommentReference(commentId);
+            found.push(new CommentAnchor(commentId, ((__ts33_7 = entry_1 == null ? undefined : entry_1.author), __ts33_7 != null ? __ts33_7 : ''), entry_1 == null ? undefined : entry_1.date, anchorRunsForReference(content, index, commentId), reference_1));
+            continue;
+        }
+        if (inline === undefined ||
+            !(inline instanceof FeatureRunParagraphItem) ||
+            !(inline.value instanceof CommentReference)) {
+            continue;
+        }
+        var reference = inline.value;
+        var entry = catalog.entryFor(reference.commentId);
+        found.push(new CommentAnchor(reference.commentId, ((__ts33_8 = entry == null ? undefined : entry.author), __ts33_8 != null ? __ts33_8 : ''), entry == null ? undefined : entry.date, anchorRunsForReference(content, index, reference.commentId), reference));
+    }
+    return found;
+}
+function removeRangeMarkers(paragraph, commentId) {
+    var e_16, _a, e_17, _b;
+    var toRemove = [];
+    try {
+        for (var _c = __values(paragraph.items), _d = _c.next(); !_d.done; _d = _c.next()) {
+            var inline = _d.value;
+            if (!(inline instanceof FeatureInlineParagraphItem)) {
+                continue;
+            }
+            if ((inline.value instanceof CommentRangeStart || inline.value instanceof CommentRangeEnd) &&
+                inline.value.commentId === commentId) {
+                toRemove.push(inline.value);
+            }
+        }
+    }
+    catch (e_16_1) { e_16 = { error: e_16_1 }; }
+    finally {
+        try {
+            if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+        }
+        finally { if (e_16) throw e_16.error; }
+    }
+    try {
+        for (var toRemove_1 = __values(toRemove), toRemove_1_1 = toRemove_1.next(); !toRemove_1_1.done; toRemove_1_1 = toRemove_1.next()) {
+            var marker = toRemove_1_1.value;
+            paragraph.removeFeatureInline(marker);
+        }
+    }
+    catch (e_17_1) { e_17 = { error: e_17_1 }; }
+    finally {
+        try {
+            if (toRemove_1_1 && !toRemove_1_1.done && (_b = toRemove_1.return)) _b.call(toRemove_1);
+        }
+        finally { if (e_17) throw e_17.error; }
+    }
+}
+function removeReferenceRun(paragraph, reference) {
+    var e_18, _a;
+    try {
+        for (var _b = __values(paragraph.items), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var inline = _c.value;
+            if (inline instanceof FeatureInlineParagraphItem && inline.value instanceof Comment) {
+                if (inline.value.commentId === reference.commentId) {
+                    paragraph.removeFeatureInline(inline.value);
+                    return;
+                }
+                continue;
+            }
+            if (inline instanceof FeatureRunParagraphItem &&
+                inline.featureId === COMMENTS &&
+                inline.value instanceof CommentReference &&
+                inline.value.commentId === reference.commentId) {
+                paragraph.removeFeatureRunItem(inline.value);
+                return;
+            }
+        }
+    }
+    catch (e_18_1) { e_18 = { error: e_18_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_18) throw e_18.error; }
+    }
+    throw new DocxError('content/unknown-comment', 'Comment reference is not in this paragraph');
+}
+var registered = false;
+/** @private Test hook */
+export function resetCommentsFeatureForTests() {
+    registered = false;
+}
+/** @private Register comment inline, run-leaf, and comments-part handlers. Idempotent. */
+export function registerCommentsFeature() {
+    if (registered) {
+        return;
+    }
+    registered = true;
+    registerFeature({ id: COMMENTS });
+    registerFeatureMultiPartHandler({
+        featureId: COMMENTS,
+        relationshipTypes: COMMENTS_RELATIONSHIP_TYPES,
+        loadParts: function (pkg, ctx) {
+            return loadCatalog(pkg, ctx.mainPartName);
+        },
+    });
+    registerFeatureInlineHandler({
+        featureId: COMMENTS,
+        wmlLocalName: 'commentRangeStart',
+        tryParse: function (element) {
+            if (!isWml(element, 'commentRangeStart')) {
+                return undefined;
+            }
+            var commentId = parseCommentId(wmlAttribute(element, 'id'));
+            if (commentId === undefined) {
+                return undefined;
+            }
+            return new CommentRangeStart(commentId);
+        },
+    });
+    registerFeatureInlineHandler({
+        featureId: COMMENTS,
+        wmlLocalName: 'commentRangeEnd',
+        tryParse: function (element) {
+            if (!isWml(element, 'commentRangeEnd')) {
+                return undefined;
+            }
+            var commentId = parseCommentId(wmlAttribute(element, 'id'));
+            if (commentId === undefined) {
+                return undefined;
+            }
+            return new CommentRangeEnd(commentId);
+        },
+    });
+    registerFeatureRunLeafHandler({
+        featureId: COMMENTS,
+        wmlLocalName: 'commentReference',
+        tryParse: function (element) {
+            if (!isWml(element, 'commentReference')) {
+                return undefined;
+            }
+            var commentId = parseCommentId(wmlAttribute(element, 'id'));
+            if (commentId === undefined) {
+                return undefined;
+            }
+            return new CommentReference(commentId);
+        },
+    });
+}
+/**
+ * Public comments collection for a {@link WordDocument}.
+ *
+ * Stable per-document identity. Members are the same interned {@link Comment}
+ * instances returned from {@link Paragraph.appendComment} and the internal
+ * comments catalog.
+ *
+ * Supports `count`, numeric index access, and iteration.
+ *
+ * @public
+ */
+var CommentCollection = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function CommentCollection(document) {
+        this.cachedLength = 0;
+        this.document = document;
+    }
+    Object.defineProperty(CommentCollection.prototype, "count", {
+        /**
+         * Number of modeled comment bodies in the Comments part.
+         *
+         * @public
+         */
+        get: function () {
+            this.rebuildIndexProperties();
+            return this.cachedLength;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Comment at zero-based `index`, or `undefined` when out of range.
+     *
+     * @public
+     */
+    CommentCollection.prototype.itemAt = function (index) {
+        var comments = commentsFor(this.document).comments(this.document);
+        return comments[index];
+    };
+    CommentCollection.prototype[Symbol.iterator] = function () {
+        var items = commentsFor(this.document).comments(this.document).slice();
+        var i = 0;
+        return {
+            next: function () {
+                if (i >= items.length) {
+                    return { done: true, value: undefined };
+                }
+                var value = items[i];
+                i += 1;
+                return { done: false, value: value };
+            },
+        };
+    };
+    /**
+     * Refresh numeric index properties from the catalog (part order).
+     *
+     * @private
+     */
+    CommentCollection.prototype.rebuildIndexProperties = function () {
+        var items = commentsFor(this.document).comments(this.document);
+        var nextLen = items.length;
+        var prevLen = this.cachedLength;
+        var limit = prevLen > nextLen ? prevLen : nextLen;
+        for (var i = 0; i < limit; i += 1) {
+            var key = String(i);
+            if (i < nextLen) {
+                Object.defineProperty(this, key, {
+                    value: items[i],
+                    writable: false,
+                    enumerable: true,
+                    configurable: true,
+                });
+            }
+            else {
+                delete this[key];
+            }
+        }
+        this.cachedLength = nextLen;
+    };
+    return CommentCollection;
+}());
+export { CommentCollection };
+var commentCollections = new WeakMap();
+/**
+ * Stable public {@link CommentCollection} for `document`.
+ *
+ * @private
+ */
+export function commentCollectionFor(document) {
+    registerCommentsFeature();
+    var cached = commentCollections.get(document);
+    if (cached !== undefined) {
+        cached.rebuildIndexProperties();
+        return cached;
+    }
+    var created = new CommentCollection(document);
+    created.rebuildIndexProperties();
+    commentCollections.set(document, created);
+    return created;
+}
+Object.defineProperty(WordDocument.prototype, 'comments', {
+    configurable: true,
+    enumerable: false,
+    get: function () {
+        return commentCollectionFor(this);
+    },
+});
+/**
+ * Comments collection for a WordDocument.
+ *
+ * On a loaded package this is the collection built from the Main WordDocument comments
+ * relationship when the feature was registered before load. On
+ * {@link WordDocument.create} (or a package with no comments part) attaches an empty
+ * collection on first use when the feature is registered.
+ *
+ * The returned {@link CommentsCollection} surface is internal; public callers use
+ * {@link commentsInDocument}, {@link commentFor}, and related helpers.
+ *
+ * @throws DocxError `feature/not-registered` when the module was not registered
+ *   or feature state was replaced with an unexpected part type.
+ *
+ * @private
+ */
+export function commentsFor(WordDocument) {
+    var part = WordDocument.featurePart(COMMENTS);
+    if (part instanceof CommentsCollection) {
+        return part;
+    }
+    if (part !== undefined) {
+        throw new DocxError('feature/not-registered', 'Comments feature state was replaced with an unexpected part type');
+    }
+    if (!isFeatureRegistered(COMMENTS)) {
+        throw new DocxError('feature/not-registered', 'Comments feature is not registered; call registerCommentsFeature() before use');
+    }
+    var created = new CommentsCollection(undefined, new CommentExtensionParts({
+        extended: undefined,
+        people: undefined,
+        ids: undefined,
+        extensible: undefined,
+    }));
+    WordDocument.setFeaturePart(COMMENTS, created);
+    return created;
+}
+/**
+ * MS-DOCX comment extension metadata for a loaded WordDocument.
+ *
+ * @private
+ */
+export function commentExtensionsFor(WordDocument) {
+    return commentsFor(WordDocument).extensions();
+}
+/**
+ * Live {@link Comment} body for a Comments part id.
+ *
+ * Returns the catalog-interned instance for `(WordDocument, commentId)` so repeated
+ * lookups share object identity (`===`).
+ *
+ * @private
+ */
+export function commentFor(WordDocument, commentId) {
+    return commentsFor(WordDocument).commentInstanceFor(WordDocument, commentId);
+}
+/**
+ * Live {@link Comment} body linked from a paragraph anchor.
+ *
+ * Same interned instance as {@link commentFor} for `anchor.commentId`.
+ *
+ * @private
+ */
+export function commentForAnchor(WordDocument, anchor) {
+    return commentsFor(WordDocument).commentInstanceFor(WordDocument, anchor.commentId);
+}
+/**
+ * Modeled comment bodies in the Comments part, in part order.
+ *
+ * Opaque preserved entries are omitted. Prefer this for a full catalog list;
+ * {@link commentsInParagraph} lists anchors in the main story.
+ *
+ * @private
+ */
+export function commentsInDocument(WordDocument) {
+    return commentsFor(WordDocument).comments(WordDocument);
+}
+/**
+ * Comment anchors in a paragraph, in WordDocument order.
+ *
+ * @private
+ */
+export function commentsInParagraph(WordDocument, paragraph) {
+    return findAnchorsInParagraph(paragraph, commentsFor(WordDocument));
+}
+/**
+ * Visible text of a comment body, when loaded (first non-empty run of the first paragraph).
+ *
+ * @private
+ */
+export function commentBody(WordDocument, anchor) {
+    return commentsFor(WordDocument).textFor(anchor.commentId);
+}
+/**
+ * Modeled body paragraphs of a comment linked from an anchor.
+ *
+ * @private
+ */
+export function commentParagraphs(WordDocument, anchor) {
+    return commentsFor(WordDocument).paragraphsFor(anchor.commentId);
+}
+function normalizeCommentDateAttribute(date, defaultNow) {
+    if (date === undefined) {
+        return defaultNow ? new Date().toISOString() : undefined;
+    }
+    if (typeof date === 'string') {
+        return optionalNonEmptyAttribute(date);
+    }
+    return date.toISOString();
+}
+function assertCommentRangeIndices(paragraph, rangeStart, rangeEnd) {
+    var length = paragraph.items.length;
+    if (!Number.isInteger(rangeStart) ||
+        !Number.isInteger(rangeEnd) ||
+        rangeStart < 0 ||
+        rangeEnd < rangeStart ||
+        rangeEnd > length) {
+        throw new RangeError("Comment range indices out of range: start=" + String(rangeStart) + " end=" + String(rangeEnd) + " length=" + String(length));
+    }
+}
+/**
+ * Resolve optional range indices for append authoring (D15).
+ *
+ * Both omitted → collapsed at current content end. One omitted → collapsed at
+ * the provided index. Validated before any mutation.
+ */
+function resolveAppendCommentRange(paragraph, rangeStart, rangeEnd) {
+    var length = paragraph.items.length;
+    var start;
+    var end;
+    if (rangeStart === undefined && rangeEnd === undefined) {
+        start = length;
+        end = length;
+    }
+    else if (rangeStart === undefined) {
+        // One-sided: collapse at the provided end index.
+        start = rangeEnd != null ? rangeEnd : length;
+        end = start;
+    }
+    else if (rangeEnd === undefined) {
+        start = rangeStart;
+        end = rangeStart;
+    }
+    else {
+        start = rangeStart;
+        end = rangeEnd;
+    }
+    assertCommentRangeIndices(paragraph, start, end);
+    return { start: start, end: end };
+}
+/**
+ * Insert range markers and one elevated {@link Comment} after the end marker.
+ *
+ * Indices are pre-insert content positions (editable-range style): start at
+ * `rangeStart`, end at `rangeEnd + 1` after the start push, Comment at
+ * `rangeEnd + 2`.
+ */
+function insertCommentMarkersAndReference(paragraph, commentId, comment, rangeStart, rangeEnd) {
+    paragraph.insertFeatureInlineAt(rangeStart, COMMENTS, new CommentRangeStart(commentId));
+    paragraph.insertFeatureInlineAt(rangeEnd + 1, COMMENTS, new CommentRangeEnd(commentId));
+    paragraph.insertFeatureInlineAt(rangeEnd + 2, COMMENTS, comment);
+}
+/**
+ * Create a new comments-part entry, intern {@link Comment}, ensure part/rel.
+ *
+ * Always allocates a **new** unique id (never a second reference for an existing id).
+ */
+function createNewCommentEntry(WordDocument, author, commentText, options) {
+    var catalog = commentsFor(WordDocument);
+    catalog.ensurePart(usedRelationshipIds(WordDocument), usedPartNameKeys(WordDocument));
+    var date = normalizeCommentDateAttribute(options.date, options.defaultDateNow);
+    var commentId = catalog.addEntry(WordDocument, author, commentText, date, options.initials);
+    var comment = catalog.commentInstanceFor(WordDocument, commentId);
+    comment.applyDefaultReferenceRunStyle();
+    return comment;
+}
+/**
+ * Append a new comment to a paragraph (range markers + elevated {@link Comment}).
+ *
+ * Primary shape: `appendComment(paragraph, text, options?)`. Options-only overload
+ * accepts {@link AppendCommentOptions} with required `text`.
+ *
+ * Behavior (locked D7/D8/D15/D16):
+ * - Comments feature must be registered (`feature/not-registered` otherwise).
+ * - Paragraph must be attached (`DetachedObjectError` via {@link Paragraph.owningDocument}).
+ * - Range indices validated **before** mutation (`RangeError` when invalid/reversed).
+ * - New unique comment id; one catalog entry; one elevated `Comment` after end marker.
+ * - When both range indices omitted: collapsed markers at append point (still emitted).
+ * - Public DOM has no empty sole-purpose `CommentReference` Run.
+ *
+ * @param paragraph - Host paragraph in the main story.
+ * @param textOrOptions - Body text, or full options object.
+ * @param options - Optional metadata / range when the first argument is text.
+ * @returns Interned {@link Comment} (`===` content slot and {@link commentFor}).
+ * @public
+ */
+export function appendComment(paragraph, textOrOptions, options) {
+    var resolved = typeof textOrOptions === 'string'
+        ? __assign({ text: textOrOptions }, options) : textOrOptions;
+    // Ownership check before any catalog mutation.
+    var WordDocument = paragraph.owningDocument();
+    var range = resolveAppendCommentRange(paragraph, resolved.rangeStart, resolved.rangeEnd);
+    var author = resolved.author != null ? resolved.author : '';
+    var comment = createNewCommentEntry(WordDocument, author, resolved.text, __assign({}, (resolved.date !== undefined ? { date: resolved.date } : {}), (resolved.initials !== undefined ? { initials: resolved.initials } : {}), { defaultDateNow: true }));
+    insertCommentMarkersAndReference(paragraph, comment.commentId, comment, range.start, range.end);
+    return comment;
+}
+/**
+ * Insert a comment with optional anchor text at the end of a paragraph.
+ *
+ * Places an elevated {@link Comment} feature-inline (not a public empty
+ * CommentReference Run). When `anchorText` is non-empty, range markers wrap the
+ * new anchor run before the Comment. When empty, only the elevated Comment is
+ * appended (legacy insert path; prefer {@link appendComment} for D15 markers).
+ *
+ * @private
+ */
+export function insertComment(WordDocument, paragraph, author, commentText, anchorText) {
+    if (anchorText === void 0) { anchorText = ''; }
+    var __ts33_9;
+    var comment = createNewCommentEntry(WordDocument, author, commentText, {
+        defaultDateNow: false,
+    });
+    var commentId = comment.commentId;
+    var reference = new CommentReference(commentId);
+    var anchorRuns = [];
+    if (anchorText.length > 0) {
+        paragraph.appendFeatureInline(COMMENTS, new CommentRangeStart(commentId));
+        var anchorRun = paragraph.appendText(anchorText);
+        anchorRuns.push(anchorRun);
+        paragraph.appendFeatureInline(COMMENTS, new CommentRangeEnd(commentId));
+    }
+    // Elevated Comment feature-inline at the former sole-purpose reference run (D1/D5).
+    paragraph.appendFeatureInline(COMMENTS, comment);
+    var entry = commentsFor(WordDocument).entryFor(commentId);
+    return new CommentAnchor(commentId, ((__ts33_9 = entry == null ? undefined : entry.author), __ts33_9 != null ? __ts33_9 : author), entry == null ? undefined : entry.date, anchorRuns, reference);
+}
+// Safe once WordDocument.ts no longer value-imports this module (TASK-8056 cycle fix).
+Paragraph.prototype.appendComment = function (textOrOptions, options) {
+    return appendComment(this, textOrOptions, options);
+};
+/**
+ * Remove a comment anchor, range markers, and comments part entry.
+ *
+ * @private
+ */
+export function removeComment(WordDocument, paragraph, anchor) {
+    removeRangeMarkers(paragraph, anchor.commentId);
+    removeReferenceRun(paragraph, anchor.reference);
+    commentsFor(WordDocument).removeEntry(anchor.commentId);
+}
+/**
+ * Whether paragraph inline content is a modeled comment range start from this module.
+ *
+ * @private
+ */
+export function isCommentRangeStartInline(inline) {
+    return (inline instanceof FeatureInlineParagraphItem &&
+        inline.featureId === COMMENTS &&
+        inline.value instanceof CommentRangeStart);
+}
+/**
+ * Whether paragraph inline content is a modeled comment range end from this module.
+ *
+ * @private
+ */
+export function isCommentRangeEndInline(inline) {
+    return (inline instanceof FeatureInlineParagraphItem &&
+        inline.featureId === COMMENTS &&
+        inline.value instanceof CommentRangeEnd);
+}
+/**
+ * Whether a paragraph item is a residual modeled comment reference featureRun.
+ *
+ * @private
+ */
+export function isCommentReferenceLeaf(leaf) {
+    return (leaf instanceof FeatureRunParagraphItem &&
+        leaf.featureId === COMMENTS &&
+        leaf.value instanceof CommentReference);
+}
+// Always-on on the main `@syncfusion/ej2-docx` entry: comment range/reference handlers +
+// comments multi-part catalog re-arm after test handler resets via
+// WordDocument.create / fromPackage.
+registerAlwaysOnBodyFeatureBootstrap(function () {
+    registerCommentsFeature();
+});
+registerCommentsFeature();