@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

package/src/features/drawing/host-codec.d.ts

@@ -0,0 +1,632 @@
+/**
+ * Drawing shape host encode helpers (`wp:inline` / `wp:anchor` + `wps:wsp`).
+ *
+ * Schema cites:
+ * - ECMA-376-1 §20.4 `CT_Inline` / `CT_Anchor`, `wp:docPr` (`CT_NonVisualDrawingProps`)
+ * - DrawingML `a:graphic` / `a:graphicData`, `a:prstGeom` (`ST_ShapeType`)
+ * - [MS-ODRAWXML] wordprocessingShape (`wps:wsp`)
+ * - ECMA-376-3 Markup Compatibility AlternateContent Choice/Fallback
+ * - ECMA-376-4 VML `w:pict` / `v:shape` Fallback (Policy B dual AC; TASK-8050)
+ * - VML main XSD: AG_Fill (`filled`/`fillcolor`), AG_ShapeAttributes
+ *   (`stroked`/`strokecolor`/`strokeweight`), AG_StrokeAttributes / `v:stroke`,
+ *   CT_Textbox (`@inset`, optional `w:txbxContent`)
+ * - `vml-wordprocessingDrawing.xsd`: `w10:wrap` (`ST_WrapType`), `w10:anchorlock`
+ * - ShapeRequirements Fallback samples: style tokens, `v:stroke` joinstyle miter,
+ *   DML `a:tailEnd type="triangle"` → VML `endarrow="block"`
+ *
+ * Anchor defaults mirror images host-codec (distL/R 114300, relativeHeight
+ * 251658240, layoutInCell 1, allowOverlap 1, positionH column 0, positionV
+ * paragraph 0, wrapNone).
+ *
+ * @packageDocumentation
+ */
+import { BodyBlockParseContext } from '../../core/registry/block-handlers';
+import { BlockContent } from '../document/paragraph';
+import { Emus } from '../document/length';
+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 { LineCap, LineEndSize, LineEndType, LineDashing } from './sp-pr';
+/**
+ * @private
+ */
+export declare const WP_NS = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
+/**
+ * @private
+ */
+export declare const A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main";
+/**
+ * @private
+ */
+export declare const R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+/**
+ * @private
+ */
+export declare const WPS_NS = "http://schemas.microsoft.com/office/word/2010/wordprocessingShape";
+/**
+ * @private
+ */
+export declare const WPG_NS = "http://schemas.microsoft.com/office/word/2010/wordprocessingGroup";
+/**
+ * @private
+ */
+export declare const WPC_NS = "http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas";
+/**
+ * @private
+ */
+export declare const VML_NS = "urn:schemas-microsoft-com:vml";
+/**
+ * Word VML extensions namespace (`vml-wordprocessingDrawing.xsd` targetNamespace).
+ * Used for `w10:wrap` / `w10:anchorlock` on authored Fallback shapes.
+ *
+ * @private
+ */
+export declare const W10_NS = "urn:schemas-microsoft-com:office:word";
+/**
+ * @private
+ */
+export declare const MC_NS = "http://schemas.openxmlformats.org/markup-compatibility/2006";
+/**
+ * ST_Angle: 60000ths of a degree (ECMA-376 DrawingML `dml-main` CT_Transform2D).
+ * Same unit as images host-codec; local copy avoids drawing→images encode coupling.
+ *
+ * @private
+ */
+export declare const ROTATION_UNITS_PER_DEGREE = 60000;
+/**
+ * @private
+ */
+export declare type DrawingHostPlacement = 'inline' | 'anchor';
+/**
+ * @private
+ * Author / rebuild input for dual AC shape host. */
+export interface EncodeDrawingShapeInput {
+    readonly placement: DrawingHostPlacement;
+    readonly widthEmu: Emus;
+    readonly heightEmu: Emus;
+    readonly presetGeometry: string;
+    readonly docPrId: number;
+    readonly name: string;
+    readonly title: string | undefined;
+    readonly description: string | undefined;
+    /** Clockwise degrees; wire `a:xfrm/@rot` = round(deg × 60000). Default 0. */
+    readonly rotation?: number;
+    /** `a:xfrm/@flipH`. Default false. */
+    readonly flipHorizontal?: boolean;
+    /** `a:xfrm/@flipV`. Default false. */
+    readonly flipVertical?: boolean;
+    /**
+     * `a:graphicFrameLocks/@noChangeAspect`.
+     * Author default true (images parity); omit locks attr when false.
+     */
+    readonly lockAspectRatio?: boolean;
+    /**
+     * Text wrapping style. `inline` forces `wp:inline`; other values force `wp:anchor`
+     * with the matching wrap child. Default: `inline` when placement is inline, else `none`.
+     */
+    readonly wrapping?: TextWrappingStyleType;
+    /** `wp:wrapSquare|wrapTight|wrapThrough/@wrapText`. Default bothSides. */
+    readonly wrapType?: TextWrappingTypeType;
+    /** `wp:inline|wp:anchor/@distT` EMU. Inline author default 0; anchor default 0. */
+    readonly distanceTopEmu?: Emus;
+    /** `wp:inline|wp:anchor/@distB` EMU. */
+    readonly distanceBottomEmu?: Emus;
+    /** `wp:inline|wp:anchor/@distL` EMU. Inline default 0; anchor default 114300. */
+    readonly distanceLeftEmu?: Emus;
+    /** `wp:inline|wp:anchor/@distR` EMU. Inline default 0; anchor default 114300. */
+    readonly distanceRightEmu?: Emus;
+    /**
+     * `wp:anchor/@behindDoc` (0/1). Ignored for inline hosts.
+     * Author default false.
+     */
+    readonly behindDocument?: boolean;
+    /**
+     * `wp:positionH/@relativeFrom` (`ST_RelFromH`). When undefined, the encoder
+     * falls back to the residual `@relativeFrom`, then `'column'` (images parity).
+     */
+    readonly horizontalOrigin?: HorizontalOriginType;
+    /**
+     * `wp:positionV/@relativeFrom` (`ST_RelFromV`). Fallback: residual, then
+     * `'paragraph'` (images parity).
+     */
+    readonly verticalOrigin?: VerticalOriginType;
+    /**
+     * `wp:positionH/wp:posOffset` EMU text. When undefined, the encoder emits the
+     * residual offset, else offset `0` unless {@link horizontalAlignment} is set.
+     * Negative values are schema-legal (`ST_PositionOffset` = xsd:int).
+     */
+    readonly horizontalPositionEmu?: Emus;
+    /** `wp:positionV/wp:posOffset` EMU (fallback: residual, then `0`). */
+    readonly verticalPositionEmu?: Emus;
+    /**
+     * `wp:positionH/wp:align` (`ST_AlignH`). XOR with posOffset per `CT_PosH`.
+     */
+    readonly horizontalAlignment?: HorizontalAlignmentType;
+    /**
+     * `wp:positionV/wp:align` (`ST_AlignV`). XOR with posOffset per `CT_PosV`.
+     */
+    readonly verticalAlignment?: VerticalAlignmentType;
+    /**
+     * `wp:anchor/@locked` (anchor position frozen for editing apps). Ignored for
+     * inline hosts. Author default false.
+     */
+    readonly lockAnchor?: boolean;
+    /** `wp:anchor/@allowOverlap`. Author default true. */
+    readonly allowOverlap?: boolean;
+    /** `wp:anchor/@layoutInCell`. Author default true. */
+    readonly layoutInCell?: boolean;
+    /**
+     * Explicit horizontal position mode override. When true, `wp:positionH` is
+     * rebuilt from {@link horizontalOrigin}/`posOffset`/`align` fields; when
+     * false/undefined the residual position is preserved when available.
+     * @private
+     */
+    readonly horizontalModeled?: boolean;
+    /**
+     * See {@link EncodeDrawingShapeInput.horizontalModeled}.
+     * @private
+     */
+    readonly verticalModeled?: boolean;
+    /**
+     * Fill MVP for authored/rebuilt spPr: solid sRGB or none. When undefined and
+     * a residual spPr fill exists, the residual fill element is preserved.
+     * @private
+     */
+    readonly fill?: {
+        readonly kind: 'solid';
+        readonly srgb: string;
+        /** DrawingML `a:alpha/@val` (0…100000). Omitted = opaque. */
+        readonly alpha?: number | undefined;
+    } | {
+        readonly kind: 'none';
+    };
+    /**
+     * Line MVP for authored/rebuilt spPr. When undefined and a residual `a:ln`
+     * exists, the residual line element is preserved.
+     * @private
+     */
+    readonly line?: {
+        readonly kind: 'solid';
+        readonly widthEmu?: Emus | undefined;
+        readonly srgb: string;
+        readonly dash?: LineDashing | undefined;
+        readonly cap?: LineCap | undefined;
+        readonly beginArrowType?: LineEndType | undefined;
+        readonly beginArrowSize?: LineEndSize | undefined;
+        readonly endArrowType?: LineEndType | undefined;
+        readonly endArrowSize?: LineEndSize | undefined;
+    } | {
+        readonly kind: 'none';
+        readonly widthEmu?: Emus | undefined;
+        readonly cap?: LineCap | undefined;
+    };
+    /**
+     * Original drawing residual for preserving wrap / position / host attrs when
+     * rebuild does not dirty modeled layout.
+     */
+    readonly preservedHost?: OpenXmlElement;
+    /**
+     * When true, rebuild wrap (and modeled distances / behindDoc) from input fields.
+     * When false and preservedHost has a matching anchor, reuse residual wrap child.
+     */
+    readonly layoutDirty?: boolean;
+    /**
+     * Serialize a text box variant: emit `wps:txbx` (with `w:txbxContent`
+     * children) and `wps:bodyPr` on `wps:wsp` (TASK-8049).
+     *
+     * `CT_WordprocessingShape` order: cNvPr? → cNvSpPr/cNvCnPr → spPr → style? →
+     * extLst? → (txbx | linkedTxbx)? → bodyPr (minOccurs 1).
+     * When undefined and the preserved host has a residual `wps:txbx`, the
+     * residual txbx is cloned verbatim (body preserved, content not rebuilt).
+     * @private
+     */
+    readonly txbxContent?: ReadonlyArray<OpenXmlElement> | undefined;
+    /**
+     * Modeled `wps:bodyPr` (`CT_TextBodyProperties` — TASK-8049). Always emitted
+     * (schema minOccurs=1) on the authored/rebuilt wsp; empty element when no
+     * field is modeled.
+     */
+    readonly bodyPr?: OpenXmlElement | undefined;
+    /**
+     * Nested child elements under top-level `wpg:wgp` (TASK-8051). When defined,
+     * {@link buildGraphic} emits `a:graphicData @uri=WPG` + `wpg:wgp` instead of
+     * a leaf `wps:wsp`. Empty array authors an empty group.
+     * @private
+     */
+    readonly groupChildElements?: ReadonlyArray<OpenXmlElement> | undefined;
+}
+/**
+ * Author / rebuild input for dual AC wordprocessing group host (TASK-8051).
+ * Identity lives on `wp:docPr`; children are bare nested `wps:wsp` / `wpg:grpSp`.
+ *
+ * @private
+ */
+export interface EncodeGroupInput {
+    readonly placement: DrawingHostPlacement;
+    readonly widthEmu: Emus;
+    readonly heightEmu: Emus;
+    readonly docPrId: number;
+    readonly name: string;
+    readonly title?: string | undefined;
+    readonly description?: string | undefined;
+    readonly rotation?: number | undefined;
+    readonly flipHorizontal?: boolean | undefined;
+    readonly flipVertical?: boolean | undefined;
+    readonly lockAspectRatio?: boolean | undefined;
+    readonly wrapping?: TextWrappingStyleType | undefined;
+    readonly distanceTopEmu?: Emus | undefined;
+    readonly distanceBottomEmu?: Emus | undefined;
+    readonly distanceLeftEmu?: Emus | undefined;
+    readonly distanceRightEmu?: Emus | undefined;
+    readonly behindDocument?: boolean | undefined;
+    readonly horizontalOrigin?: HorizontalOriginType | undefined;
+    readonly verticalOrigin?: VerticalOriginType | undefined;
+    readonly horizontalPositionEmu?: Emus | undefined;
+    readonly verticalPositionEmu?: Emus | undefined;
+    readonly horizontalAlignment?: HorizontalAlignmentType | undefined;
+    readonly verticalAlignment?: VerticalAlignmentType | undefined;
+    readonly lockAnchor?: boolean | undefined;
+    readonly allowOverlap?: boolean | undefined;
+    readonly layoutInCell?: boolean | undefined;
+    readonly horizontalModeled?: boolean | undefined;
+    readonly verticalModeled?: boolean | undefined;
+    readonly preservedHost?: OpenXmlElement | undefined;
+    readonly layoutDirty?: boolean | undefined;
+    /** Nested bare `wps:wsp` / `wpg:grpSp` children (may be empty). */
+    readonly children: ReadonlyArray<OpenXmlElement>;
+}
+/**
+ * @private
+ * Wrap + distance state read from residual DrawingML host. */
+export interface DrawingWrapState {
+    readonly placement: DrawingHostPlacement | undefined;
+    readonly wrapping: TextWrappingStyleType;
+    /**
+     * Effective `wrapText` for square/tight/through hosts.
+     * Absent attribute → Both; unrecognized token → Unknown; styles without wrapText → Both.
+     */
+    readonly wrapType: TextWrappingTypeType;
+    readonly distanceTopEmu: Emus | undefined;
+    readonly distanceBottomEmu: Emus | undefined;
+    readonly distanceLeftEmu: Emus | undefined;
+    readonly distanceRightEmu: Emus | undefined;
+    readonly behindDocument: boolean;
+    readonly lockAnchor: boolean;
+    readonly allowOverlap: boolean;
+    readonly layoutInCell: boolean;
+    readonly presetGeometry: string | undefined;
+}
+/**
+ * @private
+ * H/V position state read from residual DrawingML host. */
+export interface DrawingPositionState {
+    readonly horizontalOrigin: HorizontalOriginType | undefined;
+    readonly verticalOrigin: VerticalOriginType | undefined;
+    readonly horizontalPosition: number | undefined;
+    readonly verticalPosition: number | undefined;
+    /** EMU form of {@link DrawingPositionState.horizontalPosition}. */
+    readonly horizontalPositionEmu: Emus | undefined;
+    /** EMU form of {@link DrawingPositionState.verticalPosition}. */
+    readonly verticalPositionEmu: Emus | undefined;
+    readonly horizontalAlignment: HorizontalAlignmentType | undefined;
+    readonly verticalAlignment: VerticalAlignmentType | undefined;
+}
+/**
+ * @private
+ * Identity fields patched onto residual `wp:docPr`. */
+export interface DrawingDocPrIdentity {
+    readonly name: string | undefined;
+    readonly title: string | undefined;
+    readonly description: string | undefined;
+    readonly docPrId: number | undefined;
+}
+/**
+ * @private
+ * Layout fields for residual hydrate / layout dirty patch. */
+export interface DrawingLayoutState {
+    readonly widthEmu: Emus | undefined;
+    readonly heightEmu: Emus | undefined;
+    readonly rotation: number;
+    readonly flipHorizontal: boolean;
+    readonly flipVertical: boolean;
+    readonly lockAspectRatio: boolean;
+}
+/**
+ * @private
+ * Layout patch payload (identity optional when only structure-adjacent). */
+export interface DrawingLayoutPatch extends DrawingDocPrIdentity {
+    readonly widthEmu: Emus;
+    readonly heightEmu: Emus;
+    readonly rotation: number;
+    readonly flipHorizontal: boolean;
+    readonly flipVertical: boolean;
+    readonly lockAspectRatio: boolean;
+}
+/**
+ * @private
+ */
+export declare function findFirstElement(root: OpenXmlElement, namespaceUri: string, localName: string): OpenXmlElement | undefined;
+/**
+ * @private
+ */
+export declare function attributeValue(el: OpenXmlElement, namespaceUri: string, localName: string): string | undefined;
+/**
+ * Locate the residual `wps:spPr` for fill/line preservation on rebuild.
+ * Residual hosts nest `wps:spPr` under dual MC / `w:drawing` / `wp:*` /
+ * `a:graphic` / `wps:wsp`, so lookup is deep.
+ *
+ * @private
+ */
+export declare function findResidualSpPr(preservedHost: OpenXmlElement | undefined): OpenXmlElement | undefined;
+/**
+ * Build `wps:txbx` (`CT_TextboxInfo`) from serialized `w:txbxContent` children.
+ *
+ * Schema: `CT_TextboxInfo` = sequence `txbxContent` (minOccurs 1) + optional
+ * `extLst`; optional `@id` (default 0). `w:txbxContent` is
+ * `EG_BlockLevelElts` minOccurs 1 — the body must not be empty (Word authors
+ * at least one `w:p`; go6 author minimum matches).
+ *
+ * Cites:
+ * `specs/schemas/xsd/OfficeOpenXML-XMLSchema-Transitional/dml-wordprocessingDrawing.xsd`
+ * `CT_TxbxContent` / `CT_TextboxInfo`.
+ *
+ * @private
+ */
+export declare function buildTxbxElement(contentChildren: ReadonlyArray<OpenXmlElement>): OpenXmlElement;
+/**
+ * Serialize modeled `w:txbxContent` block state into `txbxContent` element
+ * children. Modeled paragraphs/tables/SDTs emit their DOM form; residual
+ * blocks (opaque XML not owned by a registered feature) pass through verbatim
+ * — the library never invents block OOXML it does not model.
+ *
+ * @private
+ */
+export declare function serializeTxbxContentBlocks(blocks: ReadonlyArray<TxbxBlock>): OpenXmlElement[];
+/**
+ * Block model alias for text box content (same core block union).
+ * @private
+ */
+export declare type TxbxBlock = BlockContent;
+/**
+ * Parse `w:txbxContent` children into core block state.
+ *
+ * Uses the same `parseBodyBlocks` path as headers/footers and table cells:
+ * `w:p` → modeled `Paragraph`; `w:tbl` → modeled `Table` **only when the
+ * tables feature is registered**; `w:sdt` → modeled SDT **only when the
+ * content-controls feature is registered**; everything else (and any block
+ * whose feature is unregistered) stays residual-opaque — never dropped, never
+ * invented (GO Q6; offline policy).
+ *
+ * @private
+ */
+export declare function parseTxbxContentBlocks(txbxContent: OpenXmlElement, ctx: BodyBlockParseContext): TxbxBlock[];
+/**
+ * Whether any `wps:wsp` under the host carries a `wps:txbx` (or `linkedTxbx`)
+ * child — deep walk so dual MC Choice branches resolve.
+ *
+ * @private
+ */
+export declare function residualHasTxbx(host: OpenXmlElement | undefined): boolean;
+/**
+ * Build top-level `wpg:wgp` group shape for graphicData (TASK-8051).
+ *
+ * Top-level wgp has no `cNvPr` (identity lives on `wp:docPr`). Nested groups
+ * use `wpg:grpSp` with `cNvPr` — authored via residual clone or nested
+ * structure paths, not this builder.
+ *
+ * Cites: [MS-ODRAWXML] §2.16.3.2 CT_WordprocessingGroup —
+ * `cNvGrpSpPr?`, `grpSpPr`, then `(wsp|grpSp|graphicFrame|contentPart|spTree)*`.
+ *
+ * @private
+ */
+export declare function buildWpgGroup(input: EncodeDrawingShapeInput): OpenXmlElement;
+/**
+ * Build a nested bare `wps:wsp` for group/canvas children (TASK-8051).
+ * Carries `wps:cNvPr` identity after `wps:cNvSpPr` (fixture / Word order used
+ * by TASK-8051 tests). No dual AC wrapper — nested children are bare wsp.
+ *
+ * @private
+ */
+export declare function buildNestedWpsShape(input: EncodeDrawingShapeInput): OpenXmlElement;
+/**
+ * Parse wrapping from residual host placement.
+ *
+ * @private
+ */
+export declare function parseDrawingWrapping(host: OpenXmlElement, placement: DrawingHostPlacement): TextWrappingStyleType;
+/**
+ * Parse `wp:wrapSquare|wrapTight|wrapThrough/@wrapText`.
+ * Absent → Both (schema default); wire token → token; other → Unknown.
+ *
+ * @private
+ */
+export declare function parseWrapTextAttr(wrapEl: OpenXmlElement | undefined): TextWrappingTypeType;
+/**
+ * Build wrap element from modeled style.
+ * Tight/through require wrapPolygon; without residual polygon, fall back to wrapNone
+ * (library does not invent polygons — images parity).
+ * When residual matches style but modeled wire wrapType differs, rebuild with
+ * corrected wrapText and preserve residual children/attrs.
+ *
+ * @private
+ */
+export declare function buildWrapElement(wrapping: TextWrappingStyleType, residualWrap: OpenXmlElement | undefined, wrapType?: TextWrappingTypeType): OpenXmlElement;
+/**
+ * Locate residual `wp:positionH` / `wp:positionV` children of an anchor.
+ *
+ * Children are preserved as-is (unknown `@relativeFrom` tokens or extra
+ * position children stay byte-identical on rebuild that does not model them).
+ *
+ * @private
+ */
+export declare function findResidualPositions(anchor: OpenXmlElement | undefined): {
+    readonly positionH: OpenXmlElement | undefined;
+    readonly positionV: OpenXmlElement | undefined;
+};
+/**
+ * Build modeled `wp:positionH` (`CT_PosH`).
+ *
+ * Tokens: `ST_RelFromH` / `ST_AlignH` are imported, not invented (GO Q1 —
+ * `src/features/images/layout-types.ts`). Align XOR posOffset follows the
+ * `CT_PosH` schema choice. `ST_PositionOffset` is `xsd:int` (negative EMU
+ * legal). Default origin `'column'`; offset default `0` (images parity).
+ *
+ * @private
+ */
+export declare function buildDrawingPositionH(input: {
+    readonly horizontalOrigin?: HorizontalOriginType | undefined;
+    readonly horizontalPositionEmu?: Emus | undefined;
+    readonly horizontalAlignment?: HorizontalAlignmentType | undefined;
+}): OpenXmlElement;
+/**
+ * Build modeled `wp:positionV` (`CT_PosV`). Default origin `'paragraph'`;
+ * offset default `0` (images parity).
+ *
+ * @private
+ */
+export declare function buildDrawingPositionV(input: {
+    readonly verticalOrigin?: VerticalOriginType;
+    readonly verticalPositionEmu?: Emus;
+    readonly verticalAlignment?: VerticalAlignmentType;
+}): OpenXmlElement;
+/**
+ * Read wrapping, distances, behindDoc, and preset geometry from residual DrawingML.
+ *
+ * @private
+ */
+export declare function readDrawingWrapState(residual: OpenXmlElement): DrawingWrapState;
+/**
+ * Read `wp:positionH` / `wp:positionV` from residual DrawingML.
+ *
+ * Tokens are validated against images `layout-types` sets (GO Q1 import);
+ * unknown `@relativeFrom` or align text is dropped (not preserved into the
+ * typed model) so the encoder never writes an invented token.
+ *
+ * @private
+ */
+export declare function readDrawingPositionState(residual: OpenXmlElement): DrawingPositionState;
+/**
+ * Resolve effective placement from modeled wrap + requested placement.
+ * Inline wrap forces `wp:inline`; other wraps force `wp:anchor`.
+ *
+ * @private
+ */
+export declare function effectiveDrawingPlacement(placement: DrawingHostPlacement, wrapping: TextWrappingStyleType | undefined): DrawingHostPlacement;
+/**
+ * Resolve effective wrapping for encode. Anchor + Inline wrap coerces to None.
+ *
+ * @private
+ */
+export declare function effectiveDrawingWrapping(placement: DrawingHostPlacement, wrapping: TextWrappingStyleType | undefined): TextWrappingStyleType;
+/** True when any anchor-option field is explicitly modeled. */
+/**
+ * Whether the caller explicitly modeled a position mode (offset or align).
+ * Hydrated-from-residual values do NOT count: rebuilt wire must preserve the
+ * residual axis bytes untouched unless the user intervened on that axis.
+ *
+ * @private
+ */
+export declare function usedModeledPositionMode(input: EncodeDrawingShapeInput): {
+    readonly horizontal: boolean;
+    readonly vertical: boolean;
+};
+/**
+ * Read size/transform/lock from preferred DrawingML host.
+ * Public size prefers `wp:extent`; xfrm ext is residual until size dirty.
+ *
+ * @private
+ */
+export declare function readDrawingLayout(root: OpenXmlElement): DrawingLayoutState;
+/**
+ * Corpus-backed VML Fallback pict tree (Policy B dual AC — TASK-8050).
+ *
+ * Emits `w:pict` > `v:shape` with style, fill/stroke attrs, optional `v:stroke`,
+ * `w10:wrap` / `w10:anchorlock`, and `v:textbox` (cloned txbxContent) when modeled.
+ * Does not invent shapetype paths or execute VML.
+ *
+ * @private
+ */
+export declare function buildVmlFallbackStub(input: EncodeDrawingShapeInput): OpenXmlElement;
+/**
+ * Build `w:drawing` with `wp:inline` or `wp:anchor` host (Choice body only).
+ * Wrapping drives host kind: Inline ⇒ inline; other styles ⇒ anchor.
+ *
+ * @private
+ */
+export declare function buildDrawingMlHost(input: EncodeDrawingShapeInput): OpenXmlElement;
+/**
+ * Author dual AC root: Choice(wps DrawingML) + Fallback(VML pict tree).
+ * Policy B (GO Q2/Q3/Q7) — TASK-8050 corpus-backed VML Fallback.
+ *
+ * @private
+ */
+export declare function encodeAuthoredDrawingShape(input: EncodeDrawingShapeInput): OpenXmlElement;
+/**
+ * Author dual AC root for a wordprocessing group: Choice(wpg DrawingML) +
+ * Fallback(VML pict stub). Policy B — TASK-8051.
+ *
+ * Top-level graphicData uri = WPG; body is `wpg:wgp` without cNvPr.
+ * xmlns:wpg is declared on AlternateContent so Requires="wpg" resolves;
+ * xmlns:wps is kept so nested authored `wps:wsp` children resolve.
+ *
+ * @private
+ */
+export declare function encodeAuthoredGroup(input: EncodeGroupInput): OpenXmlElement;
+/**
+ * Locate preferred DrawingML `w:drawing` for typed reads.
+ * Prefer MC Choice branch when residual is AlternateContent.
+ *
+ * @private
+ */
+export declare function preferredDrawingElement(root: OpenXmlElement): OpenXmlElement | undefined;
+/**
+ * Read `wp:docPr` identity from preferred drawing host.
+ *
+ * @private
+ */
+export declare function readDocPrIdentity(root: OpenXmlElement): {
+    name: string | undefined;
+    title: string | undefined;
+    description: string | undefined;
+    docPrId: number | undefined;
+};
+/**
+ * Deep-clone residual and patch `wp:docPr` identity attributes only (identity dirty).
+ *
+ * @private
+ */
+export declare function patchResidualDocPr(residual: OpenXmlElement, identity: DrawingDocPrIdentity): OpenXmlElement;
+/**
+ * Deep-clone residual and patch layout: `wp:extent`, `a:xfrm` (rot/flip/ext),
+ * `a:graphicFrameLocks/@noChangeAspect`, and optional `wp:docPr` identity.
+ * Preserves `wp:effectExtent` and other unmodeled siblings (layout dirty path).
+ *
+ * @private
+ */
+export declare function patchResidualLayout(residual: OpenXmlElement, layout: DrawingLayoutPatch): OpenXmlElement;
+/**
+ * True when root is MC AlternateContent owned by drawing (Choice with drawing, not picture/ink).
+ *
+ * @private
+ */
+export declare function isDrawingAlternateContent(root: OpenXmlElement): boolean;
+/**
+ * True when residual is a nested bare drawing child (`wps:wsp` or `wpg:grpSp`)
+ * rather than a top-level `w:drawing` / MC host (TASK-8051). Nested identity
+ * lives on `wps:cNvPr` / `wpg:cNvPr`, not `wp:docPr`.
+ *
+ * @private
+ */
+export declare function isNestedDrawingResidual(root: OpenXmlElement): boolean;
+/**
+ * Read nested `cNvPr` identity from bare `wps:wsp` / `wpg:grpSp` residual.
+ *
+ * @private
+ */
+export declare function readCNvPrIdentity(root: OpenXmlElement): DrawingDocPrIdentity;
+/**
+ * Deep-clone nested residual and patch `cNvPr` identity attributes only
+ * (identity dirty on group/canvas children — TASK-8051).
+ *
+ * @private
+ */
+export declare function patchResidualCNvPr(residual: OpenXmlElement, identity: DrawingDocPrIdentity): OpenXmlElement;