pptx-react-viewer 1.0.0

package/node_modules/pptx-viewer-core/dist/presentation-Bo7cMMCe.d.mts

@@ -0,0 +1,4558 @@
+/**
+ * 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' | '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;
+}
+type XmlObject = Record<string, any>;
+/**
+ * Discriminant values for the `type` field on {@link PptxElement}.
+ *
+ * Narrow on this type to access variant-specific properties.
+ *
+ * @example
+ * ```ts
+ * function isImage(el: PptxElement): el is ImagePptxElement {
+ *   return el.type === "image";
+ * }
+ * // => type guard narrowing PptxElement to ImagePptxElement
+ * ```
+ */
+type PptxElementType = 'text' | 'shape' | 'connector' | 'image' | 'picture' | 'chart' | 'table' | 'smartArt' | 'ole' | 'media' | 'group' | 'ink' | 'zoom' | 'unknown';
+/**
+ * Shape lock attributes from `p:cNvSpPr / a:spLocks`.
+ *
+ * When a flag is `true` the corresponding user interaction is disabled
+ * in the editor (e.g. `noRotation` prevents free rotation of the shape).
+ *
+ * @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 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;
+}
+
+/**
+ * 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';
+/**
+ * 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 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;
+    /** 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;
+}
+/**
+ * 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 {
+    /** 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;
+
+/**
+ * Text-related types: rich text styles, bullet metadata, and text segments.
+ *
+ * These types model the contents of `<a:r>`, `<a:rPr>`, `<a:pPr>`,
+ * and `<a:bodyPr>` nodes from the OpenXML Drawing namespace.
+ *
+ * @module pptx-types/text
+ */
+
+/**
+ * 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
+ * ```
+ */
+interface TextStyle {
+    fontFamily?: string;
+    fontSize?: number;
+    /** When true, renderer should shrink text to fit the shape bounds. */
+    autoFit?: boolean;
+    /** Explicit autofit mode from OOXML body properties.
+     * - 'shrink': `a:spAutoFit` — shrink text on overflow
+     * - 'normal': `a:normAutofit` — normal auto-fit (with optional fontScale)
+     * - '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;
+    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;
+    /** When true, the text body has no fill (`a:rPr > a:noFill`), producing hollow/outline-only text. */
+    textFillNone?: 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;
+    /** 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;
+    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;
+    align?: 'left' | 'center' | 'right' | 'justify' | 'justLow' | 'dist' | 'thaiDist';
+    vAlign?: 'top' | 'middle' | 'bottom';
+    /** 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';
+    }>;
+    /** 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';
+    /** 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;
+    /** Text language from `a:rPr/@lang`. */
+    language?: string;
+    /** Hyperlink mouse-over target from `a:hlinkMouseOver`. */
+    hyperlinkMouseOver?: string;
+    /** 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;
+    /** 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;
+    /** 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 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;
+    /** 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 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;
+    /** 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;
+    /** 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;
+}
+/**
+ * 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;
+    /** Zero-based paragraph index within the text body (for auto-numbering). */
+    paragraphIndex?: number;
+    /** Bullet font family from `a:buFont`. */
+    fontFamily?: string;
+    /** 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;
+    /** 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;
+}
+/**
+ * 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;
+    /** Raw OMML XML node for equation segments (from `a14:m` / `m:oMathPara`). */
+    equationXml?: 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;
+    /** Structured bullet info for the first segment of a paragraph. */
+    bulletInfo?: BulletInfo;
+    /**
+     * 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;
+}
+
+/**
+ * Shape visual styling types: fill, stroke, effects, and connectors.
+ *
+ * {@link ShapeStyle} is the main type attached to any element that has
+ * visible geometry (shapes, connectors, images). It covers:
+ * - **Fill**: solid, gradient, pattern, image, and theme fills
+ * - **Stroke**: colour, width, dash pattern, line join/cap
+ * - **Effects**: shadow, glow, soft-edge, reflection, blur
+ * - **Connectors**: arrow-head types and connection points
+ * - **3-D**: scene camera and shape extrusion/bevel
+ *
+ * All spatial values are stored in **pixels** (pre-converted from EMU).
+ * Opacity values are normalised to the 0–1 range.
+ *
+ * @module pptx-types/shape-style
+ */
+
+/**
+ * Comprehensive visual style for a shape, connector, or image element.
+ *
+ * All fields are optional. When absent, the element inherits from theme
+ * or layout defaults. The interface models both simple styling (solid fill +
+ * basic stroke) and advanced effects (multiple shadow layers, gradient
+ * fills, 3-D extrusion).
+ *
+ * @example
+ * ```ts
+ * // Simple blue filled shape with a thin black outline:
+ * const simple: ShapeStyle = {
+ *   fillColor: "#0055AA",
+ *   fillMode: "solid",
+ *   strokeColor: "#000000",
+ *   strokeWidth: 1,
+ * };
+ *
+ * // Gradient fill with a soft shadow:
+ * const fancy: ShapeStyle = {
+ *   fillMode: "gradient",
+ *   fillGradientType: "linear",
+ *   fillGradientAngle: 135,
+ *   fillGradientStops: [
+ *     { color: "#FF6B6B", position: 0 },
+ *     { color: "#556270", position: 1 },
+ *   ],
+ *   shadowColor: "#000000",
+ *   shadowBlur: 10,
+ *   shadowOffsetX: 4,
+ *   shadowOffsetY: 4,
+ *   shadowOpacity: 0.3,
+ * };
+ * // => both satisfy the ShapeStyle interface
+ * ```
+ */
+interface ShapeStyle {
+    fillColor?: string;
+    fillGradient?: string;
+    fillMode?: 'solid' | 'gradient' | 'pattern' | 'none' | 'image' | 'theme' | 'group';
+    fillPatternPreset?: string;
+    fillPatternBackgroundColor?: string;
+    /** Raw XML node for pattern fill foreground colour (preserves color transforms). */
+    fillPatternFgClrXml?: XmlObject;
+    /** Raw XML node for pattern fill background colour (preserves color transforms). */
+    fillPatternBgClrXml?: XmlObject;
+    /** Data-URI or URL for image fill (when fillMode === "image"). */
+    fillImageUrl?: string;
+    /** How the image is sized within the shape: stretch to fill, or tile/repeat. */
+    fillImageMode?: 'stretch' | 'tile';
+    fillGradientStops?: Array<{
+        color: string;
+        position: number;
+        opacity?: number;
+        /** Raw XML colour node preserved for round-trip (e.g. a:schemeClr with transforms). */
+        originalColorXml?: XmlObject;
+    }>;
+    fillGradientAngle?: number;
+    fillGradientType?: 'linear' | 'radial';
+    /** Path gradient sub-type from `a:path/@path` (e.g. "circle", "rect", "shape"). */
+    fillGradientPathType?: 'circle' | 'rect' | 'shape';
+    /** Focal point for path (radial) gradients, derived from `a:fillToRect`.
+     *  Values are 0..1 fractions relative to shape bounds. */
+    fillGradientFocalPoint?: {
+        x: number;
+        y: number;
+    };
+    /** Raw fillToRect LTRB values (0..1 fractions) from `a:fillToRect`.
+     *  Defines the inner rectangle where the gradient reaches its final stop.
+     *  l/t are insets from left/top edges; r/b are insets from right/bottom edges. */
+    fillGradientFillToRect?: {
+        l: number;
+        t: number;
+        r: number;
+        b: number;
+    };
+    fillOpacity?: number;
+    strokeColor?: string;
+    strokeWidth?: number;
+    strokeOpacity?: number;
+    strokeDash?: StrokeDashType;
+    /** Line join style (`a:ln/@join`): round, bevel, or miter. */
+    lineJoin?: 'round' | 'bevel' | 'miter';
+    /** Line cap style (`a:ln/@cap`): flat, rnd, or sq. */
+    lineCap?: 'flat' | 'rnd' | 'sq';
+    /** Compound line type (`a:ln/@cmpd`). */
+    compoundLine?: 'sng' | 'dbl' | 'thickThin' | 'thinThick' | 'tri';
+    shadowColor?: string;
+    shadowBlur?: number;
+    shadowOffsetX?: number;
+    shadowOffsetY?: number;
+    shadowOpacity?: number;
+    /** Preset shadow name from `a:prstShdw/@prst` (e.g. "shdw1"..."shdw20"). */
+    presetShadowName?: string;
+    /** Shadow angle in degrees (0-360). Parsed from `@_dir` (60000ths of a degree). */
+    shadowAngle?: number;
+    /** Shadow distance in pixels. Parsed from `@_dist` (EMUs). */
+    shadowDistance?: number;
+    /** Whether shadow rotates with shape. Parsed from `@_rotWithShape`. */
+    shadowRotateWithShape?: boolean;
+    /** Multiple shadow layers (for advanced effects). */
+    shadows?: ShadowEffect[];
+    glowColor?: string;
+    glowRadius?: number;
+    glowOpacity?: number;
+    softEdgeRadius?: number;
+    /** Inner shadow colour (`a:innerShdw`). */
+    innerShadowColor?: string;
+    /** Inner shadow opacity (0-1). */
+    innerShadowOpacity?: number;
+    /** Inner shadow blur radius in px. */
+    innerShadowBlur?: number;
+    /** Inner shadow horizontal offset in px. */
+    innerShadowOffsetX?: number;
+    /** Inner shadow vertical offset in px. */
+    innerShadowOffsetY?: number;
+    /** Reflection effect — distance from shape bottom in px. */
+    reflectionBlurRadius?: number;
+    /** Reflection start opacity (0-1). */
+    reflectionStartOpacity?: number;
+    /** Reflection end opacity (0-1). */
+    reflectionEndOpacity?: number;
+    /** Reflection end position (0-1 fraction of shape height). */
+    reflectionEndPosition?: number;
+    /** Reflection direction in degrees. */
+    reflectionDirection?: number;
+    /** Reflection rotation in degrees (`a:reflection/@rot` in 60000ths). */
+    reflectionRotation?: number;
+    /** Reflection distance in px. */
+    reflectionDistance?: number;
+    /** Standalone blur effect radius in px (`a:effectLst > a:blur`). */
+    blurRadius?: number;
+    /** Whether the blur effect grows the bounds of the shape (`a:blur/@grow`). */
+    blurGrow?: boolean;
+    connectorStartArrow?: ConnectorArrowType;
+    /** Start arrow width size ('sm' | 'med' | 'lg'). */
+    connectorStartArrowWidth?: 'sm' | 'med' | 'lg';
+    /** Start arrow length size ('sm' | 'med' | 'lg'). */
+    connectorStartArrowLength?: 'sm' | 'med' | 'lg';
+    connectorEndArrow?: ConnectorArrowType;
+    /** End arrow width size ('sm' | 'med' | 'lg'). */
+    connectorEndArrowWidth?: 'sm' | 'med' | 'lg';
+    /** End arrow length size ('sm' | 'med' | 'lg'). */
+    connectorEndArrowLength?: 'sm' | 'med' | 'lg';
+    /** Connection point for the start of a connector. */
+    connectorStartConnection?: ConnectorConnectionPoint;
+    /** Connection point for the end of a connector. */
+    connectorEndConnection?: ConnectorConnectionPoint;
+    /** Custom dash segments array (`a:custDash/a:ds`). Each entry has dash length and space length in EMU. */
+    customDashSegments?: Array<{
+        dash: number;
+        space: number;
+    }>;
+    /** 3D scene/camera settings from `a:scene3d`. */
+    scene3d?: Pptx3DScene;
+    /** 3D shape extrusion/bevel from `a:sp3d`. */
+    shape3d?: Pptx3DShape;
+    /** Line-level shadow colour from `a:ln/a:effectLst/a:outerShdw`. */
+    lineShadowColor?: string;
+    /** Line-level shadow opacity (0-1). */
+    lineShadowOpacity?: number;
+    /** Line-level shadow blur radius in px. */
+    lineShadowBlur?: number;
+    /** Line-level shadow horizontal offset in px. */
+    lineShadowOffsetX?: number;
+    /** Line-level shadow vertical offset in px. */
+    lineShadowOffsetY?: number;
+    /** Line-level glow colour from `a:ln/a:effectLst/a:glow`. */
+    lineGlowColor?: string;
+    /** Line-level glow radius in px. */
+    lineGlowRadius?: number;
+    /** Line-level glow opacity (0-1). */
+    lineGlowOpacity?: number;
+    /** Raw `a:effectDag` XML node preserved for round-trip serialisation. */
+    effectDagXml?: XmlObject;
+    /** Grayscale flag from effectDag `a:grayscl`. */
+    dagGrayscale?: boolean;
+    /** Bi-level threshold (0-100) from effectDag `a:biLevel`. */
+    dagBiLevel?: number;
+    /** Brightness adjustment (-100 to 100) from effectDag `a:lum/@bright`. */
+    dagLumBrightness?: number;
+    /** Contrast adjustment (-100 to 100) from effectDag `a:lum/@contrast`. */
+    dagLumContrast?: number;
+    /** Hue rotation in degrees (0-360) from effectDag `a:hsl/@hue`. */
+    dagHslHue?: number;
+    /** Saturation adjustment from effectDag `a:hsl/@sat`. */
+    dagHslSaturation?: number;
+    /** Luminance adjustment from effectDag `a:hsl/@lum`. */
+    dagHslLuminance?: number;
+    /** Alpha modulation fixed (0-100) from effectDag `a:alphaModFix`. */
+    dagAlphaModFix?: number;
+    /** Tint hue in degrees from effectDag `a:tint/@hue`. */
+    dagTintHue?: number;
+    /** Tint amount (0-100) from effectDag `a:tint/@amt`. */
+    dagTintAmount?: number;
+    /** Duotone colour pair from effectDag `a:duotone`. */
+    dagDuotone?: {
+        color1: string;
+        color2: string;
+    };
+    /** Fill overlay blend mode from effectDag `a:fillOverlay/@blend`. */
+    dagFillOverlayBlend?: 'over' | 'mult' | 'screen' | 'darken' | 'lighten';
+}
+
+/**
+ * Image types: effects, crop shapes, and properties shared by image/picture
+ * elements.
+ *
+ * @module pptx-types/image
+ */
+/**
+ * Image recolour/adjustment properties parsed from blip extensions.
+ *
+ * These effects are stored in the OpenXML `<a:blip>` extension list
+ * and applied non-destructively to the original image data.
+ *
+ * @example
+ * ```ts
+ * const fx: PptxImageEffects = {
+ *   brightness: 20,
+ *   contrast: -10,
+ *   grayscale: true,
+ * };
+ * // => { brightness: 20, contrast: -10, grayscale: true } satisfies PptxImageEffects
+ * ```
+ */
+interface PptxImageEffects {
+    /** Brightness adjustment (-100 to 100). */
+    brightness?: number;
+    /** Contrast adjustment (-100 to 100). */
+    contrast?: number;
+    /** Duotone colour pair. */
+    duotone?: {
+        color1: string;
+        color2: string;
+    };
+    /** Grayscale flag. */
+    grayscale?: boolean;
+    /** Saturation adjustment (-100 to 100). */
+    saturation?: number;
+    /** Color wash overlay. */
+    colorWash?: {
+        color: string;
+        opacity: number;
+    };
+    /** Artistic effect name (blur, pencilGrayscale, paintStrokes, etc.). */
+    artisticEffect?: string;
+    /** Artistic effect radius/amount. */
+    artisticRadius?: number;
+    /** Alpha modulation fixed — overall opacity (0-100, where 100 = fully opaque). */
+    alphaModFix?: number;
+    /** Bi-level threshold — converts to 1-bit black/white (0-100). */
+    biLevel?: number;
+    /** Colour change — swap one colour range for another (used for transparency keying). */
+    clrChange?: {
+        clrFrom: string;
+        clrTo: string;
+        /** Whether the target colour is fully transparent (alpha = 0). */
+        clrToTransparent?: boolean;
+    };
+}
+/**
+ * Shape names used for crop-to-shape (CSS `clip-path` equivalent).
+ *
+ * @example
+ * ```ts
+ * const shape: PptxCropShape = "ellipse";
+ * // => "ellipse" — one of: none | ellipse | roundedRect | triangle | diamond | pentagon | hexagon | star
+ * ```
+ */
+type PptxCropShape = 'none' | 'ellipse' | 'roundedRect' | 'triangle' | 'diamond' | 'pentagon' | 'hexagon' | 'star';
+/**
+ * Image content mixin — present on image and picture elements.
+ *
+ * Contains the decoded image data (base64 data URL or archive path),
+ * alt text, crop insets, tiling settings, and image effects.
+ *
+ * @example
+ * ```ts
+ * const props: PptxImageProperties = {
+ *   imagePath: "ppt/media/image1.png",
+ *   altText: "Company logo",
+ *   cropLeft: 0.05,
+ *   cropRight: 0.05,
+ * };
+ * // => { imagePath: "ppt/media/image1.png", altText: "Company logo", cropLeft: 0.05, cropRight: 0.05 }
+ * ```
+ */
+interface PptxImageProperties {
+    /** Base64 data-URL for the decoded image. */
+    imageData?: string;
+    /** Path within the PPTX ZIP archive. */
+    imagePath?: string;
+    /** Base64 data-URL for an SVG variant (from blip extension asvg:svgBlip). Preferred over raster when available. */
+    svgData?: string;
+    /** Path to the SVG file within the PPTX ZIP archive. */
+    svgPath?: string;
+    /** Alt text / description from `p:cNvPr/@descr`. */
+    altText?: string;
+    /** Crop from left edge as 0..1 fraction (OOXML `a:srcRect/@l`). */
+    cropLeft?: number;
+    /** Crop from top edge as 0..1 fraction (OOXML `a:srcRect/@t`). */
+    cropTop?: number;
+    /** Crop from right edge as 0..1 fraction (OOXML `a:srcRect/@r`). */
+    cropRight?: number;
+    /** Crop from bottom edge as 0..1 fraction (OOXML `a:srcRect/@b`). */
+    cropBottom?: number;
+    /** Image tiling offset X in px. */
+    tileOffsetX?: number;
+    /** Image tiling offset Y in px. */
+    tileOffsetY?: number;
+    /** Image tiling scale X as percentage (100 = 100%). */
+    tileScaleX?: number;
+    /** Image tiling scale Y as percentage (100 = 100%). */
+    tileScaleY?: number;
+    /** Image tiling flip mode. */
+    tileFlip?: 'none' | 'x' | 'y' | 'xy';
+    /** Image tiling alignment. */
+    tileAlignment?: string;
+    /** Image recolour/artistic effect properties. */
+    imageEffects?: PptxImageEffects;
+    /** Crop-to-shape — CSS clip-path shape name. */
+    cropShape?: PptxCropShape;
+}
+
+/**
+ * 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[];
+}
+/**
+ * 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[];
+}
+
+/**
+ * Chart types: chart categories, series data, style metadata, data tables,
+ * trendlines, error bars, and the composite `PptxChartData`.
+ *
+ * @module pptx-types/chart
+ */
+/**
+ * Supported chart type discriminators.
+ *
+ * @example
+ * ```ts
+ * const type: PptxChartType = "bar";
+ * // => "bar" — one of: "bar" | "line" | "pie" | "doughnut" | "area" | "scatter" | …
+ * ```
+ */
+type PptxChartType = 'bar' | 'line' | 'pie' | 'doughnut' | 'area' | 'scatter' | 'bubble' | 'radar' | 'stock' | 'bar3D' | 'line3D' | 'pie3D' | 'area3D' | 'surface' | 'histogram' | 'waterfall' | 'funnel' | 'treemap' | 'sunburst' | 'boxWhisker' | 'regionMap' | 'combo' | 'unknown';
+/**
+ * Supported trendline regression types.
+ *
+ * @example
+ * ```ts
+ * const type: PptxChartTrendlineType = "linear";
+ * // => "linear" — one of: "linear" | "exponential" | "logarithmic" | "polynomial" | "power" | "movingAvg"
+ * ```
+ */
+type PptxChartTrendlineType = 'linear' | 'exponential' | 'logarithmic' | 'polynomial' | 'power' | 'movingAvg';
+/**
+ * Configuration for a chart trendline (regression line).
+ *
+ * @example
+ * ```ts
+ * const trendline: PptxChartTrendline = {
+ *   trendlineType: "linear",
+ *   displayEq: true,
+ *   displayRSq: true,
+ *   color: "#FF0000",
+ * };
+ * // => satisfies PptxChartTrendline
+ * ```
+ */
+interface PptxChartTrendline {
+    trendlineType: PptxChartTrendlineType;
+    order?: number;
+    period?: number;
+    forward?: number;
+    backward?: number;
+    intercept?: number;
+    displayRSq?: boolean;
+    displayEq?: boolean;
+    color?: string;
+}
+/** Error-bar direction axis. */
+type PptxChartErrBarDir = 'x' | 'y';
+/** Error-bar display type (both sides, negative only, or positive only). */
+type PptxChartErrBarType = 'both' | 'minus' | 'plus';
+/**
+ * How the error-bar value is calculated.
+ *
+ * @example
+ * ```ts
+ * const valType: PptxChartErrValType = "percentage";
+ * // => "percentage" — one of: "cust" | "fixedVal" | "percentage" | "stdDev" | "stdErr"
+ * ```
+ */
+type PptxChartErrValType = 'cust' | 'fixedVal' | 'percentage' | 'stdDev' | 'stdErr';
+/**
+ * Error bars for a chart series.
+ *
+ * @example
+ * ```ts
+ * const bars: PptxChartErrBars = {
+ *   direction: "y",
+ *   barType: "both",
+ *   valType: "percentage",
+ *   val: 5,
+ * };
+ * // => satisfies PptxChartErrBars
+ * ```
+ */
+interface PptxChartErrBars {
+    direction: PptxChartErrBarDir;
+    barType: PptxChartErrBarType;
+    valType: PptxChartErrValType;
+    val?: number;
+    customPlus?: number[];
+    customMinus?: number[];
+}
+/**
+ * Visibility flags for the chart data table (axes + legend keys).
+ *
+ * @example
+ * ```ts
+ * const dt: PptxChartDataTable = {
+ *   showHorzBorder: true,
+ *   showVertBorder: true,
+ *   showOutline: true,
+ *   showKeys: true,
+ * };
+ * // => satisfies PptxChartDataTable
+ * ```
+ */
+interface PptxChartDataTable {
+    showHorzBorder?: boolean;
+    showVertBorder?: boolean;
+    showOutline?: boolean;
+    showKeys?: boolean;
+}
+/**
+ * Line appearance for chart helper lines (drop lines, hi-low lines).
+ *
+ * @example
+ * ```ts
+ * const style: PptxChartLineStyle = {
+ *   color: "#AAAAAA",
+ *   width: 1,
+ *   dashStyle: "dash",
+ * };
+ * // => satisfies PptxChartLineStyle
+ * ```
+ */
+interface PptxChartLineStyle {
+    color?: string;
+    width?: number;
+    dashStyle?: string;
+}
+/** Marker symbol types for line/scatter chart data points. */
+type PptxChartMarkerSymbol = 'circle' | 'dash' | 'diamond' | 'dot' | 'none' | 'picture' | 'plus' | 'square' | 'star' | 'triangle' | 'x' | 'auto';
+/** Shape properties extracted from c:spPr for chart formatting. */
+interface PptxChartShapeProps {
+    fillColor?: string;
+    strokeColor?: string;
+    strokeWidth?: number;
+}
+/** Marker appearance on a chart series or data point. */
+interface PptxChartMarker {
+    symbol: PptxChartMarkerSymbol;
+    size?: number;
+    spPr?: PptxChartShapeProps;
+}
+/** Per-data-point formatting override (c:dPt). */
+interface PptxChartDataPoint {
+    idx: number;
+    spPr?: PptxChartShapeProps;
+    explosion?: number;
+    invertIfNegative?: boolean;
+    marker?: PptxChartMarker;
+}
+/** Individual data label override (c:dLbl). */
+interface PptxChartDataLabel {
+    idx: number;
+    showVal?: boolean;
+    showCatName?: boolean;
+    showSerName?: boolean;
+    showPercent?: boolean;
+    showLegendKey?: boolean;
+    showBubbleSize?: boolean;
+    position?: string;
+    text?: string;
+}
+/** Axis number format. */
+interface PptxChartAxisNumFmt {
+    formatCode: string;
+    sourceLinked?: boolean;
+}
+/** Axis formatting for category, value, or date axes. */
+interface PptxChartAxisFormatting {
+    axisType: 'catAx' | 'valAx' | 'dateAx' | 'serAx';
+    /** Axis position: "b" (bottom), "l" (left), "r" (right), "t" (top). */
+    axPos?: 'b' | 'l' | 'r' | 't';
+    /** Unique axis identifier (c:axId/@val) used to link series to axes. */
+    axisId?: number;
+    /** Cross-axis identifier — the axis this axis crosses. */
+    crossAxisId?: number;
+    numFmt?: PptxChartAxisNumFmt;
+    titleText?: string;
+    spPr?: PptxChartShapeProps;
+    fontFamily?: string;
+    fontSize?: number;
+    fontBold?: boolean;
+    fontColor?: string;
+    majorGridlinesSpPr?: PptxChartShapeProps;
+    minorGridlinesSpPr?: PptxChartShapeProps;
+    /** Minimum axis value override (c:min/@val). */
+    min?: number;
+    /** Maximum axis value override (c:max/@val). */
+    max?: number;
+    /** Whether the axis is deleted/hidden (c:delete/@val). */
+    deleted?: boolean;
+    /**
+     * Display units for value axis (c:dispUnits/c:builtInUnit/@val).
+     * When set to 'custom', the actual divisor is in {@link displayUnitsValue}.
+     */
+    displayUnits?: 'hundreds' | 'thousands' | 'tenThousands' | 'hundredThousands' | 'millions' | 'tenMillions' | 'hundredMillions' | 'billions' | 'trillions' | 'custom';
+    /** Custom display unit divisor value (c:dispUnits/c:custUnit/@val). Only used when displayUnits is 'custom'. */
+    displayUnitsValue?: number;
+    /** Display units label text (c:dispUnits/c:dispUnitsLbl). Overrides the built-in default label when present. */
+    displayUnitsLabel?: string;
+    /** Whether logarithmic scaling is enabled (presence of c:scaling/c:logBase). */
+    logScale?: boolean;
+    /** Logarithmic base value (c:scaling/c:logBase/@val), typically 10 or e. */
+    logBase?: number;
+}
+/** 3D wall or floor element formatting. */
+interface PptxChart3DSurface {
+    thickness?: number;
+    spPr?: PptxChartShapeProps;
+}
+/**
+ * A single data series within a chart.
+ *
+ * @example
+ * ```ts
+ * const series: PptxChartSeries = {
+ *   name: "Revenue",
+ *   values: [100, 120, 140],
+ *   color: "#4F81BD",
+ *   trendlines: [{ trendlineType: "linear" }],
+ * };
+ * // => satisfies PptxChartSeries
+ * ```
+ */
+interface PptxChartSeries {
+    name: string;
+    values: number[];
+    color?: string;
+    trendlines?: PptxChartTrendline[];
+    errBars?: PptxChartErrBars[];
+    dataPoints?: PptxChartDataPoint[];
+    marker?: PptxChartMarker;
+    dataLabels?: PptxChartDataLabel[];
+    explosion?: number;
+    /** Axis ID this series is plotted against (links to PptxChartAxisFormatting.axisId). */
+    axisId?: number;
+}
+/**
+ * Style / formatting metadata for a chart.
+ *
+ * @example
+ * ```ts
+ * const style: PptxChartStyle = {
+ *   styleId: 2,
+ *   hasLegend: true,
+ *   legendPosition: "b",
+ *   hasDataLabels: true,
+ * };
+ * // => satisfies PptxChartStyle
+ * ```
+ */
+interface PptxChartStyle {
+    /** Chart style index from `c:style/@val`. */
+    styleId?: number;
+    /** Whether the chart has a visible legend. */
+    hasLegend?: boolean;
+    /** Legend position (t, b, l, r, tr). */
+    legendPosition?: string;
+    /** Whether the chart has a title. */
+    hasTitle?: boolean;
+    /** Whether gridlines are visible. */
+    hasGridlines?: boolean;
+    /** Whether data labels are shown. */
+    hasDataLabels?: boolean;
+}
+/**
+ * External data source reference for a chart (c:externalData).
+ *
+ * Charts can reference an external Excel workbook via a relationship ID
+ * that points to an external file (TargetMode="External"). The
+ * `autoUpdate` flag indicates whether the chart should refresh its
+ * cached data from the external source on open.
+ *
+ * @example
+ * ```ts
+ * const ext: PptxExternalData = {
+ *   relId: "rId2",
+ *   targetPath: "file:///C:/Data/budget.xlsx",
+ *   autoUpdate: true,
+ * };
+ * // => satisfies PptxExternalData
+ * ```
+ */
+interface PptxExternalData {
+    /** Relationship ID referencing the external data source in the chart .rels. */
+    relId: string;
+    /** Resolved external file path or URL from the relationship target. */
+    targetPath?: string;
+    /** Whether to auto-update data from the external source on open. */
+    autoUpdate?: boolean;
+    /** Raw binary data of the embedded xlsx workbook (from ppt/embeddings/). */
+    embeddedWorkbookData?: Uint8Array;
+}
+/** Parsed data extracted from an embedded xlsx workbook. */
+interface PptxEmbeddedWorkbookData {
+    /** Category labels from the first column/row. */
+    categories: string[];
+    /** Data series extracted from worksheet cells. */
+    series: Array<{
+        name: string;
+        values: number[];
+    }>;
+}
+/**
+ * Complete parsed chart data for a {@link ChartPptxElement}.
+ *
+ * @example
+ * ```ts
+ * const chart: PptxChartData = {
+ *   title: "Q4 Sales",
+ *   chartType: "bar",
+ *   categories: ["Jan", "Feb", "Mar"],
+ *   series: [
+ *     { name: "Revenue", values: [100, 120, 140] },
+ *   ],
+ *   grouping: "clustered",
+ *   style: { hasLegend: true, legendPosition: "b" },
+ * };
+ * // => satisfies PptxChartData
+ * ```
+ */
+interface PptxChartData {
+    title?: string;
+    chartType: PptxChartType;
+    categories: string[];
+    series: PptxChartSeries[];
+    /** Chart style/formatting metadata. */
+    style?: PptxChartStyle;
+    /** Grouping mode for bar/area/line charts: 'clustered' | 'stacked' | 'percentStacked' */
+    grouping?: 'clustered' | 'stacked' | 'percentStacked';
+    /** Internal: path to the chart XML part in the PPTX archive (for round-trip save). */
+    chartPartPath?: string;
+    /** Internal: relationship ID linking the graphic frame to the chart part. */
+    chartRelationshipId?: string;
+    dataTable?: PptxChartDataTable;
+    dropLines?: PptxChartLineStyle;
+    hiLowLines?: PptxChartLineStyle;
+    axes?: PptxChartAxisFormatting[];
+    floor?: PptxChart3DSurface;
+    sideWall?: PptxChart3DSurface;
+    backWall?: PptxChart3DSurface;
+    /** External data source reference (c:externalData) linking to an external workbook. */
+    externalData?: PptxExternalData;
+    /**
+     * Parsed data from the embedded xlsx workbook (from ppt/embeddings/).
+     *
+     * When a chart references an embedded Excel workbook via `c:externalData`,
+     * the xlsx is parsed to extract categories and series. This data serves as
+     * a fallback when the chart XML's cached series data is empty or incomplete.
+     */
+    embeddedWorkbookData?: PptxEmbeddedWorkbookData;
+    /**
+     * Pivot table data source reference (c:pivotSource).
+     *
+     * When present, the chart's data originates from a PivotTable.
+     * The chart still renders using its cached series data; this field
+     * is metadata about the data origin, preserved for round-trip fidelity.
+     */
+    pivotSource?: {
+        /** Pivot table reference name, e.g. "[workbook.xlsx]Sheet1!PivotTable1". */
+        name: string;
+        /** Format identifier from c:fmtId/@val. */
+        formatId?: number;
+    };
+    /**
+     * Whether only visible cells are plotted (c:plotVisOnly).
+     * When `true` (the default), hidden cells are excluded from the chart.
+     * When `false`, hidden data IS plotted.
+     */
+    plotVisibleOnly?: boolean;
+    /**
+     * Color palette extracted from the chart's Office 2013+ color style part
+     * (`chartColorStyle*.xml`). When present, this palette takes priority over
+     * the `c:style/@val`-derived palette in `getChartStylePalette`.
+     *
+     * Each entry is a resolved hex colour string (e.g. `"#4472C4"`).
+     */
+    colorPalette?: string[];
+    /**
+     * Color cycling method from the chart color style part's `meth` attribute.
+     *
+     * - `"cycle"` — repeat the palette colours in order (default)
+     * - `"withinLinear"` — gradient within each series
+     * - `"acrossLinear"` — gradient across series
+     */
+    colorMethod?: 'cycle' | 'withinLinear' | 'acrossLinear';
+}
+
+/**
+ * SmartArt types: layout categories, layout presets, colour schemes,
+ * data-model nodes/connections, drawing shapes, chrome, and the composite
+ * `PptxSmartArtData`.
+ *
+ * @module pptx-types/smart-art
+ */
+/**
+ * Resolved SmartArt layout category.
+ *
+ * @example
+ * ```ts
+ * const cat: SmartArtLayoutType = "hierarchy";
+ * // => "hierarchy" — one of: "list" | "process" | "cycle" | "hierarchy" | "relationship" | …
+ * ```
+ */
+type SmartArtLayoutType = 'list' | 'process' | 'cycle' | 'hierarchy' | 'relationship' | 'matrix' | 'pyramid' | 'funnel' | 'gear' | 'target' | 'timeline' | 'venn' | 'chevron' | 'bending' | 'unknown';
+/**
+ * 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 = 'colorful1' | 'colorful2' | 'colorful3' | 'monochromatic1' | 'monochromatic2';
+/**
+ * SmartArt visual style intensity.
+ *
+ * @example
+ * ```ts
+ * const style: SmartArtStyle = "moderate";
+ * // => "moderate" — one of: "flat" | "moderate" | "intense"
+ * ```
+ */
+type SmartArtStyle = 'flat' | 'moderate' | 'intense';
+/**
+ * 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;
+    parentId?: string;
+    children?: PptxSmartArtNode[];
+    /** Node type from `@_type` attribute (e.g. "doc", "node", "asst", "pres"). */
+    nodeType?: string;
+}
+/**
+ * A connection between two SmartArt data-model nodes.
+ *
+ * @example
+ * ```ts
+ * const conn: PptxSmartArtConnection = {
+ *   sourceId: "1",
+ *   destId: "2",
+ *   type: "parOf",
+ * };
+ * // => satisfies PptxSmartArtConnection
+ * ```
+ */
+interface PptxSmartArtConnection {
+    /** Model ID of the source node. */
+    sourceId: string;
+    /** Model ID of the destination node. */
+    destId: string;
+    /** Connection type (e.g. "parOf", "presOf", "sibTrans"). */
+    type?: string;
+    /** Source index for ordering sibling connections. */
+    srcOrd?: number;
+    /** Destination index for ordering. */
+    destOrd?: number;
+}
+/**
+ * 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 {
+    /** 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;
+    /** Skew along the X axis in degrees. */
+    skewX?: number;
+    /** Skew along the Y axis in degrees. */
+    skewY?: number;
+    /** Solid fill colour (hex). */
+    fillColor?: string;
+    /** Stroke colour (hex). */
+    strokeColor?: string;
+    /** Stroke width in points. */
+    strokeWidth?: number;
+    /** Text content of the shape. */
+    text?: string;
+    /** Font size in points. */
+    fontSize?: number;
+    /** Font colour (hex). */
+    fontColor?: string;
+}
+/**
+ * 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). */
+    backgroundColor?: string;
+    /** Outline stroke colour (hex). */
+    outlineColor?: string;
+    /** Outline stroke width in points. */
+    outlineWidth?: number;
+}
+/**
+ * Colour transform entry from `ppt/diagrams/colors*.xml`.
+ *
+ * @example
+ * ```ts
+ * const transform: PptxSmartArtColorTransform = {
+ *   name: "Colorful - Accent Colors",
+ *   fillColors: ["#4F81BD", "#C0504D", "#9BBB59"],
+ *   lineColors: ["#385D8A", "#8C3836", "#71893F"],
+ * };
+ * // => satisfies PptxSmartArtColorTransform
+ * ```
+ */
+interface PptxSmartArtColorTransform {
+    /** Colour scheme name / title. */
+    name?: string;
+    /** Ordered list of fill colours (hex) for each node. */
+    fillColors: string[];
+    /** Ordered list of line colours (hex). */
+    lineColors: string[];
+}
+/**
+ * Style entry from `ppt/diagrams/quickStyles*.xml`.
+ *
+ * @example
+ * ```ts
+ * const qs: PptxSmartArtQuickStyle = {
+ *   name: "Moderate Effect",
+ *   effectIntensity: "moderate",
+ * };
+ * // => satisfies PptxSmartArtQuickStyle
+ * ```
+ */
+interface PptxSmartArtQuickStyle {
+    /** Style name / title. */
+    name?: string;
+    /** Effect intensity identifier (e.g. "subtle", "moderate", "intense"). */
+    effectIntensity?: 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;
+    /** Relationship ID for the diagram data part (for round-trip save). */
+    dataRelId?: 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;
+}
+
+/**
+ * Table types: cell styling, cell data, rows, table data, and the parsed
+ * table style map from `ppt/tableStyles.xml`.
+ *
+ * @module pptx-types/table
+ */
+/**
+ * Per-cell visual style for a table cell.
+ *
+ * All fields are optional — unset values inherit from the table style.
+ *
+ * @example
+ * ```ts
+ * const header: PptxTableCellStyle = {
+ *   bold: true,
+ *   fontSize: 14,
+ *   color: "#FFFFFF",
+ *   backgroundColor: "#0055AA",
+ *   align: "center",
+ * };
+ * // => satisfies PptxTableCellStyle
+ * ```
+ */
+interface PptxTableCellStyle {
+    fontSize?: number;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    backgroundColor?: string;
+    borderColor?: string;
+    /** Top border width in px. */
+    borderTopWidth?: number;
+    /** Bottom border width in px. */
+    borderBottomWidth?: number;
+    /** Left border width in px. */
+    borderLeftWidth?: number;
+    /** Right border width in px. */
+    borderRightWidth?: number;
+    /** Top border color as hex. */
+    borderTopColor?: string;
+    /** Bottom border color as hex. */
+    borderBottomColor?: string;
+    /** Left border color as hex. */
+    borderLeftColor?: string;
+    /** Right border color as hex. */
+    borderRightColor?: string;
+    align?: 'left' | 'center' | 'right' | 'justify';
+    vAlign?: 'top' | 'middle' | 'bottom';
+    /** Text direction from `a:tcPr/@vert`. */
+    textDirection?: 'vertical' | 'vertical270' | 'eaVert' | 'wordArtVert' | 'wordArtVertRtl' | 'mongolianVert';
+    /** Cell left margin in px (from a:tcPr > a:tcMar > a:marL). */
+    marginLeft?: number;
+    /** Cell right margin in px. */
+    marginRight?: number;
+    /** Cell top margin in px. */
+    marginTop?: number;
+    /** Cell bottom margin in px. */
+    marginBottom?: number;
+    /** Diagonal border top-left to bottom-right color. */
+    borderDiagDownColor?: string;
+    /** Diagonal border top-left to bottom-right width in px. */
+    borderDiagDownWidth?: number;
+    /** Diagonal border bottom-left to top-right color. */
+    borderDiagUpColor?: string;
+    /** Diagonal border bottom-left to top-right width in px. */
+    borderDiagUpWidth?: number;
+    /** Table cell border dash style (legacy single value). */
+    borderDash?: string;
+    /** Per-edge border dash styles. */
+    borderTopDash?: string;
+    borderBottomDash?: string;
+    borderLeftDash?: string;
+    borderRightDash?: string;
+    /** Cell text shadow colour. */
+    textShadowColor?: string;
+    /** Cell text shadow blur radius in px. */
+    textShadowBlur?: number;
+    /** Cell text shadow horizontal offset in px. */
+    textShadowOffsetX?: number;
+    /** Cell text shadow vertical offset in px. */
+    textShadowOffsetY?: number;
+    /** Cell text shadow opacity (0-1). */
+    textShadowOpacity?: number;
+    /** Cell text glow colour. */
+    textGlowColor?: string;
+    /** Cell text glow radius in px. */
+    textGlowRadius?: number;
+    /** Cell text glow opacity (0-1). */
+    textGlowOpacity?: number;
+    /** Cell fill mode: solid, gradient, pattern, or none. */
+    fillMode?: 'solid' | 'gradient' | 'pattern' | 'none';
+    /** Gradient fill stops (colours with positions). */
+    gradientFillStops?: Array<{
+        color: string;
+        position: number;
+        opacity?: number;
+    }>;
+    /** Gradient angle in degrees. */
+    gradientFillAngle?: number;
+    /** Gradient type: linear or radial. */
+    gradientFillType?: 'linear' | 'radial';
+    /** Path gradient sub-type. */
+    gradientFillPathType?: 'circle' | 'rect' | 'shape';
+    /** Focal point for radial gradients (0–1 fractions). */
+    gradientFillFocalPoint?: {
+        x: number;
+        y: number;
+    };
+    /** Raw fillToRect LTRB values (0–1 fractions) for gradient sizing. */
+    gradientFillFillToRect?: {
+        l: number;
+        t: number;
+        r: number;
+        b: number;
+    };
+    /** Pre-computed CSS gradient string for rendering. */
+    gradientFillCss?: string;
+    /** Pattern fill preset name (e.g. "ltDnDiag"). */
+    patternFillPreset?: string;
+    /** Pattern fill foreground colour. */
+    patternFillForeground?: string;
+    /** Pattern fill background colour. */
+    patternFillBackground?: string;
+}
+/**
+ * A single table cell with text content, optional style, and merge info.
+ *
+ * @example
+ * ```ts
+ * const cell: PptxTableCell = {
+ *   text: "$1.5M",
+ *   style: { bold: true, align: "right" },
+ *   gridSpan: 1,
+ * };
+ * // => satisfies PptxTableCell
+ * ```
+ */
+interface PptxTableCell {
+    text: string;
+    style?: PptxTableCellStyle;
+    /** Column span (defaults to 1). */
+    gridSpan?: number;
+    /** Row span (defaults to 1). */
+    rowSpan?: number;
+    /** Whether this cell is merged vertically with the cell above. */
+    vMerge?: boolean;
+    /** Whether this cell is horizontally merged with the cell to the left (gridSpan continuation). */
+    hMerge?: boolean;
+}
+/**
+ * A single table row with an optional height and an array of cells.
+ *
+ * @example
+ * ```ts
+ * const row: PptxTableRow = {
+ *   height: 40,
+ *   cells: [
+ *     { text: "Name" },
+ *     { text: "Score" },
+ *   ],
+ * };
+ * // => satisfies PptxTableRow
+ * ```
+ */
+interface PptxTableRow {
+    /** Row height in px. */
+    height?: number;
+    cells: PptxTableCell[];
+}
+/**
+ * Complete parsed table data for a {@link TablePptxElement}.
+ *
+ * Includes row/cell data, column widths, banding flags, and the applied
+ * table style ID.
+ *
+ * @example
+ * ```ts
+ * const data: PptxTableData = {
+ *   rows: [
+ *     { cells: [{ text: "Product" }, { text: "Revenue" }] },
+ *     { cells: [{ text: "Widget A" }, { text: "$3.4M" }] },
+ *   ],
+ *   columnWidths: [0.6, 0.4],
+ *   firstRowHeader: true,
+ *   bandedRows: true,
+ * };
+ * // => satisfies PptxTableData
+ * ```
+ */
+interface PptxTableData {
+    rows: PptxTableRow[];
+    /** Column widths as proportion of total (summing to 1). */
+    columnWidths: number[];
+    /** Whether the table has banded rows. */
+    bandedRows?: boolean;
+    /** Whether the first row is a header. */
+    firstRowHeader?: boolean;
+    /** Whether banded columns are enabled. */
+    bandedColumns?: boolean;
+    /** Whether the last row is styled as a total row. */
+    lastRow?: boolean;
+    /** Whether the first column is styled as a header column. */
+    firstCol?: boolean;
+    /** Whether the last column is styled specially. */
+    lastCol?: boolean;
+    /** Table style ID from `a:tblPr/a:tblStyle@val` or `a:tblPr@tblStyle`. */
+    tableStyleId?: string;
+    /** Number of rows per banding group (default 1). */
+    bandRowCycle?: number;
+    /** Number of columns per banding group (default 1). */
+    bandColCycle?: number;
+}
+/**
+ * A single fill reference within a table style section.
+ *
+ * @example
+ * ```ts
+ * const fill: ParsedTableStyleFill = {
+ *   schemeColor: "accent1",
+ *   tint: 40000,   // 40% tint
+ * };
+ * // => satisfies ParsedTableStyleFill
+ * ```
+ */
+interface ParsedTableStyleFill {
+    /** Theme colour key (e.g. `accent1`, `dk1`). */
+    schemeColor: string;
+    /** Tint value (0-100 000). */
+    tint?: number;
+    /** Shade value (0-100 000). */
+    shade?: number;
+}
+/**
+ * A single entry in the parsed table style map.
+ *
+ * Contains fill colours for whole-table, banded rows/columns, first/last
+ * row, and first/last column sections.
+ *
+ * @example
+ * ```ts
+ * const entry: ParsedTableStyleEntry = {
+ *   styleId: "{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}",
+ *   styleName: "Medium Style 2 - Accent 1",
+ *   accentKey: "accent1",
+ *   wholeTblFill: { schemeColor: "accent1", tint: 20000 },
+ *   band1HFill:   { schemeColor: "accent1", tint: 40000 },
+ *   firstRowFill: { schemeColor: "accent1" },
+ * };
+ * // => satisfies ParsedTableStyleEntry
+ * ```
+ */
+/** Text properties from a:tcTxStyle in a table style section. */
+interface ParsedTableStyleText {
+    /** Font bold. */
+    bold?: boolean;
+    /** Font italic. */
+    italic?: boolean;
+    /** Font colour as theme scheme key. */
+    fontSchemeColor?: string;
+    /** Font colour tint (0-100 000). */
+    fontTint?: number;
+    /** Font colour shade (0-100 000). */
+    fontShade?: number;
+}
+interface ParsedTableStyleEntry {
+    styleId: string;
+    styleName?: string;
+    /** Dominant accent key derived from fills (e.g. `accent1`). */
+    accentKey?: string;
+    wholeTblFill?: ParsedTableStyleFill;
+    band1HFill?: ParsedTableStyleFill;
+    band2HFill?: ParsedTableStyleFill;
+    band1VFill?: ParsedTableStyleFill;
+    band2VFill?: ParsedTableStyleFill;
+    firstRowFill?: ParsedTableStyleFill;
+    lastRowFill?: ParsedTableStyleFill;
+    firstColFill?: ParsedTableStyleFill;
+    lastColFill?: ParsedTableStyleFill;
+    /** Per-role text styling from a:tcTxStyle. */
+    wholeTblText?: ParsedTableStyleText;
+    firstRowText?: ParsedTableStyleText;
+    lastRowText?: ParsedTableStyleText;
+    firstColText?: ParsedTableStyleText;
+    lastColText?: ParsedTableStyleText;
+    band1HText?: ParsedTableStyleText;
+    band2HText?: ParsedTableStyleText;
+    band1VText?: ParsedTableStyleText;
+    band2VText?: ParsedTableStyleText;
+}
+/**
+ * Map of GUID → table style entry.
+ *
+ * Parsed from `ppt/tableStyles.xml` and indexed by the style GUID
+ * referenced in `a:tblPr@tblStyle`.
+ *
+ * @example
+ * ```ts
+ * const styles: ParsedTableStyleMap = {
+ *   "{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}": {
+ *     styleId: "{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}",
+ *     styleName: "Medium Style 2 - Accent 1",
+ *     accentKey: "accent1",
+ *   },
+ * };
+ * // => satisfies ParsedTableStyleMap
+ * ```
+ */
+type ParsedTableStyleMap = Record<string, ParsedTableStyleEntry>;
+
+/**
+ * Slide transition types and the {@link PptxSlideTransition} data structure.
+ *
+ * Represents the `<p:transition>` element on each slide, including
+ * transition type, duration, direction, and advance timing.
+ *
+ * @module pptx-types/transition
+ */
+
+/**
+ * Available slide transition effects.
+ *
+ * Maps to the OOXML child element names under `<p:transition>` / `<p14:transition>`.
+ *
+ * @example
+ * ```ts
+ * const t: PptxTransitionType = "morph";
+ * // => "morph" — one of 40+ transition effects
+ * ```
+ */
+type PptxTransitionType = 'none' | 'cut' | 'fade' | 'push' | 'wipe' | 'split' | 'randomBar' | 'blinds' | 'checker' | 'circle' | 'comb' | 'cover' | 'diamond' | 'dissolve' | 'plus' | 'pull' | 'random' | 'strips' | 'uncover' | 'wedge' | 'wheel' | 'zoom' | 'newsflash' | 'morph' | 'conveyor' | 'doors' | 'ferris' | 'flash' | 'flythrough' | 'gallery' | 'glitter' | 'honeycomb' | 'pan' | 'prism' | 'reveal' | 'ripple' | 'shred' | 'switch' | 'vortex' | 'warp' | 'wheelReverse' | 'window';
+/** Cardinal direction tokens from OOXML transition `@_dir`. */
+type PptxTransitionDirection4 = 'l' | 'r' | 'u' | 'd';
+/** 8-way direction tokens (cardinal + diagonal) for cover/uncover. */
+type PptxTransitionDirection8 = PptxTransitionDirection4 | 'lu' | 'ld' | 'ru' | 'rd';
+/** Strip direction tokens from OOXML. */
+type PptxStripDirection = 'lu' | 'ld' | 'ru' | 'rd';
+/** Split orientation from OOXML `@_orient`. */
+type PptxSplitOrientation = 'horz' | 'vert';
+/** Split in/out direction from OOXML `@_dir`. */
+type PptxSplitDirection = 'in' | 'out';
+/** Valid direction sets per transition type. */
+declare const TRANSITION_VALID_DIRECTIONS: Readonly<Partial<Record<PptxTransitionType, readonly string[]>>>;
+/**
+ * Slide transition configuration.
+ *
+ * @example
+ * ```ts
+ * const transition: PptxSlideTransition = {
+ *   type: "fade",
+ *   durationMs: 700,
+ *   advanceOnClick: true,
+ *   advanceAfterMs: 5000,
+ * };
+ * // => { type: "fade", durationMs: 700, advanceOnClick: true, advanceAfterMs: 5000 }
+ * ```
+ */
+interface PptxSlideTransition {
+    type: PptxTransitionType;
+    durationMs?: number;
+    direction?: string;
+    advanceOnClick?: boolean;
+    advanceAfterMs?: number;
+    /** Number of spokes for wheel transition (1-8). */
+    spokes?: number;
+    /** Pattern type for shred transition. */
+    pattern?: string;
+    /** Through-black flag for blinds/checker (OOXML `@_thruBlk`). */
+    thruBlk?: boolean;
+    /** Split orientation (horz/vert) parsed from `@_orient`. */
+    orient?: PptxSplitOrientation;
+    /** Relationship ID of transition sound from `p:sndAc/p:stSnd/@r:embed` when present. */
+    soundRId?: string;
+    /** Resolved transition sound media path within the package. */
+    soundPath?: string;
+    /** Human-readable sound file name (extracted from soundPath). */
+    soundFileName?: string;
+    /** Preserved sound-action XML node from `p:sndAc` for lossless round-trip. */
+    rawSoundAction?: XmlObject;
+    /** Preserved extension-list XML node from `p:extLst` within the transition for lossless round-trip. */
+    rawExtLst?: XmlObject;
+}
+
+/**
+ * Animation types: presets, triggers, timing, native parsed animation data,
+ * and the high-level {@link PptxElementAnimation} associated with each element.
+ *
+ * @module pptx-types/animation
+ */
+
+/**
+ * Built-in animation preset names used for entrance, exit, and emphasis effects.
+ *
+ * @example
+ * ```ts
+ * const preset: PptxAnimationPreset = "fadeIn";
+ * // => "fadeIn" — one of: none | fadeIn | flyIn | zoomIn | fadeOut | flyOut | zoomOut | spin | pulse | ...
+ * ```
+ */
+type PptxAnimationPreset = 'none' | 'appear' | 'fadeIn' | 'flyIn' | 'zoomIn' | 'bounceIn' | 'wipeIn' | 'splitIn' | 'dissolveIn' | 'wheelIn' | 'blindsIn' | 'boxIn' | 'floatIn' | 'riseUp' | 'swivel' | 'expandIn' | 'checkerboardIn' | 'flashIn' | 'peekIn' | 'randomBarsIn' | 'spinnerIn' | 'growTurnIn' | 'fadeOut' | 'flyOut' | 'zoomOut' | 'bounceOut' | 'wipeOut' | 'shrinkOut' | 'dissolveOut' | 'disappear' | 'spin' | 'pulse' | 'colorWave' | 'bounce' | 'flash' | 'growShrink' | 'teeter' | 'transparency' | 'boldFlash' | 'wave';
+/** Animation timing curve. */
+type PptxAnimationTimingCurve = 'ease' | 'ease-in' | 'ease-out' | 'linear';
+/** Repeat mode for animations. */
+type PptxAnimationRepeatMode = 'untilNextClick' | 'untilEndOfSlide';
+/** Animation trigger type from OOXML `p:cTn`. */
+type PptxAnimationTrigger = 'onClick' | 'onShapeClick' | 'onHover' | 'afterPrevious' | 'withPrevious' | 'afterDelay';
+/**
+ * Parsed native animation record from `p:timing / p:tnLst`.
+ *
+ * Represents a single animation node in the OOXML timing tree,
+ * including motion paths, scale transforms, and text build settings.
+ *
+ * @example
+ * ```ts
+ * const anim: PptxNativeAnimation = {
+ *   targetId: "shape_1",
+ *   presetClass: "entr",
+ *   presetId: 10,
+ *   trigger: "afterPrevious",
+ *   durationMs: 500,
+ * };
+ * // => { targetId: "shape_1", presetClass: "entr", presetId: 10, trigger: "afterPrevious", durationMs: 500 }
+ * ```
+ */
+interface PptxNativeAnimation {
+    /** Target element/shape ID. */
+    targetId?: string;
+    /** Trigger type. */
+    trigger?: PptxAnimationTrigger;
+    /** Shape ID that triggers this animation when clicked (interactive sequence). */
+    triggerShapeId?: string;
+    /** Effect preset class (entr, exit, emph, path). */
+    presetClass?: 'entr' | 'exit' | 'emph' | 'path';
+    /** Effect preset sub-type identifier. */
+    presetId?: number;
+    /** Duration in milliseconds. */
+    durationMs?: number;
+    /** Delay in milliseconds. */
+    delayMs?: number;
+    /** Trigger delay in milliseconds (for afterDelay). */
+    triggerDelayMs?: number;
+    /** SVG path string for motion path animations (`p:animMotion/@path`). */
+    motionPath?: string;
+    /** Motion origin: "layout" or "parent". */
+    motionOrigin?: string;
+    /** Whether the element auto-rotates to follow the motion path tangent (`p:animMotion/@rAng` = "0"). */
+    motionPathRotateAuto?: boolean;
+    /** Rotation angle in degrees for `p:animRot` (converted from 60000ths). */
+    rotationBy?: number;
+    /** X scale factor (percentage / 100) for `p:animScale`. */
+    scaleByX?: number;
+    /** Y scale factor (percentage / 100) for `p:animScale`. */
+    scaleByY?: number;
+    /** Repeat count (e.g. `2`, `Infinity` for indefinite). */
+    repeatCount?: number;
+    /** Whether the animation plays in reverse after completion. */
+    autoReverse?: boolean;
+    /** Text build type from `p:bldP/@build` in `p:bldLst`. */
+    buildType?: PptxTextBuildType;
+    /** Build level for multi-level lists from `p:bldP/@bldLvl`. */
+    buildLevel?: number;
+    /** Group ID linking a `p:bldP` entry to its timing animation node. */
+    groupId?: string;
+    /** Sound relationship ID to play when animation triggers (`p:stSnd`). */
+    soundRId?: string;
+    /** Resolved sound file path from relationship. */
+    soundPath?: string;
+    /** Whether to stop any currently playing sound (`p:endSnd`). */
+    stopSound?: boolean;
+    /** Structured start conditions parsed from `p:stCondLst`. */
+    startConditions?: AnimationCondition[];
+    /** Structured end conditions parsed from `p:endCondLst`. */
+    endConditions?: AnimationCondition[];
+    /** Preserved raw `p:endCondLst` XML node for lossless round-trip. */
+    rawEndCondLst?: XmlObject;
+    /** Color animation data from `p:animClr`. */
+    colorAnimation?: PptxColorAnimation;
+    /** Text-level target: character range or paragraph range from `p:txEl`. */
+    textTarget?: PptxTextAnimationTarget;
+    /** Whether this animation is inside an exclusive container (`p:excl`). */
+    exclusive?: boolean;
+    /** Command type from `p:cmd` (@_type: call/evt/verb). */
+    commandType?: string;
+    /** Command string from `p:cmd` (@_cmd). */
+    commandString?: string;
+    /** Iteration configuration from `p:iterate`. */
+    iterate?: PptxAnimationIterate;
+}
+/** Color animation data parsed from `p:animClr`. */
+interface PptxColorAnimation {
+    /** Color interpolation space: "hsl" or "rgb". */
+    colorSpace: 'hsl' | 'rgb';
+    /** Direction for HSL interpolation: "cw" (clockwise) or "ccw". */
+    direction?: 'cw' | 'ccw';
+    /** Starting color as hex string. */
+    fromColor?: string;
+    /** Ending color as hex string. */
+    toColor?: string;
+    /** Color delta (for "by" animations) as hex string. */
+    byColor?: string;
+    /**
+     * Target attribute from `p:attrNameLst` (e.g. "fillcolor", "style.color",
+     * "stroke.color"). Used to determine which CSS property to animate.
+     */
+    targetAttribute?: string;
+}
+/** Text-level animation target from `p:txEl`. */
+interface PptxTextAnimationTarget {
+    /** Target type: character range or paragraph range. */
+    type: 'charRg' | 'pRg';
+    /** Start index (0-based). */
+    start: number;
+    /** End index (exclusive). */
+    end: number;
+}
+/**
+ * Event types for animation conditions from `p:cond/@evt`.
+ *
+ * These map directly to OOXML condition event attribute values
+ * (ISO/IEC 29500-1 S19.5.28 CT_TLTimeCondition).
+ */
+type AnimationConditionEvent = 'onBegin' | 'onEnd' | 'begin' | 'end' | 'onClick' | 'onMouseOver' | 'onMouseOut' | 'onNext' | 'onPrev' | 'onStopAudio';
+/**
+ * Structured representation of a single OOXML animation condition
+ * from `p:cond` elements inside `p:stCondLst` or `p:endCondLst`.
+ *
+ * Conditions control when an animation starts or ends, and can reference
+ * events, time delays, and target time node IDs.
+ *
+ * @example
+ * ```ts
+ * const cond: AnimationCondition = {
+ *   event: "onClick",
+ *   delay: 0,
+ *   targetShapeId: "shape_5",
+ * };
+ * ```
+ */
+interface AnimationCondition {
+    /** Event that triggers the condition. */
+    event?: AnimationConditionEvent;
+    /** Delay in milliseconds (from `@_delay`). "indefinite" is represented as -1. */
+    delay?: number;
+    /** Target time node ID reference (from `@_tn`). */
+    targetTimeNodeId?: number;
+    /** Target shape ID from `p:tgtEl/p:spTgt/@spid`. */
+    targetShapeId?: string;
+    /** Whether the condition targets a slide (from `p:tgtEl/p:sldTgt`). */
+    targetSlide?: boolean;
+}
+/** Iteration configuration from `p:iterate`. */
+interface PptxAnimationIterate {
+    /** Iteration type: el (element), lt (letter), wd (word). */
+    type: 'el' | 'lt' | 'wd';
+    /** Whether to iterate backwards. */
+    backwards?: boolean;
+    /** Timing interval (percentage of total duration, in 1000ths). */
+    tmPct?: number;
+    /** Absolute timing interval in ms. */
+    tmAbs?: number;
+}
+/** Build type for text build (paragraph/word/letter) animations from `p:bldP/@build`. */
+type PptxTextBuildType = 'allAtOnce' | 'byParagraph' | 'byWord' | 'byChar';
+/** Direction for fly-in / fly-out / wipe effects. */
+type PptxAnimationDirection = 'fromLeft' | 'fromRight' | 'fromTop' | 'fromBottom' | 'fromTopLeft' | 'fromTopRight' | 'fromBottomLeft' | 'fromBottomRight';
+/** Sequence mode for paragraph-level animations. */
+type PptxAnimationSequence = 'asOne' | 'byParagraph' | 'byWord' | 'byLetter';
+/** Behavior after animation finishes. */
+type PptxAfterAnimationAction = 'none' | 'hideOnNextClick' | 'hideAfterAnimation' | 'dimToColor';
+/**
+ * High-level animation data associated with a slide element.
+ *
+ * Combines entrance, exit, and emphasis presets with timing and
+ * trigger configuration. Used by the editor’s animation panel
+ * and the `setPptxElementAnimation` tool.
+ *
+ * @example
+ * ```ts
+ * const anim: PptxElementAnimation = {
+ *   elementId: "title_1",
+ *   entrance: "fadeIn",
+ *   durationMs: 600,
+ *   order: 1,
+ *   trigger: "afterPrevious",
+ * };
+ * // => { elementId: "title_1", entrance: "fadeIn", durationMs: 600, order: 1, trigger: "afterPrevious" }
+ * ```
+ */
+interface PptxElementAnimation {
+    elementId: string;
+    entrance?: PptxAnimationPreset;
+    exit?: PptxAnimationPreset;
+    emphasis?: PptxAnimationPreset;
+    durationMs?: number;
+    delayMs?: number;
+    order?: number;
+    trigger?: PptxAnimationTrigger;
+    /** Shape ID that triggers this animation when clicked (interactive sequence). */
+    triggerShapeId?: string;
+    timingCurve?: PptxAnimationTimingCurve;
+    repeatCount?: number;
+    repeatMode?: PptxAnimationRepeatMode;
+    /** Direction for directional effects (fly in/out, wipe, etc.). */
+    direction?: PptxAnimationDirection;
+    /** Sequence mode — animate as one object or by paragraph/word/letter. */
+    sequence?: PptxAnimationSequence;
+    /** What happens after the animation finishes playing. */
+    afterAnimation?: PptxAfterAnimationAction;
+    /** Dim-to color hex (used when afterAnimation is "dimToColor"). */
+    afterAnimationColor?: string;
+    /** SVG motion path string for custom motion path animations. */
+    motionPath?: string;
+    /** Sound relationship ID to play when animation triggers (`p:stSnd`). */
+    soundRId?: string;
+    /** Resolved sound file path from relationship. */
+    soundPath?: string;
+    /** Whether to stop any currently playing sound (`p:endSnd`). */
+    stopSound?: boolean;
+}
+
+/**
+ * Media types: audio/video discriminator, bookmarks, runtime metadata,
+ * and caption/subtitle tracks.
+ *
+ * @module pptx-types/media
+ */
+/**
+ * Discriminator for embedded media element types.
+ *
+ * @example
+ * ```ts
+ * const kind: PptxMediaType = "video";
+ * // => "video" — one of: "video" | "audio" | "unknown"
+ * ```
+ */
+type PptxMediaType = 'video' | 'audio' | 'unknown';
+/**
+ * A named bookmark within a media clip timeline.
+ *
+ * @example
+ * ```ts
+ * const bm: MediaBookmark = {
+ *   id: "bm1",
+ *   time: 12.5,
+ *   label: "Intro ends",
+ * };
+ * // => satisfies MediaBookmark
+ * ```
+ */
+interface MediaBookmark {
+    id: string;
+    /** Position in seconds from the start of the clip. */
+    time: number;
+    /** User-visible label for this bookmark. */
+    label: string;
+}
+/**
+ * Runtime-extracted metadata about a media clip (populated from HTMLMediaElement).
+ *
+ * @example
+ * ```ts
+ * const meta: MediaMetadata = {
+ *   duration: 120.5,
+ *   videoWidth: 1920,
+ *   videoHeight: 1080,
+ *   codecInfo: "video/mp4; codecs=\"avc1.640028\"",
+ * };
+ * // => satisfies MediaMetadata
+ * ```
+ */
+interface MediaMetadata {
+    /** Duration in seconds. */
+    duration?: number;
+    /** Video width in pixels (video only). */
+    videoWidth?: number;
+    /** Video height in pixels (video only). */
+    videoHeight?: number;
+    /** MIME type / codec string reported by the browser. */
+    codecInfo?: string;
+}
+/**
+ * A closed-caption / subtitle track associated with a media element.
+ *
+ * @example
+ * ```ts
+ * const track: MediaCaptionTrack = {
+ *   id: "t1",
+ *   label: "English",
+ *   language: "en",
+ *   kind: "subtitles",
+ *   isDefault: true,
+ * };
+ * // => satisfies MediaCaptionTrack
+ * ```
+ */
+interface MediaCaptionTrack {
+    /** Unique ID for this track. */
+    id: string;
+    /** Human-readable label (e.g. "English", "Spanish"). */
+    label: string;
+    /** BCP-47 language code (e.g. "en", "es"). */
+    language: string;
+    /** Track kind: subtitles, captions, or descriptions. */
+    kind: 'subtitles' | 'captions' | 'descriptions';
+    /** Data URL or path to the VTT/SRT content within the PPTX archive. */
+    src?: string;
+    /** Inline VTT content (for embedded captions). */
+    content?: string;
+    /** Whether this track is the default/active one. */
+    isDefault?: boolean;
+}
+
+/**
+ * Action types: hyperlinks, slide jumps, macros, and action buttons.
+ *
+ * @module pptx-types/actions
+ */
+/**
+ * A parsed shape-level action from `a:hlinkClick` or `a:hlinkHover`.
+ *
+ * @example
+ * ```ts
+ * const link: PptxAction = {
+ *   url: "https://example.com",
+ *   tooltip: "Visit Example",
+ *   highlightClick: true,
+ * };
+ *
+ * const slideJump: PptxAction = {
+ *   action: "ppaction://hlinksldjump",
+ *   targetSlideIndex: 3,
+ * };
+ * // => satisfies PptxAction
+ * ```
+ */
+interface PptxAction {
+    /** Relationship ID referencing the action target. */
+    rId?: string;
+    /** OOXML action string (e.g. `ppaction://hlinksldjump`). */
+    action?: string;
+    /** Tooltip text shown on hover. */
+    tooltip?: string;
+    /** Whether the shape should highlight on click. */
+    highlightClick?: boolean;
+    /** Resolved URL or file path from the slide relationship map. */
+    url?: string;
+    /** Zero-based index into the slides array for internal slide jumps. */
+    targetSlideIndex?: number;
+    /** Relationship ID of an optional click sound (`a:snd/@r:embed`). */
+    soundRId?: string;
+    /** Resolved media target path for the optional click sound. */
+    soundPath?: string;
+}
+/**
+ * High-level action type for the action settings UI.
+ * Maps to OOXML `ppaction://` verbs + external URLs.
+ *
+ * @example
+ * ```ts
+ * const type: ElementActionType = "slide";
+ * // => "slide" — one of: "none" | "url" | "slide" | "firstSlide" | "lastSlide" | "prevSlide" | "nextSlide" | "endShow"
+ * ```
+ */
+type ElementActionType = 'none' | 'url' | 'slide' | 'firstSlide' | 'lastSlide' | 'prevSlide' | 'nextSlide' | 'endShow';
+/**
+ * User-facing action configuration stored on an element.
+ * This is a convenience wrapper around the lower-level `PptxAction` that maps
+ * to/from OOXML hyperlink/action attributes.
+ *
+ * @example
+ * ```ts
+ * const action: ElementAction = {
+ *   trigger: "click",
+ *   type: "url",
+ *   url: "https://example.com",
+ * };
+ *
+ * const jumpToSlide: ElementAction = {
+ *   trigger: "click",
+ *   type: "slide",
+ *   slideIndex: 5,
+ * };
+ * // => satisfies ElementAction
+ * ```
+ */
+interface ElementAction {
+    /** When the action fires. */
+    trigger: 'click' | 'hover';
+    /** What kind of action to perform. */
+    type: ElementActionType;
+    /** External URL (for 'url' type). */
+    url?: string;
+    /** Zero-based slide index (for 'slide' type). */
+    slideIndex?: number;
+}
+/**
+ * Preset action button definition (OOXML built-in action button shapes).
+ *
+ * @example
+ * ```ts
+ * const btn: ActionButtonPreset = {
+ *   shapeType: "actionButtonBackPrevious",
+ *   label: "Back",
+ *   defaultAction: "prevSlide",
+ *   iconPath: "M 0 0 L 10 5 L 0 10 Z",
+ * };
+ * // => satisfies ActionButtonPreset
+ * ```
+ */
+interface ActionButtonPreset {
+    /** OOXML preset geometry name (e.g. 'actionButtonBackPrevious'). */
+    shapeType: string;
+    /** Human-readable label. */
+    label: string;
+    /** Default action type pre-configured on the button. */
+    defaultAction: ElementActionType;
+    /** SVG path data for the icon rendered inside the button. */
+    iconPath: string;
+}
+
+/**
+ * Metadata types: slide comments, compatibility warnings, tags,
+ * custom properties, core/app document properties.
+ *
+ * @module pptx-types/metadata
+ */
+/**
+ * A slide comment — may be a legacy positional comment or a modern
+ * threaded comment with replies.
+ *
+ * @example
+ * ```ts
+ * const comment: PptxComment = {
+ *   id: "c1",
+ *   text: "Please update this chart.",
+ *   author: "Alice",
+ *   createdAt: "2024-06-01T10:00:00Z",
+ *   resolved: false,
+ * };
+ * // => satisfies PptxComment
+ * ```
+ */
+interface PptxComment {
+    id: string;
+    text: string;
+    /** Optional parent comment id for reply threading metadata. */
+    parentId?: string;
+    author?: string;
+    createdAt?: string;
+    x?: number;
+    y?: number;
+    /** Whether this comment has been resolved/marked done. */
+    resolved?: boolean;
+    /** Modern threaded comment support (p15:threadingInfo). */
+    threadId?: string;
+    /** Replies to this comment (for modern threaded comments). */
+    replies?: PptxComment[];
+    /** ID of the element this comment is associated with (if any). */
+    elementId?: string;
+}
+/**
+ * A comment author from `ppt/commentAuthors.xml`.
+ *
+ * Stores all attributes needed for lossless round-trip serialization
+ * of the `p:cmAuthor` element (id, name, initials, lastIdx, clrIdx).
+ *
+ * @see ECMA-376 Part 1, §19.4.2 (cmAuthor)
+ *
+ * @example
+ * ```ts
+ * const author: PptxCommentAuthor = {
+ *   id: "0",
+ *   name: "John Doe",
+ *   initials: "JD",
+ *   lastIdx: 3,
+ *   clrIdx: 0,
+ * };
+ * // => satisfies PptxCommentAuthor
+ * ```
+ */
+interface PptxCommentAuthor {
+    /** Unique numeric author identifier (`@_id`). */
+    id: string;
+    /** Author display name (`@_name`). */
+    name: string;
+    /** Author initials (`@_initials`). */
+    initials: string;
+    /** Last comment index used by this author (`@_lastIdx`). */
+    lastIdx: number;
+    /** Colour index assigned to this author (`@_clrIdx`). */
+    clrIdx: number;
+}
+/**
+ * A compatibility warning generated during parse or save when the
+ * file uses features not fully supported by the editor.
+ *
+ * @example
+ * ```ts
+ * const warning: PptxCompatibilityWarning = {
+ *   code: "UNSUPPORTED_3D",
+ *   message: "3D rotation effects may not render accurately.",
+ *   severity: "warning",
+ *   scope: "element",
+ *   slideId: "slide-1",
+ *   elementId: "elem-42",
+ * };
+ * // => satisfies PptxCompatibilityWarning
+ * ```
+ */
+interface PptxCompatibilityWarning {
+    code: string;
+    message: string;
+    severity: 'info' | 'warning';
+    scope: 'presentation' | 'slide' | 'element' | 'save';
+    slideId?: string;
+    elementId?: string;
+    xmlPath?: string;
+}
+/**
+ * A single name–value tag from `ppt/tags/*.xml`.
+ *
+ * @example
+ * ```ts
+ * const tag: PptxTag = { name: "CUSTOM_ID", value: "12345" };
+ * // => satisfies PptxTag
+ * ```
+ */
+interface PptxTag {
+    name: string;
+    value: string;
+}
+/**
+ * A collection of tags from a single tags XML part.
+ *
+ * @example
+ * ```ts
+ * const coll: PptxTagCollection = {
+ *   path: "ppt/tags/tag1.xml",
+ *   tags: [{ name: "CUSTOM_ID", value: "12345" }],
+ * };
+ * // => satisfies PptxTagCollection
+ * ```
+ */
+interface PptxTagCollection {
+    /** File path within the PPTX archive. */
+    path: string;
+    /** Tags in this collection. */
+    tags: PptxTag[];
+}
+/**
+ * A custom document property from `docProps/custom.xml`.
+ *
+ * @example
+ * ```ts
+ * const prop: PptxCustomProperty = {
+ *   name: "Project",
+ *   value: "pptx",
+ *   type: "lpwstr",
+ * };
+ * // => satisfies PptxCustomProperty
+ * ```
+ */
+interface PptxCustomProperty {
+    /** Property name. */
+    name: string;
+    /** Property value (always stringified). */
+    value: string;
+    /** Original VT type (e.g. "lpwstr", "i4", "bool", "filetime"). */
+    type: string;
+}
+/**
+ * Core document properties from `docProps/core.xml` (Dublin Core + OOXML).
+ *
+ * @example
+ * ```ts
+ * const core: PptxCoreProperties = {
+ *   title: "Q4 Business Review",
+ *   creator: "Alice",
+ *   created: "2024-01-15T08:00:00Z",
+ *   modified: "2024-06-01T12:30:00Z",
+ *   lastModifiedBy: "Bob",
+ * };
+ * // => satisfies PptxCoreProperties
+ * ```
+ */
+interface PptxCoreProperties {
+    /** dc:title */
+    title?: string;
+    /** dc:subject */
+    subject?: string;
+    /** dc:creator */
+    creator?: string;
+    /** cp:keywords */
+    keywords?: string;
+    /** dc:description */
+    description?: string;
+    /** cp:lastModifiedBy */
+    lastModifiedBy?: string;
+    /** cp:revision */
+    revision?: string;
+    /** dcterms:created (ISO 8601) */
+    created?: string;
+    /** dcterms:modified (ISO 8601) */
+    modified?: string;
+    /** cp:category */
+    category?: string;
+    /** cp:contentStatus */
+    contentStatus?: string;
+}
+/**
+ * Extended (application) properties from `docProps/app.xml`.
+ *
+ * @example
+ * ```ts
+ * const app: PptxAppProperties = {
+ *   application: "Microsoft Office PowerPoint",
+ *   appVersion: "16.0000",
+ *   slides: 24,
+ *   words: 1500,
+ *   company: "Acme Corp",
+ * };
+ * // => satisfies PptxAppProperties
+ * ```
+ */
+interface PptxAppProperties {
+    /** Application name (e.g. "Microsoft Office PowerPoint"). */
+    application?: string;
+    /** Application version string. */
+    appVersion?: string;
+    /** Presentation format (e.g. "On-screen Show (16:9)"). */
+    presentationFormat?: string;
+    /** Total number of slides. */
+    slides?: number;
+    /** Number of hidden slides. */
+    hiddenSlides?: number;
+    /** Number of notes slides. */
+    notes?: number;
+    /** Total editing time in minutes. */
+    totalTime?: number;
+    /** Number of words. */
+    words?: number;
+    /** Number of paragraphs. */
+    paragraphs?: number;
+    /** Company name. */
+    company?: string;
+    /** Manager name. */
+    manager?: string;
+    /** Template name. */
+    template?: string;
+    /** Hyperlink base URL. */
+    hyperlinkBase?: string;
+}
+
+/**
+ * Base and mixin interfaces for all PPTX slide elements, plus
+ * placeholder inheritance types.
+ *
+ * Every concrete element variant (text, shape, image …) extends
+ * {@link PptxElementBase}. Text-bearing elements also mix in
+ * {@link PptxTextProperties}, and shapes / connectors / images add
+ * {@link PptxShapeProperties}.
+ *
+ * @module pptx-types/element-base
+ */
+
+/**
+ * Properties shared by **every** element on a slide.
+ *
+ * Position and size are in pixels (converted from EMU at parse time).
+ * Optional properties apply to subsets of elements or may be absent in
+ * the original OOXML.
+ *
+ * @example
+ * ```ts
+ * const base: PptxElementBase = {
+ *   id: "el_001",
+ *   x: 100, y: 50,
+ *   width: 400, height: 200,
+ *   rotation: 15,
+ *   opacity: 0.9,
+ * };
+ * // => satisfies PptxElementBase
+ * ```
+ */
+interface PptxElementBase {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation?: number;
+    /** Skew along the X axis in degrees (parsed from `@_skewX` in 1/60000ths of a degree). */
+    skewX?: number;
+    /** Skew along the Y axis in degrees (parsed from `@_skewY` in 1/60000ths of a degree). */
+    skewY?: number;
+    flipHorizontal?: boolean;
+    flipVertical?: boolean;
+    /** Whether this element is hidden (used by the Elements Panel visibility toggle). */
+    hidden?: boolean;
+    /** Element-level opacity (0-1). */
+    opacity?: number;
+    rawXml?: XmlObject;
+    /** Shape-level click action (from `a:hlinkClick` on `p:cNvPr`). */
+    actionClick?: PptxAction;
+    /** Shape-level hover action (from `a:hlinkHover` on `p:cNvPr`). */
+    actionHover?: PptxAction;
+    /** Shape lock attributes parsed from `p:cNvSpPr/a:spLocks`. */
+    locks?: PptxShapeLocks;
+}
+/**
+ * Text content mixin — present on text boxes and shapes.
+ *
+ * Shapes can contain text overlaid on the shape geometry, so both
+ * `TextPptxElement` and `ShapePptxElement` extend this interface.
+ *
+ * @example
+ * ```ts
+ * const props: PptxTextProperties = {
+ *   text: "Hello World",
+ *   textStyle: { fontSize: 24, bold: true, color: "#333333" },
+ * };
+ * // => satisfies PptxTextProperties
+ * ```
+ */
+interface PptxTextProperties {
+    text?: string;
+    textStyle?: TextStyle;
+    /** Rich text segments with individual styling. */
+    textSegments?: TextSegment[];
+    /** Per-paragraph indentation (marginLeft, indent) for multi-level bullet support. */
+    paragraphIndents?: Array<{
+        marginLeft?: number;
+        indent?: number;
+    }>;
+    /** Placeholder prompt text inherited from layout/master (e.g. "Click to add title"). Shown as a greyed-out hint when the shape has no user-entered text. */
+    promptText?: string;
+    /** Linked text box chain ID from `a:bodyPr > a:linkedTxbx/@id` or `a:txbx > a:linkedTxbx/@id`. Text overflows from one linked frame to the next. */
+    linkedTxbxId?: number;
+    /** Sequence number within a linked text box chain (0-based). */
+    linkedTxbxSeq?: number;
+}
+/**
+ * Shape styling & geometry mixin — present on shapes, connectors, and images.
+ *
+ * @example
+ * ```ts
+ * const props: PptxShapeProperties = {
+ *   shapeType: "roundRect",
+ *   shapeStyle: { fillColor: "#0055AA", strokeWidth: 2 },
+ *   shapeAdjustments: { adj: 16667 },
+ * };
+ * // => satisfies PptxShapeProperties
+ * ```
+ */
+interface PptxShapeProperties {
+    shapeStyle?: ShapeStyle;
+    /** Preset geometry name, e.g. "rect", "ellipse", "roundRect". */
+    shapeType?: string;
+    /** Geometry adjustment values, e.g. `{ adj: 16667 }`. */
+    shapeAdjustments?: Record<string, number>;
+    /** Adjustment handles for interactive shape modification (yellow diamond handles). */
+    adjustmentHandles?: GeometryAdjustmentHandle[];
+}
+/**
+ * Text styling for a single indent level (0–8) inside a placeholder’s
+ * `a:lstStyle`.
+ *
+ * Used during placeholder inheritance to fill in defaults for font,
+ * bullet, and spacing properties the slide element does not override.
+ *
+ * @example
+ * ```ts
+ * const level0: PlaceholderTextLevelStyle = {
+ *   fontSize: 32,
+ *   bold: true,
+ *   bulletChar: "•",
+ * };
+ * // => satisfies PlaceholderTextLevelStyle
+ * ```
+ */
+interface PlaceholderTextLevelStyle {
+    fontFamily?: string;
+    fontSize?: number;
+    bold?: boolean;
+    italic?: boolean;
+    color?: string;
+    bulletChar?: string;
+    bulletAutoNumType?: string;
+    bulletFontFamily?: string;
+    bulletSizePercent?: number;
+    /** Bullet colour from `a:buClr` as hex string. */
+    bulletColor?: string;
+    /** Bullet size in points from `a:buSzPts`. */
+    bulletSizePts?: number;
+    /** True when `a:buNone` is present at this level. */
+    bulletNone?: boolean;
+    marginLeft?: number;
+    indent?: number;
+    alignment?: string;
+    lineSpacing?: number;
+    lineSpacingExactPt?: number;
+    spaceBefore?: number;
+    spaceAfter?: number;
+}
+/**
+ * Pre-parsed placeholder defaults extracted from a layout or master shape
+ * that carries a `<p:ph>` element.
+ *
+ * Used to fill in inherited text styles, bullet definitions, font sizes,
+ * and body properties that the slide shape does not explicitly override.
+ *
+ * @example
+ * ```ts
+ * const defaults: PlaceholderDefaults = {
+ *   type: "title",
+ *   levelStyles: {
+ *     0: { fontSize: 36, bold: true, alignment: "left" },
+ *   },
+ * };
+ * // => satisfies PlaceholderDefaults
+ * ```
+ */
+interface PlaceholderDefaults {
+    /** Placeholder type: 'title', 'body', 'ctrTitle', 'subTitle', 'dt', 'ftr', 'sldNum', etc. */
+    type: string;
+    /** Placeholder index (when present). */
+    idx?: number;
+    bodyInsetLeft?: number;
+    bodyInsetTop?: number;
+    bodyInsetRight?: number;
+    bodyInsetBottom?: number;
+    textAnchor?: string;
+    autoFit?: boolean;
+    /** Explicit autofit mode from OOXML body properties. See {@link TextStyle.autoFitMode}. */
+    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;
+    textWrap?: string;
+    /** Level-specific text styles keyed 0-8. */
+    levelStyles?: Record<number, PlaceholderTextLevelStyle>;
+    /** Prompt text extracted from the layout/master placeholder (e.g. "Click to add title"). */
+    promptText?: string;
+}
+
+/**
+ * Concrete element types (one per `type` discriminant) and the
+ * {@link PptxElement} discriminated union.
+ *
+ * Narrow on `element.type` to access variant-specific properties:
+ * ```ts
+ * if (element.type === "image") {
+ *   console.log(element.imageData); // ImagePptxElement-only
+ * }
+ * ```
+ *
+ * @module pptx-types/elements
+ */
+
+/**
+ * A text box — a plain rectangle containing text, typically with no
+ * visible fill or stroke.
+ *
+ * @example
+ * ```ts
+ * const title: TextPptxElement = {
+ *   type: "text",
+ *   id: "txt_1", x: 50, y: 30, width: 800, height: 60,
+ *   text: "Welcome",
+ *   textStyle: { fontSize: 36, bold: true },
+ * };
+ * // => satisfies TextPptxElement
+ * ```
+ */
+interface TextPptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties {
+    type: 'text';
+}
+/**
+ * A shape — may contain text and custom geometry (preset or freeform).
+ *
+ * @example
+ * ```ts
+ * const rect: ShapePptxElement = {
+ *   type: "shape",
+ *   id: "shp_1", x: 100, y: 200, width: 300, height: 150,
+ *   shapeType: "roundRect",
+ *   shapeStyle: { fillColor: "#00AA55" },
+ *   text: "OK",
+ * };
+ * // => satisfies ShapePptxElement
+ * ```
+ */
+interface ShapePptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties, PptxCustomPathProperties {
+    type: 'shape';
+}
+/**
+ * A connector (straight, bent, or curved line between shapes).
+ *
+ * Connector endpoints can snap to specific shapes via
+ * `shapeStyle.connectorStartConnection` / `connectorEndConnection`.
+ *
+ * @example
+ * ```ts
+ * const line: ConnectorPptxElement = {
+ *   type: "connector",
+ *   id: "cxn_1", x: 100, y: 100, width: 200, height: 0,
+ *   shapeStyle: {
+ *     strokeColor: "#333",
+ *     connectorEndArrow: "triangle",
+ *   },
+ * };
+ * // => satisfies ConnectorPptxElement
+ * ```
+ */
+interface ConnectorPptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties {
+    type: 'connector';
+}
+/**
+ * An image element from an OOXML `<p:pic>` node with `type: "image"`.
+ *
+ * @example
+ * ```ts
+ * const img: ImagePptxElement = {
+ *   type: "image",
+ *   id: "img_1", x: 0, y: 0, width: 960, height: 540,
+ *   imagePath: "ppt/media/image1.png",
+ *   altText: "Background scenery",
+ * };
+ * // => satisfies ImagePptxElement
+ * ```
+ */
+interface ImagePptxElement extends PptxElementBase, PptxShapeProperties, PptxCustomPathProperties, PptxImageProperties {
+    type: 'image';
+}
+/**
+ * A picture element from an OOXML `<p:pic>` node with `type: "picture"`.
+ *
+ * Functionally identical to {@link ImagePptxElement} but distinguished by
+ * the `type` discriminant for semantic clarity.
+ */
+interface PicturePptxElement extends PptxElementBase, PptxShapeProperties, PptxCustomPathProperties, PptxImageProperties {
+    type: 'picture';
+}
+/**
+ * A table embedded via a `<p:graphicFrame>`.
+ *
+ * @example
+ * ```ts
+ * const tbl: TablePptxElement = {
+ *   type: "table",
+ *   id: "tbl_1", x: 50, y: 200, width: 860, height: 300,
+ *   tableData: {
+ *     rows: [
+ *       { cells: [{ text: "Name" }, { text: "Score" }] },
+ *       { cells: [{ text: "Alice" }, { text: "95" }] },
+ *     ],
+ *   },
+ * };
+ * // => satisfies TablePptxElement
+ * ```
+ */
+interface TablePptxElement extends PptxElementBase {
+    type: 'table';
+    /** Parsed table cell data for editing. */
+    tableData?: PptxTableData;
+}
+/**
+ * A chart embedded via a `<p:graphicFrame>`.
+ *
+ * Chart data is parsed from the related `chartN.xml` / `chartExN.xml`
+ * parts inside the PPTX archive.
+ */
+interface ChartPptxElement extends PptxElementBase {
+    type: 'chart';
+    chartData?: PptxChartData;
+}
+/**
+ * A SmartArt diagram embedded via a `<p:graphicFrame>`.
+ *
+ * SmartArt data is extracted from `dgm:dataModel` parts. The editor
+ * renders a simplified view; full editing is not supported.
+ */
+interface SmartArtPptxElement extends PptxElementBase {
+    type: 'smartArt';
+    smartArtData?: PptxSmartArtData;
+}
+/**
+ * Recognised OLE object application types derived from `progId` / `clsId`.
+ *
+ * Used to show type-specific icons and previews in the editor.
+ */
+type OleObjectType = 'excel' | 'word' | 'pdf' | 'visio' | 'mathtype' | 'package' | 'unknown';
+/**
+ * An OLE (Object Linking and Embedding) object.
+ *
+ * OLE objects can be embedded Excel sheets, Word documents, PDFs, Visio
+ * diagrams, MathType equations, or generic "packages". They carry a
+ * preview image for display and optional binary data for extraction.
+ *
+ * @example
+ * ```ts
+ * const ole: OlePptxElement = {
+ *   type: "ole",
+ *   id: "ole_1", x: 100, y: 200, width: 400, height: 300,
+ *   oleObjectType: "excel",
+ *   oleProgId: "Excel.Sheet.12",
+ *   fileName: "budget.xlsx",
+ * };
+ * // => satisfies OlePptxElement
+ * ```
+ */
+interface OlePptxElement extends PptxElementBase {
+    type: 'ole';
+    oleTarget?: string;
+    oleProgId?: string;
+    oleName?: string;
+    /** CLSID of the OLE object (from `@_classid`). */
+    oleClsId?: string;
+    /** Detected application type (excel, word, pdf, etc.). */
+    oleObjectType?: OleObjectType;
+    /** File extension for the embedded binary (e.g. "xlsx", "docx"). */
+    oleFileExtension?: string;
+    /** Original file name when available. */
+    fileName?: string;
+    /** Whether this is a linked (vs. embedded) object. */
+    isLinked?: boolean;
+    /** External file path for linked OLE objects (TargetMode="External"). */
+    externalPath?: string;
+    /** Data-URL or path for the OLE preview image. */
+    previewImage?: string;
+    /** Decoded preview image as a data-URL. */
+    previewImageData?: string;
+}
+/**
+ * An audio or video media element.
+ *
+ * Media elements reference files inside the PPTX archive
+ * (`mediaPath`) and may include trim points, poster frames, and
+ * playback settings for presentation mode.
+ *
+ * @example
+ * ```ts
+ * const video: MediaPptxElement = {
+ *   type: "media",
+ *   id: "vid_1", x: 50, y: 100, width: 640, height: 360,
+ *   mediaType: "video",
+ *   mediaPath: "ppt/media/media1.mp4",
+ *   autoPlay: true,
+ *   volume: 0.8,
+ * };
+ * // => satisfies MediaPptxElement
+ * ```
+ */
+interface MediaPptxElement extends PptxElementBase {
+    type: 'media';
+    mediaType?: PptxMediaType;
+    mediaPath?: string;
+    mediaData?: string;
+    mediaMimeType?: string;
+    /** Trim start in milliseconds (from p:cMediaNode p:cTn @st). */
+    trimStartMs?: number;
+    /** Trim end in milliseconds (from p:cMediaNode p:cTn @end). */
+    trimEndMs?: number;
+    /** Path to the poster/preview image inside the ZIP. */
+    posterFramePath?: string;
+    /** Base64 data-URL for the poster frame image. */
+    posterFrameData?: string;
+    /** Whether media should play full-screen during presentation. */
+    fullScreen?: boolean;
+    /** Whether media should loop continuously. */
+    loop?: boolean;
+    /** Fade-in duration in seconds. */
+    fadeInDuration?: number;
+    /** Fade-out duration in seconds. */
+    fadeOutDuration?: number;
+    /** Playback volume (0 to 1). */
+    volume?: number;
+    /** Whether media auto-plays on slide entry. */
+    autoPlay?: boolean;
+    /** Whether audio continues playing across slide transitions (presentation mode). */
+    playAcrossSlides?: boolean;
+    /** Hide the element when media is not actively playing. */
+    hideWhenNotPlaying?: boolean;
+    /** Named time bookmarks within the clip. */
+    bookmarks?: MediaBookmark[];
+    /** Playback speed multiplier (1 = normal, 2 = double, 0.5 = half). */
+    playbackSpeed?: number;
+    /** Runtime-extracted metadata (duration, resolution, codec). */
+    metadata?: MediaMetadata;
+    /** Closed caption / subtitle tracks. */
+    captionTracks?: MediaCaptionTrack[];
+    /** Whether the media source is missing/broken (file not found in archive). */
+    mediaMissing?: boolean;
+}
+/**
+ * A group container that holds child elements.
+ *
+ * Children inherit the group’s transform, so moving/resizing the group
+ * affects all children proportionally.
+ *
+ * @example
+ * ```ts
+ * const group: GroupPptxElement = {
+ *   type: "group",
+ *   id: "grp_1", x: 0, y: 0, width: 960, height: 540,
+ *   children: [textEl, shapeEl],
+ * };
+ * // => satisfies GroupPptxElement
+ * ```
+ */
+interface GroupPptxElement extends PptxElementBase {
+    type: 'group';
+    /** Child elements contained within this group. */
+    children: PptxElement[];
+    /** Fill style extracted from the group's `p:grpSpPr`, used for `a:grpFill` inheritance. */
+    groupFill?: ShapeStyle;
+}
+/**
+ * A freehand ink / drawing stroke captured with a stylus or mouse.
+ *
+ * Ink strokes are stored as SVG path data strings. Each path may
+ * have independent colour, width, and opacity.
+ */
+interface InkPptxElement extends PptxElementBase {
+    type: 'ink';
+    /** SVG path data for ink strokes. */
+    inkPaths: string[];
+    /** Per-path stroke colours. */
+    inkColors?: string[];
+    /** Per-path stroke widths. */
+    inkWidths?: number[];
+    /** Per-path opacities (0-1). */
+    inkOpacities?: number[];
+    /** Drawing tool used: pen, highlighter, or eraser. */
+    inkTool?: 'pen' | 'highlighter' | 'eraser';
+    /**
+     * Per-path arrays of per-point pressure values (0-1).
+     *
+     * Each entry corresponds to the path at the same index in `inkPaths`.
+     * Each inner array contains one pressure value per sampled point along
+     * the stroke. When present, the renderer uses these values to produce
+     * variable-width strokes that reflect stylus/pen pressure.
+     */
+    inkPointPressures?: number[][];
+}
+/**
+ * A single ink stroke within a {@link ContentPartPptxElement}.
+ */
+interface ContentPartInkStroke {
+    path: string;
+    color: string;
+    width: number;
+    opacity: number;
+    /**
+     * Per-point pressure values (0-1) for this stroke.
+     *
+     * When present, the renderer uses these values to produce
+     * variable-width strokes that reflect stylus/pen pressure.
+     */
+    pressures?: number[];
+}
+/**
+ * A content-part element wrapped in `mc:AlternateContent`.
+ *
+ * Typically contains ink strokes from modern PowerPoint pen/highlighter.
+ */
+interface ContentPartPptxElement extends PptxElementBase {
+    type: 'contentPart';
+    /** Ink strokes contained in this content part. */
+    inkStrokes?: ContentPartInkStroke[];
+}
+/**
+ * A Slide Zoom or Section Zoom element (PowerPoint Zoom Object).
+ *
+ * Zoom elements display a live thumbnail of the target slide and
+ * navigate to it on click during presentation mode.
+ *
+ * @example
+ * ```ts
+ * const zoom: ZoomPptxElement = {
+ *   type: "zoom",
+ *   id: "zm_1", x: 300, y: 200, width: 200, height: 120,
+ *   zoomType: "slide",
+ *   targetSlideIndex: 5,
+ * };
+ * // => satisfies ZoomPptxElement
+ * ```
+ */
+interface ZoomPptxElement extends PptxElementBase, PptxImageProperties {
+    type: 'zoom';
+    /** Type of zoom: slide-level or section-level. */
+    zoomType: 'slide' | 'section';
+    /** Zero-based index of the target slide. */
+    targetSlideIndex: number;
+    /** Section ID for section zoom. */
+    targetSectionId?: string;
+}
+/**
+ * A 3D model object embedded via `p16:model3D` inside an
+ * `mc:AlternateContent` block (PowerPoint 365+).
+ *
+ * The element carries the path to the `.glb`/`.gltf` binary inside
+ * the ZIP and a poster/fallback image for rendering in viewers that
+ * do not support interactive 3D.
+ */
+interface Model3DPptxElement extends PptxElementBase, PptxImageProperties {
+    type: 'model3d';
+    /** Path to the 3D model file inside the ZIP. */
+    modelPath?: string;
+    /** Base64 data URL of the 3D model binary. */
+    modelData?: string;
+    /** MIME type of the model (e.g. "model/gltf-binary"). */
+    modelMimeType?: string;
+    /** Poster/preview image shown when 3D rendering is unavailable. */
+    posterImage?: string;
+}
+/** An element whose type is not recognised by the parser. */
+interface UnknownPptxElement extends PptxElementBase {
+    type: 'unknown';
+}
+/**
+ * A single element on a PPTX slide.
+ *
+ * This is a **discriminated union** — narrow on `element.type` to access
+ * variant-specific properties like `imageData` (image/picture), `pathData`
+ * (shape), or `textSegments` (text/shape).
+ */
+type PptxElement = TextPptxElement | ShapePptxElement | ConnectorPptxElement | ImagePptxElement | PicturePptxElement | TablePptxElement | ChartPptxElement | SmartArtPptxElement | OlePptxElement | MediaPptxElement | GroupPptxElement | InkPptxElement | ContentPartPptxElement | ZoomPptxElement | Model3DPptxElement | UnknownPptxElement;
+/** Elements that can contain text content (text boxes, shapes, and connectors). */
+type PptxElementWithText = TextPptxElement | ShapePptxElement | ConnectorPptxElement;
+/** Elements that carry shape styling (fill, stroke, geometry). */
+type PptxElementWithShapeStyle = TextPptxElement | ShapePptxElement | ConnectorPptxElement | ImagePptxElement | PicturePptxElement;
+/** Elements that hold raster image data. */
+type PptxImageLikeElement = ImagePptxElement | PicturePptxElement;
+
+/**
+ * Theme object model — colour scheme, font scheme, and format scheme
+ * parsed from `ppt/theme/theme1.xml`.
+ *
+ * The colour scheme provides the 12 canonical OOXML colour slots.
+ * The font scheme defines major (heading) and minor (body) typefaces.
+ * The format scheme holds fill, line, and effect style matrices at
+ * three intensity levels (subtle, moderate, intense).
+ *
+ * @module pptx-types/theme
+ */
+/**
+ * The 12 OOXML theme colour scheme keys in canonical order.
+ *
+ * @example
+ * ```ts
+ * for (const key of THEME_COLOR_SCHEME_KEYS) {
+ *   console.log(key, theme.colorScheme?.[key]);
+ * }
+ * // => e.g. "dk1 #000000", "lt1 #FFFFFF", "accent1 #4F81BD", …
+ * ```
+ */
+declare const THEME_COLOR_SCHEME_KEYS: readonly ["dk1", "lt1", "dk2", "lt2", "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "hlink", "folHlink"];
+/**
+ * Resolved hex values for the 12 theme colour slots.
+ *
+ * @example
+ * ```ts
+ * const scheme: PptxThemeColorScheme = {
+ *   dk1: "#000000", lt1: "#FFFFFF",
+ *   dk2: "#1F497D", lt2: "#EEECE1",
+ *   accent1: "#4F81BD", accent2: "#C0504D",
+ *   accent3: "#9BBB59", accent4: "#8064A2",
+ *   accent5: "#4BACC6", accent6: "#F79646",
+ *   hlink: "#0000FF", folHlink: "#800080",
+ * };
+ * // => satisfies PptxThemeColorScheme
+ * ```
+ */
+interface PptxThemeColorScheme {
+    dk1: string;
+    lt1: string;
+    dk2: string;
+    lt2: string;
+    accent1: string;
+    accent2: string;
+    accent3: string;
+    accent4: string;
+    accent5: string;
+    accent6: string;
+    hlink: string;
+    folHlink: string;
+}
+/**
+ * A font-family triplet for major or minor theme fonts.
+ *
+ * Supports Latin, East Asian, and Complex Script font families.
+ *
+ * @example
+ * ```ts
+ * const fonts: PptxThemeFontGroup = {
+ *   latin: "Calibri Light",
+ *   eastAsia: "MS PGothic",
+ *   complexScript: "Arial",
+ * };
+ * // => satisfies PptxThemeFontGroup
+ * ```
+ */
+interface PptxThemeFontGroup {
+    latin?: string;
+    eastAsia?: string;
+    complexScript?: string;
+}
+/**
+ * Theme font scheme — major (headings) and minor (body) font families.
+ *
+ * @example
+ * ```ts
+ * const scheme: PptxThemeFontScheme = {
+ *   majorFont: { latin: "Calibri Light" },
+ *   minorFont: { latin: "Calibri", eastAsia: "MS PGothic" },
+ * };
+ * // => satisfies PptxThemeFontScheme
+ * ```
+ */
+interface PptxThemeFontScheme {
+    majorFont?: PptxThemeFontGroup;
+    minorFont?: PptxThemeFontGroup;
+}
+/**
+ * A single fill style entry from the theme format scheme.
+ * Each entry is one of: solid, gradient, pattern, or no fill.
+ * The raw XML node is also stored so that `phClr` substitution can happen
+ * at resolution time.
+ *
+ * @example
+ * ```ts
+ * const solidFill: PptxThemeFillStyle = {
+ *   kind: "solid",
+ *   color: "#4F81BD",
+ *   opacity: 1,
+ * };
+ *
+ * const gradientFill: PptxThemeFillStyle = {
+ *   kind: "gradient",
+ *   gradientAngle: 90,
+ *   gradientType: "linear",
+ *   gradientStops: [
+ *     { color: "#4F81BD", position: 0 },
+ *     { color: "#1F497D", position: 1 },
+ *   ],
+ * };
+ * // => satisfies PptxThemeFillStyle
+ * ```
+ */
+interface PptxThemeFillStyle {
+    /** Discriminator for the fill type. */
+    kind: 'solid' | 'gradient' | 'pattern' | 'none';
+    /** Pre-resolved colour (may be `undefined` when `phClr`-dependent). */
+    color?: string;
+    opacity?: number;
+    /** Gradient-specific fields (only present when `kind === "gradient"`). */
+    gradientStops?: Array<{
+        color: string;
+        position: number;
+        opacity?: number;
+    }>;
+    gradientAngle?: number;
+    gradientType?: 'linear' | 'radial';
+    gradientCss?: string;
+    /** Pattern-specific fields (only present when `kind === "pattern"`). */
+    patternPreset?: string;
+    patternBackgroundColor?: string;
+    /** Raw XML node preserved for `phClr` re-resolution. */
+    rawNode?: unknown;
+}
+/**
+ * A single line style entry from `a:lnStyleLst`.
+ * Provides width, dash, join, cap, and optional fill colour.
+ *
+ * @example
+ * ```ts
+ * const line: PptxThemeLineStyle = {
+ *   width: 1.5,
+ *   color: "#4F81BD",
+ *   dash: "solid",
+ *   lineJoin: "round",
+ *   lineCap: "flat",
+ * };
+ * // => satisfies PptxThemeLineStyle
+ * ```
+ */
+interface PptxThemeLineStyle {
+    /** Line width in pixels (converted from EMU). */
+    width?: number;
+    color?: string;
+    opacity?: number;
+    dash?: string;
+    lineJoin?: 'round' | 'bevel' | 'miter';
+    lineCap?: 'flat' | 'rnd' | 'sq';
+    compoundLine?: 'sng' | 'dbl' | 'thickThin' | 'thinThick' | 'tri';
+    /** Raw XML node preserved for `phClr` re-resolution. */
+    rawNode?: unknown;
+}
+/**
+ * A single effect style entry from `a:effectStyleLst`.
+ * Each entry may define shadow, glow, soft-edge, reflection, blur,
+ * and optionally a 3-D scene/shape.
+ *
+ * @example
+ * ```ts
+ * const dropShadow: PptxThemeEffectStyle = {
+ *   shadowColor: "#000000",
+ *   shadowBlur: 4,
+ *   shadowOffsetX: 2,
+ *   shadowOffsetY: 3,
+ *   shadowOpacity: 0.4,
+ * };
+ * // => satisfies PptxThemeEffectStyle
+ * ```
+ */
+interface PptxThemeEffectStyle {
+    shadowColor?: string;
+    shadowBlur?: number;
+    shadowOffsetX?: number;
+    shadowOffsetY?: number;
+    shadowOpacity?: number;
+    glowColor?: string;
+    glowRadius?: number;
+    glowOpacity?: number;
+    softEdgeRadius?: number;
+    innerShadowColor?: string;
+    innerShadowOpacity?: number;
+    innerShadowBlur?: number;
+    innerShadowOffsetX?: number;
+    innerShadowOffsetY?: number;
+    reflectionBlurRadius?: number;
+    reflectionStartOpacity?: number;
+    reflectionEndOpacity?: number;
+    reflectionEndPosition?: number;
+    reflectionDirection?: number;
+    reflectionRotation?: number;
+    reflectionDistance?: number;
+    /** 3D scene/camera from `a:scene3d` on the effect style (idx 3 typically). */
+    scene3d?: Pptx3DScene;
+    /** 3D shape extrusion/bevel from `a:sp3d` on the effect style (idx 3 typically). */
+    shape3d?: Pptx3DShape;
+    /** Raw XML node preserved for `phClr` re-resolution. */
+    rawNode?: unknown;
+}
+/**
+ * The full parsed format scheme from `a:fmtScheme` inside `a:themeElements`.
+ * Contains three fill style lists and one line/effect style list each,
+ * at three intensity levels: subtle (idx 1), moderate (idx 2), intense (idx 3).
+ *
+ * OOXML reference indices:
+ * - fillStyleLst:   idx 1-3  (used by `a:fillRef @idx` 1-3)
+ * - lnStyleLst:     idx 1-3  (used by `a:lnRef @idx` 1-3)
+ * - effectStyleLst:  idx 1-3  (used by `a:effectRef @idx` 1-3)
+ * - bgFillStyleLst:  idx 1-3  (used by `a:fillRef @idx` 1001-1003)
+ *
+ * @example
+ * ```ts
+ * const fmt: PptxThemeFormatScheme = {
+ *   name: "Office",
+ *   fillStyles: [solidFill, gradientFill, intenseFill],
+ *   lineStyles: [thinLine, mediumLine, thickLine],
+ *   effectStyles: [subtle, moderate, intense],
+ *   backgroundFillStyles: [solidBg, gradientBg, intenseBg],
+ * };
+ * // => satisfies PptxThemeFormatScheme
+ * ```
+ */
+interface PptxThemeFormatScheme {
+    /** The `@name` attribute of the format scheme. */
+    name?: string;
+    /** Fill styles at indices 1-3 (subtle, moderate, intense). */
+    fillStyles: PptxThemeFillStyle[];
+    /** Line styles at indices 1-3. */
+    lineStyles: PptxThemeLineStyle[];
+    /** Effect styles at indices 1-3. */
+    effectStyles: PptxThemeEffectStyle[];
+    /** Background fill styles at indices 1-3 (referenced via idx 1001-1003). */
+    backgroundFillStyles: PptxThemeFillStyle[];
+}
+/**
+ * Full parsed theme object available to renderers.
+ *
+ * @example
+ * ```ts
+ * const theme: PptxTheme = {
+ *   name: "Office Theme",
+ *   colorScheme: { dk1: "#000", lt1: "#FFF", /* … *\/ },
+ *   fontScheme: {
+ *     majorFont: { latin: "Calibri Light" },
+ *     minorFont: { latin: "Calibri" },
+ *   },
+ * };
+ * // => satisfies PptxTheme
+ * ```
+ */
+interface PptxTheme {
+    /** Theme name from `a:theme @name`. */
+    name?: string;
+    /** Resolved colour scheme. */
+    colorScheme?: PptxThemeColorScheme;
+    /** Resolved font scheme. */
+    fontScheme?: PptxThemeFontScheme;
+    /** Format scheme — fill, line, effect and background fill style matrices. */
+    formatScheme?: PptxThemeFormatScheme;
+}
+
+/**
+ * Master and layout types: notes master, handout master, slide master,
+ * slide layout, and theme options.
+ *
+ * @module pptx-types/masters
+ */
+
+/**
+ * Parsed notes master from `ppt/notesMasters/notesMaster1.xml`.
+ *
+ * @example
+ * ```ts
+ * const notes: PptxNotesMaster = {
+ *   path: "ppt/notesMasters/notesMaster1.xml",
+ *   backgroundColor: "#FFFFFF",
+ *   placeholders: [{ type: "body" }, { type: "sldImg" }],
+ * };
+ * // => satisfies PptxNotesMaster
+ * ```
+ */
+interface PptxNotesMaster {
+    /** File path within the PPTX archive. */
+    path: string;
+    /** Background colour of the notes master. */
+    backgroundColor?: string;
+    /** Background image data URL. */
+    backgroundImage?: string;
+    /** Placeholder shapes found on the notes master. */
+    placeholders?: Array<{
+        type: string;
+        idx?: string;
+    }>;
+    /** Editable elements on the notes master (header, footer, date, page number, slide image, notes body). */
+    elements?: PptxElement[];
+}
+/**
+ * Parsed handout master from `ppt/handoutMasters/handoutMaster1.xml`.
+ *
+ * @example
+ * ```ts
+ * const handout: PptxHandoutMaster = {
+ *   path: "ppt/handoutMasters/handoutMaster1.xml",
+ *   slidesPerPage: 6,
+ * };
+ * // => satisfies PptxHandoutMaster
+ * ```
+ */
+interface PptxHandoutMaster {
+    /** File path within the PPTX archive. */
+    path: string;
+    /** Background colour of the handout master. */
+    backgroundColor?: string;
+    /** Background image data URL. */
+    backgroundImage?: string;
+    /** Placeholder shapes found on the handout master. */
+    placeholders?: Array<{
+        type: string;
+        idx?: string;
+    }>;
+    /** Editable elements on the handout master (header, footer, date, page number, slide placeholders). */
+    elements?: PptxElement[];
+    /** Number of slides per page for handout print layout (1, 2, 3, 4, 6, or 9). */
+    slidesPerPage?: number;
+}
+/**
+ * Active tab within the master view sidebar.
+ *
+ * @example
+ * ```ts
+ * const tab: MasterViewTab = "slides";
+ * // => "slides" — one of: "slides" | "notes" | "handout"
+ * ```
+ */
+type MasterViewTab = 'slides' | 'notes' | 'handout';
+/**
+ * Structured slide master data.
+ *
+ * @example
+ * ```ts
+ * const master: PptxSlideMaster = {
+ *   path: "ppt/slideMasters/slideMaster1.xml",
+ *   name: "Office Theme",
+ *   backgroundColor: "#FFFFFF",
+ *   themePath: "ppt/theme/theme1.xml",
+ * };
+ * // => satisfies PptxSlideMaster
+ * ```
+ */
+interface PptxSlideMaster {
+    /** File path within the PPTX archive. */
+    path: string;
+    /** Human-readable name if available. */
+    name?: string;
+    /** Background colour of the slide master. */
+    backgroundColor?: string;
+    /** Background image data URL for the slide master. */
+    backgroundImage?: string;
+    /** Theme file path this master references. */
+    themePath?: string;
+    /** Layout paths associated with this master. */
+    layoutPaths?: string[];
+    /** Placeholder shapes on the master. */
+    placeholders?: Array<{
+        type: string;
+        idx?: string;
+    }>;
+    /** Parsed element shapes on the master slide (for master view rendering). */
+    elements?: PptxElement[];
+    /** Parsed slide layout objects associated with this master. */
+    layouts?: PptxSlideLayout[];
+    /** Text styles from `p:txStyles` — title, body, and other text defaults. */
+    txStyles?: PptxMasterTextStyles;
+}
+/**
+ * Per-level paragraph properties for a text style category.
+ * Each entry maps a 0-based level index to its style defaults.
+ */
+type PptxTextStyleLevels = Record<number, PlaceholderTextLevelStyle>;
+/**
+ * Text styles parsed from `p:txStyles` on a slide master.
+ * Provides cascading defaults for title, body, and other text.
+ */
+interface PptxMasterTextStyles {
+    /** Title text style (`p:titleStyle`). */
+    titleStyle?: PptxTextStyleLevels;
+    /** Body text style (`p:bodyStyle`). */
+    bodyStyle?: PptxTextStyleLevels;
+    /** Other text style (`p:otherStyle`). */
+    otherStyle?: PptxTextStyleLevels;
+}
+/**
+ * A slide layout associated with a slide master.
+ *
+ * @example
+ * ```ts
+ * const layout: PptxSlideLayout = {
+ *   path: "ppt/slideLayouts/slideLayout2.xml",
+ *   name: "Title and Content",
+ * };
+ * // => satisfies PptxSlideLayout
+ * ```
+ */
+interface PptxSlideLayout {
+    /** File path within the PPTX archive. */
+    path: string;
+    /** Human-readable layout name. */
+    name?: string;
+    /** Background colour of the layout. */
+    backgroundColor?: string;
+    /** Background image data URL for the layout. */
+    backgroundImage?: string;
+    /** Parsed element shapes on the layout. */
+    elements?: PptxElement[];
+    /** Placeholder shapes on the layout. */
+    placeholders?: Array<{
+        type: string;
+        idx?: string;
+    }>;
+    /** Matching name attribute for layout identification (`@matchingName`). */
+    matchingName?: string;
+    /** Whether the layout is marked as preserved (prevent deletion, `@preserve`). */
+    preserve?: boolean;
+    /** Whether master placeholder animations should play (`@showMasterPhAnim`). */
+    showMasterPhAnim?: boolean;
+    /** Whether this layout is user-drawn (`@userDrawn`). */
+    userDrawn?: boolean;
+    /** Colour map override from `p:clrMapOvr`. */
+    clrMapOverride?: Record<string, string>;
+}
+/**
+ * A theme part available in the presentation package.
+ *
+ * @example
+ * ```ts
+ * const opt: PptxThemeOption = {
+ *   path: "ppt/theme/theme1.xml",
+ *   name: "Office Theme",
+ * };
+ * // => satisfies PptxThemeOption
+ * ```
+ */
+interface PptxThemeOption {
+    /** File path within the PPTX archive (e.g. `ppt/theme/theme2.xml`). */
+    path: string;
+    /** Human-readable theme name from `a:theme/@name`, when present. */
+    name?: string;
+}
+
+/**
+ * View properties types parsed from `ppt/viewProps.xml`.
+ *
+ * Models the `p:viewPr` element and its child views:
+ * normalViewPr, slideViewPr, outlineViewPr, notesTextViewPr,
+ * sorterViewPr, notesViewPr.
+ *
+ * @module pptx-types/view-properties
+ */
+/**
+ * Scale factor for a view (numerator / denominator percentage).
+ */
+interface PptxViewScale {
+    /** Numerator of the scale percentage (e.g. 100 for 100%). */
+    n: number;
+    /** Denominator of the scale percentage (e.g. 100 for 100%). */
+    d: number;
+}
+/**
+ * Origin point for a view (x, y in twips or EMU).
+ */
+interface PptxViewOrigin {
+    x: number;
+    y: number;
+}
+/**
+ * Restored region dimensions for normal view splitter.
+ * Represents `p:restoredLeft` or `p:restoredTop`.
+ */
+interface PptxRestoredRegion {
+    /** Size as a percentage of the available space (thousandths of a percent). */
+    sz: number;
+    /** Whether auto-adjust is enabled. */
+    autoAdjust?: boolean;
+}
+/**
+ * Normal view properties (`p:normalViewPr`).
+ * Controls the splitter positions in normal (editing) view.
+ */
+interface PptxNormalViewProperties {
+    /** Whether to show outline icons in the slide panel. */
+    showOutlineIcons?: boolean;
+    /** Whether the outline/slide panel is snapped closed. */
+    snapVertSplitter?: boolean;
+    /** Vertical splitter bar state: 'minimized' | 'maximized' | 'restored'. */
+    vertBarState?: string;
+    /** Horizontal splitter bar state. */
+    horzBarState?: string;
+    /** Whether to prefer single-slide view in the panel. */
+    preferSingleView?: boolean;
+    /** Restored left region (slide panel width). */
+    restoredLeft?: PptxRestoredRegion;
+    /** Restored top region (notes panel height). */
+    restoredTop?: PptxRestoredRegion;
+}
+/**
+ * Common slide view properties shared by slideViewPr, outlineViewPr,
+ * notesTextViewPr, and notesViewPr.
+ */
+interface PptxCommonSlideViewProperties {
+    /** Whether snap-to-grid is enabled. */
+    snapToGrid?: boolean;
+    /** Whether snap-to-objects is enabled. */
+    snapToObjects?: boolean;
+    /** Whether drawing guides are shown. */
+    showGuides?: boolean;
+    /** View origin (scroll position). */
+    origin?: PptxViewOrigin;
+    /** View scale. */
+    scale?: PptxViewScale;
+}
+/**
+ * Full view properties from `ppt/viewProps.xml`.
+ */
+interface PptxViewProperties {
+    /** Last used view type (`p:viewPr/@lastView`). */
+    lastView?: string;
+    /** Whether comments are shown (`p:viewPr/@showComments`). */
+    showComments?: boolean;
+    /** Normal view properties (splitter positions). */
+    normalViewPr?: PptxNormalViewProperties;
+    /** Slide view properties. */
+    slideViewPr?: PptxCommonSlideViewProperties;
+    /** Outline view properties. */
+    outlineViewPr?: PptxCommonSlideViewProperties;
+    /** Notes text view properties. */
+    notesTextViewPr?: PptxCommonSlideViewProperties;
+    /** Sorter view scale. */
+    sorterViewPr?: {
+        scale?: PptxViewScale;
+    };
+    /** Notes view properties. */
+    notesViewPr?: PptxCommonSlideViewProperties;
+    /** Raw XML preserved for lossless round-trip of unparsed attributes. */
+    rawXml?: Record<string, unknown>;
+}
+
+/**
+ * Top-level presentation types: slides, canvas dimensions, export options,
+ * and the root {@link PptxData} structure returned by `PptxHandlerCore.load()`.
+ *
+ * @module pptx-types/presentation
+ */
+
+/**
+ * A customer data reference from `p:custDataLst / p:custData`.
+ *
+ * Enterprise add-ins and integrations store custom data parts in the
+ * package and reference them via relationship IDs in the slide or
+ * presentation XML.
+ *
+ * @see ECMA-376 Part 1, §19.2.1.3 (custDataLst), §19.3.1.6 (custData)
+ */
+interface PptxCustomerData {
+    /** Resolved part path inside the package (e.g. `ppt/customerData/item1.xml`). */
+    id: string;
+    /** Relationship ID referencing the custom data part. */
+    relId: string;
+    /** Raw string content of the custom data part (if resolvable). */
+    data?: string;
+}
+/**
+ * An ActiveX control reference from `p:controls / p:control`.
+ *
+ * ActiveX form controls (buttons, text boxes, check boxes, combo boxes, etc.)
+ * are embedded via OLE parts and referenced by relationship ID in the slide XML.
+ *
+ * @see ECMA-376 Part 1, §19.3.1.3 (controls), §19.3.1.2 (control)
+ */
+interface PptxActiveXControl {
+    /** Relationship ID referencing the ActiveX binary part. */
+    relId: string;
+    /** Control name from @name attribute. */
+    name?: string;
+    /** Shape ID this control is linked to (from @spid). */
+    shapeId?: string;
+    /** Raw XML for round-trip preservation. */
+    rawXml?: XmlObject;
+}
+/**
+ * A single slide in a parsed PPTX presentation.
+ *
+ * Contains the element tree, background settings, notes, comments,
+ * transition / animation data, and metadata like layout path and section.
+ *
+ * @example
+ * ```ts
+ * const slide: PptxSlide = {
+ *   id: "slide1",
+ *   rId: "rId2",
+ *   slideNumber: 1,
+ *   elements: [titleTextBox, subtitleTextBox],
+ *   backgroundColor: "#FFFFFF",
+ *   notes: "Remember to mention quarterly goals.",
+ * };
+ * // => satisfies PptxSlide
+ * ```
+ */
+interface PptxSlide {
+    id: string;
+    rId: string;
+    sourceSlideId?: string;
+    layoutPath?: string;
+    layoutName?: string;
+    slideNumber: number;
+    hidden?: boolean;
+    sectionName?: string;
+    sectionId?: string;
+    elements: PptxElement[];
+    backgroundColor?: string;
+    backgroundImage?: string;
+    backgroundGradient?: string;
+    transition?: PptxSlideTransition;
+    animations?: PptxElementAnimation[];
+    /** Native OOXML animation data parsed from `p:timing`. */
+    nativeAnimations?: PptxNativeAnimation[];
+    /** Preserved raw `p:timing` XML for lossless round-trip of native animations. */
+    rawTiming?: XmlObject;
+    notes?: string;
+    /** Rich text segments for the slide notes (preserves formatting). */
+    notesSegments?: TextSegment[];
+    comments?: PptxComment[];
+    warnings?: PptxCompatibilityWarning[];
+    rawXml?: XmlObject;
+    /** Per-slide colour map override parsed from `p:clrMapOvr`. */
+    clrMapOverride?: Record<string, string>;
+    /** Whether background animations should play (`p:bg/@showAnimation`). */
+    backgroundShowAnimation?: boolean;
+    /** Whether master slide shapes should be shown on this slide (`p:sld/@showMasterSp`). */
+    showMasterShapes?: boolean;
+    /** Drawing guides parsed from slide extension list. */
+    guides?: PptxDrawingGuide[];
+    /** When explicitly `false`, the slide is unmodified and save can skip re-serialization. */
+    isDirty?: boolean;
+    /** Customer data references from `p:custDataLst` on this slide. */
+    customerData?: PptxCustomerData[];
+    /** ActiveX control references from `p:controls` on this slide. */
+    activeXControls?: PptxActiveXControl[];
+}
+/**
+ * A slide layout available in the loaded presentation.
+ *
+ * Each entry maps to a `<p:sldLayout>` inside `ppt/slideLayouts/`.
+ *
+ * @example
+ * ```ts
+ * const layout: PptxLayoutOption = {
+ *   path: "ppt/slideLayouts/slideLayout2.xml",
+ *   name: "Title and Content",
+ * };
+ * // => satisfies PptxLayoutOption
+ * ```
+ */
+interface PptxLayoutOption {
+    path: string;
+    name: string;
+    /** Standard layout type from `p:sldLayout/@type` (e.g. "obj", "twoColTx", "blank"). */
+    type?: string;
+}
+/**
+ * Header, footer, date-time, and slide-number placeholders.
+ *
+ * Parsed from `ppt/presProps.xml` and individual slide layouts.
+ *
+ * @example
+ * ```ts
+ * const hf: PptxHeaderFooter = {
+ *   hasFooter: true,
+ *   footerText: "Confidential",
+ *   hasSlideNumber: true,
+ * };
+ * // => satisfies PptxHeaderFooter
+ * ```
+ */
+interface PptxHeaderFooter {
+    hasHeader?: boolean;
+    headerText?: string;
+    hasFooter?: boolean;
+    footerText?: string;
+    hasDateTime?: boolean;
+    dateTimeText?: string;
+    dateTimeAuto?: boolean;
+    /** OOXML date format pattern (e.g. "M/d/yyyy", "dddd, MMMM dd, yyyy"). */
+    dateFormat?: string;
+    hasSlideNumber?: boolean;
+}
+/**
+ * Presentation-level properties parsed from `presentationPr.xml`.
+ *
+ * Controls slideshow behaviour, print settings, custom colours, and grid.
+ *
+ * @example
+ * ```ts
+ * const props: PptxPresentationProperties = {
+ *   showType: "presented",
+ *   loopContinuously: false,
+ *   advanceMode: "useTimings",
+ * };
+ * // => satisfies PptxPresentationProperties
+ * ```
+ */
+interface PptxPresentationProperties {
+    /** Show type: presented, browsed, kiosk. */
+    showType?: 'presented' | 'browsed' | 'kiosk';
+    /** Whether to loop the slideshow continuously. */
+    loopContinuously?: boolean;
+    /** Whether to show without narration. */
+    showWithNarration?: boolean;
+    /** Whether to show without animation. */
+    showWithAnimation?: boolean;
+    /** Advance slides mode: manual click or use stored timings. */
+    advanceMode?: 'manual' | 'useTimings';
+    /** Show slides: 'all', a custom show id, or a from-to range. */
+    showSlidesMode?: 'all' | 'customShow' | 'range';
+    /** Custom show id to use when showSlidesMode is 'customShow'. */
+    showSlidesCustomShowId?: string;
+    /** Slide range start (1-based) when showSlidesMode is 'range'. */
+    showSlidesFrom?: number;
+    /** Slide range end (1-based) when showSlidesMode is 'range'. */
+    showSlidesTo?: number;
+    /** Whether to show subtitles/captions during presentation mode. */
+    showSubtitles?: boolean;
+    /** Print settings: slides per page. */
+    printSlidesPerPage?: number;
+    /** Print settings: frame slides. */
+    printFrameSlides?: boolean;
+    /** Print settings: colour mode (from `p:prnPr/@clrMode`). */
+    printColorMode?: 'clr' | 'gray' | 'bw';
+    /** Most-recently-used colours from the presentation palette. */
+    mruColors?: string[];
+    /** Grid spacing in EMUs (cx, cy). Default is 914400 / 8 = 114300. */
+    gridSpacing?: {
+        cx: number;
+        cy: number;
+    };
+    /** Pen colour for presentation mode annotations (from `p:showPr/p:penClr`). */
+    penColor?: string;
+    /** Kiosk auto-restart interval in milliseconds (from `p:kiosk/@restart`). Only meaningful when showType is "kiosk". */
+    kioskRestartTime?: number;
+}
+/**
+ * A named custom slide show (`p:custShowLst / p:custShow`).
+ *
+ * Custom shows define ordered subsets of slides that can be presented
+ * independently of the full deck.
+ *
+ * @example
+ * ```ts
+ * const show: PptxCustomShow = {
+ *   name: "Executive Summary",
+ *   id: "0",
+ *   slideRIds: ["rId2", "rId5", "rId8"],
+ * };
+ * // => satisfies PptxCustomShow
+ * ```
+ */
+interface PptxCustomShow {
+    /** Custom show name. */
+    name: string;
+    /** Custom show id. */
+    id: string;
+    /** Ordered list of slide relationship IDs included in this custom show. */
+    slideRIds: string[];
+}
+/**
+ * An ordered section in the presentation (from `p:sectionLst` / `p14:sectionLst`).
+ *
+ * Sections group consecutive slides under a named heading (visible
+ * in the PowerPoint slide sorter).
+ *
+ * @example
+ * ```ts
+ * const section: PptxSection = {
+ *   id: "sec_1",
+ *   name: "Introduction",
+ *   slideIds: ["256", "257"],
+ * };
+ * // => satisfies PptxSection
+ * ```
+ */
+interface PptxSection {
+    /** Section unique identifier (GUID or synthetic). */
+    id: string;
+    /** Human-readable section name. */
+    name: string;
+    /** Ordered list of numeric slide IDs that belong to this section. */
+    slideIds: string[];
+    /** Whether the section is collapsed in the slide sorter (from p15:sectionPr). */
+    collapsed?: boolean;
+    /** Section highlight color hex (from p15:sectionPr/@clr). */
+    color?: string;
+}
+/**
+ * Write-protection hash data parsed from `p:modifyVerifier` in `presentation.xml`.
+ *
+ * When present, the presentation is marked as "read-only recommended" or
+ * write-protected with a password hash.  The hash parameters follow the
+ * ECMA-376 Part 1, section 19.2.1.22 specification.
+ *
+ * @example
+ * ```ts
+ * const verifier: PptxModifyVerifier = {
+ *   algorithmName: "SHA-512",
+ *   hashData: "base64EncodedHash==",
+ *   saltData: "base64EncodedSalt==",
+ *   spinValue: 100000,
+ * };
+ * // => satisfies PptxModifyVerifier
+ * ```
+ */
+interface PptxModifyVerifier {
+    /** Hash algorithm name (e.g. "SHA-512", "SHA-1"). */
+    algorithmName?: string;
+    /** Base64-encoded hash value. */
+    hashData?: string;
+    /** Base64-encoded salt value. */
+    saltData?: string;
+    /** Number of hash iterations (spin count). */
+    spinValue?: number;
+    /** Legacy algorithm ID extension. */
+    algIdExt?: string;
+    /** Legacy algorithm ID. */
+    cryptAlgorithmSid?: number;
+    /** Cryptographic algorithm type (e.g. "typeAny"). */
+    cryptAlgorithmType?: string;
+    /** Cryptographic provider name. */
+    cryptProvider?: string;
+    /** Cryptographic provider type (e.g. "providerTypeRsaFull"). */
+    cryptProviderType?: string;
+    /** Cryptographic algorithm class (e.g. "hash"). */
+    cryptAlgorithmClass?: string;
+}
+/**
+ * Photo album metadata from `p:photoAlbum` in `presentation.xml`.
+ *
+ * Stores settings for presentations created via Insert > Photo Album.
+ *
+ * @see ECMA-376 Part 1, §19.2.1.27
+ */
+interface PptxPhotoAlbum {
+    /** Whether photos are displayed in black-and-white. */
+    bw?: boolean;
+    /** Whether captions are shown below each photo. */
+    showCaptions?: boolean;
+    /** Photo album layout (e.g. "1pic", "2pic", "4pic", "fitToSlide"). */
+    layout?: string;
+    /** Frame style applied to each photo (e.g. "frameStyle1"). */
+    frame?: string;
+}
+/**
+ * East Asian line-break (kinsoku) settings from `p:kinsoku` in `presentation.xml`.
+ *
+ * Defines forbidden start/end characters for a given language so that
+ * line-breaking follows East Asian typographic rules.
+ *
+ * @see ECMA-376 Part 1, §19.2.1.17
+ */
+interface PptxKinsoku {
+    /** Language code (e.g. "ja-JP", "zh-CN"). */
+    lang?: string;
+    /** Characters that cannot begin a line. */
+    invalStChars?: string;
+    /** Characters that cannot end a line. */
+    invalEndChars?: string;
+}
+/**
+ * Root data structure returned by {@link PptxHandlerCore.load}.
+ *
+ * Contains every slide, canvas dimensions, theme data, layout options,
+ * metadata, and optional features (custom shows, sections, macros,
+ * digital signatures, embedded fonts).
+ *
+ * @example
+ * ```ts
+ * const data: PptxData = await handler.load(buffer);
+ * console.log(`${data.slides.length} slides, ${data.width}×${data.height}`);
+ * // => e.g. "24 slides, 960×540"
+ * ```
+ */
+interface PptxData {
+    slides: PptxSlide[];
+    width: number;
+    height: number;
+    /** Slide width in EMU (for save round-trip). */
+    widthEmu?: number;
+    /** Slide height in EMU (for save round-trip). */
+    heightEmu?: number;
+    /** Slide size type from `p:sldSz/@type` (e.g. "screen4x3", "screen16x9", "custom"). */
+    slideSizeType?: string;
+    /** Notes page width in EMU (from `p:notesSz`). */
+    notesWidthEmu?: number;
+    /** Notes page height in EMU (from `p:notesSz`). */
+    notesHeightEmu?: number;
+    layoutOptions?: PptxLayoutOption[];
+    headerFooter?: PptxHeaderFooter;
+    /** Presentation-level properties parsed from `presentationPr.xml`. */
+    presentationProperties?: PptxPresentationProperties;
+    /** Named custom slide shows from `p:custShowLst`. */
+    customShows?: PptxCustomShow[];
+    /** Ordered presentation sections from `p:sectionLst` / `p14:sectionLst`. */
+    sections?: PptxSection[];
+    warnings?: PptxCompatibilityWarning[];
+    /** Map of theme colour scheme keys to resolved hex values. */
+    themeColorMap?: Record<string, string>;
+    /** Full parsed theme object with colours, fonts, and name. */
+    theme?: PptxTheme;
+    /** Available theme parts discovered in `ppt/theme/`. */
+    themeOptions?: PptxThemeOption[];
+    /** Parsed table style definitions from `ppt/tableStyles.xml`. */
+    tableStyleMap?: ParsedTableStyleMap;
+    /** Whether the presentation is password-protected. */
+    isPasswordProtected?: boolean;
+    /** Embedded font data (name + binary data URL) extracted from the presentation. */
+    embeddedFonts?: PptxEmbeddedFont[];
+    /** Most-recently-used colour list from presentation properties. */
+    mruColors?: string[];
+    /** Parsed notes master data if present in the PPTX. */
+    notesMaster?: PptxNotesMaster;
+    /** Parsed handout master data if present in the PPTX. */
+    handoutMaster?: PptxHandoutMaster;
+    /** Structured slide master data for each master in the presentation. */
+    slideMasters?: PptxSlideMaster[];
+    /** Parsed tag collections attached to the presentation or slides. */
+    tags?: PptxTagCollection[];
+    /** Custom document properties from `docProps/custom.xml`. */
+    customProperties?: PptxCustomProperty[];
+    /** Core document properties from `docProps/core.xml`. */
+    coreProperties?: PptxCoreProperties;
+    /** Extended (application) properties from `docProps/app.xml`. */
+    appProperties?: PptxAppProperties;
+    /** Whether the presentation contains VBA macros (is a .pptm file). */
+    hasMacros?: boolean;
+    /** Whether the presentation contains digital signatures (`_xmlsignatures/` parts). */
+    hasDigitalSignatures?: boolean;
+    /** Number of digital signatures found. */
+    digitalSignatureCount?: number;
+    /** Presentation-level drawing guides from `p:extLst`. */
+    presentationGuides?: PptxDrawingGuide[];
+    /** View properties from `ppt/viewProps.xml`. */
+    viewProperties?: PptxViewProperties;
+    /** Write-protection verifier from `p:modifyVerifier` in `presentation.xml`. */
+    modifyVerifier?: PptxModifyVerifier;
+    /** Photo album metadata from `p:photoAlbum` in `presentation.xml`. */
+    photoAlbum?: PptxPhotoAlbum;
+    /** East Asian line-break settings from `p:kinsoku` in `presentation.xml`. */
+    kinsoku?: PptxKinsoku;
+    /** Custom XML data parts from `customXml/` in the OPC package. */
+    customXmlParts?: PptxCustomXmlPart[];
+    /** Customer data references from `p:custDataLst` in `presentation.xml`. */
+    customerData?: PptxCustomerData[];
+    /** Thumbnail image binary data from `docProps/thumbnail.{jpeg,png}`. */
+    thumbnailData?: Uint8Array;
+    /** Comment authors parsed from `ppt/commentAuthors.xml` for round-trip preservation. */
+    commentAuthors?: PptxCommentAuthor[];
+    /**
+     * OOXML conformance class of the loaded file.
+     * - `'strict'` -- ISO/IEC 29500 Strict (uses `purl.oclc.org` namespace URIs)
+     * - `'transitional'` -- ECMA-376 Transitional (uses `schemas.openxmlformats.org` URIs)
+     *
+     * When saving, if the save option `conformance` is `'preserve'` (default),
+     * the file will be saved using the same conformance class as the original.
+     */
+    conformance?: 'strict' | 'transitional';
+}
+/**
+ * Target format for slide export.
+ *
+ * @see {@link PptxExportOptions}
+ */
+type PptxExportFormat = 'pdf' | 'png' | 'svg';
+/**
+ * Options controlling slide export to raster or vector formats.
+ *
+ * @example
+ * ```ts
+ * const opts: PptxExportOptions = {
+ *   format: "png",
+ *   slideIndices: [0, 2, 4],
+ *   dpi: 300,
+ * };
+ * // => satisfies PptxExportOptions
+ * ```
+ */
+interface PptxExportOptions {
+    /** Target format. */
+    format: PptxExportFormat;
+    /** Slide indices to export (0-based). If omitted, all slides are exported. */
+    slideIndices?: number[];
+    /** Output width in pixels (for PNG). Height is derived from aspect ratio. */
+    width?: number;
+    /** DPI for raster export (default 150). */
+    dpi?: number;
+    /** Whether to include hidden slides. */
+    includeHidden?: boolean;
+}
+/**
+ * Embedded font data extracted from a PPTX file.
+ *
+ * Used to register `@font-face` rules so the renderer can display
+ * the correct typeface even when the system font is missing.
+ *
+ * @example
+ * ```ts
+ * const font: PptxEmbeddedFont = {
+ *   name: "CustomSans",
+ *   dataUrl: "data:font/truetype;base64,AAEAK...",
+ *   format: "truetype",
+ * };
+ * // => satisfies PptxEmbeddedFont
+ * ```
+ */
+/**
+ * A single Custom XML Data Part stored in `customXml/` within the OPC package.
+ *
+ * These parts are used by add-ins, data-binding, and enterprise templates
+ * to store structured data alongside the presentation.
+ *
+ * @see ECMA-376 Part 1, §15.2.5
+ */
+interface PptxCustomXmlPart {
+    /** Item number (e.g. "1" for `customXml/item1.xml`). */
+    id: string;
+    /** Raw XML string content of the custom XML item. */
+    data: string;
+    /** Schema target namespace URI from `itemProps` (ds:schemaRef/@ds:uri). */
+    schemaUri?: string;
+    /** Raw XML string content of the associated `itemProps` file. */
+    properties?: string;
+    /** Raw XML string content of the OPC relationship file (`customXml/_rels/item{id}.xml.rels`). */
+    rels?: string;
+}
+interface PptxEmbeddedFont {
+    name: string;
+    dataUrl: string;
+    bold?: boolean;
+    italic?: boolean;
+    /** CSS font format hint (e.g. "truetype", "opentype"). */
+    format?: 'truetype' | 'opentype' | 'woff' | 'woff2';
+    /**
+     * Deobfuscated (clear-text) font binary data preserved from load
+     * for round-trip re-embedding on save. When present, the save
+     * pipeline will re-obfuscate and write this data back into the ZIP.
+     */
+    rawFontData?: Uint8Array;
+    /**
+     * Original ZIP path of the font part (e.g. `ppt/fonts/{GUID}.fntdata`).
+     * Preserved from load for round-trip.
+     */
+    partPath?: string;
+    /**
+     * The GUID used for obfuscation, either from the `fontKey` attribute
+     * or extracted from the part path. Preserved from load for round-trip.
+     */
+    fontGuid?: string;
+}
+
+export { type OleObjectType as $, type PptxTagCollection as A, type PptxPhotoAlbum as B, type ConnectorPptxElement as C, type PptxKinsoku as D, type PptxModifyVerifier as E, type PptxViewProperties as F, type PptxEmbeddedFont as G, type PptxExportOptions as H, type InkPptxElement as I, type PptxThemeFormatScheme as J, type TextSegment as K, type PptxComment as L, type PptxSlideTransition as M, type PptxElementAnimation as N, type PptxNativeAnimation as O, type PptxElement as P, type PptxCustomerData as Q, type PptxActiveXControl as R, type ShapePptxElement as S, type TextPptxElement as T, type AnimationCondition as U, type ShapeStyle as V, type TextStyle as W, type XmlObject as X, type ElementAction as Y, type ZoomPptxElement as Z, type PptxAction as _, type PptxElementWithShapeStyle as a, type ParsedTableStyleEntry as a$, type PptxSmartArtNode as a0, type SmartArtLayoutType as a1, type PptxSmartArtDrawingShape as a2, type PptxChartDataTable as a3, type PptxChartLineStyle as a4, type PptxChartErrBars as a5, type PptxChartTrendline as a6, type PptxChartMarker as a7, type PptxChartDataLabel as a8, type PptxChartDataPoint as a9, type PptxShapeLocks as aA, type PptxThemeFillStyle as aB, type PptxThemeLineStyle as aC, type PptxThemeEffectStyle as aD, type PptxSmartArtChrome as aE, type PptxSmartArtColorTransform as aF, type PptxSmartArtQuickStyle as aG, type PptxExternalData as aH, type CustomGeometryPoint as aI, type CustomGeometryPath as aJ, type ChartPptxElement as aK, type ImagePptxElement as aL, type TablePptxElement as aM, type ActionButtonPreset as aN, type AnimationConditionEvent as aO, type BevelPresetType as aP, type ConnectorConnectionPoint as aQ, type ContentPartInkStroke as aR, type ContentPartPptxElement as aS, type CustomGeometrySegment as aT, type ElementActionType as aU, type MasterViewTab as aV, type MaterialPresetType as aW, type MediaCaptionTrack as aX, type MediaMetadata as aY, type Model3DPptxElement as aZ, type OlePptxElement as a_, type PptxChartShapeProps as aa, type PptxChart3DSurface as ab, type PptxChartAxisFormatting as ac, type PptxEmbeddedWorkbookData as ad, type PptxDrawingGuide as ae, type PptxCustomXmlPart as af, type PptxCommentAuthor as ag, type MediaPptxElement as ah, type PptxTableData as ai, type PptxTheme as aj, type ParsedTableStyleMap as ak, type PptxSlideMaster as al, type PptxThemeOption as am, type PlaceholderDefaults as an, type ParsedTableStyleFill as ao, type ParsedTableStyleText as ap, type PptxImageEffects as aq, type MediaBookmark as ar, type PptxChartStyle as as, type GroupPptxElement as at, type PlaceholderTextLevelStyle as au, type PptxTableCellStyle as av, type PptxChartSeries as aw, type SmartArtPptxElement as ax, type GeometryAdjustmentHandle as ay, type BulletInfo as az, type PptxElementWithText as b, type PicturePptxElement as b0, type Pptx3DScene as b1, type Pptx3DShape as b2, type PptxAfterAnimationAction as b3, type PptxAnimationDirection as b4, type PptxAnimationIterate as b5, type PptxAnimationRepeatMode as b6, type PptxAnimationSequence as b7, type PptxAnimationTimingCurve as b8, type PptxChartAxisNumFmt as b9, type PptxTextAnimationTarget as bA, type PptxTextBuildType as bB, type PptxTextProperties as bC, type PptxTextStyleLevels as bD, type PptxTextWarpPreset as bE, type PptxThemeFontGroup as bF, type PptxTransitionDirection4 as bG, type PptxTransitionDirection8 as bH, type PptxViewOrigin as bI, type PptxViewScale as bJ, type ShadowEffect as bK, type SmartArtColorScheme as bL, type SmartArtLayout as bM, type SmartArtStyle as bN, THEME_COLOR_SCHEME_KEYS as bO, TRANSITION_VALID_DIRECTIONS as bP, type Text3DStyle as bQ, type UnderlineStyle as bR, type UnknownPptxElement as bS, type PptxChartErrBarDir as ba, type PptxChartErrBarType as bb, type PptxChartErrValType as bc, type PptxChartMarkerSymbol as bd, type PptxChartTrendlineType as be, type PptxColorAnimation as bf, type PptxCommonSlideViewProperties as bg, type PptxCropShape as bh, type PptxCustomPathProperties as bi, type PptxElementBase as bj, type PptxElementType as bk, type PptxExportFormat as bl, type PptxImageProperties as bm, type PptxMasterTextStyles as bn, type PptxMediaType as bo, type PptxNormalViewProperties as bp, type PptxRestoredRegion as bq, type PptxShapeProperties as br, type PptxSlideLayout as bs, type PptxSmartArtConnection as bt, type PptxSplitDirection as bu, type PptxSplitOrientation as bv, type PptxStripDirection as bw, type PptxTableCell as bx, type PptxTableRow as by, type PptxTag as bz, type PptxImageLikeElement as c, type PptxThemeColorScheme as d, type PptxThemeFontScheme as e, type PptxAnimationPreset as f, type PptxAnimationTrigger as g, type StrokeDashType as h, type ConnectorArrowType as i, type PptxTransitionType as j, type PptxChartType as k, type PptxSlide as l, type PptxData as m, type PptxCompatibilityWarning as n, type PptxLayoutOption as o, type PptxChartData as p, type PptxSmartArtData as q, type PptxHeaderFooter as r, type PptxPresentationProperties as s, type PptxCustomShow as t, type PptxSection as u, type PptxCoreProperties as v, type PptxAppProperties as w, type PptxCustomProperty as x, type PptxNotesMaster as y, type PptxHandoutMaster as z };