ooxml-core 0.22.1 → 0.23.0

package/dist/pptx/chunks/smart-art-CO2jmJFf.d.ts

@@ -0,0 +1,2908 @@
+import { t as PptxThemeColorRef } from "./color-ref-DT599vEx.js";
+//#region pptx/core/types/common.d.ts
+/**
+ * Shared value types used across the entire PPTX editor type system.
+ *
+ * Contains primitive enums, small interfaces, and the XML object alias
+ * that almost every other type file imports.
+ *
+ * @module pptx-types/common
+ */
+/**
+ * Underline style tokens from OOXML `a:rPr/@u`.
+ *
+ * These map directly to the OpenXML `ST_TextUnderlineType` simple type.
+ *
+ * @example
+ * ```ts
+ * const style: UnderlineStyle = "wavy";
+ * // => "wavy" — one of: sng | dbl | heavy | dotted | dash | wavy | none | ...
+ * ```
+ */
+type UnderlineStyle = 'sng' | 'dbl' | 'heavy' | 'dotted' | 'dottedHeavy' | 'dash' | 'dashHeavy' | 'dashLong' | 'dashLongHeavy' | 'dotDash' | 'dotDashHeavy' | 'dotDotDash' | 'dotDotDashHeavy' | 'wavy' | 'wavyHeavy' | 'wavyDbl' | 'words' | 'none';
+/**
+ * Connector connection point reference — links a connector endpoint to a
+ * specific shape on the slide.
+ *
+ * When both `shapeId` and `connectionSiteIndex` are set, the connector
+ * end snaps to that shapes’s connection site and “follows” the shape when
+ * it is moved.
+ *
+ * @example
+ * ```ts
+ * const start: ConnectorConnectionPoint = {
+ *   shapeId: "shape_1",
+ *   connectionSiteIndex: 2,
+ * };
+ * // => { shapeId: "shape_1", connectionSiteIndex: 2 } satisfies ConnectorConnectionPoint
+ * ```
+ */
+interface ConnectorConnectionPoint {
+  /** ID of the shape this connector endpoint is attached to. */
+  shapeId?: string;
+  /** Connection site index on the target shape (0-based). */
+  connectionSiteIndex?: number;
+}
+/**
+ * Arrow head types for connector start/end.
+ *
+ * Maps to `a:headEnd/@type` and `a:tailEnd/@type` in OOXML.
+ *
+ * @example
+ * ```ts
+ * const arrow: ConnectorArrowType = "triangle";
+ * // => "triangle" — one of: none | triangle | stealth | diamond | oval | arrow
+ * ```
+ */
+type ConnectorArrowType = 'none' | 'triangle' | 'stealth' | 'diamond' | 'oval' | 'arrow';
+/**
+ * Stroke dash pattern types for lines and shape outlines.
+ *
+ * Maps to `a:ln/a:prstDash/@val` in OOXML. Use `"custom"` for
+ * user-defined dash/space arrays.
+ *
+ * @example
+ * ```ts
+ * const dash: StrokeDashType = "dashDot";
+ * // => "dashDot" — one of: solid | dot | dash | lgDash | dashDot | custom | ...
+ * ```
+ */
+type StrokeDashType = 'solid' | 'dot' | 'dash' | 'lgDash' | 'dashDot' | 'lgDashDot' | 'lgDashDotDot' | 'sysDot' | 'sysDash' | 'sysDashDot' | 'sysDashDotDot' | 'custom';
+/**
+ * Shadow effect properties for a single shadow layer.
+ *
+ * Represents parsed values from an `<a:outerShdw>` node. Multiple instances
+ * can be stored in {@link ShapeStyle.shadows} for compound shadow effects.
+ *
+ * @example
+ * ```ts
+ * const shadow: ShadowEffect = {
+ *   color: "#000000",
+ *   opacity: 0.4,
+ *   blur: 6,
+ *   angle: 315,
+ *   distance: 4,
+ * };
+ * // => { color: "#000000", opacity: 0.4, blur: 6, angle: 315, distance: 4 } satisfies ShadowEffect
+ * ```
+ */
+interface ShadowEffect {
+  /** Shadow color as hex string. */
+  color: string;
+  /** Shadow opacity (0-1). */
+  opacity: number;
+  /** Blur radius in pixels. */
+  blur: number;
+  /** Shadow angle in degrees (0-360). */
+  angle: number;
+  /** Shadow distance in pixels. */
+  distance: number;
+  /** Whether shadow rotates with shape. */
+  rotateWithShape?: boolean;
+}
+/**
+ * Strongly-typed parsed XML node from fast-xml-parser.
+ *
+ * The parser is configured with `attributeNamePrefix: '@_'`,
+ * `parseAttributeValue: false`, and `parseTagValue: false`, so attribute and
+ * text values are always strings at runtime. This type encodes that:
+ *
+ * - **Attributes** — keys matching `` `@_${string}` `` return
+ *   `string | undefined` directly.
+ * - **Text content** — `#text` returns `string | undefined`.
+ * - **Child elements** — any other string key returns
+ *   `XmlObject | XmlObject[] | string | undefined`. The union reflects that
+ *   fast-xml-parser may emit an object (single child), an array (repeated
+ *   children), or a bare string (text-only element collapsed by the parser).
+ *
+ * For traversal, prefer the helpers in {@link ./../utils/xml-access} —
+ * `xmlChild` / `xmlChildren` / `xmlAttr` / `xmlText` / `xmlPath` — which
+ * narrow the union and normalize the single-vs-array duality. Direct
+ * indexing works for attributes (typed as string) but chained child access
+ * (`obj['p:spPr']?.['a:xfrm']`) requires the helpers or a narrowing cast
+ * because TypeScript cannot index into the `XmlObject[] | string` part of
+ * the union.
+ */
+interface XmlObject {
+  /** Attributes (`@_`-prefixed keys) are always strings at runtime. */
+  [attr: `@_${string}`]: string | undefined;
+  /** Element text content surfaces under `#text` when present. */
+  '#text'?: string;
+  /**
+   * Child elements keyed by their (namespaced) tag name. fast-xml-parser
+   * emits a single object for unique elements, an array for repeated ones,
+   * and a bare string for elements collapsed to their text content. Use
+   * the helpers in `utils/xml-access` to narrow this union.
+   */
+  [child: string]: XmlObject | XmlObject[] | string | undefined;
+}
+/**
+ * Lock attributes from an element's non-visual properties node.
+ *
+ * When a flag is `true` the corresponding user interaction is disabled
+ * in the editor (e.g. `noRotation` prevents free rotation of the shape).
+ *
+ * One bag covers every family, but the families are NOT interchangeable in
+ * the file: `a:spLocks` (`CT_ShapeLocking`), `a:picLocks`, `a:cxnSpLocks`,
+ * `a:grpSpLocks` (`CT_GroupLocking`) and `a:graphicFrameLocks`
+ * (`CT_GraphicalObjectFrameLocking`) each declare their own attribute subset.
+ * `runtime/shape-lock-containers` holds that table and is what decides which
+ * of these fields may be written for a given element.
+ *
+ * @example
+ * ```ts
+ * const locks: PptxShapeLocks = { noMove: true, noResize: true };
+ * // => { noMove: true, noResize: true } satisfies PptxShapeLocks
+ * ```
+ */
+interface PptxShapeLocks {
+  noGrouping?: boolean;
+  noRotation?: boolean;
+  noMove?: boolean;
+  noResize?: boolean;
+  noTextEdit?: boolean;
+  noSelect?: boolean;
+  noChangeAspect?: boolean;
+  noEditPoints?: boolean;
+  noAdjustHandles?: boolean;
+  noChangeArrowheads?: boolean;
+  noChangeShapeType?: boolean;
+  /**
+   * `a:graphicFrameLocks/@noDrilldown`: forbids selecting the individual
+   * parts inside a graphic frame (a chart series, a SmartArt node). Declared
+   * ONLY by `CT_GraphicalObjectFrameLocking`, so it is written for tables,
+   * charts, SmartArt, OLE objects and graphic-frame media, and never onto
+   * `a:spLocks` / `a:picLocks` / `a:cxnSpLocks` / `a:grpSpLocks`.
+   */
+  noDrilldown?: boolean;
+  /**
+   * `a:picLocks/@noCrop`: forbids cropping the picture. Declared ONLY by
+   * `CT_PictureLocking`, so it is written for pictures (and media authored as
+   * a `p:pic`) and never onto the other lock elements.
+   */
+  noCrop?: boolean;
+  /**
+   * Text-box flag from `p:cNvSpPr/@txBox`. Not a lock in the strict sense,
+   * but it lives on the same non-visual-properties node as `a:spLocks`, so
+   * it is captured here to round-trip through the model. When `true` the
+   * shape is a plain text box (no fill/line by default).
+   */
+  txBox?: boolean;
+}
+/**
+ * A drawing guide parsed from OOXML extension lists.
+ *
+ * Slide-level and presentation-level guides are shown as thin coloured
+ * lines that help users align elements.
+ *
+ * @example
+ * ```ts
+ * const guide: PptxDrawingGuide = {
+ *   id: "g1",
+ *   orientation: "horz",
+ *   positionEmu: 457200,
+ *   color: "#FF0000",
+ * };
+ * // => { id: "g1", orientation: "horz", positionEmu: 457200, color: "#FF0000" } satisfies PptxDrawingGuide
+ * ```
+ */
+interface PptxDrawingGuide {
+  /** Unique identifier (from `@_id` attribute or generated). */
+  id: string;
+  /** Orientation: horizontal or vertical. */
+  orientation: 'horz' | 'vert';
+  /** Position in EMU (converted from pos attribute). */
+  positionEmu: number;
+  /** Optional guide colour as hex string (e.g. "#FF0000"). */
+  color?: string;
+}
+//#endregion
+//#region pptx/core/types/three-d.d.ts
+/**
+ * 3-D effect properties, text warp (WordArt) presets, and scene/shape bevel
+ * definitions parsed from OOXML `a:sp3d`, `a:scene3d`, and `a:bodyPr/a:prstTxWarp`.
+ *
+ * @module pptx-types/three-d
+ */
+/**
+ * Bevel preset type tokens from OOXML `a:bevelT/@prst` / `a:bevelB/@prst`.
+ *
+ * @example
+ * ```ts
+ * const bevel: BevelPresetType = "circle";
+ * // => "circle" — one of: "circle" | "relaxedInset" | "cross" | "coolSlant" | "angle" | …
+ * ```
+ */
+type BevelPresetType = 'circle' | 'relaxedInset' | 'cross' | 'coolSlant' | 'angle' | 'softRound' | 'convex' | 'slope' | 'divot' | 'riblet' | 'hardEdge' | 'artDeco' | 'none';
+/**
+ * Material preset type tokens from OOXML `a:sp3d/@prstMaterial`.
+ *
+ * @example
+ * ```ts
+ * const mat: MaterialPresetType = "plastic";
+ * // => "plastic" — one of: "matte" | "warmMatte" | "plastic" | "metal" | "dkEdge" | …
+ * ```
+ */
+type MaterialPresetType = 'matte' | 'warmMatte' | 'plastic' | 'metal' | 'dkEdge' | 'softEdge' | 'flat' | 'softmetal' | 'clear' | 'powder' | 'translucentPowder' | 'legacyMatte' | 'legacyPlastic' | 'legacyMetal' | 'legacyWireframe';
+/**
+ * 3D text body extrusion/bevel from `a:bodyPr/a:sp3d`.
+ *
+ * @example
+ * ```ts
+ * const text3d: Text3DStyle = {
+ *   extrusionHeight: 57150,
+ *   presetMaterial: "plastic",
+ *   bevelTopType: "circle",
+ *   bevelTopWidth: 25400,
+ *   bevelTopHeight: 25400,
+ * };
+ * // => satisfies Text3DStyle
+ * ```
+ */
+interface Text3DStyle {
+  /** Extrusion height (depth) in EMU. */
+  extrusionHeight?: number;
+  /** Extrusion colour as hex string. */
+  extrusionColor?: string;
+  /** Preset material, e.g. "matte", "plastic", "metal". */
+  presetMaterial?: MaterialPresetType;
+  /** Top bevel preset type. */
+  bevelTopType?: BevelPresetType;
+  /** Top bevel width in EMU. */
+  bevelTopWidth?: number;
+  /** Top bevel height in EMU. */
+  bevelTopHeight?: number;
+  /** Bottom bevel preset type. */
+  bevelBottomType?: BevelPresetType;
+  /** Bottom bevel width in EMU. */
+  bevelBottomWidth?: number;
+  /** Bottom bevel height in EMU. */
+  bevelBottomHeight?: number;
+}
+/**
+ * 3D scene/camera properties from `a:scene3d`.
+ *
+ * @example
+ * ```ts
+ * const scene: Pptx3DScene = {
+ *   cameraPreset: "perspectiveFront",
+ *   lightRigType: "threePt",
+ *   lightRigDirection: "t",
+ * };
+ * // => satisfies Pptx3DScene
+ * ```
+ */
+interface Pptx3DScene {
+  /** Camera preset type, e.g. "orthographicFront", "perspectiveFront". */
+  cameraPreset?: string;
+  /** Camera field of view in 1/60000 degrees (`a:camera/@fov`). */
+  cameraFieldOfView?: number;
+  /** Camera zoom as an OOXML percentage fraction (`a:camera/@zoom`, 1 = 100%). */
+  cameraZoom?: number;
+  /** Camera rotation around X axis in 1/60000 degrees. */
+  cameraRotX?: number;
+  /** Camera rotation around Y axis in 1/60000 degrees. */
+  cameraRotY?: number;
+  /** Camera rotation around Z axis in 1/60000 degrees. */
+  cameraRotZ?: number;
+  /** Light rig type, e.g. "threePt", "balanced", "harsh". */
+  lightRigType?: string;
+  /** Light rig direction, e.g. "t", "b", "l", "r", "tl". */
+  lightRigDirection?: string;
+  /** Light-rig rotation latitude in 1/60000 degrees. */
+  lightRigRotX?: number;
+  /** Light-rig rotation longitude in 1/60000 degrees. */
+  lightRigRotY?: number;
+  /** Light-rig rotation revolution in 1/60000 degrees. */
+  lightRigRotZ?: number;
+  /** Whether a 3D backdrop plane is present (`a:backdrop`). */
+  hasBackdrop?: boolean;
+  /** Backdrop plane anchor X in EMU. */
+  backdropAnchorX?: number;
+  /** Backdrop plane anchor Y in EMU. */
+  backdropAnchorY?: number;
+  /** Backdrop plane anchor Z in EMU. */
+  backdropAnchorZ?: number;
+  /** Backdrop normal vector X component. */
+  backdropNormalX?: number;
+  /** Backdrop normal vector Y component. */
+  backdropNormalY?: number;
+  /** Backdrop normal vector Z component. */
+  backdropNormalZ?: number;
+  /** Backdrop up vector X component. */
+  backdropUpX?: number;
+  /** Backdrop up vector Y component. */
+  backdropUpY?: number;
+  /** Backdrop up vector Z component. */
+  backdropUpZ?: number;
+}
+/**
+ * 3D shape extrusion/bevel from `a:sp3d`.
+ *
+ * @example
+ * ```ts
+ * const shape3d: Pptx3DShape = {
+ *   extrusionHeight: 76200,
+ *   extrusionColor: "#4F81BD",
+ *   presetMaterial: "metal",
+ *   bevelTopType: "circle",
+ *   bevelTopWidth: 12700,
+ *   bevelTopHeight: 12700,
+ * };
+ * // => satisfies Pptx3DShape
+ * ```
+ */
+interface Pptx3DShape {
+  /**
+   * Position of the shape along the Z axis, in EMU (`a:sp3d/@z`, default 0).
+   * Independent of {@link extrusionHeight}: it moves the whole shape forward
+   * or back in 3D space rather than adding depth to it, most commonly used to
+   * stack several shapes at different depths under one `a:scene3d` camera.
+   */
+  positionZ?: number;
+  /** Extrusion height in EMU. */
+  extrusionHeight?: number;
+  /** Extrusion colour. */
+  extrusionColor?: string;
+  /** Contour width in EMU. */
+  contourWidth?: number;
+  /** Contour colour. */
+  contourColor?: string;
+  /** Preset material, e.g. "matte", "warmMatte", "metal". */
+  presetMaterial?: string;
+  /** Top bevel type, e.g. "circle", "relaxedInset". */
+  bevelTopType?: string;
+  /** Top bevel width in EMU. */
+  bevelTopWidth?: number;
+  /** Top bevel height in EMU. */
+  bevelTopHeight?: number;
+  /** Bottom bevel type, e.g. "circle", "relaxedInset". */
+  bevelBottomType?: string;
+  /** Bottom bevel width in EMU. */
+  bevelBottomWidth?: number;
+  /** Bottom bevel height in EMU. */
+  bevelBottomHeight?: number;
+}
+/**
+ * Known OOXML preset text warp types (WordArt transforms).
+ *
+ * Falls back to `string` for unknown presets not yet catalogued.
+ *
+ * @example
+ * ```ts
+ * const warp: PptxTextWarpPreset = "textArchUp";
+ * // => "textArchUp" — one of: "textNoShape" | "textPlain" | "textStop" | "textArchUp" | …
+ * ```
+ */
+type PptxTextWarpPreset = 'textNoShape' | 'textPlain' | 'textStop' | 'textTriangle' | 'textTriangleInverted' | 'textChevron' | 'textChevronInverted' | 'textRingInside' | 'textRingOutside' | 'textArchUp' | 'textArchDown' | 'textCircle' | 'textButton' | 'textArchUpPour' | 'textArchDownPour' | 'textCirclePour' | 'textButtonPour' | 'textCurveUp' | 'textCurveDown' | 'textCanUp' | 'textCanDown' | 'textWave1' | 'textWave2' | 'textWave4' | 'textDoubleWave1' | 'textInflate' | 'textDeflate' | 'textInflateBottom' | 'textDeflateBottom' | 'textInflateTop' | 'textDeflateTop' | 'textFadeRight' | 'textFadeLeft' | 'textFadeUp' | 'textFadeDown' | 'textSlantUp' | 'textSlantDown' | 'textCascadeUp' | 'textCascadeDown' | 'textDeflateInflate' | 'textDeflateInflateDeflate' | string;
+//#endregion
+//#region pptx/core/types/effect-dag.d.ts
+type EffectDagBlendMode = 'darken' | 'lighten' | 'mult' | 'over' | 'screen';
+type EffectDagContainerType = 'sib' | 'tree';
+type EffectDagNode = EffectDagContainer | EffectDagBlend | EffectDagXfrm | EffectDagRelOff | EffectDagBlur | EffectDagAlphaOutset | EffectDagPresetShadow | EffectDagRawLeaf;
+interface EffectDagContainer {
+  kind: 'cont';
+  type: EffectDagContainerType;
+  name?: string;
+  children: EffectDagNode[];
+}
+interface EffectDagBlend {
+  kind: 'blend';
+  mode: EffectDagBlendMode;
+  container: EffectDagContainer;
+}
+interface EffectDagXfrm {
+  kind: 'xfrmEffect';
+  sx?: number;
+  sy?: number;
+  kx?: number;
+  ky?: number;
+  tx?: number;
+  ty?: number;
+}
+interface EffectDagRelOff {
+  kind: 'relOff';
+  tx?: number;
+  ty?: number;
+}
+/** Typed CT_BlurEffect with its original payload retained for lossless edits. */
+interface EffectDagBlur {
+  kind: 'blur';
+  radiusEmu?: number;
+  grow?: boolean;
+  xml: XmlObject;
+}
+/** Typed CT_AlphaOutsetEffect with original XML retained for lossless edits. */
+interface EffectDagAlphaOutset {
+  kind: 'alphaOutset';
+  radiusEmu?: number;
+  xml: XmlObject;
+}
+/** Typed CT_PresetShadowEffect with colour and extension XML retained verbatim. */
+interface EffectDagPresetShadow {
+  kind: 'prstShdw';
+  preset?: `shdw${number}`;
+  distanceEmu?: number;
+  direction?: number;
+  xml: XmlObject;
+}
+interface EffectDagRawLeaf {
+  kind: 'raw';
+  tag: string;
+  xml: Record<string, unknown>;
+}
+//#endregion
+//#region pptx/core/types/text.d.ts
+/**
+ * Rich text style properties for a text run or paragraph.
+ *
+ * Combines character-level formatting (font, bold, colour …),
+ * paragraph-level controls (alignment, spacing, indentation), and
+ * body-level properties (autofit, insets, text direction). All
+ * fields are optional — unset properties inherit from layout/master
+ * placeholders or theme defaults.
+ *
+ * @remarks
+ * Font sizes are stored in **points**. Spatial measurements (insets,
+ * margins) are in **pixels** (pre-converted from EMU during parsing).
+ *
+ * @example
+ * ```ts
+ * const heading: TextStyle = {
+ *   fontFamily: "Montserrat",
+ *   fontSize: 36,
+ *   bold: true,
+ *   color: "#1A1A2E",
+ *   align: "center",
+ *   lineSpacing: 1.15,
+ * };
+ *
+ * const body: TextStyle = {
+ *   fontFamily: "Open Sans",
+ *   fontSize: 14,
+ *   color: "#444444",
+ *   align: "left",
+ *   paragraphSpacingAfter: 8,
+ * };
+ * // => both satisfy the TextStyle interface
+ * ```
+ */
+/** 2D linear transform matrix `[a, b, c, d]` for inherited group orientation. */
+type TextOrientationMatrix = [number, number, number, number];
+interface TextStyle {
+  /**
+   * Combined rotation/flip matrix inherited from ancestor groups.
+   * Used only to keep descendant text readable after nested group mirrors.
+   */
+  ancestorGroupTransform?: TextOrientationMatrix;
+  /** Original `a:rPr` XML retained by projections that share the shape-text model. */
+  runPropertiesXml?: XmlObject;
+  /**
+   * The properties this run's OWN `a:rPr` authored, and nothing else.
+   *
+   * A run style is assembled as
+   * `{...inheritedRunStyle, ...authoredRunStyle}`, so the flat style is a
+   * fully RESOLVED view: it cannot say whether `fontSize: 60` came from the
+   * run, from the shape's `a:lstStyle`, from the layout placeholder, from the
+   * master `p:txStyles` or from the theme. Omission is meaningful in OOXML
+   * (§21.1.2.3), so a writer that re-emits the resolved view converts every
+   * inherited value into an authored one and the deck stops being
+   * theme-driven after one save.
+   *
+   * This is the run-scope twin of {@link TextSegment.paragraphProperties},
+   * which is parsed strictly from the paragraph's own `a:pPr` for the same
+   * reason. Present only for runs that came from a parsed deck; absent for
+   * SDK-built text, where the flat style IS the only description and must be
+   * written out in full.
+   */
+  authoredRunStyle?: TextStyle;
+  /**
+   * The resolved inheritance baseline {@link authoredRunStyle} was layered
+   * on top of (shape `a:lstStyle` -> placeholder -> layout -> master
+   * `p:txStyles` -> theme -> `p:defaultTextStyle`).
+   *
+   * Kept alongside the authored half because the two answer different
+   * questions. The authored half says "the source pinned this"; the baseline
+   * says "this value is what inheritance already produces", which is how an
+   * EDIT is told apart from an inherited value: an editor mutates the flat
+   * style without knowing about either field, so a property that now differs
+   * from the baseline was either authored or edited and must be written,
+   * while one that still matches can be left to inherit.
+   *
+   * Holds a reference to the per-paragraph baseline object rather than a
+   * copy, so carrying it costs one pointer per run.
+   */
+  inheritedRunStyle?: TextStyle;
+  /**
+   * Snapshot of the ELEMENT-scope paragraph geometry (alignment, margins,
+   * indent, line and paragraph spacing, tab stops, rtl, line-break flags) as
+   * the load pipeline resolved it.
+   *
+   * Present only on an `element.textStyle` that came from a parsed deck, and
+   * populated only with the geometry keys. It exists so the save path can
+   * answer one question it otherwise cannot: has the user CHANGED the body's
+   * alignment or indent, or is the value simply what the shape's
+   * `a:lstStyle`, its layout placeholder and the master already produce?
+   * Element-level text panels (`textAdvancedPatch`, `alignPatch` and friends
+   * in `pptx-viewer-shared`) write `element.textStyle` and never touch
+   * `segment.paragraphProperties`, so a diff against this snapshot is the
+   * only way to tell an edit from an inheritance artefact.
+   *
+   * @see element-paragraph-geometry.ts
+   */
+  resolvedParagraphGeometry?: TextStyle;
+  /**
+   * Snapshot of the ELEMENT-scope `a:bodyPr` properties (vertical anchor,
+   * text direction, columns, overflow, autofit, body insets, text wrap, and
+   * the boolean/rotation attributes) as the load pipeline resolved them.
+   *
+   * A shape's own `a:bodyPr` is parsed first, then whatever it left
+   * `undefined` is back-filled from the placeholder / layout / master
+   * defaults (`applyPlaceholderBodyDefaults`), and a placeholder shape with
+   * no `a:bodyPr` of its own has the INHERITED one parsed as if it were its
+   * own. None of those three sources is distinguishable at
+   * `element.textStyle` once the cascade finishes, so a writer that
+   * re-emits every defined field turns an inherited anchor, inset, autofit
+   * mode or `rtlCol` into a value pinned on the slide forever (and an
+   * inherited `a:normAutofit` with no scale gets written back as
+   * `a:spAutoFit`, flipping AutoSize from "shrink text" to "resize shape").
+   *
+   * Present only on an `element.textStyle` that came from a parsed deck.
+   * The save path diffs the live style against this snapshot: a field that
+   * still matches is an inheritance artefact and the writer leaves the
+   * underlying `a:bodyPr` attribute untouched (whatever it already is,
+   * present or absent); a field that differs was authored or has since
+   * been edited and is written out.
+   *
+   * @see element-body-properties.ts
+   */
+  resolvedBodyProperties?: TextStyle;
+  fontFamily?: string;
+  fontSize?: number;
+  /** When true, some form of autofit is in effect; see {@link autoFitMode} for which. */
+  autoFit?: boolean;
+  /** Explicit autofit mode from OOXML body properties.
+   * - 'shrink': `a:spAutoFit` - resize the SHAPE to fit the text (never the font)
+   * - 'normal': `a:normAutofit` - shrink the TEXT to fit the shape (via `fontScale`/`lnSpcReduction`)
+   * - 'none': `a:noAutofit` - explicitly no auto-fit (text overflows)
+   * - undefined: no autofit element present (inherit from layout/master)
+   */
+  autoFitMode?: 'shrink' | 'normal' | 'none';
+  /** Font scale percentage for normAutofit (e.g. 0.9 = 90%). Only meaningful when autoFit is true. */
+  autoFitFontScale?: number;
+  /** Line spacing reduction for normAutofit (e.g. 0.2 = reduce by 20%). Only meaningful when autoFit is true. */
+  autoFitLineSpacingReduction?: number;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  /** Specific underline style (e.g. "sng", "dbl", "wavy"). Falls back to "sng" when `underline` is true. */
+  underlineStyle?: UnderlineStyle;
+  /** Underline colour as hex string (`a:uFill` / `a:uLn`). When absent, inherits text colour. */
+  underlineColor?: string;
+  /**
+   * When true, the source authored `<a:u val="none"/>` to explicitly suppress
+   * underline (rather than omitting the attribute entirely). Preserved so the
+   * writer can re-emit the explicit `none` token instead of dropping it.
+   */
+  underlineExplicitNone?: boolean;
+  /**
+   * Underline line properties parsed from `<a:rPr><a:uLn>` — width, dash
+   * preset, and end caps. Captured as a typed object so the writer can
+   * round-trip the line styling that previously was dropped (only the
+   * solidFill colour was carried before).
+   */
+  underlineLine?: {
+    /** Line width in EMU (raw OOXML) for `a:uLn/@w`. */
+    widthEmu?: number;
+    /** Compound line type (`a:uLn/@cmpd`). */
+    compound?: string;
+    /** Cap style (`a:uLn/@cap`). */
+    cap?: string;
+    /** Pen alignment (`a:uLn/@algn`). */
+    algn?: string;
+    /** Preset dash value (`a:uLn/a:prstDash/@val`). */
+    prstDash?: string;
+    /** Raw `a:uLn/a:headEnd` XML preserved verbatim. */
+    headEndXml?: XmlObject;
+    /** Raw `a:uLn/a:tailEnd` XML preserved verbatim. */
+    tailEndXml?: XmlObject;
+  };
+  /** When `<a:uLnTx/>` is present — underline line follows the text run line. */
+  underlineLineFollowsText?: boolean;
+  /** When `<a:uFillTx/>` is present — underline fill follows the text run fill. */
+  underlineFillFollowsText?: boolean;
+  strikethrough?: boolean;
+  /** Specific strike type: single or double from `a:rPr/@strike`. */
+  strikeType?: 'sngStrike' | 'dblStrike';
+  /** Text outline width in px (`a:rPr > a:ln/@w` in EMU). */
+  textOutlineWidth?: number;
+  /** Text outline colour as hex string (`a:rPr > a:ln > a:solidFill`). */
+  textOutlineColor?: string;
+  /** Text outline dash preset (`a:rPr > a:ln > a:prstDash/@val`), e.g. `dash`; absent for solid. */
+  textOutlineDash?: string;
+  /** When true, the text body has no fill (`a:rPr > a:noFill`), producing hollow/outline-only text. */
+  textFillNone?: boolean;
+  /**
+   * When true, the run authored an EMPTY `<a:effectLst/>`: an explicit "no
+   * effects" override that blocks an inherited shadow or glow. Kept so a
+   * rewrite re-emits it instead of letting the inherited effect return.
+   */
+  textEffectsExplicitNone?: boolean;
+  /** Superscript/subscript baseline shift as percentage (`a:rPr/@baseline`). Positive = super, negative = sub. */
+  baseline?: number;
+  /** Character spacing in hundredths of a point (`a:rPr/@spc`). */
+  characterSpacing?: number;
+  /** Kerning threshold in hundredths of a point (`a:rPr/@kern`). 0 = none. */
+  kerning?: number;
+  /** Text highlight colour as hex string (`a:highlight`). */
+  highlightColor?: string;
+  /**
+   * Raw colour-choice XML preserved from `a:highlight` so a themed highlight
+   * (`a:schemeClr` / `a:sysClr` / `a:prstClr`) re-emits with its original
+   * identity rather than being flattened to `<a:srgbClr/>` on save. On save we
+   * re-emit verbatim when the resolved {@link highlightColor} still matches.
+   */
+  highlightColorXml?: XmlObject;
+  /** Text-level gradient fill CSS string (from `a:rPr > a:gradFill`). */
+  textFillGradient?: string;
+  /** Structured gradient stops for text fill round-trip serialization. */
+  textFillGradientStops?: Array<{
+    color: string;
+    position: number;
+    opacity?: number;
+  }>;
+  /** Gradient angle in degrees for text fill round-trip. */
+  textFillGradientAngle?: number;
+  /** Gradient type for text fill round-trip ('linear' | 'radial'). */
+  textFillGradientType?: 'linear' | 'radial';
+  /** Text-level pattern fill preset (from `a:rPr > a:pattFill`). */
+  textFillPattern?: string;
+  /** Text-level pattern foreground colour. */
+  textFillPatternForeground?: string;
+  /** Text-level pattern background colour. */
+  textFillPatternBackground?: string;
+  /**
+   * Raw `a:rPr > a:blipFill` XML, preserved verbatim for round-trip
+   * serialization AND as the input to the image resolution pass that fills
+   * in {@link textFillBlipUrl} (parsing a run's fill happens synchronously,
+   * with no zip/relationship access at that point; resolving the blip to a
+   * displayable URL needs both, so it happens in a later async pass over
+   * the slide's parsed elements, mirroring how a shape's OWN image fill is
+   * resolved). A picture-filled text run (`a:rPr > a:blipFill`) was
+   * documented as handled ("Handles gradient fills, pattern fills, and
+   * image fills on text runs") but never actually parsed, so it silently
+   * fell through to the run's plain `color` and rendered solid black
+   * (COM-verified: `audit-text` slide 13's "PICTURE FILL" run shows the
+   * fill image through the glyphs in PowerPoint).
+   */
+  textFillBlipXml?: XmlObject;
+  /** Resolved displayable URL for {@link textFillBlipXml}, or the archive-relative path when unresolved (lazy decode). */
+  textFillBlipUrl?: string;
+  /** Tiling mode for {@link textFillBlipUrl} (`a:blipFill/a:tile` present -> 'tile', else 'stretch'). */
+  textFillBlipMode?: 'stretch' | 'tile';
+  hyperlink?: string;
+  /** Relationship ID for the hyperlink (`a:hlinkClick/@r:id`) — preserved for round-trip serialization. */
+  hyperlinkRId?: string;
+  /** Hyperlink tooltip text (`a:hlinkClick/@tooltip`). */
+  hyperlinkTooltip?: string;
+  /** Hyperlink action type (`a:hlinkClick/@action`). */
+  hyperlinkAction?: string;
+  /** Whether the hyperlink target is an internal slide jump (targetSlideIndex style). */
+  hyperlinkTargetSlideIndex?: number;
+  color?: string;
+  /**
+   * Raw XML colour-choice node preserved from `a:rPr/a:solidFill` for
+   * round-trip serialisation. Captures `a:schemeClr` / `a:sysClr` /
+   * `a:prstClr` / `a:srgbClr` plus colour transforms. On save we re-emit
+   * verbatim when the resolved {@link color} still matches this node.
+   */
+  colorXml?: XmlObject;
+  /**
+   * Typed theme colour reference for the run's text colour, set when
+   * {@link colorXml} is a plain `a:schemeClr` (see
+   * `themeColorRefFromColorChoice`). When present it WINS on save: the
+   * writer emits `<a:schemeClr>` from this ref instead of the resolved
+   * {@link color}, so the text keeps following the theme palette after a
+   * later theme change.
+   */
+  colorRef?: PptxThemeColorRef;
+  align?: 'left' | 'center' | 'right' | 'justify' | 'justLow' | 'dist' | 'thaiDist';
+  /**
+   * Vertical text-box anchor (`a:bodyPr/@anchor`, `ST_TextAnchoringType`).
+   * `distributed`/`justified` (`dist`/`just`) stretch line spacing so the
+   * paragraph block fills the box's full vertical extent, distinct from true
+   * centering (`middle`/`ctr`); both approximate to a middle-anchored render
+   * (see `text-body-layout.ts`) since CSS has no native vertical-justify
+   * primitive, but round-trip losslessly through parse/save.
+   */
+  vAlign?: 'top' | 'middle' | 'bottom' | 'distributed' | 'justified';
+  /** Right-to-left paragraph/run direction (`a:pPr/@rtl`, `a:rPr/@rtl`). */
+  rtl?: boolean;
+  /** Body text direction (`a:bodyPr/@vert`).
+   *
+   * Values map to OOXML `a:bodyPr/@vert` attribute values:
+   * - `"horizontal"` — default horizontal text (`horz`)
+   * - `"vertical"` — standard vertical text, right-to-left columns (`vert`)
+   * - `"vertical270"` — text rotated 270 degrees (`vert270`)
+   * - `"eaVert"` — East Asian vertical text with CJK glyphs upright (`eaVert`)
+   * - `"wordArtVert"` — WordArt vertical, each character upright stacked (`wordArtVert`)
+   * - `"wordArtVertRtl"` — WordArt vertical, right-to-left direction (`wordArtVertRtl`)
+   * - `"mongolianVert"` — Mongolian vertical text, left-to-right columns (`mongolianVert`)
+   */
+  textDirection?: 'horizontal' | 'vertical' | 'vertical270' | 'eaVert' | 'wordArtVert' | 'wordArtVertRtl' | 'mongolianVert';
+  /** Body column count (`a:bodyPr/@numCol`). */
+  columnCount?: number;
+  /** Column spacing in px (`a:bodyPr/@spcCol` in EMU). */
+  columnSpacing?: number;
+  /** Horizontal overflow mode from `a:bodyPr/@hOverflow`. */
+  hOverflow?: 'overflow' | 'clip';
+  /** Vertical overflow mode from `a:bodyPr/@vertOverflow`. */
+  vertOverflow?: 'overflow' | 'clip' | 'ellipsis';
+  /** Body text left inset in px (`a:bodyPr/@lIns` in EMU). */
+  bodyInsetLeft?: number;
+  /** Body text top inset in px (`a:bodyPr/@tIns` in EMU). */
+  bodyInsetTop?: number;
+  /** Body text right inset in px (`a:bodyPr/@rIns` in EMU). */
+  bodyInsetRight?: number;
+  /** Body text bottom inset in px (`a:bodyPr/@bIns` in EMU). */
+  bodyInsetBottom?: number;
+  /** Paragraph spacing before in px. */
+  paragraphSpacingBefore?: number;
+  /** Paragraph spacing after in px. */
+  paragraphSpacingAfter?: number;
+  /** Line spacing multiplier (e.g. 1.2 = 120%). Used when mode is proportional (spcPct). */
+  lineSpacing?: number;
+  /** Exact line spacing in points (from `a:lnSpc > a:spcPts`). Takes priority over `lineSpacing` when set. */
+  lineSpacingExactPt?: number;
+  /** Paragraph left margin in px (`a:pPr/@marL` in EMU). */
+  paragraphMarginLeft?: number;
+  /** Paragraph right margin in px (`a:pPr/@marR` in EMU). */
+  paragraphMarginRight?: number;
+  /** Paragraph first-line indent in px (`a:pPr/@indent` in EMU). */
+  paragraphIndent?: number;
+  /** Tab stop positions and alignments (`a:pPr/a:tabLst/a:tab`). */
+  tabStops?: Array<{
+    position: number;
+    align: 'l' | 'ctr' | 'r' | 'dec';
+    leader?: 'none' | 'dot' | 'hyphen' | 'underscore';
+    /**
+     * True when the source spelled out the schema-default `@algn="l"`, so the
+     * writer re-emits it instead of treating it as an omitted default.
+     */
+    alignAuthored?: boolean;
+    /** True when the source spelled out the schema-default `@leader="none"`. */
+    leaderAuthored?: boolean;
+  }>;
+  /**
+   * True when the paragraph's own `a:pPr` authored an EMPTY `<a:tabLst/>`
+   * (explicitly "no tab stops", overriding whatever the cascade would
+   * otherwise supply) rather than omitting the element entirely (inherit).
+   * fast-xml-parser gives a childless element as the empty string, so
+   * `tabLst` and no-`tabLst` are otherwise indistinguishable once `tabStops`
+   * comes back empty either way. Paragraph-scope only; not part of the
+   * element-level geometry cascade.
+   */
+  tabStopsExplicitEmpty?: boolean;
+  /** Body text wrapping mode from `a:bodyPr/@wrap`. */
+  textWrap?: 'square' | 'none';
+  /** Preset text warp type from `a:bodyPr/a:prstTxWarp`. */
+  textWarpPreset?: PptxTextWarpPreset;
+  /** Primary adjustment value for text warp (from `a:prstTxWarp/a:avLst/a:gd` with name "adj").
+   *  Stored as raw OOXML 1/60000th units (e.g. 50000 = default for many presets). */
+  textWarpAdj?: number;
+  /** Secondary adjustment value for text warp (from `a:prstTxWarp/a:avLst/a:gd` with name "adj2").
+   *  Stored as raw OOXML 1/60000th units. */
+  textWarpAdj2?: number;
+  /** Text capitalization style from `a:rPr/@cap`. */
+  textCaps?: 'all' | 'small' | 'none';
+  /**
+   * When true, the source authored `<a:rPr cap="none"/>` explicitly. This
+   * differs from {@link textCaps} = `"none"` only because the writer must
+   * preserve the explicit token rather than collapse it to omission.
+   */
+  textCapsExplicitNone?: boolean;
+  /** Symbol font family from `a:sym`. */
+  symbolFont?: string;
+  /** East Asian font family from `a:ea`. */
+  eastAsiaFont?: string;
+  /** Complex Script font family from `a:cs`. */
+  complexScriptFont?: string;
+  /**
+   * Theme-font token (`+mj-lt` / `+mn-lt` / ...) authored on `a:latin`, when
+   * present. {@link fontFamily} holds the resolved concrete face for
+   * rendering; this preserves the token linkage so the writer re-emits the
+   * token rather than the flattened face (see #84).
+   */
+  latinFontThemeToken?: string;
+  /** Theme-font token authored on `a:ea` (e.g. `+mn-ea`), when present. */
+  eastAsiaFontThemeToken?: string;
+  /** Theme-font token authored on `a:cs` (e.g. `+mn-cs`), when present. */
+  complexScriptFontThemeToken?: string;
+  /**
+   * Automatic per-script fallback face resolved from the theme's
+   * `<a:font script="...">` overrides for a run whose text is dominantly
+   * CJK / Arabic / Hebrew / Thai (see #83). A rendering hint only: it is not
+   * serialised back on save, so it never disturbs the round-trip typefaces.
+   */
+  scriptFallbackFont?: string;
+  /**
+   * Set alongside {@link scriptFallbackFont} when the resolved {@link fontFamily}
+   * came only from the paragraph/list-style/theme CASCADE (the run's own
+   * `a:rPr` authored no `a:latin`/`a:ea`/`a:cs` of its own). A run always
+   * inherits SOME font this way (typically the theme's `+mn-lt`), so without
+   * this flag `fontFamily` was indistinguishable from a run that genuinely
+   * chose that font itself, and the renderer never applied the theme's
+   * per-script override (see #83): `+mn-lt` names only the LATIN member of
+   * the font scheme and was never meant to cover text in a different
+   * dominant script. An explicit `a:latin`/`a:ea`/`a:cs` authored on the run
+   * itself still always wins; only the cascade default yields to the
+   * script-specific override.
+   */
+  fontFamilyIsCascadeDefault?: boolean;
+  /** Text language from `a:rPr/@lang`. */
+  language?: string;
+  /** Hyperlink mouse-over target from `a:hlinkMouseOver`. */
+  hyperlinkMouseOver?: string;
+  /**
+   * Raw `a:snd` (embedded WAV audio) child of `a:hlinkClick`, preserved
+   * verbatim (carries `@r:embed` + `@name`). Round-tripped on save so the
+   * click sound survives instead of being dropped.
+   */
+  hyperlinkSoundXml?: XmlObject;
+  /** Raw `a:snd` child of `a:hlinkMouseOver`, preserved verbatim for round-trip. */
+  hyperlinkMouseOverSoundXml?: XmlObject;
+  /** Hyperlink invalidUrl attribute (`a:hlinkClick/@invalidUrl`). */
+  hyperlinkInvalidUrl?: string;
+  /** Hyperlink target frame (`a:hlinkClick/@tgtFrame`). */
+  hyperlinkTargetFrame?: string;
+  /** Whether hyperlink history is tracked (`a:hlinkClick/@history`). */
+  hyperlinkHistory?: boolean;
+  /** Whether hyperlink uses highlight-click effect (`a:hlinkClick/@highlightClick`). */
+  hyperlinkHighlightClick?: boolean;
+  /** Whether hyperlink ends a sound (`a:hlinkClick/@endSnd`). */
+  hyperlinkEndSound?: boolean;
+  /**
+   * Raw `a:hlinkClick/a:extLst` child, preserved verbatim for round-trip.
+   * Carries vendor extensions this engine does not interpret, most commonly
+   * `ahyp:hlinkClr` (Microsoft's "hyperlink color" extension,
+   * `{A12FA001-AC4F-418D-AE19-62706E023703}`), which records whether a
+   * hyperlink run should paint with the theme's text colour instead of the
+   * hyperlink colour. Dropping the whole `a:extLst` silently reverted such a
+   * run to the default (themed) hyperlink colour on save.
+   */
+  hyperlinkExtensionXml?: XmlObject;
+  /** Kumimoji (ideographic text combining) flag for vertical CJK text (`a:rPr/@kumimoji`). */
+  kumimoji?: boolean;
+  /** Normalize height flag (`a:rPr/@normalizeH`). */
+  normalizeHeight?: boolean;
+  /** No proofing flag (`a:rPr/@noProof`). */
+  noProof?: boolean;
+  /** Dirty flag indicating run has been edited (`a:rPr/@dirty`). */
+  dirty?: boolean;
+  /** Error flag indicating spelling error (`a:rPr/@err`). */
+  spellingError?: boolean;
+  /** Smart tag clean flag (`a:rPr/@smtClean`). */
+  smartTagClean?: boolean;
+  /** Bookmark link target (`a:rPr/@bmk`). */
+  bookmark?: string;
+  /** Alternative language for the run (`a:rPr/@altLang`). Populated for runs
+   *  authored in mixed-script documents (e.g. Asian/Latin combined). */
+  altLanguage?: string;
+  /** SmartTag (Office grammar tag) GUID id (`a:rPr/@smtId`). Round-tripped
+   *  verbatim — the engine doesn't interpret it. */
+  smartTagId?: number;
+  /** Latin font PANOSE classification string from `a:rPr > a:latin/@panose`. */
+  latinFontPanose?: string;
+  /** Latin font pitch + family flag from `a:rPr > a:latin/@pitchFamily`. */
+  latinFontPitchFamily?: number;
+  /** Latin font character set id from `a:rPr > a:latin/@charset`. */
+  latinFontCharset?: number;
+  /** East-Asian font PANOSE from `a:rPr > a:ea/@panose`. */
+  eastAsiaFontPanose?: string;
+  /** East-Asian font pitch + family flag from `a:rPr > a:ea/@pitchFamily`. */
+  eastAsiaFontPitchFamily?: number;
+  /** East-Asian font character set id from `a:rPr > a:ea/@charset`. */
+  eastAsiaFontCharset?: number;
+  /** Complex-script font PANOSE from `a:rPr > a:cs/@panose`. */
+  complexScriptFontPanose?: string;
+  /** Complex-script font pitch + family flag from `a:rPr > a:cs/@pitchFamily`. */
+  complexScriptFontPitchFamily?: number;
+  /** Complex-script font character set id from `a:rPr > a:cs/@charset`. */
+  complexScriptFontCharset?: number;
+  /** Symbol-font PANOSE from `a:rPr > a:sym/@panose`. */
+  symbolFontPanose?: string;
+  /** Symbol-font pitch + family flag from `a:rPr > a:sym/@pitchFamily`. */
+  symbolFontPitchFamily?: number;
+  /** Symbol-font character set id from `a:rPr > a:sym/@charset`. */
+  symbolFontCharset?: number;
+  /** Paragraph list type for toggling bullet / numbered lists via the toolbar.
+   * - `'bullet'` — character bullet (default "•")
+   * - `'numbered'` — auto-numbered list (arabicPeriod)
+   * - `'none'` — explicitly no list
+   */
+  listType?: 'bullet' | 'numbered' | 'none';
+  /** Default tab size in px (`a:pPr/@defTabSz` in EMU). */
+  defaultTabSize?: number;
+  /** East Asian line break flag (`a:pPr/@eaLnBrk`). */
+  eaLineBreak?: boolean;
+  /** Latin line break flag (`a:pPr/@latinLnBrk`). */
+  latinLineBreak?: boolean;
+  /** Font alignment (`a:pPr/@fontAlgn`): 'auto' | 'base' | 'ctr' | 't' | 'b'. */
+  fontAlignment?: string;
+  /** Hanging punctuation flag (`a:pPr/@hangingPunct`). */
+  hangingPunctuation?: boolean;
+  /** Whether to space first and last paragraph from body edges (`a:bodyPr/@spcFirstLastPara`). */
+  spaceFirstLastParagraph?: boolean;
+  /** Right-to-left column flow (`a:bodyPr/@rtlCol`). */
+  rtlColumns?: boolean;
+  /** Whether text originates from WordArt (`a:bodyPr/@fromWordArt`). */
+  fromWordArt?: boolean;
+  /** Whether text anchoring is centered (`a:bodyPr/@anchorCtr`). */
+  anchorCenter?: boolean;
+  /** Force anti-aliasing (`a:bodyPr/@forceAA`). */
+  forceAntiAlias?: boolean;
+  /** Upright text in 3D views (`a:bodyPr/@upright`). */
+  upright?: boolean;
+  /** Compatible line spacing flag (`a:bodyPr/@compatLnSpc`). */
+  compatibleLineSpacing?: boolean;
+  /**
+   * Text body rotation in **degrees** (`a:bodyPr/@rot`).
+   *
+   * OOXML stores the value as 60000ths of a degree. Positive values rotate
+   * the body clockwise. When undefined, the attribute is omitted on save
+   * (PowerPoint treats absent `rot` as inherit/none).
+   */
+  textBodyRotation?: number;
+  /** Text shadow colour as hex string (`a:outerShdw`). */
+  textShadowColor?: string;
+  /** Text shadow blur radius in px. */
+  textShadowBlur?: number;
+  /** Text shadow horizontal offset in px. */
+  textShadowOffsetX?: number;
+  /** Text shadow vertical offset in px. */
+  textShadowOffsetY?: number;
+  /** Text shadow opacity (0-1). */
+  textShadowOpacity?: number;
+  /** Text inner shadow colour (`a:innerShdw`). */
+  textInnerShadowColor?: string;
+  /** Text inner shadow opacity (0-1). */
+  textInnerShadowOpacity?: number;
+  /** Text inner shadow blur radius in px. */
+  textInnerShadowBlur?: number;
+  /** Text inner shadow horizontal offset in px. */
+  textInnerShadowOffsetX?: number;
+  /** Text inner shadow vertical offset in px. */
+  textInnerShadowOffsetY?: number;
+  /**
+   * Original inner-shadow colour-choice XML (`a:innerShdw`'s
+   * `a:prstClr`/`a:schemeClr`/`a:srgbClr`/… child), preserved verbatim so an
+   * authored preset or theme colour round-trips instead of always being
+   * re-serialized as a resolved `a:srgbClr`. Mirrors {@link textGlowColorXml}.
+   */
+  textInnerShadowColorXml?: XmlObject;
+  /** Theme colour slot the inner shadow colour resolved from, when it is `a:schemeClr`. */
+  textInnerShadowColorRef?: PptxThemeColorRef;
+  /** Preset shadow type from `a:prstShdw/@prst` (e.g. "shdw1"..."shdw20"). */
+  textPresetShadowName?: string;
+  /** Preset shadow colour as hex string. */
+  textPresetShadowColor?: string;
+  /** Preset shadow opacity (0-1). */
+  textPresetShadowOpacity?: number;
+  /** Preset shadow distance in px. */
+  textPresetShadowDistance?: number;
+  /** Preset shadow direction in degrees. */
+  textPresetShadowDirection?: number;
+  /** Text blur effect radius in px (`a:blur`). */
+  textBlurRadius?: number;
+  /**
+   * Text soft-edge radius in px (`a:softEdge/@rad`).
+   *
+   * Feathers the glyph's own edges (a uniform blur of the alpha silhouette,
+   * the same effect a shape's `a:softEdge` gives its fill), unrelated to
+   * `a:blur` (which blurs the whole run, colour included) or a shadow. Never
+   * parsed before this field existed, so `a:softEdge` on a run was silently
+   * dropped: PowerPoint fades the glyphs to near-transparent at their
+   * outline (COM-verified, `audit-text` slide 14's "SOFTEDGE" run), while
+   * the viewer painted them fully crisp.
+   */
+  textSoftEdgeRadius?: number;
+  /**
+   * Raw `a:effectDag` XML node from `a:rPr`, preserved verbatim for
+   * round-trip serialisation. Mirrors the shape-level
+   * {@link import('./shape-style').ShapeStyle.effectDagXml} field.
+   */
+  textEffectDagXml?: XmlObject;
+  /**
+   * Typed effect graph parsed from `textEffectDagXml`. The four structural
+   * container nodes (`a:cont`, `a:blend`, `a:xfrmEffect`, `a:relOff`) are
+   * fully typed; any other leaf effect is captured as
+   * {@link import('./effect-dag').EffectDagRawLeaf} so we never have to
+   * recurse into the full effect taxonomy.
+   */
+  textEffectDagTree?: EffectDagContainer;
+  /** Text alpha modulation fixed (0-100) from `a:alphaModFix`. */
+  textAlphaModFix?: number;
+  /** Text alpha modulation from `a:alphaMod` (0-100 percentage). */
+  textAlphaMod?: number;
+  /** Text hue shift in degrees from `a:hsl/@hue`. */
+  textHslHue?: number;
+  /** Text saturation adjustment from `a:hsl/@sat`. */
+  textHslSaturation?: number;
+  /** Text luminance adjustment from `a:hsl/@lum`. */
+  textHslLuminance?: number;
+  /** Text colour change from colour as hex string (`a:clrChange`). */
+  textClrChangeFrom?: string;
+  /** Text colour change to colour as hex string. */
+  textClrChangeTo?: string;
+  /** Text duotone colour pair (`a:duotone`). */
+  textDuotone?: {
+    color1: string;
+    color2: string;
+  };
+  /** Text glow colour as hex string (`a:glow`). */
+  textGlowColor?: string;
+  /** Text glow radius in px. */
+  textGlowRadius?: number;
+  /** Text glow opacity (0-1). */
+  textGlowOpacity?: number;
+  /**
+   * Original glow colour-choice XML (`a:glow`'s `a:schemeClr`/`a:srgbClr`/…
+   * child), preserved verbatim so a theme colour reference round-trips
+   * instead of always being re-serialized as a resolved `a:srgbClr` (which
+   * cuts the glow off from theme/Recolor changes).
+   */
+  textGlowColorXml?: XmlObject;
+  /** Theme colour slot the glow colour resolved from, when it is `a:schemeClr`. */
+  textGlowColorRef?: PptxThemeColorRef;
+  /** Text reflection enabled flag. */
+  textReflection?: boolean;
+  /** Text reflection blur radius in px. */
+  textReflectionBlur?: number;
+  /** Text reflection start opacity (0-1). */
+  textReflectionStartOpacity?: number;
+  /** Text reflection end opacity (0-1). */
+  textReflectionEndOpacity?: number;
+  /** Text reflection offset distance in px. */
+  textReflectionOffset?: number;
+  /**
+   * Text reflection end position (`@endPos`) as a 0-1 fraction of the text
+   * height the fade reaches. Mirrors `ShapeStyle.reflectionEndPosition`.
+   */
+  textReflectionEndPosition?: number;
+  /**
+   * Text reflection offset direction (`@dir`) in degrees. Mirrors
+   * `ShapeStyle.reflectionDirection`.
+   */
+  textReflectionDirection?: number;
+  /**
+   * Text reflection fade direction (`a:rPr/a:effectLst/a:reflection/@fadeDir`)
+   * in degrees. Mirrors `ShapeStyle.reflectionFadeDirection`.
+   */
+  textReflectionFadeDirection?: number;
+  /**
+   * Text reflection horizontal scaling (`@sx`), same units as
+   * `ShapeStyle.reflectionScaleX` (1000ths of a percent, e.g. 100000 = 100%).
+   */
+  textReflectionScaleX?: number;
+  /** Text reflection vertical scaling (`@sy`). See `ShapeStyle.reflectionScaleY`. */
+  textReflectionScaleY?: number;
+  /**
+   * Text reflection horizontal skew (`@kx`) in 60000ths of a degree. See
+   * `ShapeStyle.reflectionSkewX`.
+   */
+  textReflectionSkewX?: number;
+  /** Text reflection vertical skew (`@ky`). See `ShapeStyle.reflectionSkewY`. */
+  textReflectionSkewY?: number;
+  /**
+   * Text reflection independent rotation (`@rot`) in degrees. See
+   * `ShapeStyle.reflectionRotation`.
+   */
+  textReflectionRotation?: number;
+  /** Text reflection anchor (`@algn`). See `ShapeStyle.reflectionAlignment`. */
+  textReflectionAlignment?: 'tl' | 't' | 'tr' | 'l' | 'ctr' | 'r' | 'bl' | 'b' | 'br';
+  /** 3D extrusion/bevel settings on the text body. */
+  text3d?: Text3DStyle;
+  /** 3D scene (camera + light rig) settings on the text body (`a:bodyPr/a:scene3d`). */
+  textBodyScene3d?: Pptx3DScene;
+  /** Raw `a:scene3d` subtree used to preserve extensions and unmodelled children. */
+  textBodyScene3dXml?: XmlObject;
+  /**
+   * `a:bodyPr/a:flatTx` - an explicit "render this text flat" marker. `sp3d`
+   * and `flatTx` are a mutually exclusive OOXML choice (`EG_Text3D`), so a
+   * shape/run that overrides an inherited 3D text body with `<a:flatTx/>`
+   * carries no `text3d` of its own; without this explicit flag a later
+   * inheritance merge has no signal to stop `text3d`/`textBodyScene3d` from
+   * an ancestor (layout/master) leaking back in, the way `noFill` stops an
+   * inherited fill. A renderer must short-circuit 3D-text application
+   * whenever this is `true`, regardless of what `text3d`/`textBodyScene3d`
+   * otherwise hold.
+   */
+  flatText?: boolean;
+  /**
+   * Raw `<a:extLst>` subtree captured from `<a:bodyPr>`. Preserved verbatim so
+   * authored extensions (e.g. content placeholders, custom application data)
+   * survive a round-trip even though the engine doesn't interpret them.
+   */
+  bodyPropertiesExtLstXml?: XmlObject;
+  /**
+   * Raw `<a:extLst>` subtree captured from `<a:pPr>`. Only meaningful on the
+   * paragraph-level style (paragraphs propagate this via the first segment).
+   */
+  paragraphPropertiesExtLstXml?: XmlObject;
+  /**
+   * Raw `<a:extLst>` subtree captured from `<a:rPr>`. Persisted verbatim on
+   * save when present — covers run-level extensions the typed model doesn't
+   * model (e.g. `a14:hiddenFill` and similar).
+   */
+  runPropertiesExtLstXml?: XmlObject;
+  /**
+   * Raw `<a:defRPr>` XML node captured from `<a:pPr>`. The schema permits
+   * `defRPr` directly inside `pPr` so that paragraph defaults can specify the
+   * end-paragraph run formatting; previously this was dropped on save. We
+   * persist the parsed XML object so it round-trips verbatim.
+   *
+   * Only meaningful on the *first* segment of each paragraph (matches the
+   * convention used for {@link bulletInfo} / {@link endParaRunProperties}).
+   */
+  paragraphDefaultRunPropertiesXml?: XmlObject;
+  /**
+   * The bullet colour / size / typeface children (`a:buClrTx`, `a:buClr`,
+   * `a:buSzTx`, `a:buSzPct`, `a:buSzPts`, `a:buFontTx`, `a:buFont`) a
+   * paragraph authored in its own `<a:pPr>` WITHOUT a bullet type
+   * (`a:buNone` / `a:buChar` / `a:buAutoNum` / `a:buBlip`), captured
+   * verbatim in source order. Such a paragraph restyles an inherited bullet
+   * rather than declaring one, so its {@link BulletInfo} resolves from the
+   * cascade and is (correctly) not written back; without this capture the
+   * paragraph's own override vanished on every rewrite.
+   *
+   * Only meaningful on a paragraph's own authored properties.
+   */
+  paragraphBulletPropertiesXml?: XmlObject;
+}
+/**
+ * Structured bullet metadata attached to the first {@link TextSegment}
+ * of each paragraph.
+ *
+ * Describes how the paragraph bullet should render: character bullets
+ * (`char`), auto-numbered lists (`autoNumType`), or picture bullets
+ * (`imageRelId` / `imageDataUrl`). Set `none: true` when `a:buNone`
+ * explicitly suppresses the bullet.
+ *
+ * @example
+ * ```ts
+ * // Simple character bullet:
+ * const bullet: BulletInfo = { char: "•", color: "#333333" };
+ *
+ * // Auto-numbered list starting at 1:
+ * const numbered: BulletInfo = {
+ *   autoNumType: "arabicPeriod",
+ *   autoNumStartAt: 1,
+ * };
+ * // => { char: "•", color: "#333333" } and { autoNumType: "arabicPeriod", autoNumStartAt: 1 }
+ * ```
+ */
+interface BulletInfo {
+  /** Bullet character (e.g. "•", "-", "»") from `a:buChar`. */
+  char?: string;
+  /** Auto-numbering type (e.g. "arabicPeriod", "romanUcPeriod") from `a:buAutoNum`. */
+  autoNumType?: string;
+  /** Auto-numbering start value. */
+  autoNumStartAt?: number;
+  /**
+   * Auto-numbering ORDINAL OFFSET: the zero-based distance of this paragraph
+   * within its own numbered list, such that
+   * `autoNumStartAt + paragraphIndex` is the ordinal to render. Despite the
+   * name it is NOT the paragraph's position in the text body; the two agree
+   * only for a list that starts at the first paragraph and is never
+   * interrupted.
+   *
+   * It has to be the offset rather than the raw position because every
+   * consumer that re-derives a marker from `BulletInfo` alone (the renderer's
+   * `resolveParagraphBullet`, the Markdown converter's `resolveListMarker`)
+   * computes `autoNumStartAt + paragraphIndex`. The load path resolves the
+   * real sequence itself, restarting the count after any paragraph that
+   * interrupts the list, and publishes the offset here so those consumers
+   * land on the same number. With the raw position they did not, and BOTH
+   * markers were painted ("3.1. Item"), because the paragraph builder drops
+   * the parsed marker segment only when the two strings agree.
+   *
+   * Runtime-only: derived at parse time and never serialized. OOXML has no
+   * counterpart (`a:buAutoNum` carries only `@type` and `@startAt`), so the
+   * writer neither reads nor emits it.
+   */
+  paragraphIndex?: number;
+  /** Bullet font family from `a:buFont`. */
+  fontFamily?: string;
+  /**
+   * PANOSE font-matching hint from `a:buFont/@panose`. `a:buFont` is a
+   * CT_TextFont, the same complex type as `a:latin`/`a:ea`/`a:cs`/`a:sym`
+   * (which carry the equivalent `TextStyle.latinFontPanose` etc.), so a
+   * bullet's own PANOSE/pitch-family/charset decide the fallback glyph
+   * PowerPoint substitutes when the named typeface is missing.
+   */
+  fontPanose?: string;
+  /** Font pitch-and-family byte from `a:buFont/@pitchFamily`. */
+  fontPitchFamily?: number;
+  /** Font character-set byte from `a:buFont/@charset`. */
+  fontCharset?: number;
+  /** Bullet size as percentage of text font size from `a:buSzPct`. */
+  sizePercent?: number;
+  /** Bullet size in points from `a:buSzPts`. */
+  sizePts?: number;
+  /** Bullet color as hex string from `a:buClr`. */
+  color?: string;
+  /**
+   * Raw colour-choice XML captured from `<a:buClr>` so that themed bullets
+   * (`a:schemeClr`, `a:sysClr`, `a:prstClr`) round-trip with their original
+   * identity rather than being flattened to `<a:srgbClr/>` on save.
+   */
+  colorXml?: XmlObject;
+  /**
+   * Typed theme colour reference for the bullet colour, set when
+   * {@link colorXml} is a plain `a:schemeClr`. Wins on save, same as
+   * {@link TextStyle.colorRef}.
+   */
+  colorRef?: PptxThemeColorRef;
+  /** True when `a:buNone` explicitly suppresses bullets. */
+  none?: boolean;
+  /** Picture bullet: relationship ID from `a:buBlip` → `a:blip[@r:embed]`. */
+  imageRelId?: string;
+  /** Picture bullet: data URL of the embedded image. */
+  imageDataUrl?: string;
+  /**
+   * Raw `<a:buBlip>` XML captured at parse time. Carries the full blipFill
+   * subtree (`a:tile`, `a:stretch`, `a:srcRect`, `a:blip > a:extLst`) so the
+   * writer can emit the complete original definition rather than the bare
+   * `a:blip[@r:embed]` mapping. When set, the writer prefers it over
+   * {@link imageRelId} for emission.
+   */
+  imageBlipFillXml?: XmlObject;
+  /** When true, `<a:buFontTx/>` was specified — inherit the bullet font from
+   *  the run text, not from a buFont declaration. */
+  fontInherit?: boolean;
+  /** When true, `<a:buClrTx/>` was specified — inherit the bullet colour from
+   *  the run text. */
+  colorInherit?: boolean;
+  /** When true, `<a:buSzTx/>` was specified — inherit the bullet size from
+   *  the run text font size. */
+  sizeInherit?: boolean;
+  /**
+   * True when this bullet resolution came from the paragraph's OWN `a:pPr`
+   * rather than the shape's `a:lstStyle`, an inherited placeholder, or the
+   * master's `a:defPPr` / `p:txStyles`. `resolveParagraphBulletInfo` walks
+   * that cascade and returns the first match, so without this flag a
+   * writer that re-emits every resolved `BulletInfo` in full pins an
+   * inherited bullet (e.g. a master `buFont="Arial"` / `buChar="•"`) onto
+   * every paragraph's own `a:pPr` the moment the slide is rewritten. The
+   * save path only writes the bullet group when this is `true`, mirroring
+   * how `paragraphProperties` gates every other per-paragraph field.
+   */
+  ownedByParagraph?: boolean;
+}
+/**
+ * A single text run within a paragraph.
+ *
+ * A text body is decomposed into an array of `TextSegment` objects,
+ * each with its own style. Paragraph breaks are represented as
+ * segments with `isParagraphBreak: true`.
+ *
+ * @example
+ * ```ts
+ * const segments: TextSegment[] = [
+ *   { text: "Bold intro ", style: { bold: true, fontSize: 16 } },
+ *   { text: "and normal text.", style: { fontSize: 16 } },
+ *   { text: "", style: {}, isParagraphBreak: true },
+ *   { text: "Second paragraph.", style: { fontSize: 14 } },
+ * ];
+ * // => 4 segments: 2 styled runs, 1 paragraph break, 1 normal run
+ * ```
+ */
+interface TextSegment {
+  text: string;
+  style: TextStyle;
+  /** When this segment originated from an `a:fld` element, stores the field type (e.g. "slidenum", "datetime"). */
+  fieldType?: string;
+  /** When this segment originated from an `a:fld` element, stores the field GUID. */
+  fieldGuid?: string;
+  /**
+   * Original attribute name used to author the field GUID — `'uuid'` for the
+   * `a:fld/@uuid` form authored by some legacy producers, `'id'` for the
+   * canonical `a:fld/@id` form. Preserved so the writer round-trips whichever
+   * spelling the source used (PowerPoint accepts both). Defaults to `'id'`
+   * on save when undefined.
+   */
+  fieldGuidAttr?: 'uuid' | 'id';
+  /**
+   * Raw per-field paragraph properties (`a:fld > a:pPr`). The schema permits
+   * `pPr` inside an `a:fld` so the field can carry its own paragraph-level
+   * formatting; preserved verbatim on save when present.
+   */
+  fieldParagraphPropertiesXml?: XmlObject;
+  /** Raw OMML XML node for equation segments (from `a14:m` / `m:oMathPara`). */
+  equationXml?: Record<string, unknown>;
+  /**
+   * The ORIGINAL top-level paragraph child that carried this equation,
+   * captured verbatim at parse time and keyed by its own tag: `{ 'a14:m':
+   * ... }`, `{ 'm:oMathPara': ... }`, `{ 'm:oMath': ... }`, or `{
+   * 'mc:AlternateContent': ... }` for an equation authored behind a
+   * Choice/Fallback switch. `equationXml` above is the resolved math content
+   * used for rendering (unwrapped one level for `a14:m`/`mc:AlternateContent`
+   * sources); this field exists solely so the writer can re-emit an UNTOUCHED
+   * equation byte-for-byte, Choice and Fallback both, instead of collapsing
+   * it to a bare math element PowerPoint's own writer never produces.
+   * `undefined` for a freshly inserted or edited equation, which the writer
+   * instead reconstructs from `equationXml` (always `{ 'm:oMathPara': ... }`
+   * or `{ 'm:oMath': ... }` for those cases). Any code that replaces
+   * `equationXml` on an existing segment must drop this field, or the writer
+   * would keep re-emitting the equation's OLD XML instead of the edit.
+   */
+  equationSourceXml?: Record<string, unknown>;
+  /**
+   * Optional equation number for numbered equations (e.g. "(1)", "(2.3)").
+   * When present, the equation is rendered centered with the number right-aligned.
+   */
+  equationNumber?: string;
+  /** Whether this segment represents a paragraph break rather than renderable text. */
+  isParagraphBreak?: boolean;
+  /**
+   * Whether this segment represents a soft line break (`a:br`) rather than
+   * a paragraph terminator. Soft line breaks remain inside the same paragraph
+   * but force a line wrap and may carry their own run properties.
+   *
+   * The renderer should treat the segment text as `"\n"` when present.
+   */
+  isLineBreak?: true;
+  /**
+   * Raw `a:rPr` XML for an `a:br` (soft line break) segment, captured verbatim
+   * during parse so the writer can re-emit attributes/colours/fonts that the
+   * typed model doesn't represent. Only meaningful when {@link isLineBreak}
+   * is `true`.
+   */
+  breakRunProperties?: Record<string, unknown>;
+  /** Structured bullet info for the first segment of a paragraph. */
+  bulletInfo?: BulletInfo;
+  /**
+   * Outline level for the paragraph this segment starts (`a:p/@lvl`).
+   *
+   * Only meaningful on the first segment of a paragraph (matching the
+   * convention used for {@link bulletInfo}). Stored as the raw OOXML
+   * value (0 = top level, 1-8 = nested) and serialised back when non-zero.
+   */
+  paragraphLevel?: number;
+  /**
+   * Raw `a:endParaRPr` XML node for the paragraph this segment starts.
+   *
+   * Captured verbatim on parse so attributes and child colours/fonts that
+   * the typed model doesn't represent survive a round-trip. Only meaningful
+   * on the first segment of a paragraph.
+   */
+  endParaRunProperties?: Record<string, unknown>;
+  /**
+   * Resolved body defaults and optional `a:endParaRPr` of a runless paragraph.
+   * Carried on its first segment (or terminator), separately from marker
+   * styling. Absent when the source contains an authored run or field.
+   */
+  paragraphInsertionStyle?: TextStyle;
+  /**
+   * Per-paragraph properties (alignment, spacing, margins, indent, tab stops,
+   * rtl) authored on this paragraph's own `a:pPr` (#69). Only meaningful on
+   * the first segment of a paragraph. When present, the writer emits these
+   * per paragraph instead of collapsing one shape-level pPr onto every
+   * paragraph. Only the paragraph-geometry keys of {@link TextStyle} are
+   * populated; unrelated fields fall back to the shape-level style.
+   */
+  paragraphProperties?: TextStyle;
+  /**
+   * The paragraph this segment starts authored an EMPTY `<a:pPr/>`. Only
+   * meaningful on the first segment of a paragraph. The writer re-emits the
+   * empty element when it has no paragraph property of its own to write, so
+   * a rewritten slide keeps the markup PowerPoint wrote.
+   */
+  emptyParagraphPropertiesAuthored?: boolean;
+  /**
+   * The paragraph this segment starts has no run content and authored no
+   * `a:endParaRPr` (a bare `<a:p/>`, possibly with an `a:pPr`). Only
+   * meaningful on the first segment of a paragraph. It stops the writer
+   * inventing an empty run or an `<a:endParaRPr lang="en-US"/>` stub for a
+   * paragraph that still has no content when saved.
+   */
+  bareParagraph?: boolean;
+  /**
+   * Phonetic annotation text from `a:ruby > a:rt` (e.g. furigana, pinyin).
+   * When present, the renderer should wrap the base text with an HTML `<ruby>` tag.
+   */
+  rubyText?: string;
+  /**
+   * Ruby text alignment from `a:rubyPr > @val` attribute.
+   * Values: "ctr" (center), "l" (left), "r" (right), "dist" (distribute), "distCat", "distLetter".
+   * @default "ctr"
+   */
+  rubyAlignment?: string;
+  /**
+   * Ruby text font size as a percentage of the base text font size
+   * from `a:rubyPr/@hps` (half-point size) or inferred from rt run font size.
+   * Stored in **points** for consistency with `TextStyle.fontSize`.
+   */
+  rubyFontSize?: number;
+  /**
+   * Style for the ruby (phonetic) text run, parsed from `a:rt > a:r > a:rPr`.
+   * Used by the renderer to apply font family, colour, etc. to the `<rt>` element.
+   */
+  rubyStyle?: TextStyle;
+  /**
+   * The parsed `a:rubyPr` node, kept verbatim so its attributes (`hps`,
+   * `hpsRaise`, `hpsBaseText`, `lid`, ...) round-trip exactly; only an
+   * edited {@link rubyAlignment} is written over it on save.
+   */
+  rubyPropertiesXml?: XmlObject;
+  /**
+   * What each of a ruby run's two base-side `a:rPr`s authored on its own:
+   * `outer` is the containing `a:r`'s, `base` the `a:rubyBase` run's. The
+   * flat {@link style} merges both for rendering; these let the writer give
+   * each `a:rPr` back only its own properties (plus any later edit).
+   */
+  rubyRunAuthoredStyles?: {
+    outer?: TextStyle;
+    base?: TextStyle;
+  };
+}
+//#endregion
+//#region pptx/core/types/geometry.d.ts
+/**
+ * Geometry types: adjustment handles, custom geometry points, segments,
+ * paths, and custom path properties.
+ *
+ * @module pptx-types/geometry
+ */
+/**
+ * Defines an adjustment handle position for a shape geometry.
+ *
+ * Adjustment handles allow users to interactively reshape preset shapes
+ * (e.g. rounding a rectangle corner or adjusting arrow head width).
+ *
+ * @example
+ * ```ts
+ * const handle: GeometryAdjustmentHandle = {
+ *   guideName: "adj",
+ *   xFraction: 0.25,
+ *   minValue: 0,
+ *   maxValue: 50000,
+ * };
+ * // => satisfies GeometryAdjustmentHandle
+ * ```
+ */
+interface GeometryAdjustmentHandle {
+  /** Name of the adjustment guide this handle controls (e.g. "adj", "adj1"). */
+  guideName: string;
+  /** X position as a fraction of shape width (0..1), or undefined if the handle only moves vertically. */
+  xFraction?: number;
+  /** Y position as a fraction of shape height (0..1), or undefined if the handle only moves horizontally. */
+  yFraction?: number;
+  /** Minimum allowed value for the adjustment guide. */
+  minValue?: number;
+  /** Maximum allowed value for the adjustment guide. */
+  maxValue?: number;
+}
+/**
+ * A single point in a custom geometry path.
+ *
+ * @example
+ * ```ts
+ * const pt: CustomGeometryPoint = { x: 100, y: 200 };
+ * // => satisfies CustomGeometryPoint
+ * ```
+ */
+interface CustomGeometryPoint {
+  x: number;
+  y: number;
+}
+/**
+ * A segment within a custom geometry path.
+ *
+ * Discriminated union over `type` — can be a moveTo, lineTo,
+ * cubic Bézier, quadratic Bézier, or close command.
+ *
+ * @example
+ * ```ts
+ * const segments: CustomGeometrySegment[] = [
+ *   { type: "moveTo", pt: { x: 0, y: 0 } },
+ *   { type: "lineTo", pt: { x: 100, y: 0 } },
+ *   { type: "lineTo", pt: { x: 100, y: 100 } },
+ *   { type: "close" },
+ * ];
+ * // => satisfies CustomGeometrySegment[]
+ * ```
+ */
+type CustomGeometrySegment = {
+  type: 'moveTo';
+  pt: CustomGeometryPoint;
+} | {
+  type: 'lineTo';
+  pt: CustomGeometryPoint;
+} | {
+  type: 'cubicBezTo';
+  pts: [CustomGeometryPoint, CustomGeometryPoint, CustomGeometryPoint];
+} | {
+  type: 'quadBezTo';
+  pts: [CustomGeometryPoint, CustomGeometryPoint];
+} | {
+  type: 'arcTo';
+  /** Horizontal radius of the ellipse. */
+  wR: number;
+  /** Vertical radius of the ellipse. */
+  hR: number;
+  /** Start angle in 60000ths of a degree. */
+  stAng: number;
+  /** Sweep angle in 60000ths of a degree. */
+  swAng: number;
+} | {
+  type: 'close';
+};
+/**
+ * A single sub-path in a custom geometry definition (maps to one `a:path`).
+ *
+ * @example
+ * ```ts
+ * const path: CustomGeometryPath = {
+ *   width: 100,
+ *   height: 100,
+ *   segments: [
+ *     { type: "moveTo", pt: { x: 0, y: 0 } },
+ *     { type: "lineTo", pt: { x: 100, y: 100 } },
+ *   ],
+ * };
+ * // => satisfies CustomGeometryPath
+ * ```
+ */
+interface CustomGeometryPath {
+  /** Coordinate-space width for this sub-path. */
+  width: number;
+  /** Coordinate-space height for this sub-path. */
+  height: number;
+  /** Ordered list of drawing segments. */
+  segments: CustomGeometrySegment[];
+  /** Path fill mode (`a:path/@fill`): norm, lighten, lightenLess, darken, darkenLess, none. */
+  fillMode?: 'norm' | 'lighten' | 'lightenLess' | 'darken' | 'darkenLess' | 'none';
+  /** Whether the path is stroked (`a:path/@stroke`). */
+  stroke?: boolean;
+  /** 3D extrusion compatibility (`a:path/@extrusionOk`). */
+  extrusionOk?: boolean;
+}
+/**
+ * Auxiliary raw XML preserved from `a:custGeom` for round-trip serialization.
+ * These are stored opaquely so adjustment guides, handles, connection sites,
+ * and the text rectangle are not lost when a custGeom is edited and saved.
+ */
+interface CustomGeometryRawData {
+  /** Raw `a:avLst` XML content (adjustment value list). */
+  avLstXml?: unknown;
+  /** Raw `a:gdLst` XML content (guide list). */
+  gdLstXml?: unknown;
+  /** Raw `a:ahLst` XML content (adjustment handles). */
+  ahLstXml?: unknown;
+  /** Raw `a:cxnLst` XML content (connection sites). */
+  cxnLstXml?: unknown;
+  /** Raw `a:rect` XML content (text rectangle). */
+  rectXml?: unknown;
+  /**
+   * Raw `a:pathLst` XML content: every `a:path`'s formula-bearing `a:pt`
+   * x/y attributes, `a:arcTo` params, `a:close`, and per-path `@w`/`@h`/
+   * `@fill`/`@stroke`/`@extrusionOk`, preserved verbatim (not the
+   * parse-time-resolved numbers in `customGeometryPaths`). Lets a live
+   * `shapeAdjustments` drag re-evaluate the outline against the CURRENT
+   * guide values instead of the ones baked in at parse time; see
+   * `geometry/custom-geometry-live-eval.ts`.
+   */
+  pathLstXml?: unknown;
+}
+/**
+ * XY-style adjustment handle (`a:ahXY`) on a custom geometry.
+ *
+ * Allows interactive editing of one or two guide values constrained to a
+ * rectangular range. Coordinates are formula references (e.g. `"adj1"`,
+ * `"w/2"`, `"0"`) preserved verbatim so they can re-emit unchanged.
+ *
+ * @example
+ * ```ts
+ * const handle: AdjustHandleXY = {
+ *   gdRefX: "adj1",
+ *   minX: "0",
+ *   maxX: "w",
+ *   posX: "adj1",
+ *   posY: "h/2",
+ * };
+ * // => satisfies AdjustHandleXY
+ * ```
+ */
+interface AdjustHandleXY {
+  /** Guide reference for the X axis (`@_gdRefX`). */
+  gdRefX?: string;
+  /** Guide reference for the Y axis (`@_gdRefY`). */
+  gdRefY?: string;
+  /** Minimum X value, as a formula reference (`@_minX`). */
+  minX?: string;
+  /** Maximum X value (`@_maxX`). */
+  maxX?: string;
+  /** Minimum Y value (`@_minY`). */
+  minY?: string;
+  /** Maximum Y value (`@_maxY`). */
+  maxY?: string;
+  /** Handle position X (formula or literal) from `a:pos/@_x`. */
+  posX?: string;
+  /** Handle position Y from `a:pos/@_y`. */
+  posY?: string;
+}
+/**
+ * Polar-style adjustment handle (`a:ahPolar`) on a custom geometry.
+ *
+ * Drives a guide via radial distance and angle rather than XY coordinates.
+ *
+ * @example
+ * ```ts
+ * const handle: AdjustHandlePolar = {
+ *   gdRefR: "adj1",
+ *   gdRefAng: "adj2",
+ *   posX: "wd2",
+ *   posY: "hd2",
+ * };
+ * // => satisfies AdjustHandlePolar
+ * ```
+ */
+interface AdjustHandlePolar {
+  /** Guide reference for the radial distance (`@_gdRefR`). */
+  gdRefR?: string;
+  /** Guide reference for the angle (`@_gdRefAng`). */
+  gdRefAng?: string;
+  /** Minimum radial value (`@_minR`). */
+  minR?: string;
+  /** Maximum radial value (`@_maxR`). */
+  maxR?: string;
+  /** Minimum angle (`@_minAng`). */
+  minAng?: string;
+  /** Maximum angle (`@_maxAng`). */
+  maxAng?: string;
+  /** Handle position X from `a:pos/@_x`. */
+  posX?: string;
+  /** Handle position Y from `a:pos/@_y`. */
+  posY?: string;
+}
+/**
+ * Connection site (`a:cxn`) on a custom geometry.
+ *
+ * Defines a point on a custom shape that connectors may snap to.
+ *
+ * @example
+ * ```ts
+ * const cxn: ConnectionSite = { ang: "0", posX: "0", posY: "hd2" };
+ * // => satisfies ConnectionSite
+ * ```
+ */
+interface ConnectionSite {
+  /** Approach angle (`@_ang`) — formula or literal degree-1/60000 value. */
+  ang?: string;
+  /** Site position X from `a:pos/@_x`. */
+  posX?: string;
+  /** Site position Y from `a:pos/@_y`. */
+  posY?: string;
+}
+/**
+ * Typed text rectangle (`a:rect`) on a custom geometry.
+ *
+ * Each edge is the formula or literal string preserved from the source XML
+ * (`"l"`, `"t"`, `"r"`, `"b"`, or any guide name / formula).
+ */
+interface CustomGeometryTextRect {
+  /** Left edge formula reference (`@_l`). */
+  l?: string;
+  /** Top edge (`@_t`). */
+  t?: string;
+  /** Right edge (`@_r`). */
+  r?: string;
+  /** Bottom edge (`@_b`). */
+  b?: string;
+}
+/**
+ * Custom (non-preset) geometry path — only on shapes and pictures.
+ *
+ * Contains SVG path data and/or structured custom geometry paths
+ * parsed from `a:custGeom/a:pathLst`.
+ *
+ * @example
+ * ```ts
+ * const custom: PptxCustomPathProperties = {
+ *   pathData: "M 0 0 L 100 0 L 100 100 Z",
+ *   pathWidth: 100,
+ *   pathHeight: 100,
+ * };
+ * // => satisfies PptxCustomPathProperties
+ * ```
+ */
+interface PptxCustomPathProperties {
+  /** SVG path data for custom shapes. */
+  pathData?: string;
+  /** Coordinate-space width for the custom path. */
+  pathWidth?: number;
+  /** Coordinate-space height for the custom path. */
+  pathHeight?: number;
+  /** Structured custom geometry paths for editing (maps to a:custGeom/a:pathLst). */
+  customGeometryPaths?: CustomGeometryPath[];
+  /** Raw adjustment/guide/handle/connection/text-rectangle XML preserved for serialization. */
+  customGeometryRawData?: CustomGeometryRawData;
+  /**
+   * Typed XY adjustment handles parsed from `a:custGeom/a:ahLst/a:ahXY`.
+   * SDK-built shapes can populate this and the writer will emit `<a:ahXY>` entries
+   * even when no raw XML was preserved.
+   */
+  customGeometryAdjustHandlesXY?: AdjustHandleXY[];
+  /**
+   * Typed polar adjustment handles parsed from `a:custGeom/a:ahLst/a:ahPolar`.
+   */
+  customGeometryAdjustHandlesPolar?: AdjustHandlePolar[];
+  /**
+   * Typed connection sites parsed from `a:custGeom/a:cxnLst/a:cxn`.
+   */
+  customGeometryConnectionSites?: ConnectionSite[];
+  /**
+   * Typed text rectangle parsed from `a:custGeom/a:rect`. When present this is
+   * preferred over {@link customGeometryRawData}'s `rectXml` on save.
+   */
+  customGeometryTextRect?: CustomGeometryTextRect;
+}
+//#endregion
+//#region diagram/types.d.ts
+/** Resolved SmartArt layout family. */
+type DiagramLayoutType = 'list' | 'process' | 'cycle' | 'hierarchy' | 'relationship' | 'matrix' | 'pyramid' | 'funnel' | 'gear' | 'target' | 'timeline' | 'venn' | 'chevron' | 'bending' | 'unknown';
+/** SmartArt colour scheme presets. */
+type DiagramColorScheme = 'colorful1' | 'colorful2' | 'colorful3' | 'monochromatic1' | 'monochromatic2';
+/** SmartArt visual style intensity. */
+type DiagramStyleIntensity = 'flat' | 'moderate' | 'intense';
+/** A connection (`dgm:cxn`) between two data-model points. */
+interface DiagramConnection {
+  /** Stable CT_Cxn model identifier. */
+  modelId?: string | null;
+  sourceId: string;
+  destId: string;
+  /** `parOf` (the schema default when omitted), `presOf`, `presParOf`, `unknownRelationship`. */
+  type?: string;
+  srcOrd?: number;
+  destOrd?: number;
+  /** Model ID of the parent transition point associated with this edge. */
+  parentTransitionId?: string | null;
+  /** Model ID of the sibling transition point associated with this edge. */
+  siblingTransitionId?: string | null;
+  /** Layout presentation identifier used by presentation connections. */
+  presentationId?: string | null;
+  /** Text typed onto the linked `parTrans`/`sibTrans` transition point, when it carries any. */
+  label?: string;
+}
+/** Manual layout overrides (`dgm:prSet/@cust*`) a user applied to a presentation point. */
+interface DiagramNodeCustomLayout {
+  /** `custAng`: additional rotation in degrees. */
+  angle?: number;
+  scaleX?: number;
+  scaleY?: number;
+  sizeX?: number;
+  sizeY?: number;
+  flipHorizontal?: boolean;
+  flipVertical?: boolean;
+  linearFactorX?: number;
+  linearFactorY?: number;
+  linearFactorNeighborX?: number;
+  linearFactorNeighborY?: number;
+  radialScaleRadius?: number;
+  radialScaleIncrement?: number;
+  hasCustomTransform?: boolean;
+}
+//#endregion
+//#region pptx/core/types/smart-art-chrome.d.ts
+/**
+ * Background / outline extracted from `dgm:bg` and `dgm:whole`.
+ *
+ * @example
+ * ```ts
+ * const chrome: PptxSmartArtChrome = {
+ *   backgroundColor: "#F0F0F0",
+ *   outlineColor: "#333333",
+ *   outlineWidth: 1,
+ * };
+ * // => satisfies PptxSmartArtChrome
+ * ```
+ */
+interface PptxSmartArtChrome {
+  /**
+   * Background fill colour (hex). When the real `dgm:bg` fill is a gradient
+   * or pattern (see {@link PptxSmartArtChrome.backgroundFillXml}), this is an
+   * APPROXIMATION (the gradient's first stop, or the pattern's foreground
+   * colour) for a consumer that only wants one display colour, not the full fill.
+   */
+  backgroundColor?: string;
+  /**
+   * Raw `dgm:bg` fill XML, present only when the background is a gradient or
+   * pattern fill (a solid fill is fully captured by {@link PptxSmartArtChrome.backgroundColor}
+   * alone). Round-trip only: `smartart-save-chrome.ts` re-emits this verbatim
+   * instead of flattening the fill to a solid colour on save.
+   */
+  backgroundFillXml?: PptxSmartArtRawBackgroundFill;
+  /** Outline stroke colour (hex). */
+  outlineColor?: string;
+  /** Outline stroke width in points. */
+  outlineWidth?: number;
+}
+/**
+ * A `dgm:bg` fill this viewer doesn't fully model as first-class chrome
+ * (gradient or pattern), preserved verbatim for round-trip. See
+ * {@link PptxSmartArtChrome.backgroundFillXml}.
+ */
+interface PptxSmartArtRawBackgroundFill {
+  /** Local element name of the fill under `dgm:bg` (`gradFill` or `pattFill`). */
+  localName: 'gradFill' | 'pattFill';
+  /** The fill element's own attributes/children, as parsed. */
+  xml: XmlObject;
+}
+//#endregion
+//#region pptx/core/types/smart-art-constraint-rules.d.ts
+type PptxSmartArtConstraintRelationship = 'self' | 'ch' | 'des';
+type PptxSmartArtConstraintOperator = 'none' | 'equ' | 'gte' | 'lte';
+type PptxSmartArtConstraintPointType = 'all' | 'doc' | 'node' | 'norm' | 'nonNorm' | 'asst' | 'nonAsst' | 'parTrans' | 'pres' | 'sibTrans';
+interface PptxSmartArtConstraintTarget {
+  for?: PptxSmartArtConstraintRelationship;
+  forName?: string;
+  pointType?: PptxSmartArtConstraintPointType;
+}
+/** Editable DiagramML CT_Constraint. */
+interface PptxSmartArtConstraint extends PptxSmartArtConstraintTarget {
+  type: string;
+  referenceType?: string;
+  referenceFor?: PptxSmartArtConstraintRelationship;
+  referenceForName?: string;
+  referencePointType?: PptxSmartArtConstraintPointType;
+  operator?: PptxSmartArtConstraintOperator;
+  value?: number;
+  factor?: number;
+  /** Original constraint retained for foreign attributes and extension content. */
+  rawXml?: XmlObject;
+}
+/** Editable DiagramML CT_NumericRule. */
+interface PptxSmartArtNumericRule extends PptxSmartArtConstraintTarget {
+  type: string;
+  value?: number;
+  factor?: number;
+  max?: number;
+  /** Original rule retained for foreign attributes and extension content. */
+  rawXml?: XmlObject;
+}
+//#endregion
+//#region pptx/core/types/smart-art-layout-primitives.d.ts
+interface PptxSmartArtLocalizedText {
+  value: string;
+  language?: string;
+}
+interface PptxSmartArtLayoutCategory {
+  type: string;
+  priority: number;
+}
+interface PptxSmartArtAlgorithmParameter {
+  type: string;
+  value?: string;
+}
+/** Typed DiagramML CT_Algorithm data attached to a layout node. */
+interface PptxSmartArtLayoutAlgorithm {
+  type: string;
+  revision?: number;
+  parameters?: PptxSmartArtAlgorithmParameter[];
+}
+interface PptxSmartArtIteratorAttributes {
+  name?: string;
+  reference?: string;
+  axis?: string[];
+  pointTypes?: string[];
+  hideLastTransition?: boolean[];
+  start?: number[];
+  count?: number[];
+  step?: number[];
+}
+interface PptxSmartArtForEach extends PptxSmartArtIteratorAttributes {
+  rawXml?: XmlObject;
+}
+interface PptxSmartArtWhen extends PptxSmartArtIteratorAttributes {
+  function: string;
+  argument?: string;
+  operator: string;
+  value: string;
+  rawXml?: XmlObject;
+}
+interface PptxSmartArtChoose {
+  name?: string;
+  when: PptxSmartArtWhen[];
+  otherwise?: {
+    name?: string;
+    rawXml?: XmlObject;
+  } | null;
+  rawXml?: XmlObject;
+}
+/** A single `dgm:adj/@val` adjustment, keyed by its `@idx` (1-based, like `a:gd`). */
+interface PptxSmartArtShapeAdjustment {
+  index: number;
+  value: number;
+}
+/**
+ * Typed DiagramML CT_Shape data (`dgm:shape`) attached to a layout node: the
+ * per-node preset geometry override real (and third-party/custom) layout
+ * definitions use so a layoutNode can be e.g. an ellipse or a chevron instead
+ * of the arranger family's hardcoded default shape.
+ */
+interface PptxSmartArtLayoutNodeShape {
+  /** `dgm:shape/@type`: a preset geometry name (`roundRect`, `ellipse`, `chevron`, `conn`, ...). */
+  presetGeometry?: string;
+  /** `dgm:adjLst/dgm:adj` entries (adjustment index -> value, as authored). */
+  adjustments?: PptxSmartArtShapeAdjustment[];
+  /** `dgm:shape/@hideGeom`: the shape is present only to size text, never painted. */
+  hideGeometry?: boolean;
+  /**
+   * `dgm:shape/@lkTxEntry` (CT_Shape, boolean, default false): this node is a
+   * decorative shape that should mirror its paired content node's text
+   * rather than always rendering blank. See `smartart-layout-interpreter-
+   * pyramid.ts`'s `arrangePyramid`, the interpreter's one existing
+   * synthesized-decorative-shape call site.
+   */
+  lkTxEntry?: boolean;
+}
+//#endregion
+//#region pptx/core/types/smart-art-layout-definition.d.ts
+/** Identity and ordering metadata from DiagramML CT_LayoutNode. */
+interface PptxSmartArtLayoutNode {
+  name?: string;
+  styleLabel?: string;
+  childOrder?: 'b' | 't';
+  moveWith?: string;
+  algorithm?: PptxSmartArtLayoutAlgorithm;
+  forEach?: PptxSmartArtForEach[];
+  choose?: PptxSmartArtChoose[];
+  constraints?: PptxSmartArtConstraint[];
+  rules?: PptxSmartArtNumericRule[];
+  /** `dgm:shape`: this node's own preset geometry override, when present. */
+  shape?: PptxSmartArtLayoutNodeShape;
+  /**
+   * `dgm:presOf` (CT_PresentationOf, same iterator shape as `dgm:forEach`):
+   * which data-model point(s) this node's OWN text/geometry binds to -
+   * `axis: ['self']` the point currently being iterated, `['des']` all of
+   * its descendants, `['ch']` its direct children, and so on. Absent or
+   * empty `axis` (including a bare `<dgm:presOf/>`) means the node carries
+   * no text of its own (a pure positioning/decoration wrapper - `composite`,
+   * `sp` spacer, connector cap). See `smartart-layout-interpreter-item-
+   * roles.ts`, the one consumer: it is what lets the interpreter tell a
+   * text-bearing per-item role (a list layout's `childText`, a card
+   * layout's `roleText`/`bodyText`) apart from a same-generation sibling
+   * that positions or decorates instead.
+   */
+  presentationOf?: PptxSmartArtIteratorAttributes;
+  /**
+   * EVERY `dgm:constr` reachable from this node, including ones declared
+   * inside a `dgm:choose`/`dgm:if`/`dgm:else` that wraps THIS layoutNode's
+   * `constrLst` (a genuinely conditional constraint set, e.g. one branch
+   * per data-point count - `gear`'s composite positions its `gear1`/
+   * `gear2`/`gear3` slots this way, so its plain, direct-child-only
+   * `constraints` above is empty for it). Stops at a nested `dgm:layoutNode`
+   * boundary: that child's own conditional constrLst becomes ITS
+   * `allConstraints`, not folded into the parent's. Read-only /
+   * interpretation-only - `constraints` above (this node's own DIRECT
+   * constrLst) remains the one `applySmartArtLayoutDefinition` round-trips,
+   * so editing an unrelated property can never collapse a genuinely
+   * conditional constrLst into a single branch. `undefined` when this node
+   * declares no constrLst at all, in or out of a choose (the common case);
+   * otherwise a superset of `constraints` (every branch, blindly unioned -
+   * this interpreter does not evaluate `dgm:choose` conditions when
+   * indexing constraints, matching the same "flatten both branches"
+   * convention `nestedLayoutNodes` already uses for `children`). See
+   * `smartart-constraint-solver.ts`'s `buildConstraintIndex`, the only
+   * consumer.
+   */
+  allConstraints?: PptxSmartArtConstraint[];
+  children?: PptxSmartArtLayoutNode[];
+  /**
+   * The iterator attributes of the ENCLOSING `dgm:forEach` this node was
+   * found through, when `nestedLayoutNodes` (`smartart-layout-definition
+   * .ts`) reached it by walking one - as opposed to being a direct child of
+   * its parent layoutNode, or reached only through a `dgm:choose` wrapper
+   * (a condition, not an iteration, leaves this `undefined`).
+   *
+   * `forEach` above records a node's OWN direct `dgm:forEach` children
+   * (which wrap ITS descendants); this is the opposite direction - the
+   * forEach that wraps the node ITSELF, one level up. A layoutNode can sit
+   * inside more than one enclosing forEach only via nesting, so this is
+   * always the SINGLE nearest one, not a list.
+   *
+   * This is what tells a genuinely repeated per-child template
+   * (`axis="ch"`, `ptType` absent or `"node"`) apart from a once-only or
+   * transition-only sibling that merely happens to sit inside SOME
+   * `dgm:forEach` (a `ptType="parTrans"`/`"sibTrans"` connector, or
+   * `axis="followSib" cnt="1"`) - both can be direct siblings under the
+   * SAME parent layoutNode (`lProcess1`'s `vertFlow` has one forEach for
+   * its `parTrans` connector and a SEPARATE one, `axis="ch"`, for its
+   * repeated `child` items; `vertFlow.forEach` bundles both, but only
+   * `child.forEachOrigin` says which ONE produced it). See
+   * `smartart-layout-interpreter-item-roles-recursive.ts`, the one
+   * consumer. Read-only / interpretation-only, like `allConstraints`:
+   * never round-tripped by `applySmartArtLayoutDefinition`.
+   */
+  forEachOrigin?: PptxSmartArtIteratorAttributes;
+  /**
+   * The conditions of EVERY enclosing `dgm:if` this node was found through,
+   * outermost first, when `nestedLayoutNodes` (`smartart-layout-
+   * definition.ts`) reached it via one or more `dgm:choose`'s `if` branches
+   * (as opposed to a direct child, a `dgm:else` branch contributing no
+   * condition of its own - see below - or a `dgm:forEach`, which sets
+   * {@link forEachOrigin} instead). ALL must hold (evaluate `!== false`,
+   * per {@link chooseGuard}'s own AND semantics - see `evaluateWhen`) for
+   * this node's branch to be genuinely live. A caller that already has the
+   * data-model node list can use this instead of treating every
+   * choose-flattened branch as unconditionally present
+   * (`nestedLayoutNodes`' pre-existing "flatten every branch" convention,
+   * still the default when this is absent or a caller does not evaluate
+   * it) - e.g. `cycle-matrix--fallback-n2.pptx`'s `child1group`..
+   * `child4group`, each gated on a DIFFERENT top-level point existing and
+   * having its own child (`axis="ch ch" st="N 1" cnt="1 0" func="cnt"
+   * op="gte" val="1"`).
+   *
+   * A CHAIN, not a single condition, because a node can sit inside NESTED
+   * `dgm:choose`s whose OWN conditions are each individually necessary -
+   * `sub-step-process--hier5.pptx`'s `chLin1`..`chLin7` each sit inside
+   * BOTH an outer `dgm:if func="pos" op="equ" val="N"` (which one of the
+   * 7 hand-duplicated per-position templates this is) AND an inner,
+   * nearly-vacuous `dgm:if func="cnt" op="gte" val="1"` (has >= 1 point at
+   * all) - keeping only the NEAREST (inner) one, as an earlier single-
+   * condition design did, loses the ONE piece of information (the outer
+   * `pos` guard) that actually discriminates `chLin1` from `chLin2`.
+   *
+   * A `dgm:else` branch contributes NO condition of its own (ECMA-376
+   * defines it as "none of the sibling ifs matched", which would need the
+   * FULL sibling list's conditions negated and ANDed together, not a
+   * single condition - no gallery fixture measured needs an else branch's
+   * own guard yet, so it is left unconditional, matching the pre-existing
+   * flatten-everything behaviour) but does NOT clear any OUTER ancestor
+   * guard already accumulated before it. Evaluate with `smartart-layout-
+   * interpreter-when.ts`'s `evaluateWhen`, once per entry, ANDed.
+   */
+  chooseGuard?: PptxSmartArtWhen[];
+  /**
+   * ROUND 42: the forEach iterator active WHEN EACH ENTRY of {@link
+   * chooseGuard} was declared (index-parallel with it, `undefined` per
+   * entry when no forEach was active at that point) - NOT the same as
+   * {@link forEachOrigin}, which is always this NODE's own single nearest
+   * enclosing forEach, however deep. A `dgm:if` declared ABOVE a `dgm:forEach`
+   * that this node's own branch happens to descend through afterwards needs
+   * ITS OWN, SHALLOWER anchor for a `func="cnt"`/`"maxDepth"`-family
+   * `@axis` condition, not this node's deeper one - `funnel--flat3.pptx`'s
+   * `item1`/`item2`/`item3` (`chooseGuard: [Name5's axis="ch" func="cnt"
+   * op="gte" val="1"]`, declared directly under the composite root, BEFORE
+   * each item's own per-item `dgm:forEach axis="ch" st="2"/"3"/"4" cnt="1"`)
+   * is exactly this shape: evaluating Name5's condition anchored to item1's
+   * OWN forEach binding (one specific data point, with no children of its
+   * own in a flat dataset) wrongly resolves its `axis="ch"` child count to
+   * 0 instead of the diagram's real top-level count, dropping the item
+   * entirely - `chooseGuardOrigins[i]` for that entry is `undefined`
+   * (Name5 sits above ANY forEach), so the guard correctly stays
+   * root-relative. See `smartart-layout-interpreter-composite-
+   * candidates.ts`'s `guardAllows`, the one production consumer.
+   * `undefined` whenever {@link chooseGuard} itself is (no enclosing
+   * choose at all).
+   */
+  chooseGuardOrigins?: (PptxSmartArtIteratorAttributes | undefined)[];
+  /**
+   * The chain of every enclosing `dgm:choose`'s own GROUP identity + this
+   * node's ordinal position within it + THAT branch's own condition,
+   * outermost first - identifies WHICH `dgm:choose` instance and WHERE
+   * within its own `dgm:if`/`dgm:else` list this node's branch sits, unlike
+   * {@link chooseGuard} (a flat AND-chain of every condition with no group/
+   * position identity, and no entry at all for a `dgm:else` branch, which
+   * has no condition of its own - see that field's doc comment). `id` is a
+   * synthetic, process-unique identifier assigned per `dgm:choose` instance
+   * during flattening (`smartart-layout-definition-nesting.ts`'s
+   * `nestedLayoutNodes`, a monotonic counter - NOT round-tripped, NOT the
+   * choose's own `@_name`, which is not guaranteed unique across a whole
+   * layoutDef); `ordinal` is 0-based document order within that ONE choose
+   * (every `dgm:if` in order, then `dgm:else` last, if present); `guard` is
+   * that branch's OWN condition (`undefined` for a `dgm:else` entry, which
+   * has none - deliberately kept PER-ENTRY rather than cross-referenced by
+   * index against {@link chooseGuard}, whose own length can diverge from
+   * this chain's whenever an ancestor `dgm:else` contributed a group
+   * position but no guard).
+   *
+   * Lets a consumer recover ECMA-376's real `dgm:choose` semantics - "the
+   * FIRST branch whose condition holds wins, siblings never coexist" -
+   * from the flattened `.children` array, where that grouping would
+   * otherwise be lost: `balance--hier5.pptx`'s `balance_NN`/`left_NN_M`/
+   * `right_NN_M` family (127 members across ~30 NESTED `dgm:choose`
+   * instances, not one flat 127-branch choose) needs first-match-wins
+   * WITHIN each individual choose to resolve to the single genuinely-live
+   * arrangement, not the "every guard-true node is an independent
+   * candidate" reading `smartart-layout-interpreter-composite-choose.ts`'s
+   * `collectRawCandidates` used before this field existed - see that
+   * module's own consumer of this field for the actual selection rule.
+   * `undefined` (or an empty array) for a node reached without any
+   * enclosing choose (a direct child, or a `dgm:forEach`-only path) -
+   * every PRE-EXISTING caller that does not consult this field is
+   * unaffected by its mere presence.
+   *
+   * ROUND 42: `origin` is the forEach iterator active when THIS branch's
+   * own `dgm:if`/`dgm:else` was declared (the SAME "declaration time, not
+   * whatever descendant ends up carrying it" concept {@link
+   * chooseGuardOrigins} exists for) - the anchor a `func="cnt"`/`"maxDepth"`
+   * -family condition in `guard` needs, NOT a representative member's own
+   * (possibly deeper) `forEachOrigin`. See `smartart-layout-interpreter-
+   * composite-choose-groups.ts`'s `winningOrdinalFor`, the one consumer.
+   */
+  chooseGroups?: {
+    id: string;
+    ordinal: number;
+    guard?: PptxSmartArtWhen;
+    origin?: PptxSmartArtIteratorAttributes;
+  }[];
+  /**
+   * Every `dgm:presOf` candidate reachable through a `dgm:choose`/`dgm:if`/
+   * `dgm:else` wrapping THIS node's OWN presOf (as opposed to
+   * {@link chooseGuard}, which gates the layoutNode's own EXISTENCE), each
+   * tagged with the FULL chain of enclosing `dgm:if` conditions that select
+   * it (`guard`, empty for an unconditional or `dgm:else`-reached
+   * candidate), in document order (every `dgm:if` then `dgm:else` last).
+   * `undefined` when this node's presOf is not choose-guarded at all (the
+   * overwhelmingly common case) - {@link presentationOf} already carries
+   * the one-and-only value then. Exists for a genuinely conditional presOf
+   * where TWO OR MORE branches each declare a real, DIFFERENT axis
+   * (`funnel--flat3.pptx`'s `item1`/`item2`/`item3`, one literal axis per
+   * data-point count): `smartart-layout-definition-constraints.ts`'s
+   * `choosePresentationOf` (feeding {@link presentationOf}) can only ever
+   * guess ONE branch statically, at parse time, with no diagram to
+   * evaluate against; this field lets an interpret-time caller with the
+   * actual diagram (`smartart-layout-interpreter-when.ts`'s
+   * `resolvePresentationOf`, the one consumer) pick the branch PowerPoint's
+   * own runtime would, first-match-wins.
+   */
+  presentationOfCandidates?: {
+    guard: PptxSmartArtWhen[];
+    presentationOf: PptxSmartArtIteratorAttributes;
+  }[];
+  /**
+   * SESSION 17: every `dgm:rule` reachable through a `dgm:choose`/`dgm:if`/
+   * `dgm:else` wrapping THIS node's `ruleLst` (a genuinely count-gated rule
+   * set, e.g. `diverging-radial`'s own `w for="ch" forName="node"` ceiling:
+   * 6 `dgm:if cnt<=N` branches, each its own `fact`), tagged with its guard
+   * chain - the SAME shape {@link presentationOfCandidates} uses for
+   * choose-guarded `presOf`, applied to `dgm:rule`. `undefined` when not
+   * choose-guarded (`rules` above then carries the one set, the common
+   * case). See `smartart-layout-interpreter-cycle-hub-ratio.ts`'s
+   * `resolveHubToNodeRatio` (COM-verified live mechanism, not a guess) for
+   * how the guard is evaluated against the real satellite count.
+   */
+  ruleCandidates?: {
+    guard: PptxSmartArtWhen[];
+    rule: PptxSmartArtNumericRule;
+  }[];
+  /**
+   * ROUND 39: every `dgm:constr` reachable through a `dgm:choose`/`dgm:if`/
+   * `dgm:else` wrapping THIS node's `constrLst` (a genuinely count/position
+   * -branched constraint set, e.g. `basic-venn--flat3.pptx`'s composite
+   * `Name9` choose, one `ctrX`/`ctrY`/`w`/`h` per data-point-count branch
+   * for `circ1`/`circ1Tx`/...), each tagged with its guard chain - the SAME
+   * shape {@link presentationOfCandidates}/{@link ruleCandidates} use,
+   * applied to `dgm:constr`. `undefined` when not choose-guarded
+   * (`allConstraints`/`constraints` above then carry the one set, the
+   * common case). See `smartart-constraint-branch-index.ts`'s
+   * `selectConstraints` for how the guard is evaluated against the real
+   * diagram, and that module's own doc comment for why `allConstraints`'s
+   * pre-existing blind union of every branch is not enough on its own.
+   */
+  constraintCandidates?: {
+    guard: PptxSmartArtWhen[];
+    constraint: PptxSmartArtConstraint;
+  }[];
+}
+/** Metadata and root node from DiagramML CT_DiagramDefinition. */
+interface PptxSmartArtLayoutDefinition {
+  uniqueId?: string;
+  minimumVersion?: string;
+  defaultStyle?: string;
+  titles?: PptxSmartArtLocalizedText[];
+  descriptions?: PptxSmartArtLocalizedText[];
+  categories?: PptxSmartArtLayoutCategory[];
+  rootNode: PptxSmartArtLayoutNode;
+  /** Original definition retained for constraint evaluation and foreign rules. */
+  rawXml?: XmlObject;
+  /**
+   * The un-parsed layout-definition part text (starting at `<dgm:layoutDef>`,
+   * XML declaration included). `rawXml` above loses the document order of
+   * differently-named siblings (the package-wide `fast-xml-parser`
+   * configuration groups children into one array per tag), which the
+   * per-point DiagramML engine (`core/utils/smartart-engine/`) needs to
+   * execute a `layoutNode` body's `forEach`/`choose`/`constrLst` statements
+   * in their real declared sequence - see that package's `ordered-xml.ts`.
+   * `undefined` when the part could not be read (matches `rawXml`'s own
+   * optionality); the engine falls back to the legacy interpreter then.
+   */
+  rawXmlText?: string;
+}
+//#endregion
+//#region pptx/core/types/smart-art-node.d.ts
+/**
+ * A single run of text inside a SmartArt node, capturing the run text and the
+ * raw `a:rPr` run-properties object verbatim so per-run formatting (bold,
+ * colour, size, etc.) survives a load -> edit -> save round-trip instead of
+ * collapsing to a single unstyled run.
+ *
+ * @example
+ * ```ts
+ * const run: PptxSmartArtTextRun = {
+ *   text: "Bold",
+ *   rPr: { "@_b": "1", "@_lang": "en-US" },
+ * };
+ * // => satisfies PptxSmartArtTextRun
+ * ```
+ */
+interface PptxSmartArtTextRun {
+  /** Run text content. */
+  text: string;
+  /**
+   * Raw parsed `a:rPr` run-properties object, preserved verbatim for
+   * round-trip. Untyped XML, hence the loose record shape.
+   */
+  rPr?: Record<string, unknown>;
+  /** Resolved standard shape-text style derived from {@link rPr}. */
+  style?: TextStyle;
+  /** Raw run XML used to retain unmodelled extension children on save. */
+  rawXml?: Record<string, unknown>;
+  /** Original direct-child order, including unmodelled extension children. */
+  childOrder?: string[];
+}
+/** An ordered item within a SmartArt text paragraph. */
+type PptxSmartArtTextParagraphItem = {
+  kind: 'run';
+  run: PptxSmartArtTextRun;
+} | {
+  kind: 'break';
+  rPr?: Record<string, unknown>;
+  style?: TextStyle;
+  rawXml?: Record<string, unknown>;
+  childOrder?: string[];
+} | {
+  kind: 'field';
+  id?: string;
+  fieldType?: string;
+  text: string;
+  rPr?: Record<string, unknown>;
+  style?: TextStyle;
+  pPr?: Record<string, unknown>;
+  rawXml?: Record<string, unknown>;
+  childOrder?: string[];
+} | {
+  kind: 'tab';
+  rawXml?: Record<string, unknown>;
+  childOrder?: string[];
+} | {
+  kind: 'raw';
+  name: string;
+  value: unknown;
+};
+/** A complete `a:p` paragraph in a SmartArt data-model text body. */
+interface PptxSmartArtTextParagraph {
+  /** Paragraph properties (`a:pPr`) preserved verbatim. */
+  pPr?: Record<string, unknown>;
+  /** Text children in source order. */
+  items: PptxSmartArtTextParagraphItem[];
+  /** End-paragraph run properties (`a:endParaRPr`) preserved verbatim. */
+  endParaRPr?: Record<string, unknown>;
+  /** Resolved style for the paragraph terminator. */
+  endParaStyle?: TextStyle;
+  /** Raw paragraph XML used to retain unmodelled extension children on save. */
+  rawXml?: Record<string, unknown>;
+}
+/**
+ * Per-node visual override for a SmartArt node.
+ *
+ * Captures the individual fill / line / font colour and the bold / italic
+ * emphasis a user has set on one specific node, independent of the diagram's
+ * colour scheme and quick style. All colours are hex strings (e.g. "#FF0000").
+ * Every field is optional: only the overridden aspects are carried, so an
+ * empty object means "no per-node override".
+ *
+ * The parser reads these from the data point's `spPr` solid fill / line colour
+ * and the first run's `rPr` (b / i / solidFill) when present, and the save path
+ * writes them back so the override survives a load -> edit -> save round-trip.
+ *
+ * @example
+ * ```ts
+ * const style: PptxSmartArtNodeStyle = {
+ *   fillColor: "#FF0000",
+ *   fontColor: "#FFFFFF",
+ *   bold: true,
+ * };
+ * // => satisfies PptxSmartArtNodeStyle
+ * ```
+ */
+interface PptxSmartArtNodeStyle {
+  /** Solid fill colour override (hex, e.g. "#4F81BD"). */
+  fillColor?: string;
+  /** Outline / line colour override (hex). */
+  lineColor?: string;
+  /** Text (font) colour override (hex). */
+  fontColor?: string;
+  /** Bold emphasis override for the node's runs. */
+  bold?: boolean;
+  /** Italic emphasis override for the node's runs. */
+  italic?: boolean;
+}
+/**
+ * Manual layout override for a `type="pres"` presentation point, read from its
+ * `dgm:prSet` attributes. PowerPoint writes these when the user drags, resizes,
+ * rotates, or flips a SmartArt node by hand in its own diagram editor; without
+ * them the node silently reverts to its algorithmic position whenever there is
+ * no cached `dsp:` drawing part to fall back on.
+ *
+ * Every field is optional: only the attributes actually present on `prSet` are
+ * populated. Angle and scale/factor units are already normalised to degrees and
+ * plain ratios (a `custScaleX="150000"` becomes `scaleX: 1.5`), so a consumer
+ * never has to know the raw `60000ths-of-a-degree` / `100000ths-of-a-percent`
+ * XML encodings.
+ *
+ * @example
+ * ```ts
+ * const custom: SmartArtNodeCustomLayout = { angle: 15, scaleX: 1.2 };
+ * // => a node manually rotated 15 degrees and widened 20% in PowerPoint
+ * ```
+ */
+type SmartArtNodeCustomLayout = DiagramNodeCustomLayout;
+/**
+ * A single node in the SmartArt data model.
+ *
+ * @example
+ * ```ts
+ * const node: PptxSmartArtNode = {
+ *   id: "1",
+ *   text: "CEO",
+ *   children: [
+ *     { id: "2", text: "VP Marketing", parentId: "1" },
+ *     { id: "3", text: "VP Engineering", parentId: "1" },
+ *   ],
+ * };
+ * // => satisfies PptxSmartArtNode
+ * ```
+ */
+interface PptxSmartArtNode {
+  id: string;
+  text: string;
+  /** CT_Pt connection identifier, when the point references a connection. */
+  connectionId?: string | null;
+  parentId?: string;
+  children?: PptxSmartArtNode[];
+  /** Node type from `@_type` attribute (e.g. "doc", "node", "asst", "pres"). */
+  nodeType?: string;
+  /**
+   * The node's own quick-style role (`dgm:prSet/@presStyleLbl` from its
+   * paired `type="pres"` presentation point, resolved via a `presOf`
+   * connection back to this content point). Structural names like `node1`,
+   * `asst2`, `bgShp`, `revTx`; distinct from {@link nodeType}, which is the
+   * data-model `@_type` ("node"/"asst"/...). Used to pick this node's own
+   * colour list from a colour transform's per-role palettes instead of the
+   * generic cycled palette (see `applySmartArtRoleColors`).
+   */
+  styleRole?: string;
+  /**
+   * `dgm:prSet/@coherent3DOff` (`CT_ElemPropSet`) resolved from the node's
+   * paired presentation point: when true, this node opts out of the
+   * diagram's overall coherent-3D scene rotation (a `dgm:scene3d`/`dgm:sp3d`
+   * quick-style variation) applied to every other node.
+   */
+  coherent3DOff?: boolean;
+  /**
+   * The layout variables PowerPoint recorded for each presentation node
+   * this point drives (`dgm:prSet/@presName` -> `dgm:presLayoutVars`
+   * variable -> `@val`), e.g. `{ hierRoot1: { hierBranch: 'l' } }` for an
+   * org-chart manager set to "Left Hanging". Read-only: the presentation
+   * points themselves round-trip verbatim.
+   */
+  presLayoutVarsByName?: Record<string, Record<string, string>>;
+  /**
+   * Per-run text + run-properties for the node's first paragraph, captured at
+   * parse time. When the joined run text still equals {@link text} (the node
+   * was not edited, or was edited only in ways that preserve the run split),
+   * the save path rebuilds the paragraph from these runs so per-run rich text
+   * is not flattened. When {@link text} diverges, the runs are ignored.
+   */
+  runs?: PptxSmartArtTextRun[];
+  /**
+   * Complete typed paragraph model. Unlike {@link runs}, this retains every
+   * paragraph and the ordered run, field, break, and tab children within it.
+   */
+  paragraphs?: PptxSmartArtTextParagraph[];
+  /**
+   * Optional per-node visual override (fill / line / font colour, bold /
+   * italic). Read at parse time from the point's `spPr` / first-run `rPr`, set
+   * by the editing op, honoured by the render path, and written back on save so
+   * it round-trips.
+   */
+  style?: PptxSmartArtNodeStyle;
+  /**
+   * Manual layout override read from the node's `dgm:prSet` `cust*`
+   * attributes (drag/resize/rotate/flip performed in PowerPoint's own diagram
+   * editor). Applied as a final transform after algorithmic layout by
+   * {@link module:smartart-layout-interpreter-custom} so it survives even
+   * when there is no cached `dsp:` drawing to fall back on.
+   */
+  customLayout?: SmartArtNodeCustomLayout;
+}
+//#endregion
+//#region pptx/core/types/smart-art-style-definition.d.ts
+interface PptxSmartArtDefinitionText {
+  value: string;
+  language?: string;
+}
+interface PptxSmartArtDefinitionCategory {
+  type: string;
+  priority: number;
+}
+type PptxSmartArtColorApplicationMethod = 'span' | 'cycle' | 'repeat';
+type PptxSmartArtHueDirection = 'cw' | 'ccw';
+/** CT_Colors application metadata. Color-choice children remain preserved XML. */
+interface PptxSmartArtColorListMetadata {
+  method?: PptxSmartArtColorApplicationMethod;
+  hueDirection?: PptxSmartArtHueDirection;
+}
+/**
+ * A quick-style label's `a:lnRef`/`a:fillRef`/`a:effectRef`/`a:fontRef`
+ * (`CT_ShapeStyle`, the same complex type an ordinary shape's `p:style`
+ * uses), resolved against the theme's `fmtScheme` at parse time instead of
+ * the coarse subtle/moderate/intense enum ({@link PptxSmartArtQuickStyle.effectIntensity}).
+ * Only populated when a theme format scheme was available when the quick
+ * style was parsed. See G13 in the 2026-09 diagram audit.
+ */
+interface PptxSmartArtResolvedStyleRef {
+  fillColor?: string;
+  fillMode?: 'solid' | 'gradient' | 'pattern' | 'none' | 'theme';
+  strokeColor?: string;
+  strokeWidth?: number;
+  /** `a:effectRef`'s theme-resolved outer shadow colour, when the style has one. */
+  shadowColor?: string;
+  /** `a:fontRef`'s theme-resolved typeface (`+mn-lt`/`+mj-lt` -> the theme's actual font). */
+  fontTypeface?: string;
+}
+/** CT_StyleLabel metadata from a quick-style definition. */
+interface PptxSmartArtQuickStyleLabel {
+  name: string;
+  /** Theme-resolved `dgm:style` refs for this label's role, when available. */
+  resolvedStyle?: PptxSmartArtResolvedStyleRef;
+  /**
+   * The label's own `dgm:scene3d` (per-shape camera + light rig). PowerPoint
+   * copies it onto a shape's cached `a:scene3d` unless it is the default
+   * front camera with a `threePt` light (see `applySmartArtQuickStyle3d`).
+   */
+  scene3d?: Pptx3DScene;
+  /** The label's own `dgm:sp3d` (bevel / extrusion / contour / material); absent when empty. */
+  shape3d?: Pptx3DShape;
+  /** The label's `dgm:txPr/a:sp3d` label-text extrusion (Bird's Eye Scene). */
+  text3d?: Text3DStyle;
+}
+/** CT_CTStyleLabel metadata from a color-transform definition. */
+interface PptxSmartArtColorStyleLabel {
+  name: string;
+  fill?: PptxSmartArtColorListMetadata;
+  line?: PptxSmartArtColorListMetadata;
+  effect?: PptxSmartArtColorListMetadata;
+  textLine?: PptxSmartArtColorListMetadata;
+  textFill?: PptxSmartArtColorListMetadata;
+  textEffect?: PptxSmartArtColorListMetadata;
+}
+interface PptxSmartArtDefinitionMetadata {
+  uniqueId?: string;
+  minimumVersion?: string;
+  titles?: PptxSmartArtDefinitionText[];
+  descriptions?: PptxSmartArtDefinitionText[];
+  categories?: PptxSmartArtDefinitionCategory[];
+}
+/** Typed CT_ColorTransform metadata and the resolved legacy color palette. */
+interface PptxSmartArtColorTransform extends PptxSmartArtDefinitionMetadata {
+  /** Legacy resolved display name. */
+  name?: string;
+  /** Ordered resolved fill colors for rendering. */
+  fillColors: string[];
+  /** Ordered resolved line colors for rendering. */
+  lineColors: string[];
+  /** Ordered resolved text-fill colors (primary styleLbl `txFillClrLst`). */
+  textFillColors?: string[];
+  /** Ordered resolved text-line colors (primary styleLbl `txLinClrLst`). */
+  textLineColors?: string[];
+  /** Ordered resolved effect colors (primary styleLbl `effectClrLst`). */
+  effectColors?: string[];
+  /** Ordered resolved text-effect colors (primary styleLbl `txEffectClrLst`). */
+  textEffectColors?: string[];
+  /** Fill-list span/cycle + hue-direction interpolation of the primary styleLbl. */
+  fillInterpolation?: PptxSmartArtColorListMetadata;
+  /** Line-list span/cycle + hue-direction interpolation of the primary styleLbl. */
+  lineInterpolation?: PptxSmartArtColorListMetadata;
+  /** Ordered CT_CTStyleLabel metadata. */
+  labels?: PptxSmartArtColorStyleLabel[];
+  /**
+   * Every `styleLbl`'s own resolved fill/line colour list, keyed by name
+   * (e.g. `node1`, `asst0`, `bgShp`, `revTx`). Unlike {@link fillColors} /
+   * {@link lineColors} (which collapse to ONE "primary" node-role list),
+   * this keeps every role so a node can be coloured from its OWN role's
+   * palette (see `PptxSmartArtNode.styleRole` and `applySmartArtRoleColors`)
+   * instead of a generic cycled colour.
+   */
+  roleColors?: Record<string, SmartArtRoleColorList>;
+}
+/** One colour-transform `styleLbl`'s resolved colour lists. */
+interface SmartArtRoleColorList {
+  fill: string[];
+  line: string[];
+  /**
+   * `txFillClrLst`, when the label declares one (`revTx` -> `tx1`). A text
+   * node's colour comes from here; see `smartart-merged-text-label`.
+   */
+  textFill?: string[];
+}
+/** Typed CT_StyleDefinition metadata and legacy rendering hint. */
+interface PptxSmartArtQuickStyle extends PptxSmartArtDefinitionMetadata {
+  /** Legacy resolved display name. */
+  name?: string;
+  /** Legacy effect-intensity rendering hint. */
+  effectIntensity?: string;
+  /** Ordered CT_StyleLabel metadata. Complex style payload remains preserved XML. */
+  labels?: PptxSmartArtQuickStyleLabel[];
+  /**
+   * Whole-diagram 3D scene (camera preset/rotation/zoom/fov, light rig,
+   * backdrop) from the quick style's own `dgm:styleDef/dgm:scene3d`, present
+   * for the "Scene" quick styles (Brick, Flat, Metallic, Sunset, Bird's Eye
+   * Scene). One camera renders the whole diagram; per-shape `a:scene3d` is
+   * absent for those styles (see `PptxSmartArtDrawingShape.scene3d`). Each
+   * `dgm:styleLbl` also carries its own per-label `dgm:scene3d`/`dgm:sp3d`
+   * ({@link PptxSmartArtQuickStyleLabel.scene3d} / `shape3d` / `text3d`),
+   * which PowerPoint bakes onto each cached shape; they are re-applied when a
+   * structural edit regenerates the shapes.
+   */
+  scene3d?: Pptx3DScene;
+}
+//#endregion
+//#region pptx/core/types/smart-art.d.ts
+/**
+ * Resolved SmartArt layout category.
+ *
+ * @example
+ * ```ts
+ * const cat: SmartArtLayoutType = "hierarchy";
+ * // => "hierarchy" — one of: "list" | "process" | "cycle" | "hierarchy" | "relationship" | …
+ * ```
+ */
+type SmartArtLayoutType = DiagramLayoutType;
+/**
+ * Named SmartArt layout presets for creation (subset of PowerPoint layouts).
+ *
+ * @example
+ * ```ts
+ * const layout: SmartArtLayout = "hierarchy";
+ * // => "hierarchy" — one of: "basicBlockList" | "alternatingHexagons" | "hierarchy" | …
+ * ```
+ */
+type SmartArtLayout = 'basicBlockList' | 'alternatingHexagons' | 'basicChevronProcess' | 'basicCycle' | 'basicPie' | 'basicRadial' | 'basicVenn' | 'continuousBlockProcess' | 'convergingRadial' | 'hierarchy' | 'horizontalBulletList' | 'linearVenn' | 'segmentedProcess' | 'stackedList' | 'tableList' | 'trapezoidList' | 'upwardArrow' | 'basicFunnel' | 'basicTarget' | 'interlockingGears' | 'basicTimeline' | 'basicMatrix' | 'basicPyramid' | 'invertedPyramid' | 'bendingProcess' | 'stepDownProcess' | 'alternatingFlow' | 'descendingProcess' | 'pictureAccentList' | 'verticalBlockList' | 'groupedList' | 'pyramidList' | 'horizontalPictureList' | 'accentProcess' | 'verticalChevronList';
+/**
+ * SmartArt colour scheme presets.
+ *
+ * @example
+ * ```ts
+ * const scheme: SmartArtColorScheme = "colorful1";
+ * // => "colorful1" — one of: "colorful1" | "colorful2" | "colorful3" | "monochromatic1" | "monochromatic2"
+ * ```
+ */
+type SmartArtColorScheme = DiagramColorScheme;
+/**
+ * SmartArt visual style intensity.
+ *
+ * @example
+ * ```ts
+ * const style: SmartArtStyle = "moderate";
+ * // => "moderate" — one of: "flat" | "moderate" | "intense"
+ * ```
+ */
+type SmartArtStyle = DiagramStyleIntensity;
+/**
+ * A connection between two SmartArt data-model nodes.
+ *
+ * @example
+ * ```ts
+ * const conn: PptxSmartArtConnection = {
+ *   sourceId: "1",
+ *   destId: "2",
+ *   type: "parOf",
+ * };
+ * // => satisfies PptxSmartArtConnection
+ * ```
+ */
+type PptxSmartArtConnection = DiagramConnection;
+/**
+ * A pre-computed shape from `ppt/diagrams/drawing*.xml`.
+ *
+ * @example
+ * ```ts
+ * const shape: PptxSmartArtDrawingShape = {
+ *   id: "s1",
+ *   shapeType: "roundRect",
+ *   x: 100, y: 50, width: 200, height: 80,
+ *   fillColor: "#4F81BD",
+ *   text: "CEO",
+ * };
+ * // => satisfies PptxSmartArtDrawingShape
+ * ```
+ */
+interface PptxSmartArtDrawingShape extends PptxCustomPathProperties {
+  /** Shape ID within the drawing. */
+  id: string;
+  /** Preset geometry type (e.g. "roundRect", "ellipse"). */
+  shapeType?: string;
+  /** Position and size in EMU-based pixels. */
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** Rotation in degrees. */
+  rotation?: number;
+  /** Horizontal/vertical mirrors declared on the cached drawing transform. */
+  flipHorizontal?: boolean;
+  flipVertical?: boolean;
+  /** Skew along the X axis in degrees. */
+  skewX?: number;
+  /** Skew along the Y axis in degrees. */
+  skewY?: number;
+  /** Preset-geometry adjustment values from `a:prstGeom/a:avLst`. */
+  shapeAdjustments?: Record<string, number>;
+  /**
+   * The cached shape declares `a:noFill`. Renderers must leave it unpainted
+   * rather than substituting a palette colour, because these shapes usually sit
+   * on top of a painted shape whose fill has to stay visible.
+   */
+  fillNone?: boolean;
+  /** Solid fill colour (hex). */
+  fillColor?: string;
+  /**
+   * Opacity (0..1) of the solid fill, from the colour's `a:alpha` (Basic Venn
+   * paints its circles at 50% so overlaps blend). Absent when opaque.
+   */
+  fillOpacity?: number;
+  /**
+   * Gradient fill stops when the cached shape uses `a:gradFill`. Positions are
+   * 0..100 (percent). Renderers emit an SVG/CSS gradient instead of a flat box.
+   */
+  fillGradientStops?: Array<{
+    color: string;
+    position: number;
+    opacity?: number;
+  }>;
+  /** Gradient geometry type (`linear` for `a:lin`, `radial` for `a:path`). */
+  fillGradientType?: 'linear' | 'radial';
+  /** Linear gradient angle in degrees (0..360). */
+  fillGradientAngle?: number;
+  /** Pattern fill preset name from `a:pattFill/@prst` (e.g. "pct50", "cross"). */
+  fillPatternPreset?: string;
+  /** Pattern fill foreground colour (hex) from `a:pattFill/a:fgClr`. */
+  fillPatternForegroundColor?: string;
+  /** Pattern fill background colour (hex) from `a:pattFill/a:bgClr`. */
+  fillPatternBackgroundColor?: string;
+  /**
+   * Relationship id of a picture (blip) fill's embedded image, from
+   * `a:blipFill/a:blip/@r:embed`. The image bytes are resolved separately; see
+   * {@link fillImageUrl}.
+   */
+  fillBlipEmbedId?: string;
+  /**
+   * Resolved data-URI/URL for a picture (blip) fill, when the embedded image
+   * part could be resolved. Absent when only {@link fillBlipEmbedId} is known.
+   */
+  fillImageUrl?: string;
+  /** Whether the cached shape carries an outer-shadow effect (`a:effectLst`). */
+  hasShadow?: boolean;
+  /** Resolved outer-shadow colour (hex), when present. */
+  shadowColor?: string;
+  /** Stroke colour (hex). */
+  strokeColor?: string;
+  /** Stroke width in points. */
+  strokeWidth?: number;
+  /** Text content of the shape. */
+  text?: string;
+  /** Standard rich-text segments projected from the associated SmartArt node. */
+  textSegments?: TextSegment[];
+  /** Font size in CSS pixels. */
+  fontSize?: number;
+  /** Font colour (hex). */
+  fontColor?: string;
+  /** Authored font family from the first styled run. */
+  fontFamily?: string;
+  /** Authored font weight (400 or 700). */
+  fontWeight?: number;
+  /** Authored font style. */
+  fontStyle?: 'normal' | 'italic';
+  /** Absolute line height in CSS pixels from `a:spcPts`. */
+  lineHeight?: number;
+  /** Relative line height from `a:spcPct`. */
+  lineHeightRatio?: number;
+  /** Absolute spacing after a paragraph in CSS pixels. */
+  lineSpacingAfter?: number;
+  /** Relative spacing after a paragraph. */
+  lineSpacingAfterRatio?: number;
+  /** Text-body insets in CSS pixels. */
+  textInsetLeft?: number;
+  textInsetTop?: number;
+  textInsetRight?: number;
+  textInsetBottom?: number;
+  /** DiagramML text vertical anchor (`t`, `ctr`, or `b`). */
+  textVerticalAnchor?: string;
+  /** Independent DiagramML text-frame geometry from `dsp:txXfrm`. */
+  textFrameX?: number;
+  textFrameY?: number;
+  textFrameWidth?: number;
+  textFrameHeight?: number;
+  /**
+   * 3D scene (camera/light rig/backdrop) from `dsp:spPr/a:scene3d`, when this
+   * cached shape carries its own per-shape camera. Bevel quick styles
+   * (Polished, Inset, Cartoon, Powder) cache one per shape (always
+   * `orthographicFront`, so the 2D layout stays undistorted). Scene quick
+   * styles (Brick, Flat, Metallic, Sunset, Bird's Eye) instead put ONE camera
+   * on the whole diagram (see `PptxSmartArtQuickStyle.scene3d`) and leave this
+   * undefined on every shape.
+   */
+  scene3d?: Pptx3DScene;
+  /**
+   * 3D extrusion/bevel/contour/material from `dsp:spPr/a:sp3d`. PowerPoint
+   * caches this fully resolved (from the quick style's per-label `dgm:sp3d`)
+   * on every shape for every non-flat quick style, bevel or scene alike.
+   */
+  shape3d?: Pptx3DShape;
+  /**
+   * Text-body 3D extrusion/bevel from `dsp:txBody/a:bodyPr/a:sp3d`. Rare:
+   * present when a quick style extrudes the label text itself off the shape
+   * face (e.g. Bird's Eye Scene: `extrusionH="28000"`), rather than only the
+   * shape body.
+   */
+  text3d?: Text3DStyle;
+  /**
+   * The presentation style label (`presStyleLbl`: `node1`, `revTx`,
+   * `sibTrans2D1`, ...) of the layout node a REGENERATED shape was laid out
+   * from, when the layout engine reports it. Picks the quick-style label
+   * whose 3D the shape takes; `undefined` on cached (parsed) shapes.
+   */
+  styleLabel?: string;
+}
+/**
+ * Presentation layout variables from `dgm:prSet/dgm:presLayoutVars` (data model)
+ * or `dgm:varLst` (layout definition defaults).
+ *
+ * These drive how the DiagramML layout interpreter arranges points: flow
+ * direction, hierarchy branch style, org-chart mode, and child count limits.
+ * The fallback layout engine can consult them for direction/org-chart hints.
+ *
+ * @example
+ * ```ts
+ * const vars: PptxSmartArtPresLayoutVars = { direction: "rev", orgChart: true };
+ * // => satisfies PptxSmartArtPresLayoutVars
+ * ```
+ */
+interface PptxSmartArtPresLayoutVars {
+  /** Flow direction (`dgm:dir`): "norm" (default) or "rev" (reversed/RTL). */
+  direction?: 'norm' | 'rev';
+  /** Hierarchy branch style (`dgm:hierBranch`): std/init/l/r/hang. */
+  hierarchyBranch?: 'std' | 'init' | 'l' | 'r' | 'hang';
+  /** Org-chart mode enabled (`dgm:orgChart`). */
+  orgChart?: boolean;
+  /** Maximum children per node (`dgm:chMax`, -1 = unbounded). */
+  childMax?: number;
+  /** Preferred children per node (`dgm:chPref`, -1 = unbounded). */
+  childPreferred?: number;
+  /** Whether bullets are enabled (`dgm:bulletEnabled`). */
+  bulletEnabled?: boolean;
+  /** Animation-by-level setting (`dgm:animLvl`). */
+  animationLevel?: string;
+  /** Animate-one setting (`dgm:animOne`). */
+  animateOne?: string;
+  /** Allowed resize handles (`dgm:resizeHandles`). */
+  resizeHandles?: string;
+}
+/**
+ * Complete parsed SmartArt data for a {@link SmartArtPptxElement}.
+ *
+ * @example
+ * ```ts
+ * const data: PptxSmartArtData = {
+ *   resolvedLayoutType: "hierarchy",
+ *   layout: "hierarchy",
+ *   colorScheme: "colorful1",
+ *   style: "moderate",
+ *   nodes: [
+ *     { id: "1", text: "CEO", children: [
+ *       { id: "2", text: "VP Marketing", parentId: "1" },
+ *     ]},
+ *   ],
+ * };
+ * // => satisfies PptxSmartArtData
+ * ```
+ */
+interface PptxSmartArtData {
+  layoutType?: string;
+  resolvedLayoutType?: SmartArtLayoutType;
+  /** Named layout preset (used when creating new SmartArt). */
+  layout?: SmartArtLayout;
+  /** Colour scheme for the SmartArt graphic. */
+  colorScheme?: SmartArtColorScheme;
+  /** Visual style intensity. */
+  style?: SmartArtStyle;
+  nodes: PptxSmartArtNode[];
+  /** Connections between data-model nodes. */
+  connections?: PptxSmartArtConnection[];
+  /** Pre-computed shapes from `ppt/diagrams/drawing*.xml`. */
+  drawingShapes?: PptxSmartArtDrawingShape[];
+  /** Background and outline chrome from `dgm:bg` / `dgm:whole`. */
+  chrome?: PptxSmartArtChrome;
+  /** Colour transform from `ppt/diagrams/colors*.xml`. */
+  colorTransform?: PptxSmartArtColorTransform;
+  /** Quick style from `ppt/diagrams/quickStyles*.xml`. */
+  quickStyle?: PptxSmartArtQuickStyle;
+  /** Editable metadata from the related DiagramML layout definition. */
+  layoutDefinition?: PptxSmartArtLayoutDefinition;
+  /**
+   * Presentation layout variables (direction, hierarchy branch, org-chart,
+   * child limits, bullets) from `dgm:presLayoutVars` / layout `dgm:varLst`.
+   * Consulted by the fallback layout engine for direction/org-chart hints.
+   */
+  presLayoutVars?: PptxSmartArtPresLayoutVars;
+  /**
+   * The deck's own theme minor-Latin font (`a:fontScheme/a:minorFont/a:latin/
+   * @typeface`): what SmartArt text actually renders in when no per-run
+   * `a:latin` override is present (the common case - see
+   * `smartart-layout-item-font-size.ts`'s font-fit, the one consumer).
+   * Undefined when the theme carries no font scheme at all.
+   */
+  themeMinorFont?: string;
+  /** Relationship ID for the diagram data part (for round-trip save). */
+  dataRelId?: string;
+  /** Relationship ID for the diagram layout part. */
+  layoutRelId?: string;
+  /** Relationship ID for the drawing part. */
+  drawingRelId?: string;
+  /** Relationship ID for the colours part. */
+  colorsRelId?: string;
+  /** Relationship ID for the quick-styles part. */
+  styleRelId?: string;
+  /**
+   * `uniqueId` of the built-in PowerPoint layout whose definition was applied by a layout swap
+   * (`ooxml-core/pptx/smartart-layouts`). Save writes that definition as the layout part.
+   */
+  builtinLayoutId?: string;
+  /** Internal save hint: the layout definition changed in the editor. */
+  layoutDirty?: boolean;
+  /** Internal save hint: typed layout-definition metadata changed. */
+  layoutDefinitionDirty?: boolean;
+  /** Internal save hint: quick-style definition metadata changed. */
+  quickStyleDirty?: boolean;
+  /** Internal save hint: color-transform definition metadata changed. */
+  colorTransformDirty?: boolean;
+  /** Internal save hint: cached drawing geometry or text changed in the editor. */
+  drawingDirty?: boolean;
+}
+//#endregion
+export { CustomGeometrySegment as $, PptxSmartArtChoose as A, UnderlineStyle as At, PptxSmartArtConstraintOperator as B, PptxSmartArtTextParagraph as C, Text3DStyle as Ct, PptxSmartArtLayoutDefinition as D, PptxShapeLocks as Dt, SmartArtNodeCustomLayout as E, PptxDrawingGuide as Et, PptxSmartArtLayoutNodeShape as F, PptxSmartArtChrome as G, PptxSmartArtConstraintRelationship as H, PptxSmartArtLocalizedText as I, AdjustHandleXY as J, PptxSmartArtRawBackgroundFill as K, PptxSmartArtShapeAdjustment as L, PptxSmartArtIteratorAttributes as M, PptxSmartArtLayoutAlgorithm as N, PptxSmartArtLayoutNode as O, ShadowEffect as Ot, PptxSmartArtLayoutCategory as P, CustomGeometryRawData as Q, PptxSmartArtWhen as R, PptxSmartArtNodeStyle as S, PptxTextWarpPreset as St, PptxSmartArtTextRun as T, ConnectorConnectionPoint as Tt, PptxSmartArtConstraintTarget as U, PptxSmartArtConstraintPointType as V, PptxSmartArtNumericRule as W, CustomGeometryPath as X, ConnectionSite as Y, CustomGeometryPoint as Z, PptxSmartArtQuickStyle as _, EffectDagXfrm as _t, SmartArtColorScheme as a, TextSegment as at, SmartArtRoleColorList as b, Pptx3DScene as bt, SmartArtStyle as c, EffectDagBlend as ct, PptxSmartArtColorStyleLabel as d, EffectDagContainer as dt, CustomGeometryTextRect as et, PptxSmartArtColorTransform as f, EffectDagContainerType as ft, PptxSmartArtHueDirection as g, EffectDagRelOff as gt, PptxSmartArtDefinitionText as h, EffectDagRawLeaf as ht, PptxSmartArtPresLayoutVars as i, TextOrientationMatrix as it, PptxSmartArtForEach as j, XmlObject as jt, PptxSmartArtAlgorithmParameter as k, StrokeDashType as kt, PptxSmartArtColorApplicationMethod as l, EffectDagBlendMode as lt, PptxSmartArtDefinitionMetadata as m, EffectDagPresetShadow as mt, PptxSmartArtData as n, PptxCustomPathProperties as nt, SmartArtLayout as o, TextStyle as ot, PptxSmartArtDefinitionCategory as p, EffectDagNode as pt, AdjustHandlePolar as q, PptxSmartArtDrawingShape as r, BulletInfo as rt, SmartArtLayoutType as s, EffectDagAlphaOutset as st, PptxSmartArtConnection as t, GeometryAdjustmentHandle as tt, PptxSmartArtColorListMetadata as u, EffectDagBlur as ut, PptxSmartArtQuickStyleLabel as v, BevelPresetType as vt, PptxSmartArtTextParagraphItem as w, ConnectorArrowType as wt, PptxSmartArtNode as x, Pptx3DShape as xt, PptxSmartArtResolvedStyleRef as y, MaterialPresetType as yt, PptxSmartArtConstraint as z };
+//# sourceMappingURL=smart-art-CO2jmJFf.d.ts.map