@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/drawing/drawing-shape.d.ts

@@ -0,0 +1,1192 @@
+/**
+* DrawingShape leaf — residual-preserving DrawingML/VML run child.
+*
+* @private
+*/
+import { WordDocument } from '../document/document';
+import { EntityType } from '../document/entity-type';
+import { FeatureRunLeaf } from '../document/feature-run-leaf';
+import { Emus } from '../document/length';
+import { Body } from '../document/body';
+import { BodyItem } from '../document/body-item';
+import { BlockContent, Paragraph, ParagraphOwner } from '../document/paragraph';
+import { OpenXmlElement } from '../../core/xml/index';
+import { HorizontalAlignment as HorizontalAlignmentType, HorizontalOrigin as HorizontalOriginType, TextWrappingStyle as TextWrappingStyleType, TextWrappingType as TextWrappingTypeType, VerticalAlignment as VerticalAlignmentType, VerticalOrigin as VerticalOriginType } from '../images/layout-types';
+import { Table as TableFeature } from '../tables/index';
+import { DrawingHostPlacement } from './host-codec';
+import { ShapeFill, ShapeLine } from './sp-pr';
+import { BodyInsets, TextAnchoring, TextAutoFit, TextBodyWrap, TextHorzOverflow, TextVerticalType, TextVertOverflow } from './body-pr';
+import { AutoShapeType } from './shape-types';
+import { FillFormat, FillFormatOwner } from './fill-format';
+import { LineFormat, LineFormatOwner } from './line-format';
+import { WrapFormat, WrapFormatOwner } from './wrap-format';
+import { TextFrame, TextFrameOwner } from './text-frame';
+import { TextDirection, TextVerticalAlignment } from './body-pr';
+import { DrawingEncoding, DrawingExtent, DrawingPlacement, DrawingVariant } from './types';
+export declare type DirtyMode = 'clean' | 'identity' | 'layout' | 'structure';
+/**
+ * Cached `wps:spPr` MVP state read from residual (lazy).
+ * @private
+ */
+export interface ShapePropertiesStateCached {
+    readonly presetGeometry: string | undefined;
+    readonly useCustomGeometry: boolean;
+    readonly fill: ShapeFill | undefined;
+    readonly line: ShapeLine | undefined;
+    readonly hasThemeStyle: boolean;
+}
+export interface DrawingShapeInit {
+    readonly encoding: DrawingEncoding;
+    readonly residual: OpenXmlElement;
+    readonly dirty: DirtyMode;
+    readonly name?: string | undefined;
+    readonly title?: string | undefined;
+    readonly description?: string | undefined;
+    readonly docPrId?: number | undefined;
+    readonly placement?: DrawingHostPlacement | undefined;
+    /** Display width in points. */
+    readonly width?: number | undefined;
+    /** Display height in points. */
+    readonly height?: number | undefined;
+    readonly presetGeometry?: string | undefined;
+    readonly rotation?: number | undefined;
+    readonly lockAspectRatio?: boolean | undefined;
+    readonly flipHorizontal?: boolean | undefined;
+    readonly flipVertical?: boolean | undefined;
+    readonly wrapping?: TextWrappingStyleType | undefined;
+    /** Wrap side (`wp:wrap*@wrapText`) for square/tight/through. */
+    readonly wrapType?: TextWrappingTypeType | undefined;
+    /** Top text distance in points. */
+    readonly distanceTop?: number | undefined;
+    /** Bottom text distance in points. */
+    readonly distanceBottom?: number | undefined;
+    /** Left text distance in points. */
+    readonly distanceLeft?: number | undefined;
+    /** Right text distance in points. */
+    readonly distanceRight?: number | undefined;
+    readonly behindDocument?: boolean | undefined;
+    readonly horizontalOrigin?: HorizontalOriginType | undefined;
+    readonly verticalOrigin?: VerticalOriginType | undefined;
+    /** Horizontal offset in points. */
+    readonly horizontalPosition?: number | undefined;
+    /** Vertical offset in points. */
+    readonly verticalPosition?: number | undefined;
+    readonly horizontalAlignment?: HorizontalAlignmentType | undefined;
+    readonly verticalAlignment?: VerticalAlignmentType | undefined;
+    readonly lockAnchor?: boolean | undefined;
+    readonly allowOverlap?: boolean | undefined;
+    readonly layoutInCell?: boolean | undefined;
+    readonly fill?: ShapeFill | undefined;
+    readonly line?: ShapeLine | undefined;
+    /** Serialized `w:txbxContent` children for authored text box variants (TASK-8049). */
+    readonly txbxContent?: ReadonlyArray<OpenXmlElement> | undefined;
+    /** Modeled `wps:bodyPr` element for authored text box variants (TASK-8049). */
+    readonly bodyPrElement?: OpenXmlElement | undefined;
+    /**
+     * Nested group/canvas children (TASK-8051). When defined, the shape is a
+     * modeled group host even if the array is empty.
+     */
+    readonly children?: ReadonlyArray<DrawingShape> | undefined;
+}
+/**
+ * Cached `wps:txbx` body state (lazy).
+ * @private
+ */
+export interface TextBoxStateCached {
+    /** True when a `wps:txbx` (WML body) exists under the residual host. */
+    readonly present: boolean;
+    /**
+     * Internal ordered store for `w:txbxContent` (paragraphs/tables/SDTs).
+     * Public lists project via adapters.
+     */
+    readonly blocks: BlockContent[];
+    /** Residual `wps:txbx` element for verbatim clone when body is untouched. */
+    readonly residualTxbx: OpenXmlElement | undefined;
+    /** Residual `w:txbxContent` element (may be absent in odd fixtures). */
+    readonly residualTxbxContent: OpenXmlElement | undefined;
+}
+export declare class TextBoxParagraphOwner implements ParagraphOwner {
+    private readonly shape;
+    constructor(shape: DrawingShape);
+    assertAttachedParagraph(target: Paragraph): void;
+    /**
+     * @private
+     */
+    owningDocument(): WordDocument;
+}
+/** Deep membership check: direct or nested (table cell / SDT) paragraph. */
+export declare function blockListOwnsParagraph(blocks: ReadonlyArray<BlockContent>, target: Paragraph): boolean;
+export declare function tableOwnsParagraph(table: TableFeature, target: Paragraph): boolean;
+/**
+ * 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
+ */
+export declare class DrawingShape implements FeatureRunLeaf, FillFormatOwner, LineFormatOwner, WrapFormatOwner, TextFrameOwner {
+    private residual;
+    private encodingValue;
+    private dirtyMode;
+    private nameValue;
+    private titleValue;
+    private descriptionValue;
+    private docPrIdValue;
+    private placementValue;
+    /** Display width in points. */
+    private widthValue;
+    /** Display height in points. */
+    private heightValue;
+    private presetGeometryValue;
+    private rotationValue;
+    private lockAspectRatioValue;
+    private flipHorizontalValue;
+    private flipVerticalValue;
+    private wrappingValue;
+    /** Top text distance in points. */
+    private distanceTopValue;
+    /** Bottom text distance in points. */
+    private distanceBottomValue;
+    /** Left text distance in points. */
+    private distanceLeftValue;
+    /** Right text distance in points. */
+    private distanceRightValue;
+    private behindDocumentValue;
+    /** Whether distance* fields were explicitly modeled (vs residual/default). */
+    private distancesModeled;
+    /** Whether behindDocument was explicitly modeled. */
+    private behindDocumentModeled;
+    private horizontalOriginValue;
+    private verticalOriginValue;
+    /** Horizontal offset in points. */
+    private horizontalPositionValue;
+    /** Vertical offset in points. */
+    private verticalPositionValue;
+    private horizontalAlignmentValue;
+    private verticalAlignmentValue;
+    /** Whether a horizontal position mode (offset or align) is explicitly modeled. */
+    private horizontalModeled;
+    /** Whether a vertical position mode (offset or align) is explicitly modeled. */
+    private verticalModeled;
+    private lockAnchorValue;
+    private allowOverlapValue;
+    private layoutInCellValue;
+    /** Geometry/fill/line state (TASK-8048). Defined after first read/mtate. */
+    private spPrState;
+    private fillValue;
+    private fillModeled;
+    private lineValue;
+    private lineModeled;
+    /** Text box body state (TASK-8049). Lazy; defined after first body access. */
+    private txbxState;
+    private txbxBlocksValue;
+    private txbxBodyModeled;
+    private bodyPrValue;
+    private bodyPrModeled;
+    private textBoxOwner;
+    /**
+     * Nested DrawingML children under a group/canvas host (TASK-8051).
+     * Populated when {@link childrenModeled} is true (authored or materialised).
+     */
+    protected childrenValue: DrawingShape[];
+    /** True when nested children are owned by the model (including empty group). */
+    protected childrenModeled: boolean;
+    /** Lazy residual parse cache when children are not yet modeled. */
+    protected childrenCache: DrawingShape[] | undefined;
+    /** Parent group/canvas when this leaf is a nested child (TASK-8051). */
+    /** Parent group when nested; package-visible for GroupShape reparenting. @private */
+    parentGroup: DrawingShape | undefined;
+    /** Modeled wrap type (square sides). Default Both when unset. */
+    private wrappingTypeValue;
+    private fillFormatValue;
+    private lineFormatValue;
+    private wrapFormatValue;
+    private textFrameValue;
+    private textBodyValue;
+    /**
+     * @private
+     */
+    constructor(encoding: DrawingEncoding, element: OpenXmlElement);
+    /**
+     * @private
+     */
+    constructor(init: DrawingShapeInit);
+    /**
+     * Whether this leaf is DrawingML (`w:drawing` / MC Choice) or VML (`w:pict`).
+     *
+     * @private
+     */
+    encoding(): DrawingEncoding;
+    /**
+     * Placement host for DrawingML leaves, or `unknown` for VML.
+     *
+     * @private
+     */
+    placement(): DrawingPlacement;
+    /**
+     * 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
+     */
+    variant(): DrawingVariant;
+    /**
+     * 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
+     */
+    children(): ReadonlyArray<DrawingShape>;
+    /**
+     * Non-visual drawing name from `wp:docPr @name` / nested `cNvPr @name`.
+     * @public
+     */
+    name: string | undefined;
+    /**
+     * Title from `wp:docPr @title` / nested `cNvPr @title`.
+     * @public
+     */
+    title: string | undefined;
+    /**
+     * Alternative text from `wp:docPr @descr` / nested `cNvPr @descr`.
+     * @public
+     */
+    alternativeText: string | undefined;
+    /**
+     * Stable fill format facade (Shape.md).
+     * @public
+     */
+    readonly fillFormat: FillFormat;
+    /**
+     * Stable line format facade (Shape.md).
+     * @public
+     */
+    readonly lineFormat: LineFormat;
+    /**
+     * Stable wrap format facade (Shape.md).
+     * @public
+     */
+    readonly wrapFormat: WrapFormat;
+    /**
+     * Stable text frame facade (Shape.md).
+     * @public
+     */
+    readonly textFrame: TextFrame;
+    /**
+     * Text-box story content as a document {@link Body} (`w:txbxContent`).
+     * First access promotes the leaf to a text-box variant (`wps:txbx`).
+     * @public
+     */
+    readonly textBody: Body;
+    /**
+     * Auto shape type from preset geometry. Returns AutoShapeType.Unknown when missing/unrecognized/VML; Custom for custGeom.
+     * @public
+     */
+    readonly autoShapeType: AutoShapeType;
+    /** @private */
+    readShapeFillState(): ShapeFill | undefined;
+    /** @private */
+    writeShapeFillState(value: ShapeFill | undefined): void;
+    /** @private */
+    readShapeLineState(): ShapeLine | undefined;
+    /** @private */
+    writeShapeLineState(value: ShapeLine | undefined): void;
+    /** @private */
+    readWrapStyle(): TextWrappingStyleType;
+    /** @private */
+    writeWrapStyle(value: TextWrappingStyleType): void;
+    /** @private */
+    readWrapType(): TextWrappingTypeType;
+    /** @private */
+    writeWrapType(value: TextWrappingTypeType): void;
+    /** @private */
+    readAllowOverlap(): boolean;
+    /** @private */
+    writeAllowOverlap(value: boolean): void;
+    /** @private */
+    readDistanceTop(): number;
+    /** @private */
+    writeDistanceTop(value: number): void;
+    /** @private */
+    readDistanceBottom(): number;
+    /** @private */
+    writeDistanceBottom(value: number): void;
+    /** @private */
+    readDistanceLeft(): number;
+    /** @private */
+    writeDistanceLeft(value: number): void;
+    /** @private */
+    readDistanceRight(): number;
+    /** @private */
+    writeDistanceRight(value: number): void;
+    /** @private */
+    readTextFrameDirection(): TextDirection | undefined;
+    /** @private */
+    writeTextFrameDirection(value: TextDirection | undefined): void;
+    /** @private */
+    readTextFrameVerticalAlignment(): TextVerticalAlignment | undefined;
+    /** @private */
+    writeTextFrameVerticalAlignment(value: TextVerticalAlignment | undefined): void;
+    /** @private */
+    readInternalMarginLeft(): number;
+    /** @private */
+    writeInternalMarginLeft(value: number): void;
+    /** @private */
+    readInternalMarginTop(): number;
+    /** @private */
+    writeInternalMarginTop(value: number): void;
+    /** @private */
+    readInternalMarginRight(): number;
+    /** @private */
+    writeInternalMarginRight(value: number): void;
+    /** @private */
+    readInternalMarginBottom(): number;
+    /** @private */
+    writeInternalMarginBottom(value: number): void;
+    /** @private */
+    private readBodyInsets;
+    /** @private */
+    private writeBodyInsets;
+    /**
+     * BodyInsets sides are **points** (body-pr parse/build converts at the
+     * wire boundary). Defaults are Word bodyPr EMU constants converted once.
+     * @private
+     */
+    private readInsetPoints;
+    /**
+     * Store InternalMargin sides as points on BodyInsets (same unit as
+     * body-pr model). Do not convert to EMU here — buildBodyPrElement does.
+     * @private
+     */
+    private writeInsetPoints;
+    /** @private */
+    ensureTextBodyAccessible(): void;
+    /**
+     * @private
+     * Point the txbx cache at the Body block store after Body mutations.
+     */
+    syncTxbxBlocksFromBody(blocks: BlockContent[]): void;
+    /**
+     * 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
+    */
+    appendShape(autoShapeType: AutoShapeType, width: number, height: number): Shape;
+    /**
+     * 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
+     */
+    extent(): DrawingExtent | undefined;
+    /**
+
+     * numbers; kept for back-compat with existing feature-module tests.
+     *
+     * @private
+     */
+    extentEmu(): {
+        readonly width: Emus;
+        readonly height: Emus;
+    } | undefined;
+    /**
+     * 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
+     */
+    width: number | undefined;
+    /**
+     * Display height (`wp:extent/@cy` preferred). Same lock semantics as {@link width}.
+     *
+     * @public
+     */
+    height: number | undefined;
+    /**
+     * 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
+     */
+    rotation: number;
+    /**
+     * 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
+     */
+    lockAspectRatio: boolean;
+    /**
+     * Horizontal flip (`a:xfrm/@flipH`). Missing attribute reads as `false`.
+     *
+     * @public
+     */
+    flipHorizontal: boolean;
+    /**
+     * Vertical flip (`a:xfrm/@flipV`). Missing attribute reads as `false`.
+     *
+     * @public
+     */
+    flipVertical: boolean;
+    /**
+     * 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 */
+    /** @private */
+    private wrappingStyleInternal;
+    /**
+     * Distance from text above the shape (`wp:inline|wp:anchor/@distT`).
+     * Missing residual attribute reads as `emuToPoint(0)`.
+     *
+     * @public
+     */
+    /** @private */
+    /** @private */
+    private distanceTopInternal;
+    /**
+     * Distance from text below the shape (`wp:inline|wp:anchor/@distB`).
+     * Missing residual attribute reads as `0` points.
+     *
+     * @public
+     */
+    /** @private */
+    /** @private */
+    private distanceBottomInternal;
+    /**
+     * 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 */
+    /** @private */
+    private distanceLeftInternal;
+    /**
+     * 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 */
+    /** @private */
+    private distanceRightInternal;
+    /**
+     * 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
+     */
+    isBelowText: boolean;
+    /**
+     * 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
+     */
+    horizontalOrigin: HorizontalOriginType;
+    /**
+     * 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
+     */
+    verticalOrigin: VerticalOriginType;
+    /**
+     * 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
+     */
+    horizontalPosition: number | undefined;
+    /**
+     * 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
+     */
+    verticalPosition: number | undefined;
+    /**
+     * 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
+     */
+    horizontalAlignment: HorizontalAlignmentType;
+    /**
+     * 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
+     */
+    verticalAlignment: VerticalAlignmentType;
+    /**
+     * 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
+     */
+    lockAnchor: boolean;
+    /**
+     * Allow overlap (`wp:anchor/@allowOverlap`). Inline and VML leaves report
+     * `false` (inline hosts have no anchor surface).
+     *
+     * @public
+     */
+    /** @private */
+    /** @private */
+    private allowOverlapInternal;
+    /**
+     * Layout in table cell (`wp:anchor/@layoutInCell`). Inline and VML leaves
+     * report `false` (inline hosts have no anchor surface).
+     *
+     * @public
+     */
+    layoutInCell: boolean;
+    /** Lazy spPr state read (cached per instance; invalidated on structure dirty). */
+    private readSpPrState;
+    /**
+     * 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
+     */
+    presetGeometryToken: string | undefined;
+    /**
+     * 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 */
+    /** @private */
+    private fillInternal;
+    /**
+     * 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 */
+    /** @private */
+    private lineInternal;
+    /**
+     * 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.
+     */
+    readonly hasThemeStyle: boolean;
+    /**
+     * Lazy residual txbx state read (cached per instance).
+     * @private
+     */
+    private readTxbxState;
+    /**
+     * Paragraph-owner context for lazy body parse.
+     * @private
+     */
+    private textBoxOwnerForParse;
+    /**
+     * 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
+     */
+    isTextBox(): boolean;
+    /**
+     * 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
+     */
+    hasVmlFallback(): boolean;
+    /** Guard for body APIs on non-textBox shapes. */
+    private requireTextBox;
+    /**
+     * Lazy residual bodyPr state read (cached per instance).
+     * @private
+     */
+    private readBodyPrState;
+    /**
+     * Persist a modeled bodyPr slice (marks structure dirty).
+     * @private
+     */
+    private writeBodyPrField;
+    /**
+     * 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
+     */
+    /**
+    * 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
+    */
+    verticalAnchor: TextAnchoring | undefined;
+    /**
+     * Center anchoring (`wps:bodyPr/@anchorCtr`). `undefined` = attribute absent.
+     *
+     * @throws DocxError `content/invalid-shape` on a VML leaf.
+     *
+     * @private
+     */
+    /**
+    * Center anchoring (`wps:bodyPr/@anchorCtr`). `undefined` = attribute absent.
+    *
+    * @throws DocxError `content/invalid-shape` on a VML leaf.
+    *
+    * @private
+    */
+    anchorCenter: boolean | undefined;
+    /**
+     * Vertical text type (`wps:bodyPr/@vert`, `ST_TextVerticalType`).
+     * `undefined` = attribute absent (horizontal).
+     *
+     * @throws DocxError `content/invalid-shape` on a VML leaf.
+     *
+     * @public
+     */
+    textDirection: TextVerticalType | undefined;
+    /**
+     * 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
+     */
+    /**
+    * 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
+    */
+    textWrapInside: TextBodyWrap | undefined;
+    /**
+     * Vertical text overflow (`wps:bodyPr/@vertOverflow`,
+     * `ST_TextVertOverflowType`). `undefined` = attribute absent.
+     *
+     * @throws DocxError `content/invalid-shape` on a VML leaf.
+     *
+     * @private
+     */
+    /**
+    * Vertical text overflow (`wps:bodyPr/@vertOverflow`,
+    * `ST_TextVertOverflowType`). `undefined` = attribute absent.
+    *
+    * @throws DocxError `content/invalid-shape` on a VML leaf.
+    *
+    * @private
+    */
+    verticalOverflow: TextVertOverflow | undefined;
+    /**
+     * Horizontal text overflow (`wps:bodyPr/@horzOverflow`,
+     * `ST_TextHorzOverflowType`). `undefined` = attribute absent.
+     *
+     * @throws DocxError `content/invalid-shape` on a VML leaf.
+     *
+     * @private
+     */
+    /**
+    * Horizontal text overflow (`wps:bodyPr/@horzOverflow`,
+    * `ST_TextHorzOverflowType`). `undefined` = attribute absent.
+    *
+    * @throws DocxError `content/invalid-shape` on a VML leaf.
+    *
+    * @private
+    */
+    horizontalOverflow: TextHorzOverflow | undefined;
+    /**
+     * WordArt source flag (`wps:bodyPr/@fromWordArt`). `undefined` = absent.
+     * Flag only — no WordArt pipeline (GO).
+     *
+     * @throws DocxError `content/invalid-shape` on a VML leaf.
+     *
+     * @private
+     */
+    /**
+    * WordArt source flag (`wps:bodyPr/@fromWordArt`). `undefined` = absent.
+    * Flag only — no WordArt pipeline (GO).
+    *
+    * @throws DocxError `content/invalid-shape` on a VML leaf.
+    *
+    * @private
+    */
+    fromWordArt: boolean | undefined;
+    /**
+     * 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
+     */
+    /**
+    * 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
+    */
+    insets: BodyInsets | undefined;
+    /**
+     * 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
+     */
+    /**
+    * 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
+    */
+    autoFit: TextAutoFit | undefined;
+    /**
+     * 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
+     */
+    readonly bodyPrResidual: boolean;
+    /**
+     * Whether the residual bodyPr has WordArt warp (`a:prstTxWarp` child).
+     * Read-only flag — warp is not modeled (never invented).
+     *
+     * @private
+     */
+    readonly hasPresetTextWarp: boolean;
+    /**
+     * 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
+     */
+    readonly blocks: ReadonlyArray<BodyItem>;
+    /**
+     * Insert a body item at `index` in the text box block list.
+     * Public consumers use {@link Shape.insertBodyItemAt}.
+     *
+     * @private
+     */
+    insertBodyItemAt(index: number, item: BodyItem): BodyItem;
+    /**
+     * Remove the body item at `index` in the text box block list.
+     * Public consumers use {@link Shape.removeBodyItemAt}.
+     *
+     * @private
+     */
+    removeBodyItemAt(index: number): void;
+    /**
+     * Remove a body item from the text box block list by projected identity.
+     * Public consumers use {@link Shape.removeBodyItem}.
+     *
+     * @private
+     */
+    removeBodyItem(item: BodyItem): void;
+    /**
+     * @private
+     * Txbx block store for TextBoxParagraphOwner attach checks.
+     */
+    internalBlocks(): ReadonlyArray<BlockContent>;
+    /**
+     * @private
+     * Owning document for textbox body paragraphs. Resolves through
+     * the anchoring paragraph when bound; throws detached otherwise.
+     */
+    internalOwningDocument(): WordDocument;
+    /**
+     * Anchoring paragraph (bound at append/load time).
+     * @private
+     */
+    private anchoringParagraph;
+    /**
+     * @private
+   * Bind the anchoring paragraph for textbox owner document resolution. */
+    /** @private */
+    /** Anchoring paragraph accessor; package-visible for GroupShape reparenting. @private */
+    getAnchoringParagraph(): Paragraph | undefined;
+    bindAnchoringParagraph(paragraph: Paragraph | undefined): void;
+    /**
+     * Relationship ids referenced by `r:embed` or `r:link` in the preserved subtree.
+     *
+     * @private
+     */
+    relationshipIds(): ReadonlyArray<string>;
+    /**
+     * @private
+     */
+    toOpenXml(): OpenXmlElement;
+    /**
+     * Replace the materialized `w:txbxContent` inside a cloned residual host
+     * (identity / layout dirty paths keep everything else verbatim).
+     */
+    private replaceTxbxContentInResidual;
+    private drawingRoot;
+    private markIdentityDirty;
+    /**
+     * Promote to layout dirty. Never demotes `structure`.
+     * Hydrates size/transform/lock from residual when leaving `clean`/`identity`.
+     */
+    private markLayoutDirty;
+    /**
+     * Promote the leaf to a textBox variant (`wps:txbx` modeled).
+     * Never demotes; idempotent once set.
+     * @private
+     */
+    private markTxbxBodyModeled;
+    /**
+     * 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 */
+    markStructureDirty(): void;
+    private hydrateIdentityAndLayoutFromResidual;
+    /**
+     * Read identity from nested `wps:cNvPr` / `wpg:cNvPr` when residual is a bare
+     * nested shape/group; otherwise from top-level `wp:docPr`.
+     */
+    private readResidualIdentity;
+    /**
+     * Parse nested `wps:wsp` / `wpg:grpSp` children under residual `wpg:wgp` or
+     * `wpc:wpc` (TASK-8051). Unknown residual siblings are not modeled as children.
+     */
+    private parseNestedChildrenFromResidual;
+    /**
+     * Materialize residual or cached children into {@link childrenValue} so nested
+     * authoring can push without dropping lazy residual siblings.
+     */
+    protected ensureChildrenModeled(): void;
+    /**
+     * Allocate a package-unique cNvPr/docPr id for a nested child using the
+     * top-level host's anchoring paragraph when available.
+     */
+    private allocateNestedDocPrId;
+    /** True when any nested child (direct) is not clean. */
+    private hasDirtyNestedChildren;
+    /**
+     * Clone residual host and replace nested wsp/grpSp under wgp/wpc with each
+     * child's {@link toOpenXml}, preserving grpSpPr and unknown residual siblings.
+     */
+    private rewriteResidualNestedChildren;
+    /**
+     * 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.
+     */
+    protected notifyParentOfChildDirty(): void;
+    private readDistancePoints;
+}
+/**
+ * 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
+ */
+export declare class Shape extends DrawingShape {
+    /**
+     * Public discriminant for {@link Paragraph.items} ({@link EntityType.Shape}).
+     * @public
+     */
+    readonly type: EntityType.Shape | EntityType.GroupShape;
+    /**
+     * @private
+     */
+    constructor(encoding: DrawingEncoding, element: OpenXmlElement);
+    /**
+     * @private
+     */
+    constructor(init: DrawingShapeInit);
+    /**
+     * 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
+     */
+    readonly items: ReadonlyArray<BodyItem>;
+    /**
+     * 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
+     */
+    insertBodyItemAt(index: number, item: BodyItem): BodyItem;
+    /**
+     * 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
+     */
+    removeBodyItemAt(index: number): void;
+    /**
+     * 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
+     */
+    removeBodyItem(item: BodyItem): void;
+}
+/**
+ * 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
+ */
+export declare class GroupShape extends Shape {
+    /**
+     * Public discriminant for {@link Paragraph.items} ({@link EntityType.GroupShape}).
+     * @public
+     */
+    readonly type: EntityType.GroupShape;
+    /**
+     * @private
+     */
+    constructor(encoding: DrawingEncoding, element: OpenXmlElement);
+    /**
+     * @private
+     */
+    constructor(init: DrawingShapeInit);
+    /**
+     * Nested DrawingML children under this group or canvas, in document order.
+     * @public
+     */
+    readonly childShapes: ReadonlyArray<DrawingShape>;
+    /**
+     * Nested child items (collection surface).
+     * @public
+     */
+    readonly childItems: ReadonlyArray<DrawingShape>;
+    /**
+     * Nested DrawingML children under this group or canvas.
+     * @private
+     */
+    children(): ReadonlyArray<DrawingShape>;
+    /**
+     * Add an existing drawing leaf as a nested child. Detaches from anchoring paragraph when needed.
+     * @public
+     */
+    add(paragraphItem: DrawingShape | {
+        readonly type?: string;
+        readonly value?: unknown;
+    }): void;
+    /**
+     * Ungroup children into an array of drawing leaves.
+     * @public
+     */
+    unGroup(): ReadonlyArray<DrawingShape>;
+    /**
+     * Append a nested preset-geometry {@link Shape} under this group.
+     * @public
+     */
+    appendShape(autoShapeType: AutoShapeType, width: number, height: number): Shape;
+    /** @private */
+    writeShapeFillState(_value: ShapeFill | undefined): void;
+    /** @private */
+    writeShapeLineState(_value: ShapeLine | undefined): void;
+    /** @private */
+    writeTextFrameDirection(_value: TextDirection | undefined): void;
+    /** @private */
+    writeTextFrameVerticalAlignment(_value: TextVerticalAlignment | undefined): void;
+    /** @private */
+    ensureTextBodyAccessible(): void;
+}
+/**
+ * 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 declare function createDrawingShape(encoding: DrawingEncoding, element: OpenXmlElement): DrawingShape;
+/**
+ * Construct {@link Shape} or {@link GroupShape} from an authored / modeled init.
+ * Modeled `children` (including `[]`) always yields {@link GroupShape}.
+ *
+ * @private
+ */
+export declare function createDrawingShapeFromInit(init: DrawingShapeInit): DrawingShape;
+/**
+ * Type guard for leaf {@link Shape} instances (not group/canvas hosts).
+ *
+ * @private
+ */
+export declare function isShape(value: DrawingShape): value is Shape;
+/**
+ * Type guard for {@link GroupShape} group/canvas hosts.
+ *
+ * @private
+ */
+export declare function isGroupShape(value: DrawingShape): value is GroupShape;