ooxml-core 1.9.0 → 1.11.0

package/dist/pptx/chunks/text-operations-CyMTMfID.d.ts

@@ -0,0 +1,3261 @@
+import { k as XmlObject, r as TextSegment, v as Pptx3DScene, w as PptxDrawingGuide, y as Pptx3DShape } from "./text-D49FKllA.js";
+import { t as PptxThemeColorRef } from "./color-ref-DT599vEx.js";
+import { F as PlaceholderTextLevelStyle, Ln as PptxImageProperties, m as PptxElement, rt as ParsedTableStyleMap } from "./elements-DD3UGOMd.js";
+//#region pptx/core/types/transition.d.ts
+/**
+ * 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' | 'box' | 'orbit' | 'fallOver' | 'drape' | 'curtains' | 'wind' | 'prestige' | 'fracture' | 'crush' | 'peelOff' | 'pageCurlDouble' | 'pageCurlSingle' | 'airplane' | 'origami';
+/** Cardinal direction tokens from OOXML transition `@_dir`. */
+type PptxTransitionDirection4 = 'l' | 'r' | 'u' | 'd';
+/** 8-way direction tokens (cardinal + diagonal) for cover/uncover. */
+type PptxTransitionDirection8 = PptxTransitionDirection4 | 'lu' | 'ld' | 'ru' | 'rd';
+/** Strip direction tokens from OOXML. */
+type PptxStripDirection = 'lu' | 'ld' | 'ru' | 'rd';
+/** Split orientation from OOXML `@_orient`. */
+type PptxSplitOrientation = 'horz' | 'vert';
+/** Split in/out direction from OOXML `@_dir`. */
+type PptxSplitDirection = 'in' | 'out';
+/** Schema-defined `ST_TransitionSpeed` values. */
+type PptxTransitionSpeed = 'slow' | 'med' | 'fast';
+/**
+ * Valid direction sets per transition type.
+ *
+ * The p14 (Office 2010+) and p15 (Office 2013+) entries below are COM-verified:
+ * each direction token was confirmed by enumerating PowerPoint's own
+ * `PpEntryEffect` constants (reflected off the installed
+ * `Microsoft.Office.Interop.PowerPoint` type library) and reading back the
+ * `p:transition` XML PowerPoint itself saved for each one, exactly like the
+ * `p14-prism-family` and `P15_INVX_PRESETS` measurements. Two findings that
+ * contradict the naive "4-way cardinal for every named Left/Up/Right/Down
+ * effect" assumption:
+ *  - `switch` and `flip` each expose four named directions in PowerPoint's UI
+ *    (Left/Up/Right/Down), but the saved XML only ever carries `dir="l"` or
+ *    `dir="r"`: Up and Down both collapse to `dir="r"` on save. Modelling them
+ *    as 4-way here would offer a picker button PowerPoint itself cannot
+ *    persist.
+ *  - `ripple`'s only named directions are the four DIAGONALS (`lu`/`ld`/`ru`/
+ *    `rd`, PowerPoint's "Ripple" gallery calls them Left-Up/Left-Down/etc.);
+ *    there is no cardinal `l`/`r`/`u`/`d` variant, and the unset default is a
+ *    fifth "From Center" state with no `dir` attribute at all.
+ */
+declare const TRANSITION_VALID_DIRECTIONS: Readonly<Partial<Record<PptxTransitionType, readonly string[]>>>;
+/**
+ * Transition types offering a "Pattern" effect option alongside direction
+ * (COM-verified via `p14:glitter/@pattern` and `p14:shred/@pattern`).
+ */
+declare const TRANSITION_PATTERN_OPTIONS: Readonly<Partial<Record<PptxTransitionType, readonly string[]>>>;
+/**
+ * Transition types offering the "Through Black" checkbox
+ * (OOXML `@_thruBlk`, `CT_OptionalBlackTransition`). COM-verified: enumerating
+ * every `PpEntryEffect` constant found a dedicated black variant only for
+ * `Cut` (`ppEffectCutThroughBlack`) and the legacy `Fade` entry (`ppEffectFade`,
+ * as opposed to the newer non-black `ppEffectFadeSmoothly`); no Blinds/
+ * Checkerboard "through black" `PpEntryEffect` constant exists despite the
+ * `thruBlk` attribute being generically parseable off any standard transition
+ * child.
+ */
+declare const TRANSITION_THRUBLK_TYPES: ReadonlySet<PptxTransitionType>;
+/**
+ * Slide transition configuration.
+ *
+ * @example
+ * ```ts
+ * const transition: PptxSlideTransition = {
+ *   type: "fade",
+ *   durationMs: 700,
+ *   advanceOnClick: true,
+ *   advanceAfterMs: 5000,
+ * };
+ * // => { type: "fade", durationMs: 700, advanceOnClick: true, advanceAfterMs: 5000 }
+ * ```
+ */
+/**
+ * Morph granularity (`<p159:morph @option>`).
+ *
+ * - `byObject`  - match whole shapes (PowerPoint's default)
+ * - `byWord`    - additionally morph text word by word
+ * - `byChar`    - additionally morph text character by character
+ */
+type PptxMorphOption = 'byObject' | 'byWord' | 'byChar';
+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 (OOXML `@_thruBlk`). COM-verified to actually apply to
+   * `cut` and `fade` (see {@link TRANSITION_THRUBLK_TYPES}); parsed generically
+   * off any standard transition child so an unexpected authored value still
+   * round-trips.
+   */
+  thruBlk?: boolean;
+  /** Split orientation (horz/vert) parsed from `@_orient`. */
+  orient?: PptxSplitOrientation;
+  /**
+   * Morph granularity from `<p159:morph @option>`: how finely PowerPoint
+   * matches content between the two slides. Only meaningful when
+   * {@link type} is `morph`; defaults to `byObject` when the attribute is
+   * absent, matching PowerPoint's own default.
+   */
+  morphOption?: PptxMorphOption;
+  /** 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, or set by the
+   * UI when a new file is picked, before it has a soundPath at all). */
+  soundFileName?: string;
+  /**
+   * A newly-picked local sound file awaiting embedding, as a `data:` URL.
+   * Set by the transitions ribbon's Sound picker (`applyTransitionSoundFile`
+   * in `pptx-viewer-shared`) when the user chooses a file that is not yet
+   * part of the package; mirrors `imageData`/`mediaData` on picture and media
+   * elements. The save pipeline (`embedTransitionSound`) writes the bytes to
+   * `ppt/media/`, mints a relationship, sets `soundRId`/`soundPath`, and
+   * clears this field so a later save does not re-embed the same bytes.
+   */
+  soundData?: 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;
+}
+//#endregion
+//#region pptx/core/types/animation-behavior.d.ts
+/** Timing of one behaviour, from its own `p:cBhvr/p:cTn`. */
+interface PptxAnimationBehaviorTiming {
+  /** The behavior's own fill, independent of its containing effect. */
+  fill?: 'remove' | 'freeze' | 'hold' | 'transition';
+  /** Preserved timing profile cannot be reduced to a finite delayed one-shot set. */
+  unsupportedSetTiming?: boolean;
+  /** `p:cTn/@dur` in ms; absent when `indefinite` or unset. */
+  durationMs?: number;
+  /** Start offset in ms from `p:stCondLst/p:cond/@delay`, relative to the effect start. */
+  delayMs?: number;
+  /** `p:cTn/@accel` as a 0..1 fraction of the behaviour's duration. */
+  accel?: number;
+  /** `p:cTn/@decel` as a 0..1 fraction of the behaviour's duration. */
+  decel?: number;
+  /** `p:cTn/@autoRev`: play forward, then backward, doubling the active time. */
+  autoReverse?: boolean;
+  /** `p:cTn/@repeatCount` in plain iterations (OOXML stores thousandths). */
+  repeatCount?: number;
+  /** `p:cTn/@tmFilter`: the raw `"t,v; t,v; ..."` time remapping list. */
+  tmFilter?: string;
+}
+interface BehaviorBase {
+  /** Lower-cased `p:attrNameLst` entries, in document order. */
+  attrNames: string[];
+  /** `p:cBhvr/@additive` (`base`, `sum`, `repl`, `mult`, `none`). */
+  additive?: string;
+  timing: PptxAnimationBehaviorTiming;
+}
+/** `p:set`: a discrete value held from the behaviour's start. */
+interface PptxSetBehavior extends BehaviorBase {
+  kind: 'set';
+  value: string | number | boolean;
+}
+/** `p:anim`: a `p:tavLst` ramp or a `from`/`to`/`by` formula ramp. */
+interface PptxAnimBehavior extends BehaviorBase {
+  kind: 'anim';
+  calcMode?: 'discrete' | 'lin' | 'fmla';
+  valueType?: string;
+  from?: string;
+  to?: string;
+  by?: string;
+  keyframes: PptxAnimationKeyframe[];
+}
+/** `p:animEffect`: a filter transition (`fade`, `wipe(down)`...). */
+interface PptxAnimEffectBehavior extends BehaviorBase {
+  kind: 'animEffect';
+  filter?: string;
+  transition?: 'in' | 'out' | 'none';
+}
+/** A `p:animScale` factor pair (1 = unscaled) or a `p:animMotion` offset (slide fractions). */
+interface PptxBehaviorPoint {
+  x: number;
+  y: number;
+}
+/** `p:animScale`: scale factors as fractions (OOXML stores percent*1000, so `100000` = 1). */
+interface PptxAnimScaleBehavior extends BehaviorBase {
+  kind: 'animScale';
+  from?: PptxBehaviorPoint;
+  to?: PptxBehaviorPoint;
+  by?: PptxBehaviorPoint;
+  zoomContents?: boolean;
+}
+/** `p:animRot`: rotation in degrees (OOXML stores 60000ths). */
+interface PptxAnimRotBehavior extends BehaviorBase {
+  kind: 'animRot';
+  from?: number;
+  to?: number;
+  by?: number;
+}
+/** `p:animMotion`: a path (slide fractions) or a `from`/`to`/`by` offset. */
+interface PptxAnimMotionBehavior extends BehaviorBase {
+  kind: 'animMotion';
+  path?: string;
+  origin?: string;
+  from?: PptxBehaviorPoint;
+  to?: PptxBehaviorPoint;
+  by?: PptxBehaviorPoint;
+}
+/** One behaviour child of an effect, tagged by its OOXML element. */
+type PptxAnimationBehavior = PptxSetBehavior | PptxAnimBehavior | PptxAnimEffectBehavior | PptxAnimScaleBehavior | PptxAnimRotBehavior | PptxAnimMotionBehavior;
+//#endregion
+//#region pptx/core/types/animation.d.ts
+/**
+ * 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' |
+/**
+ * Starts when a media element's playback reaches a named bookmark
+ * (PowerPoint's "Trigger > On Bookmark"). The media element is
+ * {@link PptxElementAnimation.triggerShapeId} and the bookmark
+ * {@link PptxElementAnimation.triggerBookmark}; saved as an interactive
+ * sequence gated on `p:cond evt="onMediaBookmark"` with a `p14:bmkTgt`.
+ */
+'onMediaBookmark';
+/**
+ * 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';
+/**
+ * `p:spTgt/p:graphicEl` (CT_TLGraphicalObjectBuildElement, ECMA-376 S19.5.34):
+ * identifies exactly which series/category/element of a chart or diagram
+ * build a per-stage effect reveals, when a deck authors one effect per stage
+ * instead of a single staged `p:bldGraphic` reveal.
+ */
+interface PptxAnimationGraphicElementTarget {
+  /** Which graphic kind: `p:dgm` (diagram) or `p:chart`. */
+  kind: 'dgm' | 'chart';
+  /** `@_seriesIdx`, 0-based series index, when the target is series-scoped. */
+  seriesIdx?: number;
+  /** `@_categoryIdx`, 0-based category index, when the target is category-scoped. */
+  categoryIdx?: number;
+  /**
+   * `p:dgm/@_id` (CT_TLBuildDiagram, ECMA-376 S19.5.10): the diagram DATA MODEL
+   * point id (`dgm:pt/@modelId`) this per-stage effect reveals, when a
+   * `p:bldDgm` build authors one effect per node instead of a single staged
+   * reveal. `dgm`-kind targets only; a `chart`-kind target never carries this.
+   * Matches `PptxSmartArtNode.id` (parsed from the same `@modelId`), so a
+   * diagram renderer can reveal the exact authored node.
+   */
+  id?: string;
+  /**
+   * `@_bldStep`: `ST_TLChartBuildStep` (`category` / `categoryEl` / `series` /
+   * `seriesEl`) for a `chart`-kind target, or `ST_TLDiagramBuildStep`
+   * (`sp` / `bg`) for a `dgm`-kind target.
+   */
+  bldStep?: string;
+}
+/**
+ * `p:spTgt/p:oleChartEl` (CT_TLOleChartTargetElement, ECMA-376 S19.5.44):
+ * legacy pre-DrawingML OLE Graph chart sub-element targeting.
+ */
+interface PptxAnimationOleChartElementTarget {
+  /** `@_type` (ST_TLOleChartSubelementType): entireChart / series / category / ... */
+  subelementType: string;
+  /** `@_lvl`, optional sub-element level. */
+  level?: number;
+}
+/** A target selected by `p:tgtEl` in the PresentationML timing model. */
+type PptxAnimationTarget = {
+  type: 'shape';
+  shapeId: string;
+  /** Whether `p:spTgt/p:bg` limits the effect to the shape background. */
+  backgroundOnly?: boolean;
+  /**
+   * `p:spTgt/p:subSp/@_spid`: the id of a shape NESTED inside the group
+   * named by {@link shapeId} (CT_TLSubShapeId, ECMA-376 S19.5.71).
+   * PowerPoint authors this when a user animates one member of a group
+   * without ungrouping it: `shapeId` stays the outer group's id for
+   * round-trip, but this sub-shape is the real playback target.
+   */
+  subShapeId?: string;
+  /** `p:spTgt/p:graphicEl`: chart/diagram series/category/element target. */
+  graphicElement?: PptxAnimationGraphicElementTarget;
+  /** `p:spTgt/p:oleChartEl`: legacy OLE chart sub-element target. */
+  oleChartElement?: PptxAnimationOleChartElementTarget;
+  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;
+};
+/**
+ * A single `p:tmpl` timing template parsed from a TEXT `p:bldP/p:tmplLst`
+ * (CT_TLTemplate, ECMA-376 §19.5.85; the list itself is CT_TLTemplateList,
+ * §19.5.84).
+ *
+ * PowerPoint writes these as the timing PowerPoint would apply to a build
+ * level that does not yet have an instantiated effect, so that promoting or
+ * demoting an outline paragraph, or adding a new bullet at a level with no
+ * prior animation, has a default to clone. They are not consulted at
+ * playback: the animation actually shown for every paragraph level already
+ * visible on the slide is the real, instantiated `p:tnLst` under
+ * `p:timing/p:tnLst`, which the rest of this parser already models in full.
+ *
+ * The nested time-node tree under each template's own `p:tnLst` is kept as
+ * a preserved `XmlObject` rather than deep-parsed into
+ * {@link PptxNativeAnimation} records: it is schema-identical to the
+ * top-level timing tree but scoped to a template that is never itself
+ * executed, so structurally modelling it would stand up a second, unused
+ * parallel animation model. Parsing stops at typed round-trip; see
+ * `docs/guide/limitations.md`.
+ */
+interface PptxTimingTemplate {
+  /** Build level this template targets, from `p:tmpl/@lvl` (ST_TLLevel, default 0). */
+  level: number;
+  /** Preserved `p:tnLst` (CT_TimeNodeList) subtree, verbatim. */
+  timeNodeList: XmlObject;
+  /** Preserved `p:tmpl` XML node (its attributes plus any unmodelled children). */
+  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: the clicked shape of an
+   * interactive sequence, or the media element of an `onMediaBookmark` one.
+   */
+  triggerShapeId?: string;
+  /** Bookmark name an `onMediaBookmark` interactive sequence waits for. */
+  triggerBookmark?: string;
+  /** Whether this effect belongs to an OOXML `interactiveSeq`. */
+  interactiveSequence?: boolean;
+  /** Whether `p:endSync/p:rtn[@val="all"]` makes that sequence replayable. */
+  interactiveRestart?: boolean;
+  /** Effect preset class (entr, exit, emph, path). */
+  presetClass?: 'entr' | 'exit' | 'emph' | 'path';
+  /** Effect preset sub-type identifier. */
+  presetId?: number;
+  /**
+   * Effect preset direction/variant code from `p:cTn/@presetSubtype`
+   * (ECMA-376 CT_TLCommonTimeNodeData). For Fly In/Out this encodes the
+   * edge/corner the object travels from as a bitmask (1=top, 2=right,
+   * 4=bottom, 8=left; corners combine bits). Absent means the preset default.
+   */
+  presetSubtype?: number;
+  /** Duration in milliseconds. */
+  durationMs?: number;
+  /** Delay in milliseconds. */
+  delayMs?: number;
+  /**
+   * Acceleration fraction in the range 0..1, parsed from `p:cTn/@accel`
+   * (ST_PositiveFixedPercentage, stored as 1000ths of a percent). A non-zero
+   * value means the effect eases in (starts slow). Absent means no easing-in.
+   */
+  accel?: number;
+  /**
+   * Deceleration fraction in the range 0..1, parsed from `p:cTn/@decel`.
+   * A non-zero value means the effect eases out (ends slow). Absent means no
+   * easing-out. When both {@link accel} and {@link decel} are set, the effect
+   * eases in and out.
+   */
+  decel?: 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.
+   * Viewer-authoring-only hint: OOXML has no such flag (`p:animMotion/@rAng`
+   * is a plain rotation angle that PowerPoint writes as "0" on every path),
+   * so the parser never sets this.
+   */
+  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;
+  /** Authored path rotation in degrees from `p:animMotion/@rAng`. */
+  motionPathRotationAngle?: number;
+  /** Motion-path rotation centre X in slide percentage units (`p:rCtr/@x`). */
+  motionPathRotationCenterX?: number;
+  /** Motion-path rotation centre Y in slide percentage units (`p:rCtr/@y`). */
+  motionPathRotationCenterY?: number;
+  /** 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[];
+  /**
+   * The attribute {@link keyframes} drives, from the SAME node's
+   * `p:cBhvr/p:attrNameLst/p:attrName` (ECMA-376 S19.5.4). `p:tavLst` is
+   * schema-generic: without this, playback could see a numeric ramp but not
+   * know whether it targeted opacity, position, colour, or something with
+   * no CSS mapping. Lowercased and trimmed; common values seen in the wild
+   * (and written by this codebase's own animation writer) include
+   * `"style.opacity"`, `"style.color"`, `"style.visibility"`, `"fillcolor"`,
+   * `"stroke.color"`, `"r"` (rotation, only meaningful on `p:animRot`), and
+   * `"ppt_x"` / `"ppt_y"` (position, normally driven via `p:animMotion`
+   * instead). Absent when the behaviour carries no `p:attrNameLst`.
+   */
+  attrName?: string;
+  /** Every generic `p:anim` sibling composed by the authored effect. */
+  attributeAnimations?: PptxAttributeAnimation[];
+  /** 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. Modern PowerPoint
+   * (COM-verified against 2016) writes this as a `p:audio/p:cMediaNode`
+   * sibling of the effect's own `p:childTnLst`, targeting `p:sndTgt` rather
+   * than a shape; the legacy `p:stSnd` form (directly on `p:cTn`) is still
+   * accepted on load for round-trip of older-authored decks, but PowerPoint
+   * itself no longer writes it and does not recognise it back
+   * (`Effect.EffectInformation.SoundEffect` reads empty against it).
+   */
+  soundRId?: string;
+  /** Resolved sound file path from relationship. */
+  soundPath?: string;
+  /**
+   * The embedded sound's `@_name` (from `p:snd`/`p:sndTgt`). For one of
+   * PowerPoint's 19 built-in stock sounds this is the exact upper-case file
+   * name PowerPoint itself writes (e.g. `"CHIMES.WAV"`); see
+   * `pptx-viewer-shared`'s `effect-sound-catalogue.ts`, which matches this
+   * value back to a gallery entry. Absent for a custom sound with no name,
+   * or when unresolved.
+   */
+  soundName?: string;
+  /** Whether to stop any currently playing sound (`p:endSnd`). */
+  stopSound?: boolean;
+  /**
+   * End-state behaviour from `p:cTn/@fill` (ST_TLTimeNodeFillType, ECMA-376
+   * §19.5.27). `hold`/`freeze` mean the effect's final frame persists after
+   * it finishes; `remove` (the default when absent) means the target reverts
+   * to its pre-effect appearance. `transition` behaves like `hold` until the
+   * next time node starts. Absent means the OOXML default (`remove`).
+   */
+  fill?: 'remove' | 'freeze' | 'hold' | 'transition';
+  /**
+   * Restart behaviour from `p:cTn/@restart` (ST_TLTimeNodeRestartType).
+   * Absent means the OOXML default (`always`).
+   */
+  restart?: 'always' | 'whenNotActive' | 'never';
+  /**
+   * Repeat duration in milliseconds from `p:cTn/@repeatDur`. `Infinity`
+   * represents the literal `"indefinite"` token.
+   */
+  repeatDurMs?: number;
+  /**
+   * Playback speed multiplier from `p:cTn/@spd` (ST_Percentage, normalized
+   * from OOXML's 1000ths-of-a-percent storage to a plain percentage, e.g.
+   * `150` for 150% / double speed). Absent means normal (100%) speed.
+   */
+  speedPct?: number;
+  /**
+   * Reverse the paragraph build order from `p:bldP/@rev` (TEXT build only).
+   * Not to be confused with {@link PptxGraphicBuild}'s `reverse` field, which
+   * carries the unrelated `p:bldDgm`/`@rev` DIAGRAM-build reverse flag.
+   */
+  buildReverse?: boolean;
+  /**
+   * Auto-advance time in milliseconds from `p:bldP/@advAuto`. `Infinity`
+   * represents the literal `"indefinite"` token. Absent means the build
+   * step waits for a click.
+   */
+  buildAdvAutoMs?: number;
+  /**
+   * Per-build-level timing templates from a TEXT `p:bldP/p:tmplLst`
+   * (ECMA-376 §19.5.84 CT_TLTemplateList). Parsed for round-trip only; see
+   * {@link PptxTimingTemplate} for why they are not consulted at playback.
+   */
+  buildTemplates?: PptxTimingTemplate[];
+  /**
+   * Whether the enclosing `p:seq` allows concurrent play with its siblings,
+   * from `p:seq/@concurrent`. Parsed for round-trip; not yet honoured by
+   * playback (see `docs/guide/limitations.md`).
+   */
+  seqConcurrent?: boolean;
+  /** Next-action behaviour from `p:seq/@nextAc` (ST_TLNextActionType). */
+  seqNextAction?: 'none' | 'seek';
+  /** Previous-action behaviour from `p:seq/@prevAc` (ST_TLPreviousActionType). */
+  seqPrevAction?: 'none' | 'skipTimeNode';
+  /**
+   * Whether the enclosing click-level group (a direct `p:par` child of the
+   * `mainSeq`) begins automatically when the slide appears, rather than waiting
+   * for a click.
+   *
+   * PowerPoint gates a click step with a lone `<p:cond delay="indefinite"/>`;
+   * a group that also carries a time-node condition (`onBegin`/`onEnd` with a
+   * `@tn`) or a finite delay starts on slide entry ("With/After Previous" as the
+   * first effect on the slide). The flat animation list cannot express that on
+   * its own, so the parse layer stamps it here.
+   */
+  groupAutoStart?: boolean;
+  /**
+   * Index of the enclosing effect-wrapper `p:par` inside the click-level group.
+   *
+   * Effects that share a wrapper are OOXML siblings: they all start when that
+   * wrapper starts, and each `p:cond/@delay` is measured from the wrapper's
+   * start, NOT chained off the effect before it. Playback uses this to place
+   * simultaneous effects at their true offsets instead of accumulating delays.
+   */
+  parGroupIndex?: number;
+  /**
+   * Absolute start offset of the enclosing effect-wrapper from its click group.
+   *
+   * Structural `p:par` wrappers can carry their own start conditions. Keeping
+   * this offset separate from the effect's delay prevents playback from
+   * replacing an authored absolute start with a duration-based approximation.
+   */
+  parGroupDelayMs?: number;
+  /** 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;
+  /**
+   * Identifies which `p:excl` container this animation belongs to, when
+   * {@link exclusive} is set. ECMA-376 S19.5.24 CT_TLExclusiveTimeNode: at
+   * most one direct child of an exclusive container may be active at a
+   * time, so starting one child stops any other currently-playing child of
+   * the SAME container. Two different `p:excl` containers on the same slide
+   * are independent groups; this id (assigned per container encountered
+   * during parsing, stable only within one parse's animation list) lets
+   * playback tell them apart. Absent when {@link exclusive} is unset.
+   */
+  exclGroupId?: number;
+  /** 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;
+  /**
+   * 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.
+   */
+  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;
+  /**
+   * OLE-embedded chart build attribute (`p:bldOleChart/@bld`) when this
+   * animation stages an OLE chart graphic frame. Values follow
+   * ST_TLOleChartBuildType: `allAtOnce`, `series`, `category`, `seriesEl`,
+   * `categoryEl`. Lets a staged-reveal renderer build the chart by series /
+   * category / element to match PowerPoint, rather than as one whole element.
+   */
+  oleChartBuild?: 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>;
+  /** Parent timing cannot be reduced to the bounded fixed-opacity interval. */
+  unsupportedOpacitySetTiming?: boolean;
+  /** Admitted isolated held whole-shape visibility flip from native preset zero. */
+  visibilitySetTiming?: PptxVisibilitySetTiming;
+  /** A retained preset-zero visibility body has an unmeasured target, value or clock. */
+  unsupportedVisibilitySet?: boolean;
+  /**
+   * 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;
+  /**
+   * "After animation" end-state behaviour: dim-to-colour, hide-after-
+   * animation, or hide-on-next-click. Populated directly by the
+   * native-timing parser (`native-animation-after-effect.ts`) when the
+   * effect's `p:cTn/p:subTnLst` carries PowerPoint's genuine after-effect
+   * shape, so a real-world deck's build shows up here even with no
+   * `pptx:editorMeta`. `applyAfterAnimationFromEditorList` in
+   * `pptx-viewer-shared` overrides this from the matching
+   * {@link PptxElementAnimation.afterAnimation} entry when the editor's
+   * per-element animation list has one (the model the animation panel
+   * writes `afterAnimation` into), so an edit through our own UI always wins.
+   */
+  afterAnimationAction?: PptxAfterAnimationAction;
+  /** Dim-to color hex, present when {@link afterAnimationAction} is `dimToColor` AND the dim target is an already-resolved `a:srgbClr`. */
+  afterAnimationColor?: string;
+  /**
+   * The typed theme reference when a `dimToColor` target is an `a:schemeClr`
+   * (e.g. `accent2`) instead of `a:srgbClr`: this parse layer has no theme to
+   * resolve it to sRGB with (see {@link afterAnimationColor}'s doc), so a
+   * playback consumer resolves this against the deck's theme colour map.
+   * Mutually exclusive with {@link afterAnimationColor} being set.
+   */
+  afterAnimationColorRef?: PptxThemeColorRef;
+  /**
+   * Parsed `p:animEffect` filter descriptor. `presetId`/`presetClass` remain
+   * the primary effect selector (see `resolveEffect` in `pptx-viewer-shared`);
+   * this is the fallback used when a preset table lookup misses (unmapped or
+   * absent `presetId`), which happens for decks authored by tools other than
+   * PowerPoint that only emit the SMIL-style filter string.
+   */
+  effectFilter?: PptxAnimationEffectFilter;
+  /**
+   * This effect's own `p:cTn/@_id` (a raw OOXML time-node id, not a shape
+   * id). Lets playback resolve a `p:cond/@tn` dependency (see
+   * {@link AnimationCondition.targetTimeNodeId}) against the SPECIFIC node
+   * it names rather than assuming it is always the positionally-previous
+   * effect. Absent when the node carried no `@_id`.
+   */
+  nodeId?: number;
+  /**
+   * Interpolation mode for this effect's PRIMARY `p:anim`-family behaviour
+   * (the same node {@link keyframes}/{@link attrName} were read from), from
+   * `@_calcmode` (ST_TLAnimateBehaviorCalcMode, ECMA-376 S19.5.2). See
+   * {@link PptxAttributeAnimation.calcMode} for the per-component version.
+   */
+  calcMode?: 'discrete' | 'lin' | 'fmla';
+  /**
+   * `p:cBhvr/@_additive` (ST_TLBehaviorAdditiveType, ECMA-376 S19.5.4):
+   * controls how this behaviour's value composites with sibling behaviours
+   * driving the same attribute on the same target. `sum` accumulates
+   * (e.g. a combined scale+rotate), `repl`/`base`/`none`/`mult` replace or
+   * otherwise combine. Absent means the OOXML default (`base`).
+   */
+  cBhvrAdditive?: 'base' | 'sum' | 'repl' | 'mult' | 'none';
+  /**
+   * `p:cBhvr/@_accumulate` (ST_TLBehaviorAccumulateType): `always` means
+   * each `p:cTn/@repeatCount` repeat starts from the PREVIOUS repeat's end
+   * value (e.g. a 3x Spin totals 1080deg instead of replaying 0-360 three
+   * times); `none` (the OOXML default) resets every repeat.
+   */
+  cBhvrAccumulate?: 'none' | 'always';
+  /**
+   * `p:cBhvr/@_xfrmType` (only meaningful on `p:animMotion`): `point`
+   * (default) or `img`, a legacy compatibility hint. Round-tripped only.
+   */
+  cBhvrXfrmType?: 'point' | 'img';
+  /**
+   * `p:cBhvr/@_override` (ST_TLBehaviorOverrideType): `normal` (default) or
+   * `childStyle`, a legacy compatibility hint. Round-tripped only.
+   */
+  cBhvrOverride?: 'normal' | 'childStyle';
+  /**
+   * `p:set` discrete attribute assignments composed alongside this effect
+   * (ECMA-376 S19.5.79 CT_TLSetBehavior): an instantaneous (non-interpolated)
+   * value change, as opposed to {@link attributeAnimations}'s `p:anim`
+   * keyframe ramps. PowerPoint authors several font-style emphasis effects
+   * this way (Bold Reveal, Underline, Bold Flash, Change Font Size), since
+   * "on/off" or "size N" has nothing to interpolate. Not yet consulted by
+   * shared playback (round-trip/typed-model only so far).
+   */
+  setAnimations?: PptxSetAnimation[];
+  /**
+   * Every behaviour child of this effect (`p:set`, `p:anim`, `p:animEffect`,
+   * `p:animScale`, `p:animRot`, `p:animMotion`) with its own timing, as
+   * authored. The single-valued fields above flatten a composed preset;
+   * this keeps the whole tree so playback can follow what PowerPoint wrote
+   * (see `animation-behavior-player` in `pptx-viewer-shared`).
+   */
+  behaviors?: PptxAnimationBehavior[];
+}
+/**
+ * One `p:set` discrete (non-interpolated) attribute assignment composed
+ * alongside an authored effect. See {@link PptxNativeAnimation.setAnimations}.
+ *
+ * @see ECMA-376 S19.5.79 CT_TLSetBehavior
+ */
+interface PptxSetAnimation {
+  /** Lowercased target attribute from `p:cBhvr/p:attrNameLst/p:attrName`. */
+  attrName: string;
+  /** Decoded value from `p:to` (same variant shape as a `p:tav/p:val`). */
+  value: string | boolean | number;
+  /** Discriminant indicating which `p:to` child carried the value. */
+  valueType: 'str' | 'bool' | 'int' | 'flt' | 'clr';
+  /** Duration from this behaviour's nested `p:cTn/@dur`. */
+  durationMs?: number;
+  /** Start offset from this behaviour's nested `p:stCondLst`. */
+  delayMs?: number;
+}
+/**
+ * Parsed `p:animEffect/@filter` (+ `@transition`) descriptor. ECMA-376
+ * describes `@filter` as a free-form string of the form `family(subtype)`,
+ * optionally followed by `;`-separated fallback candidates (only the first
+ * is honoured, per ECMA-376 S19.5.3's "first supported filter wins" rule).
+ *
+ * @example
+ * ```ts
+ * const f: PptxAnimationEffectFilter = { family: 'wipe', subtype: 'up', transition: 'in', raw: 'wipe(up)' };
+ * ```
+ */
+interface PptxAnimationEffectFilter {
+  /** Filter family name (e.g. `"wipe"`, `"barn"`, `"checkerboard"`), lowercased. */
+  family: string;
+  /**
+   * Parenthesised subtype/direction token verbatim (e.g. `"up"`,
+   * `"inVertical"`, `"across"`, `"4"`). Absent when the filter has no
+   * subtype (e.g. bare `"dissolve"`).
+   */
+  subtype?: string;
+  /**
+   * `p:animEffect/@transition`: `"in"` reveals the target (the OOXML
+   * default when the attribute is omitted), `"out"` conceals it, `"none"`
+   * applies the filter without a visibility change (a static filter pass).
+   */
+  transition?: 'in' | 'out' | 'none';
+  /** Raw filter string exactly as authored, for round-trip/debugging. */
+  raw: string;
+}
+/**
+ * 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;
+  /**
+   * The typed theme reference when a `p:val/p:clrVal` stop is an
+   * `a:schemeClr` (e.g. `accent1`), including any `tint`/`shade`/`lumMod`/
+   * `lumOff`/`alpha` children. {@link value} keeps the bare scheme name for
+   * round-trip; a playback consumer needs this ref (resolved against the
+   * deck's theme colour map) to turn the stop into a real CSS colour, which
+   * the bare name alone cannot do. Absent for an `a:srgbClr` stop, whose
+   * {@link value} is already a resolved `#rrggbb` hex string.
+   */
+  colorRef?: PptxThemeColorRef;
+}
+/** One generic `p:anim` behaviour inside a composed PowerPoint effect. */
+interface PptxAttributeAnimation {
+  /** Lowercased target attribute from `p:attrNameLst`. */
+  attrName: string;
+  /**
+   * Authored value stops from this behaviour's `p:tavLst`. Empty when the
+   * behaviour instead uses the simpler `from`/`to`/`by` attribute form (see
+   * below); at least one of `keyframes`, `from`/`to`, or `by` is present.
+   */
+  keyframes: PptxAnimationKeyframe[];
+  /**
+   * `p:anim/@_from` (a formula string, ECMA-376 S19.5.4 CT_TLAnimateBehavior):
+   * the absolute starting value, used instead of `p:tavLst` when the
+   * behaviour only has two endpoints. PowerPoint writes this form for some
+   * built-in presets (e.g. "Grow And Turn"'s `ppt_x` fly-in): a bare
+   * `p:anim from="..." to="..."` with no `p:tavLst` child at all. See
+   * `animation-ppt-formula-ground-truth.md` in `pptx-viewer-shared` for the
+   * real-PowerPoint sample this was found in.
+   */
+  from?: string;
+  /** `p:anim/@_to`: the absolute ending value. See {@link from}. */
+  to?: string;
+  /**
+   * `p:anim/@_by`: a DELTA formula added to wherever the attribute already
+   * stands (as opposed to `from`/`to`'s absolute values), typically paired
+   * with `p:cBhvr/@_additive="sum"` so it composites with a sibling
+   * behaviour driving the same attribute instead of replacing it.
+   */
+  by?: string;
+  /** Duration from this behaviour's nested `p:cTn/@dur`. */
+  durationMs?: number;
+  /** Start offset from this behaviour's nested `p:stCondLst`. */
+  delayMs?: number;
+  /**
+   * Interpolation mode from this behaviour's own `@_calcmode`
+   * (ST_TLAnimateBehaviorCalcMode, ECMA-376 S19.5.2): `discrete` snaps to
+   * each `p:tav` stop with no interpolation, `lin` (the OOXML default)
+   * interpolates linearly. `fmla` as the WHOLE behaviour's calc mode has
+   * never been observed in a real PowerPoint file and is not consulted at
+   * playback; what PowerPoint actually writes is `calcmode="lin"` with a
+   * per-stop `p:tav/@fmla` (see {@link PptxAnimationKeyframe.fmla}), which
+   * IS consulted regardless of this field's value. Absent means `lin`.
+   */
+  calcMode?: 'discrete' | 'lin' | 'fmla';
+  /**
+   * `p:anim/@_p14:bounceEnd` (Office 2010 `p14` extension attribute,
+   * MS-OI29500), normalized to a 0-1 fraction of this behaviour's own
+   * duration. PowerPoint's "Bounce End" effect option (COM:
+   * `Effect.Timing.BounceEnd` + `BounceEndIntensity`) writes this on the
+   * position-ramp `p:anim` node(s): the share of the duration spent
+   * BOUNCING at the end. Measured from PowerPoint's own CreateVideo frames,
+   * the travel completes at `1 - bounceEnd` and the rest is a damped
+   * oscillation about the final value (see shared's `animation-bounce-end`).
+   * Mirrored verbatim by PowerPoint onto the enclosing
+   * `p:cTn/@_p14:presetBounceEnd`. Absent for every animation that doesn't
+   * use this effect option (the overwhelming majority).
+   */
+  bounceEnd?: number;
+}
+/** Signed HSL channel deltas parsed from `p:animClr/p:by/p:hsl`. */
+interface PptxHslColorDelta {
+  /** Hue offset in degrees. OOXML stores this in 60000ths of a degree. */
+  hue: number;
+  /** Saturation offset in percentage points. */
+  saturation: number;
+  /** Lightness offset in percentage points. */
+  lightness: number;
+}
+/** 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, or the bare scheme name (e.g. `accent1`) for a theme colour; see {@link fromColorRef}. */
+  fromColor?: string;
+  /** Ending color as hex string, or the bare scheme name; see {@link toColorRef}. */
+  toColor?: string;
+  /**
+   * Color delta (for "by" animations) as hex string, or the bare scheme name;
+   * see {@link byColorRef}. For HSL colour-space animations this retains the
+   * historical byte-packed compatibility value; consumers should prefer
+   * {@link hslDelta}, which preserves signed values.
+   */
+  byColor?: string;
+  /**
+   * The typed theme reference when {@link fromColor} is an `a:schemeClr`
+   * (including `tint`/`shade`/`lumMod`/`lumOff`/`alpha`), so playback can
+   * resolve it against the deck's theme colour map. Absent when `fromColor`
+   * is already a resolved `#rrggbb` hex (an `a:srgbClr` stop).
+   */
+  fromColorRef?: PptxThemeColorRef;
+  /** The typed theme reference for {@link toColor}; see {@link fromColorRef}. */
+  toColorRef?: PptxThemeColorRef;
+  /**
+   * The typed theme reference for {@link byColor} (RGB colour space only; an
+   * HSL `by` is a signed delta, never a theme colour). See {@link fromColorRef}.
+   */
+  byColorRef?: PptxThemeColorRef;
+  /**
+   * Typed HSL delta from `p:by/p:hsl`. This preserves signed values and their
+   * OOXML units without forcing them through the legacy byte-packed `byColor`
+   * representation.
+   */
+  hslDelta?: PptxHslColorDelta;
+  /**
+   * Target attribute from `p:attrNameLst` (e.g. "fillcolor", "style.color",
+   * "stroke.color"). Used to determine which CSS property to animate.
+   */
+  targetAttribute?: string;
+  /**
+   * All sibling `p:animClr` behaviours authored for the same timing node.
+   * The top-level fields continue to mirror the first behaviour for backwards
+   * compatibility; this list is present only when there is more than one.
+   */
+  components?: readonly PptxColorAnimation[];
+}
+/** 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' | 'onDblClick' | 'onMediaBookmark';
+/**
+ * `p14:bmkTgt` (Office 2010 `p14` extension, MS-OI29500): names the specific
+ * media element and bookmark an `evt="onMediaBookmark"` condition fires for.
+ * `bookmarkName` matches a `p14:bmk/@_name` on that media element's own
+ * `p14:bmkLst` (see `MediaBookmark.label` in `core/types/elements.ts`).
+ */
+interface PptxMediaBookmarkTarget {
+  /** `p14:bmkTgt/@_spid`: the media element's shape id. */
+  shapeId: string;
+  /** `p14:bmkTgt/@_bmkName`: the bookmark's name. */
+  bookmarkName: string;
+}
+/**
+ * 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;
+  /**
+   * The media element/bookmark this condition fires for, when
+   * {@link event} is `onMediaBookmark`. See {@link PptxMediaBookmarkTarget}.
+   */
+  bookmarkTarget?: PptxMediaBookmarkTarget;
+  /** 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;
+  /**
+   * The {@link order} the loader derived from the slide's `p:timing` tree for
+   * an entry whose `pptx:editorMeta` record authored no `@order`. The tree
+   * already expresses that position (and every load re-derives it), so the
+   * writer omits `@order` while `order` still equals this value; a reorder
+   * changes `order` and the attribute is written again. Load-time bookkeeping
+   * only; never set it by hand.
+   */
+  orderFromTimeline?: number;
+  trigger?: PptxAnimationTrigger;
+  /**
+   * Shape ID that triggers this animation: the shape clicked for
+   * `onShapeClick`, or the media element whose bookmark fires it for
+   * `onMediaBookmark`.
+   */
+  triggerShapeId?: string;
+  /** Bookmark name (`p14:bmk/@name`) an `onMediaBookmark` trigger waits for. */
+  triggerBookmark?: 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;
+  /** Imported after-state for controls, not an authored override or serialized extension. */
+  nativeAfterAnimation?: PptxAfterAnimationAction;
+  nativeAfterAnimationColor?: 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;
+  /** Authored path rotation in degrees from `p:animMotion/@rAng`. */
+  motionPathRotationAngle?: number;
+  /** Motion-path rotation centre X in slide percentage units (`p:rCtr/@x`). */
+  motionPathRotationCenterX?: number;
+  /** Motion-path rotation centre Y in slide percentage units (`p:rCtr/@y`). */
+  motionPathRotationCenterY?: number;
+  /**
+   * Sound relationship ID to play when animation triggers. Written on save
+   * as a `p:audio/p:cMediaNode` sibling of the effect's own `p:childTnLst`
+   * (see `PptxNativeAnimation.soundRId` for the COM-verified detail).
+   */
+  soundRId?: string;
+  /** Resolved sound file path from relationship. */
+  soundPath?: string;
+  /**
+   * The `@_name` to write on the embedded sound (`p:sndTgt`). For a stock
+   * gallery pick this is the exact PowerPoint file name (e.g.
+   * `"CHIMES.WAV"`), which is what makes PowerPoint itself recognise the
+   * sound as that built-in entry when it reopens the saved deck (there is no
+   * separate "built-in" flag anywhere in the schema). Set by
+   * `pptx-viewer-shared`'s `setEffectSound` when the pick carries a
+   * `soundName`; absent for a custom file with no meaningful name.
+   */
+  soundName?: string;
+  /** Whether to stop any currently playing sound (`p:endSnd`). */
+  stopSound?: boolean;
+  /**
+   * Pending, not-yet-embedded sound chosen in the authoring UI, as a
+   * `data:audio/...;base64,...` URL. Mirrors the `imageData` /
+   * `mediaData` pending-embed convention used elsewhere in the typed model:
+   * on save, the writer converts this to real bytes under `ppt/media/`,
+   * mints a relationship, and replaces this field with the resolved
+   * {@link soundRId} / {@link soundPath}. Cleared once embedded.
+   */
+  soundData?: string;
+  /**
+   * Display name for the chosen sound (e.g. the uploaded file's name),
+   * shown by the authoring UI's sound picker. Purely cosmetic; has no
+   * OOXML equivalent and is not required for playback. For a stock gallery
+   * pick, the UI derives its label from {@link soundName} via the catalogue
+   * instead of this field.
+   */
+  soundFileName?: string;
+  /**
+   * Per-build-level timing template(s) from the {@link sequence}'s own
+   * `p:bldP/p:tmplLst` (ECMA-376 §19.5.84), carried over from the loaded
+   * `PptxNativeAnimation.buildTemplates` this element animation was derived
+   * from so a full timing-tree rebuild (`PptxAnimationWriteService`'s
+   * `buildTimingXml`, when the slide had no prior `p:timing`) can re-emit
+   * them instead of silently dropping the deck's authored per-level
+   * defaults. Absent when {@link sequence} carries no such template.
+   */
+  buildTemplates?: PptxTimingTemplate[];
+}
+/**
+ * A read-only anchor representing one of the deck's own effect groups: a
+ * top-level click group (`p:par` under `p:timing`'s main sequence) that this
+ * app did not author, so it is never exposed as an editable
+ * {@link PptxElementAnimation}.
+ *
+ * The authoring UI merges these anchors alongside `PptxSlide.animations` to
+ * render the FULL animation sequence (editor-authored and deck-native
+ * effects together) and lets an editor-authored entry be dragged to any
+ * position relative to them. `order` is the anchor's position among ALL
+ * top-level click groups (editor-owned and native) at load time, in the same
+ * numbering space as {@link PptxElementAnimation.order}, so the two
+ * populations sort into one coherent timeline.
+ *
+ * Anchors are never written back: on save, an untouched anchor's own click
+ * group is repositioned (if an editor-authored effect was dragged past it)
+ * but never mutated, so the deck's own effect stays byte-identical apart
+ * from its position in the sequence.
+ */
+interface PptxAnimationTimelineAnchor {
+  /**
+   * Position of this group among all top-level click groups in the main
+   * animation sequence at load time (dense, shared with editor entries'
+   * `order`).
+   */
+  order: number;
+  /** Shape id(s) this group's effects target, for a readable UI label. */
+  targetIds: string[];
+  /** Effect preset classes present in the group (entr/exit/emph/path). */
+  presetClasses: Array<'entr' | 'exit' | 'emph' | 'path'>;
+}
+interface PptxVisibilitySetTiming {
+  /** Delay from effect start until the shape becomes visible. */
+  delayMs: number;
+  /** Native one-millisecond visibility behavior interval. */
+  durationMs: number;
+}
+//#endregion
+//#region pptx/core/types/comment-mentions.d.ts
+/**
+ * A single `@`-mention inside a modern comment body.
+ *
+ * Offsets index into the comment's FLATTENED plain text: every `a:t` value
+ * below `p188:txBody` concatenated, with paragraphs joined by `\n`. That is the
+ * same string `PptxComment.text` carries, so an edit to `text` invalidates
+ * every offset after the edit point and the serializer re-bases them.
+ *
+ * The markup Office uses for a mention is `CT_Mention` (documented for the
+ * SpreadsheetML `2018/threadedcomments` part): `mentionpersonId`, `mentionId`,
+ * `startIndex` and `length`. The PowerPoint `2018/8/main` schema does not
+ * publish a mention element at all, so `rawXml` is retained and re-emitted
+ * attribute-for-attribute: a producer that spells the attributes differently
+ * still round-trips.
+ *
+ * @example
+ * ```ts
+ * const mention: PptxCommentMention = {
+ *   personId: "{2CB2E9D0-D392-EB21-5D46-FBA34C1295E6}",
+ *   authorName: "Bob Example",
+ *   startIndex: 3,
+ *   length: 11,
+ * };
+ * // => "Hi Bob Example can you check this".slice(3, 14) === "Bob Example"
+ * ```
+ */
+interface PptxCommentMention {
+  /** `mentionId`: GUID identifying this mention instance. */
+  id?: string;
+  /** `mentionpersonId`: the `p188:author` id of the mentioned person. */
+  personId: string;
+  /** Display name resolved from the author list at parse time, when known. */
+  authorName?: string;
+  /** Character offset of the mentioned span in the flattened plain text. */
+  startIndex: number;
+  /** Character length of the mentioned span. */
+  length: number;
+  /**
+   * `uri` of the `p188:ext` this mention list was read from. Undefined means
+   * the list is a direct child of `p188:cm`, which is where it is written for
+   * newly authored mentions.
+   */
+  containerUri?: string;
+  /** Original `p188:mention` node, retained for unknown-attribute preservation. */
+  rawXml?: XmlObject;
+}
+//#endregion
+//#region pptx/core/types/metadata.d.ts
+/**
+ * A slide comment — may be a legacy positional comment or a modern
+ * threaded comment with replies.
+ *
+ * @example
+ * ```ts
+ * const comment: PptxComment = {
+ *   id: "c1",
+ *   text: "Please update this chart.",
+ *   author: "Alice",
+ *   createdAt: "2024-06-01T10:00:00Z",
+ *   resolved: false,
+ * };
+ * // => satisfies PptxComment
+ * ```
+ */
+interface PptxComment {
+  id: string;
+  text: string;
+  /** 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;
+  /** `@`-mentions, indexed into `text` (see {@link PptxCommentMention}). */
+  mentions?: PptxCommentMention[];
+  /** 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;
+}
+/** Office 2021 comment author from the p188 Author part. */
+interface PptxModernCommentAuthor {
+  id: string;
+  name: string;
+  initials?: string;
+  userId: string;
+  providerId: string;
+  rawXml?: XmlObject;
+}
+/**
+ * A comment author from `ppt/commentAuthors.xml`.
+ *
+ * Stores all attributes needed for lossless round-trip serialization
+ * of the `p:cmAuthor` element (id, name, initials, lastIdx, clrIdx).
+ *
+ * @see ECMA-376 Part 1, §19.4.2 (cmAuthor)
+ *
+ * @example
+ * ```ts
+ * const author: PptxCommentAuthor = {
+ *   id: "0",
+ *   name: "John Doe",
+ *   initials: "JD",
+ *   lastIdx: 3,
+ *   clrIdx: 0,
+ * };
+ * // => satisfies PptxCommentAuthor
+ * ```
+ */
+interface PptxCommentAuthor {
+  /** Unique numeric author identifier (`@_id`). */
+  id: string;
+  /** Author display name (`@_name`). */
+  name: string;
+  /** Author initials (`@_initials`). */
+  initials: string;
+  /** Last comment index used by this author (`@_lastIdx`). */
+  lastIdx: number;
+  /** Colour index assigned to this author (`@_clrIdx`). */
+  clrIdx: number;
+  /** Original `p:cmAuthor` subtree, retained for unknown attribute preservation. */
+  rawXml?: XmlObject;
+}
+/**
+ * A compatibility warning generated during parse or save when the
+ * file uses features not fully supported by the editor.
+ *
+ * @example
+ * ```ts
+ * const warning: PptxCompatibilityWarning = {
+ *   code: "UNSUPPORTED_3D",
+ *   message: "3D rotation effects may not render accurately.",
+ *   severity: "warning",
+ *   scope: "element",
+ *   slideId: "slide-1",
+ *   elementId: "elem-42",
+ * };
+ * // => satisfies PptxCompatibilityWarning
+ * ```
+ */
+interface PptxCompatibilityWarning {
+  code: string;
+  message: string;
+  severity: 'info' | 'warning';
+  scope: 'presentation' | 'slide' | 'element' | 'save';
+  slideId?: string;
+  elementId?: string;
+  xmlPath?: string;
+}
+/**
+ * A single name–value tag from `ppt/tags/*.xml`.
+ *
+ * @example
+ * ```ts
+ * const tag: PptxTag = { name: "CUSTOM_ID", value: "12345" };
+ * // => satisfies PptxTag
+ * ```
+ */
+interface PptxTag {
+  name: string;
+  value: string;
+}
+/**
+ * A collection of tags from a single tags XML part.
+ *
+ * @example
+ * ```ts
+ * const coll: PptxTagCollection = {
+ *   path: "ppt/tags/tag1.xml",
+ *   tags: [{ name: "CUSTOM_ID", value: "12345" }],
+ * };
+ * // => satisfies PptxTagCollection
+ * ```
+ */
+interface PptxTagCollection {
+  /** File path within the PPTX archive. */
+  path?: string;
+  /** Package owner of the tags relationship. New collections default to presentation. */
+  owner?: 'presentation' | 'slide' | 'part';
+  /** Source OPC part that owns the relationship, e.g. ppt/slides/slide1.xml. */
+  sourcePartPath?: string;
+  /** Durable relationship identifier from the owning part. */
+  relationshipId?: string;
+  /** Tags in this collection. */
+  tags: PptxTag[];
+  /** Parsed tag-list XML retained for unknown-node preservation. */
+  rawXml?: XmlObject;
+}
+/**
+ * A custom document property from `docProps/custom.xml`.
+ *
+ * @example
+ * ```ts
+ * const prop: PptxCustomProperty = {
+ *   name: "Project",
+ *   value: "pptx",
+ *   type: "lpwstr",
+ * };
+ * // => satisfies PptxCustomProperty
+ * ```
+ */
+interface PptxCustomProperty {
+  /** Property name. */
+  name: string;
+  /** Property value (always stringified). */
+  value: string;
+  /** Original VT type (e.g. "lpwstr", "i4", "bool", "filetime"). */
+  type: string;
+}
+/**
+ * Core document properties from `docProps/core.xml` (Dublin Core + OOXML).
+ *
+ * @example
+ * ```ts
+ * const core: PptxCoreProperties = {
+ *   title: "Q4 Business Review",
+ *   creator: "Alice",
+ *   created: "2024-01-15T08:00:00Z",
+ *   modified: "2024-06-01T12:30:00Z",
+ *   lastModifiedBy: "Bob",
+ * };
+ * // => satisfies PptxCoreProperties
+ * ```
+ */
+interface PptxCoreProperties {
+  /** dc:title */
+  title?: string;
+  /** dc:subject */
+  subject?: string;
+  /** dc:creator */
+  creator?: string;
+  /** cp:keywords */
+  keywords?: string;
+  /** dc:description */
+  description?: string;
+  /** cp:lastModifiedBy */
+  lastModifiedBy?: string;
+  /** cp:revision */
+  revision?: string;
+  /** dcterms:created (ISO 8601) */
+  created?: string;
+  /** dcterms:modified (ISO 8601) */
+  modified?: string;
+  /** cp:category */
+  category?: string;
+  /** cp:contentStatus */
+  contentStatus?: string;
+}
+/**
+ * Extended (application) properties from `docProps/app.xml`.
+ *
+ * @example
+ * ```ts
+ * const app: PptxAppProperties = {
+ *   application: "Microsoft Office PowerPoint",
+ *   appVersion: "16.0000",
+ *   slides: 24,
+ *   words: 1500,
+ *   company: "Acme Corp",
+ * };
+ * // => satisfies PptxAppProperties
+ * ```
+ */
+interface PptxAppProperties {
+  /** Application name (e.g. "Microsoft Office PowerPoint"). */
+  application?: string;
+  /** Application version string. */
+  appVersion?: string;
+  /** Presentation format (e.g. "On-screen Show (16:9)"). */
+  presentationFormat?: string;
+  /** Total number of slides. */
+  slides?: number;
+  /** Number of hidden slides. */
+  hiddenSlides?: number;
+  /** Number of notes slides. */
+  notes?: number;
+  /** Total editing time in minutes. */
+  totalTime?: number;
+  /** Number of words. */
+  words?: number;
+  /** Number of paragraphs. */
+  paragraphs?: number;
+  /** Company name. */
+  company?: string;
+  /** Manager name. */
+  manager?: string;
+  /** Template name. */
+  template?: string;
+  /** Hyperlink base URL. */
+  hyperlinkBase?: string;
+  /** Document security bitmask (`<DocSecurity>`). */
+  docSecurity?: number;
+  /** Number of multimedia clips (`<MMClips>`). */
+  mmClips?: number;
+  /** Whether thumbnail images were scaled to fit (`<ScaleCrop>`). */
+  scaleCrop?: boolean;
+  /** Whether hyperlinks are current (`<LinksUpToDate>`). */
+  linksUpToDate?: boolean;
+  /** Whether the document is shared (`<SharedDoc>`). */
+  sharedDoc?: boolean;
+  /** Whether hyperlinks changed since last save (`<HyperlinksChanged>`). */
+  hyperlinksChanged?: boolean;
+}
+//#endregion
+//#region pptx/core/types/theme.d.ts
+/**
+ * Theme object model — colour scheme, font scheme, and format scheme
+ * parsed from `ppt/theme/theme1.xml`.
+ *
+ * The colour scheme provides the 12 canonical OOXML colour slots.
+ * The font scheme defines major (heading) and minor (body) typefaces.
+ * The format scheme holds fill, line, and effect style matrices at
+ * three intensity levels (subtle, moderate, intense).
+ *
+ * @module pptx-types/theme
+ */
+/**
+ * The 12 OOXML theme colour scheme keys in canonical order.
+ *
+ * @example
+ * ```ts
+ * for (const key of THEME_COLOR_SCHEME_KEYS) {
+ *   console.log(key, theme.colorScheme?.[key]);
+ * }
+ * // => e.g. "dk1 #000000", "lt1 #FFFFFF", "accent1 #4F81BD", …
+ * ```
+ */
+declare const THEME_COLOR_SCHEME_KEYS: readonly ['dk1', 'lt1', 'dk2', 'lt2', 'accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6', 'hlink', 'folHlink'];
+/**
+ * Resolved hex values for the 12 theme colour slots.
+ *
+ * @example
+ * ```ts
+ * const scheme: PptxThemeColorScheme = {
+ *   dk1: "#000000", lt1: "#FFFFFF",
+ *   dk2: "#1F497D", lt2: "#EEECE1",
+ *   accent1: "#4F81BD", accent2: "#C0504D",
+ *   accent3: "#9BBB59", accent4: "#8064A2",
+ *   accent5: "#4BACC6", accent6: "#F79646",
+ *   hlink: "#0000FF", folHlink: "#800080",
+ * };
+ * // => satisfies PptxThemeColorScheme
+ * ```
+ */
+interface PptxThemeColorScheme {
+  dk1: string;
+  lt1: string;
+  dk2: string;
+  lt2: string;
+  accent1: string;
+  accent2: string;
+  accent3: string;
+  accent4: string;
+  accent5: string;
+  accent6: string;
+  hlink: string;
+  folHlink: string;
+}
+/**
+ * A font-family triplet for major or minor theme fonts.
+ *
+ * Supports Latin, East Asian, and Complex Script font families.
+ *
+ * @example
+ * ```ts
+ * const fonts: PptxThemeFontGroup = {
+ *   latin: "Calibri Light",
+ *   eastAsia: "MS PGothic",
+ *   complexScript: "Arial",
+ * };
+ * // => satisfies PptxThemeFontGroup
+ * ```
+ */
+interface PptxThemeFontGroup {
+  latin?: string;
+  eastAsia?: string;
+  complexScript?: string;
+  /**
+   * Per-script typeface overrides (`<a:font script="Hans|Hant|Arab|Hebr|
+   * Thai|Beng|Gujr|Khmr|Knda|…"/>` per ECMA-376 §20.1.4.1.16). Keyed by
+   * the four-letter ISO 15924 script tag from the `script` attribute.
+   *
+   * Phase 4 Stream A / M4.
+   */
+  byScript?: Record<string, string>;
+}
+/**
+ * Theme font scheme — major (headings) and minor (body) font families.
+ *
+ * @example
+ * ```ts
+ * const scheme: PptxThemeFontScheme = {
+ *   majorFont: { latin: "Calibri Light" },
+ *   minorFont: { latin: "Calibri", eastAsia: "MS PGothic" },
+ * };
+ * // => satisfies PptxThemeFontScheme
+ * ```
+ */
+interface PptxThemeFontScheme {
+  majorFont?: PptxThemeFontGroup;
+  minorFont?: PptxThemeFontGroup;
+}
+/**
+ * A single fill style entry from the theme format scheme.
+ * Each entry is one of: solid, gradient, pattern, or no fill.
+ * The raw XML node is also stored so that `phClr` substitution can happen
+ * at resolution time.
+ *
+ * @example
+ * ```ts
+ * const solidFill: PptxThemeFillStyle = {
+ *   kind: "solid",
+ *   color: "#4F81BD",
+ *   opacity: 1,
+ * };
+ *
+ * const gradientFill: PptxThemeFillStyle = {
+ *   kind: "gradient",
+ *   gradientAngle: 90,
+ *   gradientType: "linear",
+ *   gradientStops: [
+ *     { color: "#4F81BD", position: 0 },
+ *     { color: "#1F497D", position: 1 },
+ *   ],
+ * };
+ * // => satisfies PptxThemeFillStyle
+ * ```
+ */
+interface PptxThemeFillStyle {
+  /**
+   * Discriminator for the fill type.
+   *
+   * `'group'` corresponds to `<a:grpFill/>` — a fill that inherits the
+   * containing group shape's fill at render time. Captured for round-trip
+   * preservation in `fmtScheme/fillStyleLst`.
+   */
+  kind: 'solid' | 'gradient' | 'pattern' | 'none' | 'group';
+  /** Pre-resolved colour (may be `undefined` when `phClr`-dependent). */
+  color?: string;
+  opacity?: number;
+  /** Gradient-specific fields (only present when `kind === "gradient"`). */
+  gradientStops?: Array<{
+    color: string;
+    position: number;
+    opacity?: number;
+  }>;
+  gradientAngle?: number;
+  gradientType?: 'linear' | 'radial';
+  gradientCss?: string;
+  /** Pattern-specific fields (only present when `kind === "pattern"`). */
+  patternPreset?: string;
+  patternBackgroundColor?: string;
+  /** Raw XML node preserved for `phClr` re-resolution. */
+  rawNode?: unknown;
+}
+/**
+ * A single line style entry from `a:lnStyleLst`.
+ * Provides width, dash, join, cap, and optional fill colour.
+ *
+ * @example
+ * ```ts
+ * const line: PptxThemeLineStyle = {
+ *   width: 1.5,
+ *   color: "#4F81BD",
+ *   dash: "solid",
+ *   lineJoin: "round",
+ *   lineCap: "flat",
+ * };
+ * // => satisfies PptxThemeLineStyle
+ * ```
+ */
+interface PptxThemeLineStyle {
+  /** Line width in pixels (converted from EMU). */
+  width?: number;
+  color?: string;
+  opacity?: number;
+  dash?: string;
+  lineJoin?: 'round' | 'bevel' | 'miter';
+  lineCap?: 'flat' | 'rnd' | 'sq';
+  compoundLine?: 'sng' | 'dbl' | 'thickThin' | 'thinThick' | 'tri';
+  /** Raw XML node preserved for `phClr` re-resolution. */
+  rawNode?: unknown;
+}
+/**
+ * A single effect style entry from `a:effectStyleLst`.
+ * Each entry may define shadow, glow, soft-edge, reflection, blur,
+ * and optionally a 3-D scene/shape.
+ *
+ * @example
+ * ```ts
+ * const dropShadow: PptxThemeEffectStyle = {
+ *   shadowColor: "#000000",
+ *   shadowBlur: 4,
+ *   shadowOffsetX: 2,
+ *   shadowOffsetY: 3,
+ *   shadowOpacity: 0.4,
+ * };
+ * // => satisfies PptxThemeEffectStyle
+ * ```
+ */
+interface PptxThemeEffectStyle {
+  shadowColor?: string;
+  shadowBlur?: number;
+  shadowOffsetX?: number;
+  shadowOffsetY?: number;
+  shadowOpacity?: number;
+  glowColor?: string;
+  glowRadius?: number;
+  glowOpacity?: number;
+  softEdgeRadius?: number;
+  innerShadowColor?: string;
+  innerShadowOpacity?: number;
+  innerShadowBlur?: number;
+  innerShadowOffsetX?: number;
+  innerShadowOffsetY?: number;
+  reflectionBlurRadius?: number;
+  reflectionStartOpacity?: number;
+  reflectionEndOpacity?: number;
+  reflectionEndPosition?: number;
+  reflectionDirection?: number;
+  reflectionRotation?: number;
+  reflectionDistance?: number;
+  /** 3D scene/camera from `a:scene3d` on the effect style (idx 3 typically). */
+  scene3d?: Pptx3DScene;
+  /** 3D shape extrusion/bevel from `a:sp3d` on the effect style (idx 3 typically). */
+  shape3d?: Pptx3DShape;
+  /** Raw XML node preserved for `phClr` re-resolution. */
+  rawNode?: unknown;
+}
+/**
+ * The full parsed format scheme from `a:fmtScheme` inside `a:themeElements`.
+ * Contains three fill style lists and one line/effect style list each,
+ * at three intensity levels: subtle (idx 1), moderate (idx 2), intense (idx 3).
+ *
+ * OOXML reference indices:
+ * - fillStyleLst:   idx 1-3  (used by `a:fillRef @idx` 1-3)
+ * - lnStyleLst:     idx 1-3  (used by `a:lnRef @idx` 1-3)
+ * - effectStyleLst:  idx 1-3  (used by `a:effectRef @idx` 1-3)
+ * - bgFillStyleLst:  idx 1-3  (used by `a:fillRef @idx` 1001-1003)
+ *
+ * @example
+ * ```ts
+ * const fmt: PptxThemeFormatScheme = {
+ *   name: "Office",
+ *   fillStyles: [solidFill, gradientFill, intenseFill],
+ *   lineStyles: [thinLine, mediumLine, thickLine],
+ *   effectStyles: [subtle, moderate, intense],
+ *   backgroundFillStyles: [solidBg, gradientBg, intenseBg],
+ * };
+ * // => satisfies PptxThemeFormatScheme
+ * ```
+ */
+interface PptxThemeFormatScheme {
+  /** The `@name` attribute of the format scheme. */
+  name?: string;
+  /** Fill styles at indices 1-3 (subtle, moderate, intense). */
+  fillStyles: PptxThemeFillStyle[];
+  /** Line styles at indices 1-3. */
+  lineStyles: PptxThemeLineStyle[];
+  /** Effect styles at indices 1-3. */
+  effectStyles: PptxThemeEffectStyle[];
+  /** Background fill styles at indices 1-3 (referenced via idx 1001-1003). */
+  backgroundFillStyles: PptxThemeFillStyle[];
+}
+/**
+ * Full parsed theme object available to renderers.
+ *
+ * @example
+ * ```ts
+ * const theme: PptxTheme = {
+ *   name: "Office Theme",
+ *   colorScheme: { dk1: "#000", lt1: "#FFF", /* … *\/ },
+ *   fontScheme: {
+ *     majorFont: { latin: "Calibri Light" },
+ *     minorFont: { latin: "Calibri" },
+ *   },
+ * };
+ * // => satisfies PptxTheme
+ * ```
+ */
+interface PptxTheme {
+  /** Theme name from `a:theme @name`. */
+  name?: string;
+  /** Resolved colour scheme. */
+  colorScheme?: PptxThemeColorScheme;
+  /** Resolved font scheme. */
+  fontScheme?: PptxThemeFontScheme;
+  /** Format scheme — fill, line, effect and background fill style matrices. */
+  formatScheme?: PptxThemeFormatScheme;
+}
+/**
+ * Snapshot of `<a:objectDefaults>` (ECMA-376 §20.1.6.7). Each child
+ * (`spDef`, `lnDef`, `txDef`) carries `<a:spPr>`, `<a:bodyPr>`,
+ * `<a:lstStyle>`, `<a:style>`. We capture them as raw parser objects so
+ * round-trip is byte-stable regardless of schema-walking depth.
+ *
+ * Phase 4 Stream A / M5.
+ */
+interface PptxThemeObjectDefaults {
+  /** Raw `<a:spDef>` parser object, or `undefined` if absent. */
+  spDef?: unknown;
+  /** Raw `<a:lnDef>` parser object, or `undefined` if absent. */
+  lnDef?: unknown;
+  /** Raw `<a:txDef>` parser object, or `undefined` if absent. */
+  txDef?: unknown;
+}
+//#endregion
+//#region pptx/core/types/masters.d.ts
+/**
+ * A placeholder slot declared on a master or layout.
+ *
+ * The geometry fields are in CSS pixels (EMU / {@link EMU_PER_PX}) and are only
+ * present when the shape carried an explicit `a:xfrm`. Placeholders that
+ * inherit their frame from the master leave them undefined, so consumers that
+ * draw placeholder outlines (the layout gallery) must skip those entries
+ * rather than assume a zero-sized box at the origin.
+ *
+ * @example
+ * ```ts
+ * const frame: PptxPlaceholderFrame = { type: "body", idx: "1", x: 63, y: 130 };
+ * // => satisfies PptxPlaceholderFrame
+ * ```
+ */
+interface PptxPlaceholderFrame {
+  /** `p:ph/@type`, lower-cased by the parser; defaults to `body` when omitted. */
+  type: string;
+  /** `p:ph/@idx`, when present. */
+  idx?: string;
+  /** Left offset in CSS pixels, when the shape declares `a:off`. */
+  x?: number;
+  /** Top offset in CSS pixels, when the shape declares `a:off`. */
+  y?: number;
+  /** Width in CSS pixels, when the shape declares `a:ext`. */
+  width?: number;
+  /** Height in CSS pixels, when the shape declares `a:ext`. */
+  height?: number;
+}
+/**
+ * Parsed notes master from `ppt/notesMasters/notesMaster1.xml`.
+ *
+ * @example
+ * ```ts
+ * const notes: PptxNotesMaster = {
+ *   path: "ppt/notesMasters/notesMaster1.xml",
+ *   backgroundColor: "#FFFFFF",
+ *   placeholders: [{ type: "body" }, { type: "sldImg" }],
+ * };
+ * // => satisfies PptxNotesMaster
+ * ```
+ */
+interface PptxNotesMaster {
+  /** File path within the PPTX archive. */
+  path: string;
+  /** Background colour of the notes master. */
+  backgroundColor?: string;
+  /** Background image data URL. */
+  backgroundImage?: string;
+  /** Crop, tiling and image effects authored on the background blip fill. */
+  backgroundImageProperties?: PptxImageProperties;
+  /** Placeholder shapes found on the notes master. */
+  placeholders?: PptxPlaceholderFrame[];
+  /** Editable elements on the notes master (header, footer, date, page number, slide image, notes body). */
+  elements?: PptxElement[];
+  /** Header/footer flags from `<p:hf>` on the notes master (P-H3). */
+  headerFooter?: PptxHeaderFooterFlags;
+  /** Colour map from `<p:clrMap>` (12 alias attributes). Applied at save time. */
+  clrMap?: Record<string, string>;
+  /**
+   * Notes text defaults from `<p:notesStyle>` (`CT_TextListStyle`, ECMA-376
+   * §19.3.1.34): the same `a:defPPr` + `a:lvl1pPr`..`a:lvl9pPr` shape as
+   * {@link PptxMasterTextStyles}'s per-category styles, keyed 0-8 with the
+   * default at `-1`. Governs the notes body placeholder's font size, indent
+   * levels, and bullet style wherever a notes slide does not override them.
+   * Parsed read-only for the render cascade; the save side preserves the
+   * original `<p:notesStyle>` XML verbatim rather than re-serialising this.
+   */
+  notesStyle?: PptxTextStyleLevels;
+}
+/**
+ * Parsed handout master from `ppt/handoutMasters/handoutMaster1.xml`.
+ *
+ * @example
+ * ```ts
+ * const handout: PptxHandoutMaster = {
+ *   path: "ppt/handoutMasters/handoutMaster1.xml",
+ *   slidesPerPage: 6,
+ * };
+ * // => satisfies PptxHandoutMaster
+ * ```
+ */
+interface PptxHandoutMaster {
+  /** File path within the PPTX archive. */
+  path: string;
+  /** Background colour of the handout master. */
+  backgroundColor?: string;
+  /** Background image data URL. */
+  backgroundImage?: string;
+  /** Crop, tiling and image effects authored on the background blip fill. */
+  backgroundImageProperties?: PptxImageProperties;
+  /** Placeholder shapes found on the handout master. */
+  placeholders?: PptxPlaceholderFrame[];
+  /** Editable elements on the handout master (header, footer, date, page number, slide placeholders). */
+  elements?: PptxElement[];
+  /** Number of slides per page for handout print layout (1, 2, 3, 4, 6, or 9). */
+  slidesPerPage?: number;
+  /** Header/footer flags from `<p:hf>` on the handout master (P-H3). */
+  headerFooter?: PptxHeaderFooterFlags;
+  /** Colour map from `<p:clrMap>` (12 alias attributes). Applied at save time. */
+  clrMap?: Record<string, string>;
+}
+/**
+ * Active tab within the master view sidebar.
+ *
+ * @example
+ * ```ts
+ * const tab: MasterViewTab = "slides";
+ * // => "slides" — one of: "slides" | "notes" | "handout"
+ * ```
+ */
+type MasterViewTab = 'slides' | 'notes' | 'handout';
+/**
+ * Structured slide master data.
+ *
+ * @example
+ * ```ts
+ * const master: PptxSlideMaster = {
+ *   path: "ppt/slideMasters/slideMaster1.xml",
+ *   name: "Office Theme",
+ *   backgroundColor: "#FFFFFF",
+ *   themePath: "ppt/theme/theme1.xml",
+ * };
+ * // => satisfies PptxSlideMaster
+ * ```
+ */
+interface PptxSlideMaster {
+  /** File path within the PPTX archive. */
+  path: string;
+  /** Human-readable name if available. */
+  name?: string;
+  /** Background colour of the slide master. */
+  backgroundColor?: string;
+  /** Background image data URL for the slide master. */
+  backgroundImage?: string;
+  /** Crop, tiling and image effects authored on the background blip fill. */
+  backgroundImageProperties?: PptxImageProperties;
+  /** Theme file path this master references. */
+  themePath?: string;
+  /** Layout paths associated with this master. */
+  layoutPaths?: string[];
+  /** Placeholder shapes on the master. */
+  placeholders?: PptxPlaceholderFrame[];
+  /** Parsed element shapes on the master slide (for master view rendering). */
+  elements?: PptxElement[];
+  /** Parsed slide layout objects associated with this master. */
+  layouts?: PptxSlideLayout[];
+  /** Text styles from `p:txStyles` — title, body, and other text defaults. */
+  txStyles?: PptxMasterTextStyles;
+  /** Header/footer flags from `<p:hf>` on this master (P-H3). */
+  headerFooter?: PptxHeaderFooterFlags;
+  /**
+   * Colour map from `<p:clrMap>` (12 alias attributes: bg1/tx1/bg2/tx2,
+   * accent1-6, hlink, folHlink). Applied at save time when present.
+   */
+  clrMap?: Record<string, string>;
+  /**
+   * Whether the master is marked as preserved (prevent auto-deletion,
+   * `@preserve`). Mirrors {@link PptxSlideLayout.preserve}: PowerPoint
+   * silently drops an unused master unless this is set.
+   *
+   * ECMA-376 §19.3.1.38 (CT_SlideMaster).
+   */
+  preserve?: boolean;
+}
+/**
+ * Per-level paragraph properties for a text style category.
+ * Each entry maps a 0-based level index to its style defaults.
+ */
+type PptxTextStyleLevels = Record<number, PlaceholderTextLevelStyle>;
+/**
+ * Text styles parsed from `p:txStyles` on a slide master.
+ * Provides cascading defaults for title, body, and other text.
+ */
+interface PptxMasterTextStyles {
+  /** Title text style (`p:titleStyle`). */
+  titleStyle?: PptxTextStyleLevels;
+  /** Body text style (`p:bodyStyle`). */
+  bodyStyle?: PptxTextStyleLevels;
+  /** Other text style (`p:otherStyle`). */
+  otherStyle?: PptxTextStyleLevels;
+}
+/**
+ * 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;
+}
+/**
+ * A slide layout associated with a slide master.
+ *
+ * @example
+ * ```ts
+ * const layout: PptxSlideLayout = {
+ *   path: "ppt/slideLayouts/slideLayout2.xml",
+ *   name: "Title and Content",
+ * };
+ * // => satisfies PptxSlideLayout
+ * ```
+ */
+interface PptxSlideLayout {
+  /** File path within the PPTX archive. */
+  path: string;
+  /** Human-readable layout name. */
+  name?: string;
+  /** Background colour of the layout. */
+  backgroundColor?: string;
+  /** Background image data URL for the layout. */
+  backgroundImage?: string;
+  /** Crop, tiling and image effects authored on the background blip fill. */
+  backgroundImageProperties?: PptxImageProperties;
+  /** Parsed element shapes on the layout. */
+  elements?: PptxElement[];
+  /** Placeholder shapes on the layout. */
+  placeholders?: PptxPlaceholderFrame[];
+  /** Matching name attribute for layout identification (`@matchingName`). */
+  matchingName?: string;
+  /** Whether the layout is marked as preserved (prevent deletion, `@preserve`). */
+  preserve?: boolean;
+  /** Whether master placeholder animations should play (`@showMasterPhAnim`). */
+  showMasterPhAnim?: boolean;
+  /** Whether this layout is user-drawn (`@userDrawn`). */
+  userDrawn?: boolean;
+  /** Colour map override from `p:clrMapOvr`. */
+  clrMapOverride?: Record<string, string>;
+  /** Header/footer flags from `<p:hf>` on this layout (P-H3). */
+  headerFooter?: PptxHeaderFooterFlags;
+}
+/**
+ * Rendered content of a single layout, used to draw gallery thumbnails.
+ *
+ * Produced on demand rather than during load: materialising every layout's
+ * artwork (and decoding its images) up front costs a noticeable amount of time
+ * on decks with many masters, and most sessions never open the layout gallery
+ * at all.
+ *
+ * @example
+ * ```ts
+ * const preview: PptxLayoutPreview = {
+ *   path: "ppt/slideLayouts/slideLayout2.xml",
+ *   width: 960,
+ *   height: 540,
+ *   elements: [],
+ *   placeholders: [{ type: "title" }],
+ * };
+ * // => satisfies PptxLayoutPreview
+ * ```
+ */
+interface PptxLayoutPreview {
+  /** ZIP path of the layout this preview belongs to. */
+  path: string;
+  /** Slide width in CSS pixels, so a thumbnail can compute its own scale. */
+  width: number;
+  /** Slide height in CSS pixels. */
+  height: number;
+  /** Background resolved from the layout, falling back to its master's. */
+  backgroundColor?: string;
+  /** Background image data URL, when the layout or master declares one. */
+  backgroundImage?: string;
+  /** Crop, tiling and image effects authored on the resolved background image. */
+  backgroundImageProperties?: PptxImageProperties;
+  /** The layout's own artwork (pictures, shapes and static text). */
+  elements: PptxElement[];
+  /** Placeholder slots, drawn as outlined frames in the gallery. */
+  placeholders: PptxPlaceholderFrame[];
+}
+/**
+ * A theme part available in the presentation package.
+ *
+ * @example
+ * ```ts
+ * const opt: PptxThemeOption = {
+ *   path: "ppt/theme/theme1.xml",
+ *   name: "Office Theme",
+ * };
+ * // => satisfies PptxThemeOption
+ * ```
+ */
+interface PptxThemeOption {
+  /** File path within the PPTX archive (e.g. `ppt/theme/theme2.xml`). */
+  path: string;
+  /** Human-readable theme name from `a:theme/@name`, when present. */
+  name?: string;
+}
+//#endregion
+//#region pptx/core/types/embedded-font.d.ts
+interface PptxEmbeddedFontDataId {
+  /** Required relationship identifier from `r:id`. */
+  relationshipId?: string | null;
+  /** Original leaf retained for unknown attribute preservation. */
+  rawXml?: XmlObject;
+}
+interface PptxEmbeddedFontDescriptor {
+  typeface?: string | null;
+  panose?: string | null;
+  pitchFamily?: string | null;
+  charset?: string | null;
+  rawXml?: XmlObject;
+}
+interface PptxEmbeddedFontListEntry {
+  font: PptxEmbeddedFontDescriptor;
+  regular?: PptxEmbeddedFontDataId | null;
+  bold?: PptxEmbeddedFontDataId | null;
+  italic?: PptxEmbeddedFontDataId | null;
+  boldItalic?: PptxEmbeddedFontDataId | null;
+  rawXml?: XmlObject;
+}
+interface PptxEmbeddedFontList {
+  fonts: PptxEmbeddedFontListEntry[];
+  /** Original list retained for unknown attribute and child preservation. */
+  rawXml?: XmlObject;
+}
+//#endregion
+//#region pptx/core/types/presentation-print-properties.d.ts
+type PptxPrintOutput = 'slides' | 'handouts1' | 'handouts2' | 'handouts3' | 'handouts4' | 'handouts6' | 'handouts9' | 'notes' | 'outline';
+type PptxPrintColorMode = 'bw' | 'gray' | 'clr';
+/** PresentationML `CT_PrintProperties` (`p:prnPr`). */
+interface PptxPresentationPrintProperties {
+  printWhat?: PptxPrintOutput | null;
+  colorMode?: PptxPrintColorMode | null;
+  hiddenSlides?: boolean | null;
+  scaleToFitPaper?: boolean | null;
+  frameSlides?: boolean | null;
+  /** Original subtree retained for unknown attributes and `p:extLst`. */
+  rawXml?: XmlObject;
+}
+//#endregion
+//#region pptx/core/types/view-properties.d.ts
+/**
+ * View properties types parsed from `ppt/viewProps.xml`.
+ *
+ * Models the `p:viewPr` element and its child views:
+ * normalViewPr, slideViewPr, outlineViewPr, notesTextViewPr,
+ * sorterViewPr, notesViewPr.
+ *
+ * @module pptx-types/view-properties
+ */
+/**
+ * Scale factor for a view (numerator / denominator percentage).
+ */
+interface PptxViewScale {
+  /** Numerator of the scale percentage (e.g. 100 for 100%). */
+  n: number;
+  /** Denominator of the scale percentage (e.g. 100 for 100%). */
+  d: number;
+  /** Optional independent vertical scale. When absent, the X scale is used. */
+  sy?: {
+    n: number;
+    d: number;
+  };
+}
+/**
+ * Origin point for a view (x, y in twips or EMU).
+ */
+interface PptxViewOrigin {
+  x: number;
+  y: number;
+}
+/** A horizontal or vertical drawing guide in slide coordinates. */
+interface PptxViewGuide {
+  orientation?: 'horz' | 'vert';
+  position?: number;
+}
+/** Positive grid spacing from `p:gridSpacing`. */
+interface PptxGridSpacing {
+  cx: number;
+  cy: number;
+}
+/**
+ * Restored region dimensions for normal view splitter.
+ * Represents `p:restoredLeft` or `p:restoredTop`.
+ */
+interface PptxRestoredRegion {
+  /** Size as a percentage of the available space (thousandths of a percent). */
+  sz: number;
+  /** Whether auto-adjust is enabled. */
+  autoAdjust?: boolean;
+}
+/**
+ * Normal view properties (`p:normalViewPr`).
+ * Controls the splitter positions in normal (editing) view.
+ */
+interface PptxNormalViewProperties {
+  /** Whether to show outline icons in the slide panel. */
+  showOutlineIcons?: boolean;
+  /** Whether the outline/slide panel is snapped closed. */
+  snapVertSplitter?: boolean;
+  /** Vertical splitter bar state: 'minimized' | 'maximized' | 'restored'. */
+  vertBarState?: string;
+  /** Horizontal splitter bar state. */
+  horzBarState?: string;
+  /** Whether to prefer single-slide view in the panel. */
+  preferSingleView?: boolean;
+  /** Restored left region (slide panel width). */
+  restoredLeft?: PptxRestoredRegion;
+  /** Restored top region (notes panel height). */
+  restoredTop?: PptxRestoredRegion;
+}
+/**
+ * Common slide view properties shared by slideViewPr, outlineViewPr,
+ * notesTextViewPr, and notesViewPr.
+ */
+interface PptxCommonSlideViewProperties {
+  /** Whether snap-to-grid is enabled. */
+  snapToGrid?: boolean;
+  /** Whether snap-to-objects is enabled. */
+  snapToObjects?: boolean;
+  /** Whether drawing guides are shown. */
+  showGuides?: boolean;
+  /** Whether the application may vary the scale automatically. */
+  variableScale?: boolean;
+  /** Drawing guides shown in this slide view. */
+  guides?: PptxViewGuide[];
+  /** View origin (scroll position). */
+  origin?: PptxViewOrigin;
+  /** View scale. */
+  scale?: PptxViewScale;
+}
+/**
+ * Full view properties from `ppt/viewProps.xml`.
+ */
+interface PptxViewProperties {
+  /** Last used view type (`p:viewPr/@lastView`). */
+  lastView?: string;
+  /** Whether comments are shown (`p:viewPr/@showComments`). */
+  showComments?: boolean;
+  /** Normal view properties (splitter positions). */
+  normalViewPr?: PptxNormalViewProperties;
+  /** Slide view properties. */
+  slideViewPr?: PptxCommonSlideViewProperties;
+  /** Outline view properties. */
+  outlineViewPr?: PptxCommonSlideViewProperties;
+  /** Notes text view properties. */
+  notesTextViewPr?: PptxCommonSlideViewProperties;
+  /** Sorter view scale. */
+  sorterViewPr?: {
+    scale?: PptxViewScale;
+  };
+  /** Notes view properties. */
+  notesViewPr?: PptxCommonSlideViewProperties;
+  /** Grid spacing in positive DrawingML coordinates. */
+  gridSpacing?: PptxGridSpacing;
+  /** Raw XML preserved for lossless round-trip of unparsed attributes. */
+  rawXml?: Record<string, unknown>;
+}
+//#endregion
+//#region pptx/core/types/presentation.d.ts
+/**
+ * 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. `customXml/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;
+  /** OPC content type for the custom data part. */
+  contentType?: string;
+  /** Raw `p:custData` XML retained for unknown-node preservation. */
+  rawXml?: XmlObject;
+}
+/**
+ * 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;
+  /**
+   * `p:control/@showAsIcon` (CT_Control, ECMA-376 S19.3.1.2): whether the
+   * control renders as its static icon rather than its live appearance.
+   * `undefined` when the source authored no explicit value (schema default
+   * `false`).
+   */
+  showAsIcon?: boolean;
+  /**
+   * `p:control/@imgW` in EMU (ST_PositiveCoordinate32): the width the host
+   * reserves for the control's icon/preview image. Distinct from
+   * {@link width}, which is the fallback `p:pic`'s own `a:ext/@cx` in px;
+   * `imgW`/`imgH` are direct attributes on `p:control` itself.
+   */
+  imgWidthEmu?: number;
+  /** `p:control/@imgH` in EMU (ST_PositiveCoordinate32). @see imgWidthEmu */
+  imgHeightEmu?: number;
+  /** X position (px) of the control's fallback picture, if present. */
+  x?: number;
+  /** Y position (px) of the control's fallback picture, if present. */
+  y?: number;
+  /** Width (px) of the control's fallback picture, if present. */
+  width?: number;
+  /** Height (px) of the control's fallback picture, if present. */
+  height?: number;
+  /**
+   * Relationship ID of the control's static fallback picture
+   * (`mc:AlternateContent > mc:Fallback > p:pic > p:blipFill > a:blip@r:embed`).
+   * Renderers resolve this to an image so a control shows its last static
+   * frame instead of a blank area (the live ActiveX cannot run in a viewer).
+   */
+  fallbackImageRelId?: string;
+  /** Raw XML for round-trip preservation. */
+  rawXml?: XmlObject;
+}
+/**
+ * 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;
+}
+/**
+ * A single slide in a parsed PPTX presentation.
+ *
+ * Contains the element tree, background settings, notes, comments,
+ * transition / animation data, and metadata like layout path and section.
+ *
+ * @example
+ * ```ts
+ * const slide: PptxSlide = {
+ *   id: "slide1",
+ *   rId: "rId2",
+ *   slideNumber: 1,
+ *   elements: [titleTextBox, subtitleTextBox],
+ *   backgroundColor: "#FFFFFF",
+ *   notes: "Remember to mention quarterly goals.",
+ * };
+ * // => satisfies PptxSlide
+ * ```
+ */
+interface PptxSlide {
+  id: string;
+  rId: string;
+  /**
+   * `p:sldIdLst/p:sldId/@id` (ST_SlideId, 256..2147483647): the numeric key
+   * that sections (`p14:sldIdLst/p14:sldId/@id`) and section/summary zooms
+   * name slides by.
+   *
+   * It lives in `presentation.xml`, NOT in the slide part, so it cannot be
+   * recovered from `rawXml`. Without it on the model, code that writes a
+   * section's membership has nothing correct to write and falls back to the
+   * slide NUMBER, which is 1-based and therefore never matches a real deck's
+   * ids: the section reloads with no slides in it.
+   */
+  slideId?: string;
+  sourceSlideId?: string;
+  /**
+   * The slide name, `p:cSld/@name`: loaded from the part, written back on
+   * save (an empty string clears the attribute), and settable via
+   * `SlideBuilder.setName`.
+   */
+  name?: string;
+  layoutPath?: string;
+  layoutName?: string;
+  slideNumber: number;
+  hidden?: boolean;
+  sectionName?: string;
+  sectionId?: string;
+  elements: PptxElement[];
+  backgroundColor?: string;
+  backgroundImage?: string;
+  /** Crop, tiling and image effects authored on the background blip fill. */
+  backgroundImageProperties?: PptxImageProperties;
+  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
+   * anchor the background gradient on the title placeholder as a
+   * rectangular path gradient (COM-measured against real PowerPoint;
+   * it does NOT recolour toward the title's text colour, despite the
+   * attribute's name). Parsed and round-tripped here on the core model;
+   * the actual visual effect is applied by `pptx-viewer-shared`'s
+   * `getSlideBackgroundStyle` (see `render/background-shade-to-title.ts`),
+   * consumed by all five bindings, not by core itself. Legacy PowerPoint
+   * 97-2003 hint, not observed in any real-world corpus file this project
+   * has collected and not settable from any modern PowerPoint UI; see
+   * `docs/guide/limitations.md`.
+   *
+   * ECMA-376 §19.3.1.2 (CT_BackgroundProperties).
+   */
+  backgroundShadeToTitle?: boolean;
+  transition?: PptxSlideTransition;
+  animations?: PptxElementAnimation[];
+  /**
+   * Read-only anchors for the deck's own (non-editor-authored) effect
+   * groups, merged with `animations` by the authoring UI so drag-to-reorder
+   * can target any position in the full sequence. See
+   * {@link PptxAnimationTimelineAnchor}.
+   */
+  animationTimelineAnchors?: PptxAnimationTimelineAnchor[];
+  /** 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;
+  /**
+   * Whether inherited master placeholder animations should replay on this
+   * slide (`p:sld/@showMasterPhAnim`). Distinct from {@link showMasterShapes}:
+   * this governs animation timing, not shape visibility. Mirrors
+   * `p:sldLayout/@showMasterPhAnim`, ECMA-376 §19.3.1.38.
+   */
+  showMasterPhAnim?: 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[];
+  /**
+   * Shapes parsed from a referenced legacy VML drawing part
+   * (`ppt/drawings/vmlDrawing*.vml`, linked via a `legacyDrawing`
+   * relationship). These are read-only render hints: the VML part itself is
+   * preserved verbatim on save, so this field is not re-serialized.
+   */
+  legacyVmlElements?: PptxElement[];
+  /** 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;
+}
+interface PptxModernCommentPart {
+  path: string;
+  relationshipId: string;
+  /** Original p188:cmLst root, including unknown attributes and extensions. */
+  rawXml?: XmlObject;
+}
+/** 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;
+}
+/**
+ * A slide layout available in the loaded presentation.
+ *
+ * Each entry maps to a `<p:sldLayout>` inside `ppt/slideLayouts/`.
+ *
+ * @example
+ * ```ts
+ * const layout: PptxLayoutOption = {
+ *   path: "ppt/slideLayouts/slideLayout2.xml",
+ *   name: "Title and Content",
+ * };
+ * // => satisfies PptxLayoutOption
+ * ```
+ */
+interface PptxLayoutOption {
+  path: string;
+  name: string;
+  /** Standard layout type from `p:sldLayout/@type` (e.g. "obj", "twoColTx", "blank"). */
+  type?: string;
+  /** ZIP path of the slide master this layout belongs to. */
+  masterPath?: string;
+}
+/**
+ * Header, footer, date-time, and slide-number placeholders.
+ *
+ * Parsed from `ppt/presProps.xml` and individual slide layouts.
+ *
+ * @example
+ * ```ts
+ * const hf: PptxHeaderFooter = {
+ *   hasFooter: true,
+ *   footerText: "Confidential",
+ *   hasSlideNumber: true,
+ * };
+ * // => satisfies PptxHeaderFooter
+ * ```
+ */
+interface PptxHeaderFooter {
+  hasHeader?: boolean;
+  headerText?: string;
+  hasFooter?: boolean;
+  footerText?: string;
+  hasDateTime?: boolean;
+  dateTimeText?: string;
+  dateTimeAuto?: boolean;
+  /**
+   * The master date placeholder's own `a:fld/@type` (e.g. "datetime2"), NOT a
+   * format pattern. It is one of the predefined OOXML datetime field types
+   * (`datetime1`-`datetime13`); the display pattern for each is resolved by
+   * `resolveFieldDateText` in `packages/shared/src/render/text-field-substitution.ts`.
+   */
+  dateFormat?: string;
+  hasSlideNumber?: boolean;
+}
+/**
+ * Presentation-level properties parsed from `presentationPr.xml`.
+ *
+ * Controls slideshow behaviour, print settings, custom colours, and grid.
+ *
+ * @example
+ * ```ts
+ * const props: PptxPresentationProperties = {
+ *   showType: "presented",
+ *   loopContinuously: false,
+ *   advanceMode: "useTimings",
+ * };
+ * // => satisfies PptxPresentationProperties
+ * ```
+ */
+interface PptxPresentationProperties {
+  /** Show type: presented, browsed, kiosk. */
+  showType?: 'presented' | 'browsed' | 'kiosk';
+  /** Whether to loop the slideshow continuously. */
+  loopContinuously?: boolean;
+  /** Whether to show without narration. */
+  showWithNarration?: boolean;
+  /** Whether to show without animation. */
+  showWithAnimation?: boolean;
+  /** Advance slides mode: manual click or use stored timings. */
+  advanceMode?: 'manual' | 'useTimings';
+  /** Show slides: 'all', a custom show id, or a from-to range. */
+  showSlidesMode?: 'all' | 'customShow' | 'range';
+  /** Custom show id to use when showSlidesMode is 'customShow'. */
+  showSlidesCustomShowId?: string;
+  /** Slide range start (1-based) when showSlidesMode is 'range'. */
+  showSlidesFrom?: number;
+  /** Slide range end (1-based) when showSlidesMode is 'range'. */
+  showSlidesTo?: number;
+  /** Whether to show subtitles/captions during presentation mode. */
+  showSubtitles?: boolean;
+  /** Typed `p:prnPr` settings. Set to null during save to remove the element. */
+  printProperties?: PptxPresentationPrintProperties | null;
+  /** Most-recently-used colours from the presentation palette. */
+  mruColors?: string[];
+  /**
+   * Pen colour for presentation mode annotations (from `p:showPr/p:penClr`).
+   * `p:penClr` is a full `EG_ColorChoice` (P1-G2): a scheme/preset/system
+   * swatch resolves to a hex string here just like a direct `a:srgbClr`.
+   */
+  penColor?: string;
+  /**
+   * The resolved hex value {@link penColor} had at parse time, and the
+   * original `p:penClr` colour-choice XML node, preserved so a save that
+   * never touches the pen colour re-emits the original scheme/preset
+   * reference verbatim instead of flattening it to a baked `a:srgbClr`.
+   * Internal round-trip bookkeeping; not meant to be set by API callers.
+   */
+  penColorOriginal?: string;
+  /** @see penColorOriginal */
+  penColorXml?: XmlObject;
+  /** Kiosk auto-restart interval in milliseconds (from `p:kiosk/@restart`). Only meaningful when showType is "kiosk". */
+  kioskRestartTime?: number;
+  /**
+   * `p:showPr/p:browse/@showScrollbar` (CT_ShowInfoBrowse §19.2.1.10 /
+   * §19.3.1.43), the "Show scrollbar" checkbox in PowerPoint's Set Up Show
+   * dialog. Only meaningful when `showType` is `"browsed"`; the schema
+   * default is `true`. `undefined` means the source authored no explicit
+   * value (or `showType` is not `"browsed"`).
+   */
+  showScrollbar?: boolean;
+}
+/**
+ * Slide dimensions from `p:sldSz` (CT_SlideSize, ECMA-376 §19.2.1.39).
+ *
+ * @example
+ * ```ts
+ * const size: PptxSlideSize = { widthEmu: 9144000, heightEmu: 6858000, type: 'screen4x3' };
+ * // => satisfies PptxSlideSize
+ * ```
+ */
+interface PptxSlideSize {
+  /** `@cx` in EMU. Omitted or non-positive values leave the loaded width alone. */
+  widthEmu?: number;
+  /** `@cy` in EMU. Omitted or non-positive values leave the loaded height alone. */
+  heightEmu?: number;
+  /**
+   * `@type` (ST_SlideSizeType). The schema default is `custom`, which is
+   * why PowerPoint omits the attribute for a non-preset size.
+   */
+  type?: string;
+}
+/**
+ * A named custom slide show (`p:custShowLst / p:custShow`).
+ *
+ * Custom shows define ordered subsets of slides that can be presented
+ * independently of the full deck.
+ *
+ * @example
+ * ```ts
+ * const show: PptxCustomShow = {
+ *   name: "Executive Summary",
+ *   id: "0",
+ *   slideRIds: ["rId2", "rId5", "rId8"],
+ * };
+ * // => satisfies PptxCustomShow
+ * ```
+ */
+interface PptxCustomShow {
+  /** Custom show name. */
+  name: string;
+  /** Custom show id. */
+  id: string;
+  /** Ordered list of slide relationship IDs included in this custom show. */
+  slideRIds: string[];
+  /** Original `p:custShow` subtree used to preserve unmodelled attributes and extensions. */
+  rawXml?: XmlObject;
+}
+/**
+ * An ordered section in the presentation (from `p:sectionLst` / `p14:sectionLst`).
+ *
+ * Sections group consecutive slides under a named heading (visible
+ * in the PowerPoint slide sorter).
+ *
+ * @example
+ * ```ts
+ * const section: PptxSection = {
+ *   id: "sec_1",
+ *   name: "Introduction",
+ *   slideIds: ["256", "257"],
+ * };
+ * // => satisfies PptxSection
+ * ```
+ */
+interface PptxSection {
+  /** Section unique identifier (GUID or synthetic). */
+  id: string;
+  /** Human-readable section name. */
+  name: string;
+  /** Ordered list of numeric slide IDs that belong to this section. */
+  slideIds: string[];
+  /** Whether the section is collapsed in the slide sorter (from p15:sectionPr). */
+  collapsed?: boolean;
+  /** Section highlight color hex (from p15:sectionPr/@clr). */
+  color?: string;
+  /** Original section subtree used to preserve unmodelled attributes and extensions. */
+  rawXml?: XmlObject;
+}
+/**
+ * Write-protection hash data parsed from `p:modifyVerifier` in `presentation.xml`.
+ *
+ * When present, the presentation is marked as "read-only recommended" or
+ * write-protected with a password hash.  The hash parameters follow the
+ * ECMA-376 Part 1, section 19.2.1.22 specification.
+ *
+ * @example
+ * ```ts
+ * const verifier: PptxModifyVerifier = {
+ *   algorithmName: "SHA-512",
+ *   hashData: "base64EncodedHash==",
+ *   saltData: "base64EncodedSalt==",
+ *   spinValue: 100000,
+ * };
+ * // => satisfies PptxModifyVerifier
+ * ```
+ */
+interface PptxModifyVerifier {
+  /** Hash algorithm name (e.g. "SHA-512", "SHA-1"). */
+  algorithmName?: string;
+  /** Base64-encoded hash value. */
+  hashData?: string;
+  /** Base64-encoded salt value. */
+  saltData?: string;
+  /** Number of hash iterations (spin count). */
+  spinValue?: number;
+  /** Legacy algorithm ID extension. */
+  algIdExt?: string;
+  /** Legacy algorithm ID. */
+  cryptAlgorithmSid?: number;
+  /** Cryptographic algorithm type (e.g. "typeAny"). */
+  cryptAlgorithmType?: string;
+  /** Cryptographic provider name. */
+  cryptProvider?: string;
+  /** Cryptographic provider type (e.g. "providerTypeRsaFull"). */
+  cryptProviderType?: string;
+  /** Cryptographic algorithm class (e.g. "hash"). */
+  cryptAlgorithmClass?: string;
+}
+/**
+ * Photo album metadata from `p:photoAlbum` in `presentation.xml`.
+ *
+ * Stores settings for presentations created via Insert > Photo Album.
+ *
+ * @see ECMA-376 Part 1, §19.2.1.27
+ */
+interface PptxPhotoAlbum {
+  /** Whether photos are displayed in black-and-white. */
+  bw?: boolean;
+  /** Whether captions are shown below each photo. */
+  showCaptions?: boolean;
+  /** Photo album layout (e.g. "1pic", "2pic", "4pic", "fitToSlide"). */
+  layout?: string;
+  /** Frame style applied to each photo (e.g. "frameStyle1"). */
+  frame?: string;
+  /**
+   * `p:photoAlbum/@isPhoto` (ECMA-376 S19.2.1.27, CT_PhotoAlbum): whether
+   * the pictures placed by the album wizard are real photographs, as
+   * opposed to clip art or other embedded images. `undefined` when the
+   * source authored no explicit value (schema default `false`); this is a
+   * purely declarative wizard-provenance flag, not something this library
+   * gates any layout/frame behaviour on.
+   */
+  isPhoto?: boolean;
+}
+/**
+ * A recognizer-owned `p:smartTags` reference from `presentation.xml`
+ * (CT_SmartTags, ECMA-376 S19.2.1.42): a bare relationship id pointing at a
+ * legacy Office "Smart Tags" recognizer part, distinct from the
+ * user-authored `p:tags` construct (see {@link PptxTagCollection}).
+ *
+ * This library has no data model for recognizer part CONTENT (there is no
+ * way to create, inspect, or edit one through the public API), so this type
+ * only captures enough to preserve an authored reference losslessly: the
+ * relationship id and, when resolvable, the target part path.
+ */
+interface PptxSmartTagsReference {
+  /** Relationship id from `p:smartTags/@r:id`. */
+  relId: string;
+  /** Resolved ZIP path of the referenced recognizer part, when resolvable. */
+  targetPath?: string;
+  /** Raw `p:smartTags` XML retained for lossless round-trip. */
+  rawXml?: XmlObject;
+}
+/**
+ * East Asian line-break (kinsoku) settings from `p:kinsoku` in `presentation.xml`.
+ *
+ * Defines forbidden start/end characters for a given language so that
+ * line-breaking follows East Asian typographic rules.
+ *
+ * @see ECMA-376 Part 1, §19.2.1.17
+ */
+interface PptxKinsoku {
+  /** Language code (e.g. "ja-JP", "zh-CN"). */
+  lang?: string | null;
+  /** Characters that cannot begin a line. */
+  invalStChars?: string;
+  /** Characters that cannot end a line. */
+  invalEndChars?: string;
+  /** Original leaf retained for unknown attribute preservation. */
+  rawXml?: XmlObject;
+}
+/**
+ * Root data structure returned by {@link PptxHandlerCore.load}.
+ *
+ * Contains every slide, canvas dimensions, theme data, layout options,
+ * metadata, and optional features (custom shows, sections, macros,
+ * digital signatures, embedded fonts).
+ *
+ * @example
+ * ```ts
+ * const data: PptxData = await handler.load(buffer);
+ * console.log(`${data.slides.length} slides, ${data.width}×${data.height}`);
+ * // => e.g. "24 slides, 960×540"
+ * ```
+ */
+interface PptxData {
+  slides: PptxSlide[];
+  width: number;
+  height: number;
+  /** Slide width in EMU (for save round-trip). */
+  widthEmu?: number;
+  /** Slide height in EMU (for save round-trip). */
+  heightEmu?: number;
+  /** Slide size type from `p:sldSz/@type` (e.g. "screen4x3", "screen16x9", "custom"). */
+  slideSizeType?: string;
+  /** Notes page width in EMU (from `p:notesSz`). */
+  notesWidthEmu?: number;
+  /** Notes page height in EMU (from `p:notesSz`). */
+  notesHeightEmu?: number;
+  layoutOptions?: PptxLayoutOption[];
+  headerFooter?: PptxHeaderFooter;
+  /** Presentation-level properties parsed from `presentationPr.xml`. */
+  presentationProperties?: PptxPresentationProperties;
+  /** Named custom slide shows from `p:custShowLst`. */
+  customShows?: PptxCustomShow[];
+  /** Ordered presentation sections from `p:sectionLst` / `p14:sectionLst`. */
+  sections?: PptxSection[];
+  warnings?: PptxCompatibilityWarning[];
+  /** Map of theme colour scheme keys to resolved hex values. */
+  themeColorMap?: Record<string, string>;
+  /** Full parsed theme object with colours, fonts, and name. */
+  theme?: PptxTheme;
+  /** Available theme parts discovered in `ppt/theme/`. */
+  themeOptions?: PptxThemeOption[];
+  /** Parsed table style definitions from `ppt/tableStyles.xml`. */
+  tableStyleMap?: ParsedTableStyleMap;
+  /**
+   * The current default table style GUID (`ppt/tableStyles.xml`'s
+   * `a:tblStyleLst/@def`): the style PowerPoint applies to a newly inserted
+   * table. Matches `PptxSaveOptions.tableStylesDefaultId` so a save call
+   * that omits it can fall back to what was loaded.
+   */
+  tableStylesDefaultId?: string;
+  /** Whether the presentation is password-protected. */
+  isPasswordProtected?: boolean;
+  /** Embedded font data (name + binary data URL) extracted from the presentation. */
+  embeddedFonts?: PptxEmbeddedFont[];
+  /** Typed `p:embeddedFontLst` package metadata, including unresolved variants. */
+  embeddedFontList?: PptxEmbeddedFontList;
+  /**
+   * `p:presentation/@embedTrueTypeFonts` (ECMA-376 §19.2.1.26): the author's
+   * saved preference that TrueType fonts referenced by the deck be embedded.
+   * `undefined` when the attribute is absent (spec default `false`).
+   *
+   * This is purely declarative in this library: fonts are only ever embedded
+   * when the caller explicitly supplies `embeddedFontList`/`embeddedFonts`
+   * (there is no automatic embed-on-save), so toggling this flag does not
+   * gate any embedding behaviour of its own here - it only round-trips the
+   * author's stated preference, the same way real PowerPoint reads it back
+   * as a checkbox state rather than a trigger. See `@saveSubsetFonts`,
+   * which is a separate, deliberately unimplemented flag (no glyph
+   * subsetting) that does not interact with this one.
+   */
+  embedTrueTypeFonts?: boolean;
+  /**
+   * `p:presentation/@firstSlideNum`: a `slidenum` field on slide `i` (0-based)
+   * shows `firstSlideNumber + i`. Absent means the spec default, 1.
+   */
+  firstSlideNumber?: number;
+  /**
+   * Presentation-level default text style (`p:defaultTextStyle`): the
+   * last-resort paragraph/run-property fallback for every shape (placeholder
+   * or not) whose local and inherited cascade leaves a field undefined.
+   * Keyed the same way as {@link PptxMasterTextStyles} categories: `-1` is
+   * `a:defPPr`, `0`-`8` are `a:lvl1pPr`-`a:lvl9pPr`.
+   */
+  defaultTextStyle?: PptxTextStyleLevels;
+  /** Most-recently-used colour list from presentation properties. */
+  mruColors?: string[];
+  /** Parsed notes master data if present in the PPTX. */
+  notesMaster?: PptxNotesMaster;
+  /** Parsed handout master data if present in the PPTX. */
+  handoutMaster?: PptxHandoutMaster;
+  /** Structured slide master data for each master in the presentation. */
+  slideMasters?: PptxSlideMaster[];
+  /** Parsed tag collections attached to the presentation or slides. */
+  tags?: PptxTagCollection[];
+  /** Custom document properties from `docProps/custom.xml`. */
+  customProperties?: PptxCustomProperty[];
+  /** Core document properties from `docProps/core.xml`. */
+  coreProperties?: PptxCoreProperties;
+  /** Extended (application) properties from `docProps/app.xml`. */
+  appProperties?: PptxAppProperties;
+  /** Whether the presentation contains VBA macros (is a .pptm file). */
+  hasMacros?: boolean;
+  /** Whether the presentation contains digital signatures (`_xmlsignatures/` parts). */
+  hasDigitalSignatures?: boolean;
+  /** Number of digital signatures found. */
+  digitalSignatureCount?: number;
+  /** Presentation-level drawing guides from `p:extLst`. */
+  presentationGuides?: PptxDrawingGuide[];
+  /** View properties from `ppt/viewProps.xml`. */
+  viewProperties?: PptxViewProperties;
+  /** Write-protection verifier from `p:modifyVerifier` in `presentation.xml`. */
+  modifyVerifier?: PptxModifyVerifier;
+  /** Photo album metadata from `p:photoAlbum` in `presentation.xml`. */
+  photoAlbum?: PptxPhotoAlbum;
+  /**
+   * Legacy Smart Tags recognizer reference from `p:smartTags` in
+   * `presentation.xml`. Read-only: there is no data model for the
+   * recognizer part's own content, so this exists to make the reference
+   * inspectable and to prove it survives a save (the owning part and its
+   * relationship are preserved passively, like any other unmodelled part).
+   */
+  smartTags?: PptxSmartTagsReference;
+  /** East Asian line-break settings from `p:kinsoku` in `presentation.xml`. */
+  kinsoku?: PptxKinsoku;
+  /** Custom XML data parts from `customXml/` in the OPC package. */
+  customXmlParts?: PptxCustomXmlPart[];
+  /** Customer data references from `p:custDataLst` in `presentation.xml`. */
+  customerData?: PptxCustomerData[];
+  /** Thumbnail image binary data from `docProps/thumbnail.{jpeg,png}`. */
+  thumbnailData?: Uint8Array;
+  /** Comment authors parsed from `ppt/commentAuthors.xml` for round-trip preservation. */
+  commentAuthors?: PptxCommentAuthor[];
+  /** Office 2021 p188 authors from the modern Author part. */
+  modernCommentAuthors?: PptxModernCommentAuthor[];
+  /**
+   * OOXML conformance class of the loaded file.
+   * - `'strict'` -- ISO/IEC 29500 Strict (uses `purl.oclc.org` namespace URIs)
+   * - `'transitional'` -- ECMA-376 Transitional (uses `schemas.openxmlformats.org` URIs)
+   *
+   * When saving, if the save option `conformance` is `'preserve'` (default),
+   * the file will be saved using the same conformance class as the original.
+   */
+  conformance?: 'strict' | 'transitional';
+}
+/**
+ * Target format for slide export.
+ *
+ * @see {@link PptxExportOptions}
+ */
+type PptxExportFormat = 'pdf' | 'png' | 'svg';
+/**
+ * Options controlling slide export to raster or vector formats.
+ *
+ * @example
+ * ```ts
+ * const opts: PptxExportOptions = {
+ *   format: "png",
+ *   slideIndices: [0, 2, 4],
+ *   dpi: 300,
+ * };
+ * // => satisfies PptxExportOptions
+ * ```
+ */
+interface PptxExportOptions {
+  /** Target format. */
+  format: PptxExportFormat;
+  /** Slide indices to export (0-based). If omitted, all slides are exported. */
+  slideIndices?: number[];
+  /** Output width in pixels (for PNG). Height is derived from aspect ratio. */
+  width?: number;
+  /** DPI for raster export (default 150). */
+  dpi?: number;
+  /** Whether to include hidden slides. */
+  includeHidden?: boolean;
+}
+/**
+ * Embedded font data extracted from a PPTX file.
+ *
+ * Used to register `@font-face` rules so the renderer can display
+ * the correct typeface even when the system font is missing.
+ *
+ * @example
+ * ```ts
+ * const font: PptxEmbeddedFont = {
+ *   name: "CustomSans",
+ *   dataUrl: "data:font/truetype;base64,AAEAK...",
+ *   format: "truetype",
+ * };
+ * // => satisfies PptxEmbeddedFont
+ * ```
+ */
+/**
+ * A single Custom XML Data Part stored in `customXml/` within the OPC package.
+ *
+ * These parts are used by add-ins, data-binding, and enterprise templates
+ * to store structured data alongside the presentation.
+ *
+ * @see ECMA-376 Part 1, §15.2.5
+ */
+interface PptxCustomXmlPart {
+  /** Item number (e.g. "1" for `customXml/item1.xml`). */
+  id: string;
+  /** Raw XML string content of the custom XML item. */
+  data: string;
+  /** Schema target namespace URI from `itemProps` (ds:schemaRef/@ds:uri). */
+  schemaUri?: string;
+  /** Raw XML string content of the associated `itemProps` file. */
+  properties?: string;
+  /** Raw XML string content of the OPC relationship file (`customXml/_rels/item{id}.xml.rels`). */
+  rels?: string;
+}
+interface PptxEmbeddedFont {
+  name: string;
+  dataUrl: string;
+  bold?: boolean;
+  italic?: boolean;
+  /** CSS font format hint (e.g. "truetype", "opentype"). */
+  format?: 'truetype' | 'opentype' | 'woff' | 'woff2';
+  /**
+   * Deobfuscated (clear-text) font binary data preserved from load
+   * for round-trip re-embedding on save. When present, the save
+   * pipeline will re-obfuscate and write this data back into the ZIP.
+   */
+  rawFontData?: Uint8Array;
+  /**
+   * Original ZIP path of the font part (e.g. `ppt/fonts/{GUID}.fntdata`).
+   * Preserved from load for round-trip.
+   */
+  partPath?: string;
+  /**
+   * The GUID used for obfuscation, either from the `fontKey` attribute
+   * or extracted from the part path. Preserved from load for round-trip.
+   */
+  fontGuid?: string;
+  /**
+   * Relationship ID (e.g. `rId21`) of the font part in
+   * `ppt/_rels/presentation.xml.rels`. Preserved from load so the save
+   * pipeline can reuse the original part/rel instead of minting a new
+   * GUID-named copy alongside the stale original.
+   */
+  originalRId?: string;
+  /**
+   * Raw bytes of the original obfuscated font part exactly as they were
+   * stored in the source ZIP. When the loader could not determine a
+   * usable GUID (e.g. EOT extraction path), the save pipeline preserves
+   * these bytes verbatim under the original path/rel.
+   */
+  originalPartBytes?: Uint8Array;
+}
+//#endregion
+//#region pptx/core/builders/sdk/merge-operations.d.ts
+/**
+ * Options controlling how slides are merged from source into target.
+ */
+interface MergeOptions {
+  /** Which slides to take from source (0-based indices). Default: all */
+  slideIndices?: number[];
+  /** Where to insert in target (0-based). Default: end */
+  insertAt?: number;
+  /** Whether to keep source theme (false = use target theme). Default: false */
+  keepSourceTheme?: boolean;
+}
+/**
+ * Merge slides from a source presentation into a target.
+ *
+ * This is a data-level merge that operates on {@link PptxData} objects.
+ * Slides are deep-cloned from the source, re-numbered to avoid ID
+ * conflicts, and inserted into the target's slides array.
+ *
+ * Media embedded as data URLs (imageData, mediaData, backgroundImage,
+ * posterFrameData) travel with the cloned elements automatically.
+ *
+ * @param targetData - The target presentation data (will be modified in place).
+ * @param sourceData - The source presentation data (read-only — slides are cloned).
+ * @param options - Merge configuration.
+ * @returns Number of slides merged.
+ *
+ * @example
+ * ```ts
+ * const target = await handler.load(targetBuffer);
+ * const source = await handler.load(sourceBuffer);
+ *
+ * const count = mergePresentation(target, source, {
+ *   slideIndices: [0, 2],
+ *   insertAt: 1,
+ * });
+ * console.log(`Merged ${count} slides`);
+ * ```
+ */
+declare function mergePresentation(targetData: PptxData, sourceData: PptxData, options?: MergeOptions): number;
+//#endregion
+//#region pptx/core/builders/sdk/text-operations.d.ts
+/**
+ * A single text match result returned by {@link findText}.
+ */
+interface FindResult {
+  /** 0-based slide index. */
+  slideIndex: number;
+  /** ID of the element containing the match. */
+  elementId: string;
+  /** Index of the text segment within the element. */
+  segmentIndex: number;
+  /** The matched text. */
+  text: string;
+  /** Character offset within the segment where the match starts. */
+  matchIndex: number;
+}
+/**
+ * Search for text across all slides in the presentation.
+ *
+ * Searches through all text segments in all elements (including
+ * group children recursively). Supports both plain string and
+ * RegExp patterns.
+ *
+ * @param slides - Array of slides to search.
+ * @param search - Plain string or RegExp to search for.
+ * @returns Array of match results with location information.
+ *
+ * @example
+ * ```ts
+ * const results = findText(data.slides, /Q[1-4] \d{4}/);
+ * console.log(`Found ${results.length} date references`);
+ * ```
+ */
+declare function findText(slides: PptxSlide[], search: string | RegExp): FindResult[];
+/**
+ * Replace all occurrences of a search pattern in a single slide's elements.
+ *
+ * Mutates the slide's elements in place. Searches through all
+ * text segments including group children recursively.
+ *
+ * @param slide - The slide to perform replacements on.
+ * @param search - Plain string or RegExp to search for.
+ * @param replacement - The replacement string (supports `$1`, `$&` etc. for RegExp).
+ * @returns The number of replacements made.
+ *
+ * @example
+ * ```ts
+ * const count = replaceTextInSlide(data.slides[0], "2025", "2026");
+ * console.log(`Updated ${count} occurrences on slide 1`);
+ * ```
+ */
+declare function replaceTextInSlide(slide: PptxSlide, search: string | RegExp, replacement: string): number;
+/**
+ * Replace all occurrences of a search pattern across all slides.
+ *
+ * Mutates slides' elements in place. Searches through all text
+ * segments including group children recursively.
+ *
+ * @param slides - Array of slides to perform replacements on.
+ * @param search - Plain string or RegExp to search for.
+ * @param replacement - The replacement string.
+ * @returns The total number of replacements made across all slides.
+ *
+ * @example
+ * ```ts
+ * const count = replaceText(data.slides, "Acme Corp", "NewCo Inc");
+ * console.log(`Rebranded ${count} occurrences`);
+ * ```
+ */
+declare function replaceText(slides: PptxSlide[], search: string | RegExp, replacement: string): number;
+//#endregion
+export { PptxThemeOption as $, PptxAnimScaleBehavior as $t, PptxNormalViewProperties as A, PptxAnimationRepeatMode as At, PptxEmbeddedFontDescriptor as B, PptxHslColorDelta as Bt, PptxSlide as C, PptxAnimationDirection as Ct, PptxSmartTagsReference as D, PptxAnimationKeyframe as Dt, PptxSlideSyncProperties as E, PptxAnimationIterate as Et, PptxViewScale as F, PptxAnimationTrigger as Ft, PptxHeaderFooterFlags as G, PptxTextAnimationTarget as Gt, PptxEmbeddedFontListEntry as H, PptxNativeAnimation as Ht, PptxPresentationPrintProperties as I, PptxAttributeAnimation as It, PptxNotesMaster as J, PptxVisibilitySetTiming as Jt, PptxLayoutPreview as K, PptxTextBuildType as Kt, PptxPrintColorMode as L, PptxColorAnimation as Lt, PptxViewGuide as M, PptxAnimationTarget as Mt, PptxViewOrigin as N, PptxAnimationTimelineAnchor as Nt, PptxCommonSlideViewProperties as O, PptxAnimationOleChartElementTarget as Ot, PptxViewProperties as P, PptxAnimationTimingCurve as Pt, PptxTextStyleLevels as Q, PptxAnimRotBehavior as Qt, PptxPrintOutput as R, PptxElementAnimation as Rt, PptxSection as S, PptxAfterAnimationAction as St, PptxSlideSize as T, PptxAnimationGraphicElementTarget as Tt, MasterViewTab as U, PptxNativeAnimationKind as Ut, PptxEmbeddedFontList as V, PptxMediaBookmarkTarget as Vt, PptxHandoutMaster as W, PptxSetAnimation as Wt, PptxSlideLayout as X, PptxAnimEffectBehavior as Xt, PptxPlaceholderFrame as Y, PptxAnimBehavior as Yt, PptxSlideMaster as Z, PptxAnimMotionBehavior as Zt, PptxLayoutOption as _, PptxTag as _t, MergeOptions as a, PptxSlideTransition as an, PptxThemeFontScheme as at, PptxPhotoAlbum as b, AnimationCondition as bt, PptxCustomShow as c, PptxStripDirection as cn, PptxThemeObjectDefaults as ct, PptxData as d, PptxTransitionSpeed as dn, PptxComment as dt, PptxAnimationBehavior as en, PptxTheme as et, PptxEmbeddedFont as f, PptxTransitionType as fn, PptxCommentAuthor as ft, PptxKinsoku as g, PptxModernCommentAuthor as gt, PptxHeaderFooter as h, TRANSITION_VALID_DIRECTIONS as hn, PptxCustomProperty as ht, replaceTextInSlide as i, PptxMorphOption as in, PptxThemeFontGroup as it, PptxRestoredRegion as j, PptxAnimationSequence as jt, PptxGridSpacing as k, PptxAnimationPreset as kt, PptxCustomXmlPart as l, PptxTransitionDirection4 as ln, THEME_COLOR_SCHEME_KEYS as lt, PptxExportOptions as m, TRANSITION_THRUBLK_TYPES as mn, PptxCoreProperties as mt, findText as n, PptxBehaviorPoint as nn, PptxThemeEffectStyle as nt, mergePresentation as o, PptxSplitDirection as on, PptxThemeFormatScheme as ot, PptxExportFormat as p, TRANSITION_PATTERN_OPTIONS as pn, PptxCompatibilityWarning as pt, PptxMasterTextStyles as q, PptxTimingTemplate as qt, replaceText as r, PptxSetBehavior as rn, PptxThemeFillStyle as rt, PptxActiveXControl as s, PptxSplitOrientation as sn, PptxThemeLineStyle as st, FindResult as t, PptxAnimationBehaviorTiming as tn, PptxThemeColorScheme as tt, PptxCustomerData as u, PptxTransitionDirection8 as un, PptxAppProperties as ut, PptxModernCommentPart as v, PptxTagCollection as vt, PptxSlideBackgroundPattern as w, PptxAnimationEffectFilter as wt, PptxPresentationProperties as x, AnimationConditionEvent as xt, PptxModifyVerifier as y, PptxCommentMention as yt, PptxEmbeddedFontDataId as z, PptxGraphicBuild as zt };
+//# sourceMappingURL=text-operations-CyMTMfID.d.ts.map