pptx-svelte-viewer 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -125,173 +125,4586 @@ declare const vermilionLightTheme: ViewerTheme;
 /** Dark vermilion theme, ready for the viewer's `theme` prop. */
 declare const vermilionDarkTheme: ViewerTheme;
 
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
 /**
  * Strongly-typed parsed XML node from fast-xml-parser.
  *
- * The parser is configured with `attributeNamePrefix: '@_'`,
- * `parseAttributeValue: false`, and `parseTagValue: false`, so attribute and
- * text values are always strings at runtime. This type encodes that:
+ * The parser is configured with `attributeNamePrefix: '@_'`,
+ * `parseAttributeValue: false`, and `parseTagValue: false`, so attribute and
+ * text values are always strings at runtime. This type encodes that:
+ *
+ * - **Attributes** — keys matching `` `@_${string}` `` return
+ *   `string | undefined` directly.
+ * - **Text content** — `#text` returns `string | undefined`.
+ * - **Child elements** — any other string key returns
+ *   `XmlObject | XmlObject[] | string | undefined`. The union reflects that
+ *   fast-xml-parser may emit an object (single child), an array (repeated
+ *   children), or a bare string (text-only element collapsed by the parser).
+ *
+ * For traversal, prefer the helpers in {@link ./../utils/xml-access} —
+ * `xmlChild` / `xmlChildren` / `xmlAttr` / `xmlText` / `xmlPath` — which
+ * narrow the union and normalize the single-vs-array duality. Direct
+ * indexing works for attributes (typed as string) but chained child access
+ * (`obj['p:spPr']?.['a:xfrm']`) requires the helpers or a narrowing cast
+ * because TypeScript cannot index into the `XmlObject[] | string` part of
+ * the union.
+ */
+interface XmlObject {
+    /** Attributes (`@_`-prefixed keys) are always strings at runtime. */
+    [attr: `@_${string}`]: string | undefined;
+    /** Element text content surfaces under `#text` when present. */
+    '#text'?: string;
+    /**
+     * Child elements keyed by their (namespaced) tag name. fast-xml-parser
+     * emits a single object for unique elements, an array for repeated ones,
+     * and a bare string for elements collapsed to their text content. Use
+     * the helpers in `utils/xml-access` to narrow this union.
+     */
+    [child: string]: XmlObject | XmlObject[] | string | undefined;
+}
+/**
+ * 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;
+}
+
+/**
+ * Geometry types: adjustment handles, custom geometry points, segments,
+ * paths, and custom path properties.
+ *
+ * @module pptx-types/geometry
+ */
+/**
+ * Defines an adjustment handle position for a shape geometry.
+ *
+ * Adjustment handles allow users to interactively reshape preset shapes
+ * (e.g. rounding a rectangle corner or adjusting arrow head width).
+ *
+ * @example
+ * ```ts
+ * const handle: GeometryAdjustmentHandle = {
+ *   guideName: "adj",
+ *   xFraction: 0.25,
+ *   minValue: 0,
+ *   maxValue: 50000,
+ * };
+ * // => satisfies GeometryAdjustmentHandle
+ * ```
+ */
+interface GeometryAdjustmentHandle {
+    /** Name of the adjustment guide this handle controls (e.g. "adj", "adj1"). */
+    guideName: string;
+    /** X position as a fraction of shape width (0..1), or undefined if the handle only moves vertically. */
+    xFraction?: number;
+    /** Y position as a fraction of shape height (0..1), or undefined if the handle only moves horizontally. */
+    yFraction?: number;
+    /** Minimum allowed value for the adjustment guide. */
+    minValue?: number;
+    /** Maximum allowed value for the adjustment guide. */
+    maxValue?: number;
+}
+/**
+ * A single point in a custom geometry path.
+ *
+ * @example
+ * ```ts
+ * const pt: CustomGeometryPoint = { x: 100, y: 200 };
+ * // => satisfies CustomGeometryPoint
+ * ```
+ */
+interface CustomGeometryPoint {
+    x: number;
+    y: number;
+}
+/**
+ * A segment within a custom geometry path.
+ *
+ * Discriminated union over `type` — can be a moveTo, lineTo,
+ * cubic Bézier, quadratic Bézier, or close command.
+ *
+ * @example
+ * ```ts
+ * const segments: CustomGeometrySegment[] = [
+ *   { type: "moveTo", pt: { x: 0, y: 0 } },
+ *   { type: "lineTo", pt: { x: 100, y: 0 } },
+ *   { type: "lineTo", pt: { x: 100, y: 100 } },
+ *   { type: "close" },
+ * ];
+ * // => satisfies CustomGeometrySegment[]
+ * ```
+ */
+type CustomGeometrySegment = {
+    type: 'moveTo';
+    pt: CustomGeometryPoint;
+} | {
+    type: 'lineTo';
+    pt: CustomGeometryPoint;
+} | {
+    type: 'cubicBezTo';
+    pts: [CustomGeometryPoint, CustomGeometryPoint, CustomGeometryPoint];
+} | {
+    type: 'quadBezTo';
+    pts: [CustomGeometryPoint, CustomGeometryPoint];
+} | {
+    type: 'arcTo';
+    /** Horizontal radius of the ellipse. */
+    wR: number;
+    /** Vertical radius of the ellipse. */
+    hR: number;
+    /** Start angle in 60000ths of a degree. */
+    stAng: number;
+    /** Sweep angle in 60000ths of a degree. */
+    swAng: number;
+} | {
+    type: 'close';
+};
+/**
+ * A single sub-path in a custom geometry definition (maps to one `a:path`).
+ *
+ * @example
+ * ```ts
+ * const path: CustomGeometryPath = {
+ *   width: 100,
+ *   height: 100,
+ *   segments: [
+ *     { type: "moveTo", pt: { x: 0, y: 0 } },
+ *     { type: "lineTo", pt: { x: 100, y: 100 } },
+ *   ],
+ * };
+ * // => satisfies CustomGeometryPath
+ * ```
+ */
+interface CustomGeometryPath {
+    /** Coordinate-space width for this sub-path. */
+    width: number;
+    /** Coordinate-space height for this sub-path. */
+    height: number;
+    /** Ordered list of drawing segments. */
+    segments: CustomGeometrySegment[];
+    /** Path fill mode (`a:path/@fill`): norm, lighten, lightenLess, darken, darkenLess, none. */
+    fillMode?: 'norm' | 'lighten' | 'lightenLess' | 'darken' | 'darkenLess' | 'none';
+    /** Whether the path is stroked (`a:path/@stroke`). */
+    stroke?: boolean;
+    /** 3D extrusion compatibility (`a:path/@extrusionOk`). */
+    extrusionOk?: boolean;
+}
+/**
+ * Auxiliary raw XML preserved from `a:custGeom` for round-trip serialization.
+ * These are stored opaquely so adjustment guides, handles, connection sites,
+ * and the text rectangle are not lost when a custGeom is edited and saved.
+ */
+interface CustomGeometryRawData {
+    /** Raw `a:gdLst` XML content (guide list). */
+    gdLstXml?: unknown;
+    /** Raw `a:ahLst` XML content (adjustment handles). */
+    ahLstXml?: unknown;
+    /** Raw `a:cxnLst` XML content (connection sites). */
+    cxnLstXml?: unknown;
+    /** Raw `a:rect` XML content (text rectangle). */
+    rectXml?: unknown;
+}
+/**
+ * XY-style adjustment handle (`a:ahXY`) on a custom geometry.
+ *
+ * Allows interactive editing of one or two guide values constrained to a
+ * rectangular range. Coordinates are formula references (e.g. `"adj1"`,
+ * `"w/2"`, `"0"`) preserved verbatim so they can re-emit unchanged.
+ *
+ * @example
+ * ```ts
+ * const handle: AdjustHandleXY = {
+ *   gdRefX: "adj1",
+ *   minX: "0",
+ *   maxX: "w",
+ *   posX: "adj1",
+ *   posY: "h/2",
+ * };
+ * // => satisfies AdjustHandleXY
+ * ```
+ */
+interface AdjustHandleXY {
+    /** Guide reference for the X axis (`@_gdRefX`). */
+    gdRefX?: string;
+    /** Guide reference for the Y axis (`@_gdRefY`). */
+    gdRefY?: string;
+    /** Minimum X value, as a formula reference (`@_minX`). */
+    minX?: string;
+    /** Maximum X value (`@_maxX`). */
+    maxX?: string;
+    /** Minimum Y value (`@_minY`). */
+    minY?: string;
+    /** Maximum Y value (`@_maxY`). */
+    maxY?: string;
+    /** Handle position X (formula or literal) from `a:pos/@_x`. */
+    posX?: string;
+    /** Handle position Y from `a:pos/@_y`. */
+    posY?: string;
+}
+/**
+ * Polar-style adjustment handle (`a:ahPolar`) on a custom geometry.
+ *
+ * Drives a guide via radial distance and angle rather than XY coordinates.
+ *
+ * @example
+ * ```ts
+ * const handle: AdjustHandlePolar = {
+ *   gdRefR: "adj1",
+ *   gdRefAng: "adj2",
+ *   posX: "wd2",
+ *   posY: "hd2",
+ * };
+ * // => satisfies AdjustHandlePolar
+ * ```
+ */
+interface AdjustHandlePolar {
+    /** Guide reference for the radial distance (`@_gdRefR`). */
+    gdRefR?: string;
+    /** Guide reference for the angle (`@_gdRefAng`). */
+    gdRefAng?: string;
+    /** Minimum radial value (`@_minR`). */
+    minR?: string;
+    /** Maximum radial value (`@_maxR`). */
+    maxR?: string;
+    /** Minimum angle (`@_minAng`). */
+    minAng?: string;
+    /** Maximum angle (`@_maxAng`). */
+    maxAng?: string;
+    /** Handle position X from `a:pos/@_x`. */
+    posX?: string;
+    /** Handle position Y from `a:pos/@_y`. */
+    posY?: string;
+}
+/**
+ * Connection site (`a:cxn`) on a custom geometry.
+ *
+ * Defines a point on a custom shape that connectors may snap to.
+ *
+ * @example
+ * ```ts
+ * const cxn: ConnectionSite = { ang: "0", posX: "0", posY: "hd2" };
+ * // => satisfies ConnectionSite
+ * ```
+ */
+interface ConnectionSite {
+    /** Approach angle (`@_ang`) — formula or literal degree-1/60000 value. */
+    ang?: string;
+    /** Site position X from `a:pos/@_x`. */
+    posX?: string;
+    /** Site position Y from `a:pos/@_y`. */
+    posY?: string;
+}
+/**
+ * Typed text rectangle (`a:rect`) on a custom geometry.
+ *
+ * Each edge is the formula or literal string preserved from the source XML
+ * (`"l"`, `"t"`, `"r"`, `"b"`, or any guide name / formula).
+ */
+interface CustomGeometryTextRect {
+    /** Left edge formula reference (`@_l`). */
+    l?: string;
+    /** Top edge (`@_t`). */
+    t?: string;
+    /** Right edge (`@_r`). */
+    r?: string;
+    /** Bottom edge (`@_b`). */
+    b?: string;
+}
+/**
+ * Custom (non-preset) geometry path — only on shapes and pictures.
+ *
+ * Contains SVG path data and/or structured custom geometry paths
+ * parsed from `a:custGeom/a:pathLst`.
+ *
+ * @example
+ * ```ts
+ * const custom: PptxCustomPathProperties = {
+ *   pathData: "M 0 0 L 100 0 L 100 100 Z",
+ *   pathWidth: 100,
+ *   pathHeight: 100,
+ * };
+ * // => satisfies PptxCustomPathProperties
+ * ```
+ */
+interface PptxCustomPathProperties {
+    /** SVG path data for custom shapes. */
+    pathData?: string;
+    /** Coordinate-space width for the custom path. */
+    pathWidth?: number;
+    /** Coordinate-space height for the custom path. */
+    pathHeight?: number;
+    /** Structured custom geometry paths for editing (maps to a:custGeom/a:pathLst). */
+    customGeometryPaths?: CustomGeometryPath[];
+    /** Raw a:gdLst/a:ahLst/a:cxnLst/a:rect XML preserved for round-trip serialization. */
+    customGeometryRawData?: CustomGeometryRawData;
+    /**
+     * Typed XY adjustment handles parsed from `a:custGeom/a:ahLst/a:ahXY`.
+     * SDK-built shapes can populate this and the writer will emit `<a:ahXY>` entries
+     * even when no raw XML was preserved.
+     */
+    customGeometryAdjustHandlesXY?: AdjustHandleXY[];
+    /**
+     * Typed polar adjustment handles parsed from `a:custGeom/a:ahLst/a:ahPolar`.
+     */
+    customGeometryAdjustHandlesPolar?: AdjustHandlePolar[];
+    /**
+     * Typed connection sites parsed from `a:custGeom/a:cxnLst/a:cxn`.
+     */
+    customGeometryConnectionSites?: ConnectionSite[];
+    /**
+     * Typed text rectangle parsed from `a:custGeom/a:rect`. When present this is
+     * preferred over {@link customGeometryRawData}'s `rectXml` on save.
+     */
+    customGeometryTextRect?: CustomGeometryTextRect;
+}
+
+/**
+ * 3-D effect properties, text warp (WordArt) presets, and scene/shape bevel
+ * definitions parsed from OOXML `a:sp3d`, `a:scene3d`, and `a:bodyPr/a:prstTxWarp`.
+ *
+ * @module pptx-types/three-d
+ */
+/**
+ * Bevel preset type tokens from OOXML `a:bevelT/@prst` / `a:bevelB/@prst`.
+ *
+ * @example
+ * ```ts
+ * const bevel: BevelPresetType = "circle";
+ * // => "circle" — one of: "circle" | "relaxedInset" | "cross" | "coolSlant" | "angle" | …
+ * ```
+ */
+type BevelPresetType = 'circle' | 'relaxedInset' | 'cross' | 'coolSlant' | 'angle' | 'softRound' | 'convex' | 'slope' | 'divot' | 'riblet' | 'hardEdge' | 'artDeco' | 'none';
+/**
+ * Material preset type tokens from OOXML `a:sp3d/@prstMaterial`.
+ *
+ * @example
+ * ```ts
+ * const mat: MaterialPresetType = "plastic";
+ * // => "plastic" — one of: "matte" | "warmMatte" | "plastic" | "metal" | "dkEdge" | …
+ * ```
+ */
+type MaterialPresetType = 'matte' | 'warmMatte' | 'plastic' | 'metal' | 'dkEdge' | 'softEdge' | 'flat' | 'softmetal' | 'clear' | 'powder' | 'translucentPowder' | 'legacyMatte' | 'legacyPlastic' | 'legacyMetal' | 'legacyWireframe';
+/**
+ * 3D text body extrusion/bevel from `a:bodyPr/a:sp3d`.
+ *
+ * @example
+ * ```ts
+ * const text3d: Text3DStyle = {
+ *   extrusionHeight: 57150,
+ *   presetMaterial: "plastic",
+ *   bevelTopType: "circle",
+ *   bevelTopWidth: 25400,
+ *   bevelTopHeight: 25400,
+ * };
+ * // => satisfies Text3DStyle
+ * ```
+ */
+interface Text3DStyle {
+    /** Extrusion height (depth) in EMU. */
+    extrusionHeight?: number;
+    /** Extrusion colour as hex string. */
+    extrusionColor?: string;
+    /** Preset material, e.g. "matte", "plastic", "metal". */
+    presetMaterial?: MaterialPresetType;
+    /** Top bevel preset type. */
+    bevelTopType?: BevelPresetType;
+    /** Top bevel width in EMU. */
+    bevelTopWidth?: number;
+    /** Top bevel height in EMU. */
+    bevelTopHeight?: number;
+    /** Bottom bevel preset type. */
+    bevelBottomType?: BevelPresetType;
+    /** Bottom bevel width in EMU. */
+    bevelBottomWidth?: number;
+    /** Bottom bevel height in EMU. */
+    bevelBottomHeight?: number;
+}
+/**
+ * 3D scene/camera properties from `a:scene3d`.
+ *
+ * @example
+ * ```ts
+ * const scene: Pptx3DScene = {
+ *   cameraPreset: "perspectiveFront",
+ *   lightRigType: "threePt",
+ *   lightRigDirection: "t",
+ * };
+ * // => satisfies Pptx3DScene
+ * ```
+ */
+interface Pptx3DScene {
+    /** Camera preset type, e.g. "orthographicFront", "perspectiveFront". */
+    cameraPreset?: string;
+    /** Camera field of view in 1/60000 degrees (`a:camera/@fov`). */
+    cameraFieldOfView?: number;
+    /** Camera zoom as an OOXML percentage fraction (`a:camera/@zoom`, 1 = 100%). */
+    cameraZoom?: number;
+    /** Camera rotation around X axis in 1/60000 degrees. */
+    cameraRotX?: number;
+    /** Camera rotation around Y axis in 1/60000 degrees. */
+    cameraRotY?: number;
+    /** Camera rotation around Z axis in 1/60000 degrees. */
+    cameraRotZ?: number;
+    /** Light rig type, e.g. "threePt", "balanced", "harsh". */
+    lightRigType?: string;
+    /** Light rig direction, e.g. "t", "b", "l", "r", "tl". */
+    lightRigDirection?: string;
+    /** Light-rig rotation latitude in 1/60000 degrees. */
+    lightRigRotX?: number;
+    /** Light-rig rotation longitude in 1/60000 degrees. */
+    lightRigRotY?: number;
+    /** Light-rig rotation revolution in 1/60000 degrees. */
+    lightRigRotZ?: number;
+    /** Whether a 3D backdrop plane is present (`a:backdrop`). */
+    hasBackdrop?: boolean;
+    /** Backdrop plane anchor X in EMU. */
+    backdropAnchorX?: number;
+    /** Backdrop plane anchor Y in EMU. */
+    backdropAnchorY?: number;
+    /** Backdrop plane anchor Z in EMU. */
+    backdropAnchorZ?: number;
+    /** Backdrop normal vector X component. */
+    backdropNormalX?: number;
+    /** Backdrop normal vector Y component. */
+    backdropNormalY?: number;
+    /** Backdrop normal vector Z component. */
+    backdropNormalZ?: number;
+    /** Backdrop up vector X component. */
+    backdropUpX?: number;
+    /** Backdrop up vector Y component. */
+    backdropUpY?: number;
+    /** Backdrop up vector Z component. */
+    backdropUpZ?: number;
+}
+/**
+ * 3D shape extrusion/bevel from `a:sp3d`.
+ *
+ * @example
+ * ```ts
+ * const shape3d: Pptx3DShape = {
+ *   extrusionHeight: 76200,
+ *   extrusionColor: "#4F81BD",
+ *   presetMaterial: "metal",
+ *   bevelTopType: "circle",
+ *   bevelTopWidth: 12700,
+ *   bevelTopHeight: 12700,
+ * };
+ * // => satisfies Pptx3DShape
+ * ```
+ */
+interface Pptx3DShape {
+    /** 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;
+
+/**
+ * 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;
+    /**
+     * Raw XML colour-choice node preserved from `a:solidFill` for round-trip
+     * serialisation. Captures `a:schemeClr` / `a:sysClr` / `a:prstClr` /
+     * `a:srgbClr` plus colour transforms (`lumMod`, `lumOff`, `tint`,
+     * `shade`, `satMod`, `alpha`, …). On save we re-emit verbatim when the
+     * resolved {@link fillColor} still matches this node, otherwise we fall
+     * back to canonical `<a:srgbClr>`.
+     */
+    fillColorXml?: XmlObject;
+    fillGradient?: string;
+    /** Original `gradFill` XML retained for unknown-child and extension round-tripping. */
+    fillGradientXml?: XmlObject;
+    fillMode?: 'solid' | 'gradient' | 'pattern' | 'none' | 'image' | 'theme' | 'group';
+    fillPatternPreset?: string;
+    fillPatternBackgroundColor?: string;
+    /** Original `pattFill` XML retained for unknown-child round-tripping. */
+    fillPatternXml?: XmlObject;
+    /** 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;
+    };
+    /** Gradient tile flip mode (`a:gradFill/@flip`).
+     *  `none` = no tiling flip (default), `x|y|xy` = mirror in the named axis. */
+    fillGradientFlip?: 'none' | 'x' | 'y' | 'xy';
+    /** Whether the gradient rotates with the shape (`a:gradFill/@rotWithShape`).
+     *  Defaults to true per the schema; preserved for round-trip when the source
+     *  authored the attribute explicitly. */
+    fillGradientRotWithShape?: boolean;
+    /** Whether the linear gradient is scaled to the shape (`a:lin/@scaled`).
+     *  Defaults to true per the schema; preserved for round-trip. */
+    fillGradientScaled?: boolean;
+    fillOpacity?: number;
+    strokeColor?: string;
+    /**
+     * Raw XML colour-choice node preserved from `a:ln/a:solidFill` for
+     * round-trip serialisation. See {@link fillColorXml} for the rationale.
+     */
+    strokeColorXml?: XmlObject;
+    strokeWidth?: number;
+    strokeOpacity?: number;
+    strokeDash?: StrokeDashType;
+    /** Line join style (`a:ln/@join`): round, bevel, or miter. */
+    lineJoin?: 'round' | 'bevel' | 'miter';
+    /** Miter limit (`a:miter/@lim`) in EMU-percent units (default 800000 = 8.0). Only meaningful when lineJoin is 'miter'. */
+    miterLimit?: number;
+    /** 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';
+    /** Pen line alignment (`a:ln/@algn`): `ctr` (centre, default) or `in` (inside). */
+    lineAlignment?: 'ctr' | 'in';
+    shadowColor?: string;
+    /** Preserved source `a:effectLst`, including unknown effects and extensions. */
+    effectListXml?: XmlObject;
+    /** Original outer-shadow node used for lossless surgical updates. */
+    outerShadowXml?: XmlObject;
+    /** Resolved source shadow colour used to detect colour edits. */
+    outerShadowOriginalColor?: string;
+    /** Source shadow opacity used to detect alpha edits. */
+    outerShadowOriginalOpacity?: number;
+    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;
+    /** Outer-shadow horizontal scaling (`a:outerShdw/@sx`) in 1000ths of a percent (default 100000 = 100%). */
+    shadowScaleX?: number;
+    /** Outer-shadow vertical scaling (`a:outerShdw/@sy`). */
+    shadowScaleY?: number;
+    /** Outer-shadow horizontal skew (`a:outerShdw/@kx`) in 60000ths of a degree. */
+    shadowSkewX?: number;
+    /** Outer-shadow vertical skew (`a:outerShdw/@ky`). */
+    shadowSkewY?: number;
+    /** Outer-shadow alignment (`a:outerShdw/@algn`). */
+    shadowAlignment?: 'tl' | 't' | 'tr' | 'l' | 'ctr' | 'r' | 'bl' | 'b' | 'br';
+    /** Inner-shadow rotateWithShape (`a:innerShdw/@rotWithShape`). */
+    innerShadowRotateWithShape?: boolean;
+    /** Reflection fade direction (`a:reflection/@fadeDir`) in 60000ths of a degree. */
+    reflectionFadeDirection?: number;
+    /** Reflection horizontal scaling (`a:reflection/@sx`). */
+    reflectionScaleX?: number;
+    /** Reflection vertical scaling (`a:reflection/@sy`). */
+    reflectionScaleY?: number;
+    /** Reflection horizontal skew (`a:reflection/@kx`). */
+    reflectionSkewX?: number;
+    /** Reflection vertical skew (`a:reflection/@ky`). */
+    reflectionSkewY?: number;
+    /** Reflection alignment (`a:reflection/@algn`). */
+    reflectionAlignment?: 'tl' | 't' | 'tr' | 'l' | 'ctr' | 'r' | 'bl' | 'b' | 'br';
+    /** Reflection rotateWithShape (`a:reflection/@rotWithShape`). */
+    reflectionRotateWithShape?: boolean;
+    /** Reflection start position (`a:reflection/@stPos`) as 0-1 fraction. */
+    reflectionStartPosition?: number;
+    /** Multiple shadow layers (for advanced effects). */
+    shadows?: ShadowEffect[];
+    glowColor?: string;
+    /** Original glow node used for lossless surgical updates. */
+    glowXml?: XmlObject;
+    /** Resolved source glow colour used to detect colour edits. */
+    glowOriginalColor?: string;
+    /** Source glow opacity used to detect alpha edits. */
+    glowOriginalOpacity?: number;
+    glowRadius?: number;
+    glowOpacity?: number;
+    softEdgeRadius?: number;
+    /** Inner shadow colour (`a:innerShdw`). */
+    innerShadowColor?: string;
+    /** Original inner-shadow node used for lossless surgical updates. */
+    innerShadowXml?: XmlObject;
+    /** Resolved source inner-shadow colour used to detect colour edits. */
+    innerShadowOriginalColor?: string;
+    /** Source inner-shadow opacity used to detect alpha edits. */
+    innerShadowOriginalOpacity?: number;
+    /** 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;
+    /** Original soft-edge node, including vendor attributes and extensions. */
+    softEdgeXml?: XmlObject;
+    /** Reflection effect — distance from shape bottom in px. */
+    reflectionBlurRadius?: number;
+    /** Original reflection node, including vendor attributes and extensions. */
+    reflectionXml?: XmlObject;
+    /** 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';
+    /** `<a:lnRef @idx>` — 1-based index into the theme's lnStyleLst. */
+    lnRefIdx?: number;
+    /** Raw XML colour child of `<a:lnRef>` (e.g. `<a:schemeClr>` with transforms). */
+    lnRefColorXml?: XmlObject;
+    /** `<a:fillRef @idx>` — 1-based index into fillStyleLst (1-3) or bgFillStyleLst (1001-1003). */
+    fillRefIdx?: number;
+    /** Raw XML colour child of `<a:fillRef>`. */
+    fillRefColorXml?: XmlObject;
+    /** `<a:effectRef @idx>` — 1-based index into the theme's effectStyleLst. */
+    effectRefIdx?: number;
+    /** Raw XML colour child of `<a:effectRef>`. */
+    effectRefColorXml?: XmlObject;
+    /** `<a:fontRef @idx>` — typically `major`, `minor`, or `none`. */
+    fontRefIdx?: string;
+    /** Raw XML colour child of `<a:fontRef>`. */
+    fontRefColorXml?: XmlObject;
+}
+
+/**
+ * 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;
+    /**
+     * When true, the source authored `<a:u val="none"/>` to explicitly suppress
+     * underline (rather than omitting the attribute entirely). Preserved so the
+     * writer can re-emit the explicit `none` token instead of dropping it.
+     */
+    underlineExplicitNone?: boolean;
+    /**
+     * Underline line properties parsed from `<a:rPr><a:uLn>` — width, dash
+     * preset, and end caps. Captured as a typed object so the writer can
+     * round-trip the line styling that previously was dropped (only the
+     * solidFill colour was carried before).
+     */
+    underlineLine?: {
+        /** Line width in EMU (raw OOXML) for `a:uLn/@w`. */
+        widthEmu?: number;
+        /** Compound line type (`a:uLn/@cmpd`). */
+        compound?: string;
+        /** Cap style (`a:uLn/@cap`). */
+        cap?: string;
+        /** Pen alignment (`a:uLn/@algn`). */
+        algn?: string;
+        /** Preset dash value (`a:uLn/a:prstDash/@val`). */
+        prstDash?: string;
+        /** Raw `a:uLn/a:headEnd` XML preserved verbatim. */
+        headEndXml?: XmlObject;
+        /** Raw `a:uLn/a:tailEnd` XML preserved verbatim. */
+        tailEndXml?: XmlObject;
+    };
+    /** When `<a:uLnTx/>` is present — underline line follows the text run line. */
+    underlineLineFollowsText?: boolean;
+    /** When `<a:uFillTx/>` is present — underline fill follows the text run fill. */
+    underlineFillFollowsText?: boolean;
+    strikethrough?: boolean;
+    /** Specific strike type: single or double from `a:rPr/@strike`. */
+    strikeType?: 'sngStrike' | 'dblStrike';
+    /** Text outline width in px (`a:rPr > a:ln/@w` in EMU). */
+    textOutlineWidth?: number;
+    /** Text outline colour as hex string (`a:rPr > a:ln > a:solidFill`). */
+    textOutlineColor?: string;
+    /** 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;
+    /**
+     * Raw XML colour-choice node preserved from `a:rPr/a:solidFill` for
+     * round-trip serialisation. Captures `a:schemeClr` / `a:sysClr` /
+     * `a:prstClr` / `a:srgbClr` plus colour transforms. On save we re-emit
+     * verbatim when the resolved {@link color} still matches this node.
+     */
+    colorXml?: XmlObject;
+    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';
+    /**
+     * When true, the source authored `<a:rPr cap="none"/>` explicitly. This
+     * differs from {@link textCaps} = `"none"` only because the writer must
+     * preserve the explicit token rather than collapse it to omission.
+     */
+    textCapsExplicitNone?: boolean;
+    /** Symbol font family from `a:sym`. */
+    symbolFont?: string;
+    /** East Asian font family from `a:ea`. */
+    eastAsiaFont?: string;
+    /** Complex Script font family from `a:cs`. */
+    complexScriptFont?: string;
+    /** 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;
+    /** Alternative language for the run (`a:rPr/@altLang`). Populated for runs
+     *  authored in mixed-script documents (e.g. Asian/Latin combined). */
+    altLanguage?: string;
+    /** SmartTag (Office grammar tag) GUID id (`a:rPr/@smtId`). Round-tripped
+     *  verbatim — the engine doesn't interpret it. */
+    smartTagId?: number;
+    /** Latin font PANOSE classification string from `a:rPr > a:latin/@panose`. */
+    latinFontPanose?: string;
+    /** Latin font pitch + family flag from `a:rPr > a:latin/@pitchFamily`. */
+    latinFontPitchFamily?: number;
+    /** Latin font character set id from `a:rPr > a:latin/@charset`. */
+    latinFontCharset?: number;
+    /** East-Asian font PANOSE from `a:rPr > a:ea/@panose`. */
+    eastAsiaFontPanose?: string;
+    /** East-Asian font pitch + family flag from `a:rPr > a:ea/@pitchFamily`. */
+    eastAsiaFontPitchFamily?: number;
+    /** East-Asian font character set id from `a:rPr > a:ea/@charset`. */
+    eastAsiaFontCharset?: number;
+    /** Complex-script font PANOSE from `a:rPr > a:cs/@panose`. */
+    complexScriptFontPanose?: string;
+    /** Complex-script font pitch + family flag from `a:rPr > a:cs/@pitchFamily`. */
+    complexScriptFontPitchFamily?: number;
+    /** Complex-script font character set id from `a:rPr > a:cs/@charset`. */
+    complexScriptFontCharset?: number;
+    /** Symbol-font PANOSE from `a:rPr > a:sym/@panose`. */
+    symbolFontPanose?: string;
+    /** Symbol-font pitch + family flag from `a:rPr > a:sym/@pitchFamily`. */
+    symbolFontPitchFamily?: number;
+    /** Symbol-font character set id from `a:rPr > a:sym/@charset`. */
+    symbolFontCharset?: number;
+    /** Paragraph list type for toggling bullet / numbered lists via the toolbar.
+     * - `'bullet'` — character bullet (default "•")
+     * - `'numbered'` — auto-numbered list (arabicPeriod)
+     * - `'none'` — explicitly no list
+     */
+    listType?: 'bullet' | 'numbered' | 'none';
+    /** Default tab size in px (`a:pPr/@defTabSz` in EMU). */
+    defaultTabSize?: number;
+    /** East Asian line break flag (`a:pPr/@eaLnBrk`). */
+    eaLineBreak?: boolean;
+    /** Latin line break flag (`a:pPr/@latinLnBrk`). */
+    latinLineBreak?: boolean;
+    /** Font alignment (`a:pPr/@fontAlgn`): 'auto' | 'base' | 'ctr' | 't' | 'b'. */
+    fontAlignment?: string;
+    /** Hanging punctuation flag (`a:pPr/@hangingPunct`). */
+    hangingPunctuation?: boolean;
+    /** Whether to space first and last paragraph from body edges (`a:bodyPr/@spcFirstLastPara`). */
+    spaceFirstLastParagraph?: boolean;
+    /** Right-to-left column flow (`a:bodyPr/@rtlCol`). */
+    rtlColumns?: boolean;
+    /** Whether text originates from WordArt (`a:bodyPr/@fromWordArt`). */
+    fromWordArt?: boolean;
+    /** Whether text anchoring is centered (`a:bodyPr/@anchorCtr`). */
+    anchorCenter?: boolean;
+    /** Force anti-aliasing (`a:bodyPr/@forceAA`). */
+    forceAntiAlias?: boolean;
+    /** Upright text in 3D views (`a:bodyPr/@upright`). */
+    upright?: boolean;
+    /** Compatible line spacing flag (`a:bodyPr/@compatLnSpc`). */
+    compatibleLineSpacing?: boolean;
+    /**
+     * Text body rotation in **degrees** (`a:bodyPr/@rot`).
+     *
+     * OOXML stores the value as 60000ths of a degree. Positive values rotate
+     * the body clockwise. When undefined, the attribute is omitted on save
+     * (PowerPoint treats absent `rot` as inherit/none).
+     */
+    textBodyRotation?: number;
+    /** Text shadow colour as hex string (`a:outerShdw`). */
+    textShadowColor?: string;
+    /** Text shadow blur radius in px. */
+    textShadowBlur?: number;
+    /** Text shadow horizontal offset in px. */
+    textShadowOffsetX?: number;
+    /** Text shadow vertical offset in px. */
+    textShadowOffsetY?: number;
+    /** Text shadow opacity (0-1). */
+    textShadowOpacity?: number;
+    /** Text inner shadow colour (`a:innerShdw`). */
+    textInnerShadowColor?: string;
+    /** Text inner shadow opacity (0-1). */
+    textInnerShadowOpacity?: number;
+    /** Text inner shadow blur radius in px. */
+    textInnerShadowBlur?: number;
+    /** Text inner shadow horizontal offset in px. */
+    textInnerShadowOffsetX?: number;
+    /** Text inner shadow vertical offset in px. */
+    textInnerShadowOffsetY?: number;
+    /** 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;
+    /** Raw `a:scene3d` subtree used to preserve extensions and unmodelled children. */
+    textBodyScene3dXml?: XmlObject;
+    /**
+     * Raw `<a:extLst>` subtree captured from `<a:bodyPr>`. Preserved verbatim so
+     * authored extensions (e.g. content placeholders, custom application data)
+     * survive a round-trip even though the engine doesn't interpret them.
+     */
+    bodyPropertiesExtLstXml?: XmlObject;
+    /**
+     * Raw `<a:extLst>` subtree captured from `<a:pPr>`. Only meaningful on the
+     * paragraph-level style (paragraphs propagate this via the first segment).
+     */
+    paragraphPropertiesExtLstXml?: XmlObject;
+    /**
+     * Raw `<a:extLst>` subtree captured from `<a:rPr>`. Persisted verbatim on
+     * save when present — covers run-level extensions the typed model doesn't
+     * model (e.g. `a14:hiddenFill` and similar).
+     */
+    runPropertiesExtLstXml?: XmlObject;
+    /**
+     * Raw `<a:defRPr>` XML node captured from `<a:pPr>`. The schema permits
+     * `defRPr` directly inside `pPr` so that paragraph defaults can specify the
+     * end-paragraph run formatting; previously this was dropped on save. We
+     * persist the parsed XML object so it round-trips verbatim.
+     *
+     * Only meaningful on the *first* segment of each paragraph (matches the
+     * convention used for {@link bulletInfo} / {@link endParaRunProperties}).
+     */
+    paragraphDefaultRunPropertiesXml?: XmlObject;
+}
+/**
+ * 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;
+    /**
+     * Raw colour-choice XML captured from `<a:buClr>` so that themed bullets
+     * (`a:schemeClr`, `a:sysClr`, `a:prstClr`) round-trip with their original
+     * identity rather than being flattened to `<a:srgbClr/>` on save.
+     */
+    colorXml?: XmlObject;
+    /** True when `a:buNone` explicitly suppresses bullets. */
+    none?: boolean;
+    /** Picture bullet: relationship ID from `a:buBlip` → `a:blip[@r:embed]`. */
+    imageRelId?: string;
+    /** Picture bullet: data URL of the embedded image. */
+    imageDataUrl?: string;
+    /**
+     * Raw `<a:buBlip>` XML captured at parse time. Carries the full blipFill
+     * subtree (`a:tile`, `a:stretch`, `a:srcRect`, `a:blip > a:extLst`) so the
+     * writer can emit the complete original definition rather than the bare
+     * `a:blip[@r:embed]` mapping. When set, the writer prefers it over
+     * {@link imageRelId} for emission.
+     */
+    imageBlipFillXml?: XmlObject;
+    /** When true, `<a:buFontTx/>` was specified — inherit the bullet font from
+     *  the run text, not from a buFont declaration. */
+    fontInherit?: boolean;
+    /** When true, `<a:buClrTx/>` was specified — inherit the bullet colour from
+     *  the run text. */
+    colorInherit?: boolean;
+    /** When true, `<a:buSzTx/>` was specified — inherit the bullet size from
+     *  the run text font size. */
+    sizeInherit?: boolean;
+}
+/**
+ * A single text run within a paragraph.
+ *
+ * A text body is decomposed into an array of `TextSegment` objects,
+ * each with its own style. Paragraph breaks are represented as
+ * segments with `isParagraphBreak: true`.
+ *
+ * @example
+ * ```ts
+ * const segments: TextSegment[] = [
+ *   { text: "Bold intro ", style: { bold: true, fontSize: 16 } },
+ *   { text: "and normal text.", style: { fontSize: 16 } },
+ *   { text: "", style: {}, isParagraphBreak: true },
+ *   { text: "Second paragraph.", style: { fontSize: 14 } },
+ * ];
+ * // => 4 segments: 2 styled runs, 1 paragraph break, 1 normal run
+ * ```
+ */
+interface TextSegment {
+    text: string;
+    style: TextStyle;
+    /** When this segment originated from an `a:fld` element, stores the field type (e.g. "slidenum", "datetime"). */
+    fieldType?: string;
+    /** When this segment originated from an `a:fld` element, stores the field GUID. */
+    fieldGuid?: string;
+    /**
+     * Original attribute name used to author the field GUID — `'uuid'` for the
+     * `a:fld/@uuid` form authored by some legacy producers, `'id'` for the
+     * canonical `a:fld/@id` form. Preserved so the writer round-trips whichever
+     * spelling the source used (PowerPoint accepts both). Defaults to `'id'`
+     * on save when undefined.
+     */
+    fieldGuidAttr?: 'uuid' | 'id';
+    /**
+     * Raw per-field paragraph properties (`a:fld > a:pPr`). The schema permits
+     * `pPr` inside an `a:fld` so the field can carry its own paragraph-level
+     * formatting; preserved verbatim on save when present.
+     */
+    fieldParagraphPropertiesXml?: XmlObject;
+    /** Raw OMML XML node for equation segments (from `a14:m` / `m:oMathPara`). */
+    equationXml?: Record<string, unknown>;
+    /**
+     * Optional equation number for numbered equations (e.g. "(1)", "(2.3)").
+     * When present, the equation is rendered centered with the number right-aligned.
+     */
+    equationNumber?: string;
+    /** Whether this segment represents a paragraph break rather than renderable text. */
+    isParagraphBreak?: boolean;
+    /**
+     * Whether this segment represents a soft line break (`a:br`) rather than
+     * a paragraph terminator. Soft line breaks remain inside the same paragraph
+     * but force a line wrap and may carry their own run properties.
+     *
+     * The renderer should treat the segment text as `"\n"` when present.
+     */
+    isLineBreak?: true;
+    /**
+     * Raw `a:rPr` XML for an `a:br` (soft line break) segment, captured verbatim
+     * during parse so the writer can re-emit attributes/colours/fonts that the
+     * typed model doesn't represent. Only meaningful when {@link isLineBreak}
+     * is `true`.
+     */
+    breakRunProperties?: Record<string, unknown>;
+    /** Structured bullet info for the first segment of a paragraph. */
+    bulletInfo?: BulletInfo;
+    /**
+     * Outline level for the paragraph this segment starts (`a:p/@lvl`).
+     *
+     * Only meaningful on the first segment of a paragraph (matching the
+     * convention used for {@link bulletInfo}). Stored as the raw OOXML
+     * value (0 = top level, 1-8 = nested) and serialised back when non-zero.
+     */
+    paragraphLevel?: number;
+    /**
+     * Raw `a:endParaRPr` XML node for the paragraph this segment starts.
+     *
+     * Captured verbatim on parse so attributes and child colours/fonts that
+     * the typed model doesn't represent survive a round-trip. Only meaningful
+     * on the first segment of a paragraph.
+     */
+    endParaRunProperties?: Record<string, unknown>;
+    /**
+     * 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;
+}
+
+/**
+ * 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;
+    /**
+     * The shape's native OOXML id from `p:cNvPr/@id` (an unsigned integer, as a
+     * string), captured on load. Distinct from {@link id}, which is a synthetic
+     * positional identity (`${slidePath}-shape-${index}`) the loader assigns for
+     * selection / undo / template tracking. Animations target shapes by this
+     * native id (`p:spTgt/@spid`), so it is the stable key used to reconcile an
+     * animation to the element it animates across a save/reload round trip.
+     * Absent on SDK-created elements until one is minted at save time.
+     */
+    shapeId?: string;
+    /** Element name from `cNvPr/@name`. Used for morph transition matching via the `!!` naming convention. */
+    name?: 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;
+    /**
+     * Opaque `<a:ext>` children captured from the shape's `<a:extLst>` whose
+     * URI is not recognised by a typed extractor (hidden fill/line, image
+     * effects, …). Preserved verbatim and re-emitted on save so unknown
+     * vendor extensions survive a round-trip.
+     *
+     * Mirrors the existing `effectDagXml` / `endParaRunProperties` raw-XML
+     * preservation pattern.
+     */
+    extLstXml?: XmlObject[];
+}
+/**
+ * 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[];
+}
+
+/** Tick-mark placement from ChartML `ST_TickMark`. */
+type PptxChartTickMark = 'cross' | 'in' | 'none' | 'out';
+/** Typed axis tick and category/date label controls. */
+interface PptxChartAxisLabelFormatting {
+    /** Primary and secondary tick-mark placement. */
+    majorTickMark?: PptxChartTickMark;
+    minorTickMark?: PptxChartTickMark;
+    /** Tick-label position from ChartML `ST_TickLblPos`. */
+    tickLblPos?: 'high' | 'low' | 'nextTo' | 'none';
+    /** Automatic category/date axis behavior (`c:auto`). */
+    auto?: boolean;
+    /** Category-axis label alignment (`c:lblAlgn`). */
+    labelAlignment?: 'ctr' | 'l' | 'r';
+    /** Category/date label distance, from 0 through 1000 percent. */
+    labelOffset?: number;
+    /** Suppress multi-level category labels (`c:noMultiLvlLbl`). */
+    noMultiLevelLabels?: boolean;
+}
+
+/**
+ * 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' | 'ofPie' | '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;
+    name?: string;
+    order?: number;
+    period?: number;
+    forward?: number;
+    backward?: number;
+    intercept?: number;
+    displayRSq?: boolean;
+    displayEq?: boolean;
+    color?: string;
+    label?: PptxChartTrendlineLabel | null;
+}
+/** Typed, commonly edited properties of `c:trendlineLbl`. */
+interface PptxChartTrendlineLabel {
+    layout?: PptxChartManualLayout;
+    numberFormatCode?: string;
+    sourceLinked?: boolean;
+}
+/** 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[];
+    noEndCap?: boolean;
+    color?: string;
+}
+/**
+ * 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;
+    /** Line dash style (a:prstDash/@val), e.g. 'solid', 'dash', 'dot', 'lgDash'. */
+    strokeDashStyle?: string;
+}
+/** Up/down bar formatting on line and stock charts (`c:upDownBars`). */
+interface PptxChartUpDownBars {
+    /** Gap between bars as a percentage, constrained to 0 through 500. */
+    gapWidth?: number;
+    upBars?: PptxChartShapeProps;
+    downBars?: PptxChartShapeProps;
+}
+/** 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;
+}
+/** Schema values accepted by `c:dLblPos`. */
+type PptxChartDataLabelPosition = 'bestFit' | 'b' | 'ctr' | 'inBase' | 'inEnd' | 'l' | 'outEnd' | 'r' | 't';
+/** Individual data label override (c:dLbl). */
+interface PptxChartDataLabel {
+    idx: number;
+    /** Suppress this data point's automatically generated label. */
+    deleted?: boolean;
+    showVal?: boolean;
+    showCatName?: boolean;
+    showSerName?: boolean;
+    showPercent?: boolean;
+    showLegendKey?: boolean;
+    showBubbleSize?: boolean;
+    position?: PptxChartDataLabelPosition;
+    text?: string;
+    separator?: string;
+    showLeaderLines?: boolean;
+}
+/** Axis number format. */
+interface PptxChartAxisNumFmt {
+    formatCode: string;
+    sourceLinked?: boolean;
+}
+/** Typed contents of a value-axis display-unit label (`c:dispUnitsLbl`). */
+interface PptxChartDisplayUnitsLabel {
+    /** Literal label text. Omit to preserve the source text subtree. */
+    text?: string;
+    /** Manual label placement. `null` removes only the manual layout. */
+    layout?: PptxChartManualLayout | null;
+    /** Label shape formatting. `null` removes `c:spPr`. */
+    spPr?: PptxChartShapeProps | null;
+}
+/** Axis formatting for category, value, or date axes. */
+interface PptxChartAxisFormatting extends PptxChartAxisLabelFormatting {
+    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;
+    /** Whether major gridlines are present (`c:majorGridlines`). */
+    majorGridlines?: boolean;
+    /** Whether minor gridlines are present (`c:minorGridlines`). */
+    minorGridlines?: boolean;
+    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-unit label contents (`c:dispUnits/c:dispUnitsLbl`). A string is
+     * retained as a compatibility shorthand for `{ text: string }`; `null`
+     * explicitly removes the label.
+     */
+    displayUnitsLabel?: string | PptxChartDisplayUnitsLabel | null;
+    /** 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;
+    /** Major-unit interval between primary tick marks (c:majorUnit/@val). */
+    majorUnit?: number;
+    /** Minor-unit interval between secondary tick marks (c:minorUnit/@val). */
+    minorUnit?: 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;
+    /**
+     * Per-series chart type, used for combo charts where individual series are
+     * plotted with different chart types (e.g. a bar series and a line series in
+     * the same chart). Maps to the OOXML chart-type container that holds the
+     * series (`c:barChart`, `c:lineChart`, etc.). Omitted for single-type charts,
+     * where the chart-level {@link PptxChartData.chartType} applies to every
+     * series.
+     */
+    seriesChartType?: PptxChartType;
+}
+/**
+ * Chart-level data-label options (`c:dLbls` directly under a chart-type
+ * container, applying to every series). Mirrors the OOXML `c:show*` flags
+ * and `c:dLblPos`.
+ */
+interface PptxChartDataLabelOptions {
+    /** Show the numeric value (`c:showVal`). */
+    showValue?: boolean;
+    /** Show the category name (`c:showCatName`). */
+    showCategory?: boolean;
+    /** Show the series name (`c:showSerName`). */
+    showSeriesName?: boolean;
+    /** Show the percentage (`c:showPercent`, pie/doughnut). */
+    showPercent?: boolean;
+    /** Show the legend key swatch (`c:showLegendKey`). */
+    showLegendKey?: boolean;
+    /** Show bubble size (`c:showBubbleSize`). */
+    showBubbleSize?: boolean;
+    /** Text placed between combined label components (`c:separator`). */
+    separator?: string;
+    /** Show leader lines where supported (`c:showLeaderLines`). */
+    showLeaderLines?: boolean;
+    /**
+     * Label position (`c:dLblPos`). Valid values depend on the chart type
+     * (`ctr`, `inEnd`, `inBase`, `outEnd`, `bestFit`, `l`, `r`, `t`, `b`).
+     * Omit to let PowerPoint use the type default.
+     */
+    position?: PptxChartDataLabelPosition;
+}
+/** Typed text defaults for a single chart legend entry. */
+interface PptxChartLegendTextStyle {
+    fontFamily?: string;
+    fontSize?: number;
+    bold?: boolean;
+    italic?: boolean;
+    color?: string;
+}
+/** Per-series legend entry override (`c:legendEntry`). */
+interface PptxChartLegendEntry {
+    index: number;
+    deleted?: boolean;
+    textStyle?: PptxChartLegendTextStyle;
+}
+/**
+ * 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;
+    /** Per-series visibility and text-style overrides. */
+    legendEntries?: PptxChartLegendEntry[];
+    /** Whether the chart has a title. */
+    hasTitle?: boolean;
+    /** Whether gridlines are visible. */
+    hasGridlines?: boolean;
+    /** Whether data labels are shown. */
+    hasDataLabels?: boolean;
+    /** Chart-level data-label content/position options (when `hasDataLabels`). */
+    dataLabels?: PptxChartDataLabelOptions;
+}
+/**
+ * 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;
+}
+/**
+ * Options specific to the OOXML "Pie of Pie" / "Bar of Pie" chart
+ * (`c:ofPieChart`, ECMA-376 §21.2.2.126 / CT_OfPieChart).
+ *
+ * The primary discriminator is {@link ofPieType}: `"pie"` produces a
+ * pie-of-pie chart whose secondary plot is itself a pie, while `"bar"`
+ * produces a bar-of-pie chart whose secondary plot is a horizontal bar.
+ *
+ * - {@link splitType} chooses the split rule.
+ * - {@link splitPos} is the threshold value used by `pos`/`val`/`percent`.
+ * - {@link secondPieSize} controls the secondary plot's size (5–200%).
+ * - {@link serLines} toggles the leader lines connecting the plots.
+ * - {@link gapWidth} is the gap between the plots in percent (0–500).
+ */
+interface PptxChartOfPieOptions {
+    ofPieType: 'pie' | 'bar';
+    splitType?: 'auto' | 'cust' | 'percent' | 'pos' | 'val';
+    splitPos?: number;
+    custSplit?: number[];
+    secondPieSize?: number;
+    serLines?: boolean;
+    gapWidth?: number;
+}
+/** Classic `c:bubbleChart` options from CT_BubbleChart. */
+interface PptxBubbleChartOptions {
+    bubble3D?: boolean;
+    /** Bubble diameter scale in percent, constrained to 0 through 300. */
+    bubbleScale?: number;
+    showNegativeBubbles?: boolean;
+    sizeRepresents?: 'area' | 'w';
+}
+/**
+ * 3D viewing parameters for a chart (`c:view3D`, ECMA-376 §21.2.2.228 /
+ * CT_View3D).
+ *
+ * All fields are optional and round-trip verbatim.
+ *
+ * - {@link rotX} — X-axis rotation in degrees (-90…90).
+ * - {@link rotY} — Y-axis rotation in degrees (0…360).
+ * - {@link depthPercent} — chart depth as a percentage of base width.
+ * - {@link rAngAx} — `true` if axes meet at right angles.
+ * - {@link perspective} — perspective angle in degrees (0…240).
+ * - {@link hPercent} — height as a percentage of chart width.
+ */
+interface PptxChartView3D {
+    rotX?: number;
+    rotY?: number;
+    depthPercent?: number;
+    rAngAx?: boolean;
+    perspective?: number;
+    hPercent?: number;
+}
+/**
+ * Chart "chrome" flags from `c:chart` that round-trip cleanly even when
+ * rendering ignores them.
+ *
+ * - {@link autoTitleDeleted} — `c:autoTitleDeleted/@val`. Suppresses the
+ *   auto-generated title for single-series charts.
+ * - {@link dispBlanksAs} — `c:dispBlanksAs/@val`. How blank cells
+ *   render: `"gap"`, `"zero"`, or `"span"`.
+ * - {@link showDLblsOverMax} — `c:showDLblsOverMax/@val`. Keeps data
+ *   labels visible for points exceeding the value-axis maximum.
+ *
+ * `c:plotVisOnly` lives on {@link PptxChartData.plotVisibleOnly} and is
+ * intentionally not duplicated here.
+ */
+interface PptxChartChrome {
+    autoTitleDeleted?: boolean;
+    dispBlanksAs?: 'gap' | 'zero' | 'span';
+    showDLblsOverMax?: boolean;
+}
+/** Manual chart placement from `c:layout/c:manualLayout` (CT_ManualLayout). */
+interface PptxChartManualLayout {
+    layoutTarget?: 'inner' | 'outer';
+    xMode?: 'edge' | 'factor';
+    yMode?: 'edge' | 'factor';
+    widthMode?: 'edge' | 'factor';
+    heightMode?: 'edge' | 'factor';
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+/**
+ * Typed manual layouts for chart regions that accept `c:layout`.
+ * A `null` region removes its manual layout without removing extensions.
+ */
+interface PptxChartLayouts {
+    title?: PptxChartManualLayout | null;
+    plotArea?: PptxChartManualLayout | null;
+    legend?: PptxChartManualLayout | null;
+}
+/** 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;
+    /** `null` explicitly removes an existing ChartML data table. */
+    dataTable?: PptxChartDataTable | null;
+    dropLines?: PptxChartLineStyle;
+    hiLowLines?: PptxChartLineStyle;
+    /** `null` explicitly removes an existing up/down-bars container. */
+    upDownBars?: PptxChartUpDownBars | null;
+    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';
+    /**
+     * Pie-of-pie / Bar-of-pie options (`c:ofPieChart`, CT_OfPieChart).
+     *
+     * Present only when {@link chartType} is `"ofPie"`. Carries the split
+     * configuration, secondary plot size, and serLines flag so that an
+     * `ofPieChart` element can be re-emitted on save with full fidelity.
+     */
+    ofPieOptions?: PptxChartOfPieOptions;
+    /** Classic bubble-chart display options (`c:bubbleChart`). */
+    bubbleOptions?: PptxBubbleChartOptions;
+    /**
+     * 3D viewing parameters (`c:view3D`, CT_View3D).
+     *
+     * Parsed from and emitted to `c:chart/c:view3D`. Absent when the
+     * chart XML has no `c:view3D` element.
+     */
+    view3D?: PptxChartView3D;
+    /**
+     * Top-level chart chrome flags (`c:autoTitleDeleted`,
+     * `c:dispBlanksAs`, `c:showDLblsOverMax`).
+     *
+     * Each flag is omitted from the emitted XML when absent on the
+     * source data, so absence does not produce empty `<c:…/>` placeholders.
+     */
+    chartChrome?: PptxChartChrome;
+    /** Editable manual placement for the title, plot area, and legend. */
+    layouts?: PptxChartLayouts;
+    /**
+     * Raw `c:userShapes` XML subtree (a drawing tree) preserved verbatim.
+     *
+     * `c:userShapes` references a separate drawing part containing
+     * shapes drawn over the chart. The reference is preserved as-is so
+     * that round-trip save re-emits the original element without
+     * attempting to parse the nested drawing tree.
+     */
+    userShapesXml?: unknown;
+    /**
+     * Raw `c:pivotFmts` XML subtree preserved verbatim.
+     *
+     * `c:pivotFmts` carries a list of `c:pivotFmt` formatting overrides
+     * for charts whose data originates from a PivotTable. Preserved
+     * verbatim for round-trip fidelity.
+     */
+    pivotFmtsXml?: unknown;
+    /**
+     * Color-map override (`c:clrMapOvr`) carrying 12 attributes that
+     * remap theme colour roles for this chart only. Preserved as a flat
+     * `attribute → value` map for round-trip fidelity.
+     */
+    clrMapOvr?: Record<string, string>;
+}
+
+type EffectDagBlendMode = 'darken' | 'lighten' | 'mult' | 'over' | 'screen';
+type EffectDagContainerType = 'sib' | 'tree';
+type EffectDagNode = EffectDagContainer | EffectDagBlend | EffectDagXfrm | EffectDagRelOff | EffectDagBlur | EffectDagPresetShadow | EffectDagRawLeaf;
+interface EffectDagContainer {
+    kind: 'cont';
+    type: EffectDagContainerType;
+    name?: string;
+    children: EffectDagNode[];
+}
+interface EffectDagBlend {
+    kind: 'blend';
+    mode: EffectDagBlendMode;
+    container: EffectDagContainer;
+}
+interface EffectDagXfrm {
+    kind: 'xfrmEffect';
+    sx?: number;
+    sy?: number;
+    kx?: number;
+    ky?: number;
+    tx?: number;
+    ty?: number;
+}
+interface EffectDagRelOff {
+    kind: 'relOff';
+    tx?: number;
+    ty?: number;
+}
+/** Typed CT_BlurEffect with its original payload retained for lossless edits. */
+interface EffectDagBlur {
+    kind: 'blur';
+    radiusEmu?: number;
+    grow?: boolean;
+    xml: XmlObject;
+}
+/** Typed CT_PresetShadowEffect with colour and extension XML retained verbatim. */
+interface EffectDagPresetShadow {
+    kind: 'prstShdw';
+    preset?: `shdw${number}`;
+    distanceEmu?: number;
+    direction?: number;
+    xml: XmlObject;
+}
+interface EffectDagRawLeaf {
+    kind: 'raw';
+    tag: string;
+    xml: Record<string, unknown>;
+}
+
+/**
+ * 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;
+    };
+    /**
+     * Alpha inverse effect (`a:alphaInv`). Inverts the alpha channel; an optional
+     * colour child shifts the inversion baseline.
+     */
+    alphaInv?: {
+        /** Optional baseline colour (hex). */
+        color?: string;
+    };
+    /** Alpha ceiling (`a:alphaCeiling`) — clamps any non-zero alpha to fully opaque. Boolean flag. */
+    alphaCeiling?: boolean;
+    /** Alpha floor (`a:alphaFloor`) — clamps any non-fully-opaque alpha to fully transparent. Boolean flag. */
+    alphaFloor?: boolean;
+    /**
+     * Alpha modulate (`a:alphaMod`). The schema requires a single `cont` (effect
+     * container) child; we preserve the inner XML opaquely for round-trip.
+     */
+    alphaMod?: {
+        /** Raw opaque XML for the `a:cont` child to preserve on save. */
+        contRawXml?: Record<string, unknown>;
+    };
+    /** Alpha replace (`a:alphaRepl`) — replaces alpha with the given fixed-percent value (0..100). */
+    alphaRepl?: number;
+    /** Alpha bi-level (`a:alphaBiLevel`) — threshold (0..100) above which alpha becomes fully opaque. */
+    alphaBiLevel?: number;
+    /**
+     * Colour replace (`a:clrRepl`) — replaces all colour information in an image
+     * with the given solid colour. Stores the raw colour child to preserve scheme
+     * colour references and modifiers.
+     */
+    clrRepl?: {
+        /** Resolved hex colour. */
+        color: string;
+        /** Raw opaque colour XML for round-trip. */
+        rawXml?: Record<string, unknown>;
+    };
+    /** Luminance modulation (`a:lum`) — bright/contrast as fixed percentages (0..100). */
+    lum?: {
+        bright?: number;
+        contrast?: number;
+    };
+    /** HSL modulation (`a:hsl`) — hue (0..360 degrees), saturation/luminance (-100..100). */
+    hsl?: {
+        hue?: number;
+        sat?: number;
+        lum?: number;
+    };
+    /** Image-effect tint (`a:tint` inside blip) — hue (0..360), amount (-100..100). */
+    tint?: {
+        hue?: number;
+        amt?: number;
+    };
+    /**
+     * Fill overlay (`a:fillOverlay`) — overlays a fill on top of the blip.
+     * Stores blend mode and the raw inner fill XML for round-trip.
+     */
+    fillOverlay?: {
+        blend: 'over' | 'mult' | 'screen' | 'darken' | 'lighten';
+        /** Raw opaque fill XML preserved for round-trip. */
+        fillRawXml?: Record<string, unknown>;
+    };
+    /** Blur (`a:blur`) — radius in EMU and grow flag. */
+    blur?: {
+        rad?: number;
+        grow?: 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;
+}
+declare module "./index" {
+    interface TextStyle {
+        /**
+         * Raw `a:effectDag` XML node from `a:rPr`, preserved verbatim for
+         * round-trip serialisation. Mirrors the shape-level
+         * {@link import('./shape-style').ShapeStyle.effectDagXml} field.
+         */
+        textEffectDagXml?: XmlObject;
+        /**
+         * Typed effect graph parsed from `textEffectDagXml`. The four structural
+         * container nodes (`a:cont`, `a:blend`, `a:xfrmEffect`, `a:relOff`) are
+         * fully typed; any other leaf effect is captured as
+         * {@link EffectDagRawLeaf} so we never have to recurse into the full
+         * effect taxonomy.
+         */
+        textEffectDagTree?: EffectDagContainer;
+    }
+}
+declare module "./index" {
+    interface ShapeStyle {
+        /**
+         * Typed effect graph parsed from {@link ShapeStyle.effectDagXml}. The four
+         * structural container nodes (`a:cont`, `a:blend`, `a:xfrmEffect`,
+         * `a:relOff`) are fully typed; any other leaf effect (e.g. `a:outerShdw`,
+         * `a:glow`, `a:alphaInv`) is captured as {@link EffectDagRawLeaf} so we
+         * never have to recurse into the full effect taxonomy.
+         */
+        effectDagTree?: EffectDagContainer;
+    }
+}
+
+/**
+ * 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';
+type PptxMediaReferenceKind = 'audioCd' | 'wavAudioFile' | 'audioFile' | 'videoFile' | 'quickTimeFile';
+interface PptxAudioCdPosition {
+    track: number;
+    time?: number;
+}
+/**
+ * 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;
+}
+
+/** Typed, editable metadata from a DiagramML layout-definition part. */
+interface PptxSmartArtLocalizedText {
+    value: string;
+    language?: string;
+}
+interface PptxSmartArtLayoutCategory {
+    type: string;
+    priority: number;
+}
+/** Identity and ordering metadata from DiagramML CT_LayoutNode. */
+interface PptxSmartArtLayoutNode {
+    name?: string;
+    styleLabel?: string;
+    childOrder?: 'b' | 't';
+    moveWith?: string;
+    children?: PptxSmartArtLayoutNode[];
+}
+/** Metadata and root node from DiagramML CT_DiagramDefinition. */
+interface PptxSmartArtLayoutDefinition {
+    uniqueId?: string;
+    minimumVersion?: string;
+    defaultStyle?: string;
+    titles?: PptxSmartArtLocalizedText[];
+    descriptions?: PptxSmartArtLocalizedText[];
+    categories?: PptxSmartArtLayoutCategory[];
+    rootNode: PptxSmartArtLayoutNode;
+}
+
+/**
+ * SmartArt node types: per-run text, per-node visual override, and the
+ * data-model node itself. Split out of `smart-art.ts` to keep each type file
+ * within the project's per-file line budget. Re-exported from `smart-art.ts`
+ * (and thus the `types` barrel) for backward compatibility, so existing
+ * imports of these symbols continue to work unchanged.
+ *
+ * @module pptx-types/smart-art-node
+ */
+/**
+ * A single run of text inside a SmartArt node, capturing the run text and the
+ * raw `a:rPr` run-properties object verbatim so per-run formatting (bold,
+ * colour, size, etc.) survives a load -> edit -> save round-trip instead of
+ * collapsing to a single unstyled run.
+ *
+ * @example
+ * ```ts
+ * const run: PptxSmartArtTextRun = {
+ *   text: "Bold",
+ *   rPr: { "@_b": "1", "@_lang": "en-US" },
+ * };
+ * // => satisfies PptxSmartArtTextRun
+ * ```
+ */
+interface PptxSmartArtTextRun {
+    /** Run text content. */
+    text: string;
+    /**
+     * Raw parsed `a:rPr` run-properties object, preserved verbatim for
+     * round-trip. Untyped XML, hence the loose record shape.
+     */
+    rPr?: Record<string, unknown>;
+}
+/**
+ * Per-node visual override for a SmartArt node.
+ *
+ * Captures the individual fill / line / font colour and the bold / italic
+ * emphasis a user has set on one specific node, independent of the diagram's
+ * colour scheme and quick style. All colours are hex strings (e.g. "#FF0000").
+ * Every field is optional: only the overridden aspects are carried, so an
+ * empty object means "no per-node override".
+ *
+ * The parser reads these from the data point's `spPr` solid fill / line colour
+ * and the first run's `rPr` (b / i / solidFill) when present, and the save path
+ * writes them back so the override survives a load -> edit -> save round-trip.
+ *
+ * @example
+ * ```ts
+ * const style: PptxSmartArtNodeStyle = {
+ *   fillColor: "#FF0000",
+ *   fontColor: "#FFFFFF",
+ *   bold: true,
+ * };
+ * // => satisfies PptxSmartArtNodeStyle
+ * ```
+ */
+interface PptxSmartArtNodeStyle {
+    /** Solid fill colour override (hex, e.g. "#4F81BD"). */
+    fillColor?: string;
+    /** Outline / line colour override (hex). */
+    lineColor?: string;
+    /** Text (font) colour override (hex). */
+    fontColor?: string;
+    /** Bold emphasis override for the node's runs. */
+    bold?: boolean;
+    /** Italic emphasis override for the node's runs. */
+    italic?: boolean;
+}
+/**
+ * A single node in the SmartArt data model.
+ *
+ * @example
+ * ```ts
+ * const node: PptxSmartArtNode = {
+ *   id: "1",
+ *   text: "CEO",
+ *   children: [
+ *     { id: "2", text: "VP Marketing", parentId: "1" },
+ *     { id: "3", text: "VP Engineering", parentId: "1" },
+ *   ],
+ * };
+ * // => satisfies PptxSmartArtNode
+ * ```
+ */
+interface PptxSmartArtNode {
+    id: string;
+    text: string;
+    /** CT_Pt connection identifier, when the point references a connection. */
+    connectionId?: string | null;
+    parentId?: string;
+    children?: PptxSmartArtNode[];
+    /** Node type from `@_type` attribute (e.g. "doc", "node", "asst", "pres"). */
+    nodeType?: string;
+    /**
+     * Per-run text + run-properties for the node's first paragraph, captured at
+     * parse time. When the joined run text still equals {@link text} (the node
+     * was not edited, or was edited only in ways that preserve the run split),
+     * the save path rebuilds the paragraph from these runs so per-run rich text
+     * is not flattened. When {@link text} diverges, the runs are ignored.
+     */
+    runs?: PptxSmartArtTextRun[];
+    /**
+     * Optional per-node visual override (fill / line / font colour, bold /
+     * italic). Read at parse time from the point's `spPr` / first-run `rPr`, set
+     * by the editing op, honoured by the render path, and written back on save so
+     * it round-trips.
+     */
+    style?: PptxSmartArtNodeStyle;
+}
+
+/** Editable metadata shared by DiagramML quick-style and color definitions. */
+interface PptxSmartArtDefinitionText {
+    value: string;
+    language?: string;
+}
+interface PptxSmartArtDefinitionCategory {
+    type: string;
+    priority: number;
+}
+type PptxSmartArtColorApplicationMethod = 'span' | 'cycle' | 'repeat';
+type PptxSmartArtHueDirection = 'cw' | 'ccw';
+/** CT_Colors application metadata. Color-choice children remain preserved XML. */
+interface PptxSmartArtColorListMetadata {
+    method?: PptxSmartArtColorApplicationMethod;
+    hueDirection?: PptxSmartArtHueDirection;
+}
+/** CT_StyleLabel metadata from a quick-style definition. */
+interface PptxSmartArtQuickStyleLabel {
+    name: string;
+}
+/** CT_CTStyleLabel metadata from a color-transform definition. */
+interface PptxSmartArtColorStyleLabel {
+    name: string;
+    fill?: PptxSmartArtColorListMetadata;
+    line?: PptxSmartArtColorListMetadata;
+    effect?: PptxSmartArtColorListMetadata;
+    textLine?: PptxSmartArtColorListMetadata;
+    textFill?: PptxSmartArtColorListMetadata;
+    textEffect?: PptxSmartArtColorListMetadata;
+}
+interface PptxSmartArtDefinitionMetadata {
+    uniqueId?: string;
+    minimumVersion?: string;
+    titles?: PptxSmartArtDefinitionText[];
+    descriptions?: PptxSmartArtDefinitionText[];
+    categories?: PptxSmartArtDefinitionCategory[];
+}
+/** Typed CT_ColorTransform metadata and the resolved legacy color palette. */
+interface PptxSmartArtColorTransform extends PptxSmartArtDefinitionMetadata {
+    /** Legacy resolved display name. */
+    name?: string;
+    /** Ordered resolved fill colors for rendering. */
+    fillColors: string[];
+    /** Ordered resolved line colors for rendering. */
+    lineColors: string[];
+    /** Ordered CT_CTStyleLabel metadata. */
+    labels?: PptxSmartArtColorStyleLabel[];
+}
+/** Typed CT_StyleDefinition metadata and legacy rendering hint. */
+interface PptxSmartArtQuickStyle extends PptxSmartArtDefinitionMetadata {
+    /** Legacy resolved display name. */
+    name?: string;
+    /** Legacy effect-intensity rendering hint. */
+    effectIntensity?: string;
+    /** Ordered CT_StyleLabel metadata. Complex style payload remains preserved XML. */
+    labels?: PptxSmartArtQuickStyleLabel[];
+}
+
+/**
+ * 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 connection between two SmartArt data-model nodes.
+ *
+ * @example
+ * ```ts
+ * const conn: PptxSmartArtConnection = {
+ *   sourceId: "1",
+ *   destId: "2",
+ *   type: "parOf",
+ * };
+ * // => satisfies PptxSmartArtConnection
+ * ```
+ */
+interface PptxSmartArtConnection {
+    /** Stable CT_Cxn model identifier. Required when serialized. */
+    modelId?: string | null;
+    /** 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;
+    /** Model ID of the parent transition point associated with this edge. */
+    parentTransitionId?: string | null;
+    /** Model ID of the sibling transition point associated with this edge. */
+    siblingTransitionId?: string | null;
+    /** Layout presentation identifier used by presentation connections. */
+    presentationId?: string | null;
+}
+/**
+ * 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;
+}
+/**
+ * Complete parsed SmartArt data for a {@link SmartArtPptxElement}.
+ *
+ * @example
+ * ```ts
+ * const data: PptxSmartArtData = {
+ *   resolvedLayoutType: "hierarchy",
+ *   layout: "hierarchy",
+ *   colorScheme: "colorful1",
+ *   style: "moderate",
+ *   nodes: [
+ *     { id: "1", text: "CEO", children: [
+ *       { id: "2", text: "VP Marketing", parentId: "1" },
+ *     ]},
+ *   ],
+ * };
+ * // => satisfies PptxSmartArtData
+ * ```
+ */
+interface PptxSmartArtData {
+    layoutType?: string;
+    resolvedLayoutType?: SmartArtLayoutType;
+    /** Named layout preset (used when creating new SmartArt). */
+    layout?: SmartArtLayout;
+    /** Colour scheme for the SmartArt graphic. */
+    colorScheme?: SmartArtColorScheme;
+    /** Visual style intensity. */
+    style?: SmartArtStyle;
+    nodes: PptxSmartArtNode[];
+    /** Connections between data-model nodes. */
+    connections?: PptxSmartArtConnection[];
+    /** Pre-computed shapes from `ppt/diagrams/drawing*.xml`. */
+    drawingShapes?: PptxSmartArtDrawingShape[];
+    /** Background and outline chrome from `dgm:bg` / `dgm:whole`. */
+    chrome?: PptxSmartArtChrome;
+    /** Colour transform from `ppt/diagrams/colors*.xml`. */
+    colorTransform?: PptxSmartArtColorTransform;
+    /** Quick style from `ppt/diagrams/quickStyles*.xml`. */
+    quickStyle?: PptxSmartArtQuickStyle;
+    /** Editable metadata from the related DiagramML layout definition. */
+    layoutDefinition?: PptxSmartArtLayoutDefinition;
+    /** Relationship ID for the diagram data part (for round-trip save). */
+    dataRelId?: string;
+    /** Relationship ID for the diagram layout part. */
+    layoutRelId?: string;
+    /** Relationship ID for the drawing part. */
+    drawingRelId?: string;
+    /** Relationship ID for the colours part. */
+    colorsRelId?: string;
+    /** Relationship ID for the quick-styles part. */
+    styleRelId?: string;
+    /** Internal save hint: the layout definition changed in the editor. */
+    layoutDirty?: boolean;
+    /** Internal save hint: typed layout-definition metadata changed. */
+    layoutDefinitionDirty?: boolean;
+    /** Internal save hint: quick-style definition metadata changed. */
+    quickStyleDirty?: boolean;
+    /** Internal save hint: color-transform definition metadata changed. */
+    colorTransformDirty?: boolean;
+    /** Internal save hint: cached drawing geometry or text changed in the editor. */
+    drawingDirty?: boolean;
+}
+
+/**
+ * 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;
+    /**
+     * Raw XML colour-choice node preserved from `a:tc/a:txBody/.../a:rPr/a:solidFill`
+     * for round-trip serialisation. Currently unused by the cell-level writer
+     * (cell text colour falls through `writeCellTextFormatting`), reserved for
+     * future expansion alongside the run-properties round-trip path.
+     */
+    colorXml?: XmlObject;
+    backgroundColor?: string;
+    /**
+     * Raw XML colour-choice node preserved from cell `a:tcPr/a:solidFill` for
+     * round-trip serialisation. Re-emitted verbatim when the resolved
+     * {@link backgroundColor} still matches the original colour.
+     */
+    backgroundColorXml?: XmlObject;
+    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` (spec values from CT_TextVerticalType). */
+    textDirection?: 'vert' | 'vert270' | '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;
+    /**
+     * Opaque round-trip storage for `a:tcPr` attributes that don't yet have
+     * typed equivalents on {@link PptxTableCellStyle} (e.g. `horzOverflow`,
+     * `anchorCtr`, `headers`, `hideSlicers`, `slicerCacheId`). Keys are the
+     * raw XML attribute names without the `@_` prefix used by
+     * fast-xml-parser. Re-emitted verbatim by the save writer when present.
+     */
+    extraAttributes?: Record<string, string>;
+}
+/**
+ * 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;
+    /** Right-to-left table layout from `a:tblPr/@rtl`. */
+    rtl?: boolean;
+}
+
+/**
+ * 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 single unrecognised `<a:graphicData>/<a:extLst>/<a:ext>` extension on a
+ * graphicFrame, captured verbatim so the round-trip can preserve future or
+ * vendor-specific markup that the parser doesn't yet understand.
+ *
+ * The XML is preserved as a fast-xml-parser object tree (the same shape as
+ * `rawXml` on other elements) so the save layer can re-emit it through the
+ * existing builder without lossy string manipulation.
+ */
+interface PptxGraphicFrameExtension {
+    /** The `@_uri` attribute identifying the extension (e.g. `{C3CD43...}`). */
+    uri: string;
+    /** Parsed XML payload of the extension, suitable for re-serialization. */
+    xml: XmlObject;
+}
+/**
+ * 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;
+    /**
+     * Unrecognised extensions captured from `a:graphicData/a:extLst` so they
+     * round-trip losslessly. See {@link PptxGraphicFrameExtension}.
+     */
+    extensionXml?: PptxGraphicFrameExtension[];
+}
+/**
+ * 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;
+    /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
+    extensionXml?: PptxGraphicFrameExtension[];
+}
+/**
+ * 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;
+    /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
+    extensionXml?: PptxGraphicFrameExtension[];
+}
+/**
+ * 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;
+    /** Whether the OLE object is shown as an icon (`p:oleObj/@showAsIcon`). */
+    oleShowAsIcon?: boolean;
+    /** Authored display width of the OLE object preview, in EMU (`@imgW`). */
+    oleImgW?: number;
+    /** Authored display height of the OLE object preview, in EMU (`@imgH`). */
+    oleImgH?: number;
+    /**
+     * The recovered embedded payload as a data-URL (e.g.
+     * `data:application/vnd...;base64,...`), suitable for download or
+     * open-in-new-tab. For a generic "Package" OLE object this is the unwrapped
+     * inner file; for a plain embedded file (e.g. `.xlsx`) it is that file
+     * directly. Undefined when the embedding is missing or unreadable.
+     *
+     * Stored as a data-URL string to mirror how images store decoded bytes
+     * ({@link ImagePptxElement.imageData}) and to stay serialization-safe.
+     */
+    oleEmbeddedData?: string;
+    /** Original file name of the embedded payload when recoverable. */
+    oleEmbeddedFileName?: string;
+    /** MIME type of the embedded payload, derived from its extension/ProgID. */
+    oleEmbeddedMimeType?: string;
+    /** Size of the embedded payload in bytes. */
+    oleEmbeddedByteSize?: number;
+    /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
+    extensionXml?: PptxGraphicFrameExtension[];
+}
+/**
+ * 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;
+    mediaReferenceKind?: PptxMediaReferenceKind;
+    mediaReferenceName?: string;
+    audioCdStart?: PptxAudioCdPosition;
+    audioCdEnd?: PptxAudioCdPosition;
+    rawMediaReferenceXml?: XmlObject;
+    /** 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;
+    /**
+     * Whether the media is linked (external `r:link`) rather than embedded
+     * (`r:embed`). Defaults to embedded when undefined.
+     */
+    isLinked?: boolean;
+    /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
+    extensionXml?: PptxGraphicFrameExtension[];
+}
+/**
+ * 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[][];
+    /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
+    extensionXml?: PptxGraphicFrameExtension[];
+}
+/**
+ * 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).
  *
- * - **Attributes** — keys matching `` `@_${string}` `` return
- *   `string | undefined` directly.
- * - **Text content** — `#text` returns `string | undefined`.
- * - **Child elements** — any other string key returns
- *   `XmlObject | XmlObject[] | string | undefined`. The union reflects that
- *   fast-xml-parser may emit an object (single child), an array (repeated
- *   children), or a bare string (text-only element collapsed by the parser).
+ * Zoom elements display a live thumbnail of the target slide and
+ * navigate to it on click during presentation mode.
  *
- * For traversal, prefer the helpers in {@link ./../utils/xml-access} —
- * `xmlChild` / `xmlChildren` / `xmlAttr` / `xmlText` / `xmlPath` — which
- * narrow the union and normalize the single-vs-array duality. Direct
- * indexing works for attributes (typed as string) but chained child access
- * (`obj['p:spPr']?.['a:xfrm']`) requires the helpers or a narrowing cast
- * because TypeScript cannot index into the `XmlObject[] | string` part of
- * the union.
+ * @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 XmlObject {
-    /** Attributes (`@_`-prefixed keys) are always strings at runtime. */
-    [attr: `@_${string}`]: string | undefined;
-    /** Element text content surfaces under `#text` when present. */
-    '#text'?: string;
+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;
+    /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
+    extensionXml?: PptxGraphicFrameExtension[];
+}
+/** An element whose type is not recognised by the parser. */
+interface UnknownPptxElement extends PptxElementBase {
+    type: 'unknown';
+    /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
+    extensionXml?: PptxGraphicFrameExtension[];
+}
+/**
+ * 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;
+/**
+ * Per-part header/footer flags from `<p:hf>` (CT_HeaderFooter, ECMA-376
+ * §19.3.1.21). Defaults are "all true" — fields are only set on the typed
+ * model when they were explicitly read, so callers can distinguish "unset"
+ * (preserve original XML) from "false" (override).
+ */
+interface PptxHeaderFooterFlags {
+    /** `@hdr` — show header placeholder. Spec default: `true`. */
+    hasHeader?: boolean;
+    /** `@ftr` — show footer placeholder. Spec default: `true`. */
+    hasFooter?: boolean;
+    /** `@dt` — show date/time placeholder. Spec default: `true`. */
+    hasDateTime?: boolean;
+    /** `@sldNum` — show slide-number placeholder. Spec default: `true`. */
+    hasSlideNumber?: boolean;
+}
+
+/**
+ * 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';
+/**
+ * Native animation kind. The historic shape-targeted preset animations are
+ * implicitly the default kind (`undefined`). Media animations (`p:audio`,
+ * `p:video`) emit dedicated entries so playback order on the slide timeline
+ * is preserved alongside other animations.
+ */
+type PptxNativeAnimationKind = 'media';
+/** A target selected by `p:tgtEl` in the PresentationML timing model. */
+type PptxAnimationTarget = {
+    type: 'shape';
+    shapeId: string;
+    rawXml?: XmlObject;
+} | {
+    type: 'slide';
+    rawXml?: XmlObject;
+} | {
+    type: 'sound';
+    relationshipId: string;
+    name?: string;
+    rawXml?: XmlObject;
+} | {
+    type: 'ink';
+    shapeId: string;
+    rawXml?: XmlObject;
+} | {
+    type: 'unknown';
+    rawXml: XmlObject;
+};
+/** Nested build choice carried by `p:bldGraphic`. */
+type PptxGraphicBuild = {
+    mode: 'asOne';
+    rawXml?: XmlObject;
+} | {
+    mode: 'sub';
+    kind: 'diagram';
+    build: string;
+    reverse: boolean;
+    rawXml?: XmlObject;
+} | {
+    mode: 'sub';
+    kind: 'chart';
+    build: string;
+    animateBackground: boolean;
+    rawXml?: XmlObject;
+};
+/**
+ * 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;
+    /** Full timing target, including sound and ink target variants. */
+    target?: PptxAnimationTarget;
+    /** 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;
+    /** Path edit mode from `p:animMotion/@pathEditMode` (e.g. "relative", "fixed"). */
+    motionPathEditMode?: string;
+    /** Comma-separated point-types string from `p:animMotion/@ptsTypes`. */
+    motionPtsTypes?: string;
+    /** Rotation angle in degrees for `p:animRot/@by` (converted from 60000ths). */
+    rotationBy?: number;
+    /** Starting rotation angle in degrees for `p:animRot/@from` (converted from 60000ths). */
+    rotationFrom?: number;
+    /** Ending rotation angle in degrees for `p:animRot/@to` (converted from 60000ths). */
+    rotationTo?: number;
+    /** X scale factor (percentage / 100) for `p:animScale/p:by/@x`. */
+    scaleByX?: number;
+    /** Y scale factor (percentage / 100) for `p:animScale/p:by/@y`. */
+    scaleByY?: number;
+    /** Starting X scale factor for `p:animScale/p:from/@x`. */
+    scaleFromX?: number;
+    /** Starting Y scale factor for `p:animScale/p:from/@y`. */
+    scaleFromY?: number;
+    /** Ending X scale factor for `p:animScale/p:to/@x`. */
+    scaleToX?: number;
+    /** Ending Y scale factor for `p:animScale/p:to/@y`. */
+    scaleToY?: number;
+    /** Whether `p:animScale/@zoomContents` was set ("1"/"true"). */
+    scaleZoomContents?: boolean;
+    /** Parsed `p:tav` keyframes from `p:tavLst` (CT_TLAnimVariantList). */
+    keyframes?: PptxAnimationKeyframe[];
+    /** 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;
     /**
-     * Child elements keyed by their (namespaced) tag name. fast-xml-parser
-     * emits a single object for unique elements, an array for repeated ones,
-     * and a bare string for elements collapsed to their text content. Use
-     * the helpers in `utils/xml-access` to narrow this union.
+     * Discriminator for non-preset animation kinds. When `undefined`, the
+     * entry represents the default shape-effect animation. The `'media'`
+     * kind represents a `p:audio` / `p:video` timing node, captured here so
+     * playback order in the timeline is preserved alongside other animations.
      */
-    [child: string]: XmlObject | XmlObject[] | string | undefined;
+    kind?: PptxNativeAnimationKind;
+    /**
+     * For `kind === 'media'`, identifies whether this is an audio or video
+     * media node so writers know which OOXML element to re-emit.
+     */
+    mediaType?: 'audio' | 'video';
+    /**
+     * SmartArt build attribute (`p:bldDgm/@bld`) when this animation is
+     * associated with a SmartArt diagram build. Common values include
+     * `whole`, `one`, `lvlOne`, `lvlAtOnce`.
+     */
+    smartArtBuild?: string;
+    /**
+     * Graphic-frame build attribute (`p:bldGraphic/@bld`) when this animation
+     * is associated with a generic graphic frame build (charts, tables, etc.
+     * that aren't OLE charts).
+     */
+    graphicBuild?: string;
+    /** Schema-accurate `p:bldGraphic/p:bldAsOne|p:bldSub` representation. */
+    graphicBuildProperties?: PptxGraphicBuild;
+    /**
+     * Opaque map of `p:cTn` attributes that don't have a typed home on this
+     * interface but must round-trip through parse → save. Keys are stored
+     * verbatim including the `@_` prefix used by the underlying XML parser
+     * (e.g. `@_evtFilter`, `@_display`, `@_masterRel`, `@_nodePh`,
+     * `@_endSync`, `@_progress`). The `subTnLst` child element is also
+     * preserved here under the literal key `p:subTnLst`. The `afterEffect`
+     * attribute is surfaced separately as a typed boolean ({@link afterEffect})
+     * because it changes write semantics for subsequent timing nodes.
+     */
+    cTnAttributes?: Record<string, unknown>;
+    /**
+     * Whether the OOXML `p:cTn/@afterEffect` flag is set. Indicates this node
+     * runs after the parent effect's main body has completed; affects how
+     * subsequent peer nodes are sequenced when serialised back to OOXML.
+     */
+    afterEffect?: boolean;
+}
+/**
+ * Single keyframe parsed from a `p:tav` element (CT_TLTimeAnimateValue).
+ *
+ * Each entry in a `p:tavLst` has a time fraction (`@_tm`, in 1000ths of the
+ * total duration; or the literal "indefinite" / "large") and a typed value
+ * child under `p:val/p:strVal|p:boolVal|p:intVal|p:fltVal|p:clrVal`.
+ *
+ * @see ECMA-376 §19.5.30 CT_TLAnimVariantList / §19.5.92 CT_TLTimeAnimateValue
+ */
+interface PptxAnimationKeyframe {
+    /**
+     * Time fraction. A finite number is the OOXML `@_tm` integer (0–100000
+     * for percentage, where 100000 = 100% of duration). A string preserves
+     * special tokens ("indefinite", "large").
+     */
+    tm: number | string;
+    /** Decoded keyframe value. */
+    value: string | boolean | number;
+    /** Discriminant indicating which `p:val` child carried the value. */
+    valueType: 'str' | 'bool' | 'int' | 'flt' | 'clr';
+    /**
+     * Optional formula carried on `p:tav/@_fmla`. Preserved for round-trip
+     * fidelity; consumers may use it to drive computed animation values.
+     */
+    fmla?: string;
+}
+/** 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';
+    /**
+     * Optional `p:animClr/@path` value preserved for round-trip. When set,
+     * the colour sweep follows a path-based interpolation rather than the
+     * straight cw/ccw arc. ECMA-376 §19.5.13 documents this attribute as a
+     * companion to `@dir` for HSL colour-space animations.
+     */
+    path?: string;
+    /** Starting color as hex string. */
+    fromColor?: string;
+    /** Ending color as hex string. */
+    toColor?: string;
+    /**
+     * Color delta (for "by" animations) as hex string. For HSL colour-space
+     * animations the value encodes a delta over hue/sat/lum and is preserved
+     * verbatim from the source.
+     */
+    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;
+    /** Full target choice, including `p:sndTgt` and `p:inkTgt`. */
+    target?: PptxAnimationTarget;
+}
+/** 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;
+    /**
+     * Path edit mode for `p:animMotion/@pathEditMode`. Defaults to "relative"
+     * when emitted without an explicit value.
+     */
+    motionPathEditMode?: string;
+    /** Comma-separated point-types string for `p:animMotion/@ptsTypes`. */
+    motionPtsTypes?: 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;
 }
 
 /**
- * Image types: effects, crop shapes, and properties shared by image/picture
- * elements.
+ * Metadata types: slide comments, compatibility warnings, tags,
+ * custom properties, core/app document properties.
  *
- * @module pptx-types/image
+ * @module pptx-types/metadata
  */
+
 /**
- * Blend mode for `a:blend` container nodes inside an `a:effectDag` (CT_BlendEffect).
+ * A slide comment — may be a legacy positional comment or a modern
+ * threaded comment with replies.
  *
- * Per ECMA-376 §20.1.8.10, valid values are: `darken`, `lighten`, `mult`,
- * `over`, `screen`.
+ * @example
+ * ```ts
+ * const comment: PptxComment = {
+ *   id: "c1",
+ *   text: "Please update this chart.",
+ *   author: "Alice",
+ *   createdAt: "2024-06-01T10:00:00Z",
+ *   resolved: false,
+ * };
+ * // => satisfies PptxComment
+ * ```
  */
-type EffectDagBlendMode = 'darken' | 'lighten' | 'mult' | 'over' | 'screen';
+interface PptxComment {
+    id: string;
+    text: string;
+    /** Storage vocabulary used by this comment. Omitted means legacy PresentationML. */
+    format?: 'legacy' | 'modern';
+    /** Stable GUID author identifier used by Office 2021 modern comments. */
+    authorId?: 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;
+    /** Native p188 status token. */
+    status?: 'active' | 'resolved' | 'closed';
+    /** Modern comment classification tags and author IDs that liked the comment. */
+    tags?: string[];
+    likes?: string[];
+    startDate?: string;
+    dueDate?: string;
+    assignedTo?: string[];
+    /** Task completion in thousandths of a percent, from 0 through 100000. */
+    complete?: number;
+    priority?: number;
+    title?: string;
+    /** 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;
+    /** Original `p:cm` subtree, retained for unknown child and extension preservation. */
+    rawXml?: XmlObject;
+}
 /**
- * Container node kind inside an `a:effectDag` (CT_EffectContainer @type).
+ * A compatibility warning generated during parse or save when the
+ * file uses features not fully supported by the editor.
  *
- * Per ECMA-376 §20.1.8.20, `sib` (sibling) draws each child independently
- * over the same source; `tree` (tree) chains effects so each sees the output
- * of its siblings.
+ * @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
+ * ```
  */
-type EffectDagContainerType = 'sib' | 'tree';
+interface PptxCompatibilityWarning {
+    code: string;
+    message: string;
+    severity: 'info' | 'warning';
+    scope: 'presentation' | 'slide' | 'element' | 'save';
+    slideId?: string;
+    elementId?: string;
+    xmlPath?: string;
+}
+
 /**
- * Typed model of the directed-acyclic effect graph stored in `a:effectDag`.
+ * Slide transition types and the {@link PptxSlideTransition} data structure.
  *
- * The four "structural" container/transform nodes are typed; any other inner
- * effect (e.g. `a:outerShdw`, `a:glow`, `a:alphaInv`) is preserved verbatim
- * as a raw XML object via the {@link EffectDagRawLeaf} variant so we never
- * have to recurse into the full effect taxonomy.
+ * 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' | 'cube' | 'flip' | 'rotate' | 'orbit';
+/** Split orientation from OOXML `@_orient`. */
+type PptxSplitOrientation = 'horz' | 'vert';
+/** Schema-defined `ST_TransitionSpeed` values. */
+type PptxTransitionSpeed = 'slow' | 'med' | 'fast';
+/**
+ * Slide transition configuration.
  *
  * @example
  * ```ts
- * // <a:effectDag>
- * //   <a:cont type="sib">
- * //     <a:blend blend="mult"><a:cont type="tree" /></a:blend>
- * //   </a:cont>
- * // </a:effectDag>
- * const dag: EffectDagContainer = {
- *   kind: "cont",
- *   type: "sib",
- *   children: [{
- *     kind: "blend",
- *     mode: "mult",
- *     container: { kind: "cont", type: "tree", children: [] },
- *   }],
+ * const transition: PptxSlideTransition = {
+ *   type: "fade",
+ *   durationMs: 700,
+ *   advanceOnClick: true,
+ *   advanceAfterMs: 5000,
  * };
+ * // => { type: "fade", durationMs: 700, advanceOnClick: true, advanceAfterMs: 5000 }
  * ```
  */
-type EffectDagNode = EffectDagContainer | EffectDagBlend | EffectDagXfrm | EffectDagRelOff | EffectDagRawLeaf;
-/** `a:cont` — CT_EffectContainer. Recursive; mirrors the top-level `effectDag`. */
-interface EffectDagContainer {
-    kind: 'cont';
-    /** `@type` — `sib` or `tree`. */
-    type: EffectDagContainerType;
-    /** Optional `@name` attribute. */
-    name?: string;
-    /** Ordered children. */
-    children: EffectDagNode[];
+interface PptxSlideTransition {
+    type: PptxTransitionType;
+    /** Schema-defined transition speed. Defaults to `fast` when omitted. */
+    speed?: PptxTransitionSpeed;
+    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;
+    /** Embedded WAV display name from `p:stSnd/p:snd/@name`. */
+    soundName?: string;
+    /** Whether the transition sound repeats until another sound starts. */
+    soundLoop?: boolean;
+    /** Resolved transition sound media path within the package. */
+    soundPath?: string;
+    /** Human-readable sound file name (extracted from soundPath). */
+    soundFileName?: string;
+    /**
+     * When true, the transition stops the currently-playing sound (OOXML `p:sndAc/p:endSnd`).
+     * Mutually exclusive with `soundRId`/`soundPath` (which use `p:stSnd`).
+     */
+    stopSound?: boolean;
+    /** 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;
+    /** Original transition node, retained to preserve unknown attributes and children. */
+    rawTransition?: XmlObject;
 }
-/** `a:blend` — CT_BlendEffect. Always wraps a single `a:cont` child. */
-interface EffectDagBlend {
-    kind: 'blend';
-    /** `@blend` attribute. */
-    mode: EffectDagBlendMode;
-    /** Required child `a:cont` container. */
-    container: EffectDagContainer;
+
+/**
+ * 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;
 }
-/** `a:xfrmEffect` — CT_TransformEffect. Affine transform with no children. */
-interface EffectDagXfrm {
-    kind: 'xfrmEffect';
-    /** Horizontal scale, percentage * 1000 (e.g. 100000 = 100%). */
-    sx?: number;
-    /** Vertical scale, percentage * 1000. */
-    sy?: number;
-    /** Horizontal skew, degrees * 60000. */
-    kx?: number;
-    /** Vertical skew, degrees * 60000. */
-    ky?: number;
-    /** Horizontal translation in EMU. */
-    tx?: number;
-    /** Vertical translation in EMU. */
-    ty?: number;
+/**
+ * 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:relOff` — CT_RelativeOffsetEffect. Relative offset in 1000ths of a percent. */
-interface EffectDagRelOff {
-    kind: 'relOff';
-    /** Horizontal offset, percentage * 1000. */
-    tx?: number;
-    /** Vertical offset, percentage * 1000. */
-    ty?: number;
+/**
+ * Pattern fill on a slide background.
+ *
+ * Mirrors the `<a:pattFill>` choice inside `<p:bgPr>`. Renderers should
+ * draw a 2-colour preset pattern (e.g. `dkDnDiag`, `pct50`).
+ *
+ * ECMA-376 §20.1.8.47.
+ *
+ * @example
+ * ```ts
+ * const pattern: PptxSlideBackgroundPattern = {
+ *   preset: "ltDnDiag",
+ *   fgColor: "#4472C4",
+ *   bgColor: "#FFFFFF",
+ * };
+ * // => satisfies PptxSlideBackgroundPattern
+ * ```
+ */
+interface PptxSlideBackgroundPattern {
+    /** DrawingML preset pattern token (`@_prst`). */
+    preset: string;
+    /** Foreground colour resolved to `#RRGGBB`. */
+    fgColor?: string;
+    /** Background colour resolved to `#RRGGBB`. */
+    bgColor?: string;
 }
 /**
- * Catch-all leaf preserving any non-container effect (e.g. `a:outerShdw`,
- * `a:glow`, `a:alphaInv`) as raw XML. Re-emitted verbatim on save.
+ * 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 EffectDagRawLeaf {
-    kind: 'raw';
-    /** Local element name without the `a:` prefix (e.g. `outerShdw`, `glow`). */
-    tag: string;
-    /** Raw XML object captured at load — preserved verbatim on save. */
-    xml: Record<string, unknown>;
+interface PptxSlide {
+    id: string;
+    rId: string;
+    sourceSlideId?: string;
+    /** Optional author-supplied slide name (set via `SlideBuilder.setName`). */
+    name?: string;
+    layoutPath?: string;
+    layoutName?: string;
+    slideNumber: number;
+    hidden?: boolean;
+    sectionName?: string;
+    sectionId?: string;
+    elements: PptxElement[];
+    backgroundColor?: string;
+    backgroundImage?: string;
+    backgroundGradient?: string;
+    /**
+     * Pattern fill on the slide background (`<a:pattFill>` inside `<p:bgPr>`).
+     *
+     * When present, renderers should draw a real two-colour pattern using
+     * the named DrawingML preset (e.g. `"ltDnDiag"`, `"pct50"`). The flat
+     * `backgroundColor` field is left set to the foreground colour for
+     * fallback rendering paths that don't understand patterns.
+     *
+     * ECMA-376 §20.1.8.47.
+     */
+    backgroundPattern?: PptxSlideBackgroundPattern;
+    /**
+     * `<p:bgPr/@shadeToTitle>` — boolean flag instructing the renderer to
+     * shade the background toward the title placeholder colour. Captured
+     * for lossless round-trip; the React renderer currently treats it as
+     * a passthrough hint.
+     *
+     * ECMA-376 §19.3.1.2 (CT_BackgroundProperties).
+     */
+    backgroundShadeToTitle?: boolean;
+    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[];
+    /**
+     * Parsed shapes from the notes slide's `<p:cSld>/<p:spTree>` so the full
+     * notes-page shape tree can be inspected and mutated, not just the body
+     * placeholder text. When undefined, the existing notes XML is left
+     * untouched on save and only `notes` / `notesSegments` are written.
+     */
+    notesShapes?: PptxElement[];
+    /**
+     * Per-notes-slide colour map override parsed from `<p:notes>/<p:clrMapOvr>`.
+     * Captured for lossless round-trip of the notes-slide's colour scheme.
+     */
+    notesClrMapOverride?: Record<string, string>;
+    /** Optional `<p:cSld @name>` value of the notes slide, for round-trip. */
+    notesCSldName?: string;
+    comments?: PptxComment[];
+    /** Source package metadata for an Office 2021 p188 comment part. */
+    modernCommentPart?: PptxModernCommentPart;
+    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[];
+    /** Per-slide header/footer flags from `<p:hf>` (P-H3). */
+    headerFooterFlags?: PptxHeaderFooterFlags;
+    /** Server-backed slide synchronization metadata stored in a related OPC part. */
+    slideSynchronization?: PptxSlideSyncProperties;
 }
-declare module "./index" {
-    interface TextStyle {
-        /**
-         * Raw `a:effectDag` XML node from `a:rPr`, preserved verbatim for
-         * round-trip serialisation. Mirrors the shape-level
-         * {@link import('./shape-style').ShapeStyle.effectDagXml} field.
-         */
-        textEffectDagXml?: XmlObject;
-        /**
-         * Typed effect graph parsed from `textEffectDagXml`. The four structural
-         * container nodes (`a:cont`, `a:blend`, `a:xfrmEffect`, `a:relOff`) are
-         * fully typed; any other leaf effect is captured as
-         * {@link EffectDagRawLeaf} so we never have to recurse into the full
-         * effect taxonomy.
-         */
-        textEffectDagTree?: EffectDagContainer;
-    }
+interface PptxModernCommentPart {
+    path: string;
+    relationshipId: string;
+    /** Original p188:cmLst root, including unknown attributes and extensions. */
+    rawXml?: XmlObject;
 }
-declare module "./index" {
-    interface ShapeStyle {
-        /**
-         * Typed effect graph parsed from {@link ShapeStyle.effectDagXml}. The four
-         * structural container nodes (`a:cont`, `a:blend`, `a:xfrmEffect`,
-         * `a:relOff`) are fully typed; any other leaf effect (e.g. `a:outerShdw`,
-         * `a:glow`, `a:alphaInv`) is captured as {@link EffectDagRawLeaf} so we
-         * never have to recurse into the full effect taxonomy.
-         */
-        effectDagTree?: EffectDagContainer;
-    }
+/** Metadata from a `p:sldSyncPr` slide synchronization data part. */
+interface PptxSlideSyncProperties {
+    serverSlideId: string;
+    serverSlideModifiedTime: string;
+    clientInsertedTime: string;
+    extensionList?: XmlObject;
+    rawXml?: XmlObject;
+    partPath?: string;
+    relationshipId?: string;
 }
 
 /**
@@ -307,6 +4720,102 @@ interface CanvasSize {
     width: number;
     height: number;
 }
+/** Viewer interaction mode: read-only, edit, presentation, or master-view. */
+type ViewerMode = 'preview' | 'edit' | 'present' | 'master';
+/**
+ * Framework-agnostic imperative API contract for the PowerPoint viewer.
+ *
+ * Each binding (React `forwardRef` handle, Vue `defineExpose`, Angular public
+ * methods) implements this interface so consumers get a consistent progressive
+ * API regardless of framework.
+ */
+interface PowerPointViewerAPI {
+    /** Serialise the current presentation to `.pptx` bytes. */
+    getContent: () => Promise<Uint8Array>;
+    /** Navigate to a specific slide by zero-based index. */
+    goTo: (slideIndex: number) => void;
+    /** Navigate to the previous slide. */
+    goPrev: () => void;
+    /** Navigate to the next slide. */
+    goNext: () => void;
+    /** Undo the last editing action. No-op when nothing to undo. */
+    undo: () => void;
+    /** Redo the last undone action. No-op when nothing to redo. */
+    redo: () => void;
+    /** Whether an undo action is available. */
+    canUndo: () => boolean;
+    /** Whether a redo action is available. */
+    canRedo: () => boolean;
+    /** Get the current zoom level (1 = 100%). */
+    getZoom: () => number;
+    /** Set the zoom level (clamped to min/max bounds). */
+    setZoom: (level: number) => void;
+    /** Zoom in by one step. */
+    zoomIn: () => void;
+    /** Zoom out by one step. */
+    zoomOut: () => void;
+    /** Reset zoom to 100%. */
+    zoomReset: () => void;
+    /** Get the current viewer mode. */
+    getMode: () => ViewerMode;
+    /** Switch the viewer mode (e.g. 'edit', 'preview', 'present'). */
+    setMode: (mode: ViewerMode) => void;
+    /** Get the zero-based active slide index. */
+    getActiveSlideIndex: () => number;
+    /** Set the active slide by zero-based index (alias of goTo). */
+    setActiveSlideIndex: (index: number) => void;
+    /** Get the total number of slides. */
+    getSlideCount: () => number;
+    /** Whether the document has unsaved changes. */
+    isDirty: () => boolean;
+    /**
+     * Get the full slide array. Returns the actual `PptxSlide[]` from the
+     * internal model with full type information (elements, notes, transitions,
+     * animations, etc.). The returned reference is a snapshot; mutations are
+     * not reflected back unless done via the manipulation methods.
+     */
+    getSlides: () => readonly PptxSlide[];
+    /** Get a single slide by zero-based index, or undefined if out of range. */
+    getSlide: (index: number) => PptxSlide | undefined;
+    /** Get the currently active slide. */
+    getActiveSlide: () => PptxSlide | undefined;
+    /** Add a blank slide after the given index (or at end if omitted). */
+    addSlide: (afterIndex?: number) => void;
+    /** Delete slides at the given zero-based indexes. At least one slide is kept. */
+    deleteSlides: (indexes: number[]) => void;
+    /** Duplicate slides at the given zero-based indexes. */
+    duplicateSlides: (indexes: number[]) => void;
+    /** Move a slide from one position to another. */
+    moveSlide: (fromIndex: number, toIndex: number) => void;
+    /** Toggle the hidden flag on slides at the given indexes. */
+    toggleHideSlides: (indexes: number[]) => void;
+    /**
+     * Get the elements on a slide. Defaults to the active slide when
+     * `slideIndex` is omitted. Returns the full `PptxElement[]` with
+     * all type-specific properties intact.
+     */
+    getElements: (slideIndex?: number) => readonly PptxElement[];
+    /** Get a single element by ID from the active slide (or a specified slide). */
+    getElementById: (elementId: string, slideIndex?: number) => PptxElement | undefined;
+    /**
+     * Update one or more properties of an element by ID on the active slide.
+     * Accepts a `Partial<PptxElement>` patch (e.g. `{ x: 100, width: 300 }`).
+     */
+    updateElement: (elementId: string, updates: Partial<PptxElement>) => void;
+    /** Delete elements by their IDs from the active slide. */
+    deleteElements: (elementIds: string[]) => void;
+    /**
+     * Duplicate an element on the active slide.
+     * Returns the new element's ID, or undefined if the source was not found.
+     */
+    duplicateElement: (elementId: string) => string | undefined;
+    /** Get the IDs of currently selected elements. */
+    getSelectedElementIds: () => string[];
+    /** Programmatically select elements by their IDs. */
+    selectElements: (ids: string[]) => void;
+    /** Clear the current selection. */
+    clearSelection: () => void;
+}
 /** Collaboration role within a session. */
 type CollaborationRole = 'owner' | 'collaborator' | 'viewer';
 /**
@@ -319,10 +4828,12 @@ type CollaborationRole = 'owner' | 'collaborator' | 'viewer';
  *   any signaling server, which makes this mode usable from static hosting.
  */
 type CollaborationTransport = 'websocket' | 'webrtc';
+/** How the local user entered a collaboration session. */
+type CollaborationSessionIntent = 'create' | 'join';
 /**
  * Real-time collaboration configuration.
  *
- * The same shape is accepted by the React, Vue, and Angular bindings.
+ * The same shape is accepted by every framework binding.
  */
 interface CollaborationConfig {
     /** Unique identifier for the collaboration room (alphanumeric, hyphens, underscores). */
@@ -350,6 +4861,13 @@ interface CollaborationConfig {
     authToken?: string;
     /** Role in the session; defaults to `'collaborator'`. */
     role?: CollaborationRole;
+    /**
+     * Whether this client created the room or joined an existing room. Providers
+     * do not use this value, but hosts can use it to avoid publishing local file
+     * bytes when handling a join request. Omitted values retain the legacy
+     * create-session behaviour.
+     */
+    sessionIntent?: CollaborationSessionIntent;
     /**
      * Elected-writer write-back callback (Area 3 of the C3 hardening plan).
      *
@@ -367,6 +4885,19 @@ interface CollaborationConfig {
      */
     writeBackDebounceMs?: number;
 }
+/**
+ * A font supplied by the host application. The package never ships fonts:
+ * applications provide a licensed URL, data URL, or blob URL for their users.
+ */
+interface ViewerFontSource {
+    family: string;
+    src: string;
+    format?: 'truetype' | 'opentype' | 'woff' | 'woff2';
+    weight?: string | number;
+    style?: 'normal' | 'italic';
+}
+declare function parsePresentationSessionId(hash: string): string | null;
+declare function loadPresentationDeck(sessionId: string): Promise<Uint8Array | null>;
 interface AutosaveRecord {
     key: string;
     data: Uint8Array;
@@ -557,6 +5088,8 @@ interface ViewerLoadDetail {
 interface PowerPointViewerProps {
     /** PowerPoint content as `Uint8Array` (or `ArrayBuffer`). */
     source: Uint8Array | ArrayBuffer | null | undefined;
+    /** Licensed font sources supplied by the host application. */
+    fonts?: ViewerFontSource[];
     /**
      * Theme configuration for customising the viewer's appearance. Accepts
      * partial color overrides, a custom border-radius, and arbitrary CSS
@@ -617,6 +5150,15 @@ interface PowerPointViewerProps {
      * to track the dirty state or mirror edits into host state.
      */
     onchange?: () => void;
+    /** Canonical viewer contract callbacks. */
+    ondirtychange?: (dirty: boolean) => void;
+    oncontentchange?: (content: Uint8Array) => void;
+    onmodechange?: (mode: string) => void;
+    onzoomchange?: (zoom: number) => void;
+    onselectionchange?: (elementIds: string[]) => void;
+    onslidecountchange?: (count: number) => void;
+    /** Host override for the File > Open action. */
+    onopenfile?: () => void;
     /**
      * Enable debounced crash-recovery autosave. On each edit (when `editable`)
      * the current slides are serialized to `.pptx` bytes and written to the
@@ -668,7 +5210,7 @@ interface PowerPointViewerProps {
  * instance (via `bind:this`). Mirrors the vanilla binding's `EditorController`
  * surface subset the host drives directly.
  */
-interface PowerPointViewerApi {
+interface PowerPointViewerApi extends PowerPointViewerAPI {
     /** Undo the last committed edit. */
     undo(): void;
     /** Redo the last undone edit. */
@@ -761,5 +5303,5 @@ declare const PowerPointViewer: Component<PowerPointViewerProps, PowerPointViewe
  */
 type AutosaveStatus = 'idle' | 'disabled' | 'saving' | 'saved' | 'error';
 
-export { PowerPointViewer, defaultCssVars, defaultRadius, defaultThemeColors, deleteAutosaveSnapshot, getAutosaveSnapshot, listAutosaveSnapshots, registerTranslations, themeToCssVars, vermilionDarkColors, vermilionDarkTheme, vermilionLightColors, vermilionLightTheme, vermilionRadius };
+export { PowerPointViewer, defaultCssVars, defaultRadius, defaultThemeColors, deleteAutosaveSnapshot, getAutosaveSnapshot, listAutosaveSnapshots, loadPresentationDeck, parsePresentationSessionId, registerTranslations, themeToCssVars, vermilionDarkColors, vermilionDarkTheme, vermilionLightColors, vermilionLightTheme, vermilionRadius };
 export type { AutosaveRecord, AutosaveStatus, CanvasSize, CollaborationConfig, CollaborationRole, CollaborationTransport, ExportGifOptions, ExportPdfOptions, ExportVideoOptions, PowerPointViewerApi, PowerPointViewerProps, PrintOptions, TranslationDictionary, Translator, ViewerLoadDetail, ViewerTheme, ViewerThemeColors };