@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

package/src/features/document/paragraph.js

@@ -0,0 +1,888 @@
+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 };
+        }
+    };
+};
+import { DetachedObjectError, DocxError } from '../../core/errors/docx-error';
+import { tryParseFeatureInline, } from '../../core/registry/inline-handlers';
+import { CharacterFormat, parseCharacterFormat, } from './character-format';
+import { emptyParagraphFormatSnapshot, ParagraphFormat, parseParagraphFormat, } from './paragraph-format';
+import { ParagraphItemCollection, } from './paragraph-item-collection';
+import { Break, BreakClearType, BreakType, createStandaloneBreakItem, createStandaloneSymbolItem, createTextAndTabItems, FeatureInlineParagraphItem, FeatureRunParagraphItem, OpaqueParagraphItem, parseTextRangeGroup, serializeParagraphItems, Tab, TextRange, WireRunGroup, } from './text-range';
+import { elementChildren, isWml, wValAttribute, wmlAttr, wmlElement } from './wml';
+/**
+ * Factory for {@link Paragraph.listFormat} — registered by the numbering feature
+ * to avoid Vitest ESM-breaking extensionless CJS require of list-format.
+ * @private
+ */
+var listFormatFactory;
+/**
+ * @private Registers the ListFormat constructor bridge (called from numbering feature load).
+ */
+export function setListFormatFactory(factory) {
+    listFormatFactory = factory;
+}
+/**
+ * @private Test-only reset.
+ */
+export function resetListFormatFactoryForTests() {
+    listFormatFactory = undefined;
+}
+/**
+ * WordprocessingML paragraph (`w:p`).
+ *
+ * Paragraph properties live on {@link Paragraph.paragraphFormat} (`w:pPr`).
+ * Paragraph-mark character formatting lives on
+ * {@link Paragraph.breakCharacterFormat} (`w:pPr/w:rPr`). Text-range character
+ * formatting remains on {@link TextRange.characterFormat} (`w:r/w:rPr`).
+ *
+ * Items appear directly on {@link Paragraph.items} — there is no nested run
+ * collection. Physical `w:r` grouping is reconstructed on serialize.
+ *
+ * @public
+ */
+var Paragraph = /** @class */ (function () {
+    /** @private */
+    function Paragraph(owner) {
+        this.owner = owner;
+        this.extraAttributes = [];
+        this.numPrExtra = [];
+        this.sectionBreakSectPrElement = undefined;
+        this.paragraphItems = new ParagraphItemCollection(this);
+        this.paragraphFormatField = undefined;
+        this.breakCharacterFormatField = undefined;
+        this.listFormatField = undefined;
+    }
+    Object.defineProperty(Paragraph.prototype, "paragraphFormat", {
+        /**
+         * The direct paragraph formatting (`w:pPr`) of this paragraph — the only
+         * public paragraph-formatting surface.
+         *
+         * A live view over the typed `w:pPr` state: every read/write goes to the
+         * same storage the parser fills and the serializer reads. Lazily created
+         * on first access and cached; never null.
+         *
+         * Mutating it validates attachment — writes on a detached paragraph throw
+         * {@link DetachedObjectError}.
+         *
+         * @example
+         * ```ts
+         * paragraph.paragraphFormat.beforeSpacing = 18;
+         * paragraph.paragraphFormat.lineSpacing = 10;
+         * paragraph.paragraphFormat.firstLineIndent = 10; // negative = hanging
+         * paragraph.paragraphFormat.backColor = 'D3D3D3';
+         * ```
+         *
+         * @public
+         */
+        get: function () {
+            if (this.paragraphFormatField === undefined) {
+                this.paragraphFormatField = new ParagraphFormat(this);
+            }
+            return this.paragraphFormatField;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Paragraph.prototype, "breakCharacterFormat", {
+        /**
+         * Character formatting of the paragraph mark (`w:pPr/w:rPr`).
+         *
+         * Reuses the same {@link CharacterFormat} type as {@link TextRange.characterFormat}.
+         * Lazily constructed; never null. Empty format does not emit an empty `w:rPr`.
+         *
+         * @example
+         * ```ts
+         * paragraph.breakCharacterFormat.bold = true;
+         * paragraph.breakCharacterFormat.italic = true;
+         * paragraph.breakCharacterFormat.fontSize = 14;
+         * ```
+         *
+         * @public
+         */
+        get: function () {
+            if (this.breakCharacterFormatField === undefined) {
+                this.breakCharacterFormatField = new CharacterFormat(this);
+            }
+            return this.breakCharacterFormatField;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Paragraph.prototype, "listFormat", {
+        /**
+         * Paragraph list formatting (`w:numPr`).
+         *
+         * A live list-format interface for applying and modifying numbering and
+         * bullet formatting on this paragraph. Lazily created on first access
+         * and cached; never null.
+         *
+         * @example
+         * ```ts
+         * paragraph.listFormat.applyDefBulletStyle();
+         * paragraph.listFormat.increaseIndentLevel();
+         * paragraph.listFormat.listId = 5;
+         * ```
+         *
+         * @public
+         */
+        get: function () {
+            if (this.listFormatField === undefined) {
+                // Factory is registered by the numbering feature (avoids circular
+                // import and extensionless CJS require under Vitest).
+                if (listFormatFactory === undefined) {
+                    throw new DocxError('feature/not-registered', 'ListFormat is unavailable; register the numbering feature before accessing paragraph.listFormat');
+                }
+                this.listFormatField = listFormatFactory(this);
+            }
+            return this.listFormatField;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /** @private ParagraphFormatHost — mutation notification + detachment guard. */
+    Paragraph.prototype.notifyParagraphFormatMutation = function () {
+        this.mutate();
+    };
+    /** @private CharacterFormatHost — mark rPr mutation notification. */
+    Paragraph.prototype.notifyCharacterFormatMutation = function () {
+        this.mutate();
+    };
+    /** @private */
+    Paragraph.prototype.detach = function () {
+        this.owner = undefined;
+        this.paragraphItems.detachAll();
+    };
+    /** @private */
+    Paragraph.prototype.attach = function (owner) {
+        this.owner = owner;
+        this.paragraphItems.reattachAll();
+    };
+    /**
+     * @private ParagraphItemOwner — gate item property mutation.
+     */
+    Paragraph.prototype.assertAttachedItem = function (target) {
+        this.mutate();
+        if (!this.paragraphItems.containsIdentity(target)) {
+            throw new DetachedObjectError('This paragraph item is no longer in its paragraph');
+        }
+    };
+    /**
+     * @private Gate paragraph-level authoring.
+     */
+    Paragraph.prototype.assertMutable = function () {
+        this.mutate();
+    };
+    Paragraph.prototype.mutate = function () {
+        if (this.owner === undefined) {
+            throw new DetachedObjectError('This paragraph is no longer in a document');
+        }
+        this.owner.assertAttachedParagraph(this);
+    };
+    /** @private */
+    Paragraph.prototype.owningDocument = function () {
+        if (this.owner === undefined) {
+            throw new DetachedObjectError('This paragraph is no longer in a document');
+        }
+        return this.owner.owningDocument();
+    };
+    Object.defineProperty(Paragraph.prototype, "styleId", {
+        /**
+         * Gets or sets the identifier of the paragraph style applied to this paragraph.
+         *
+         * If undefined, no paragraph style is applied and formatting comes from the
+         * document defaults. The identifier must name a style that exists in the
+         * document when the file is saved.
+         *
+         * @defaultValue No paragraph style when omitted (body text formatting).
+         *
+         * @public
+         */
+        get: function () {
+            return this.styleIdValue;
+        },
+        set: function (value) {
+            this.mutate();
+            this.styleIdValue = value;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Applies a paragraph style by id or BuiltInStyle.
+     * Implementation is registered by the styles feature (writes resolved styleId only).
+     * @public
+     */
+    Paragraph.prototype.applyStyle = function (_style) {
+        throw new Error('Styles feature is not loaded');
+    };
+    /**
+     * @private Optional CharacterFormatHost effective resolver (overwritten by styles feature).
+     */
+    Paragraph.prototype.resolveEffectiveCharacterValue = function (_key) {
+        return undefined;
+    };
+    /**
+     * @private Optional ParagraphFormatHost effective resolver (overwritten by styles feature).
+     */
+    Paragraph.prototype.resolveEffectiveParagraphValue = function (_key) {
+        return undefined;
+    };
+    Object.defineProperty(Paragraph.prototype, "numId", {
+        /**
+         * @private
+         * Direct `w:numPr/w:numId/@w:val`. `undefined` means absent (not in a list). */
+        get: function () {
+            return this.numIdValue;
+        },
+        /**
+         * @private
+         * Direct `w:numPr/w:numId/@w:val`. `undefined` means absent (not in a list). */
+        set: function (value) {
+            this.mutate();
+            this.numIdValue = value;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Paragraph.prototype, "listLevel", {
+        /**
+         * Zero-based list level (`w:ilvl`). Prefer {@link listFormat.listLevelNumber}.
+         *
+         * @private
+         */
+        get: function () {
+            return this.listLevelValue;
+        },
+        /**
+         * @private
+         */
+        set: function (value) {
+            this.mutate();
+            this.listLevelValue = value;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private
+     * Conditional table-style membership on `w:pPr/w:cnfStyle`.
+     */
+    Paragraph.prototype.getConditionalFormatting = function () {
+        return this.paragraphFormat.readCnfStyle();
+    };
+    /**
+     * @private
+     * Set or clear conditional table-style membership on this paragraph.
+     * Does not call {@link mutate} beyond ParagraphFormat's write path so
+     * detached table rebuilds during calculation can still write masks.
+     */
+    Paragraph.prototype.setConditionalFormatting = function (state) {
+        this.paragraphFormat.writeCnfStyle(state);
+    };
+    Object.defineProperty(Paragraph.prototype, "isInCell", {
+        /**
+         * True when this paragraph’s nearest body owner is a table cell
+         * (including nested table cells). False for body, header/footer, text box,
+         * footnote, endnote, or detached paragraphs.
+         *
+         * @public
+         */
+        get: function () {
+            var owner = this.owner;
+            return owner !== undefined && owner.bodyOwnerKind === 'tableCell';
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /** @private Paragraph section-break `w:pPr/w:sectPr`, when present. */
+    Paragraph.prototype.sectionBreakSectPr = function () {
+        return this.sectionBreakSectPrElement;
+    };
+    /**
+     * @private
+     * Replace paragraph section-break `w:sectPr`.
+     *
+     * Load/partition/flatten may dual-hold before the paragraph is attached to a
+     * body (parse uses a detached context; save may append an empty terminator).
+     * When already attached, still assert ownership via {@link mutate}.
+     */
+    Paragraph.prototype.replaceSectionBreakSectPr = function (value) {
+        if (this.owner !== undefined) {
+            this.mutate();
+        }
+        this.sectionBreakSectPrElement = value;
+        if (value !== undefined) {
+            this.sectionBreakPropertiesModelValue = undefined;
+        }
+    };
+    /**
+     * @private
+     * Live paragraph section-break properties model (sections feature), if any.
+     */
+    Paragraph.prototype.sectionBreakPropertiesModel = function () {
+        return this.sectionBreakPropertiesModelValue;
+    };
+    /**
+     * @private
+     * Attach or clear the live paragraph section-break properties model.
+     * When set, clears preserved `w:sectPr` XML so the model is the sole source of truth.
+     *
+     * Same attach rules as {@link replaceSectionBreakSectPr}: dual-hold is allowed
+     * before body ownership is established (TASK-8075 partition/flatten).
+     */
+    Paragraph.prototype.replaceSectionBreakPropertiesModel = function (value) {
+        if (this.owner !== undefined) {
+            this.mutate();
+        }
+        this.sectionBreakPropertiesModelValue = value;
+        if (value !== undefined) {
+            this.sectionBreakSectPrElement = undefined;
+        }
+    };
+    Object.defineProperty(Paragraph.prototype, "items", {
+        /**
+         * Ordered paragraph items (text ranges, breaks, tabs, symbols, feature
+         * content, opaque markup) in document order.
+         *
+         * Stable collection identity for the life of the paragraph. Physical `w:r`
+         * grouping is reconstructed on serialize via shared wire groups.
+         *
+         * @public
+         */
+        get: function () {
+            return this.paragraphItems;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Paragraph.prototype, "text", {
+        /**
+         * Gets the concatenated plain text of modeled text ranges and tab characters
+         * in document order.
+         *
+         * Opaque and feature inlines (for example hyperlinks owned by feature modules)
+         * are skipped. Field instruction text is also skipped; only field result text
+         * is included. {@link Tab} items contribute U+0009 so plain-text views match
+         * run-level tab characters authored via {@link appendText} or loaded from
+         * `w:tab`.
+         *
+         * @public
+         */
+        get: function () {
+            var parts = [];
+            var items = this.paragraphItems.snapshot();
+            var fieldStack = [];
+            for (var i = 0; i < items.length; i += 1) {
+                var item = items[i];
+                // Check if this is a Field (begin marker)
+                if (item !== undefined && typeof item === 'object' && 'fieldType' in item && !('fieldMarkType' in item)) {
+                    fieldStack.push({ phase: 'instruction' });
+                    continue;
+                }
+                // Check if this is a FieldMark (separator or end)
+                if (item !== undefined && typeof item === 'object' && 'fieldMarkType' in item) {
+                    var mark = item;
+                    if (mark.fieldMarkType === 'separate') {
+                        if (fieldStack.length > 0) {
+                            var top_1 = fieldStack[fieldStack.length - 1];
+                            if (top_1 !== undefined) {
+                                top_1.phase = 'result';
+                            }
+                        }
+                        continue;
+                    }
+                    else if (mark.fieldMarkType === 'end') {
+                        if (fieldStack.length > 0) {
+                            fieldStack.pop();
+                        }
+                        continue;
+                    }
+                }
+                // Include text / tabs only if not in field instruction phase
+                var inResult = fieldStack.length === 0 || fieldStack[fieldStack.length - 1].phase === 'result';
+                if (!inResult) {
+                    continue;
+                }
+                if (item instanceof TextRange) {
+                    parts.push(item.text);
+                }
+                else if (item instanceof Tab) {
+                    parts.push('\t');
+                }
+            }
+            return parts.join('');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Appends an empty text range to the end of this paragraph and returns it.
+     *
+     * @returns The newly created empty text range.
+     * @throws DetachedObjectError if this paragraph is no longer attached to a document.
+     *
+     * @public
+     */
+    Paragraph.prototype.appendTextRange = function () {
+        this.mutate();
+        var textRange = new TextRange();
+        this.paragraphItems.add(textRange);
+        return textRange;
+    };
+    /**
+     * Append text as one or more paragraph items, optionally with common character
+     * formatting. U+0009 (tab) characters become dedicated {@link Tab} items
+     * (`w:r/w:tab`) interleaved with {@link TextRange} segments that share one
+     * wire run group, matching Word / OOXML run-inner content.
+     *
+     * @returns The first {@link TextRange} created for non-empty text segments, or
+     * an empty trailing {@link TextRange} when `text` is empty or tab-only (so the
+     * return type stays {@link TextRange}).
+     *
+     * @public
+     */
+    Paragraph.prototype.appendText = function (text, options) {
+        this.mutate();
+        var group = new WireRunGroup();
+        var items = createTextAndTabItems(text, group);
+        var firstTextRange;
+        for (var i = 0; i < items.length; i += 1) {
+            var item = items[i];
+            if (item === undefined) {
+                continue;
+            }
+            this.paragraphItems.add(item);
+            if (firstTextRange === undefined && item instanceof TextRange) {
+                firstTextRange = item;
+            }
+        }
+        if (firstTextRange === undefined) {
+            // Tab-only input: keep API contract with an empty range on the same wire group.
+            firstTextRange = new TextRange(undefined, group);
+            this.paragraphItems.add(firstTextRange);
+        }
+        // Shared WireRunGroup CF — any member's characterFormat is the run's rPr.
+        if (options != null && options.bold !== undefined) {
+            firstTextRange.characterFormat.bold = options.bold;
+        }
+        if (options != null && options.italic !== undefined) {
+            firstTextRange.characterFormat.italic = options.italic;
+        }
+        if (options != null && options.fontSize !== undefined) {
+            firstTextRange.characterFormat.fontSize = options.fontSize;
+        }
+        return firstTextRange;
+    };
+    /**
+     * Append a break (`w:br`) as a direct paragraph item.
+     *
+     * Always run content on the wire (`w:r/w:br`), never a paragraph-level
+     * sibling of `w:r`. Serialization rebuilds the physical run.
+     *
+     * @param type - Break kind ({@link BreakType}).
+     * @param options - Optional text-wrapping clear (Line / TextWrappingBreak only).
+     * @returns The break item.
+     * @throws DocxError `content/invalid-break` if `clear` is set on Page or Column.
+     *
+     * @example
+     * ```ts
+     * paragraph.appendBreak(BreakType.PageBreak);
+     * paragraph.appendBreak(BreakType.LineBreak, { clear: BreakClearType.All });
+     * ```
+     *
+     * @public
+     */
+    Paragraph.prototype.appendBreak = function (type, options) {
+        this.mutate();
+        var clear = options == null ? undefined : options.clear;
+        var item = createStandaloneBreakItem(type, clear != null ? clear : BreakClearType.None);
+        this.paragraphItems.add(item);
+        return item;
+    };
+    /**
+     * Append a symbol character (`w:sym`) as a direct paragraph item.
+     *
+     * Always run content on the wire (`w:r/w:sym`, ECMA-376-1 §17.3.3.30).
+     *
+     * @param font - Symbol font name (`w:font`), for example `"Wingdings"`.
+     * @param char - `ST_ShortHexNumber` hex digits for `w:char` (four hex digits, e.g. `"F0FC"`).
+     * @returns The symbol paragraph item that was created.
+     *
+     * @example
+     * ```ts
+     * paragraph.appendText('checkmark: ');
+     * paragraph.appendSymbol('Wingdings', 'F0FC');
+     * ```
+     *
+     * @public
+     */
+    Paragraph.prototype.appendSymbol = function (font, char) {
+        this.mutate();
+        var item = createStandaloneSymbolItem(font, char);
+        this.paragraphItems.add(item);
+        return item;
+    };
+    /**
+     * Appends a feature-owned run-level item (for example an image) as a direct
+     * paragraph child. Serializes inside a physical `w:r` via its wire group.
+     *
+     * @private
+     */
+    Paragraph.prototype.appendFeatureRunItem = function (featureId, value) {
+        this.mutate();
+        var item = new FeatureRunParagraphItem(featureId, value, new WireRunGroup());
+        this.paragraphItems.add(item);
+        return item;
+    };
+    /**
+     * Appends a feature-owned inline sibling (for example `w:hyperlink`).
+     *
+     * @private
+     */
+    Paragraph.prototype.appendFeatureInline = function (featureId, value) {
+        this.mutate();
+        var item = new FeatureInlineParagraphItem(featureId, value);
+        this.paragraphItems.add(item);
+        return item;
+    };
+    /**
+     * Inserts a feature-owned inline at a raw content index (`0…items.count` inclusive).
+     *
+     * @private
+     */
+    Paragraph.prototype.insertFeatureInlineAt = function (index, featureId, value) {
+        this.mutate();
+        var item = new FeatureInlineParagraphItem(featureId, value);
+        this.paragraphItems.insert(index, item);
+        return item;
+    };
+    /** @private Remove a feature inline from this paragraph. */
+    Paragraph.prototype.removeFeatureInline = function (value) {
+        this.mutate();
+        var items = this.paragraphItems.snapshot();
+        for (var i = 0; i < items.length; i += 1) {
+            var item = items[i];
+            if (item instanceof FeatureInlineParagraphItem && item.value === value) {
+                this.paragraphItems.removeAt(i);
+                return;
+            }
+        }
+        throw new DetachedObjectError('This inline is no longer in its paragraph');
+    };
+    /**
+     * @private Remove a feature run-level item (image, drawing residual, …).
+     */
+    Paragraph.prototype.removeFeatureRunItem = function (value) {
+        this.mutate();
+        var items = this.paragraphItems.snapshot();
+        for (var i = 0; i < items.length; i += 1) {
+            var item = items[i];
+            if (item instanceof FeatureRunParagraphItem && item.value === value) {
+                this.paragraphItems.removeAt(i);
+                return;
+            }
+        }
+        throw new DetachedObjectError('This item is no longer in its paragraph');
+    };
+    /**
+     * @private Append a pre-built paragraph item (feature modules).
+     */
+    Paragraph.prototype.appendParagraphItem = function (item) {
+        this.mutate();
+        this.paragraphItems.add(item);
+    };
+    /**
+     * @private Remove a text range by identity.
+     */
+    Paragraph.prototype.removeTextRange = function (run) {
+        this.mutate();
+        var at = this.paragraphItems.indexOfIdentity(run);
+        if (at === -1) {
+            throw new DetachedObjectError('This text range is no longer in its paragraph');
+        }
+        this.paragraphItems.removeAt(at);
+    };
+    /**
+     * Advanced hatch: `w:p` tree. Unstable; prefer semantic properties.
+     */
+    Paragraph.prototype.toOpenXml = function () {
+        return serializeParagraph(this);
+    };
+    /** @private */
+    Paragraph.fromXml = function (el, owner) {
+        return parseParagraph(el, owner);
+    };
+    /** @private */
+    Paragraph.prototype.hydrate = function (data) {
+        this.extraAttributes = data.extraAttributes;
+        this.styleIdValue = data.styleIdValue;
+        this.numIdValue = data.numIdValue;
+        this.listLevelValue = data.listLevelValue;
+        this.numPrExtra = data.numPrExtra;
+        this.sectionBreakSectPrElement = data.sectionBreakSectPr;
+        // Detach any prior owner on incoming items so collection hydrate can attach.
+        for (var i = 0; i < data.items.length; i += 1) {
+            var incoming = data.items[i];
+            if (incoming.owner !== undefined) {
+                incoming.detach();
+            }
+        }
+        this.paragraphItems.hydrate(data.items);
+        // TASK-9020-C: formatting state hydrates from parseParagraphFormat snapshot.
+        this.paragraphFormat.hydrate(data.paragraphFormat);
+        if (data.breakCharacterFormat !== undefined) {
+            this.breakCharacterFormat.hydrate(data.breakCharacterFormat);
+        }
+    };
+    /** @private */
+    Paragraph.prototype.snapshot = function () {
+        return {
+            extraAttributes: this.extraAttributes,
+            styleIdValue: this.styleIdValue,
+            numIdValue: this.numIdValue,
+            listLevelValue: this.listLevelValue,
+            numPrExtra: this.numPrExtra,
+            // Prefer the live sections-feature model when present (clears preserved XML).
+            sectionBreakSectPr: this.sectionBreakPropertiesModelValue !== undefined
+                ? this.sectionBreakPropertiesModelValue.toOpenXml()
+                : this.sectionBreakSectPrElement,
+            items: this.paragraphItems.snapshot(),
+            paragraphFormat: this.paragraphFormat.snapshot(),
+            breakCharacterFormat: this.breakCharacterFormat.snapshot(),
+        };
+    };
+    return Paragraph;
+}());
+export { Paragraph };
+function parseDecimalVal(raw) {
+    if (raw === undefined || !/^-?\d+$/.test(raw)) {
+        return undefined;
+    }
+    return Number.parseInt(raw, 10);
+}
+/**
+ * Parse `w:p`. Paragraph-owned: `pStyle` / `numPr` / `rPr` / `sectPr` / content.
+ * Format-owned `w:pPr` children go through {@link parseParagraphFormat}.
+ */
+function parseParagraph(el, owner) {
+    var e_1, _a, e_2, _b, e_3, _c;
+    var paragraph = new Paragraph(owner);
+    var styleIdValue;
+    var numIdValue;
+    var listLevelValue;
+    var sectionBreakSectPr;
+    var numPrExtra = [];
+    var items = [];
+    var formatSnap;
+    var breakCfSnap;
+    try {
+        for (var _d = __values(elementChildren(el)), _e = _d.next(); !_e.done; _e = _d.next()) {
+            var child = _e.value;
+            if (isWml(child, 'pPr')) {
+                try {
+                    // Paragraph-owned children first, then format codec for the rest.
+                    for (var _f = __values(elementChildren(child)), _g = _f.next(); !_g.done; _g = _f.next()) {
+                        var prop = _g.value;
+                        if (isWml(prop, 'pStyle')) {
+                            styleIdValue = wValAttribute(prop);
+                            continue;
+                        }
+                        if (isWml(prop, 'numPr')) {
+                            try {
+                                for (var _h = __values(elementChildren(prop)), _j = _h.next(); !_j.done; _j = _h.next()) {
+                                    var numChild = _j.value;
+                                    if (isWml(numChild, 'ilvl')) {
+                                        var parsed = parseDecimalVal(wValAttribute(numChild));
+                                        if (parsed === undefined) {
+                                            numPrExtra.push(numChild);
+                                        }
+                                        else {
+                                            listLevelValue = parsed;
+                                        }
+                                        continue;
+                                    }
+                                    if (isWml(numChild, 'numId')) {
+                                        var parsed = parseDecimalVal(wValAttribute(numChild));
+                                        if (parsed === undefined) {
+                                            numPrExtra.push(numChild);
+                                        }
+                                        else {
+                                            numIdValue = parsed;
+                                        }
+                                        continue;
+                                    }
+                                    numPrExtra.push(numChild);
+                                }
+                            }
+                            catch (e_3_1) { e_3 = { error: e_3_1 }; }
+                            finally {
+                                try {
+                                    if (_j && !_j.done && (_c = _h.return)) _c.call(_h);
+                                }
+                                finally { if (e_3) throw e_3.error; }
+                            }
+                            continue;
+                        }
+                        if (isWml(prop, 'rPr')) {
+                            // Paragraph-mark character formatting (`w:pPr/w:rPr`).
+                            breakCfSnap = parseCharacterFormat(prop);
+                            continue;
+                        }
+                        if (isWml(prop, 'sectPr')) {
+                            sectionBreakSectPr = prop;
+                            continue;
+                        }
+                    }
+                }
+                catch (e_2_1) { e_2 = { error: e_2_1 }; }
+                finally {
+                    try {
+                        if (_g && !_g.done && (_b = _f.return)) _b.call(_f);
+                    }
+                    finally { if (e_2) throw e_2.error; }
+                }
+                // TASK-9020-C: format-owned pPr interpretation (skips pStyle/numPr/rPr/sectPr).
+                formatSnap = parseParagraphFormat(child);
+                continue;
+            }
+            if (isWml(child, 'r')) {
+                // Owner is applied by paragraph.hydrate → collection.hydrate.
+                var groupItems = parseTextRangeGroup(child, undefined);
+                for (var gi = 0; gi < groupItems.length; gi += 1) {
+                    items.push(groupItems[gi]);
+                }
+                continue;
+            }
+            var feature = tryParseFeatureInline(child);
+            if (feature !== undefined) {
+                items.push(new FeatureInlineParagraphItem(feature.featureId, feature.value));
+                continue;
+            }
+            items.push(new OpaqueParagraphItem(child));
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (_e && !_e.done && (_a = _d.return)) _a.call(_d);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    paragraph.hydrate({
+        extraAttributes: el.attributes,
+        styleIdValue: styleIdValue,
+        numIdValue: numIdValue,
+        listLevelValue: listLevelValue,
+        numPrExtra: numPrExtra,
+        sectionBreakSectPr: sectionBreakSectPr,
+        items: items,
+        paragraphFormat: formatSnap !== undefined
+            ? formatSnap
+            : emptyParagraphFormatSnapshot(),
+        breakCharacterFormat: breakCfSnap,
+    });
+    return paragraph;
+}
+/**
+ * Serialize a paragraph. `w:pPr` children after `pStyle` come from
+ * {@link ParagraphFormat.buildPPrChildren} (CT_PPr order; TASK-9020-D).
+ * Mark `w:rPr` is injected from {@link Paragraph.breakCharacterFormat}.
+ */
+export function serializeParagraph(paragraph) {
+    var snap = paragraph.snapshot();
+    var pPrChildren = [];
+    if (snap.styleIdValue !== undefined) {
+        pPrChildren.push(wmlElement('pStyle', { attributes: [wmlAttr('val', snap.styleIdValue)] }));
+    }
+    var numPr;
+    if (snap.numIdValue !== undefined ||
+        snap.listLevelValue !== undefined ||
+        snap.numPrExtra.length > 0) {
+        var numPrChildren = [];
+        if (snap.listLevelValue !== undefined) {
+            numPrChildren.push(wmlElement('ilvl', { attributes: [wmlAttr('val', String(snap.listLevelValue))] }));
+        }
+        if (snap.numIdValue !== undefined) {
+            numPrChildren.push(wmlElement('numId', { attributes: [wmlAttr('val', String(snap.numIdValue))] }));
+        }
+        for (var i = 0; i < snap.numPrExtra.length; i++) {
+            numPrChildren.push(snap.numPrExtra[i]);
+        }
+        numPr = wmlElement('numPr', { children: numPrChildren });
+    }
+    // Match TextRange: omit empty mark rPr (no empty <w:rPr/>).
+    var rPrChildList = paragraph.breakCharacterFormat.buildRPrChildren();
+    var rPr;
+    if (rPrChildList.length > 0) {
+        rPr = wmlElement('rPr', { children: rPrChildList });
+    }
+    var formatChildren = paragraph.paragraphFormat.buildPPrChildren({
+        numPr: numPr,
+        rPr: rPr,
+        sectPr: snap.sectionBreakSectPr,
+    });
+    for (var i = 0; i < formatChildren.length; i++) {
+        pPrChildren.push(formatChildren[i]);
+    }
+    var children = [];
+    if (pPrChildren.length > 0) {
+        children.push(wmlElement('pPr', { children: pPrChildren }));
+    }
+    var itemXml = serializeParagraphItems(snap.items);
+    for (var i = 0; i < itemXml.length; i++) {
+        children.push(itemXml[i]);
+    }
+    // DocIO pageBreakAfter has no ECMA pPr child. Body serializers emit a
+    // following page-break-only paragraph via shouldEmitPageBreakAfterParagraph /
+    // createPageBreakAfterParagraphElement — do not append w:br into this w:p.
+    // Citation: docs/specs/paragraph-formatting.md (deliberate omissions); ECMA-376-1 §17.3.3.1 w:br.
+    return wmlElement('p', { attributes: snap.extraAttributes, children: children });
+}
+/**
+ * True when {@link ParagraphFormat.pageBreakAfter} should emit a dedicated
+ * following paragraph containing only `w:br/@w:type="page"`.
+ *
+ * Skips when the content paragraph already contains a page-break item so
+ * authoring does not duplicate breaks.
+ *
+ * @private
+ */
+export function shouldEmitPageBreakAfterParagraph(paragraph) {
+    var snap = paragraph.snapshot();
+    if (snap.paragraphFormat.pageBreakAfterValue !== true) {
+        return false;
+    }
+    return !paragraphItemsIncludePageBreak(snap.items);
+}
+/**
+ * Build a standalone `w:p` whose only content is a page break run.
+ * Used after a content paragraph when {@link shouldEmitPageBreakAfterParagraph}.
+ *
+ * @private
+ */
+export function createPageBreakAfterParagraphElement() {
+    var pageBreakItem = createStandaloneBreakItem(BreakType.PageBreak);
+    var breakXml = serializeParagraphItems([pageBreakItem]);
+    return wmlElement('p', { children: breakXml });
+}
+/**
+ * True when paragraph items already contain a page break (`w:br/@w:type="page"`).
+ * @private
+ */
+function paragraphItemsIncludePageBreak(items) {
+    for (var i = 0; i < items.length; i++) {
+        var item = items[i];
+        if (item instanceof Break && item.breakType === BreakType.PageBreak) {
+            return true;
+        }
+    }
+    return false;
+}
+// Re-export BodyItem for historical import sites (paragraph was the old home).
+// TS 3.3.1: no export type { ... } from (3.8+). Use import() type queries.