pptx-svelte-viewer 1.4.0 → 2.1.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { Component } from 'svelte';
+import { LanguageModel, ChatTransport, UIMessage, ToolSet } from 'ai';
 
 //#region src/core/types/actions.d.ts
 /**
@@ -204,6 +205,13 @@ interface PptxShapeLocks {
   noAdjustHandles?: boolean;
   noChangeArrowheads?: boolean;
   noChangeShapeType?: boolean;
+  /**
+   * Text-box flag from `p:cNvSpPr/@txBox`. Not a lock in the strict sense,
+   * but it lives on the same non-visual-properties node as `a:spLocks`, so
+   * it is captured here to round-trip through the model. When `true` the
+   * shape is a plain text box (no fill/line by default).
+   */
+  txBox?: boolean;
 }
 /**
  * A drawing guide parsed from OOXML extension lists.
@@ -793,6 +801,15 @@ interface ShapeStyle {
     r: number;
     b: number;
   };
+  /** Raw tileRect LTRB values (0..1 fractions, may be negative) from
+   *  `a:gradFill/a:tileRect`. Defines the rectangle the gradient tile occupies
+   *  before any flip/tiling is applied. */
+  fillGradientTileRect?: {
+    l: number;
+    t: number;
+    r: number;
+    b: number;
+  };
   /** Gradient tile flip mode (`a:gradFill/@flip`).
    *  `none` = no tiling flip (default), `x|y|xy` = mirror in the named axis. */
   fillGradientFlip?: 'none' | 'x' | 'y' | 'xy';
@@ -810,6 +827,20 @@ interface ShapeStyle {
    * round-trip serialisation. See {@link fillColorXml} for the rationale.
    */
   strokeColorXml?: XmlObject;
+  /**
+   * Kind of fill painted on the outline (`a:ln` child). Distinguishes a solid
+   * outline from a gradient/pattern/none outline so save can emit the correct
+   * single line fill instead of collapsing every outline to `a:solidFill`
+   * (which, alongside a preserved `a:gradFill`/`a:pattFill`, produces an
+   * invalid dual-fill `<a:ln>`).
+   */
+  strokeFillMode?: 'solid' | 'gradient' | 'pattern' | 'none';
+  /** Raw `a:ln/a:gradFill` XML preserved for round-trip when the outline is
+   *  gradient-filled. Re-emitted verbatim as the line's single fill on save. */
+  strokeGradientXml?: XmlObject;
+  /** Raw `a:ln/a:pattFill` XML preserved for round-trip when the outline is
+   *  pattern-filled. Re-emitted verbatim as the line's single fill on save. */
+  strokePatternXml?: XmlObject;
   strokeWidth?: number;
   strokeOpacity?: number;
   strokeDash?: StrokeDashType;
@@ -991,6 +1022,14 @@ interface ShapeStyle {
   };
   /** Fill overlay blend mode from effectDag `a:fillOverlay/@blend`. */
   dagFillOverlayBlend?: 'over' | 'mult' | 'screen' | 'darken' | 'lighten';
+  /**
+   * Fill overlay tint colour (hex `#RRGGBB`) from effectDag `a:fillOverlay`'s
+   * `a:solidFill`/`a:gradFill`. Painted as a blended overlay layer over the
+   * element; the blend mode comes from {@link dagFillOverlayBlend}.
+   */
+  dagFillOverlayColor?: string;
+  /** Fill overlay tint opacity (0-1), from the overlay fill colour's alpha. */
+  dagFillOverlayOpacity?: number;
   /** `<a:lnRef @idx>` — 1-based index into the theme's lnStyleLst. */
   lnRefIdx?: number;
   /** Raw XML colour child of `<a:lnRef>` (e.g. `<a:schemeClr>` with transforms). */
@@ -1118,6 +1157,13 @@ interface TextStyle {
   kerning?: number;
   /** Text highlight colour as hex string (`a:highlight`). */
   highlightColor?: string;
+  /**
+   * Raw colour-choice XML preserved from `a:highlight` so a themed highlight
+   * (`a:schemeClr` / `a:sysClr` / `a:prstClr`) re-emits with its original
+   * identity rather than being flattened to `<a:srgbClr/>` on save. On save we
+   * re-emit verbatim when the resolved {@link highlightColor} still matches.
+   */
+  highlightColorXml?: XmlObject;
   /** Text-level gradient fill CSS string (from `a:rPr > a:gradFill`). */
   textFillGradient?: string;
   /** Structured gradient stops for text fill round-trip serialization. */
@@ -1229,10 +1275,36 @@ interface TextStyle {
   eastAsiaFont?: string;
   /** Complex Script font family from `a:cs`. */
   complexScriptFont?: string;
+  /**
+   * Theme-font token (`+mj-lt` / `+mn-lt` / ...) authored on `a:latin`, when
+   * present. {@link fontFamily} holds the resolved concrete face for
+   * rendering; this preserves the token linkage so the writer re-emits the
+   * token rather than the flattened face (see #84).
+   */
+  latinFontThemeToken?: string;
+  /** Theme-font token authored on `a:ea` (e.g. `+mn-ea`), when present. */
+  eastAsiaFontThemeToken?: string;
+  /** Theme-font token authored on `a:cs` (e.g. `+mn-cs`), when present. */
+  complexScriptFontThemeToken?: string;
+  /**
+   * Automatic per-script fallback face resolved from the theme's
+   * `<a:font script="...">` overrides for a run whose text is dominantly
+   * CJK / Arabic / Hebrew / Thai (see #83). A rendering hint only: it is not
+   * serialised back on save, so it never disturbs the round-trip typefaces.
+   */
+  scriptFallbackFont?: string;
   /** Text language from `a:rPr/@lang`. */
   language?: string;
   /** Hyperlink mouse-over target from `a:hlinkMouseOver`. */
   hyperlinkMouseOver?: string;
+  /**
+   * Raw `a:snd` (embedded WAV audio) child of `a:hlinkClick`, preserved
+   * verbatim (carries `@r:embed` + `@name`). Round-tripped on save so the
+   * click sound survives instead of being dropped.
+   */
+  hyperlinkSoundXml?: XmlObject;
+  /** Raw `a:snd` child of `a:hlinkMouseOver`, preserved verbatim for round-trip. */
+  hyperlinkMouseOverSoundXml?: XmlObject;
   /** Hyperlink invalidUrl attribute (`a:hlinkClick/@invalidUrl`). */
   hyperlinkInvalidUrl?: string;
   /** Hyperlink target frame (`a:hlinkClick/@tgtFrame`). */
@@ -1576,6 +1648,15 @@ interface TextSegment {
    * on the first segment of a paragraph.
    */
   endParaRunProperties?: Record<string, unknown>;
+  /**
+   * Per-paragraph properties (alignment, spacing, margins, indent, tab stops,
+   * rtl) authored on this paragraph's own `a:pPr` (#69). Only meaningful on
+   * the first segment of a paragraph. When present, the writer emits these
+   * per paragraph instead of collapsing one shape-level pPr onto every
+   * paragraph. Only the paragraph-geometry keys of {@link TextStyle} are
+   * populated; unrelated fields fall back to the shape-level style.
+   */
+  paragraphProperties?: TextStyle;
   /**
    * Phonetic annotation text from `a:ruby > a:rt` (e.g. furigana, pinyin).
    * When present, the renderer should wrap the base text with an HTML `<ruby>` tag.
@@ -1881,6 +1962,75 @@ interface PptxChartProtection {
   rawXml?: XmlObject;
 }
 //#endregion
+//#region src/core/types/chart-user-shapes.d.ts
+/**
+ * Types for chart drawing-overlay shapes (`c:userShapes`).
+ *
+ * A chart's `c:userShapes` element carries an `r:id` that references a
+ * separate drawing part (`ppt/drawings/drawingN.xml`) whose root is a
+ * `c:userShapes` element populated with `cdr:relSizeAnchor` /
+ * `cdr:absSizeAnchor` wrappers around `sp` / `pic` / `cxnSp` shapes drawn on
+ * top of the chart plot. These interfaces describe the parsed, renderable
+ * overlay model. The raw reference is preserved separately on
+ * {@link PptxChartData.userShapesXml} for verbatim round-trip save; this model
+ * is render-only.
+ *
+ * @module pptx-types/chart-user-shapes
+ */
+/** A single paragraph of overlay-shape text with light formatting. */
+interface PptxChartUserShapeParagraph {
+  /** Joined run text of the paragraph. */
+  text: string;
+  /** Font size in points (`a:rPr/@sz` divided by 100), when present. */
+  fontSize?: number;
+  /** Whether the first run is bold (`a:rPr/@b`). */
+  bold?: boolean;
+  /** Whether the first run is italic (`a:rPr/@i`). */
+  italic?: boolean;
+  /** Resolved run colour hex (e.g. `"#FF0000"`), when present. */
+  color?: string;
+  /** Paragraph alignment (`a:pPr/@algn`): left / centre / right. */
+  align?: 'l' | 'ctr' | 'r';
+}
+/**
+ * A parsed chart-overlay shape positioned by a drawing anchor.
+ *
+ * Position is expressed as chart-relative fractions in {@link from}. For a
+ * `relSizeAnchor` the opposite corner is {@link to} (also fractional); for an
+ * `absSizeAnchor` the extent is {@link ext} in EMU.
+ */
+interface PptxChartUserShape {
+  /** Shape kind: text/preset shape, connector, or picture. */
+  kind: 'sp' | 'cxnSp' | 'pic';
+  /** Anchor kind that positioned the shape. */
+  anchor: 'rel' | 'abs';
+  /** Top-left corner as chart-relative fractions (0-1). */
+  from: {
+    x: number;
+    y: number;
+  };
+  /** Bottom-right corner as chart-relative fractions (0-1); relSizeAnchor only. */
+  to?: {
+    x: number;
+    y: number;
+  };
+  /** Extent in EMU (cx, cy); absSizeAnchor only. */
+  ext?: {
+    cx: number;
+    cy: number;
+  };
+  /** Preset geometry name (`a:prstGeom/@prst`), defaulting to `"rect"`. */
+  prst?: string;
+  /** Resolved solid-fill hex colour, when present. */
+  fill?: string;
+  /** Resolved line/stroke hex colour, when present. */
+  stroke?: string;
+  /** Line width in points (`a:ln/@w` divided by 12700), when present. */
+  strokeWidth?: number;
+  /** Text paragraphs of the shape's `txBody`, when present. */
+  paragraphs?: PptxChartUserShapeParagraph[];
+}
+//#endregion
 //#region src/core/types/chart.d.ts
 /**
  * Supported chart type discriminators.
@@ -2214,6 +2364,15 @@ interface PptxChartTreemapOptions {
 interface PptxChartSeries {
   name: string;
   values: number[];
+  /**
+   * Blank-value mask aligned index-for-index with {@link values}: `true` marks
+   * a category whose numeric cache point (`c:numCache/c:pt`) was absent or
+   * empty, i.e. a genuine blank rather than a real `0`. Present only when the
+   * source series actually contains blanks; when set, blank slots in
+   * {@link values} carry `0` as a placeholder. Renderers honour
+   * `c:dispBlanksAs` (gap / zero / span) using this mask.
+   */
+  blanks?: boolean[];
   color?: string;
   trendlines?: PptxChartTrendline[];
   errBars?: PptxChartErrBars[];
@@ -2221,6 +2380,18 @@ interface PptxChartSeries {
   marker?: PptxChartMarker;
   dataLabels?: PptxChartDataLabel[];
   explosion?: number;
+  /**
+   * Series-level `c:invertIfNegative`: when true, bar/column data points with a
+   * negative value are drawn with an inverted (lightened) fill. A per-point
+   * `c:dPt/c:invertIfNegative` overrides this for that point. Absent when the
+   * source XML omits the flag.
+   */
+  invertIfNegative?: boolean;
+  /**
+   * Whether this line/scatter series is drawn with bezier smoothing
+   * (`c:ser/c:smooth/@val`). Absent when the source XML omits `c:smooth`.
+   */
+  smooth?: boolean;
   /** Axis ID this series is plotted against (links to PptxChartAxisFormatting.axisId). */
   axisId?: number;
   /**
@@ -2423,6 +2594,14 @@ interface PptxChartManualLayout {
   y?: number;
   width?: number;
   height?: number;
+  /**
+   * Raw `c:extLst` (CT_ExtensionList) of the `c:manualLayout`, captured
+   * verbatim so it round-trips through the typed model. Without this, a dirty
+   * write of an edited layout would drop the extension list (the manual node
+   * is rebuilt from the typed fields). Emitted as the trailing child, matching
+   * the CT_ManualLayout schema order.
+   */
+  ext?: XmlObject;
 }
 /**
  * Typed manual layouts for chart regions that accept `c:layout`.
@@ -2487,6 +2666,33 @@ interface PptxChartData {
   style?: PptxChartStyle;
   /** Grouping mode for bar/area/line charts: 'clustered' | 'stacked' | 'percentStacked' */
   grouping?: 'clustered' | 'stacked' | 'percentStacked';
+  /**
+   * Whether the first (or only) series varies its point colours
+   * (`c:varyColors/@val`). Pie/doughnut default this on; single-series
+   * bar/column honour it by giving each point a distinct palette colour.
+   * Absent when the source XML omits `c:varyColors`.
+   */
+  varyColors?: boolean;
+  /**
+   * Pie/doughnut start angle in degrees clockwise from 12 o'clock
+   * (`c:firstSliceAng/@val`, 0 through 360). Absent uses the default 0.
+   */
+  firstSliceAngle?: number;
+  /**
+   * Doughnut hole diameter as a percentage of the outer diameter
+   * (`c:holeSize/@val`, 10 through 90). Absent uses the renderer default.
+   */
+  doughnutHoleSize?: number;
+  /**
+   * Bar/column gap between category clusters as a percentage of bar width
+   * (`c:gapWidth/@val`, 0 through 500). Absent uses the renderer default.
+   */
+  barGapWidth?: number;
+  /**
+   * Clustered bar/column overlap between series within a category as a
+   * percentage (`c:overlap/@val`, -100 through 100). Absent uses 0.
+   */
+  barOverlap?: number;
   /** Internal: path to the chart XML part in the PPTX archive (for round-trip save). */
   chartPartPath?: string;
   /** Internal: relationship ID linking the graphic frame to the chart part. */
@@ -2587,6 +2793,15 @@ interface PptxChartData {
    * attempting to parse the nested drawing tree.
    */
   userShapesXml?: unknown;
+  /**
+   * Parsed, renderable drawing-overlay shapes resolved from the separate
+   * drawing part referenced by `c:userShapes/@r:id`
+   * (`ppt/drawings/drawingN.xml`). Each entry carries chart-relative anchor
+   * geometry plus light shape/text formatting so the viewer can render an
+   * overlay on top of the chart plot. Render-only: {@link userShapesXml}
+   * remains the source of truth for round-trip save.
+   */
+  userShapes?: PptxChartUserShape[];
   /**
    * Raw `c:pivotFmts` XML subtree preserved verbatim.
    *
@@ -3294,6 +3509,18 @@ interface PptxSmartArtColorTransform extends PptxSmartArtDefinitionMetadata {
   fillColors: string[];
   /** Ordered resolved line colors for rendering. */
   lineColors: string[];
+  /** Ordered resolved text-fill colors (primary styleLbl `txFillClrLst`). */
+  textFillColors?: string[];
+  /** Ordered resolved text-line colors (primary styleLbl `txLinClrLst`). */
+  textLineColors?: string[];
+  /** Ordered resolved effect colors (primary styleLbl `effectClrLst`). */
+  effectColors?: string[];
+  /** Ordered resolved text-effect colors (primary styleLbl `txEffectClrLst`). */
+  textEffectColors?: string[];
+  /** Fill-list span/cycle + hue-direction interpolation of the primary styleLbl. */
+  fillInterpolation?: PptxSmartArtColorListMetadata;
+  /** Line-list span/cycle + hue-direction interpolation of the primary styleLbl. */
+  lineInterpolation?: PptxSmartArtColorListMetadata;
   /** Ordered CT_CTStyleLabel metadata. */
   labels?: PptxSmartArtColorStyleLabel[];
 }
@@ -3414,6 +3641,40 @@ interface PptxSmartArtDrawingShape extends PptxCustomPathProperties {
   skewY?: number;
   /** Solid fill colour (hex). */
   fillColor?: string;
+  /**
+   * Gradient fill stops when the cached shape uses `a:gradFill`. Positions are
+   * 0..100 (percent). Renderers emit an SVG/CSS gradient instead of a flat box.
+   */
+  fillGradientStops?: Array<{
+    color: string;
+    position: number;
+    opacity?: number;
+  }>;
+  /** Gradient geometry type (`linear` for `a:lin`, `radial` for `a:path`). */
+  fillGradientType?: 'linear' | 'radial';
+  /** Linear gradient angle in degrees (0..360). */
+  fillGradientAngle?: number;
+  /** Pattern fill preset name from `a:pattFill/@prst` (e.g. "pct50", "cross"). */
+  fillPatternPreset?: string;
+  /** Pattern fill foreground colour (hex) from `a:pattFill/a:fgClr`. */
+  fillPatternForegroundColor?: string;
+  /** Pattern fill background colour (hex) from `a:pattFill/a:bgClr`. */
+  fillPatternBackgroundColor?: string;
+  /**
+   * Relationship id of a picture (blip) fill's embedded image, from
+   * `a:blipFill/a:blip/@r:embed`. The image bytes are resolved separately; see
+   * {@link fillImageUrl}.
+   */
+  fillBlipEmbedId?: string;
+  /**
+   * Resolved data-URI/URL for a picture (blip) fill, when the embedded image
+   * part could be resolved. Absent when only {@link fillBlipEmbedId} is known.
+   */
+  fillImageUrl?: string;
+  /** Whether the cached shape carries an outer-shadow effect (`a:effectLst`). */
+  hasShadow?: boolean;
+  /** Resolved outer-shadow colour (hex), when present. */
+  shadowColor?: string;
   /** Stroke colour (hex). */
   strokeColor?: string;
   /** Stroke width in points. */
@@ -3448,6 +3709,40 @@ interface PptxSmartArtChrome {
   /** Outline stroke width in points. */
   outlineWidth?: number;
 }
+/**
+ * Presentation layout variables from `dgm:prSet/dgm:presLayoutVars` (data model)
+ * or `dgm:varLst` (layout definition defaults).
+ *
+ * These drive how the DiagramML layout interpreter arranges points: flow
+ * direction, hierarchy branch style, org-chart mode, and child count limits.
+ * The fallback layout engine can consult them for direction/org-chart hints.
+ *
+ * @example
+ * ```ts
+ * const vars: PptxSmartArtPresLayoutVars = { direction: "rev", orgChart: true };
+ * // => satisfies PptxSmartArtPresLayoutVars
+ * ```
+ */
+interface PptxSmartArtPresLayoutVars {
+  /** Flow direction (`dgm:dir`): "norm" (default) or "rev" (reversed/RTL). */
+  direction?: 'norm' | 'rev';
+  /** Hierarchy branch style (`dgm:hierBranch`): std/init/l/r/hang. */
+  hierarchyBranch?: 'std' | 'init' | 'l' | 'r' | 'hang';
+  /** Org-chart mode enabled (`dgm:orgChart`). */
+  orgChart?: boolean;
+  /** Maximum children per node (`dgm:chMax`, -1 = unbounded). */
+  childMax?: number;
+  /** Preferred children per node (`dgm:chPref`, -1 = unbounded). */
+  childPreferred?: number;
+  /** Whether bullets are enabled (`dgm:bulletEnabled`). */
+  bulletEnabled?: boolean;
+  /** Animation-by-level setting (`dgm:animLvl`). */
+  animationLevel?: string;
+  /** Animate-one setting (`dgm:animOne`). */
+  animateOne?: string;
+  /** Allowed resize handles (`dgm:resizeHandles`). */
+  resizeHandles?: string;
+}
 /**
  * Complete parsed SmartArt data for a {@link SmartArtPptxElement}.
  *
@@ -3489,6 +3784,12 @@ interface PptxSmartArtData {
   quickStyle?: PptxSmartArtQuickStyle;
   /** Editable metadata from the related DiagramML layout definition. */
   layoutDefinition?: PptxSmartArtLayoutDefinition;
+  /**
+   * Presentation layout variables (direction, hierarchy branch, org-chart,
+   * child limits, bullets) from `dgm:presLayoutVars` / layout `dgm:varLst`.
+   * Consulted by the fallback layout engine for direction/org-chart hints.
+   */
+  presLayoutVars?: PptxSmartArtPresLayoutVars;
   /** Relationship ID for the diagram data part (for round-trip save). */
   dataRelId?: string;
   /** Relationship ID for the diagram layout part. */
@@ -3521,7 +3822,7 @@ interface PptxSmartArtData {
 /**
  * Per-cell visual style for a table cell.
  *
- * All fields are optional — unset values inherit from the table style.
+ * All fields are optional - unset values inherit from the table style.
  *
  * @example
  * ```ts
@@ -3649,6 +3950,52 @@ interface PptxTableCellStyle {
   patternFillForeground?: string;
   /** Pattern fill background colour. */
   patternFillBackground?: string;
+  /**
+   * Cell 3D bevel + lighting from `a:tcPr/a:cell3D` (CT_Cell3D,
+   * ECMA-376 §21.1.3.1). Rendered as a CSS bevel treatment.
+   */
+  cell3D?: PptxTableCell3D;
+  /**
+   * `a:tcPr/@anchorCtr` - centre the text block in the direction
+   * perpendicular to the text flow (horizontal centring for horizontal text).
+   */
+  anchorCtr?: boolean;
+  /**
+   * `a:tcPr/@horzOverflow` (ST_TextHorzOverflowType): `clip` clips text at
+   * the cell edge, `overflow` (the default) lets it spill.
+   */
+  horzOverflow?: 'clip' | 'overflow';
+}
+/**
+ * Cell 3D bevel + lighting parsed from `a:tcPr/a:cell3D` (CT_Cell3D).
+ *
+ * Only the fields needed to render a plausible bevel treatment are captured;
+ * verbatim round-trip of the full node is handled separately by the save path.
+ *
+ * @example
+ * ```ts
+ * const c3d: PptxTableCell3D = {
+ *   bevelWidth: 8,
+ *   bevelHeight: 8,
+ *   bevelPreset: 'circle',
+ *   material: 'plastic',
+ * };
+ * // => satisfies PptxTableCell3D
+ * ```
+ */
+interface PptxTableCell3D {
+  /** Bevel width in px (from `a:bevel@w`, EMU converted). */
+  bevelWidth?: number;
+  /** Bevel height in px (from `a:bevel@h`, EMU converted). */
+  bevelHeight?: number;
+  /** Bevel preset name (`a:bevel@prst`, e.g. `circle`, `relaxedInset`). */
+  bevelPreset?: string;
+  /** Preset material (`a:cell3D@prstMaterial`, e.g. `plastic`, `metal`). */
+  material?: string;
+  /** Light rig type (`a:lightRig@rig`, e.g. `threePt`, `soft`). */
+  lightRig?: string;
+  /** Light rig direction (`a:lightRig@dir`, e.g. `tl`, `t`, `tr`). */
+  lightRigDirection?: string;
 }
 /**
  * A single table cell with text content, optional style, and merge info.
@@ -3761,12 +4108,50 @@ interface PptxTableData {
  * ```
  */
 interface ParsedTableStyleFill {
-  /** Theme colour key (e.g. `accent1`, `dk1`). */
+  /**
+   * Theme colour key (e.g. `accent1`, `dk1`). Empty string when the fill is a
+   * non-scheme fill (explicit sRGB, gradient, pattern, or none) that carries
+   * no theme colour reference; the renderer then resolves {@link color},
+   * {@link gradient}, {@link pattern}, or {@link noFill} instead.
+   */
   schemeColor: string;
   /** Tint value (0-100 000). */
   tint?: number;
   /** Shade value (0-100 000). */
   shade?: number;
+  /** Explicit sRGB hex colour (e.g. `#FF8800`) from `a:srgbClr`. */
+  color?: string;
+  /** The fill was `a:noFill`: renders transparent and clears lower layers. */
+  noFill?: boolean;
+  /** Gradient fill parsed from `a:gradFill`. */
+  gradient?: ParsedTableStyleGradient;
+  /** Preset pattern fill parsed from `a:pattFill`. */
+  pattern?: ParsedTableStylePattern;
+}
+/** A single colour stop within a {@link ParsedTableStyleGradient}. */
+interface ParsedTableStyleGradientStop {
+  /** Stop position as a percentage (0-100). */
+  position: number;
+  /** Stop colour (scheme or explicit sRGB). */
+  fill: ParsedTableStyleFill;
+}
+/** A gradient fill parsed from a table style section's `a:gradFill`. */
+interface ParsedTableStyleGradient {
+  /** Ordered colour stops. */
+  stops: ParsedTableStyleGradientStop[];
+  /** Linear gradient angle in degrees (from `a:lin@ang`, 60000ths -> deg). */
+  angle?: number;
+  /** Gradient family: linear (`a:lin`) or radial (`a:path`). */
+  type: 'linear' | 'radial';
+}
+/** A preset pattern fill parsed from a table style section's `a:pattFill`. */
+interface ParsedTableStylePattern {
+  /** OOXML preset name (e.g. `ltDnDiag`) from `a:pattFill@prst`. */
+  preset: string;
+  /** Foreground colour (`a:fgClr`). */
+  foreground?: ParsedTableStyleFill;
+  /** Background colour (`a:bgClr`). */
+  background?: ParsedTableStyleFill;
 }
 /**
  * A single entry in the parsed table style map.
@@ -3793,12 +4178,67 @@ interface ParsedTableStyleText {
   bold?: boolean;
   /** Font italic. */
   italic?: boolean;
+  /** Font underline (from `a:tcTxStyle@u`, any value other than `none`). */
+  underline?: boolean;
   /** Font colour as theme scheme key. */
   fontSchemeColor?: string;
   /** Font colour tint (0-100 000). */
   fontTint?: number;
   /** Font colour shade (0-100 000). */
   fontShade?: number;
+  /** Explicit sRGB hex font colour (e.g. `#FF0000`) from `a:srgbClr`. */
+  fontColor?: string;
+  /** Typeface from `a:font@typeface` (latin font). */
+  fontFace?: string;
+  /** Font-collection index from `a:fontRef@idx` (`minor`, `major`, `none`). */
+  fontRefIdx?: string;
+}
+/**
+ * A single border side within a table style's `a:tcStyle/a:tcBdr`.
+ *
+ * Corresponds to one of `a:left`, `a:right`, `a:top`, `a:bottom`,
+ * `a:insideH`, `a:insideV`, `a:tl2br`, `a:bl2tr` (each a
+ * `CT_ThemeableLineStyle` wrapping an `a:ln`).
+ *
+ * @example
+ * ```ts
+ * const side: ParsedTableStyleBorder = {
+ *   width: 1,
+ *   dash: 'solid',
+ *   fill: { schemeColor: 'lt1' },
+ * };
+ * // => satisfies ParsedTableStyleBorder
+ * ```
+ */
+interface ParsedTableStyleBorder {
+  /** Line width in px (converted from the `a:ln@w` EMU value). */
+  width?: number;
+  /** OOXML `a:prstDash@val` (e.g. `solid`, `dash`, `sysDot`). */
+  dash?: string;
+  /** Border colour as a theme scheme fill (from `a:ln/a:solidFill/a:schemeClr`). */
+  fill?: ParsedTableStyleFill;
+  /** Explicit hex colour when the line used `a:srgbClr` (e.g. `#808080`). */
+  color?: string;
+  /** The line was `a:noFill` - an explicit "no border" that clears lower layers. */
+  noFill?: boolean;
+}
+/**
+ * The set of border sides parsed from a table style section's
+ * `a:tcStyle/a:tcBdr` element.
+ */
+interface ParsedTableStyleBorders {
+  left?: ParsedTableStyleBorder;
+  right?: ParsedTableStyleBorder;
+  top?: ParsedTableStyleBorder;
+  bottom?: ParsedTableStyleBorder;
+  /** Interior horizontal borders between rows in the region. */
+  insideH?: ParsedTableStyleBorder;
+  /** Interior vertical borders between columns in the region. */
+  insideV?: ParsedTableStyleBorder;
+  /** Top-left to bottom-right diagonal. */
+  tl2br?: ParsedTableStyleBorder;
+  /** Bottom-left to top-right diagonal. */
+  bl2tr?: ParsedTableStyleBorder;
 }
 /**
  * Table background style (CT_TableBackgroundStyle, ECMA-376 §21.1.3.7).
@@ -3834,6 +4274,24 @@ interface ParsedTableStyleEntry {
   swCellFill?: ParsedTableStyleFill;
   neCellFill?: ParsedTableStyleFill;
   nwCellFill?: ParsedTableStyleFill;
+  /**
+   * Per-role border styling from `a:tcStyle/a:tcBdr`. These supply the
+   * gridlines/edges a styled table inherits from its table style when the
+   * cells carry no explicit per-cell `a:lnX` overrides.
+   */
+  wholeTblBorders?: ParsedTableStyleBorders;
+  firstRowBorders?: ParsedTableStyleBorders;
+  lastRowBorders?: ParsedTableStyleBorders;
+  firstColBorders?: ParsedTableStyleBorders;
+  lastColBorders?: ParsedTableStyleBorders;
+  band1HBorders?: ParsedTableStyleBorders;
+  band2HBorders?: ParsedTableStyleBorders;
+  band1VBorders?: ParsedTableStyleBorders;
+  band2VBorders?: ParsedTableStyleBorders;
+  seCellBorders?: ParsedTableStyleBorders;
+  swCellBorders?: ParsedTableStyleBorders;
+  neCellBorders?: ParsedTableStyleBorders;
+  nwCellBorders?: ParsedTableStyleBorders;
   /** Per-role text styling from a:tcTxStyle. */
   wholeTblText?: ParsedTableStyleText;
   firstRowText?: ParsedTableStyleText;
@@ -4631,10 +5089,30 @@ interface PptxNativeAnimation {
   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`). */
@@ -4727,6 +5205,14 @@ interface PptxNativeAnimation {
    * 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;
   /**
@@ -5216,6 +5702,18 @@ interface PptxAppProperties {
   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 src/core/types/presentation-print-properties.d.ts
@@ -5506,7 +6004,7 @@ interface PptxTheme {
  * // => "morph" — one of 40+ transition effects
  * ```
  */
-type PptxTransitionType = 'none' | 'cut' | 'fade' | 'push' | 'wipe' | 'split' | 'randomBar' | 'blinds' | 'checker' | 'circle' | 'comb' | 'cover' | 'diamond' | 'dissolve' | 'plus' | 'pull' | 'random' | 'strips' | 'uncover' | 'wedge' | 'wheel' | 'zoom' | 'newsflash' | 'morph' | 'conveyor' | 'doors' | 'ferris' | 'flash' | 'flythrough' | 'gallery' | 'glitter' | 'honeycomb' | 'pan' | 'prism' | 'reveal' | 'ripple' | 'shred' | 'switch' | 'vortex' | 'warp' | 'wheelReverse' | 'window' | 'cube' | 'flip' | 'rotate' | 'orbit';
+type PptxTransitionType = 'none' | 'cut' | 'fade' | 'push' | 'wipe' | 'split' | 'randomBar' | 'blinds' | 'checker' | 'circle' | 'comb' | 'cover' | 'diamond' | 'dissolve' | 'plus' | 'pull' | 'random' | 'strips' | 'uncover' | 'wedge' | 'wheel' | 'zoom' | 'newsflash' | 'morph' | 'conveyor' | 'doors' | 'ferris' | 'flash' | 'flythrough' | 'gallery' | 'glitter' | 'honeycomb' | 'pan' | 'prism' | 'reveal' | 'ripple' | 'shred' | 'switch' | 'vortex' | 'warp' | 'wheelReverse' | 'window' | 'cube' | 'flip' | 'rotate' | 'orbit' | 'fallOver' | 'drape' | 'curtains' | 'wind' | 'prestige' | 'fracture' | 'crush' | 'peelOff' | 'pageCurlDouble' | 'pageCurlSingle' | 'airplane' | 'origami';
 /** Split orientation from OOXML `@_orient`. */
 type PptxSplitOrientation = 'horz' | 'vert';
 /** Schema-defined `ST_TransitionSpeed` values. */
@@ -5720,6 +6218,21 @@ interface PptxActiveXControl {
   name?: string;
   /** Shape ID this control is linked to (from @spid). */
   shapeId?: string;
+  /** 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;
 }
@@ -5846,6 +6359,13 @@ interface PptxSlide {
   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. */
@@ -5954,12 +6474,6 @@ interface PptxPresentationProperties {
   showSubtitles?: boolean;
   /** Typed `p:prnPr` settings. Set to null during save to remove the element. */
   printProperties?: PptxPresentationPrintProperties | null;
-  /** @deprecated Use `printProperties.printWhat`; retained as a handout compatibility alias. */
-  printSlidesPerPage?: number;
-  /** @deprecated Use `printProperties.frameSlides`. */
-  printFrameSlides?: boolean;
-  /** @deprecated Use `printProperties.colorMode`. */
-  printColorMode?: 'clr' | 'gray' | 'bw';
   /** Most-recently-used colours from the presentation palette. */
   mruColors?: string[];
   /** Grid spacing in EMUs (cx, cy). Default is 914400 / 8 = 114300. */
@@ -6206,6 +6720,37 @@ interface PptxData {
    */
   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.
  *
@@ -6281,96 +6826,1415 @@ interface PptxEmbeddedFont {
   originalPartBytes?: Uint8Array;
 }
 
-/** Output format for the save pipeline. */
-type PptxSaveFormat = 'pptx' | 'ppsx' | 'pptm';
 //#endregion
-//#region src/converter/SvgExporter.d.ts
-/**
- * Options controlling SVG export behaviour.
- */
-interface SvgExportOptions {
-  /** Include hidden slides when exporting all. Default `false`. */
-  includeHidden?: boolean;
-  /** Slide indices to export (0-based). If omitted, all slides are exported. */
-  slideIndices?: number[];
-  /** Default font family when the element does not specify one. */
-  defaultFontFamily?: string;
-  /** Default font size in points when the element does not specify one. */
-  defaultFontSize?: number;
-}
-
-//#region src/theme/types.d.ts
+//#region src/core/types/theme-presets.d.ts
 /**
- * Theme configuration types for the PowerPoint viewer.
- *
- * All color values accept any valid CSS color string:
- * hex (`#6366f1`), rgb (`rgb(99 102 241)`), hsl (`hsl(239 84% 67%)`),
- * oklch (`oklch(0.585 0.233 277)`), named colors, etc.
+ * A complete theme preset that can be applied to a presentation.
  *
- * Framework-agnostic — shared by the React, Vue, and Angular bindings.
- */
-/**
- * Semantic color tokens for the viewer UI.
+ * @example
+ * ```ts
+ * import { THEME_PRESETS } from "pptx-viewer-core";
  *
- * These map to CSS custom properties (`--pptx-<token>`) and drive all
- * UI component colors. The naming follows the shadcn/ui convention so
- * that Tailwind + shadcn users get a familiar experience.
+ * const office = THEME_PRESETS.find(p => p.id === "office");
+ * await handler.switchTheme(office.colorScheme, office.fontScheme, office.name);
+ * ```
  */
-interface ViewerThemeColors {
-  /** Page / root background */
-  background: string;
-  /** Default text color */
-  foreground: string;
-  /** Card / panel surface */
-  card: string;
-  /** Text on card surfaces */
-  cardForeground: string;
-  /** Popover / dropdown surface */
-  popover: string;
-  /** Text inside popovers */
-  popoverForeground: string;
-  /** Primary action color (buttons, active indicators) */
-  primary: string;
-  /** Text on primary-colored backgrounds */
-  primaryForeground: string;
-  /** Secondary / subdued action color */
-  secondary: string;
-  /** Text on secondary backgrounds */
-  secondaryForeground: string;
-  /** Muted / disabled surface */
-  muted: string;
-  /** Text on muted surfaces (also used for secondary text) */
-  mutedForeground: string;
-  /** Accent / hover-highlight surface */
-  accent: string;
-  /** Text on accent surfaces */
-  accentForeground: string;
-  /** Destructive / danger action color */
-  destructive: string;
-  /** Text on destructive backgrounds */
-  destructiveForeground: string;
-  /** Default border color */
-  border: string;
-  /** Input field border color */
-  input: string;
-  /** Focus ring color */
-  ring: string;
+interface PptxThemePreset {
+  /** Unique identifier for the preset. */
+  id: string;
+  /** Human-readable display name. */
+  name: string;
+  /** The 12-colour scheme. */
+  colorScheme: PptxThemeColorScheme;
+  /** Heading and body font families. */
+  fontScheme: PptxThemeFontScheme;
 }
-/**
- * Full viewer theme configuration.
- *
- * Every property is optional — unset values fall back to the built-in
- * dark theme defaults.
- */
-interface ViewerTheme {
-  /** Semantic UI colors. Each key maps to a `--pptx-<key>` CSS custom property. */
-  colors?: Partial<ViewerThemeColors>;
-  /** Base border-radius value (e.g. `"0.5rem"`, `"8px"`). */
-  radius?: string;
-  /**
-   * Escape hatch: arbitrary CSS custom properties to set on the viewer
-   * root element. Keys should include the `--` prefix.
-   *
+//#endregion
+//#region src/core/builders/sdk/types.d.ts
+/** Position and size in pixels. Converted to EMU internally when needed. */
+interface ElementPosition {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  rotation?: number;
+}
+type FillInput = {
+  type: 'solid';
+  color: string;
+  opacity?: number;
+} | {
+  type: 'gradient';
+  angle?: number;
+  gradientType?: 'linear' | 'radial';
+  stops: Array<{
+    color: string;
+    position: number;
+    opacity?: number;
+  }>;
+} | {
+  type: 'pattern';
+  preset: string;
+  foreground?: string;
+  background?: string;
+} | {
+  type: 'image';
+  url: string;
+  mode?: 'stretch' | 'tile';
+} | {
+  type: 'none';
+};
+interface StrokeInput {
+  color?: string;
+  width?: number;
+  dash?: StrokeDashType;
+  opacity?: number;
+  join?: 'round' | 'bevel' | 'miter';
+  cap?: 'flat' | 'rnd' | 'sq';
+}
+interface ShadowInput {
+  color?: string;
+  blur?: number;
+  offsetX?: number;
+  offsetY?: number;
+  opacity?: number;
+}
+interface TextStyleInput {
+  fontSize?: number;
+  fontFamily?: string;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  strikethrough?: boolean;
+  color?: string;
+  alignment?: 'left' | 'center' | 'right' | 'justify';
+  verticalAlignment?: 'top' | 'middle' | 'bottom';
+  lineSpacing?: number;
+  spaceBefore?: number;
+  spaceAfter?: number;
+}
+interface TextSegmentInput {
+  text: string;
+  style?: Partial<TextStyleInput>;
+}
+interface TextOptions extends Partial<ElementPosition> {
+  fontSize?: number;
+  fontFamily?: string;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  strikethrough?: boolean;
+  color?: string;
+  alignment?: 'left' | 'center' | 'right' | 'justify';
+  verticalAlignment?: 'top' | 'middle' | 'bottom';
+  lineSpacing?: number;
+  fill?: FillInput;
+  stroke?: StrokeInput;
+  shadow?: ShadowInput;
+  opacity?: number;
+}
+interface ShapeOptions extends Partial<ElementPosition> {
+  fill?: FillInput;
+  stroke?: StrokeInput;
+  text?: string;
+  textStyle?: Partial<TextStyleInput>;
+  adjustments?: Record<string, number>;
+  shadow?: ShadowInput;
+  opacity?: number;
+}
+interface ImageOptions extends Partial<ElementPosition> {
+  altText?: string;
+  cropLeft?: number;
+  cropTop?: number;
+  cropRight?: number;
+  cropBottom?: number;
+  opacity?: number;
+}
+interface TableInput {
+  rows: TableRowInput[];
+  columnWidths?: number[];
+  style?: string;
+  bandRows?: boolean;
+  bandColumns?: boolean;
+  firstRow?: boolean;
+  lastRow?: boolean;
+  firstCol?: boolean;
+  lastCol?: boolean;
+}
+interface TableRowInput {
+  cells: TableCellInput[];
+  height?: number;
+}
+interface TableCellInput {
+  text: string;
+  style?: Partial<TextStyleInput>;
+  fill?: FillInput;
+  gridSpan?: number;
+  rowSpan?: number;
+}
+interface TableOptions extends Partial<ElementPosition> {}
+interface ChartSeriesInput {
+  name: string;
+  values: number[];
+  color?: string;
+  boxWhiskerOptions?: PptxChartBoxWhiskerOptions;
+  histogramOptions?: PptxChartHistogramOptions;
+  waterfallOptions?: PptxChartWaterfallOptions;
+  regionMapOptions?: PptxChartRegionMapOptions;
+  treemapOptions?: PptxChartTreemapOptions;
+}
+interface ChartInput {
+  series: ChartSeriesInput[];
+  categories: string[];
+  /** ChartEx hierarchy levels in leaf-to-root XML order. */
+  categoryLevels?: string[][];
+  title?: string;
+  hasLegend?: boolean;
+  legendPosition?: 't' | 'b' | 'l' | 'r' | 'tr';
+  grouping?: 'clustered' | 'stacked' | 'percentStacked';
+}
+interface ChartOptions extends Partial<ElementPosition> {}
+interface ConnectorOptions extends Partial<ElementPosition> {
+  type?: 'straight' | 'bent' | 'curved';
+  stroke?: StrokeInput;
+  startArrow?: ConnectorArrowType;
+  endArrow?: ConnectorArrowType;
+  from?: {
+    elementId: string;
+    site: number;
+  };
+  to?: {
+    elementId: string;
+    site: number;
+  };
+}
+interface MediaOptions extends Partial<ElementPosition> {
+  autoPlay?: boolean;
+  loop?: boolean;
+  volume?: number;
+  trimStartMs?: number;
+  trimEndMs?: number;
+  posterFrame?: string;
+}
+interface GroupOptions extends Partial<ElementPosition> {}
+type BackgroundInput = {
+  type: 'solid';
+  color: string;
+} | {
+  type: 'gradient';
+  angle?: number;
+  stops: Array<{
+    color: string;
+    position: number;
+  }>;
+} | {
+  type: 'image';
+  source: string;
+};
+interface TransitionInput {
+  type: PptxTransitionType;
+  duration?: number;
+  direction?: string;
+  advanceAfterMs?: number;
+}
+interface AnimationInput {
+  preset: PptxAnimationPreset;
+  trigger?: PptxAnimationTrigger;
+  duration?: number;
+  delay?: number;
+}
+interface PresentationOptions {
+  /** Slide width in EMU. Default: 12192000 (16:9 widescreen). */
+  width?: number;
+  /** Slide height in EMU. Default: 6858000 (16:9 widescreen). */
+  height?: number;
+  /** Theme configuration. */
+  theme?: PresentationThemeInput;
+  /** Presentation title (stored in docProps/core.xml). */
+  title?: string;
+  /** Presentation author. */
+  creator?: string;
+  /**
+   * Number of blank slides to include in the initial presentation.
+   * Default: 0 (no slides). Slides use the "Blank" layout.
+   */
+  initialSlideCount?: number;
+}
+interface PresentationThemeInput {
+  name?: string;
+  colors?: {
+    dk1?: string;
+    lt1?: string;
+    dk2?: string;
+    lt2?: string;
+    accent1?: string;
+    accent2?: string;
+    accent3?: string;
+    accent4?: string;
+    accent5?: string;
+    accent6?: string;
+    hlink?: string;
+    folHlink?: string;
+  };
+  fonts?: {
+    majorFont?: string;
+    minorFont?: string;
+  };
+}
+//#endregion
+//#region src/core/builders/sdk/SlideBuilder.d.ts
+/**
+ * Fluent builder for a single slide.
+ *
+ * @example
+ * ```ts
+ * const slide = new SlideBuilder(1)
+ *   .addText("Hello World", { fontSize: 36, bold: true, x: 100, y: 50 })
+ *   .addShape("roundRect", { fill: { type: "solid", color: "#4472C4" } })
+ *   .setNotes("Remember to mention key points")
+ *   .setBackground({ type: "solid", color: "#F5F5F5" })
+ *   .build();
+ * ```
+ */
+declare class SlideBuilder {
+  private readonly slide;
+  /**
+   * @param slideNumber - 1-based slide number.
+   * @param layoutPath - Optional layout archive path.
+   * @param layoutName - Optional layout display name.
+   */
+  constructor(slideNumber: number, layoutPath?: string, layoutName?: string);
+  /** Add a text box to the slide. */
+  addText(text: string | TextSegmentInput[], options?: TextOptions): this;
+  /** Add a shape to the slide. */
+  addShape(shapeType: string, options?: ShapeOptions): this;
+  /** Add a connector (line) to the slide. */
+  addConnector(options?: ConnectorOptions): this;
+  /** Add an image to the slide. */
+  addImage(source: string, options?: ImageOptions): this;
+  /** Add a table to the slide. */
+  addTable(input: TableInput, options?: TableOptions): this;
+  /** Add a chart to the slide. */
+  addChart(chartType: PptxChartType, input: ChartInput, options?: ChartOptions): this;
+  /** Add a media element (video or audio) to the slide. */
+  addMedia(mediaType: 'video' | 'audio', source: string, options?: MediaOptions): this;
+  /** Add a group of elements to the slide. */
+  addGroup(children: PptxElement[], options?: GroupOptions): this;
+  /** Add a pre-built element directly. */
+  addElement(element: PptxElement): this;
+  /** Set slide background. */
+  setBackground(bg: BackgroundInput): this;
+  /** Set slide transition. */
+  setTransition(input: TransitionInput): this;
+  /** Add an animation to an element on this slide. */
+  addAnimation(elementId: string, input: AnimationInput): this;
+  /** Set speaker notes. */
+  setNotes(text: string): this;
+  /** Mark the slide as hidden. */
+  setHidden(hidden: boolean): this;
+  /** Assign the slide to a section. */
+  setSection(name: string, id?: string): this;
+  /**
+   * Add a freeform shape from SVG path data.
+   *
+   * Creates a custom-geometry shape element using the provided SVG path
+   * string and appends it to the slide's element list.
+   *
+   * @param pathData - An SVG path data string (e.g. `"M 0 0 L 100 50 L 50 100 Z"`).
+   * @param options - Optional position, styling, and size overrides.
+   * @returns The builder instance for chaining.
+   *
+   * @example
+   * ```ts
+   * new SlideBuilder(1)
+   *   .addFreeform("M 0 0 C 33 0 66 100 100 100", {
+   *     stroke: { color: "#FF0000", width: 2 },
+   *   })
+   *   .build();
+   * ```
+   */
+  addFreeform(pathData: string, options?: ShapeOptions): this;
+  /**
+   * Add a pre-built element from any element builder (calls `.build()` for you).
+   *
+   * Accepts any object with a `build()` method that returns a {@link PptxElement},
+   * such as {@link TextBuilder}, {@link ShapeBuilder}, {@link ImageBuilder}, etc.
+   *
+   * @param builder - An element builder with a `.build()` method.
+   * @returns The builder instance for chaining.
+   *
+   * @example
+   * ```ts
+   * const title = TextBuilder.create("Hello").fontSize(36).bold();
+   * new SlideBuilder(1).addBuilderElement(title).build();
+   * ```
+   */
+  addBuilderElement(builder: {
+    build(): PptxElement;
+  }): this;
+  /**
+   * Remove an element by its ID.
+   *
+   * Filters out the element with the given ID from the slide's element list.
+   * If no element matches, the slide is left unchanged.
+   *
+   * @param elementId - The unique ID of the element to remove.
+   * @returns The builder instance for chaining.
+   *
+   * @example
+   * ```ts
+   * const slide = new SlideBuilder(1)
+   *   .addText("temp", { x: 0, y: 0 })
+   *   .removeElement("txt_abc123_1")
+   *   .build();
+   * ```
+   */
+  removeElement(elementId: string): this;
+  /**
+   * Get the current list of elements on this slide.
+   *
+   * Returns a readonly view of the elements array. Useful for inspecting
+   * what has been added so far during the build process.
+   *
+   * @returns A readonly array of the slide's current elements.
+   *
+   * @example
+   * ```ts
+   * const builder = new SlideBuilder(1).addText("Hi");
+   * console.log(builder.getElements().length); // 1
+   * ```
+   */
+  getElements(): readonly PptxElement[];
+  /**
+   * Get the number of elements on this slide.
+   *
+   * @returns The count of elements currently added to the slide.
+   *
+   * @example
+   * ```ts
+   * const builder = new SlideBuilder(1)
+   *   .addText("A").addText("B");
+   * console.log(builder.elementCount); // 2
+   * ```
+   */
+  get elementCount(): number;
+  /**
+   * Get the last added element (useful for getting its ID for animations).
+   *
+   * Returns `undefined` if the slide has no elements yet.
+   *
+   * @returns The most recently added element, or `undefined`.
+   *
+   * @example
+   * ```ts
+   * const builder = new SlideBuilder(1).addShape("rect");
+   * const shape = builder.getLastElement();
+   * if (shape) {
+   *   builder.addAnimation(shape.id, { preset: "fadeIn" });
+   * }
+   * ```
+   */
+  getLastElement(): PptxElement | undefined;
+  /**
+   * Set the slide name/title for organizational purposes.
+   *
+   * Stores an arbitrary name string on the slide object. This is useful
+   * for labeling slides in tooling or custom workflows.
+   *
+   * @param name - The display name to assign to the slide.
+   * @returns The builder instance for chaining.
+   *
+   * @example
+   * ```ts
+   * new SlideBuilder(1)
+   *   .setName("Introduction")
+   *   .addText("Welcome!")
+   *   .build();
+   * ```
+   */
+  setName(name: string): this;
+  /** Return the built {@link PptxSlide}. */
+  build(): PptxSlide;
+}
+//#endregion
+//#region src/core/builders/sdk/PresentationBuilder.d.ts
+/** Result returned by {@link PresentationBuilder.create}. */
+interface PresentationBuilderResult {
+  /** Initialized handler ready for editing and saving. */
+  handler: PptxHandler;
+  /** Parsed presentation data. */
+  data: PptxData;
+  /** Convenience slide builder factory. */
+  createSlide: (layoutName?: string) => SlideBuilder;
+}
+//#endregion
+//#region src/core/builders/fluent/PptxXmlBuilder.d.ts
+/**
+ * Fluent interface for navigating and mutating a {@link PptxData} structure.
+ * Provides method-chaining access to slides, elements, and notes.
+ */
+interface IPptxXmlBuilder {
+  /** Navigate to a slide by zero-based index (Pascal-case alias). */
+  Slides(index: number): PptxSlideBuilder;
+  /** Navigate to a slide by zero-based index. */
+  slide(index: number): PptxSlideBuilder;
+  /** Navigate to a slide by zero-based index (plural alias). */
+  slides(index: number): PptxSlideBuilder;
+  /** Return the underlying presentation data. */
+  project(): PptxData;
+}
+/**
+ * Root builder of the fluent PPTX editing API.
+ *
+ * Wraps a {@link PptxData} object and provides chainable accessors
+ * to navigate into slides, elements, and notes for in-place mutation.
+ */
+declare class PptxXmlBuilder implements IPptxXmlBuilder {
+  /** The presentation data being mutated. */
+  private readonly data;
+  /** @param data - The presentation data to wrap. */
+  constructor(data: PptxData);
+  /**
+   * Factory method to create a builder from presentation data.
+   * @param data - The presentation data to wrap.
+   * @returns A new {@link PptxXmlBuilder} instance.
+   */
+  static from(data: PptxData): PptxXmlBuilder;
+  /** @inheritdoc */
+  Slides(index: number): PptxSlideBuilder;
+  /**
+   * Navigate to a slide by zero-based index.
+   * @param index - Zero-based slide index.
+   * @returns A {@link PptxSlideBuilder} for the requested slide.
+   * @throws Error if index is not an integer or is out of range.
+   */
+  slide(index: number): PptxSlideBuilder;
+  /** @inheritdoc */
+  slides(index: number): PptxSlideBuilder;
+  /** Return the underlying {@link PptxData}. */
+  project(): PptxData;
+  /** Pascal-case alias for {@link project}. */
+  Project(): PptxData;
+}
+/**
+ * Fluent builder scoped to a single slide.
+ * Provides navigation to the slide's elements and notes.
+ */
+declare class PptxSlideBuilder {
+  /** The slide being operated on. */
+  private readonly slideValue;
+  /** Reference back to the root builder for chaining. */
+  private readonly rootBuilder;
+  /**
+   * @param slideValue - The slide data.
+   * @param rootBuilder - The parent builder.
+   */
+  constructor(slideValue: PptxSlide, rootBuilder: PptxXmlBuilder);
+  /** Navigate to the slide's notes builder (getter). */
+  get Notes(): PptxSlideNotesBuilder;
+  /** Navigate to the slide's notes builder. */
+  notes(): PptxSlideNotesBuilder;
+  /** Navigate to the slide's elements builder. */
+  elements(): PptxSlideElementsBuilder;
+  /** Return the underlying slide data. */
+  project(): PptxSlide;
+  /** Pascal-case alias for {@link project}. */
+  Project(): PptxSlide;
+  /** Navigate back to the root builder. */
+  done(): PptxXmlBuilder;
+  /** Pascal-case alias for {@link done}. */
+  Done(): PptxXmlBuilder;
+}
+/**
+ * Fluent builder for manipulating the elements array of a single slide.
+ * Supports adding, removing, and updating elements by ID.
+ */
+declare class PptxSlideElementsBuilder {
+  private readonly slideValue;
+  private readonly slideBuilder;
+  /**
+   * @param slideValue - The slide whose elements are being modified.
+   * @param slideBuilder - The parent slide builder for chaining.
+   */
+  constructor(slideValue: PptxSlide, slideBuilder: PptxSlideBuilder);
+  /**
+   * Append an element to the slide's element list.
+   * @param element - The element to add.
+   * @returns This builder for chaining.
+   */
+  add(element: PptxElement): this;
+  /**
+   * Remove an element from the slide by its ID.
+   * @param elementId - The ID of the element to remove.
+   * @returns This builder for chaining.
+   */
+  removeById(elementId: string): this;
+  /**
+   * Update an element in-place by ID using a transform function.
+   * @param elementId - The ID of the element to update.
+   * @param updater - A function that receives the current element and returns the replacement.
+   * @returns This builder for chaining.
+   */
+  updateById(elementId: string, updater: (current: PptxElement) => PptxElement): this;
+  /** Return the current elements array. */
+  project(): PptxElement[];
+  /** Navigate back to the slide builder. */
+  done(): PptxSlideBuilder;
+}
+/**
+ * Fluent builder for manipulating speaker notes on a single slide.
+ * Supports adding, setting, clearing, and retrieving notes text.
+ */
+declare class PptxSlideNotesBuilder {
+  private readonly slideValue;
+  private readonly slideBuilder;
+  /**
+   * @param slideValue - The slide whose notes are being modified.
+   * @param slideBuilder - The parent slide builder for chaining.
+   */
+  constructor(slideValue: PptxSlide, slideBuilder: PptxSlideBuilder);
+  /**
+   * Append text to existing notes (separated by newline).
+   * @param text - The text to append.
+   * @returns This builder for chaining.
+   */
+  add(text: string): this;
+  /** Pascal-case alias for {@link add}. */
+  Add(text: string): this;
+  /**
+   * Replace all notes with the given text.
+   * @param text - The replacement notes text. Empty string clears notes.
+   * @returns This builder for chaining.
+   */
+  set(text: string): this;
+  /** Pascal-case alias for {@link set}. */
+  Set(text: string): this;
+  /** Remove all notes from the slide. */
+  clear(): this;
+  /** Pascal-case alias for {@link clear}. */
+  Clear(): this;
+  /** Return the current notes text, or `undefined` if none. */
+  get(): string | undefined;
+  /** Pascal-case alias for {@link get}. */
+  Get(): string | undefined;
+  /** Navigate back to the slide builder. */
+  done(): PptxSlideBuilder;
+  /** Pascal-case alias for {@link done}. */
+  Done(): PptxSlideBuilder;
+  /**
+   * Synchronize the `notesSegments` array from the plain-text notes string.
+   * Splits text on newlines and creates corresponding {@link TextSegment} entries
+   * with paragraph break markers between lines.
+   */
+  private syncSegmentsFromNotes;
+}
+//#endregion
+//#region src/core/core/types.d.ts
+interface PptxHandlerLoadOptions {
+  eagerDecodeImages?: boolean;
+  password?: string;
+  /**
+   * Maximum total uncompressed bytes accepted from the input ZIP archive.
+   * Defaults to 500 MiB. When the sum of `_data.uncompressedSize` across
+   * all archive entries exceeds this cap, `load()` rejects with a
+   * {@link ZipBombError}. A hard cap of 65 536 archive entries also
+   * applies.
+   */
+  maxUncompressedBytes?: number;
+  /**
+   * When `false` (default), relationship targets that resolve to
+   * `http://` or `https://` URLs are dropped from rendered slides
+   * (image, picture, background). Set to `true` to allow external image
+   * URLs to flow through to `<img src>`.
+   *
+   * Disabled by default to mitigate SSRF / privacy-leak vectors in
+   * server-side rendering and headless export pipelines.
+   */
+  allowExternalImages?: boolean;
+}
+/** Output format for the save pipeline. */
+type PptxSaveFormat = 'pptx' | 'ppsx' | 'pptm';
+interface PptxHandlerSaveOptions {
+  headerFooter?: PptxHeaderFooter;
+  presentationProperties?: PptxPresentationProperties;
+  customShows?: PptxCustomShow[];
+  sections?: PptxSection[];
+  coreProperties?: PptxCoreProperties;
+  appProperties?: PptxAppProperties;
+  customProperties?: PptxCustomProperty[];
+  /** Updated notes master data to save back to notesMaster1.xml. */
+  notesMaster?: PptxNotesMaster;
+  /** Updated handout master data to save back to handoutMaster1.xml. */
+  handoutMaster?: PptxHandoutMaster;
+  /**
+   * Updated slide masters to save back to ppt/slideMasters/slideMaster*.xml.
+   * Each entry in the array applies typed mutations (clrMap, hf flags,
+   * background) to the master at its `path`. Masters not listed here pass
+   * through verbatim from the original load.
+   */
+  slideMasters?: PptxSlideMaster[];
+  /**
+   * Updated slide layouts to save back to ppt/slideLayouts/slideLayout*.xml.
+   * Each entry applies typed mutations (clrMapOverride, attrs, hf flags,
+   * background) to the layout at its `path`. Layouts not listed here pass
+   * through verbatim from the original load.
+   */
+  slideLayouts?: PptxSlideLayout[];
+  /** Updated tag collections to save back to ppt/tags/tag*.xml. */
+  tags?: PptxTagCollection[];
+  /** Presentation-level customer data references to author or update. */
+  customerData?: PptxCustomerData[];
+  /** Photo album metadata to save back to `p:photoAlbum`. */
+  photoAlbum?: PptxPhotoAlbum;
+  /** East Asian line-break settings to save back to `p:kinsoku`. */
+  kinsoku?: PptxKinsoku | null;
+  /** Write-protection verifier. Set to `null` to remove, `undefined` to preserve existing. */
+  modifyVerifier?: PptxModifyVerifier | null;
+  /** View properties to save back to ppt/viewProps.xml. */
+  viewProperties?: PptxViewProperties;
+  /**
+   * Table style edits to save back to `ppt/tableStyles.xml`. Pass the
+   * `tableStyleMap` from `PptxData` (optionally with edited entries)
+   * to persist user edits. The `def` GUID and any unmodelled XML are
+   * preserved verbatim. Omitting the option round-trips the original
+   * part untouched.
+   */
+  tableStyles?: ParsedTableStyleMap;
+  /**
+   * Target output format.
+   * - `'pptx'` (default): Standard presentation.
+   * - `'ppsx'`: Slide-show file (opens in presentation mode).
+   * - `'pptm'`: Macro-enabled presentation (requires VBA data).
+   */
+  outputFormat?: PptxSaveFormat;
+  /**
+   * Embedded fonts to write back (or add) to the saved PPTX.
+   *
+   * Pass the `embeddedFonts` array from `PptxData` to preserve existing
+   * embedded fonts during save. You can also add new fonts by including
+   * entries with `rawFontData` populated.
+   *
+   * When omitted, the save pipeline will automatically re-embed any
+   * fonts that were loaded from the original PPTX and have `rawFontData`
+   * preserved (i.e. the default is lossless round-trip).
+   */
+  embeddedFonts?: PptxEmbeddedFont[];
+  /** Typed embedded-font list metadata. Set to null to remove fonts and relationships. */
+  embeddedFontList?: PptxEmbeddedFontList | null;
+  /**
+   * OOXML conformance class for the saved output.
+   * - `'preserve'` (default): use the same conformance as the loaded file.
+   * - `'strict'`: force Strict Open XML (ISO/IEC 29500) namespace URIs.
+   * - `'transitional'`: force Transitional (ECMA-376) namespace URIs.
+   */
+  conformance?: 'strict' | 'transitional' | 'preserve';
+}
+interface IPptxHandlerRuntime {
+  /**
+   * Release all resources held by this runtime (Blob URLs, caches, ZIP).
+   * After calling, the runtime cannot be used further.
+   */
+  dispose(): void;
+  /**
+   * Revoke all Blob URLs created during image loading.
+   */
+  revokeBlobUrls(): void;
+  getCompatibilityWarnings(): PptxCompatibilityWarning[];
+  getLayoutOptions(): PptxLayoutOption[];
+  createXmlBuilder(data: PptxData): PptxXmlBuilder;
+  Builder(data: PptxData): PptxXmlBuilder;
+  setTemplateBackground(path: string, backgroundColor: string | undefined): void;
+  setPresentationTheme(themePath: string, applyToAllMasters?: boolean): Promise<void>;
+  getTemplateBackgroundColor(path: string): string | undefined;
+  updateThemeColorScheme(colorScheme: PptxThemeColorScheme): Promise<void>;
+  updateThemeFontScheme(fontScheme: PptxThemeFontScheme): Promise<void>;
+  updateThemeName(name: string): Promise<void>;
+  applyTheme(colorScheme: PptxThemeColorScheme, fontScheme: PptxThemeFontScheme, themeName?: string): Promise<void>;
+  load(data: ArrayBuffer, options?: PptxHandlerLoadOptions): Promise<PptxData>;
+  getChartDataForGraphicFrame(slidePath: string, graphicFrame: XmlObject | undefined): Promise<PptxChartData | undefined>;
+  getSmartArtDataForGraphicFrame(slidePath: string, graphicFrame: XmlObject | undefined): Promise<PptxSmartArtData | undefined>;
+  getImageData(imagePath: string): Promise<string | undefined>;
+  /**
+   * Extract a media file from the PPTX archive as an ArrayBuffer.
+   * Returns undefined if the file is not found.
+   */
+  getMediaArrayBuffer(mediaPath: string): Promise<ArrayBuffer | undefined>;
+  save(slides: PptxSlide[], options?: PptxHandlerSaveOptions): Promise<Uint8Array>;
+  exportSlides(slides: PptxSlide[], options: PptxExportOptions): Promise<Map<number, Uint8Array>>;
+  /**
+   * Get the available slide layouts for a specific slide, based on the
+   * slide's master. Scans the slide master's relationships to find all
+   * layouts that belong to it.
+   *
+   * @param slideIndex - Zero-based slide index.
+   * @param slides - Current slides array.
+   * @returns Array of layout options belonging to the same slide master.
+   */
+  getAvailableLayoutsForSlide(slideIndex: number, slides: PptxSlide[]): Promise<PptxLayoutOption[]>;
+  /**
+   * Resolve the editable template (master + layout) elements a slide
+   * inherits, each carrying a `master-` / `layout-` prefixed id. Excludes
+   * placeholders; returns only decorative shapes/pictures/graphic frames.
+   *
+   * @param slideId - The slide's archive path (`PptxSlide.id`).
+   */
+  getTemplateElementsForSlide(slideId: string): Promise<PptxElement[]>;
+  /**
+   * Scan the loaded PPTX archive for all theme parts.
+   */
+  getAvailableThemes(): Promise<Array<{
+    path: string;
+    name?: string;
+  }>>;
+  /**
+   * Apply a different layout to an existing slide by updating the slide's
+   * relationship to point to the new layout and re-parsing layout
+   * placeholders / background.
+   *
+   * @param slideIndex - Zero-based slide index.
+   * @param layoutPath - Archive path of the target layout
+   *                     (e.g. `ppt/slideLayouts/slideLayout2.xml`).
+   * @param slides - Current slides array.
+   * @returns The updated slide with new layout path, name, and background.
+   */
+  applyLayoutToSlide(slideIndex: number, layoutPath: string, slides: PptxSlide[]): Promise<PptxSlide>;
+}
+//#endregion
+//#region src/core/core/PptxHandlerRuntimeFactory.d.ts
+/**
+ * Abstract factory contract for creating {@link IPptxHandlerRuntime}
+ * instances.
+ *
+ * Implement this interface to supply a custom runtime (e.g. a
+ * WASM-backed or test-double runtime) to {@link PptxHandlerCore}.
+ */
+interface IPptxHandlerRuntimeFactory {
+  /** Instantiate and return a new runtime implementation. */
+  createRuntime(): IPptxHandlerRuntime;
+}
+//#endregion
+//#region src/core/utils/ooxml-crypto-types.d.ts
+/**
+ * Type definitions for OOXML encryption and decryption.
+ *
+ * Contains all interfaces and type aliases used by the OOXML crypto modules.
+ *
+ * @module ooxml-crypto-types
+ */
+/** Supported encryption algorithms. */
+type EncryptionAlgorithm = 'AES128' | 'AES256';
+/** Encryption options for creating encrypted files. */
+interface EncryptionOptions {
+  /** The encryption algorithm to use (defaults to AES256). */
+  algorithm?: EncryptionAlgorithm;
+  /** Number of hash iterations for key derivation (defaults to 100000). Lower values speed up tests. */
+  spinCount?: number;
+}
+//#endregion
+//#region src/core/PptxHandlerCore.d.ts
+/**
+ * Dependency injection options for {@link PptxHandlerCore}.
+ *
+ * Provide either `runtime` (an already-constructed runtime) or
+ * `runtimeFactory` (a factory that will be called once). When neither
+ * is supplied the default runtime is created automatically.
+ *
+ * @example
+ * ```ts
+ * // Use the default runtime:
+ * const core = new PptxHandlerCore();
+ *
+ * // Inject a custom runtime:
+ * const core = new PptxHandlerCore({ runtime: myRuntime });
+ *
+ * // Supply a factory for lazy creation:
+ * const core = new PptxHandlerCore({ runtimeFactory: myFactory });
+ * // => PptxHandlerCore instance with injected runtime
+ * ```
+ */
+interface PptxHandlerCoreDependencies {
+  runtime?: IPptxHandlerRuntime;
+  runtimeFactory?: IPptxHandlerRuntimeFactory;
+}
+/**
+ * Thin facade over the PPTX runtime implementation.
+ *
+ * All heavy parsing, serialisation, and XML manipulation is delegated to an
+ * {@link IPptxHandlerRuntime}. This surface stays stable and small so that
+ * callers remain decoupled from the runtime internals and host-specific
+ * runtime swaps (e.g. WASM vs Node) can be done transparently.
+ *
+ * @remarks
+ * - Constructed once per open document.
+ * - Errors from encrypted files are caught at `load()` time via
+ *   {@link EncryptedFileError}.
+ * - `PptxXmlBuilder` instances returned by `createXmlBuilder()` / `Builder()`
+ *   operate directly on the runtime’s in-memory ZIP.
+ *
+ * @example
+ * ```ts
+ * const handler = new PptxHandlerCore();
+ * const data    = await handler.load(arrayBuffer);
+ * // ... mutate slides ...
+ * const out     = await handler.save(data.slides);
+ * // => Uint8Array of the modified .pptx file
+ * ```
+ */
+declare class PptxHandlerCore {
+  private readonly runtime;
+  /**
+   * Create a new handler, optionally injecting a custom runtime.
+   *
+   * Resolution order:
+   * 1. `dependencies.runtime` — use as-is.
+   * 2. `dependencies.runtimeFactory` — call `createRuntime()` once.
+   * 3. Fall back to {@link createDefaultPptxHandlerRuntime}.
+   *
+   * @param dependencies - Optional runtime or factory override.
+   *
+   * @example
+   * ```ts
+   * const core = new PptxHandlerCore();
+   * // => PptxHandlerCore instance with default runtime
+   * ```
+   */
+  constructor(dependencies?: PptxHandlerCoreDependencies);
+  /**
+   * Release all resources held by this handler instance.
+   *
+   * Revokes every Blob URL created for images/media, clears all
+   * in-memory caches, and releases the in-memory ZIP archive.
+   *
+   * Call this when the handler is no longer needed (e.g. component
+   * unmount) to free memory immediately rather than waiting for GC.
+   *
+   * After calling `dispose()`, do not call any other methods — create
+   * a new `PptxHandler` instance instead.
+   */
+  dispose(): void;
+  /**
+   * Return any compatibility warnings detected during the most recent load.
+   *
+   * Warnings indicate features the editor cannot fully represent (e.g.
+   * SmartArt, 3-D effects, embedded OLE objects).
+   *
+   * @returns Array of {@link PptxCompatibilityWarning} objects.
+   */
+  getCompatibilityWarnings(): PptxCompatibilityWarning[];
+  /**
+   * Get the slide layout options available in the loaded presentation.
+   *
+   * Each option maps to a `<p:sldLayout>` inside the PPTX archive.
+   *
+   * @returns Array of {@link PptxLayoutOption} entries.
+   */
+  getLayoutOptions(): PptxLayoutOption[];
+  /**
+   * Create a fluent XML builder scoped to the given presentation data.
+   *
+   * The builder provides a chainable API for constructing and inserting
+   * OpenXML nodes directly into the runtime’s in-memory ZIP.
+   *
+   * @param data - The parsed {@link PptxData} to bind the builder to.
+   * @returns A new {@link PptxXmlBuilder} instance.
+   */
+  createXmlBuilder(data: PptxData): PptxXmlBuilder;
+  /**
+   * Shorthand alias for {@link createXmlBuilder}.
+   *
+   * @param data - Parsed presentation data.
+   * @returns A {@link PptxXmlBuilder} instance.
+   */
+  Builder(data: PptxData): PptxXmlBuilder;
+  /**
+   * Register a background image for a specific template layout path.
+   *
+   * @param path - The internal PPTX path (e.g. `ppt/slideLayouts/slideLayout1.xml`).
+   * @param backgroundColor - Optional hex colour to render behind the image.
+   */
+  setTemplateBackground(path: string, backgroundColor: string | undefined): void;
+  /**
+   * Retrieve the background colour previously set for a template layout.
+   *
+   * @param path - The internal PPTX layout path.
+   * @returns Hex colour string, or `undefined` if none was set.
+   */
+  getTemplateBackgroundColor(path: string): string | undefined;
+  /**
+   * Replace the presentation’s theme by loading an external `.thmx` file.
+   *
+   * @param themePath - Absolute or relative path to the `.thmx` file.
+   * @param applyToAllMasters - Apply to every slide master (default `true`).
+   *
+   * @example
+   * ```ts
+   * await handler.setPresentationTheme("./themes/corporate.thmx");
+   * // => void — theme XML replaced in the in-memory ZIP
+   * ```
+   */
+  setPresentationTheme(themePath: string, applyToAllMasters?: boolean): Promise<void>;
+  /**
+   * Modify the theme’s colour scheme (accent colours, background, text, etc.).
+   *
+   * @param colorScheme - A {@link PptxThemeColorScheme} with hex colour values.
+   *
+   * @example
+   * ```ts
+   * await handler.updateThemeColorScheme({
+   *   dk1: "#1A1A2E", dk2: "#16213E",
+   *   lt1: "#FFFFFF", lt2: "#E8E8E8",
+   *   accent1: "#0F3460", accent2: "#533483",
+   *   accent3: "#E94560", accent4: "#F0A500",
+   * });
+   * // => void — colour scheme updated in the in-memory theme XML
+   * ```
+   */
+  updateThemeColorScheme(colorScheme: PptxThemeColorScheme): Promise<void>;
+  /**
+   * Update the theme’s font scheme (heading + body typefaces).
+   *
+   * @param fontScheme - A {@link PptxThemeFontScheme} with font family names.
+   *
+   * @example
+   * ```ts
+   * await handler.updateThemeFontScheme({
+   *   majorFont: "Montserrat",
+   *   minorFont: "Open Sans",
+   * });
+   * // => void — font scheme updated in the in-memory theme XML
+   * ```
+   */
+  updateThemeFontScheme(fontScheme: PptxThemeFontScheme): Promise<void>;
+  /**
+   * Rename the presentation theme.
+   *
+   * @param name - New display name for the theme.
+   */
+  updateThemeName(name: string): Promise<void>;
+  /**
+   * Apply a complete theme in one call (colour scheme + font scheme + optional name).
+   *
+   * This is a convenience wrapper over {@link updateThemeColorScheme},
+   * {@link updateThemeFontScheme}, and {@link updateThemeName}.
+   *
+   * @param colorScheme - Colour definitions.
+   * @param fontScheme  - Font definitions.
+   * @param themeName   - Optional theme display name.
+   *
+   * @example
+   * ```ts
+   * await handler.applyTheme(
+   *   { dk1: "#000", lt1: "#FFF", accent1: "#0066CC", /* … *\/ },
+   *   { majorFont: "Helvetica", minorFont: "Arial" },
+   *   "Corporate 2025",
+   * );
+   * // => void — colour scheme, font scheme, and name applied atomically
+   * ```
+   */
+  applyTheme(colorScheme: PptxThemeColorScheme, fontScheme: PptxThemeFontScheme, themeName?: string): Promise<void>;
+  /**
+   * Switch the presentation's theme, updating both the underlying XML and
+   * re-resolving all element colours in-place.
+   *
+   * This is the high-level API for theme switching: it updates the theme
+   * data in the ZIP, then patches all resolved colours in the provided
+   * `PptxData` so that elements immediately reflect the new colour scheme
+   * without requiring a re-parse.
+   *
+   * @param data - The current parsed presentation data (mutated in-place for
+   *   convenience, but a new `PptxData` object is also returned).
+   * @param colorScheme - New colour scheme (12 colours).
+   * @param fontScheme - Optional new font scheme.
+   * @param themeName - Optional theme display name.
+   * @returns The updated PptxData with re-resolved colours.
+   *
+   * @example
+   * ```ts
+   * import { THEME_PRESETS } from "pptx-viewer-core";
+   *
+   * const ion = THEME_PRESETS.find(p => p.id === "ion")!;
+   * const newData = await handler.switchTheme(
+   *   data,
+   *   ion.colorScheme,
+   *   ion.fontScheme,
+   *   ion.name,
+   * );
+   * // => PptxData with all colours updated to the Ion theme
+   * ```
+   */
+  switchTheme(data: PptxData, colorScheme: PptxThemeColorScheme, fontScheme?: PptxThemeFontScheme, themeName?: string): Promise<PptxData>;
+  /**
+   * Apply a built-in theme preset to the presentation.
+   *
+   * Convenience wrapper around {@link switchTheme} that accepts a
+   * {@link PptxThemePreset} directly.
+   *
+   * @param data - The current parsed presentation data.
+   * @param preset - One of the built-in presets from {@link THEME_PRESETS}.
+   * @returns The updated PptxData.
+   *
+   * @example
+   * ```ts
+   * import { THEME_PRESETS } from "pptx-viewer-core";
+   *
+   * const preset = THEME_PRESETS.find(p => p.id === "facet")!;
+   * const newData = await handler.switchThemePreset(data, preset);
+   * ```
+   */
+  switchThemePreset(data: PptxData, preset: PptxThemePreset): Promise<PptxData>;
+  /**
+   * Parse a PPTX file from an `ArrayBuffer` and return structured data.
+   *
+   * If the file is encrypted and a `password` is provided in `options`,
+   * the file will be decrypted before parsing. If no password is provided
+   * for an encrypted file, throws {@link EncryptedFileError}.
+   *
+   * @param data    - Raw bytes of the `.pptx` file (may be encrypted OLE2).
+   * @param options - Optional load-time settings, including `password`.
+   * @returns Parsed {@link PptxData} containing slides, theme, layouts, etc.
+   *
+   * @example
+   * ```ts
+   * // Load an unencrypted file:
+   * const pptx = await handler.load(buf.buffer);
+   *
+   * // Load a password-protected file:
+   * const pptx = await handler.load(buf.buffer, { password: "secret" });
+   * console.log(`${pptx.slides.length} slides loaded`);
+   * ```
+   */
+  load(data: ArrayBuffer, options?: PptxHandlerLoadOptions): Promise<PptxData>;
+  /**
+   * Extract chart data from a graphic-frame XML node.
+   *
+   * @param slidePath    - Internal archive path of the slide (e.g. `ppt/slides/slide1.xml`).
+   * @param graphicFrame - Parsed XML object for the `<p:graphicFrame>` node.
+   * @returns Chart data, or `undefined` if the frame is not a chart.
+   */
+  getChartDataForGraphicFrame(slidePath: string, graphicFrame: XmlObject | undefined): Promise<PptxChartData | undefined>;
+  /**
+   * Extract SmartArt data from a graphic-frame XML node.
+   *
+   * @param slidePath    - Internal archive path of the slide.
+   * @param graphicFrame - Parsed XML object for the `<p:graphicFrame>` node.
+   * @returns SmartArt data, or `undefined` if the frame is not SmartArt.
+   */
+  getSmartArtDataForGraphicFrame(slidePath: string, graphicFrame: XmlObject | undefined): Promise<PptxSmartArtData | undefined>;
+  /**
+   * Get the base64-encoded data URL for an embedded image.
+   *
+   * @param imagePath - Archive-relative path (e.g. `ppt/media/image1.png`).
+   * @returns A `data:image/...;base64,...` string, or `undefined` if not found.
+   */
+  getImageData(imagePath: string): Promise<string | undefined>;
+  /**
+   * Extract a media file from the PPTX archive as an ArrayBuffer.
+   * Avoids the 33% base64 overhead of getImageData — prefer this for
+   * audio/video media that will be played via Blob URLs.
+   */
+  getMediaArrayBuffer(mediaPath: string): Promise<ArrayBuffer | undefined>;
+  /**
+   * Serialise current slides back into a PPTX byte array.
+   *
+   * @param slides  - The (possibly mutated) slide array.
+   * @param options - Optional save-time settings (e.g. thumbnail generation).
+   * @returns `Uint8Array` of the complete `.pptx` file.
+   *
+   * @example
+   * ```ts
+   * const bytes = await handler.save(data.slides);
+   * await fs.writeFile("output.pptx", Buffer.from(bytes));
+   * // => Uint8Array written to disk as a valid .pptx file
+   * ```
+   */
+  save(slides: PptxSlide[], options?: PptxHandlerSaveOptions): Promise<Uint8Array>;
+  /**
+   * Serialise slides and then encrypt the output with a password.
+   *
+   * This is a convenience method that calls {@link save} followed by
+   * {@link encryptPptx}. The result is an OLE2 container suitable for
+   * opening in Microsoft PowerPoint with a password prompt.
+   *
+   * @param slides   - The (possibly mutated) slide array.
+   * @param password - The password to encrypt with.
+   * @param options  - Optional save-time and encryption settings.
+   * @returns `Uint8Array` of the encrypted OLE2 file.
+   *
+   * @example
+   * ```ts
+   * const bytes = await handler.saveEncrypted(data.slides, "secret");
+   * await fs.writeFile("protected.pptx", Buffer.from(bytes));
+   * // => Encrypted OLE2 file requiring password to open
+   * ```
+   */
+  saveEncrypted(slides: PptxSlide[], password: string, options?: PptxHandlerSaveOptions & {
+    encryption?: EncryptionOptions;
+  }): Promise<Uint8Array>;
+  /**
+   * Get the slide layouts available for a specific slide.
+   *
+   * Returns layouts belonging to the same slide master as the given slide.
+   * This is useful for building a layout picker UI scoped to the current
+   * slide's master.
+   *
+   * @param slideIndex - Zero-based slide index.
+   * @param slides     - Current slides array.
+   * @returns Array of {@link PptxLayoutOption} entries for the slide's master.
+   *
+   * @example
+   * ```ts
+   * const layouts = await handler.getAvailableLayoutsForSlide(0, data.slides);
+   * console.log(layouts.map(l => l.name));
+   * // => ["Title Slide", "Title and Content", "Blank", ...]
+   * ```
+   */
+  getAvailableLayoutsForSlide(slideIndex: number, slides: PptxSlide[]): Promise<PptxLayoutOption[]>;
+  /**
+   * Resolve the editable template (master + layout) elements a slide
+   * inherits, each carrying a `master-` / `layout-` prefixed id.
+   *
+   * This is the foundation for an "edit template/master" feature. The
+   * returned elements are the decorative master/layout shapes the loader
+   * already merges behind slide-authored content (master shapes behind,
+   * layout shapes on top); placeholders are excluded. The same elements are
+   * shared by every slide inheriting the layout/master, so editing one and
+   * saving updates the shared part.
+   *
+   * To persist an edit, keep the mutated template element inside the
+   * `slide.elements` array passed to {@link save}; the save writer reads
+   * template elements from there and writes their shape XML back into the
+   * owning layout/master `p:spTree`.
+   *
+   * @param slideId - The slide's archive path (the `PptxSlide.id`).
+   * @returns Master + layout elements with prefixed ids (may be empty).
+   *
+   * @example
+   * ```ts
+   * const templateEls = await handler.getTemplateElementsForSlide(slide.id);
+   * const logo = templateEls.find((e) => e.id.startsWith("master-"));
+   * if (logo) {
+   *   logo.x += 10;
+   *   slide.elements = [...slide.elements, logo];
+   *   await handler.save(data.slides);
+   * }
+   * ```
+   */
+  getTemplateElementsForSlide(slideId: string): Promise<PptxElement[]>;
+  /**
+   * Apply a different layout to an existing slide.
+   *
+   * Updates the slide's relationship to point to the new layout and
+   * refreshes layout-derived properties (background, layout name).
+   * The slide's own content elements are preserved.
+   *
+   * @param slideIndex - Zero-based slide index.
+   * @param layoutPath - Archive path of the target layout
+   *                     (e.g. `ppt/slideLayouts/slideLayout2.xml`).
+   * @param slides     - Current slides array (the slide at `slideIndex`
+   *                     is replaced in-place).
+   * @returns The updated {@link PptxSlide} with new layout metadata.
+   *
+   * @example
+   * ```ts
+   * const updated = await handler.applyLayoutToSlide(
+   *   0,
+   *   "ppt/slideLayouts/slideLayout3.xml",
+   *   data.slides,
+   * );
+   * console.log(updated.layoutName);
+   * // => "Two Content"
+   * ```
+   */
+  applyLayoutToSlide(slideIndex: number, layoutPath: string, slides: PptxSlide[]): Promise<PptxSlide>;
+  /**
+   * Scan the loaded PPTX archive for all theme parts (`ppt/theme/theme*.xml`)
+   * and return their paths and display names.
+   */
+  getAvailableThemes(): Promise<Array<{
+    path: string;
+    name?: string;
+  }>>;
+  /**
+   * Export selected slides as individual PPTX files.
+   *
+   * Each entry in the returned map is keyed by slide index and contains a
+   * standalone `Uint8Array` PPTX with only that slide.
+   *
+   * @param slides  - Full slide array.
+   * @param options - Export options (slide indexes, format, etc.).
+   * @returns A `Map<slideIndex, Uint8Array>` of exported files.
+   *
+   * @example
+   * ```ts
+   * const exports = await handler.exportSlides(data.slides, {
+   *   slideIndexes: [0, 2],
+   * });
+   * for (const [idx, bytes] of exports) {
+   *   await fs.writeFile(`slide_${idx}.pptx`, Buffer.from(bytes));
+   * }
+   * // => Map<number, Uint8Array> — one standalone .pptx per exported slide
+   * ```
+   */
+  exportSlides(slides: PptxSlide[], options: PptxExportOptions): Promise<Map<number, Uint8Array>>;
+}
+//#endregion
+//#region src/core/PptxHandler.d.ts
+/**
+ * Public facade for the PPTX editor handler.
+ *
+ * The implementation lives in `PptxHandlerCore` so this surface can stay small,
+ * stable, and easy to replace with alternate implementations in the future.
+ */
+declare class PptxHandler extends PptxHandlerCore {
+  /**
+   * Create a new blank PPTX presentation from scratch.
+   *
+   * This is a convenience static method that delegates to
+   * {@link PresentationBuilder.create}. The returned handler is fully
+   * initialized and ready for editing, adding slides, and saving.
+   *
+   * @param options - Optional slide dimensions, theme, and metadata.
+   * @returns Handler, parsed data, and a slide builder factory.
+   *
+   * @example
+   * ```ts
+   * const { handler, data, createSlide } = await PptxHandler.createBlank({
+   *   title: "My Deck",
+   *   theme: { colors: { accent1: "#FF6B6B" } },
+   * });
+   *
+   * data.slides.push(
+   *   createSlide("Blank")
+   *     .addText("Hello", { fontSize: 36 })
+   *     .build()
+   * );
+   *
+   * const bytes = await handler.save(data.slides);
+   * ```
+   */
+  static createBlank(options?: PresentationOptions): Promise<PresentationBuilderResult>;
+  /**
+   * Create a new PPTX presentation from scratch.
+   *
+   * Alias for {@link createBlank}. Generates a valid minimal OpenXML
+   * package and returns a fully initialized handler ready for editing,
+   * adding slides, and saving.
+   *
+   * @param options - Optional slide dimensions, theme, metadata,
+   *   and initial slide count.
+   * @returns Handler, parsed data, and a slide builder factory.
+   *
+   * @example
+   * ```ts
+   * const { handler, data, createSlide } = await PptxHandler.create({
+   *   title: "Q4 Report",
+   *   initialSlideCount: 3,
+   *   theme: { colors: { accent1: "#FF6B6B" } },
+   * });
+   *
+   * // The presentation already has 3 blank slides
+   * console.log(data.slides.length); // => 3
+   *
+   * // Add more slides with content
+   * data.slides.push(
+   *   createSlide("Blank")
+   *     .addText("Hello", { fontSize: 36 })
+   *     .build()
+   * );
+   *
+   * const bytes = await handler.save(data.slides);
+   * ```
+   */
+  static create(options?: PresentationOptions): Promise<PresentationBuilderResult>;
+}
+//#endregion
+//#region src/converter/SvgExporter.d.ts
+/**
+ * Options controlling SVG export behaviour.
+ */
+interface SvgExportOptions {
+  /** Include hidden slides when exporting all. Default `false`. */
+  includeHidden?: boolean;
+  /** Slide indices to export (0-based). If omitted, all slides are exported. */
+  slideIndices?: number[];
+  /** Default font family when the element does not specify one. */
+  defaultFontFamily?: string;
+  /** Default font size in points when the element does not specify one. */
+  defaultFontSize?: number;
+}
+
+//#region src/theme/types.d.ts
+/**
+ * Theme configuration types for the PowerPoint viewer.
+ *
+ * All color values accept any valid CSS color string:
+ * hex (`#6366f1`), rgb (`rgb(99 102 241)`), hsl (`hsl(239 84% 67%)`),
+ * oklch (`oklch(0.585 0.233 277)`), named colors, etc.
+ *
+ * Framework-agnostic — shared by the React, Vue, and Angular bindings.
+ */
+/**
+ * Semantic color tokens for the viewer UI.
+ *
+ * These map to CSS custom properties (`--pptx-<token>`) and drive all
+ * UI component colors. The naming follows the shadcn/ui convention so
+ * that Tailwind + shadcn users get a familiar experience.
+ */
+interface ViewerThemeColors {
+  /** Page / root background */
+  background: string;
+  /** Default text color */
+  foreground: string;
+  /** Card / panel surface */
+  card: string;
+  /** Text on card surfaces */
+  cardForeground: string;
+  /** Popover / dropdown surface */
+  popover: string;
+  /** Text inside popovers */
+  popoverForeground: string;
+  /** Primary action color (buttons, active indicators) */
+  primary: string;
+  /** Text on primary-colored backgrounds */
+  primaryForeground: string;
+  /** Secondary / subdued action color */
+  secondary: string;
+  /** Text on secondary backgrounds */
+  secondaryForeground: string;
+  /** Muted / disabled surface */
+  muted: string;
+  /** Text on muted surfaces (also used for secondary text) */
+  mutedForeground: string;
+  /** Accent / hover-highlight surface */
+  accent: string;
+  /** Text on accent surfaces */
+  accentForeground: string;
+  /** Destructive / danger action color */
+  destructive: string;
+  /** Text on destructive backgrounds */
+  destructiveForeground: string;
+  /** Default border color */
+  border: string;
+  /** Input field border color */
+  input: string;
+  /** Focus ring color */
+  ring: string;
+}
+/**
+ * Full viewer theme configuration.
+ *
+ * Every property is optional — unset values fall back to the built-in
+ * dark theme defaults.
+ */
+interface ViewerTheme {
+  /** Semantic UI colors. Each key maps to a `--pptx-<key>` CSS custom property. */
+  colors?: Partial<ViewerThemeColors>;
+  /** Base border-radius value (e.g. `"0.5rem"`, `"8px"`). */
+  radius?: string;
+  /**
+   * Escape hatch: arbitrary CSS custom properties to set on the viewer
+   * root element. Keys should include the `--` prefix.
+   *
    * @example
    * ```ts
    * { "--my-custom-shadow": "0 4px 12px rgba(0,0,0,0.5)" }
@@ -6721,6 +8585,227 @@ interface PrintSettings {
   customRangeTo: number;
 }
 
+//#endregion
+//#region src/ai/change-animator.d.ts
+/** Host-tunable options for how AI edits are animated on the canvas. */
+interface AiChangeAnimationConfig {
+  /** Master switch. Default true. */
+  enabled?: boolean;
+  /** How long the motion + glow plays, in ms. Default 900. */
+  durationMs?: number;
+  /** Draw the pulsing glow highlight on changed elements. Default true. */
+  glow?: boolean;
+  /** Glide old->new bounds and cross-fade colours. Default true. */
+  tween?: boolean;
+  /** Accent colour (any CSS colour) for the glow/ghosts. Default a blue. */
+  color?: string;
+}
+//#endregion
+//#region src/ai/config.d.ts
+/** The UI message shape exchanged with the assistant. Alias of the SDK type. */
+type PptxAiUIMessage = UIMessage;
+/**
+ * Canonical name of every tool the assistant can call. Document tools mirror the
+ * `pptx-viewer-mcp` server exactly (they ARE the same functions, run against the
+ * live deck); the viewer-only tools (navigation, deck outline, element/notes
+ * readers, table merge) have no MCP counterpart.
+ */
+type PptxAiToolName = 'get_deck_overview' | 'get_slide' | 'get_element' | 'get_speaker_notes' | 'find_text' | 'get_theme' | 'go_to_slide' | 'select_elements' | 'merge_tables' | 'get_metadata' | 'get_layouts' | 'find_placeholders' | 'get_presentation_properties' | 'run_accessibility_check' | 'convert_to_markdown' | 'add_element' | 'update_element' | 'delete_elements' | 'arrange_elements' | 'clone_element' | 'set_element_animation' | 'group_elements' | 'ungroup_elements' | 'batch_update_elements' | 'update_element_style' | 'replace_geometry' | 'set_element_lock' | 'manage_hyperlinks' | 'replace_text' | 'manage_comments' | 'update_table_cells' | 'manage_table_structure' | 'create_chart' | 'update_chart' | 'add_chart_series' | 'remove_chart_series' | 'update_chart_series_data' | 'manage_smart_art' | 'apply_template' | 'add_slide' | 'duplicate_slide' | 'delete_slides' | 'reorder_slides' | 'update_slide_properties' | 'set_slide_transition' | 'apply_theme_preset' | 'update_theme_colors' | 'update_theme_fonts' | 'set_canvas_size' | 'update_metadata' | 'manage_sections' | 'update_presentation_properties' | 'apply_layout';
+type Resolvable<T> = T | (() => T | Promise<T>);
+/** How the assistant reaches a language model. */
+type PptxAiConnection =
+/**
+ * Post messages to a host backend route (recommended for production so the
+ * provider API key stays server-side). Maps to `DefaultChatTransport`.
+ */
+{
+  kind: 'endpoint';
+  api: string;
+  headers?: Resolvable<Record<string, string>>;
+  body?: Resolvable<Record<string, unknown>>;
+  credentials?: RequestCredentials;
+  fetch?: typeof globalThis.fetch;
+} |
+/**
+ * Run a language model in-process in the browser (bring-your-own key /
+ * local model). Maps to a `ToolLoopAgent` behind a `DirectChatTransport`.
+ */
+{
+  kind: 'model';
+  model: LanguageModel;
+  system?: string;
+  maxSteps?: number;
+} |
+/** Provide a fully-constructed transport (advanced / testing escape hatch). */
+{
+  kind: 'transport';
+  transport: ChatTransport<PptxAiUIMessage>;
+};
+/** How writes proposed by the assistant reach the document. */
+type PptxAiWritePolicy = 'stage' | 'approve' | 'auto';
+/** Which deck context is fed to the model with each turn. */
+type PptxAiContextStrategy = 'outline' | 'current-slide' | 'none';
+/** Optional per-session history persistence hooks. */
+interface PptxAiHistoryHooks {
+  load?(id: string): Promise<PptxAiUIMessage[]>;
+  save?(id: string, messages: PptxAiUIMessage[]): Promise<void>;
+}
+/** Complete host configuration for an AI chat session. */
+interface PptxAiConfig {
+  connection: PptxAiConnection;
+  /** Extra host instructions appended to the base system prompt. */
+  systemPromptExtras?: string;
+  tools?: {
+    /** Allowlist. When set, only these tools are exposed. */
+    enabled?: PptxAiToolName[];
+    /** Denylist, applied after `enabled`. */
+    disabled?: PptxAiToolName[];
+    /** Additional host-defined tools merged into the tool set. */
+    extra?: ToolSet;
+  };
+  /** Default `'stage'`. */
+  writePolicy?: PptxAiWritePolicy;
+  /** Default `'outline'`. */
+  contextStrategy?: PptxAiContextStrategy;
+  history?: PptxAiHistoryHooks;
+  /**
+   * How AI edits are animated on the canvas so the user can watch them land
+   * (glide old->new, fade/scale in-out, glow-pulse). Omit for the defaults;
+   * set `{ enabled: false }` to turn it off.
+   */
+  changeAnimation?: AiChangeAnimationConfig;
+  onError?(error: Error): void;
+}
+//#endregion
+//#region src/ai/bridge.d.ts
+/** Lightweight, model-friendly summary of the whole deck. */
+interface PptxAiDeckMeta {
+  /** Total number of slides. */
+  slideCount: number;
+  /** Zero-based index of the currently active slide. */
+  activeSlideIndex: number;
+  /** Deck title, when known (first slide title / core properties). */
+  title?: string;
+  /** Slide canvas width in CSS pixels. */
+  width: number;
+  /** Slide canvas height in CSS pixels. */
+  height: number;
+}
+/** Severity hint for {@link PptxAiBridge.notify}. */
+type PptxAiNotifyLevel = 'info' | 'success' | 'warning' | 'error';
+/**
+ * A target the user has scoped the assistant to: either a whole slide or a
+ * single element on a slide. Returned by {@link PptxAiBridge.getFocusedTargets}
+ * so the context builder can tell the model exactly what to focus on.
+ */
+type PptxAiFocusedTarget = {
+  kind: 'slide';
+  slideIndex: number;
+} | {
+  kind: 'element';
+  slideIndex: number;
+  elementId: string;
+};
+/**
+ * A pure updater over the deck's slides. It receives a deep clone of the
+ * current slides (mutation-safe) and returns the next slides array. The bridge
+ * commits the returned array as ONE history entry.
+ */
+type PptxAiSlidesUpdater = (slides: PptxSlide[]) => PptxSlide[];
+/**
+ * A pure updater over the whole parsed deck ({@link PptxData}). Mirrors the
+ * `pptx-viewer-mcp` tool model (data in, mutated data out) so presentation-level
+ * MCP tools (metadata, sections, canvas size, presentation properties, layouts)
+ * can be committed as ONE undoable history entry through {@link
+ * PptxAiBridge.applyDeckData}. Optional: bindings that only track slide/theme
+ * state can omit it, in which case those presentation-level tools report that
+ * they are unavailable in this viewer while every slide/theme tool still works.
+ */
+type PptxAiDataUpdater = (data: PptxData) => PptxData;
+/** Field-level updates for a single element, mirroring the MCP update vocab. */
+interface PptxAiElementUpdate {
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  rotation?: number;
+  opacity?: number;
+  hidden?: boolean;
+  flipHorizontal?: boolean;
+  flipVertical?: boolean;
+  text?: string;
+  fontSize?: number;
+  fontFamily?: string;
+  fontColor?: string;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  align?: 'left' | 'center' | 'right' | 'justify';
+  fillColor?: string;
+  strokeColor?: string;
+  strokeWidth?: number;
+}
+/**
+ * Implemented by each binding to expose its live editor to the AI core.
+ *
+ * Read methods must be cheap and synchronous. Write methods must route through
+ * the binding's editor-history layer so AI edits are undoable like manual ones.
+ */
+interface PptxAiBridge {
+  /** Return a summary of the whole deck. */
+  getDeckMeta(): PptxAiDeckMeta;
+  /** Return the deck's slides. Callers must not mutate the returned array. */
+  getSlides(): PptxSlide[];
+  /** Return the zero-based index of the active slide. */
+  getActiveSlideIndex(): number;
+  /** Return the resolved presentation theme, when available. */
+  getTheme(): PptxTheme | undefined;
+  /** Return the underlying core handler, when the binding exposes one. */
+  getHandler(): PptxHandler | undefined;
+  /** Navigate the viewer to a slide by zero-based index. */
+  goToSlide(index: number): void;
+  /** Select the given elements on a slide (empty array clears selection). */
+  selectElements(slideIndex: number, elementIds: string[]): void;
+  /**
+   * Apply a slides updater as a single, atomic, undoable history entry. The
+   * binding is responsible for cloning current slides before calling
+   * `updater` and for installing the result.
+   */
+  applySlidesUpdate(updater: PptxAiSlidesUpdater, label: string): void;
+  /** Apply field updates to one element as a single history entry. */
+  updateElement(slideIndex: number, elementId: string, updates: PptxAiElementUpdate): void;
+  /** Apply partial theme updates as a single history entry. */
+  applyTheme(updates: Partial<PptxTheme>): void;
+  /**
+   * Return the full parsed {@link PptxData} for the open deck, with the live
+   * (edited) slides and theme overlaid. Enables `pptx-viewer-mcp` tools that
+   * read presentation-level state (metadata, sections, layouts, presentation
+   * properties). Optional: when absent, the AI core synthesises a minimal
+   * PptxData from slides + dimensions, which is enough for every slide/theme
+   * tool but not for presentation-level reads.
+   */
+  getDeckData?(): PptxData | undefined;
+  /**
+   * Commit a whole-deck {@link PptxData} mutation as one undoable history entry.
+   * Used to apply presentation-level MCP tool results (metadata, sections,
+   * canvas size, presentation properties, layouts). Optional: when absent,
+   * those tools report they are not supported in this viewer; slide/theme tools
+   * are unaffected (they route through {@link PptxAiBridge.applySlidesUpdate}
+   * and {@link PptxAiBridge.applyTheme}).
+   */
+  applyDeckData?(updater: PptxAiDataUpdater, label: string): void;
+  /**
+   * Return the slides / elements the user has scoped the assistant to, if any.
+   * When present and non-empty, the context builder tells the model to focus on
+   * exactly these targets. Optional so existing bridges satisfy the contract
+   * without change; a bridge that does not implement it behaves as before (no
+   * focus scoping).
+   */
+  getFocusedTargets?(): PptxAiFocusedTarget[];
+  /** Surface a transient message in the host UI (toast / status line). */
+  notify?(message: string, level?: PptxAiNotifyLevel): void;
+}
+
 //#endregion
 //#region src/i18n/locale-catalog.d.ts
 /** One selectable entry in the viewer chrome's built-in language picker (File > Options > Language). */
@@ -6943,11 +9028,11 @@ interface PowerPointViewerProps {
      */
     showNotes?: boolean;
     /**
-     * Opt in to the experimental Three.js (WebGL) SmartArt renderer for
-     * `smartArt` elements, in place of the default SVG renderer. Requires the
-     * optional `three` peer dependency; when it is unavailable, or a diagram
-     * has no renderable nodes, or the WebGL mount fails, the SVG renderer is
-     * used automatically. Default false.
+     * Opt in to the Three.js (WebGL) SmartArt renderer for `smartArt` elements,
+     * in place of the default SVG renderer. Requires the optional `three` peer
+     * dependency; when it is unavailable, or a diagram has no renderable nodes,
+     * or the WebGL mount fails, the SVG renderer is used automatically. Default
+     * false.
      */
     smartArt3D?: boolean;
     /**
@@ -7036,6 +9121,15 @@ interface PowerPointViewerProps {
         userName?: string;
         serverUrl?: string;
     };
+    /**
+     * Optional AI assistant configuration. When provided, a Sparkles toggle
+     * appears in the ribbon's command row and opens a right-side chat panel that
+     * can read the open deck and propose edits through the viewer's undo history.
+     * The panel (and the optional `@ai-sdk/svelte` + `ai` peers it needs) is
+     * lazily loaded only when first opened; leaving this undefined ships no AI UI
+     * and never pulls the SDK. See `pptx-viewer-shared/ai`'s `PptxAiConfig`.
+     */
+    ai?: PptxAiConfig;
 }
 /**
  * Imperative editing API exposed on the `<PowerPointViewer>` component
@@ -7140,4 +9234,4 @@ declare const PowerPointViewer: Component<PowerPointViewerProps, PowerPointViewe
 type AutosaveStatus = 'idle' | 'disabled' | 'saving' | 'saved' | 'error';
 
 export { PowerPointViewer, defaultCssVars, defaultRadius, defaultThemeColors, deleteAutosaveSnapshot, exportAllSlidesToSvg, exportAllSlidesToSvgBlobs, exportSlideAsSvg, exportSlideToSvg, exportSlideToSvgBlob, getAutosaveSnapshot, listAutosaveSnapshots, loadPresentationDeck, parsePresentationSessionId, registerTranslations, themeToCssVars, vermilionDarkColors, vermilionDarkTheme, vermilionLightColors, vermilionLightTheme, vermilionRadius };
-export type { AutosaveRecord, AutosaveStatus, CanvasSize, CollaborationConfig, CollaborationRole, CollaborationTransport, ExportGifOptions, ExportPdfOptions, ExportVideoOptions, PowerPointViewerApi, PowerPointViewerProps, PrintOptions, SvgExportAllOptions, SvgExportSingleSlideOptions, TranslationDictionary, Translator, ViewerLoadDetail, ViewerTheme, ViewerThemeColors };
+export type { AutosaveRecord, AutosaveStatus, CanvasSize, CollaborationConfig, CollaborationRole, CollaborationTransport, ExportGifOptions, ExportPdfOptions, ExportVideoOptions, PowerPointViewerApi, PowerPointViewerProps, PptxAiBridge, PptxAiConfig, PptxAiConnection, PptxAiContextStrategy, PptxAiToolName, PptxAiUIMessage, PptxAiWritePolicy, PrintOptions, SvgExportAllOptions, SvgExportSingleSlideOptions, TranslationDictionary, Translator, ViewerLoadDetail, ViewerTheme, ViewerThemeColors };