@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/drawing/drawing-shape.js

@@ -0,0 +1,3239 @@
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+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 __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;
+};
+import { EntityType } from '../document/entity-type';
+import { pointToEmus, pointToCoordinateEmus, emuToPoint } from '../document/length';
+import { Body } from '../document/body';
+import { Paragraph } from '../document/paragraph';
+import { FeatureRunParagraphItem } from '../document/text-range';
+import { isWml, wmlElement } from '../document/wml';
+import { DetachedObjectError, DocxError } from '../../core/errors/docx-error';
+import { assertEnumMember, HORIZONTAL_ALIGNMENT_SET, HORIZONTAL_ORIGIN_SET, TEXT_WRAPPING_STYLE_SET, TEXT_WRAPPING_TYPE_SET, TextWrappingStyle, TextWrappingType, VERTICAL_ALIGNMENT_SET, VERTICAL_ORIGIN_SET, HorizontalAlignment as HorizontalAlignmentType, HorizontalOrigin as HorizontalOriginType, VerticalAlignment as VerticalAlignmentType, VerticalOrigin as VerticalOriginType } from '../images/layout-types';
+import { isTableBlock, isTableBodyItem } from '../tables/index';
+import { ContentControl } from '../content-controls/index';
+import { isBlockContentControl } from '../content-controls/index';
+function bindFeatureBlockToDocument(value, document) {
+    if (document === undefined) {
+        return;
+    }
+    if (typeof value !== 'object' || value === null || !('bindDocument' in value)) {
+        return;
+    }
+    var bindDocument = value.bindDocument;
+    bindDocument.call(value, document);
+}
+import { buildNestedWpsShape, encodeAuthoredDrawingShape, encodeAuthoredGroup, findFirstElement, isNestedDrawingResidual, preferredDrawingElement, patchResidualCNvPr, patchResidualDocPr, patchResidualLayout, readCNvPrIdentity, readDocPrIdentity, readDrawingLayout, readDrawingPositionState, readDrawingWrapState, WP_NS, WPS_NS, parseTxbxContentBlocks, serializeTxbxContentBlocks } from './host-codec';
+import { readShapePropertiesState } from './sp-pr';
+import { buildBodyPrElement, findTxbxContentElement, findTxbxElement, readBodyPropertiesState } from './body-pr';
+import { AutoShapeType, isPresetAutoShapeType, isStShapeType } from './shape-types';
+import { defaultAuthoredShapeFill, FillFormat } from './fill-format';
+import { defaultAuthoredShapeLine, LineFormat } from './line-format';
+import { WrapFormat } from './wrap-format';
+import { TextFrame } from './text-frame';
+import { ANCHOR_DEFAULT_SIDE_DIST_EMU } from './types';
+import { cloneResidualElement, collectRelationshipIds, detectDmlVariant, detectVmlVariant, elementChildren, emptyTxbxParagraphBlocks, findNestedDrawingContainer, residualHasVmlFallback, } from './residual-utils';
+import { drawingShapeInit, encodeDrawingShapeInput, encodeGroupInput, modeledFillForEncode, modeledLineForEncode, } from './encode-builders';
+import { allocateDocPrId } from './parse-register';
+/**
+ * Shape `w:txbxContent` story as a document {@link Body}.
+ * Syncs the live block store back onto the parent shape on mutate.
+ * @private
+ */
+var ShapeTextBoxBody = /** @class */ (function (_super) {
+    __extends(ShapeTextBoxBody, _super);
+    function ShapeTextBoxBody(hostShape, document, items) {
+        var _this = _super.call(this, document, items) || this;
+        _this.hostShape = hostShape;
+        return _this;
+    }
+    /**
+     * @private
+     */
+    ShapeTextBoxBody.prototype.replaceRawBlocks = function (blocks) {
+        _super.prototype.replaceRawBlocks.call(this, blocks);
+        this.hostShape.syncTxbxBlocksFromBody(this.rawBlocks());
+    };
+    /**
+     * @private
+     * Prefer the shape anchor document when the body was constructed detached.
+     */
+    ShapeTextBoxBody.prototype.owningDocument = function () {
+        try {
+            return _super.prototype.owningDocument.call(this);
+        }
+        catch (e) {
+            return this.hostShape.internalOwningDocument();
+        }
+    };
+    return ShapeTextBoxBody;
+}(Body));
+var TextBoxParagraphOwner = /** @class */ (function () {
+    function TextBoxParagraphOwner(shape) {
+        this.shape = shape;
+    }
+    TextBoxParagraphOwner.prototype.assertAttachedParagraph = function (target) {
+        if (!blockListOwnsParagraph(this.shape.internalBlocks(), target)) {
+            throw new DetachedObjectError('Paragraph is not in this text box');
+        }
+    };
+    /**
+     * @private
+     */
+    TextBoxParagraphOwner.prototype.owningDocument = function () {
+        // Text box paragraphs live inside the run leaf; the owning document is the
+        // document that owns the anchoring paragraph. Resolve lazily through the
+        // shape's anchor paragraph when bound; otherwise detached.
+        return this.shape.internalOwningDocument();
+    };
+    return TextBoxParagraphOwner;
+}());
+export { TextBoxParagraphOwner };
+/** Deep membership check: direct or nested (table cell / SDT) paragraph. */
+export function blockListOwnsParagraph(blocks, target) {
+    var e_1, _a;
+    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' && block.paragraph === target) {
+                return true;
+            }
+            if (isTableBlock(block)) {
+                if (tableOwnsParagraph(block.value, target)) {
+                    return true;
+                }
+            }
+            if (isBlockContentControl(block)) {
+                var inner = block.value.blockContentControl;
+                if (inner !== undefined && bodyItemsOwnParagraph(inner, target)) {
+                    return true;
+                }
+            }
+        }
+    }
+    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 false;
+}
+/** Membership over projected public body items (nested SDT children). */
+function bodyItemsOwnParagraph(items, target) {
+    var e_2, _a;
+    try {
+        for (var items_1 = __values(items), items_1_1 = items_1.next(); !items_1_1.done; items_1_1 = items_1.next()) {
+            var item = items_1_1.value;
+            if (item instanceof Paragraph && item === target) {
+                return true;
+            }
+            if (isTableBodyItem(item)) {
+                if (tableOwnsParagraph(item, target)) {
+                    return true;
+                }
+            }
+            if (item instanceof ContentControl) {
+                var nested = item.blockContentControl;
+                if (nested !== undefined && bodyItemsOwnParagraph(nested, target)) {
+                    return true;
+                }
+            }
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (items_1_1 && !items_1_1.done && (_a = items_1.return)) _a.call(items_1);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    return false;
+}
+export function tableOwnsParagraph(table, target) {
+    var e_3, _a, e_4, _b, e_5, _c, e_6, _d;
+    try {
+        for (var _e = __values(table.rows.toArray()), _f = _e.next(); !_f.done; _f = _e.next()) {
+            var row = _f.value;
+            try {
+                for (var _g = __values(row.cells.toArray()), _h = _g.next(); !_h.done; _h = _g.next()) {
+                    var cell = _h.value;
+                    try {
+                        for (var _j = __values(cell.listParagraphs()), _k = _j.next(); !_k.done; _k = _j.next()) {
+                            var cellParagraph = _k.value;
+                            if (cellParagraph === target) {
+                                return true;
+                            }
+                        }
+                    }
+                    catch (e_5_1) { e_5 = { error: e_5_1 }; }
+                    finally {
+                        try {
+                            if (_k && !_k.done && (_c = _j.return)) _c.call(_j);
+                        }
+                        finally { if (e_5) throw e_5.error; }
+                    }
+                    try {
+                        for (var _l = __values(cell.nestedTables), _m = _l.next(); !_m.done; _m = _l.next()) {
+                            var nested = _m.value;
+                            if (tableOwnsParagraph(nested, target)) {
+                                return true;
+                            }
+                        }
+                    }
+                    catch (e_6_1) { e_6 = { error: e_6_1 }; }
+                    finally {
+                        try {
+                            if (_m && !_m.done && (_d = _l.return)) _d.call(_l);
+                        }
+                        finally { if (e_6) throw e_6.error; }
+                    }
+                }
+            }
+            catch (e_4_1) { e_4 = { error: e_4_1 }; }
+            finally {
+                try {
+                    if (_h && !_h.done && (_b = _g.return)) _b.call(_g);
+                }
+                finally { if (e_4) throw e_4.error; }
+            }
+        }
+    }
+    catch (e_3_1) { e_3 = { error: e_3_1 }; }
+    finally {
+        try {
+            if (_f && !_f.done && (_a = _e.return)) _a.call(_e);
+        }
+        finally { if (e_3) throw e_3.error; }
+    }
+    return false;
+}
+/**
+ * Minimum `w:txbxContent` body: one empty paragraph (`EG_BlockLevelElts`
+ * minOccurs=1 — `CT_TxbxContent` cannot be empty; Word authors a bare `w:p`).
+ */
+/**
+ * Shared base for DrawingML / VML run leaves: identity, placement, size,
+ * rotation/flip/lock, wrap/distances, position, residual dirty plumbing, and
+ * `FeatureRunLeaf` serialization.
+ *
+ * Concrete leaves are {@link Shape}; group/canvas hosts are {@link GroupShape}.
+ * Prefer those subclasses (and {@link createDrawingShape}) at construction time.
+ * `instanceof DrawingShape` remains true for both subclasses so existing leaf
+ * guards keep working.
+ *
+ * Clean load/save is residual pass-through. Identity mutators patch `wp:docPr`
+ * only. Layout mutators (size/rotation/lock/flip) patch residual extent+xfrm+locks
+ * without full dual-AC rebuild. Position mutators (H/V origin, offset vs align,
+ * `lockAnchor`/`allowOverlap`/`layoutInCell`) mark the shape structure dirty:
+ * the dual MC shell is re-encoded with residual position preserved per-axis
+ * when a mode was not modeled. Authoring (`appendShape`) emits dual MC
+ * AlternateContent (Choice wps + Fallback VML stub) — GO Policy B.
+ * Text box leaves expose `wps:bodyPr` typed state and the `w:txbxContent`
+ * block body (paragraphs / tables / nested tables / block SDTs — GO Q6);
+ * non-textBox shapes throw on body APIs (TASK-8049).
+ *
+ * @private
+ */
+var DrawingShape = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function DrawingShape(encodingOrInit, element) {
+        var e_7, _a;
+        /** Whether a horizontal position mode (offset or align) is explicitly modeled. */
+        this.horizontalModeled = false;
+        /** Whether a vertical position mode (offset or align) is explicitly modeled. */
+        this.verticalModeled = false;
+        if (typeof encodingOrInit === 'string') {
+            if (element === undefined) {
+                throw new TypeError('DrawingShape residual element is required');
+            }
+            this.encodingValue = encodingOrInit;
+            this.residual = element;
+            this.dirtyMode = 'clean';
+            var identity = isNestedDrawingResidual(element)
+                ? readCNvPrIdentity(element)
+                : readDocPrIdentity(element);
+            this.nameValue = identity.name;
+            this.titleValue = identity.title;
+            this.descriptionValue = identity.description;
+            this.docPrIdValue = identity.docPrId;
+            this.distancesModeled = false;
+            this.behindDocumentModeled = false;
+            this.fillModeled = false;
+            this.lineModeled = false;
+            this.txbxBodyModeled = false;
+            this.bodyPrModeled = false;
+            this.childrenValue = [];
+            this.childrenModeled = false;
+            this.childrenCache = undefined;
+            this.parentGroup = undefined;
+            // Layout / wrap / position / spPr fields stay undefined until first
+            // read/mtate so clean residual path does not force modeled defaults onto wire.
+            return;
+        }
+        this.encodingValue = encodingOrInit.encoding;
+        this.residual = encodingOrInit.residual;
+        this.dirtyMode = encodingOrInit.dirty;
+        this.nameValue = encodingOrInit.name;
+        this.titleValue = encodingOrInit.title;
+        this.descriptionValue = encodingOrInit.description;
+        this.docPrIdValue = encodingOrInit.docPrId;
+        this.placementValue = encodingOrInit.placement;
+        this.widthValue = encodingOrInit.width;
+        this.heightValue = encodingOrInit.height;
+        this.presetGeometryValue = encodingOrInit.presetGeometry;
+        this.rotationValue = encodingOrInit.rotation;
+        this.lockAspectRatioValue = encodingOrInit.lockAspectRatio;
+        this.flipHorizontalValue = encodingOrInit.flipHorizontal;
+        this.flipVerticalValue = encodingOrInit.flipVertical;
+        this.wrappingValue = encodingOrInit.wrapping;
+        this.wrappingTypeValue = encodingOrInit.wrapType;
+        this.distanceTopValue = encodingOrInit.distanceTop;
+        this.distanceBottomValue = encodingOrInit.distanceBottom;
+        this.distanceLeftValue = encodingOrInit.distanceLeft;
+        this.distanceRightValue = encodingOrInit.distanceRight;
+        this.behindDocumentValue = encodingOrInit.behindDocument;
+        this.distancesModeled =
+            encodingOrInit.distanceTop !== undefined ||
+                encodingOrInit.distanceBottom !== undefined ||
+                encodingOrInit.distanceLeft !== undefined ||
+                encodingOrInit.distanceRight !== undefined;
+        this.behindDocumentModeled = encodingOrInit.behindDocument !== undefined;
+        this.horizontalOriginValue = encodingOrInit.horizontalOrigin;
+        this.verticalOriginValue = encodingOrInit.verticalOrigin;
+        this.horizontalPositionValue = encodingOrInit.horizontalPosition;
+        this.verticalPositionValue = encodingOrInit.verticalPosition;
+        this.horizontalAlignmentValue = encodingOrInit.horizontalAlignment;
+        this.verticalAlignmentValue = encodingOrInit.verticalAlignment;
+        this.horizontalModeled =
+            encodingOrInit.horizontalPosition !== undefined ||
+                encodingOrInit.horizontalAlignment !== undefined ||
+                encodingOrInit.horizontalOrigin !== undefined;
+        this.verticalModeled =
+            encodingOrInit.verticalPosition !== undefined ||
+                encodingOrInit.verticalAlignment !== undefined ||
+                encodingOrInit.verticalOrigin !== undefined;
+        this.lockAnchorValue = encodingOrInit.lockAnchor;
+        this.allowOverlapValue = encodingOrInit.allowOverlap;
+        this.layoutInCellValue = encodingOrInit.layoutInCell;
+        this.fillValue = encodingOrInit.fill;
+        this.fillModeled = encodingOrInit.fill !== undefined;
+        this.lineValue = encodingOrInit.line;
+        this.lineModeled = encodingOrInit.line !== undefined;
+        this.txbxBodyModeled = encodingOrInit.txbxContent !== undefined;
+        this.bodyPrModeled = encodingOrInit.bodyPrElement !== undefined;
+        if (encodingOrInit.bodyPrElement !== undefined) {
+            this.bodyPrValue = readBodyPropertiesState(encodingOrInit.bodyPrElement);
+        }
+        this.childrenValue =
+            encodingOrInit.children !== undefined ? __spread(encodingOrInit.children) : [];
+        this.childrenModeled = encodingOrInit.children !== undefined;
+        this.childrenCache = undefined;
+        this.parentGroup = undefined;
+        if (this.childrenModeled) {
+            try {
+                for (var _b = __values(this.childrenValue), _c = _b.next(); !_c.done; _c = _b.next()) {
+                    var child = _c.value;
+                    child.parentGroup = this;
+                }
+            }
+            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; }
+            }
+        }
+    }
+    /**
+     * Whether this leaf is DrawingML (`w:drawing` / MC Choice) or VML (`w:pict`).
+     *
+     * @private
+     */
+    DrawingShape.prototype.encoding = function () {
+        return this.encodingValue;
+    };
+    /**
+     * Placement host for DrawingML leaves, or `unknown` for VML.
+     *
+     * @private
+     */
+    DrawingShape.prototype.placement = function () {
+        if (this.placementValue !== undefined) {
+            return this.placementValue;
+        }
+        if (this.encodingValue === 'vml') {
+            return 'unknown';
+        }
+        var drawing = this.drawingRoot();
+        if (drawing === undefined) {
+            return 'unknown';
+        }
+        if (findFirstElement(drawing, WP_NS, 'anchor') !== undefined) {
+            return 'anchor';
+        }
+        if (findFirstElement(drawing, WP_NS, 'inline') !== undefined) {
+            return 'inline';
+        }
+        return 'unknown';
+    };
+    /**
+     * Shape variant: kind of drawing object this leaf hosts.
+     *
+     * Detection is via `a:graphicData @uri` for DML and child element localName
+     * for VML. Modeled empty groups (`childrenModeled`) read as `'group'` before
+     * residual URI detection. Nested residual leaves (`wps:wsp` / `wpg:grpSp`)
+     * are classified from their own element when no `w:drawing` host is present
+     * (TASK-8051). Authored structure + presetGeometry still short-circuits to
+     * `'shape'` / `'textBox'` after group/canvas checks so residual groups are
+     * never misread as shapes.
+     *
+     * @private
+     */
+    DrawingShape.prototype.variant = function () {
+        if (this.encodingValue === 'vml') {
+            return detectVmlVariant(this.residual);
+        }
+        // Authored empty groups (and residual materialised children lists).
+        if (this.childrenModeled) {
+            return 'group';
+        }
+        // Nested residual shape/group hosts have no wp:docPr drawing root.
+        if (isNestedDrawingResidual(this.residual)) {
+            if (this.residual.localName === 'grpSp') {
+                return 'group';
+            }
+            if (this.txbxBodyModeled) {
+                return 'textBox';
+            }
+            if (this.presetGeometryValue !== undefined || this.dirtyMode === 'structure') {
+                return 'shape';
+            }
+            // Residual nested wsp: text box vs shape via local wps:txbx presence.
+            if (findFirstElement(this.residual, WPS_NS, 'txbx') !== undefined) {
+                return 'textBox';
+            }
+            return 'shape';
+        }
+        var drawing = this.drawingRoot();
+        if (drawing !== undefined) {
+            var fromUri = detectDmlVariant(drawing);
+            // Prefer residual group/canvas over structure+preset short-circuit so
+            // loaded groups never flip to 'shape' when geometry is later modeled.
+            if (fromUri === 'group' || fromUri === 'canvas') {
+                return fromUri;
+            }
+        }
+        if (this.presetGeometryValue !== undefined && this.dirtyMode === 'structure') {
+            return this.txbxBodyModeled ? 'textBox' : 'shape';
+        }
+        if (drawing === undefined) {
+            return 'unknown';
+        }
+        return detectDmlVariant(drawing);
+    };
+    /**
+     * Nested DrawingML children under a group or canvas host (TASK-8051).
+     *
+     * Leaf shapes, VML, and unknown variants return `[]`. Residual group/canvas
+     * hosts lazy-parse `wps:wsp` / `wpg:grpSp` under `wpg:wgp` or `wpc:wpc`.
+     * Modeled groups (including empty authored groups) return the owned list.
+     * Public consumers use {@link GroupShape.childShapes}.
+     *
+     * @private
+     */
+    DrawingShape.prototype.children = function () {
+        if (this.encodingValue === 'vml') {
+            return [];
+        }
+        if (this.childrenModeled) {
+            return this.childrenValue;
+        }
+        if (this.childrenCache !== undefined) {
+            return this.childrenCache;
+        }
+        var nested = this.parseNestedChildrenFromResidual();
+        this.childrenCache = nested;
+        return nested;
+    };
+    Object.defineProperty(DrawingShape.prototype, "name", {
+        /**
+         * Non-visual drawing name from `wp:docPr @name` / nested `cNvPr @name`.
+         * @public
+         */
+        get: function () {
+            if (this.nameValue !== undefined) {
+                return this.nameValue;
+            }
+            return this.readResidualIdentity().name;
+        },
+        set: function (value) {
+            this.nameValue = value;
+            this.markIdentityDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "title", {
+        /**
+         * Title from `wp:docPr @title` / nested `cNvPr @title`.
+         * @public
+         */
+        get: function () {
+            if (this.dirtyMode !== 'clean' || this.titleValue !== undefined) {
+                return this.titleValue;
+            }
+            return this.readResidualIdentity().title;
+        },
+        set: function (value) {
+            this.titleValue = value;
+            this.markIdentityDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "alternativeText", {
+        /**
+         * Alternative text from `wp:docPr @descr` / nested `cNvPr @descr`.
+         * @public
+         */
+        get: function () {
+            if (this.dirtyMode !== 'clean' || this.descriptionValue !== undefined) {
+                return this.descriptionValue;
+            }
+            return this.readResidualIdentity().description;
+        },
+        set: function (value) {
+            this.descriptionValue = value;
+            this.markIdentityDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "fillFormat", {
+        /**
+         * Stable fill format facade (Shape.md).
+         * @public
+         */
+        get: function () {
+            if (this.fillFormatValue === undefined) {
+                this.fillFormatValue = new FillFormat(this);
+            }
+            return this.fillFormatValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "lineFormat", {
+        /**
+         * Stable line format facade (Shape.md).
+         * @public
+         */
+        get: function () {
+            if (this.lineFormatValue === undefined) {
+                this.lineFormatValue = new LineFormat(this);
+            }
+            return this.lineFormatValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "wrapFormat", {
+        /**
+         * Stable wrap format facade (Shape.md).
+         * @public
+         */
+        get: function () {
+            if (this.wrapFormatValue === undefined) {
+                this.wrapFormatValue = new WrapFormat(this);
+            }
+            return this.wrapFormatValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "textFrame", {
+        /**
+         * Stable text frame facade (Shape.md).
+         * @public
+         */
+        get: function () {
+            if (this.textFrameValue === undefined) {
+                this.textFrameValue = new TextFrame(this);
+            }
+            return this.textFrameValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "textBody", {
+        /**
+         * Text-box story content as a document {@link Body} (`w:txbxContent`).
+         * First access promotes the leaf to a text-box variant (`wps:txbx`).
+         * @public
+         */
+        get: function () {
+            this.ensureTextBodyAccessible();
+            if (this.textBodyValue === undefined) {
+                var state = this.readTxbxState();
+                var document_1;
+                try {
+                    document_1 = this.internalOwningDocument();
+                }
+                catch (e) {
+                    document_1 = undefined;
+                }
+                this.textBodyValue = new ShapeTextBoxBody(this, document_1, state.blocks);
+                // Share the Body store with the txbx cache (constructor copies once).
+                this.syncTxbxBlocksFromBody(this.textBodyValue.rawBlocks());
+            }
+            return this.textBodyValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "autoShapeType", {
+        /**
+         * Auto shape type from preset geometry. Returns AutoShapeType.Unknown when missing/unrecognized/VML; Custom for custGeom.
+         * @public
+         */
+        get: function () {
+            if (this.encodingValue === 'vml') {
+                return AutoShapeType.Unknown;
+            }
+            if (this.readSpPrState().useCustomGeometry) {
+                return AutoShapeType.Custom;
+            }
+            var token = this.presetGeometryToken;
+            if (token !== undefined && isStShapeType(token)) {
+                return token;
+            }
+            return AutoShapeType.Unknown;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /** @private */
+    DrawingShape.prototype.readShapeFillState = function () {
+        if (this.fillModeled) {
+            return this.fillValue;
+        }
+        if (this.encodingValue === 'vml') {
+            return undefined;
+        }
+        return this.readSpPrState().fill;
+    };
+    /** @private */
+    DrawingShape.prototype.writeShapeFillState = function (value) {
+        if (value !== undefined && value.kind !== 'solid' && value.kind !== 'none') {
+            throw new RangeError("Fill kind \"" + String(value.kind) + "\" cannot be authored; use solid or none");
+        }
+        this.fillValue = value;
+        this.fillModeled = true;
+        this.markStructureDirty();
+    };
+    /** @private */
+    DrawingShape.prototype.readShapeLineState = function () {
+        if (this.lineModeled) {
+            return this.lineValue;
+        }
+        if (this.encodingValue === 'vml') {
+            return undefined;
+        }
+        return this.readSpPrState().line;
+    };
+    /** @private */
+    DrawingShape.prototype.writeShapeLineState = function (value) {
+        if (value !== undefined && value.kind !== 'solid' && value.kind !== 'none') {
+            throw new RangeError("Line kind \"" + String(value.kind) + "\" cannot be authored; use solid or none");
+        }
+        if (value !== undefined && value.kind === 'solid' && value.srgbColor === undefined) {
+            throw new RangeError('Solid line requires an sRGB color');
+        }
+        this.lineValue = value;
+        this.lineModeled = true;
+        this.markStructureDirty();
+    };
+    /** @private */
+    DrawingShape.prototype.readWrapStyle = function () {
+        return this.wrappingStyleInternal;
+    };
+    /** @private */
+    DrawingShape.prototype.writeWrapStyle = function (value) {
+        this.wrappingStyleInternal = value;
+    };
+    /** @private */
+    DrawingShape.prototype.readWrapType = function () {
+        if (this.wrappingTypeValue !== undefined) {
+            return this.wrappingTypeValue;
+        }
+        if (this.encodingValue === 'vml') {
+            return TextWrappingType.Both;
+        }
+        return readDrawingWrapState(this.residual).wrapType;
+    };
+    /** @private */
+    DrawingShape.prototype.writeWrapType = function (value) {
+        if (value === TextWrappingType.Unknown) {
+            throw new RangeError('WrapFormat.textWrappingType cannot be set to TextWrappingType.Unknown');
+        }
+        assertEnumMember('wrapType', value, TEXT_WRAPPING_TYPE_SET);
+        this.wrappingTypeValue = value;
+        this.markStructureDirty();
+    };
+    /** @private */
+    DrawingShape.prototype.readAllowOverlap = function () {
+        return this.allowOverlapInternal;
+    };
+    /** @private */
+    DrawingShape.prototype.writeAllowOverlap = function (value) {
+        this.allowOverlapInternal = value;
+    };
+    /** @private */
+    DrawingShape.prototype.readDistanceTop = function () {
+        return this.distanceTopInternal;
+    };
+    /** @private */
+    DrawingShape.prototype.writeDistanceTop = function (value) {
+        this.distanceTopInternal = value;
+    };
+    /** @private */
+    DrawingShape.prototype.readDistanceBottom = function () {
+        return this.distanceBottomInternal;
+    };
+    /** @private */
+    DrawingShape.prototype.writeDistanceBottom = function (value) {
+        this.distanceBottomInternal = value;
+    };
+    /** @private */
+    DrawingShape.prototype.readDistanceLeft = function () {
+        return this.distanceLeftInternal;
+    };
+    /** @private */
+    DrawingShape.prototype.writeDistanceLeft = function (value) {
+        this.distanceLeftInternal = value;
+    };
+    /** @private */
+    DrawingShape.prototype.readDistanceRight = function () {
+        return this.distanceRightInternal;
+    };
+    /** @private */
+    DrawingShape.prototype.writeDistanceRight = function (value) {
+        this.distanceRightInternal = value;
+    };
+    /** @private */
+    DrawingShape.prototype.readTextFrameDirection = function () {
+        return this.textDirection;
+    };
+    /** @private */
+    DrawingShape.prototype.writeTextFrameDirection = function (value) {
+        this.textDirection = value;
+    };
+    /** @private */
+    DrawingShape.prototype.readTextFrameVerticalAlignment = function () {
+        return this.verticalAnchor;
+    };
+    /** @private */
+    DrawingShape.prototype.writeTextFrameVerticalAlignment = function (value) {
+        this.verticalAnchor = value;
+    };
+    /** @private */
+    DrawingShape.prototype.readInternalMarginLeft = function () {
+        return this.readInsetPoints('left', 91440);
+    };
+    /** @private */
+    DrawingShape.prototype.writeInternalMarginLeft = function (value) {
+        this.writeInsetPoints('left', value);
+    };
+    /** @private */
+    DrawingShape.prototype.readInternalMarginTop = function () {
+        return this.readInsetPoints('top', 45720);
+    };
+    /** @private */
+    DrawingShape.prototype.writeInternalMarginTop = function (value) {
+        this.writeInsetPoints('top', value);
+    };
+    /** @private */
+    DrawingShape.prototype.readInternalMarginRight = function () {
+        return this.readInsetPoints('right', 91440);
+    };
+    /** @private */
+    DrawingShape.prototype.writeInternalMarginRight = function (value) {
+        this.writeInsetPoints('right', value);
+    };
+    /** @private */
+    DrawingShape.prototype.readInternalMarginBottom = function () {
+        return this.readInsetPoints('bottom', 45720);
+    };
+    /** @private */
+    DrawingShape.prototype.writeInternalMarginBottom = function (value) {
+        this.writeInsetPoints('bottom', value);
+    };
+    /** @private */
+    DrawingShape.prototype.readBodyInsets = function () {
+        return this.insets;
+    };
+    /** @private */
+    DrawingShape.prototype.writeBodyInsets = function (value) {
+        this.insets = value;
+    };
+    /**
+     * BodyInsets sides are **points** (body-pr parse/build converts at the
+     * wire boundary). Defaults are Word bodyPr EMU constants converted once.
+     * @private
+     */
+    DrawingShape.prototype.readInsetPoints = function (side, defaultEmu) {
+        var insets = this.readBodyInsets();
+        var points;
+        if (insets !== undefined) {
+            if (side === 'left')
+                points = insets.left;
+            else if (side === 'top')
+                points = insets.top;
+            else if (side === 'right')
+                points = insets.right;
+            else
+                points = insets.bottom;
+        }
+        if (points !== undefined) {
+            return points;
+        }
+        return emuToPoint(defaultEmu);
+    };
+    /**
+     * Store InternalMargin sides as points on BodyInsets (same unit as
+     * body-pr model). Do not convert to EMU here — buildBodyPrElement does.
+     * @private
+     */
+    DrawingShape.prototype.writeInsetPoints = function (side, points) {
+        var prev = this.readBodyInsets() || {};
+        var next = {
+            left: prev.left,
+            top: prev.top,
+            right: prev.right,
+            bottom: prev.bottom,
+        };
+        if (side === 'left')
+            next.left = points;
+        else if (side === 'top')
+            next.top = points;
+        else if (side === 'right')
+            next.right = points;
+        else
+            next.bottom = points;
+        this.writeBodyInsets(next);
+    };
+    /** @private */
+    DrawingShape.prototype.ensureTextBodyAccessible = function () {
+        // Keep the live DOM empty until the caller appends body content.
+        // Wire format still requires CT_TxbxContent minOccurs=1: serialize paths
+        // fall back to emptyTxbxParagraphBlocks() when blocks.length === 0.
+        this.readTxbxState();
+        // First textBody access promotes the leaf to a textBox variant (wps:txbx).
+        this.markTxbxBodyModeled();
+    };
+    /**
+     * @private
+     * Point the txbx cache at the Body block store after Body mutations.
+     */
+    DrawingShape.prototype.syncTxbxBlocksFromBody = function (blocks) {
+        var state = this.readTxbxState();
+        // TextBoxStateCached.blocks is readonly on the type but the cache is live.
+        state.blocks = blocks;
+        this.markTxbxBodyModeled();
+        this.markStructureDirty();
+    };
+    /**
+     * Append a nested preset-geometry shape under this group or canvas (TASK-8051).
+     *
+     * Only valid when {@link variant} is `'group'` or `'canvas'`. Nested children
+     * serialize as bare `wps:wsp` (with `wps:cNvPr`) under `wpg:wgp` / `wpc:wpc`
+     * — not as a second `w:drawing` host. Marks this host structure-dirty.
+     *
+     * @throws DocxError `content/invalid-shape` when the host is not a group/canvas,
+     *   or when geometry/size options are invalid.
+     *
+     * Public consumers call {@link GroupShape.appendShape}.
+     *
+     * @private
+     */
+    /**
+    * Append a nested preset-geometry {@link Shape} under this group or canvas.
+    * @public
+    */
+    DrawingShape.prototype.appendShape = function (autoShapeType, width, height) {
+        var hostVariant = this.variant();
+        if (hostVariant !== 'group' && hostVariant !== 'canvas') {
+            throw new DocxError('content/invalid-shape', "appendShape is only valid on group or canvas hosts; variant is \"" + hostVariant + "\"");
+        }
+        if (!isPresetAutoShapeType(autoShapeType)) {
+            throw new DocxError('content/invalid-shape', "Invalid autoShapeType \"" + String(autoShapeType) + "\"; expected a preset AutoShapeType token");
+        }
+        var widthEmu;
+        var heightEmu;
+        try {
+            widthEmu = pointToEmus(width);
+            heightEmu = pointToEmus(height);
+        }
+        catch (error) {
+            if (error instanceof RangeError) {
+                throw new DocxError('content/invalid-shape', 'Shape width and height must be positive point values', { cause: error });
+            }
+            throw error;
+        }
+        if (!(widthEmu > 0) || !(heightEmu > 0)) {
+            throw new DocxError('content/invalid-shape', 'Shape width and height must be positive point values');
+        }
+        var rotation = 0;
+        var name = 'Shape';
+        var lockAspectRatio = true;
+        var flipHorizontal = false;
+        var flipVertical = false;
+        var docPrId = this.allocateNestedDocPrId();
+        var defaultFill = defaultAuthoredShapeFill();
+        var defaultLine = defaultAuthoredShapeLine();
+        var nestedWsp = buildNestedWpsShape({
+            placement: 'anchor',
+            widthEmu: widthEmu,
+            heightEmu: heightEmu,
+            presetGeometry: autoShapeType,
+            docPrId: docPrId,
+            name: name,
+            title: undefined,
+            description: undefined,
+            rotation: rotation,
+            flipHorizontal: flipHorizontal,
+            flipVertical: flipVertical,
+            lockAspectRatio: lockAspectRatio,
+            txbxContent: undefined,
+            bodyPr: undefined,
+            fill: defaultFill,
+            line: modeledLineForEncode(defaultLine),
+        });
+        this.ensureChildrenModeled();
+        var child = new Shape(drawingShapeInit({
+            encoding: 'drawingml',
+            residual: nestedWsp,
+            dirty: 'structure',
+            name: name,
+            title: undefined,
+            description: undefined,
+            docPrId: docPrId,
+            width: width,
+            height: height,
+            presetGeometry: autoShapeType,
+            rotation: rotation,
+            lockAspectRatio: lockAspectRatio,
+            flipHorizontal: flipHorizontal,
+            flipVertical: flipVertical,
+            fill: defaultFill,
+            line: defaultLine,
+        }));
+        child.parentGroup = this;
+        this.childrenValue.push(child);
+        this.childrenModeled = true;
+        this.childrenCache = undefined;
+        this.markStructureDirty();
+        this.notifyParentOfChildDirty();
+        return child;
+    };
+    /**
+     * Extent (width × height) from modeled size or `wp:extent`, as point `number`.
+     *
+     * Returns `undefined` when no size is modeled and no `wp:extent` / `a:ext`
+     * is reachable with numeric `cx`/`cy`. VML leaves return `undefined`.
+     *
+     * @private
+     */
+    DrawingShape.prototype.extent = function () {
+        if (this.widthValue !== undefined && this.heightValue !== undefined) {
+            return { width: this.widthValue, height: this.heightValue };
+        }
+        if (this.encodingValue === 'vml') {
+            return undefined;
+        }
+        var layout = readDrawingLayout(this.residual);
+        if (layout.widthEmu !== undefined && layout.heightEmu !== undefined) {
+            return { width: emuToPoint(layout.widthEmu), height: emuToPoint(layout.heightEmu) };
+        }
+        return undefined;
+    };
+    /**
+
+     * numbers; kept for back-compat with existing feature-module tests.
+     *
+     * @private
+     */
+    DrawingShape.prototype.extentEmu = function () {
+        var e = this.extent();
+        if (e === undefined) {
+            return undefined;
+        }
+        return { width: pointToEmus(e.width), height: pointToEmus(e.height) };
+    };
+    Object.defineProperty(DrawingShape.prototype, "width", {
+        /**
+         * Display width (`wp:extent/@cx` preferred; EMU-backed point `number`).
+         * Setter marks layout dirty and updates both `wp:extent` and `a:xfrm/a:ext`
+         * on save. Does **not** auto-adjust height when {@link lockAspectRatio} is true
+         * (images parity — lock is a flag for consumers/Word).
+         *
+         * @public
+         */
+        get: function () {
+            if (this.widthValue !== undefined) {
+                return this.widthValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return undefined;
+            }
+            var layout = readDrawingLayout(this.residual);
+            return layout.widthEmu !== undefined ? emuToPoint(layout.widthEmu) : undefined;
+        },
+        set: function (value) {
+            this.widthValue = value;
+            this.markLayoutDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "height", {
+        /**
+         * Display height (`wp:extent/@cy` preferred). Same lock semantics as {@link width}.
+         *
+         * @public
+         */
+        get: function () {
+            if (this.heightValue !== undefined) {
+                return this.heightValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return undefined;
+            }
+            var layout = readDrawingLayout(this.residual);
+            return layout.heightEmu !== undefined ? emuToPoint(layout.heightEmu) : undefined;
+        },
+        set: function (value) {
+            this.heightValue = value;
+            this.markLayoutDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "rotation", {
+        /**
+         * Clockwise rotation in degrees (`a:xfrm/@rot`).
+         * Wire uses ST_Angle = degrees × 60000. Missing attribute reads as `0`.
+         * `@rot` is omitted on encode when the value is `0`.
+         *
+         * @throws RangeError when the value is not finite.
+         *
+         * @public
+         */
+        get: function () {
+            if (this.rotationValue !== undefined) {
+                return this.rotationValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return 0;
+            }
+            return readDrawingLayout(this.residual).rotation;
+        },
+        set: function (value) {
+            if (!Number.isFinite(value)) {
+                throw new RangeError("Invalid rotation value \"" + String(value) + "\"; expected a finite number");
+            }
+            this.rotationValue = value;
+            this.markLayoutDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "lockAspectRatio", {
+        /**
+         * Aspect-ratio lock (`a:graphicFrameLocks/@noChangeAspect`).
+         * Authoring default is `true`; missing locks on load read as `false`.
+         * Setting the flag does not recompute width/height (images parity).
+         *
+         * @public
+         */
+        get: function () {
+            if (this.lockAspectRatioValue !== undefined) {
+                return this.lockAspectRatioValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return false;
+            }
+            return readDrawingLayout(this.residual).lockAspectRatio;
+        },
+        set: function (value) {
+            this.lockAspectRatioValue = value;
+            this.markLayoutDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "flipHorizontal", {
+        /**
+         * Horizontal flip (`a:xfrm/@flipH`). Missing attribute reads as `false`.
+         *
+         * @public
+         */
+        get: function () {
+            if (this.flipHorizontalValue !== undefined) {
+                return this.flipHorizontalValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return false;
+            }
+            return readDrawingLayout(this.residual).flipHorizontal;
+        },
+        set: function (value) {
+            this.flipHorizontalValue = value;
+            this.markLayoutDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "flipVertical", {
+        /**
+         * Vertical flip (`a:xfrm/@flipV`). Missing attribute reads as `false`.
+         *
+         * @public
+         */
+        get: function () {
+            if (this.flipVerticalValue !== undefined) {
+                return this.flipVerticalValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return false;
+            }
+            return readDrawingLayout(this.residual).flipVertical;
+        },
+        set: function (value) {
+            this.flipVerticalValue = value;
+            this.markLayoutDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "wrappingStyleInternal", {
+        /**
+         * Text wrapping style.
+         *
+         * - `'inline'` serializes as `wp:inline`. Collapsing an anchored shape to
+         *   inline **drops** position and wrap residual by design (images parity).
+         * - Other values promote to `wp:anchor` with the matching `wp:wrap*` child.
+         *   Tight/through without a residual wrapPolygon fall back to `wrapNone`
+         *   (library does not invent polygons).
+         *
+         * VML leaves report `'none'`.
+         *
+         * @throws RangeError when `value` is not a known {@link TextWrappingStyle}.
+         *
+         * @public
+         */
+        /** @private */
+        get: function () {
+            if (this.wrappingValue !== undefined) {
+                return this.wrappingValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return TextWrappingStyle.None;
+            }
+            return readDrawingWrapState(this.residual).wrapping;
+        },
+        /** @private */
+        set: function (value) {
+            assertEnumMember('wrappingStyle', value, TEXT_WRAPPING_STYLE_SET);
+            this.wrappingValue = value;
+            if (value === TextWrappingStyle.Inline) {
+                this.placementValue = 'inline';
+            }
+            else {
+                this.placementValue = 'anchor';
+            }
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "distanceTopInternal", {
+        /**
+         * Distance from text above the shape (`wp:inline|wp:anchor/@distT`).
+         * Missing residual attribute reads as `emuToPoint(0)`.
+         *
+         * @public
+         */
+        /** @private */
+        get: function () {
+            return this.readDistancePoints('top');
+        },
+        /** @private */
+        set: function (value) {
+            this.distanceTopValue = value;
+            this.distancesModeled = true;
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "distanceBottomInternal", {
+        /**
+         * Distance from text below the shape (`wp:inline|wp:anchor/@distB`).
+         * Missing residual attribute reads as `0` points.
+         *
+         * @public
+         */
+        /** @private */
+        get: function () {
+            return this.readDistancePoints('bottom');
+        },
+        /** @private */
+        set: function (value) {
+            this.distanceBottomValue = value;
+            this.distancesModeled = true;
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "distanceLeftInternal", {
+        /**
+         * Distance from text to the left of the shape (`wp:inline|wp:anchor/@distL`).
+         * Missing residual on anchor reads as author default `emuToPoint(114300)`; inline `0` points.
+         *
+         * @public
+         */
+        /** @private */
+        get: function () {
+            return this.readDistancePoints('left');
+        },
+        /** @private */
+        set: function (value) {
+            this.distanceLeftValue = value;
+            this.distancesModeled = true;
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "distanceRightInternal", {
+        /**
+         * Distance from text to the right of the shape (`wp:inline|wp:anchor/@distR`).
+         * Missing residual on anchor reads as author default `emuToPoint(114300)`; inline `0` points.
+         *
+         * @public
+         */
+        /** @private */
+        get: function () {
+            return this.readDistancePoints('right');
+        },
+        /** @private */
+        set: function (value) {
+            this.distanceRightValue = value;
+            this.distancesModeled = true;
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "isBelowText", {
+        /**
+         * Whether the shape is behind document text (`wp:anchor/@behindDoc`).
+         * Inline hosts always report `false`. VML leaves report `false`.
+         *
+         * @private
+         */
+        /**
+         * Whether the shape is drawn below text (`wp:anchor/@behindDoc`).
+         * @public
+         */
+        get: function () {
+            if (this.behindDocumentValue !== undefined) {
+                return this.behindDocumentValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return false;
+            }
+            return readDrawingWrapState(this.residual).behindDocument;
+        },
+        set: function (value) {
+            this.behindDocumentValue = value;
+            this.behindDocumentModeled = true;
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "horizontalOrigin", {
+        /**
+         * Horizontal origin (`wp:positionH/@relativeFrom`, `ST_RelFromH`).
+         * Missing residual position reads as {@link HorizontalOrigin.Column}.
+         * Effective getter never returns `undefined` and does not dirty on read.
+         *
+         * @throws RangeError when `value` is not a known {@link HorizontalOrigin}.
+         *
+         * @public
+         */
+        get: function () {
+            if (this.horizontalOriginValue !== undefined) {
+                return this.horizontalOriginValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return HorizontalOriginType.Column;
+            }
+            var fromResidual = readDrawingPositionState(this.residual).horizontalOrigin;
+            return fromResidual !== undefined ? fromResidual : HorizontalOriginType.Column;
+        },
+        set: function (value) {
+            if (value !== undefined) {
+                assertEnumMember('horizontalOrigin', value, HORIZONTAL_ORIGIN_SET);
+            }
+            this.horizontalModeled = true;
+            this.horizontalOriginValue = value;
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "verticalOrigin", {
+        /**
+         * Vertical origin (`wp:positionV/@relativeFrom`, `ST_RelFromV`).
+         * Missing residual position reads as {@link VerticalOrigin.Paragraph}.
+         * Effective getter never returns `undefined` and does not dirty on read.
+         *
+         * @throws RangeError when `value` is not a known {@link VerticalOrigin}.
+         *
+         * @public
+         */
+        get: function () {
+            if (this.verticalOriginValue !== undefined) {
+                return this.verticalOriginValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return VerticalOriginType.Paragraph;
+            }
+            var fromResidual = readDrawingPositionState(this.residual).verticalOrigin;
+            return fromResidual !== undefined ? fromResidual : VerticalOriginType.Paragraph;
+        },
+        set: function (value) {
+            if (value !== undefined) {
+                assertEnumMember('verticalOrigin', value, VERTICAL_ORIGIN_SET);
+            }
+            this.verticalModeled = true;
+            this.verticalOriginValue = value;
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "horizontalPosition", {
+        /**
+         * Horizontal offset (`wp:positionH/wp:posOffset`).
+         * Setting a defined offset clears {@link horizontalAlignment} (align XOR
+         * posOffset — CT_PosH schema choice). Setting `undefined` clears the modeled
+         * offset (encoder then falls back to offset `0` unless align is modeled).
+         *
+         * @public
+         */
+        get: function () {
+            if (this.horizontalPositionValue !== undefined) {
+                return this.horizontalPositionValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return undefined;
+            }
+            return readDrawingPositionState(this.residual).horizontalPosition;
+        },
+        set: function (value) {
+            this.horizontalModeled = true;
+            this.horizontalPositionValue = value;
+            if (value !== undefined) {
+                this.horizontalAlignmentValue = undefined;
+            }
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "verticalPosition", {
+        /**
+         * Vertical offset (`wp:positionV/wp:posOffset`).
+         * Setting a defined offset clears {@link verticalAlignment} (align XOR
+         * posOffset — CT_PosV schema choice). Setting `undefined` clears the modeled
+         * offset (encoder then falls back to offset `0` unless align is modeled).
+         *
+         * @public
+         */
+        get: function () {
+            if (this.verticalPositionValue !== undefined) {
+                return this.verticalPositionValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return undefined;
+            }
+            return readDrawingPositionState(this.residual).verticalPosition;
+        },
+        set: function (value) {
+            this.verticalModeled = true;
+            this.verticalPositionValue = value;
+            if (value !== undefined) {
+                this.verticalAlignmentValue = undefined;
+            }
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "horizontalAlignment", {
+        /**
+         * Horizontal alignment (`wp:positionH/wp:align`, `ST_AlignH`).
+         * Setting a defined alignment clears {@link horizontalPosition} (align XOR
+         * posOffset — CT_PosH schema choice). Effective value is never undefined:
+         * modeled alignment, else residual align, else {@link HorizontalAlignment.None}
+         * when the axis uses posOffset or the leaf is VML.
+         *
+         * @throws RangeError when `value` is not a known {@link HorizontalAlignment}.
+         *
+         * @public
+         */
+        get: function () {
+            if (this.horizontalAlignmentValue !== undefined) {
+                return this.horizontalAlignmentValue;
+            }
+            if (this.horizontalPositionValue !== undefined) {
+                return HorizontalAlignmentType.None;
+            }
+            if (this.encodingValue === 'vml') {
+                return HorizontalAlignmentType.None;
+            }
+            var fromResidual = readDrawingPositionState(this.residual).horizontalAlignment;
+            return fromResidual !== undefined ? fromResidual : HorizontalAlignmentType.None;
+        },
+        set: function (value) {
+            if (value !== undefined) {
+                if (value === HorizontalAlignmentType.Unknown) {
+                    throw new RangeError('horizontalAlignment cannot be set to HorizontalAlignment.Unknown');
+                }
+                assertEnumMember('horizontalAlignment', value, HORIZONTAL_ALIGNMENT_SET);
+                this.horizontalPositionValue = undefined;
+            }
+            this.horizontalModeled = true;
+            this.horizontalAlignmentValue = value;
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "verticalAlignment", {
+        /**
+         * Vertical alignment (`wp:positionV/wp:align`, `ST_AlignV`).
+         * Setting a defined alignment clears {@link verticalPosition} (align XOR
+         * posOffset — CT_PosV schema choice). Effective value is never undefined:
+         * modeled alignment, else residual align, else {@link VerticalAlignment.None}
+         * when the axis uses posOffset or the leaf is VML.
+         *
+         * @throws RangeError when `value` is not a known {@link VerticalAlignment}.
+         *
+         * @public
+         */
+        get: function () {
+            if (this.verticalAlignmentValue !== undefined) {
+                return this.verticalAlignmentValue;
+            }
+            if (this.verticalPositionValue !== undefined) {
+                return VerticalAlignmentType.None;
+            }
+            if (this.encodingValue === 'vml') {
+                return VerticalAlignmentType.None;
+            }
+            var fromResidual = readDrawingPositionState(this.residual).verticalAlignment;
+            return fromResidual !== undefined ? fromResidual : VerticalAlignmentType.None;
+        },
+        set: function (value) {
+            if (value !== undefined) {
+                if (value === VerticalAlignmentType.Unknown) {
+                    throw new RangeError('verticalAlignment cannot be set to VerticalAlignment.Unknown');
+                }
+                assertEnumMember('verticalAlignment', value, VERTICAL_ALIGNMENT_SET);
+                this.verticalPositionValue = undefined;
+            }
+            this.verticalModeled = true;
+            this.verticalAlignmentValue = value;
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "lockAnchor", {
+        /**
+         * Lock anchor (`wp:anchor/@locked`): the anchor location must not be modified
+         * at runtime by an application editing the document (ECMA-376-1 §20.4.2.1).
+         * Inline and VML leaves report `false`.
+         *
+         * @public
+         */
+        get: function () {
+            if (this.lockAnchorValue !== undefined) {
+                return this.lockAnchorValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return false;
+            }
+            return readDrawingWrapState(this.residual).lockAnchor;
+        },
+        set: function (value) {
+            this.lockAnchorValue = value;
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "allowOverlapInternal", {
+        /**
+         * Allow overlap (`wp:anchor/@allowOverlap`). Inline and VML leaves report
+         * `false` (inline hosts have no anchor surface).
+         *
+         * @public
+         */
+        /** @private */
+        get: function () {
+            if (this.allowOverlapValue !== undefined) {
+                return this.allowOverlapValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return false;
+            }
+            return readDrawingWrapState(this.residual).allowOverlap;
+        },
+        /** @private */
+        set: function (value) {
+            this.allowOverlapValue = value;
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "layoutInCell", {
+        /**
+         * Layout in table cell (`wp:anchor/@layoutInCell`). Inline and VML leaves
+         * report `false` (inline hosts have no anchor surface).
+         *
+         * @public
+         */
+        get: function () {
+            if (this.layoutInCellValue !== undefined) {
+                return this.layoutInCellValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return false;
+            }
+            return readDrawingWrapState(this.residual).layoutInCell;
+        },
+        set: function (value) {
+            this.layoutInCellValue = value;
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    // -------------------------------------------------------------------------
+    // Geometry, fill, line MVP (TASK-8048)
+    // -------------------------------------------------------------------------
+    /** Lazy spPr state read (cached per instance; invalidated on structure dirty). */
+    DrawingShape.prototype.readSpPrState = function () {
+        if (this.spPrState === undefined) {
+            var state = readShapePropertiesState(this.residual);
+            this.spPrState = {
+                presetGeometry: state.presetGeometry,
+                useCustomGeometry: state.useCustomGeometry,
+                fill: state.fill,
+                line: state.line,
+                hasThemeStyle: state.hasThemeStyle,
+            };
+        }
+        return this.spPrState;
+    };
+    Object.defineProperty(DrawingShape.prototype, "presetGeometryToken", {
+        /**
+         * Preset geometry token (`a:prstGeom/@prst`, `ST_ShapeType`).
+         * `undefined` when spPr is absent, has `a:custGeom`, or the `@prst` token is
+         * not in the schema set (residual passthrough). VML reads `undefined`.
+         *
+         * @throws RangeError when set to a value outside `ST_ShapeType`.
+         *
+         * @private
+         */
+        get: function () {
+            if (this.presetGeometryValue !== undefined) {
+                return this.presetGeometryValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return undefined;
+            }
+            return this.readSpPrState().presetGeometry;
+        },
+        set: function (value) {
+            if (value !== undefined && !isStShapeType(value)) {
+                throw new RangeError("Invalid presetGeometry value \"" + value + "\"; expected an ST_ShapeType token");
+            }
+            this.presetGeometryValue = value;
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "fillInternal", {
+        /**
+         * Fill MVP (`CT_ShapeProperties` `EG_FillProperties`).
+         *
+         * Reads:
+         * - `a:solidFill/a:srgbClr` → `{ kind: 'solid', srgb }`
+         * - `a:noFill` → `{ kind: 'none' }`
+         * - `a:pattFill` → `{ kind: 'pattern', preset }` (residual-preserving slice)
+         * - theme/absent/gradient/picture → `undefined` or `{ kind: 'theme' }`
+         *   (never an invented color); check {@link DrawingShape.hasThemeStyle}.
+         *
+         * Setting `solid`/`none` marks the shape structure dirty and replaces the
+         * spPr fill child (`wps:style` theme refs stay residual per GO).
+         *
+         * @public
+         */
+        /** @private */
+        get: function () {
+            if (this.fillModeled) {
+                return this.fillValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return undefined;
+            }
+            return this.readSpPrState().fill;
+        },
+        /** @private */
+        set: function (value) {
+            if (value !== undefined && value.kind !== 'solid' && value.kind !== 'none') {
+                throw new RangeError("Fill kind \"" + String(value.kind) + "\" cannot be authored; use solid or none");
+            }
+            this.fillValue = value;
+            this.fillModeled = true;
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "lineInternal", {
+        /**
+         * Line MVP (`a:ln`). `kind: 'theme'` when absent/non-srgb (inherited from
+         * `wps:style`); `kind: 'none'` when `a:ln/a:noFill`; `residual: true` flags a
+         * line with unmodeled children (join/custDash/nknown dash) — mutating it
+         * would drop those children, so serialization keeps the residual element
+         * unless the caller models it explicitly.
+         *
+         * @public
+         */
+        /** @private */
+        get: function () {
+            if (this.lineModeled) {
+                return this.lineValue;
+            }
+            if (this.encodingValue === 'vml') {
+                return undefined;
+            }
+            return this.readSpPrState().line;
+        },
+        /** @private */
+        set: function (value) {
+            if (value !== undefined && value.kind !== 'solid' && value.kind !== 'none') {
+                throw new RangeError("Line kind \"" + String(value.kind) + "\" cannot be authored; use solid or none");
+            }
+            this.lineValue = value;
+            this.lineModeled = true;
+            this.markStructureDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "hasThemeStyle", {
+        /**
+         * Whether theme formatting (`wps:style` with `lnRef`/`fillRef`/`effectRef`/
+         * `fontRef`) is present on the shape. Theme-styled shapes without a solid
+         *
+         * @private
+         * override read fill/line as `theme`/`undefined` — set {@link fill}/
+         * {@link line} to replace.
+         */
+        get: function () {
+            if (this.encodingValue === 'vml') {
+                return false;
+            }
+            return this.readSpPrState().hasThemeStyle;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    // -------------------------------------------------------------------------
+    // Text box bodyPr + txbx body (TASK-8049)
+    // -------------------------------------------------------------------------
+    /**
+     * Lazy residual txbx state read (cached per instance).
+     * @private
+     */
+    DrawingShape.prototype.readTxbxState = function () {
+        if (this.txbxState === undefined) {
+            if (this.encodingValue === 'vml') {
+                this.txbxState = {
+                    present: false,
+                    blocks: [],
+                    residualTxbx: undefined,
+                    residualTxbxContent: undefined,
+                };
+                return this.txbxState;
+            }
+            var residualTxbx = findTxbxElement(this.residual);
+            var residualTxbxContent = residualTxbx !== undefined ? findTxbxContentElement(residualTxbx) : undefined;
+            // Materialize lazily (spec: prefer lazy on first body access). Parse on
+            // first access with a textbox-scoped paragraph owner so appended content
+            // validates membership against this shape's body.
+            var blocks = residualTxbxContent !== undefined
+                ? parseTxbxContentBlocks(residualTxbxContent, this.textBoxOwnerForParse())
+                : [];
+            this.txbxState = {
+                present: residualTxbx !== undefined,
+                blocks: blocks,
+                residualTxbx: residualTxbx,
+                residualTxbxContent: residualTxbxContent,
+            };
+        }
+        return this.txbxState;
+    };
+    /**
+     * Paragraph-owner context for lazy body parse.
+     * @private
+     */
+    DrawingShape.prototype.textBoxOwnerForParse = function () {
+        if (this.textBoxOwner === undefined) {
+            this.textBoxOwner = new TextBoxParagraphOwner(this);
+        }
+        return this.textBoxOwner;
+    };
+    /**
+     * Whether this shape hosts a WordprocessingShape text box
+     * (`wps:txbx` child). Deep residual walk only — does **not** materialize
+     * the body block state (reads stay byte-stable). `linkedTxbx` also reports
+     * true for guard purposes — linked text boxes are out of scope (GO) but
+     * body APIs still throw the documented non-textBox error only when no txbx
+     * of any kind exists.
+     *
+     * @private
+     */
+    DrawingShape.prototype.isTextBox = function () {
+        if (this.encodingValue === 'vml') {
+            return false;
+        }
+        if (this.txbxBodyModeled) {
+            return true;
+        }
+        return findTxbxElement(this.residual) !== undefined;
+    };
+    /**
+     * Whether the residual root carries a Markup Compatibility Fallback branch
+     * with a VML `w:pict` tree (Policy B dual AC — TASK-8050).
+     *
+     * True for authored dual AC and for residual Choice+Fallback fixtures.
+     * Pure DrawingML-only or pure VML leaves return false. Does not execute VML.
+     *
+     * @private
+     */
+    DrawingShape.prototype.hasVmlFallback = function () {
+        if (this.encodingValue === 'vml') {
+            return false;
+        }
+        return residualHasVmlFallback(this.residual);
+    };
+    /** Guard for body APIs on non-textBox shapes. */
+    DrawingShape.prototype.requireTextBox = function () {
+        if (!this.isTextBox()) {
+            throw new DocxError('content/invalid-shape', 'Text box body APIs require a textBox variant shape (wps:txbx). ' +
+                'Author one with appendShape({ textBox: true }) or edit a loaded text box.');
+        }
+        return this.readTxbxState();
+    };
+    /**
+     * Lazy residual bodyPr state read (cached per instance).
+     * @private
+     */
+    DrawingShape.prototype.readBodyPrState = function () {
+        if (this.bodyPrModeled && this.bodyPrValue !== undefined) {
+            return this.bodyPrValue;
+        }
+        if (this.bodyPrValue === undefined) {
+            if (this.encodingValue === 'vml') {
+                this.bodyPrValue = {
+                    verticalAnchor: undefined,
+                    anchorCenter: undefined,
+                    textDirection: undefined,
+                    textWrapInside: undefined,
+                    verticalOverflow: undefined,
+                    horizontalOverflow: undefined,
+                    fromWordArt: undefined,
+                    insets: undefined,
+                    autoFit: undefined,
+                    hasPresetTextWarp: false,
+                    residual: false,
+                };
+            }
+            else {
+                this.bodyPrValue = readBodyPropertiesState(this.residual);
+            }
+        }
+        return this.bodyPrValue;
+    };
+    /**
+     * Persist a modeled bodyPr slice (marks structure dirty).
+     * @private
+     */
+    DrawingShape.prototype.writeBodyPrField = function (patch) {
+        if (this.encodingValue === 'vml') {
+            throw new DocxError('content/invalid-shape', 'VML leaves do not carry wps:bodyPr; convert to DrawingML to model text body properties');
+        }
+        this.bodyPrValue = patch;
+        this.bodyPrModeled = true;
+        this.markStructureDirty();
+    };
+    Object.defineProperty(DrawingShape.prototype, "verticalAnchor", {
+        /**
+         * Text anchor inside the shape (`wps:bodyPr/@anchor`,
+         * `ST_TextAnchoringType`: `t|ctr|b|just|dist`). `undefined` = attribute
+         * absent (Word default `t`).
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @private
+         */
+        get: function () {
+            return this.readBodyPrState().verticalAnchor;
+        },
+        /**
+        * Text anchor inside the shape (`wps:bodyPr/@anchor`,
+        * `ST_TextAnchoringType`: `t|ctr|b|just|dist`). `undefined` = attribute
+        * absent (Word default `t`).
+        *
+        * @throws DocxError `content/invalid-shape` on a VML leaf.
+        *
+        * @private
+        */
+        set: function (value) {
+            var current = this.readBodyPrState();
+            this.writeBodyPrField(__assign({}, current, { verticalAnchor: value }));
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "anchorCenter", {
+        /**
+         * Center anchoring (`wps:bodyPr/@anchorCtr`). `undefined` = attribute absent.
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @private
+         */
+        get: function () {
+            return this.readBodyPrState().anchorCenter;
+        },
+        /**
+         * Center anchoring (`wps:bodyPr/@anchorCtr`). `undefined` = attribute absent.
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @private
+         */
+        set: function (value) {
+            var current = this.readBodyPrState();
+            this.writeBodyPrField(__assign({}, current, { anchorCenter: value }));
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "textDirection", {
+        /**
+         * Vertical text type (`wps:bodyPr/@vert`, `ST_TextVerticalType`).
+         * `undefined` = attribute absent (horizontal).
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @public
+         */
+        get: function () {
+            return this.readBodyPrState().textDirection;
+        },
+        set: function (value) {
+            var current = this.readBodyPrState();
+            this.writeBodyPrField(__assign({}, current, { textDirection: value }));
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "textWrapInside", {
+        /**
+         * Text wrap inside the shape (`wps:bodyPr/@wrap`,
+         * `ST_TextWrappingType`: `none|square` only per schema).
+         * `undefined` = attribute absent (square).
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @private
+         */
+        get: function () {
+            return this.readBodyPrState().textWrapInside;
+        },
+        /**
+         * Text wrap inside the shape (`wps:bodyPr/@wrap`,
+         * `ST_TextWrappingType`: `none|square` only per schema).
+         * `undefined` = attribute absent (square).
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @private
+         */
+        set: function (value) {
+            var current = this.readBodyPrState();
+            this.writeBodyPrField(__assign({}, current, { textWrapInside: value }));
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "verticalOverflow", {
+        /**
+         * Vertical text overflow (`wps:bodyPr/@vertOverflow`,
+         * `ST_TextVertOverflowType`). `undefined` = attribute absent.
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @private
+         */
+        get: function () {
+            return this.readBodyPrState().verticalOverflow;
+        },
+        /**
+         * Vertical text overflow (`wps:bodyPr/@vertOverflow`,
+         * `ST_TextVertOverflowType`). `undefined` = attribute absent.
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @private
+         */
+        set: function (value) {
+            var current = this.readBodyPrState();
+            this.writeBodyPrField(__assign({}, current, { verticalOverflow: value }));
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "horizontalOverflow", {
+        /**
+         * Horizontal text overflow (`wps:bodyPr/@horzOverflow`,
+         * `ST_TextHorzOverflowType`). `undefined` = attribute absent.
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @private
+         */
+        get: function () {
+            return this.readBodyPrState().horizontalOverflow;
+        },
+        /**
+         * Horizontal text overflow (`wps:bodyPr/@horzOverflow`,
+         * `ST_TextHorzOverflowType`). `undefined` = attribute absent.
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @private
+         */
+        set: function (value) {
+            var current = this.readBodyPrState();
+            this.writeBodyPrField(__assign({}, current, { horizontalOverflow: value }));
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "fromWordArt", {
+        /**
+         * WordArt source flag (`wps:bodyPr/@fromWordArt`). `undefined` = absent.
+         * Flag only — no WordArt pipeline (GO).
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @private
+         */
+        get: function () {
+            return this.readBodyPrState().fromWordArt;
+        },
+        /**
+         * WordArt source flag (`wps:bodyPr/@fromWordArt`). `undefined` = absent.
+         * Flag only — no WordArt pipeline (GO).
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @private
+         */
+        set: function (value) {
+            var current = this.readBodyPrState();
+            this.writeBodyPrField(__assign({}, current, { fromWordArt: value }));
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "insets", {
+        /**
+         * Text insets (`wps:bodyPr/@lIns|tIns|rIns|bIns`, `ST_Coordinate32` EMU).
+         * Non-negative EMU `Point`; `undefined` per side = attribute absent
+         * (Word default 91440/45720/91440/45720). Absent insets object = no
+         * inset attribute modeled.
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @private
+         */
+        get: function () {
+            return this.readBodyPrState().insets;
+        },
+        /**
+         * Text insets (`wps:bodyPr/@lIns|tIns|rIns|bIns`, `ST_Coordinate32` EMU).
+         * Non-negative EMU `Point`; `undefined` per side = attribute absent
+         * (Word default 91440/45720/91440/45720). Absent insets object = no
+         * inset attribute modeled.
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @private
+         */
+        set: function (value) {
+            var current = this.readBodyPrState();
+            this.writeBodyPrField(__assign({}, current, { insets: value }));
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "autoFit", {
+        /**
+         * Autofit choice (`wps:bodyPr` child: `a:noAutofit` | `a:normAutofit` |
+         * `a:spAutoFit`, `EG_TextAutofit`). `undefined` = no autofit child
+         * (Word default noAutofit). Residual `a:prstTxWarp` / 3D / extLst stay
+         * residual — setting any bodyPr field rebuilds bodyPr without them
+         * (residual flag on read documents what was dropped).
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @private
+         */
+        get: function () {
+            return this.readBodyPrState().autoFit;
+        },
+        /**
+         * Text insets (`wps:bodyPr/@lIns|tIns|rIns|bIns`, `ST_Coordinate32` EMU).
+         * Non-negative EMU `Point`; `undefined` per side = attribute absent
+         * (Word default 91440/45720/91440/45720). Absent insets object = no
+         * inset attribute modeled.
+         *
+         * @throws DocxError `content/invalid-shape` on a VML leaf.
+         *
+         * @private
+         */
+        set: function (value) {
+            var current = this.readBodyPrState();
+            this.writeBodyPrField(__assign({}, current, { autoFit: value }));
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "bodyPrResidual", {
+        /**
+         * Whether residual `wps:bodyPr` carries unmodeled content (`a:prstTxWarp`,
+         * 3D children, `extLst`, unknown attributes). Read-only; mutating any
+         * bodyPr field rebuilds `wps:bodyPr` from modeled state and drops the
+         * residual children (documented in the mapping).
+         *
+         * @private
+         */
+        get: function () {
+            if (this.encodingValue === 'vml') {
+                return false;
+            }
+            return this.readBodyPrState().residual;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "hasPresetTextWarp", {
+        /**
+         * Whether the residual bodyPr has WordArt warp (`a:prstTxWarp` child).
+         * Read-only flag — warp is not modeled (never invented).
+         *
+         * @private
+         */
+        get: function () {
+            if (this.encodingValue === 'vml') {
+                return false;
+            }
+            return this.readBodyPrState().hasPresetTextWarp;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(DrawingShape.prototype, "blocks", {
+        /**
+         * Modeled blocks inside `w:txbxContent` (GO Q6). Public consumers use
+         * {@link Shape.items} / {@link Shape.insertBodyItemAt}.
+         * Projects internal {@link BlockContent} store via body-item adapters.
+         *
+         * @private
+         */
+        get: function () {
+            this.requireTextBox();
+            return this.textBody.items.toArray();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Insert a body item at `index` in the text box block list.
+     * Public consumers use {@link Shape.insertBodyItemAt}.
+     *
+     * @private
+     */
+    DrawingShape.prototype.insertBodyItemAt = function (index, item) {
+        this.requireTextBox();
+        return this.textBody.items.insert(index, item);
+    };
+    /**
+     * Remove the body item at `index` in the text box block list.
+     * Public consumers use {@link Shape.removeBodyItemAt}.
+     *
+     * @private
+     */
+    DrawingShape.prototype.removeBodyItemAt = function (index) {
+        this.requireTextBox();
+        this.textBody.items.removeAt(index);
+    };
+    /**
+     * Remove a body item from the text box block list by projected identity.
+     * Public consumers use {@link Shape.removeBodyItem}.
+     *
+     * @private
+     */
+    DrawingShape.prototype.removeBodyItem = function (item) {
+        this.requireTextBox();
+        this.textBody.items.remove(item);
+    };
+    /**
+     * @private
+     * Txbx block store for TextBoxParagraphOwner attach checks.
+     */
+    DrawingShape.prototype.internalBlocks = function () {
+        if (this.textBodyValue !== undefined) {
+            return this.textBodyValue.rawBlocks();
+        }
+        if (this.txbxState !== undefined) {
+            return this.txbxState.blocks;
+        }
+        return this.readTxbxState().blocks;
+    };
+    /**
+     * @private
+     * Owning document for textbox body paragraphs. Resolves through
+     * the anchoring paragraph when bound; throws detached otherwise.
+     */
+    DrawingShape.prototype.internalOwningDocument = function () {
+        var paragraph = this.anchoringParagraph;
+        if (paragraph !== undefined) {
+            return paragraph.owningDocument();
+        }
+        throw new DetachedObjectError('This drawing shape is not attached to a document paragraph');
+    };
+    /**
+     * @private
+   * Bind the anchoring paragraph for textbox owner document resolution. */
+    /** @private */
+    /** Anchoring paragraph accessor; package-visible for GroupShape reparenting. @private */
+    DrawingShape.prototype.getAnchoringParagraph = function () {
+        return this.anchoringParagraph;
+    };
+    DrawingShape.prototype.bindAnchoringParagraph = function (paragraph) {
+        this.anchoringParagraph = paragraph;
+    };
+    /**
+     * Relationship ids referenced by `r:embed` or `r:link` in the preserved subtree.
+     *
+     * @private
+     */
+    DrawingShape.prototype.relationshipIds = function () {
+        return collectRelationshipIds(this.residual);
+    };
+    /**
+     * @private
+     */
+    DrawingShape.prototype.toOpenXml = function () {
+        // Text box body serialization precedence (TASK-8049): once the txbx block
+        // state was materialized, the DOM owns `w:txbxContent` on every path —
+        // nested table-cell/SDT mutations serialize even when the host stays
+        // clean. The host shell is preserved (clone + txbxContent replacement on
+        // clean/identity/layout; full dual-AC rebuild only on structure), so
+        // unmodified bodies round-trip byte-stable (modeled paragraph
+        // serialization is the same byte-stable path as the document body).
+        if (this.txbxState !== undefined && this.encodingValue !== 'vml') {
+            var state = this.readTxbxState();
+            if (this.dirtyMode === 'clean') {
+                var host = this.replaceTxbxContentInResidual(cloneResidualElement(this.residual), state);
+                if (this.hasDirtyNestedChildren()) {
+                    host = this.rewriteResidualNestedChildren(host);
+                }
+                return host;
+            }
+            if (this.dirtyMode === 'identity') {
+                var patchedIdentity = isNestedDrawingResidual(this.residual)
+                    ? patchResidualCNvPr(cloneResidualElement(this.residual), {
+                        name: this.nameValue,
+                        title: this.titleValue,
+                        description: this.descriptionValue,
+                        docPrId: this.docPrIdValue,
+                    })
+                    : patchResidualDocPr(cloneResidualElement(this.residual), {
+                        name: this.nameValue,
+                        title: this.titleValue,
+                        description: this.descriptionValue,
+                        docPrId: this.docPrIdValue,
+                    });
+                var host = this.replaceTxbxContentInResidual(patchedIdentity, state);
+                if (this.hasDirtyNestedChildren()) {
+                    host = this.rewriteResidualNestedChildren(host);
+                }
+                return host;
+            }
+            if (this.dirtyMode === 'layout') {
+                if (this.widthValue === undefined || this.heightValue === undefined) {
+                    throw new DocxError('content/invalid-shape', 'Layout-dirty drawing shape is missing width or height');
+                }
+                var widthEmu_1 = pointToEmus(this.widthValue);
+                var heightEmu_1 = pointToEmus(this.heightValue);
+                var host = patchResidualLayout(this.residual, {
+                    widthEmu: widthEmu_1,
+                    heightEmu: heightEmu_1,
+                    rotation: this.rotationValue != null ? this.rotationValue : 0,
+                    flipHorizontal: this.flipHorizontalValue != null ? this.flipHorizontalValue : false,
+                    flipVertical: this.flipVerticalValue != null ? this.flipVerticalValue : false,
+                    lockAspectRatio: this.lockAspectRatioValue != null ? this.lockAspectRatioValue : false,
+                    name: this.nameValue,
+                    title: this.titleValue,
+                    description: this.descriptionValue,
+                    docPrId: this.docPrIdValue,
+                });
+                // DOM owns w:txbxContent once materialized — layout must not drop body edits.
+                host = this.replaceTxbxContentInResidual(host, state);
+                if (this.hasDirtyNestedChildren()) {
+                    host = this.rewriteResidualNestedChildren(host);
+                }
+                return host;
+            }
+            // structure — falls through to the full rebuild below.
+        }
+        if (this.dirtyMode === 'clean') {
+            // Parent group/canvas may stay clean while a nested child is dirty
+            // (e.g. ChildA rename). Rewrite nested wsp/grpSp in-place, preserving
+            // residual grpSpPr and unknown siblings (TASK-8051).
+            if (this.hasDirtyNestedChildren()) {
+                return this.rewriteResidualNestedChildren(cloneResidualElement(this.residual));
+            }
+            return this.residual;
+        }
+        if (this.dirtyMode === 'identity') {
+            var identity = {
+                name: this.nameValue,
+                title: this.titleValue,
+                description: this.descriptionValue,
+                docPrId: this.docPrIdValue,
+            };
+            var host = isNestedDrawingResidual(this.residual)
+                ? patchResidualCNvPr(this.residual, identity)
+                : patchResidualDocPr(this.residual, identity);
+            if (this.hasDirtyNestedChildren()) {
+                host = this.rewriteResidualNestedChildren(host === this.residual ? cloneResidualElement(this.residual) : host);
+            }
+            return host;
+        }
+        if (this.dirtyMode === 'layout') {
+            if (this.widthValue === undefined || this.heightValue === undefined) {
+                throw new DocxError('content/invalid-shape', 'Layout-dirty drawing shape is missing width or height');
+            }
+            var widthEmu_2 = pointToEmus(this.widthValue);
+            var heightEmu_2 = pointToEmus(this.heightValue);
+            var host = patchResidualLayout(this.residual, {
+                widthEmu: widthEmu_2,
+                heightEmu: heightEmu_2,
+                rotation: this.rotationValue != null ? this.rotationValue : 0,
+                flipHorizontal: this.flipHorizontalValue != null ? this.flipHorizontalValue : false,
+                flipVertical: this.flipVerticalValue != null ? this.flipVerticalValue : false,
+                lockAspectRatio: this.lockAspectRatioValue != null ? this.lockAspectRatioValue : false,
+                name: this.nameValue,
+                title: this.titleValue,
+                description: this.descriptionValue,
+                docPrId: this.docPrIdValue,
+            });
+            if (this.hasDirtyNestedChildren()) {
+                host = this.rewriteResidualNestedChildren(host);
+            }
+            return host;
+        }
+        // structure — dual AC author / rebuild (host kind / wrap / geometry / group)
+        var placement = this.placementValue != null ? this.placementValue : 'anchor';
+        var widthEmu = this.widthValue === undefined ? undefined : pointToEmus(this.widthValue);
+        var heightEmu = this.heightValue === undefined ? undefined : pointToEmus(this.heightValue);
+        // Coordinates/distances may be 0; do not wrap with emus() (positive-only).
+        var distanceTopEmu = this.distanceTopValue === undefined ? undefined : pointToCoordinateEmus(this.distanceTopValue);
+        var distanceBottomEmu = this.distanceBottomValue === undefined ? undefined : pointToCoordinateEmus(this.distanceBottomValue);
+        var distanceLeftEmu = this.distanceLeftValue === undefined ? undefined : pointToCoordinateEmus(this.distanceLeftValue);
+        var distanceRightEmu = this.distanceRightValue === undefined ? undefined : pointToCoordinateEmus(this.distanceRightValue);
+        var horizontalPositionEmu = this.horizontalPositionValue === undefined ? undefined : pointToCoordinateEmus(this.horizontalPositionValue);
+        var verticalPositionEmu = this.verticalPositionValue === undefined ? undefined : pointToCoordinateEmus(this.verticalPositionValue);
+        var docPrId = this.docPrIdValue != null ? this.docPrIdValue : 1;
+        var wrapping = this.wrappingValue != null ? this.wrappingValue : (placement === 'inline' ? TextWrappingStyle.Inline : TextWrappingStyle.None);
+        // TASK-8051: group/canvas structure encode (empty children OK). Must run
+        // before the leaf presetGeometry required check.
+        var variant = this.variant();
+        var isGroupOrCanvasHost = this.childrenModeled || variant === 'group' || variant === 'canvas';
+        if (isGroupOrCanvasHost) {
+            if (widthEmu === undefined || heightEmu === undefined) {
+                throw new DocxError('content/invalid-shape', 'Authored drawing group is missing width or height');
+            }
+            this.ensureChildrenModeled();
+            var childElements = this.childrenValue.map(function (child) { return child.toOpenXml(); });
+            return encodeAuthoredGroup(encodeGroupInput({
+                placement: placement,
+                widthEmu: widthEmu,
+                heightEmu: heightEmu,
+                docPrId: docPrId,
+                name: this.nameValue != null ? this.nameValue : 'Group',
+                title: this.titleValue,
+                description: this.descriptionValue,
+                rotation: this.rotationValue != null ? this.rotationValue : 0,
+                flipHorizontal: this.flipHorizontalValue != null ? this.flipHorizontalValue : false,
+                flipVertical: this.flipVerticalValue != null ? this.flipVerticalValue : false,
+                lockAspectRatio: this.lockAspectRatioValue != null ? this.lockAspectRatioValue : true,
+                wrapping: wrapping,
+                distanceTopEmu: distanceTopEmu,
+                distanceBottomEmu: distanceBottomEmu,
+                distanceLeftEmu: distanceLeftEmu,
+                distanceRightEmu: distanceRightEmu,
+                behindDocument: this.behindDocumentValue,
+                horizontalOrigin: this.horizontalOriginValue,
+                verticalOrigin: this.verticalOriginValue,
+                horizontalPositionEmu: horizontalPositionEmu,
+                verticalPositionEmu: verticalPositionEmu,
+                horizontalAlignment: this.horizontalAlignmentValue,
+                verticalAlignment: this.verticalAlignmentValue,
+                horizontalModeled: this.horizontalModeled,
+                verticalModeled: this.verticalModeled,
+                lockAnchor: this.lockAnchorValue,
+                allowOverlap: this.allowOverlapValue,
+                layoutInCell: this.layoutInCellValue,
+                preservedHost: this.residual,
+                layoutDirty: true,
+                children: childElements,
+            }));
+        }
+        // TASK-8051: nested bare wsp structure rebuild (no second drawing host).
+        if (isNestedDrawingResidual(this.residual)) {
+            if (widthEmu === undefined || heightEmu === undefined) {
+                throw new DocxError('content/invalid-shape', 'Authored nested drawing shape is missing width or height');
+            }
+            var presetGeometryNested = this.presetGeometryValue;
+            if (presetGeometryNested === undefined) {
+                throw new DocxError('content/invalid-shape', 'Authored nested drawing shape is missing presetGeometry');
+            }
+            var txbxContentNested = void 0;
+            if (this.txbxState !== undefined || this.txbxBodyModeled) {
+                var state = this.readTxbxState();
+                txbxContentNested = serializeTxbxContentBlocks(state.blocks.length > 0 ? state.blocks : emptyTxbxParagraphBlocks());
+            }
+            var bodyPrNested = this.bodyPrModeled
+                ? buildBodyPrElement(this.bodyPrValue != null ? this.bodyPrValue : {})
+                : undefined;
+            var encodeFillNested = this.fillModeled
+                ? modeledFillForEncode(this.fillValue)
+                : undefined;
+            var encodeLineNested = this.lineModeled
+                ? modeledLineForEncode(this.lineValue)
+                : undefined;
+            return buildNestedWpsShape({
+                placement: 'anchor',
+                widthEmu: widthEmu,
+                heightEmu: heightEmu,
+                presetGeometry: presetGeometryNested,
+                docPrId: docPrId,
+                name: this.nameValue != null ? this.nameValue : 'Shape',
+                title: this.titleValue,
+                description: this.descriptionValue,
+                rotation: this.rotationValue != null ? this.rotationValue : 0,
+                flipHorizontal: this.flipHorizontalValue != null ? this.flipHorizontalValue : false,
+                flipVertical: this.flipVerticalValue != null ? this.flipVerticalValue : false,
+                lockAspectRatio: this.lockAspectRatioValue != null ? this.lockAspectRatioValue : true,
+                txbxContent: txbxContentNested,
+                bodyPr: bodyPrNested,
+                fill: encodeFillNested,
+                line: encodeLineNested,
+            });
+        }
+        var presetGeometry = this.presetGeometryValue;
+        if (widthEmu === undefined || heightEmu === undefined || presetGeometry === undefined) {
+            throw new DocxError('content/invalid-shape', 'Authored drawing shape is missing size or presetGeometry');
+        }
+        // TASK-8049: text box body + bodyPr encode. The body is rebuilt from the
+        // typed block state whenever it was materialized (any body access —
+        // top-level or nested inside a table/SDT) or explicitly modeled; nested
+        // mutations serialize because the materialized blocks reference the same
+        // live Paragraph/Table/SDT objects. When the body was never accessed, the
+        // residual txbx is cloned verbatim (structure dirt from layout/wrap
+        // mutators must not drop textbox content). bodyPr emits when modeled.
+        var txbxContent;
+        if (this.txbxState !== undefined || this.txbxBodyModeled) {
+            var state = this.readTxbxState();
+            txbxContent = serializeTxbxContentBlocks(state.blocks.length > 0 ? state.blocks : emptyTxbxParagraphBlocks());
+        }
+        var bodyPrElement = this.bodyPrModeled
+            ? buildBodyPrElement(this.bodyPrValue != null ? this.bodyPrValue : {})
+            : undefined;
+        return encodeAuthoredDrawingShape(encodeDrawingShapeInput({
+            placement: placement,
+            widthEmu: widthEmu,
+            heightEmu: heightEmu,
+            presetGeometry: presetGeometry,
+            docPrId: docPrId,
+            name: this.nameValue != null ? this.nameValue : 'Shape',
+            title: this.titleValue,
+            description: this.descriptionValue,
+            rotation: this.rotationValue != null ? this.rotationValue : 0,
+            flipHorizontal: this.flipHorizontalValue != null ? this.flipHorizontalValue : false,
+            flipVertical: this.flipVerticalValue != null ? this.flipVerticalValue : false,
+            lockAspectRatio: this.lockAspectRatioValue != null ? this.lockAspectRatioValue : true,
+            wrapping: wrapping,
+            wrapType: this.readWrapType(),
+            distanceTopEmu: distanceTopEmu,
+            distanceBottomEmu: distanceBottomEmu,
+            distanceLeftEmu: distanceLeftEmu,
+            distanceRightEmu: distanceRightEmu,
+            behindDocument: this.behindDocumentValue,
+            horizontalOrigin: this.horizontalOriginValue,
+            verticalOrigin: this.verticalOriginValue,
+            horizontalPositionEmu: horizontalPositionEmu,
+            verticalPositionEmu: verticalPositionEmu,
+            horizontalAlignment: this.horizontalAlignmentValue,
+            verticalAlignment: this.verticalAlignmentValue,
+            horizontalModeled: this.horizontalModeled,
+            verticalModeled: this.verticalModeled,
+            lockAnchor: this.lockAnchorValue,
+            allowOverlap: this.allowOverlapValue,
+            layoutInCell: this.layoutInCellValue,
+            preservedHost: this.residual,
+            layoutDirty: true,
+            txbxContent: txbxContent,
+            bodyPr: bodyPrElement,
+            fill: this.fillModeled ? modeledFillForEncode(this.fillValue) : undefined,
+            line: this.lineModeled ? modeledLineForEncode(this.lineValue) : undefined,
+        }));
+    };
+    /**
+     * Replace the materialized `w:txbxContent` inside a cloned residual host
+     * (identity / layout dirty paths keep everything else verbatim).
+     */
+    DrawingShape.prototype.replaceTxbxContentInResidual = function (host, state) {
+        var txbxContentHost = findTxbxElement(host);
+        if (txbxContentHost === undefined) {
+            return host;
+        }
+        var txbxContent = serializeTxbxContentBlocks(state.blocks.length > 0 ? state.blocks : emptyTxbxParagraphBlocks());
+        // Replace the w:txbxContent child of the cloned wps:txbx (attributes
+        // — e.g. @id for linked-box pairs — and linkedTxbx siblings stay).
+        var children = txbxContentHost.children.filter(function (c) { return !(c.kind === 'element' && c.localName === 'txbxContent'); });
+        txbxContentHost.children = __spread(children, [
+            (function () {
+                var el = wmlElement('txbxContent', { children: txbxContent });
+                return el;
+            })(),
+        ]);
+        return host;
+    };
+    DrawingShape.prototype.drawingRoot = function () {
+        var __ts33_0;
+        return ((__ts33_0 = preferredDrawingElement(this.residual)), __ts33_0 != null ? __ts33_0 : (isWml(this.residual, 'drawing') ? this.residual : undefined));
+    };
+    DrawingShape.prototype.markIdentityDirty = function () {
+        if (this.dirtyMode === 'structure' || this.dirtyMode === 'layout') {
+            this.notifyParentOfChildDirty();
+            return;
+        }
+        if (this.dirtyMode === 'clean') {
+            var identity = this.readResidualIdentity();
+            if (this.nameValue === undefined) {
+                this.nameValue = identity.name;
+            }
+            if (this.titleValue === undefined) {
+                this.titleValue = identity.title;
+            }
+            if (this.descriptionValue === undefined) {
+                this.descriptionValue = identity.description;
+            }
+            if (this.docPrIdValue === undefined) {
+                this.docPrIdValue = identity.docPrId;
+            }
+        }
+        this.dirtyMode = 'identity';
+        this.notifyParentOfChildDirty();
+    };
+    /**
+     * Promote to layout dirty. Never demotes `structure`.
+     * Hydrates size/transform/lock from residual when leaving `clean`/`identity`.
+     */
+    DrawingShape.prototype.markLayoutDirty = function () {
+        if (this.dirtyMode === 'structure') {
+            this.notifyParentOfChildDirty();
+            return;
+        }
+        if (this.dirtyMode === 'clean' || this.dirtyMode === 'identity') {
+            this.hydrateIdentityAndLayoutFromResidual();
+        }
+        this.dirtyMode = 'layout';
+        this.notifyParentOfChildDirty();
+    };
+    /**
+     * Promote the leaf to a textBox variant (`wps:txbx` modeled).
+     * Never demotes; idempotent once set.
+     * @private
+     */
+    DrawingShape.prototype.markTxbxBodyModeled = function () {
+        this.txbxBodyModeled = true;
+    };
+    /**
+     * Promote to structure dirty (host kind / wrap / distances / behindDoc).
+     * Never demotes. Hydrates identity, layout, wrap, and presetGeometry from residual.
+     */
+    /** Promote dirty mode to structure; package-visible for GroupShape. @private */
+    DrawingShape.prototype.markStructureDirty = function () {
+        if (this.dirtyMode !== 'structure') {
+            this.hydrateIdentityAndLayoutFromResidual();
+            if (this.encodingValue !== 'vml') {
+                var wrap = readDrawingWrapState(this.residual);
+                if (this.placementValue === undefined) {
+                    this.placementValue = wrap.placement;
+                }
+                if (this.wrappingValue === undefined) {
+                    this.wrappingValue = wrap.wrapping;
+                }
+                if (!this.distancesModeled) {
+                    if (this.distanceTopValue === undefined && wrap.distanceTopEmu !== undefined) {
+                        this.distanceTopValue = emuToPoint(wrap.distanceTopEmu);
+                    }
+                    if (this.distanceBottomValue === undefined && wrap.distanceBottomEmu !== undefined) {
+                        this.distanceBottomValue = emuToPoint(wrap.distanceBottomEmu);
+                    }
+                    if (this.distanceLeftValue === undefined && wrap.distanceLeftEmu !== undefined) {
+                        this.distanceLeftValue = emuToPoint(wrap.distanceLeftEmu);
+                    }
+                    if (this.distanceRightValue === undefined && wrap.distanceRightEmu !== undefined) {
+                        this.distanceRightValue = emuToPoint(wrap.distanceRightEmu);
+                    }
+                }
+                if (!this.behindDocumentModeled && this.behindDocumentValue === undefined) {
+                    this.behindDocumentValue = wrap.behindDocument;
+                }
+                if (this.presetGeometryValue === undefined) {
+                    this.presetGeometryValue = wrap.presetGeometry;
+                }
+                // Hydrate position values and anchor booleans from residual so structure
+                // encode never invents tokens or silently flips residual option values.
+                // Hydration fills missing fields on BOTH axes regardless of the per-axis
+                // modeled flags — the flags only decide whether an axis is rebuilt from
+                // model or preserved verbatim on the wire (host-codec).
+                var position = readDrawingPositionState(this.residual);
+                if (this.horizontalOriginValue === undefined) {
+                    this.horizontalOriginValue = position.horizontalOrigin;
+                }
+                if (this.horizontalPositionValue === undefined && position.horizontalPositionEmu !== undefined) {
+                    this.horizontalPositionValue = emuToPoint(position.horizontalPositionEmu);
+                }
+                if (this.horizontalAlignmentValue === undefined) {
+                    this.horizontalAlignmentValue = position.horizontalAlignment;
+                }
+                if (this.verticalOriginValue === undefined) {
+                    this.verticalOriginValue = position.verticalOrigin;
+                }
+                if (this.verticalPositionValue === undefined && position.verticalPositionEmu !== undefined) {
+                    this.verticalPositionValue = emuToPoint(position.verticalPositionEmu);
+                }
+                if (this.verticalAlignmentValue === undefined) {
+                    this.verticalAlignmentValue = position.verticalAlignment;
+                }
+                if (this.lockAnchorValue === undefined) {
+                    this.lockAnchorValue = wrap.lockAnchor;
+                }
+                if (this.allowOverlapValue === undefined) {
+                    this.allowOverlapValue = wrap.allowOverlap;
+                }
+                if (this.layoutInCellValue === undefined) {
+                    this.layoutInCellValue = wrap.layoutInCell;
+                }
+            }
+            // Always invalidate cached residual spPr reads when structure dirtied —
+            // including when already structure (geometry/fill/line mutators).
+            this.spPrState = undefined;
+        }
+        // Re-reads of bodyPr residual after a modeled write must reflect the
+        // modeled state, not the stale residual — only clear the residual-derived
+        // cache when bodyPr was not modeled here.
+        if (!this.bodyPrModeled) {
+            this.bodyPrValue = undefined;
+        }
+        this.dirtyMode = 'structure';
+        this.notifyParentOfChildDirty();
+    };
+    DrawingShape.prototype.hydrateIdentityAndLayoutFromResidual = function () {
+        var identity = this.readResidualIdentity();
+        if (this.nameValue === undefined) {
+            this.nameValue = identity.name;
+        }
+        if (this.titleValue === undefined) {
+            this.titleValue = identity.title;
+        }
+        if (this.descriptionValue === undefined) {
+            this.descriptionValue = identity.description;
+        }
+        if (this.docPrIdValue === undefined) {
+            this.docPrIdValue = identity.docPrId;
+        }
+        if (this.encodingValue !== 'vml') {
+            var layout = readDrawingLayout(this.residual);
+            if (this.widthValue === undefined && layout.widthEmu !== undefined) {
+                this.widthValue = emuToPoint(layout.widthEmu);
+            }
+            if (this.heightValue === undefined && layout.heightEmu !== undefined) {
+                this.heightValue = emuToPoint(layout.heightEmu);
+            }
+            if (this.rotationValue === undefined) {
+                this.rotationValue = layout.rotation;
+            }
+            if (this.flipHorizontalValue === undefined) {
+                this.flipHorizontalValue = layout.flipHorizontal;
+            }
+            if (this.flipVerticalValue === undefined) {
+                this.flipVerticalValue = layout.flipVertical;
+            }
+            if (this.lockAspectRatioValue === undefined) {
+                this.lockAspectRatioValue = layout.lockAspectRatio;
+            }
+        }
+    };
+    /**
+     * Read identity from nested `wps:cNvPr` / `wpg:cNvPr` when residual is a bare
+     * nested shape/group; otherwise from top-level `wp:docPr`.
+     */
+    DrawingShape.prototype.readResidualIdentity = function () {
+        if (isNestedDrawingResidual(this.residual)) {
+            return readCNvPrIdentity(this.residual);
+        }
+        return readDocPrIdentity(this.residual);
+    };
+    /**
+     * Parse nested `wps:wsp` / `wpg:grpSp` children under residual `wpg:wgp` or
+     * `wpc:wpc` (TASK-8051). Unknown residual siblings are not modeled as children.
+     */
+    DrawingShape.prototype.parseNestedChildrenFromResidual = function () {
+        var e_8, _a;
+        if (this.encodingValue === 'vml') {
+            return [];
+        }
+        var container = findNestedDrawingContainer(this.residual);
+        if (container === undefined) {
+            return [];
+        }
+        var children = [];
+        try {
+            for (var _b = __values(elementChildren(container)), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var childEl = _c.value;
+                if (!isNestedDrawingResidual(childEl)) {
+                    continue;
+                }
+                var child = createDrawingShape('drawingml', childEl);
+                child.parentGroup = this;
+                children.push(child);
+            }
+        }
+        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; }
+        }
+        return children;
+    };
+    /**
+     * Materialize residual or cached children into {@link childrenValue} so nested
+     * authoring can push without dropping lazy residual siblings.
+     */
+    DrawingShape.prototype.ensureChildrenModeled = function () {
+        var e_9, _a;
+        if (this.childrenModeled) {
+            return;
+        }
+        var existing = this.childrenCache !== undefined
+            ? this.childrenCache
+            : this.parseNestedChildrenFromResidual();
+        this.childrenValue = __spread(existing);
+        try {
+            for (var _b = __values(this.childrenValue), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var child = _c.value;
+                child.parentGroup = this;
+            }
+        }
+        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; }
+        }
+        this.childrenModeled = true;
+        this.childrenCache = undefined;
+    };
+    /**
+     * Allocate a package-unique cNvPr/docPr id for a nested child using the
+     * top-level host's anchoring paragraph when available.
+     */
+    DrawingShape.prototype.allocateNestedDocPrId = function () {
+        var e_10, _a;
+        var paragraph = this.anchoringParagraph != null ? this.anchoringParagraph : this.parentGroup == null ? undefined : this.parentGroup.anchoringParagraph;
+        if (paragraph !== undefined) {
+            return allocateDocPrId(paragraph);
+        }
+        // Detached authoring path: walk already-modeled descendants only.
+        var max = this.docPrIdValue != null ? this.docPrIdValue : 0;
+        try {
+            for (var _b = __values(this.children()), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var child = _c.value;
+                var id = child.docPrIdValue;
+                if (id !== undefined && id > max) {
+                    max = id;
+                }
+            }
+        }
+        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 max + 1;
+    };
+    /** True when any nested child (direct) is not clean. */
+    DrawingShape.prototype.hasDirtyNestedChildren = function () {
+        var e_11, _a;
+        if (this.encodingValue === 'vml') {
+            return false;
+        }
+        // Avoid infinite recursion via children() cache population while still
+        // detecting dirt on already-modeled children without forcing parse.
+        var kids = this.childrenModeled
+            ? this.childrenValue
+            : this.childrenCache !== undefined
+                ? this.childrenCache
+                : undefined;
+        if (kids === undefined) {
+            return false;
+        }
+        try {
+            for (var kids_1 = __values(kids), kids_1_1 = kids_1.next(); !kids_1_1.done; kids_1_1 = kids_1.next()) {
+                var child = kids_1_1.value;
+                if (child.dirtyMode !== 'clean' || child.hasDirtyNestedChildren()) {
+                    return true;
+                }
+            }
+        }
+        catch (e_11_1) { e_11 = { error: e_11_1 }; }
+        finally {
+            try {
+                if (kids_1_1 && !kids_1_1.done && (_a = kids_1.return)) _a.call(kids_1);
+            }
+            finally { if (e_11) throw e_11.error; }
+        }
+        return false;
+    };
+    /**
+     * Clone residual host and replace nested wsp/grpSp under wgp/wpc with each
+     * child's {@link toOpenXml}, preserving grpSpPr and unknown residual siblings.
+     */
+    DrawingShape.prototype.rewriteResidualNestedChildren = function (host) {
+        var e_12, _a;
+        this.ensureChildrenModeled();
+        var container = findNestedDrawingContainer(host);
+        if (container === undefined) {
+            return host;
+        }
+        var modeled = this.childrenValue;
+        var modelIndex = 0;
+        var nextChildren = [];
+        try {
+            for (var _b = __values(container.children), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var node = _c.value;
+                if (node.kind !== 'element' || !isNestedDrawingResidual(node)) {
+                    nextChildren.push(node);
+                    continue;
+                }
+                var child = modeled[modelIndex];
+                if (child !== undefined) {
+                    nextChildren.push(child.toOpenXml());
+                    modelIndex += 1;
+                }
+                // Extra residual nested shapes beyond modeled list are dropped only when
+                // the model intentionally no longer contains them (structure author path
+                // rebuilds entirely). Preserve-by-model-order for dirty-child rewrite.
+            }
+        }
+        catch (e_12_1) { e_12 = { error: e_12_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_12) throw e_12.error; }
+        }
+        // Append any additional modeled children not matched to residual slots.
+        while (modelIndex < modeled.length) {
+            var child = modeled[modelIndex];
+            if (child === undefined) {
+                break;
+            }
+            nextChildren.push(child.toOpenXml());
+            modelIndex += 1;
+        }
+        container.children = nextChildren;
+        return host;
+    };
+    /**
+     * Nested child dirt must surface on save even when the parent residual stays
+     * clean — notify by ensuring children are modeled (so hasDirtyNestedChildren
+     * can see them). Parent dirtyMode is left alone; toOpenXml rewrites kids.
+     */
+    DrawingShape.prototype.notifyParentOfChildDirty = function () {
+        var parent = this.parentGroup;
+        if (parent === undefined) {
+            return;
+        }
+        parent.ensureChildrenModeled();
+    };
+    DrawingShape.prototype.readDistancePoints = function (side) {
+        var modeled = side === 'top'
+            ? this.distanceTopValue
+            : side === 'bottom'
+                ? this.distanceBottomValue
+                : side === 'left'
+                    ? this.distanceLeftValue
+                    : this.distanceRightValue;
+        if (modeled !== undefined) {
+            return modeled;
+        }
+        if (this.encodingValue === 'vml') {
+            return 0;
+        }
+        var wrap = readDrawingWrapState(this.residual);
+        var residual = side === 'top'
+            ? wrap.distanceTopEmu
+            : side === 'bottom'
+                ? wrap.distanceBottomEmu
+                : side === 'left'
+                    ? wrap.distanceLeftEmu
+                    : wrap.distanceRightEmu;
+        if (residual !== undefined) {
+            return emuToPoint(residual);
+        }
+        var placement = this.placement();
+        if ((side === 'left' || side === 'right') && placement === 'anchor') {
+            return emuToPoint(ANCHOR_DEFAULT_SIDE_DIST_EMU);
+        }
+        return 0;
+    };
+    return DrawingShape;
+}());
+export { DrawingShape };
+/**
+ * Leaf DrawingML / VML shape (preset geometry, fill/line, optional text box).
+ *
+ * Inherits identity, placement, size, wrap, and position format from
+ * {@link DrawingShape}. Text-box body content uses {@link Shape.items}.
+ * Group hosts use {@link GroupShape}.
+ *
+ * @public
+ */
+var Shape = /** @class */ (function (_super) {
+    __extends(Shape, _super);
+    /**
+     * @private
+     */
+    function Shape(encodingOrInit, element) {
+        var _this = 
+        // Base constructor validates `element` for the string-encoding overload
+        // (throws when undefined); super() must remain the first statement here
+        // because this class has initialized properties (TS2376).
+        _super.call(this, encodingOrInit, element) || this;
+        /**
+         * Public discriminant for {@link Paragraph.items} ({@link EntityType.Shape}).
+         * @public
+         */
+        _this.type = EntityType.Shape;
+        return _this;
+    }
+    Object.defineProperty(Shape.prototype, "items", {
+        /**
+         * Ordered text-box body children ({@link BodyItem}) — paragraphs, tables,
+         * block content controls, and residual-opaque blocks in document order.
+         *
+         * Requires a text-box variant (`wps:txbx`). Mutate only through
+         * {@link insertBodyItemAt}, {@link removeBodyItemAt}, and {@link removeBodyItem}.
+         *
+         * @throws DocxError `content/invalid-shape` when the shape is not a text box.
+         *
+         * @public
+         */
+        get: function () {
+            return this.blocks;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Inserts a body item at `index` in {@link Shape.items}
+     * (`0…length` inclusive — insert-before / append).
+     *
+     * Attaches paragraphs and binds feature blocks to the owning document.
+     * Returns the same `item` reference for chaining (API-RULES R1.1).
+     *
+     * @param index - Index in {@link Shape.items}.
+     * @param item - Paragraph, feature, or opaque body child.
+     * @returns The inserted {@link BodyItem}.
+     * @throws RangeError if `index` is out of range.
+     * @throws DocxError `content/invalid-shape` when the shape is not a text box.
+     *
+     * @public
+     */
+    Shape.prototype.insertBodyItemAt = function (index, item) {
+        return _super.prototype.insertBodyItemAt.call(this, index, item);
+    };
+    /**
+     * Removes the body item at `index` in {@link Shape.items}
+     * (`0…length-1`). Paragraphs detach; feature blocks may release content.
+     *
+     * @param index - Index in {@link Shape.items}.
+     * @throws RangeError if `index` is out of range.
+     * @throws DocxError `content/invalid-shape` when the shape is not a text box.
+     *
+     * @public
+     */
+    Shape.prototype.removeBodyItemAt = function (index) {
+        _super.prototype.removeBodyItemAt.call(this, index);
+    };
+    /**
+     * Removes a body item from {@link Shape.items}.
+     *
+     * Matches by collection entry identity first, then by payload identity
+     * (same {@link Paragraph}, feature value, or opaque XML node).
+     *
+     * @param item - Entry from `items`, or an equivalent payload wrapper.
+     * @throws DetachedObjectError if `item` is not in this text box.
+     * @throws DocxError `content/invalid-shape` when the shape is not a text box.
+     *
+     * @public
+     */
+    Shape.prototype.removeBodyItem = function (item) {
+        _super.prototype.removeBodyItem.call(this, item);
+    };
+    return Shape;
+}(DrawingShape));
+export { Shape };
+/**
+ * DrawingML group or canvas host with nested {@link Shape} / {@link GroupShape}
+ * children (TASK-8051).
+ *
+ * Inherits identity, placement, size, wrap, and position format from
+ * {@link DrawingShape}. Nested children are exposed as {@link childShapes};
+ * author nested leaves with {@link appendShape}.
+ *
+ * @public
+ */
+var GroupShape = /** @class */ (function (_super) {
+    __extends(GroupShape, _super);
+    /**
+     * @private
+     */
+    function GroupShape(encodingOrInit, element) {
+        var _this = 
+        // Base constructor validates `element` for the string-encoding overload
+        // (throws when undefined); super() must remain the first statement here
+        // because this class has initialized properties (TS2376).
+        _super.call(this, encodingOrInit, element) || this;
+        /**
+         * Public discriminant for {@link Paragraph.items} ({@link EntityType.GroupShape}).
+         * @public
+         */
+        _this.type = EntityType.GroupShape;
+        return _this;
+    }
+    Object.defineProperty(GroupShape.prototype, "childShapes", {
+        /**
+         * Nested DrawingML children under this group or canvas, in document order.
+         * @public
+         */
+        get: function () {
+            return this.children();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(GroupShape.prototype, "childItems", {
+        /**
+         * Nested child items (collection surface).
+         * @public
+         */
+        get: function () {
+            return this.children();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Nested DrawingML children under this group or canvas.
+     * @private
+     */
+    GroupShape.prototype.children = function () {
+        return _super.prototype.children.call(this);
+    };
+    /**
+     * Add an existing drawing leaf as a nested child. Detaches from anchoring paragraph when needed.
+     * @public
+     */
+    GroupShape.prototype.add = function (paragraphItem) {
+        var child;
+        if (paragraphItem instanceof DrawingShape) {
+            child = paragraphItem;
+        }
+        else if (paragraphItem instanceof FeatureRunParagraphItem &&
+            paragraphItem.value instanceof DrawingShape) {
+            child = paragraphItem.value;
+        }
+        if (child === undefined) {
+            throw new DocxError('content/invalid-shape', 'GroupShape.add requires a drawing shape paragraph item');
+        }
+        if (child === this) {
+            throw new DocxError('content/invalid-shape', 'GroupShape cannot add itself');
+        }
+        var para = child.getAnchoringParagraph();
+        if (para !== undefined) {
+            var items = para.items.toArray();
+            for (var i = items.length - 1; i >= 0; i -= 1) {
+                var it_1 = items[i];
+                if (it_1 instanceof FeatureRunParagraphItem && it_1.value === child) {
+                    para.removeFeatureRunItem(child);
+                    break;
+                }
+            }
+        }
+        child.parentGroup = this;
+        this.ensureChildrenModeled();
+        this.childrenValue.push(child);
+        this.childrenModeled = true;
+        this.childrenCache = undefined;
+        this.markStructureDirty();
+        this.notifyParentOfChildDirty();
+    };
+    /**
+     * Ungroup children into an array of drawing leaves.
+     * @public
+     */
+    GroupShape.prototype.unGroup = function () {
+        var e_13, _a;
+        var kids = __spread(this.children());
+        this.ensureChildrenModeled();
+        try {
+            for (var kids_2 = __values(kids), kids_2_1 = kids_2.next(); !kids_2_1.done; kids_2_1 = kids_2.next()) {
+                var child = kids_2_1.value;
+                child.parentGroup = undefined;
+            }
+        }
+        catch (e_13_1) { e_13 = { error: e_13_1 }; }
+        finally {
+            try {
+                if (kids_2_1 && !kids_2_1.done && (_a = kids_2.return)) _a.call(kids_2);
+            }
+            finally { if (e_13) throw e_13.error; }
+        }
+        this.childrenValue = [];
+        this.childrenModeled = true;
+        this.childrenCache = undefined;
+        this.markStructureDirty();
+        return kids;
+    };
+    /**
+     * Append a nested preset-geometry {@link Shape} under this group.
+     * @public
+     */
+    GroupShape.prototype.appendShape = function (autoShapeType, width, height) {
+        return _super.prototype.appendShape.call(this, autoShapeType, width, height);
+    };
+    /** @private */
+    GroupShape.prototype.writeShapeFillState = function (_value) {
+        throw new DocxError('content/invalid-shape', 'Fill is not supported on GroupShape');
+    };
+    /** @private */
+    GroupShape.prototype.writeShapeLineState = function (_value) {
+        throw new DocxError('content/invalid-shape', 'Line is not supported on GroupShape');
+    };
+    /** @private */
+    GroupShape.prototype.writeTextFrameDirection = function (_value) {
+        throw new DocxError('content/invalid-shape', 'Text frame is not supported on GroupShape');
+    };
+    /** @private */
+    GroupShape.prototype.writeTextFrameVerticalAlignment = function (_value) {
+        throw new DocxError('content/invalid-shape', 'Text frame is not supported on GroupShape');
+    };
+    /** @private */
+    GroupShape.prototype.ensureTextBodyAccessible = function () {
+        throw new DocxError('content/invalid-shape', 'Text body is not supported on GroupShape');
+    };
+    return GroupShape;
+}(Shape));
+export { GroupShape };
+/**
+ * Construct {@link Shape} or {@link GroupShape} from a residual host element.
+ * Nested `wps:wsp` / `wpg:grpSp` residuals and top-level dual-AC trees are
+ * classified by residual localName / Choice URI (TASK-8051).
+ *
+ * @private
+ */
+export function createDrawingShape(encoding, element) {
+    var __ts33_1;
+    if (encoding === 'vml') {
+        return new Shape(encoding, element);
+    }
+    if (isNestedDrawingResidual(element)) {
+        if (element.localName === 'grpSp') {
+            return new GroupShape(encoding, element);
+        }
+        return new Shape(encoding, element);
+    }
+    var drawing = ((__ts33_1 = preferredDrawingElement(element)), __ts33_1 != null ? __ts33_1 : (isWml(element, 'drawing') ? element : undefined));
+    if (drawing !== undefined) {
+        var fromUri = detectDmlVariant(drawing);
+        if (fromUri === 'group' || fromUri === 'canvas') {
+            return new GroupShape(encoding, element);
+        }
+    }
+    // Unknown / picture-declined / bare fragments still surface as Shape leaves so
+    // residual pass-through and identity APIs remain available.
+    return new Shape(encoding, element);
+}
+/**
+ * Construct {@link Shape} or {@link GroupShape} from an authored / modeled init.
+ * Modeled `children` (including `[]`) always yields {@link GroupShape}.
+ *
+ * @private
+ */
+export function createDrawingShapeFromInit(init) {
+    var __ts33_2;
+    if (init.children !== undefined) {
+        return new GroupShape(init);
+    }
+    if (init.encoding === 'vml') {
+        return new Shape(init);
+    }
+    if (isNestedDrawingResidual(init.residual)) {
+        if (init.residual.localName === 'grpSp') {
+            return new GroupShape(init);
+        }
+        return new Shape(init);
+    }
+    var drawing = ((__ts33_2 = preferredDrawingElement(init.residual)), __ts33_2 != null ? __ts33_2 : (isWml(init.residual, 'drawing') ? init.residual : undefined));
+    if (drawing !== undefined) {
+        var fromUri = detectDmlVariant(drawing);
+        if (fromUri === 'group' || fromUri === 'canvas') {
+            return new GroupShape(init);
+        }
+    }
+    return new Shape(init);
+}
+/**
+ * Type guard for leaf {@link Shape} instances (not group/canvas hosts).
+ *
+ * @private
+ */
+export function isShape(value) {
+    return value instanceof Shape;
+}
+/**
+ * Type guard for {@link GroupShape} group/canvas hosts.
+ *
+ * @private
+ */
+export function isGroupShape(value) {
+    return value instanceof GroupShape;
+}