pptx-react-viewer 1.25.4 → 2.0.0

package/dist/index.d.ts

@@ -1,7 +1,27 @@
 import * as React$1 from 'react';
 import React$1__default from 'react';
+import { LanguageModel, ChatTransport, UIMessage, ToolSet } from 'ai';
 import { Options } from 'html2canvas-pro';
 
+//#endregion
+//#region src/i18n/locale-catalog.d.ts
+/** One selectable entry in the viewer chrome's built-in language picker (File > Options > Language). */
+interface LocaleCatalogEntry {
+  /** BCP-47-ish locale code, e.g. `'en'`, `'fr'`. Matches `pptx-viewer-locales`' exports. */
+  code: string;
+  /** English display name, used before a translation dictionary for the target locale is loaded. */
+  label: string;
+  /** The locale's own name for itself, e.g. `'Français'` for `fr`. */
+  nativeLabel: string;
+}
+/**
+ * Built-in language choices offered by File > Options > Language when a host
+ * doesn't supply its own `availableLocales`. Mirrors the locales shipped by
+ * the optional `pptx-viewer-locales` package (English needs no dictionary,
+ * it's the viewer's own baseline).
+ */
+declare const LOCALE_CATALOG: readonly LocaleCatalogEntry[];
+
 //#region src/core/types/actions.d.ts
 /**
  * Action types: hyperlinks, slide jumps, macros, and action buttons.
@@ -206,6 +226,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.
@@ -795,6 +822,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';
@@ -812,6 +848,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;
@@ -993,6 +1043,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). */
@@ -1120,6 +1178,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. */
@@ -1231,10 +1296,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`). */
@@ -1578,6 +1669,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.
@@ -1723,6 +1823,47 @@ interface PptxShapeProperties {
   /** Adjustment handles for interactive shape modification (yellow diamond handles). */
   adjustmentHandles?: GeometryAdjustmentHandle[];
 }
+/**
+ * Text styling for a single indent level (0–8) inside a placeholder’s
+ * `a:lstStyle`.
+ *
+ * Used during placeholder inheritance to fill in defaults for font,
+ * bullet, and spacing properties the slide element does not override.
+ *
+ * @example
+ * ```ts
+ * const level0: PlaceholderTextLevelStyle = {
+ *   fontSize: 32,
+ *   bold: true,
+ *   bulletChar: "•",
+ * };
+ * // => satisfies PlaceholderTextLevelStyle
+ * ```
+ */
+interface PlaceholderTextLevelStyle {
+  fontFamily?: string;
+  fontSize?: number;
+  bold?: boolean;
+  italic?: boolean;
+  color?: string;
+  bulletChar?: string;
+  bulletAutoNumType?: string;
+  bulletFontFamily?: string;
+  bulletSizePercent?: number;
+  /** Bullet colour from `a:buClr` as hex string. */
+  bulletColor?: string;
+  /** Bullet size in points from `a:buSzPts`. */
+  bulletSizePts?: number;
+  /** True when `a:buNone` is present at this level. */
+  bulletNone?: boolean;
+  marginLeft?: number;
+  indent?: number;
+  alignment?: string;
+  lineSpacing?: number;
+  lineSpacingExactPt?: number;
+  spaceBefore?: number;
+  spaceAfter?: number;
+}
 //#endregion
 //#region src/core/types/chart-axis.d.ts
 /** Tick-mark placement from ChartML `ST_TickMark`. */
@@ -1842,6 +1983,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.
@@ -2175,6 +2385,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[];
@@ -2182,6 +2401,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;
   /**
@@ -2384,6 +2615,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`.
@@ -2448,6 +2687,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. */
@@ -2548,6 +2814,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.
    *
@@ -3255,6 +3530,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[];
 }
@@ -3443,6 +3730,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}.
  *
@@ -3484,6 +3805,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. */
@@ -3516,7 +3843,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
@@ -3644,6 +3971,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.
@@ -3756,12 +4129,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.
@@ -3788,12 +4199,20 @@ 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`.
@@ -3821,7 +4240,7 @@ interface ParsedTableStyleBorder {
   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. */
+  /** The line was `a:noFill` - an explicit "no border" that clears lower layers. */
   noFill?: boolean;
 }
 /**
@@ -4392,6 +4811,136 @@ interface UnknownPptxElement extends PptxElementBase {
  * (shape), or `textSegments` (text/shape).
  */
 type PptxElement = TextPptxElement | ShapePptxElement | ConnectorPptxElement | ImagePptxElement | PicturePptxElement | TablePptxElement | ChartPptxElement | SmartArtPptxElement | OlePptxElement | MediaPptxElement | GroupPptxElement | InkPptxElement | ContentPartPptxElement | ZoomPptxElement | Model3DPptxElement | UnknownPptxElement;
+//#endregion
+//#region src/core/types/masters.d.ts
+/**
+ * Parsed notes master from `ppt/notesMasters/notesMaster1.xml`.
+ *
+ * @example
+ * ```ts
+ * const notes: PptxNotesMaster = {
+ *   path: "ppt/notesMasters/notesMaster1.xml",
+ *   backgroundColor: "#FFFFFF",
+ *   placeholders: [{ type: "body" }, { type: "sldImg" }],
+ * };
+ * // => satisfies PptxNotesMaster
+ * ```
+ */
+interface PptxNotesMaster {
+  /** File path within the PPTX archive. */
+  path: string;
+  /** Background colour of the notes master. */
+  backgroundColor?: string;
+  /** Background image data URL. */
+  backgroundImage?: string;
+  /** Placeholder shapes found on the notes master. */
+  placeholders?: Array<{
+    type: string;
+    idx?: string;
+  }>;
+  /** Editable elements on the notes master (header, footer, date, page number, slide image, notes body). */
+  elements?: PptxElement[];
+  /** Header/footer flags from `<p:hf>` on the notes master (P-H3). */
+  headerFooter?: PptxHeaderFooterFlags;
+  /** Colour map from `<p:clrMap>` (12 alias attributes). Applied at save time. */
+  clrMap?: Record<string, string>;
+}
+/**
+ * Parsed handout master from `ppt/handoutMasters/handoutMaster1.xml`.
+ *
+ * @example
+ * ```ts
+ * const handout: PptxHandoutMaster = {
+ *   path: "ppt/handoutMasters/handoutMaster1.xml",
+ *   slidesPerPage: 6,
+ * };
+ * // => satisfies PptxHandoutMaster
+ * ```
+ */
+interface PptxHandoutMaster {
+  /** File path within the PPTX archive. */
+  path: string;
+  /** Background colour of the handout master. */
+  backgroundColor?: string;
+  /** Background image data URL. */
+  backgroundImage?: string;
+  /** Placeholder shapes found on the handout master. */
+  placeholders?: Array<{
+    type: string;
+    idx?: string;
+  }>;
+  /** Editable elements on the handout master (header, footer, date, page number, slide placeholders). */
+  elements?: PptxElement[];
+  /** Number of slides per page for handout print layout (1, 2, 3, 4, 6, or 9). */
+  slidesPerPage?: number;
+  /** Header/footer flags from `<p:hf>` on the handout master (P-H3). */
+  headerFooter?: PptxHeaderFooterFlags;
+  /** Colour map from `<p:clrMap>` (12 alias attributes). Applied at save time. */
+  clrMap?: Record<string, string>;
+}
+/**
+ * Structured slide master data.
+ *
+ * @example
+ * ```ts
+ * const master: PptxSlideMaster = {
+ *   path: "ppt/slideMasters/slideMaster1.xml",
+ *   name: "Office Theme",
+ *   backgroundColor: "#FFFFFF",
+ *   themePath: "ppt/theme/theme1.xml",
+ * };
+ * // => satisfies PptxSlideMaster
+ * ```
+ */
+interface PptxSlideMaster {
+  /** File path within the PPTX archive. */
+  path: string;
+  /** Human-readable name if available. */
+  name?: string;
+  /** Background colour of the slide master. */
+  backgroundColor?: string;
+  /** Background image data URL for the slide master. */
+  backgroundImage?: string;
+  /** Theme file path this master references. */
+  themePath?: string;
+  /** Layout paths associated with this master. */
+  layoutPaths?: string[];
+  /** Placeholder shapes on the master. */
+  placeholders?: Array<{
+    type: string;
+    idx?: string;
+  }>;
+  /** Parsed element shapes on the master slide (for master view rendering). */
+  elements?: PptxElement[];
+  /** Parsed slide layout objects associated with this master. */
+  layouts?: PptxSlideLayout[];
+  /** Text styles from `p:txStyles` — title, body, and other text defaults. */
+  txStyles?: PptxMasterTextStyles;
+  /** Header/footer flags from `<p:hf>` on this master (P-H3). */
+  headerFooter?: PptxHeaderFooterFlags;
+  /**
+   * Colour map from `<p:clrMap>` (12 alias attributes: bg1/tx1/bg2/tx2,
+   * accent1-6, hlink, folHlink). Applied at save time when present.
+   */
+  clrMap?: Record<string, string>;
+}
+/**
+ * Per-level paragraph properties for a text style category.
+ * Each entry maps a 0-based level index to its style defaults.
+ */
+type PptxTextStyleLevels = Record<number, PlaceholderTextLevelStyle>;
+/**
+ * Text styles parsed from `p:txStyles` on a slide master.
+ * Provides cascading defaults for title, body, and other text.
+ */
+interface PptxMasterTextStyles {
+  /** Title text style (`p:titleStyle`). */
+  titleStyle?: PptxTextStyleLevels;
+  /** Body text style (`p:bodyStyle`). */
+  bodyStyle?: PptxTextStyleLevels;
+  /** Other text style (`p:otherStyle`). */
+  otherStyle?: PptxTextStyleLevels;
+}
 /**
  * Per-part header/footer flags from `<p:hf>` (CT_HeaderFooter, ECMA-376
  * §19.3.1.21). Defaults are "all true" — fields are only set on the typed
@@ -4408,6 +4957,65 @@ interface PptxHeaderFooterFlags {
   /** `@sldNum` — show slide-number placeholder. Spec default: `true`. */
   hasSlideNumber?: boolean;
 }
+/**
+ * A slide layout associated with a slide master.
+ *
+ * @example
+ * ```ts
+ * const layout: PptxSlideLayout = {
+ *   path: "ppt/slideLayouts/slideLayout2.xml",
+ *   name: "Title and Content",
+ * };
+ * // => satisfies PptxSlideLayout
+ * ```
+ */
+interface PptxSlideLayout {
+  /** File path within the PPTX archive. */
+  path: string;
+  /** Human-readable layout name. */
+  name?: string;
+  /** Background colour of the layout. */
+  backgroundColor?: string;
+  /** Background image data URL for the layout. */
+  backgroundImage?: string;
+  /** Parsed element shapes on the layout. */
+  elements?: PptxElement[];
+  /** Placeholder shapes on the layout. */
+  placeholders?: Array<{
+    type: string;
+    idx?: string;
+  }>;
+  /** Matching name attribute for layout identification (`@matchingName`). */
+  matchingName?: string;
+  /** Whether the layout is marked as preserved (prevent deletion, `@preserve`). */
+  preserve?: boolean;
+  /** Whether master placeholder animations should play (`@showMasterPhAnim`). */
+  showMasterPhAnim?: boolean;
+  /** Whether this layout is user-drawn (`@userDrawn`). */
+  userDrawn?: boolean;
+  /** Colour map override from `p:clrMapOvr`. */
+  clrMapOverride?: Record<string, string>;
+  /** Header/footer flags from `<p:hf>` on this layout (P-H3). */
+  headerFooter?: PptxHeaderFooterFlags;
+}
+/**
+ * A theme part available in the presentation package.
+ *
+ * @example
+ * ```ts
+ * const opt: PptxThemeOption = {
+ *   path: "ppt/theme/theme1.xml",
+ *   name: "Office Theme",
+ * };
+ * // => satisfies PptxThemeOption
+ * ```
+ */
+interface PptxThemeOption {
+  /** File path within the PPTX archive (e.g. `ppt/theme/theme2.xml`). */
+  path: string;
+  /** Human-readable theme name from `a:theme/@name`, when present. */
+  name?: string;
+}
 //#endregion
 //#region src/core/types/animation.d.ts
 /**
@@ -4513,6 +5121,19 @@ interface PptxNativeAnimation {
   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`). */
@@ -4605,6 +5226,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;
   /**
@@ -4803,6 +5432,34 @@ interface PptxElementAnimation {
   stopSound?: boolean;
 }
 //#endregion
+//#region src/core/types/embedded-font.d.ts
+interface PptxEmbeddedFontDataId {
+  /** Required relationship identifier from `r:id`. */
+  relationshipId?: string | null;
+  /** Original leaf retained for unknown attribute preservation. */
+  rawXml?: XmlObject;
+}
+interface PptxEmbeddedFontDescriptor {
+  typeface?: string | null;
+  panose?: string | null;
+  pitchFamily?: string | null;
+  charset?: string | null;
+  rawXml?: XmlObject;
+}
+interface PptxEmbeddedFontListEntry {
+  font: PptxEmbeddedFontDescriptor;
+  regular?: PptxEmbeddedFontDataId | null;
+  bold?: PptxEmbeddedFontDataId | null;
+  italic?: PptxEmbeddedFontDataId | null;
+  boldItalic?: PptxEmbeddedFontDataId | null;
+  rawXml?: XmlObject;
+}
+interface PptxEmbeddedFontList {
+  fonts: PptxEmbeddedFontListEntry[];
+  /** Original list retained for unknown attribute and child preservation. */
+  rawXml?: XmlObject;
+}
+//#endregion
 //#region src/core/types/metadata.d.ts
 /**
  * A slide comment — may be a legacy positional comment or a modern
@@ -4856,6 +5513,49 @@ interface PptxComment {
   /** Original `p:cm` subtree, retained for unknown child and extension preservation. */
   rawXml?: XmlObject;
 }
+/** Office 2021 comment author from the p188 Author part. */
+interface PptxModernCommentAuthor {
+  id: string;
+  name: string;
+  initials?: string;
+  userId: string;
+  providerId: string;
+  rawXml?: XmlObject;
+}
+/**
+ * A comment author from `ppt/commentAuthors.xml`.
+ *
+ * Stores all attributes needed for lossless round-trip serialization
+ * of the `p:cmAuthor` element (id, name, initials, lastIdx, clrIdx).
+ *
+ * @see ECMA-376 Part 1, §19.4.2 (cmAuthor)
+ *
+ * @example
+ * ```ts
+ * const author: PptxCommentAuthor = {
+ *   id: "0",
+ *   name: "John Doe",
+ *   initials: "JD",
+ *   lastIdx: 3,
+ *   clrIdx: 0,
+ * };
+ * // => satisfies PptxCommentAuthor
+ * ```
+ */
+interface PptxCommentAuthor {
+  /** Unique numeric author identifier (`@_id`). */
+  id: string;
+  /** Author display name (`@_name`). */
+  name: string;
+  /** Author initials (`@_initials`). */
+  initials: string;
+  /** Last comment index used by this author (`@_lastIdx`). */
+  lastIdx: number;
+  /** Colour index assigned to this author (`@_clrIdx`). */
+  clrIdx: number;
+  /** Original `p:cmAuthor` subtree, retained for unknown attribute preservation. */
+  rawXml?: XmlObject;
+}
 /**
  * A compatibility warning generated during parse or save when the
  * file uses features not fully supported by the editor.
@@ -4883,24 +5583,192 @@ interface PptxCompatibilityWarning {
   xmlPath?: string;
 }
 /**
- * Resolved hex values for the 12 theme colour slots.
+ * A single name–value tag from `ppt/tags/*.xml`.
  *
  * @example
  * ```ts
- * const scheme: PptxThemeColorScheme = {
- *   dk1: "#000000", lt1: "#FFFFFF",
- *   dk2: "#1F497D", lt2: "#EEECE1",
- *   accent1: "#4F81BD", accent2: "#C0504D",
- *   accent3: "#9BBB59", accent4: "#8064A2",
- *   accent5: "#4BACC6", accent6: "#F79646",
- *   hlink: "#0000FF", folHlink: "#800080",
- * };
- * // => satisfies PptxThemeColorScheme
+ * const tag: PptxTag = { name: "CUSTOM_ID", value: "12345" };
+ * // => satisfies PptxTag
  * ```
  */
-interface PptxThemeColorScheme {
-  dk1: string;
-  lt1: string;
+interface PptxTag {
+  name: string;
+  value: string;
+}
+/**
+ * A collection of tags from a single tags XML part.
+ *
+ * @example
+ * ```ts
+ * const coll: PptxTagCollection = {
+ *   path: "ppt/tags/tag1.xml",
+ *   tags: [{ name: "CUSTOM_ID", value: "12345" }],
+ * };
+ * // => satisfies PptxTagCollection
+ * ```
+ */
+interface PptxTagCollection {
+  /** File path within the PPTX archive. */
+  path?: string;
+  /** Package owner of the tags relationship. New collections default to presentation. */
+  owner?: 'presentation' | 'slide' | 'part';
+  /** Source OPC part that owns the relationship, e.g. ppt/slides/slide1.xml. */
+  sourcePartPath?: string;
+  /** Durable relationship identifier from the owning part. */
+  relationshipId?: string;
+  /** Tags in this collection. */
+  tags: PptxTag[];
+  /** Parsed tag-list XML retained for unknown-node preservation. */
+  rawXml?: XmlObject;
+}
+/**
+ * A custom document property from `docProps/custom.xml`.
+ *
+ * @example
+ * ```ts
+ * const prop: PptxCustomProperty = {
+ *   name: "Project",
+ *   value: "pptx",
+ *   type: "lpwstr",
+ * };
+ * // => satisfies PptxCustomProperty
+ * ```
+ */
+interface PptxCustomProperty {
+  /** Property name. */
+  name: string;
+  /** Property value (always stringified). */
+  value: string;
+  /** Original VT type (e.g. "lpwstr", "i4", "bool", "filetime"). */
+  type: string;
+}
+/**
+ * Core document properties from `docProps/core.xml` (Dublin Core + OOXML).
+ *
+ * @example
+ * ```ts
+ * const core: PptxCoreProperties = {
+ *   title: "Q4 Business Review",
+ *   creator: "Alice",
+ *   created: "2024-01-15T08:00:00Z",
+ *   modified: "2024-06-01T12:30:00Z",
+ *   lastModifiedBy: "Bob",
+ * };
+ * // => satisfies PptxCoreProperties
+ * ```
+ */
+interface PptxCoreProperties {
+  /** dc:title */
+  title?: string;
+  /** dc:subject */
+  subject?: string;
+  /** dc:creator */
+  creator?: string;
+  /** cp:keywords */
+  keywords?: string;
+  /** dc:description */
+  description?: string;
+  /** cp:lastModifiedBy */
+  lastModifiedBy?: string;
+  /** cp:revision */
+  revision?: string;
+  /** dcterms:created (ISO 8601) */
+  created?: string;
+  /** dcterms:modified (ISO 8601) */
+  modified?: string;
+  /** cp:category */
+  category?: string;
+  /** cp:contentStatus */
+  contentStatus?: string;
+}
+/**
+ * Extended (application) properties from `docProps/app.xml`.
+ *
+ * @example
+ * ```ts
+ * const app: PptxAppProperties = {
+ *   application: "Microsoft Office PowerPoint",
+ *   appVersion: "16.0000",
+ *   slides: 24,
+ *   words: 1500,
+ *   company: "Acme Corp",
+ * };
+ * // => satisfies PptxAppProperties
+ * ```
+ */
+interface PptxAppProperties {
+  /** Application name (e.g. "Microsoft Office PowerPoint"). */
+  application?: string;
+  /** Application version string. */
+  appVersion?: string;
+  /** Presentation format (e.g. "On-screen Show (16:9)"). */
+  presentationFormat?: string;
+  /** Total number of slides. */
+  slides?: number;
+  /** Number of hidden slides. */
+  hiddenSlides?: number;
+  /** Number of notes slides. */
+  notes?: number;
+  /** Total editing time in minutes. */
+  totalTime?: number;
+  /** Number of words. */
+  words?: number;
+  /** Number of paragraphs. */
+  paragraphs?: number;
+  /** Company name. */
+  company?: string;
+  /** Manager name. */
+  manager?: string;
+  /** Template name. */
+  template?: string;
+  /** Hyperlink base URL. */
+  hyperlinkBase?: string;
+  /** Document security bitmask (`<DocSecurity>`). */
+  docSecurity?: number;
+  /** Number of multimedia clips (`<MMClips>`). */
+  mmClips?: number;
+  /** Whether thumbnail images were scaled to fit (`<ScaleCrop>`). */
+  scaleCrop?: boolean;
+  /** Whether hyperlinks are current (`<LinksUpToDate>`). */
+  linksUpToDate?: boolean;
+  /** Whether the document is shared (`<SharedDoc>`). */
+  sharedDoc?: boolean;
+  /** Whether hyperlinks changed since last save (`<HyperlinksChanged>`). */
+  hyperlinksChanged?: boolean;
+}
+//#endregion
+//#region src/core/types/presentation-print-properties.d.ts
+type PptxPrintOutput = 'slides' | 'handouts1' | 'handouts2' | 'handouts3' | 'handouts4' | 'handouts6' | 'handouts9' | 'notes' | 'outline';
+type PptxPrintColorMode = 'bw' | 'gray' | 'clr';
+/** PresentationML `CT_PrintProperties` (`p:prnPr`). */
+interface PptxPresentationPrintProperties {
+  printWhat?: PptxPrintOutput | null;
+  colorMode?: PptxPrintColorMode | null;
+  hiddenSlides?: boolean | null;
+  scaleToFitPaper?: boolean | null;
+  frameSlides?: boolean | null;
+  /** Original subtree retained for unknown attributes and `p:extLst`. */
+  rawXml?: XmlObject;
+}
+/**
+ * Resolved hex values for the 12 theme colour slots.
+ *
+ * @example
+ * ```ts
+ * const scheme: PptxThemeColorScheme = {
+ *   dk1: "#000000", lt1: "#FFFFFF",
+ *   dk2: "#1F497D", lt2: "#EEECE1",
+ *   accent1: "#4F81BD", accent2: "#C0504D",
+ *   accent3: "#9BBB59", accent4: "#8064A2",
+ *   accent5: "#4BACC6", accent6: "#F79646",
+ *   hlink: "#0000FF", folHlink: "#800080",
+ * };
+ * // => satisfies PptxThemeColorScheme
+ * ```
+ */
+interface PptxThemeColorScheme {
+  dk1: string;
+  lt1: string;
   dk2: string;
   lt2: string;
   accent1: string;
@@ -5215,6 +6083,125 @@ interface PptxSlideTransition {
   rawTransition?: XmlObject;
 }
 //#endregion
+//#region src/core/types/view-properties.d.ts
+/**
+ * View properties types parsed from `ppt/viewProps.xml`.
+ *
+ * Models the `p:viewPr` element and its child views:
+ * normalViewPr, slideViewPr, outlineViewPr, notesTextViewPr,
+ * sorterViewPr, notesViewPr.
+ *
+ * @module pptx-types/view-properties
+ */
+/**
+ * Scale factor for a view (numerator / denominator percentage).
+ */
+interface PptxViewScale {
+  /** Numerator of the scale percentage (e.g. 100 for 100%). */
+  n: number;
+  /** Denominator of the scale percentage (e.g. 100 for 100%). */
+  d: number;
+  /** Optional independent vertical scale. When absent, the X scale is used. */
+  sy?: {
+    n: number;
+    d: number;
+  };
+}
+/**
+ * Origin point for a view (x, y in twips or EMU).
+ */
+interface PptxViewOrigin {
+  x: number;
+  y: number;
+}
+/** A horizontal or vertical drawing guide in slide coordinates. */
+interface PptxViewGuide {
+  orientation?: 'horz' | 'vert';
+  position?: number;
+}
+/** Positive grid spacing from `p:gridSpacing`. */
+interface PptxGridSpacing {
+  cx: number;
+  cy: number;
+}
+/**
+ * Restored region dimensions for normal view splitter.
+ * Represents `p:restoredLeft` or `p:restoredTop`.
+ */
+interface PptxRestoredRegion {
+  /** Size as a percentage of the available space (thousandths of a percent). */
+  sz: number;
+  /** Whether auto-adjust is enabled. */
+  autoAdjust?: boolean;
+}
+/**
+ * Normal view properties (`p:normalViewPr`).
+ * Controls the splitter positions in normal (editing) view.
+ */
+interface PptxNormalViewProperties {
+  /** Whether to show outline icons in the slide panel. */
+  showOutlineIcons?: boolean;
+  /** Whether the outline/slide panel is snapped closed. */
+  snapVertSplitter?: boolean;
+  /** Vertical splitter bar state: 'minimized' | 'maximized' | 'restored'. */
+  vertBarState?: string;
+  /** Horizontal splitter bar state. */
+  horzBarState?: string;
+  /** Whether to prefer single-slide view in the panel. */
+  preferSingleView?: boolean;
+  /** Restored left region (slide panel width). */
+  restoredLeft?: PptxRestoredRegion;
+  /** Restored top region (notes panel height). */
+  restoredTop?: PptxRestoredRegion;
+}
+/**
+ * Common slide view properties shared by slideViewPr, outlineViewPr,
+ * notesTextViewPr, and notesViewPr.
+ */
+interface PptxCommonSlideViewProperties {
+  /** Whether snap-to-grid is enabled. */
+  snapToGrid?: boolean;
+  /** Whether snap-to-objects is enabled. */
+  snapToObjects?: boolean;
+  /** Whether drawing guides are shown. */
+  showGuides?: boolean;
+  /** Whether the application may vary the scale automatically. */
+  variableScale?: boolean;
+  /** Drawing guides shown in this slide view. */
+  guides?: PptxViewGuide[];
+  /** View origin (scroll position). */
+  origin?: PptxViewOrigin;
+  /** View scale. */
+  scale?: PptxViewScale;
+}
+/**
+ * Full view properties from `ppt/viewProps.xml`.
+ */
+interface PptxViewProperties {
+  /** Last used view type (`p:viewPr/@lastView`). */
+  lastView?: string;
+  /** Whether comments are shown (`p:viewPr/@showComments`). */
+  showComments?: boolean;
+  /** Normal view properties (splitter positions). */
+  normalViewPr?: PptxNormalViewProperties;
+  /** Slide view properties. */
+  slideViewPr?: PptxCommonSlideViewProperties;
+  /** Outline view properties. */
+  outlineViewPr?: PptxCommonSlideViewProperties;
+  /** Notes text view properties. */
+  notesTextViewPr?: PptxCommonSlideViewProperties;
+  /** Sorter view scale. */
+  sorterViewPr?: {
+    scale?: PptxViewScale;
+  };
+  /** Notes view properties. */
+  notesViewPr?: PptxCommonSlideViewProperties;
+  /** Grid spacing in positive DrawingML coordinates. */
+  gridSpacing?: PptxGridSpacing;
+  /** Raw XML preserved for lossless round-trip of unparsed attributes. */
+  rawXml?: Record<string, unknown>;
+}
+//#endregion
 //#region src/core/types/presentation.d.ts
 /**
  * A customer data reference from `p:custDataLst / p:custData`.
@@ -5252,6 +6239,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;
 }
@@ -5378,6 +6380,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. */
@@ -5399,6 +6408,105 @@ interface PptxSlideSyncProperties {
   partPath?: string;
   relationshipId?: string;
 }
+/**
+ * A slide layout available in the loaded presentation.
+ *
+ * Each entry maps to a `<p:sldLayout>` inside `ppt/slideLayouts/`.
+ *
+ * @example
+ * ```ts
+ * const layout: PptxLayoutOption = {
+ *   path: "ppt/slideLayouts/slideLayout2.xml",
+ *   name: "Title and Content",
+ * };
+ * // => satisfies PptxLayoutOption
+ * ```
+ */
+interface PptxLayoutOption {
+  path: string;
+  name: string;
+  /** Standard layout type from `p:sldLayout/@type` (e.g. "obj", "twoColTx", "blank"). */
+  type?: string;
+  /** ZIP path of the slide master this layout belongs to. */
+  masterPath?: string;
+}
+/**
+ * Header, footer, date-time, and slide-number placeholders.
+ *
+ * Parsed from `ppt/presProps.xml` and individual slide layouts.
+ *
+ * @example
+ * ```ts
+ * const hf: PptxHeaderFooter = {
+ *   hasFooter: true,
+ *   footerText: "Confidential",
+ *   hasSlideNumber: true,
+ * };
+ * // => satisfies PptxHeaderFooter
+ * ```
+ */
+interface PptxHeaderFooter {
+  hasHeader?: boolean;
+  headerText?: string;
+  hasFooter?: boolean;
+  footerText?: string;
+  hasDateTime?: boolean;
+  dateTimeText?: string;
+  dateTimeAuto?: boolean;
+  /** OOXML date format pattern (e.g. "M/d/yyyy", "dddd, MMMM dd, yyyy"). */
+  dateFormat?: string;
+  hasSlideNumber?: boolean;
+}
+/**
+ * Presentation-level properties parsed from `presentationPr.xml`.
+ *
+ * Controls slideshow behaviour, print settings, custom colours, and grid.
+ *
+ * @example
+ * ```ts
+ * const props: PptxPresentationProperties = {
+ *   showType: "presented",
+ *   loopContinuously: false,
+ *   advanceMode: "useTimings",
+ * };
+ * // => satisfies PptxPresentationProperties
+ * ```
+ */
+interface PptxPresentationProperties {
+  /** Show type: presented, browsed, kiosk. */
+  showType?: 'presented' | 'browsed' | 'kiosk';
+  /** Whether to loop the slideshow continuously. */
+  loopContinuously?: boolean;
+  /** Whether to show without narration. */
+  showWithNarration?: boolean;
+  /** Whether to show without animation. */
+  showWithAnimation?: boolean;
+  /** Advance slides mode: manual click or use stored timings. */
+  advanceMode?: 'manual' | 'useTimings';
+  /** Show slides: 'all', a custom show id, or a from-to range. */
+  showSlidesMode?: 'all' | 'customShow' | 'range';
+  /** Custom show id to use when showSlidesMode is 'customShow'. */
+  showSlidesCustomShowId?: string;
+  /** Slide range start (1-based) when showSlidesMode is 'range'. */
+  showSlidesFrom?: number;
+  /** Slide range end (1-based) when showSlidesMode is 'range'. */
+  showSlidesTo?: number;
+  /** Whether to show subtitles/captions during presentation mode. */
+  showSubtitles?: boolean;
+  /** Typed `p:prnPr` settings. Set to null during save to remove the element. */
+  printProperties?: PptxPresentationPrintProperties | null;
+  /** Most-recently-used colours from the presentation palette. */
+  mruColors?: string[];
+  /** Grid spacing in EMUs (cx, cy). Default is 914400 / 8 = 114300. */
+  gridSpacing?: {
+    cx: number;
+    cy: number;
+  };
+  /** Pen colour for presentation mode annotations (from `p:showPr/p:penClr`). */
+  penColor?: string;
+  /** Kiosk auto-restart interval in milliseconds (from `p:kiosk/@restart`). Only meaningful when showType is "kiosk". */
+  kioskRestartTime?: number;
+}
 /**
  * A named custom slide show (`p:custShowLst / p:custShow`).
  *
@@ -5425,122 +6533,1757 @@ interface PptxCustomShow {
   /** Original `p:custShow` subtree used to preserve unmodelled attributes and extensions. */
   rawXml?: XmlObject;
 }
-
-//#region src/theme/types.d.ts
 /**
- * Theme configuration types for the PowerPoint viewer.
+ * An ordered section in the presentation (from `p:sectionLst` / `p14:sectionLst`).
  *
- * 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.
+ * Sections group consecutive slides under a named heading (visible
+ * in the PowerPoint slide sorter).
  *
- * Framework-agnostic — shared by the React, Vue, and Angular bindings.
+ * @example
+ * ```ts
+ * const section: PptxSection = {
+ *   id: "sec_1",
+ *   name: "Introduction",
+ *   slideIds: ["256", "257"],
+ * };
+ * // => satisfies PptxSection
+ * ```
  */
+interface PptxSection {
+  /** Section unique identifier (GUID or synthetic). */
+  id: string;
+  /** Human-readable section name. */
+  name: string;
+  /** Ordered list of numeric slide IDs that belong to this section. */
+  slideIds: string[];
+  /** Whether the section is collapsed in the slide sorter (from p15:sectionPr). */
+  collapsed?: boolean;
+  /** Section highlight color hex (from p15:sectionPr/@clr). */
+  color?: string;
+  /** Original section subtree used to preserve unmodelled attributes and extensions. */
+  rawXml?: XmlObject;
+}
 /**
- * Semantic color tokens for the viewer UI.
+ * Write-protection hash data parsed from `p:modifyVerifier` in `presentation.xml`.
  *
- * 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.
+ * When present, the presentation is marked as "read-only recommended" or
+ * write-protected with a password hash.  The hash parameters follow the
+ * ECMA-376 Part 1, section 19.2.1.22 specification.
+ *
+ * @example
+ * ```ts
+ * const verifier: PptxModifyVerifier = {
+ *   algorithmName: "SHA-512",
+ *   hashData: "base64EncodedHash==",
+ *   saltData: "base64EncodedSalt==",
+ *   spinValue: 100000,
+ * };
+ * // => satisfies PptxModifyVerifier
+ * ```
  */
-interface 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 PptxModifyVerifier {
+  /** Hash algorithm name (e.g. "SHA-512", "SHA-1"). */
+  algorithmName?: string;
+  /** Base64-encoded hash value. */
+  hashData?: string;
+  /** Base64-encoded salt value. */
+  saltData?: string;
+  /** Number of hash iterations (spin count). */
+  spinValue?: number;
+  /** Legacy algorithm ID extension. */
+  algIdExt?: string;
+  /** Legacy algorithm ID. */
+  cryptAlgorithmSid?: number;
+  /** Cryptographic algorithm type (e.g. "typeAny"). */
+  cryptAlgorithmType?: string;
+  /** Cryptographic provider name. */
+  cryptProvider?: string;
+  /** Cryptographic provider type (e.g. "providerTypeRsaFull"). */
+  cryptProviderType?: string;
+  /** Cryptographic algorithm class (e.g. "hash"). */
+  cryptAlgorithmClass?: string;
+}
+/**
+ * Photo album metadata from `p:photoAlbum` in `presentation.xml`.
+ *
+ * Stores settings for presentations created via Insert > Photo Album.
+ *
+ * @see ECMA-376 Part 1, §19.2.1.27
+ */
+interface PptxPhotoAlbum {
+  /** Whether photos are displayed in black-and-white. */
+  bw?: boolean;
+  /** Whether captions are shown below each photo. */
+  showCaptions?: boolean;
+  /** Photo album layout (e.g. "1pic", "2pic", "4pic", "fitToSlide"). */
+  layout?: string;
+  /** Frame style applied to each photo (e.g. "frameStyle1"). */
+  frame?: string;
+}
+/**
+ * East Asian line-break (kinsoku) settings from `p:kinsoku` in `presentation.xml`.
+ *
+ * Defines forbidden start/end characters for a given language so that
+ * line-breaking follows East Asian typographic rules.
+ *
+ * @see ECMA-376 Part 1, §19.2.1.17
+ */
+interface PptxKinsoku {
+  /** Language code (e.g. "ja-JP", "zh-CN"). */
+  lang?: string | null;
+  /** Characters that cannot begin a line. */
+  invalStChars?: string;
+  /** Characters that cannot end a line. */
+  invalEndChars?: string;
+  /** Original leaf retained for unknown attribute preservation. */
+  rawXml?: XmlObject;
 }
 /**
- * Full viewer theme configuration.
+ * Root data structure returned by {@link PptxHandlerCore.load}.
  *
- * Every property is optional — unset values fall back to the built-in
- * dark theme defaults.
+ * Contains every slide, canvas dimensions, theme data, layout options,
+ * metadata, and optional features (custom shows, sections, macros,
+ * digital signatures, embedded fonts).
+ *
+ * @example
+ * ```ts
+ * const data: PptxData = await handler.load(buffer);
+ * console.log(`${data.slides.length} slides, ${data.width}×${data.height}`);
+ * // => e.g. "24 slides, 960×540"
+ * ```
  */
-interface 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;
+interface PptxData {
+  slides: PptxSlide[];
+  width: number;
+  height: number;
+  /** Slide width in EMU (for save round-trip). */
+  widthEmu?: number;
+  /** Slide height in EMU (for save round-trip). */
+  heightEmu?: number;
+  /** Slide size type from `p:sldSz/@type` (e.g. "screen4x3", "screen16x9", "custom"). */
+  slideSizeType?: string;
+  /** Notes page width in EMU (from `p:notesSz`). */
+  notesWidthEmu?: number;
+  /** Notes page height in EMU (from `p:notesSz`). */
+  notesHeightEmu?: number;
+  layoutOptions?: PptxLayoutOption[];
+  headerFooter?: PptxHeaderFooter;
+  /** Presentation-level properties parsed from `presentationPr.xml`. */
+  presentationProperties?: PptxPresentationProperties;
+  /** Named custom slide shows from `p:custShowLst`. */
+  customShows?: PptxCustomShow[];
+  /** Ordered presentation sections from `p:sectionLst` / `p14:sectionLst`. */
+  sections?: PptxSection[];
+  warnings?: PptxCompatibilityWarning[];
+  /** Map of theme colour scheme keys to resolved hex values. */
+  themeColorMap?: Record<string, string>;
+  /** Full parsed theme object with colours, fonts, and name. */
+  theme?: PptxTheme;
+  /** Available theme parts discovered in `ppt/theme/`. */
+  themeOptions?: PptxThemeOption[];
+  /** Parsed table style definitions from `ppt/tableStyles.xml`. */
+  tableStyleMap?: ParsedTableStyleMap;
+  /** Whether the presentation is password-protected. */
+  isPasswordProtected?: boolean;
+  /** Embedded font data (name + binary data URL) extracted from the presentation. */
+  embeddedFonts?: PptxEmbeddedFont[];
+  /** Typed `p:embeddedFontLst` package metadata, including unresolved variants. */
+  embeddedFontList?: PptxEmbeddedFontList;
+  /** Most-recently-used colour list from presentation properties. */
+  mruColors?: string[];
+  /** Parsed notes master data if present in the PPTX. */
+  notesMaster?: PptxNotesMaster;
+  /** Parsed handout master data if present in the PPTX. */
+  handoutMaster?: PptxHandoutMaster;
+  /** Structured slide master data for each master in the presentation. */
+  slideMasters?: PptxSlideMaster[];
+  /** Parsed tag collections attached to the presentation or slides. */
+  tags?: PptxTagCollection[];
+  /** Custom document properties from `docProps/custom.xml`. */
+  customProperties?: PptxCustomProperty[];
+  /** Core document properties from `docProps/core.xml`. */
+  coreProperties?: PptxCoreProperties;
+  /** Extended (application) properties from `docProps/app.xml`. */
+  appProperties?: PptxAppProperties;
+  /** Whether the presentation contains VBA macros (is a .pptm file). */
+  hasMacros?: boolean;
+  /** Whether the presentation contains digital signatures (`_xmlsignatures/` parts). */
+  hasDigitalSignatures?: boolean;
+  /** Number of digital signatures found. */
+  digitalSignatureCount?: number;
+  /** Presentation-level drawing guides from `p:extLst`. */
+  presentationGuides?: PptxDrawingGuide[];
+  /** View properties from `ppt/viewProps.xml`. */
+  viewProperties?: PptxViewProperties;
+  /** Write-protection verifier from `p:modifyVerifier` in `presentation.xml`. */
+  modifyVerifier?: PptxModifyVerifier;
+  /** Photo album metadata from `p:photoAlbum` in `presentation.xml`. */
+  photoAlbum?: PptxPhotoAlbum;
+  /** East Asian line-break settings from `p:kinsoku` in `presentation.xml`. */
+  kinsoku?: PptxKinsoku;
+  /** Custom XML data parts from `customXml/` in the OPC package. */
+  customXmlParts?: PptxCustomXmlPart[];
+  /** Customer data references from `p:custDataLst` in `presentation.xml`. */
+  customerData?: PptxCustomerData[];
+  /** Thumbnail image binary data from `docProps/thumbnail.{jpeg,png}`. */
+  thumbnailData?: Uint8Array;
+  /** Comment authors parsed from `ppt/commentAuthors.xml` for round-trip preservation. */
+  commentAuthors?: PptxCommentAuthor[];
+  /** Office 2021 p188 authors from the modern Author part. */
+  modernCommentAuthors?: PptxModernCommentAuthor[];
   /**
-   * Escape hatch: arbitrary CSS custom properties to set on the viewer
-   * root element. Keys should include the `--` prefix.
+   * OOXML conformance class of the loaded file.
+   * - `'strict'` -- ISO/IEC 29500 Strict (uses `purl.oclc.org` namespace URIs)
+   * - `'transitional'` -- ECMA-376 Transitional (uses `schemas.openxmlformats.org` URIs)
    *
-   * @example
-   * ```ts
-   * { "--my-custom-shadow": "0 4px 12px rgba(0,0,0,0.5)" }
-   * ```
+   * When saving, if the save option `conformance` is `'preserve'` (default),
+   * the file will be saved using the same conformance class as the original.
    */
-  cssVars?: Record<string, string>;
+  conformance?: 'strict' | 'transitional';
 }
-//#endregion
-//#region src/theme/defaults.d.ts
 /**
- * Default dark-theme color values.
+ * Target format for slide export.
  *
- * These correspond to the built-in dark UI of the PowerPoint viewer and
- * use Tailwind's gray palette as the neutral scale with indigo as the
- * primary accent.
+ * @see {@link PptxExportOptions}
  */
-declare const defaultThemeColors: ViewerThemeColors;
-/** Default border-radius. */
-declare const defaultRadius = "0.5rem";
-//#endregion
-//#region src/theme/css-vars.d.ts
+type PptxExportFormat = 'pdf' | 'png' | 'svg';
 /**
- * Convert a `ViewerTheme` into a flat `Record<string, string>` of CSS
- * custom properties (including the `--` prefix) ready to be spread onto
- * a `style` attribute.
+ * Options controlling slide export to raster or vector formats.
  *
- * Only properties that differ from the built-in defaults are emitted when
- * `omitDefaults` is true (the default).
+ * @example
+ * ```ts
+ * const opts: PptxExportOptions = {
+ *   format: "png",
+ *   slideIndices: [0, 2, 4],
+ *   dpi: 300,
+ * };
+ * // => satisfies PptxExportOptions
+ * ```
  */
-declare function themeToCssVars(theme: ViewerTheme | undefined, omitDefaults?: boolean): Record<string, string>;
+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;
+}
 /**
- * Build the complete set of CSS custom properties with all defaults.
- * Useful for generating a full fallback stylesheet.
+ * Embedded font data extracted from a PPTX file.
+ *
+ * Used to register `@font-face` rules so the renderer can display
+ * the correct typeface even when the system font is missing.
+ *
+ * @example
+ * ```ts
+ * const font: PptxEmbeddedFont = {
+ *   name: "CustomSans",
+ *   dataUrl: "data:font/truetype;base64,AAEAK...",
+ *   format: "truetype",
+ * };
+ * // => satisfies PptxEmbeddedFont
+ * ```
  */
-declare function defaultCssVars(): Record<string, string>;
-//#endregion
-//#region src/theme/presets.d.ts
 /**
- * Built-in "vermilion" theme presets.
+ * A single Custom XML Data Part stored in `customXml/` within the OPC package.
  *
- * These mirror the pptx-viewer brand used on the documentation site:
- * a warm paper canvas in light mode, a dimmed presenter room in dark
- * mode, and the vermilion accent in both. Pass one to the viewer's
+ * These parts are used by add-ins, data-binding, and enterprise templates
+ * to store structured data alongside the presentation.
+ *
+ * @see ECMA-376 Part 1, §15.2.5
+ */
+interface PptxCustomXmlPart {
+  /** Item number (e.g. "1" for `customXml/item1.xml`). */
+  id: string;
+  /** Raw XML string content of the custom XML item. */
+  data: string;
+  /** Schema target namespace URI from `itemProps` (ds:schemaRef/@ds:uri). */
+  schemaUri?: string;
+  /** Raw XML string content of the associated `itemProps` file. */
+  properties?: string;
+  /** Raw XML string content of the OPC relationship file (`customXml/_rels/item{id}.xml.rels`). */
+  rels?: string;
+}
+interface PptxEmbeddedFont {
+  name: string;
+  dataUrl: string;
+  bold?: boolean;
+  italic?: boolean;
+  /** CSS font format hint (e.g. "truetype", "opentype"). */
+  format?: 'truetype' | 'opentype' | 'woff' | 'woff2';
+  /**
+   * Deobfuscated (clear-text) font binary data preserved from load
+   * for round-trip re-embedding on save. When present, the save
+   * pipeline will re-obfuscate and write this data back into the ZIP.
+   */
+  rawFontData?: Uint8Array;
+  /**
+   * Original ZIP path of the font part (e.g. `ppt/fonts/{GUID}.fntdata`).
+   * Preserved from load for round-trip.
+   */
+  partPath?: string;
+  /**
+   * The GUID used for obfuscation, either from the `fontKey` attribute
+   * or extracted from the part path. Preserved from load for round-trip.
+   */
+  fontGuid?: string;
+  /**
+   * Relationship ID (e.g. `rId21`) of the font part in
+   * `ppt/_rels/presentation.xml.rels`. Preserved from load so the save
+   * pipeline can reuse the original part/rel instead of minting a new
+   * GUID-named copy alongside the stale original.
+   */
+  originalRId?: string;
+  /**
+   * Raw bytes of the original obfuscated font part exactly as they were
+   * stored in the source ZIP. When the loader could not determine a
+   * usable GUID (e.g. EOT extraction path), the save pipeline preserves
+   * these bytes verbatim under the original path/rel.
+   */
+  originalPartBytes?: Uint8Array;
+}
+
+//#endregion
+//#region src/core/types/theme-presets.d.ts
+/**
+ * A complete theme preset that can be applied to a presentation.
+ *
+ * @example
+ * ```ts
+ * import { THEME_PRESETS } from "pptx-viewer-core";
+ *
+ * const office = THEME_PRESETS.find(p => p.id === "office");
+ * await handler.switchTheme(office.colorScheme, office.fontScheme, office.name);
+ * ```
+ */
+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;
+}
+//#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>;
+}
+
+//#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)" }
+   * ```
+   */
+  cssVars?: Record<string, string>;
+}
+//#endregion
+//#region src/theme/defaults.d.ts
+/**
+ * Default dark-theme color values.
+ *
+ * These correspond to the built-in dark UI of the PowerPoint viewer and
+ * use Tailwind's gray palette as the neutral scale with indigo as the
+ * primary accent.
+ */
+declare const defaultThemeColors: ViewerThemeColors;
+/** Default border-radius. */
+declare const defaultRadius = "0.5rem";
+//#endregion
+//#region src/theme/css-vars.d.ts
+/**
+ * Convert a `ViewerTheme` into a flat `Record<string, string>` of CSS
+ * custom properties (including the `--` prefix) ready to be spread onto
+ * a `style` attribute.
+ *
+ * Only properties that differ from the built-in defaults are emitted when
+ * `omitDefaults` is true (the default).
+ */
+declare function themeToCssVars(theme: ViewerTheme | undefined, omitDefaults?: boolean): Record<string, string>;
+/**
+ * Build the complete set of CSS custom properties with all defaults.
+ * Useful for generating a full fallback stylesheet.
+ */
+declare function defaultCssVars(): Record<string, string>;
+//#endregion
+//#region src/theme/presets.d.ts
+/**
+ * Built-in "vermilion" theme presets.
+ *
+ * These mirror the pptx-viewer brand used on the documentation site:
+ * a warm paper canvas in light mode, a dimmed presenter room in dark
+ * mode, and the vermilion accent in both. Pass one to the viewer's
  * `theme` prop (React/Vue) or `provideViewerTheme` (Angular), or spread
  * the color objects to derive your own variant.
  */
@@ -5740,12 +8483,69 @@ interface CollaborationConfig {
    */
   writeBackDebounceMs?: number;
 }
+/**
+ * Normalized staged-reveal mode for a chart graphic frame, derived from the
+ * OOXML `a:bldChart/@bld` (or `p:bldOleChart/@bld`) token:
+ *  - `asOne`      the whole chart appears at once (`allAtOnce`).
+ *  - `bySeries`   one data series is revealed per stage (`series`).
+ *  - `byCategory` one category is revealed per stage (`category`).
+ *  - `byElement`  one series/category ELEMENT is revealed per stage
+ *                 (`seriesElement` / `categoryElement`).
+ */
+type ChartBuildMode = 'asOne' | 'bySeries' | 'byCategory' | 'byElement';
+/**
+ * Normalized staged-reveal mode for a SmartArt diagram, derived from the OOXML
+ * `a:bldDgm/@bld` or `p:bldDgm/@bld` token:
+ *  - `asOne`        the whole diagram appears at once (`whole` / `allAtOnce`).
+ *  - `byOne`        one node is revealed per stage (`one`, and the assorted
+ *                   `depthBy*` / `breadthBy*` / directional traversals).
+ *  - `byLvl`        levels are revealed one element at a time (`lvlOne`).
+ *  - `byLvlAtOnce`  a whole level is revealed per stage (`lvlAtOnce`).
+ */
+type DiagramBuildMode = 'asOne' | 'byOne' | 'byLvl' | 'byLvlAtOnce';
+/**
+ * Playback-time staged-build state surfaced on {@link ElementAnimationState}.
+ * `progress` is the 0..1 fraction of the build revealed at the current playback
+ * time; a consumer maps it to its own item COUNT (see `revealedStageCount`).
+ */
+type ElementBuildState = {
+  kind: 'chart';
+  mode: ChartBuildMode;
+  progress: number;
+} | {
+  kind: 'diagram';
+  mode: DiagramBuildMode;
+  progress: number;
+};
 /** Snapshot of a single element's animation state at a point in the timeline. */
 interface ElementAnimationState {
   /** Whether the element should be visible. */
   visible: boolean;
   /** CSS animation shorthand to apply (undefined = no active animation). */
   cssAnimation: string | undefined;
+  /**
+   * Staged-build reveal state, present only when the active animation builds a
+   * chart or SmartArt diagram in stages (`p:bldChart` / `p:bldDgm`) rather than
+   * revealing the whole element at once. A staged renderer multiplies
+   * `build.progress` (0..1) by its own series / category / level COUNT to
+   * decide how many stages are revealed at the current playback time; see
+   * {@link import('./animation-build').revealedStageCount}. Absent for ordinary
+   * whole-element entrances, so existing renderers are unaffected.
+   */
+  build?: ElementBuildState;
+  /**
+   * True when an active `p:animClr` color animation targets this shape's fill.
+   * A vector renderer should then paint the fill with `fill: inherit` so the
+   * wrapper-level colour keyframes cascade to the SVG path. Absent/false means
+   * no active fill-colour animation.
+   */
+  animatesFill?: boolean;
+  /**
+   * True when an active `p:animClr` color animation targets this shape's
+   * stroke. A vector renderer should then paint the stroke with
+   * `stroke: inherit`. Absent/false means no active stroke-colour animation.
+   */
+  animatesStroke?: boolean;
 }
 /** The unit system used for ruler display. */
 type RulerUnit = 'inches' | 'centimetres';
@@ -6019,25 +8819,6 @@ declare function writeStoredViewerPrefs(patch: Partial<StoredViewerPrefs>): void
 /** Remove all persisted viewer preferences. Silently no-ops when storage is unavailable. */
 declare function clearStoredViewerPrefs(): void;
 
-//#endregion
-//#region src/i18n/locale-catalog.d.ts
-/** One selectable entry in the viewer chrome's built-in language picker (File > Options > Language). */
-interface LocaleCatalogEntry {
-  /** BCP-47-ish locale code, e.g. `'en'`, `'fr'`. Matches `pptx-viewer-locales`' exports. */
-  code: string;
-  /** English display name, used before a translation dictionary for the target locale is loaded. */
-  label: string;
-  /** The locale's own name for itself, e.g. `'Français'` for `fr`. */
-  nativeLabel: string;
-}
-/**
- * Built-in language choices offered by File > Options > Language when a host
- * doesn't supply its own `availableLocales`. Mirrors the locales shipped by
- * the optional `pptx-viewer-locales` package (English needs no dictionary,
- * it's the viewer's own baseline).
- */
-declare const LOCALE_CATALOG: readonly LocaleCatalogEntry[];
-
 //#region src/viewer/types-core.d.ts
 /**
  * Union of all shape preset types that the viewer can insert or render.
@@ -6073,6 +8854,228 @@ declare function ViewerThemeProvider({ theme, children }: ViewerThemeProviderPro
  */
 declare function useViewerTheme(): ViewerTheme | undefined;
 //#endregion
+//#region ../shared/dist/ai/index.d.ts
+//#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/viewer/types-ui.d.ts
 /**
  * Base handle interface for file viewer components.
@@ -6273,11 +9276,11 @@ interface PowerPointViewerProps {
     serverUrl?: string;
   };
   /**
-   * Opt in to the experimental Three.js SmartArt renderer. When `true`,
-   * SmartArt diagrams render as extruded 3D blocks on a WebGL canvas instead
-   * of flat SVG. Requires the optional `three` peer dependency; when it is not
-   * installed (or the diagram has no geometry), the viewer transparently falls
-   * back to the SVG `SmartArtRenderer`. Default `false`.
+   * Opt in to the Three.js SmartArt renderer. When `true`, SmartArt diagrams
+   * render as extruded 3D blocks on a WebGL canvas instead of flat SVG.
+   * Requires the optional `three` peer dependency; when it is not installed
+   * (or the diagram has no geometry), the viewer transparently falls back to
+   * the SVG `SmartArtRenderer`. Default `false`.
    */
   smartArt3D?: boolean;
   /**
@@ -6298,163 +9301,44 @@ interface PowerPointViewerProps {
    * ```
    */
   hiddenActions?: ToolbarActionId[];
-}
-interface PowerPointViewerHandle extends FileViewerHandle, PowerPointViewerAPI {
-  getContent: () => Promise<Uint8Array>;
-}
-
-//#region src/viewer/hooks/useAutosave.d.ts
-type AutosaveStatus = {
-  state: 'idle';
-} | {
-  state: 'disabled';
-  reason: string;
-} | {
-  state: 'saving';
-} | {
-  state: 'saved';
-  timestamp: number;
-} | {
-  state: 'error';
-  message: string;
-};
-//#endregion
-//#region src/viewer/utils/table-band-style.d.ts
-/** Context for resolving table style colours from the theme. */
-interface TableStyleContext {
-  tableStyleMap?: ParsedTableStyleMap;
-  theme?: PptxTheme;
-}
-//#endregion
-//#region src/viewer/components/canvas/canvas-types.d.ts
-interface ZoomViewport {
-  canvasViewportRef: React$1__default.RefObject<HTMLDivElement | null>;
-  editWrapperRef: React$1__default.RefObject<HTMLDivElement | null>;
-  canvasStageRef: React$1__default.RefObject<HTMLDivElement | null>;
-  editorScale: number;
-}
-interface SlideCanvasProps {
-  activeSlide: PptxSlide | undefined;
-  templateElements: PptxElement[];
-  canvasSize: CanvasSize;
-  zoom: ZoomViewport;
-  mode: ViewerMode;
-  canEdit: boolean;
-  editTemplateMode: boolean;
-  selectedElementIdSet: Set<string>;
-  selectedElement: PptxElement | null;
-  inlineEditingElementId: string | null;
-  inlineEditingText: string;
-  spellCheckEnabled: boolean;
-  mediaDataUrls: Map<string, string>;
-  tableEditorState: TableCellEditorState | null;
-  marqueeSelectionState: MarqueeSelectionState | null;
-  snapLines: Array<{
-    axis: string;
-    position: number;
-  }>;
-  showGrid: boolean;
-  /** Grid spacing in CSS px (derived from PPTX gridSpacing EMUs). */
-  gridSpacingPx?: number;
-  showRulers: boolean;
-  /** Unit system for rulers (default: inches). */
-  rulerUnit?: RulerUnit;
-  guides: Array<{
-    id: string;
-    axis: 'h' | 'v';
-    position: number;
-  }>;
-  presentationElementStates?: Map<string, ElementAnimationState>;
-  presentationKeyframesCss?: string;
-  onClick: (elementId: string, e: React$1__default.MouseEvent) => void;
-  onDoubleClick: (elementId: string, e: React$1__default.MouseEvent) => void;
-  onMouseDown: (elementId: string, e: React$1__default.MouseEvent) => void;
-  onContextMenu: (elementId: string, e: React$1__default.MouseEvent) => void;
-  /** Called when the user presses mouse down on empty canvas space. */
-  onCanvasMouseDown?: (e: React$1__default.MouseEvent) => void;
-  onResizePointerDown: (elementId: string, e: React$1__default.MouseEvent, handle: string) => void;
-  onAdjustmentPointerDown: (elementId: string, e: React$1__default.MouseEvent) => void;
-  /** Commit a new rotation (degrees) when the on-canvas rotate handle is dragged. */
-  onRotate?: (elementId: string, rotationDeg: number) => void;
-  onInlineEditChange: (text: string) => void;
-  onInlineEditCommit: () => void;
-  onInlineEditCancel: () => void;
-  onTableCellSelect: (cell: Omit<TableCellEditorState, 'elementId'> | null, elementId: string) => void;
-  /** Called when an edited table cell should be committed. */
-  onCommitCellEdit?: (elementId: string, rowIndex: number, colIndex: number, text: string) => void;
-  /**
-   * Commit a partial update to a SmartArt element from inline (on-canvas) node
-   * editing. Routed to the same element-update path the inspector uses (undo/redo
-   * + dirty marking). When absent, inline SmartArt editing is disabled.
-   */
-  onUpdateSmartArtElement?: (elementId: string, updates: Partial<PptxElement>) => void;
   /**
-   * Apply a text-style toggle (Ctrl/Cmd+B/I/U) to the element being
-   * inline-edited. Routed to the same updateSelectedTextStyle path as the
-   * toolbar. When absent, the inline formatting shortcuts are inert.
+   * Opt in to the built-in AI assistant. When provided, a Sparkles toggle
+   * appears in the toolbar and opens a chat panel wired to this config; when
+   * omitted, no AI icon renders and no AI code is loaded (the panel and its
+   * `@ai-sdk/react` dependency are `React.lazy`-imported only on first open).
+   *
+   * The host supplies the model connection (a backend `endpoint`, an in-browser
+   * `model`, or a custom `transport`) plus optional tool allow/deny lists and a
+   * write policy. Requires the optional `ai` and `@ai-sdk/react` peers.
+   *
+   * @example
+   * ```tsx
+   * <PowerPointViewer content={bytes} ai={{ connection: { kind: 'model', model } }} />
+   * ```
+   *
+   * @see {@link PptxAiConfig}
    */
-  onFormatText?: (updates: Partial<TextStyle>) => void;
-  /** Called when table column widths are resized. */
-  onResizeTableColumns?: (elementId: string, newWidths: number[]) => void;
-  /** Called when a table row is resized. */
-  onResizeTableRow?: (elementId: string, rowIndex: number, newHeight: number) => void;
-  /** Find & Replace results (all matches across all slides). */
-  findResults?: Array<{
-    slideIndex: number;
-    elementId: string;
-    segmentIndex: number;
-    startOffset: number;
-    length: number;
-  }>;
-  /** Index of the currently focused find result (-1 for none). */
-  findResultIndex?: number;
-  /** Index of the currently visible slide (needed to filter find results). */
-  activeSlideIndex?: number;
-  /** Currently active drawing tool ("select" means no drawing overlay). */
-  activeTool?: DrawingTool;
-  /** Stroke colour for pen / highlighter. */
-  drawingColor?: string;
-  /** Stroke width for pen / highlighter. */
-  drawingWidth?: number;
-  /** Ref that is true while a pointer stroke is in progress. */
-  isDrawingRef?: React$1__default.RefObject<boolean>;
-  /** Called when a completed ink stroke should be added to the slide. */
-  onAddInkElement?: (ink: InkPptxElement) => void;
-  /** Called when a freeform drawing stroke should be added as a shape element. */
-  onAddFreeformShape?: (shape: ShapePptxElement) => void;
-  /** Called when the eraser tool removes an ink element. */
-  onEraseInkElement?: (elementId: string) => void;
-  /** Called when a shape-level action is clicked (e.g. slide jump, URL). */
-  onActionClick?: (elementId: string, action: PptxAction) => void;
-  /** Called when a text-level hyperlink is clicked. */
-  onHyperlinkClick?: (url: string) => void;
-  /** Comments for the current slide (used for on-canvas markers). */
-  comments?: PptxComment[];
-  /** Whether to show comment markers on the slide canvas. */
-  showCommentMarkers?: boolean;
-  /** Called when a comment marker is clicked. */
-  onCommentMarkerClick?: (commentId: string) => void;
-  onMoveGuide?: (guideId: string, position: number) => void;
-  onDeleteGuide?: (guideId: string) => void;
-  onCreateGuideFromRuler?: (axis: 'h' | 'v', positionPx: number) => void;
-  /** When true, shows connection sites on shapes and enables connector drawing. */
-  connectorCreationMode?: boolean;
-  /** Called when a new connector is created between two shapes. */
-  onCreateConnector?: (connector: ConnectorPptxElement) => void;
-  /** All slides in the presentation (for zoom element thumbnails). */
-  allSlides?: readonly PptxSlide[];
-  /** Callback fired when a zoom element is clicked in presentation mode. */
-  onZoomClick?: (targetSlideIndex: number, returnSlideIndex: number) => void;
-  /** Index of the current slide (for zoom return navigation). */
-  sourceSlideIndex?: number;
-  /** Context for text field placeholder substitution (slide number, header/footer, etc.). */
-  fieldContext?: FieldSubstitutionContext;
-  /** Theme + table style map for resolving table band/header colours. */
-  tableStyleContext?: TableStyleContext;
-  /** Optional collaboration cursor overlay rendered on top of the canvas. */
-  collaborationOverlay?: React$1__default.ReactNode;
+  ai?: PptxAiConfig;
+}
+interface PowerPointViewerHandle extends FileViewerHandle, PowerPointViewerAPI {
+  getContent: () => Promise<Uint8Array>;
 }
+
+//#region src/viewer/utils/animation-effects.d.ts
+declare function getAnimationInitialStyle(preset: PptxAnimationPreset | undefined, nativeAnimation?: PptxNativeAnimation): React$1__default.CSSProperties;
 //#endregion
+//#region src/viewer/PowerPointViewer.d.ts
+/**
+ * Root React component for the PowerPoint viewer/editor.
+ *
+ * Accepts binary `.pptx` content and renders a full-featured editor with
+ * slide canvas, toolbar, inspector panels, presentation mode, and more.
+ *
+ * Uses `forwardRef` to expose a `PowerPointViewerHandle` for imperative
+ * access (e.g. serialising the current content for saving).
+ */
+declare const PowerPointViewer: React$1.ForwardRefExoticComponent<PowerPointViewerProps & React$1.RefAttributes<PowerPointViewerHandle>>;
+
 //#region src/viewer/components/toolbar/toolbar-types.d.ts
 interface ToolbarProps {
   fileName?: string;
@@ -6606,8 +9490,171 @@ interface ToolbarProps {
   onApplyTransitionToAll: () => void;
   /** Host-supplied list of toolbar buttons/ribbon tabs to hide. See `PowerPointViewerProps.hiddenActions`. */
   hiddenActions?: readonly ToolbarActionId[];
+  /** Whether the AI assistant is available (the host passed the `ai` prop). */
+  aiEnabled?: boolean;
+  /** Whether the AI assistant panel is currently open. */
+  isAiPanelOpen?: boolean;
+  /** Toggle the AI assistant panel. */
+  onToggleAiPanel?: () => void;
+}
+//#endregion
+//#region src/viewer/utils/table-band-style.d.ts
+/** Context for resolving table style colours from the theme. */
+interface TableStyleContext {
+  tableStyleMap?: ParsedTableStyleMap;
+  theme?: PptxTheme;
+}
+//#endregion
+//#region src/viewer/components/canvas/canvas-types.d.ts
+interface ZoomViewport {
+  canvasViewportRef: React$1__default.RefObject<HTMLDivElement | null>;
+  editWrapperRef: React$1__default.RefObject<HTMLDivElement | null>;
+  canvasStageRef: React$1__default.RefObject<HTMLDivElement | null>;
+  editorScale: number;
+}
+interface SlideCanvasProps {
+  activeSlide: PptxSlide | undefined;
+  templateElements: PptxElement[];
+  canvasSize: CanvasSize;
+  zoom: ZoomViewport;
+  mode: ViewerMode;
+  canEdit: boolean;
+  editTemplateMode: boolean;
+  selectedElementIdSet: Set<string>;
+  selectedElement: PptxElement | null;
+  inlineEditingElementId: string | null;
+  inlineEditingText: string;
+  spellCheckEnabled: boolean;
+  mediaDataUrls: Map<string, string>;
+  tableEditorState: TableCellEditorState | null;
+  marqueeSelectionState: MarqueeSelectionState | null;
+  snapLines: Array<{
+    axis: string;
+    position: number;
+  }>;
+  showGrid: boolean;
+  /** Grid spacing in CSS px (derived from PPTX gridSpacing EMUs). */
+  gridSpacingPx?: number;
+  showRulers: boolean;
+  /** Unit system for rulers (default: inches). */
+  rulerUnit?: RulerUnit;
+  guides: Array<{
+    id: string;
+    axis: 'h' | 'v';
+    position: number;
+  }>;
+  presentationElementStates?: Map<string, ElementAnimationState>;
+  presentationKeyframesCss?: string;
+  onClick: (elementId: string, e: React$1__default.MouseEvent) => void;
+  onDoubleClick: (elementId: string, e: React$1__default.MouseEvent) => void;
+  onMouseDown: (elementId: string, e: React$1__default.MouseEvent) => void;
+  onContextMenu: (elementId: string, e: React$1__default.MouseEvent) => void;
+  /** Called when the user presses mouse down on empty canvas space. */
+  onCanvasMouseDown?: (e: React$1__default.MouseEvent) => void;
+  onResizePointerDown: (elementId: string, e: React$1__default.MouseEvent, handle: string) => void;
+  onAdjustmentPointerDown: (elementId: string, e: React$1__default.MouseEvent) => void;
+  /** Commit a new rotation (degrees) when the on-canvas rotate handle is dragged. */
+  onRotate?: (elementId: string, rotationDeg: number) => void;
+  onInlineEditChange: (text: string) => void;
+  onInlineEditCommit: () => void;
+  onInlineEditCancel: () => void;
+  onTableCellSelect: (cell: Omit<TableCellEditorState, 'elementId'> | null, elementId: string) => void;
+  /** Called when an edited table cell should be committed. */
+  onCommitCellEdit?: (elementId: string, rowIndex: number, colIndex: number, text: string) => void;
+  /**
+   * Commit a partial update to a SmartArt element from inline (on-canvas) node
+   * editing. Routed to the same element-update path the inspector uses (undo/redo
+   * + dirty marking). When absent, inline SmartArt editing is disabled.
+   */
+  onUpdateSmartArtElement?: (elementId: string, updates: Partial<PptxElement>) => void;
+  /**
+   * Apply a text-style toggle (Ctrl/Cmd+B/I/U) to the element being
+   * inline-edited. Routed to the same updateSelectedTextStyle path as the
+   * toolbar. When absent, the inline formatting shortcuts are inert.
+   */
+  onFormatText?: (updates: Partial<TextStyle>) => void;
+  /** Called when table column widths are resized. */
+  onResizeTableColumns?: (elementId: string, newWidths: number[]) => void;
+  /** Called when a table row is resized. */
+  onResizeTableRow?: (elementId: string, rowIndex: number, newHeight: number) => void;
+  /** Find & Replace results (all matches across all slides). */
+  findResults?: Array<{
+    slideIndex: number;
+    elementId: string;
+    segmentIndex: number;
+    startOffset: number;
+    length: number;
+  }>;
+  /** Index of the currently focused find result (-1 for none). */
+  findResultIndex?: number;
+  /** Index of the currently visible slide (needed to filter find results). */
+  activeSlideIndex?: number;
+  /** Currently active drawing tool ("select" means no drawing overlay). */
+  activeTool?: DrawingTool;
+  /** Stroke colour for pen / highlighter. */
+  drawingColor?: string;
+  /** Stroke width for pen / highlighter. */
+  drawingWidth?: number;
+  /** Ref that is true while a pointer stroke is in progress. */
+  isDrawingRef?: React$1__default.RefObject<boolean>;
+  /** Called when a completed ink stroke should be added to the slide. */
+  onAddInkElement?: (ink: InkPptxElement) => void;
+  /** Called when a freeform drawing stroke should be added as a shape element. */
+  onAddFreeformShape?: (shape: ShapePptxElement) => void;
+  /** Called when the eraser tool removes an ink element. */
+  onEraseInkElement?: (elementId: string) => void;
+  /** Called when a shape-level action is clicked (e.g. slide jump, URL). */
+  onActionClick?: (elementId: string, action: PptxAction) => void;
+  /** Called when a text-level hyperlink is clicked. */
+  onHyperlinkClick?: (url: string) => void;
+  /** Comments for the current slide (used for on-canvas markers). */
+  comments?: PptxComment[];
+  /** Whether to show comment markers on the slide canvas. */
+  showCommentMarkers?: boolean;
+  /** Called when a comment marker is clicked. */
+  onCommentMarkerClick?: (commentId: string) => void;
+  onMoveGuide?: (guideId: string, position: number) => void;
+  onDeleteGuide?: (guideId: string) => void;
+  onCreateGuideFromRuler?: (axis: 'h' | 'v', positionPx: number) => void;
+  /** When true, shows connection sites on shapes and enables connector drawing. */
+  connectorCreationMode?: boolean;
+  /** Called when a new connector is created between two shapes. */
+  onCreateConnector?: (connector: ConnectorPptxElement) => void;
+  /** All slides in the presentation (for zoom element thumbnails). */
+  allSlides?: readonly PptxSlide[];
+  /** Callback fired when a zoom element is clicked in presentation mode. */
+  onZoomClick?: (targetSlideIndex: number, returnSlideIndex: number) => void;
+  /** Index of the current slide (for zoom return navigation). */
+  sourceSlideIndex?: number;
+  /** Context for text field placeholder substitution (slide number, header/footer, etc.). */
+  fieldContext?: FieldSubstitutionContext;
+  /** Theme + table style map for resolving table band/header colours. */
+  tableStyleContext?: TableStyleContext;
+  /** Optional collaboration cursor overlay rendered on top of the canvas. */
+  collaborationOverlay?: React$1__default.ReactNode;
+  /**
+   * When true, the stage marks itself `data-pptx-ai-active` so element colour
+   * changes tween while the AI assistant is working (see AiFocusHighlightOverlay).
+   */
+  aiActive?: boolean;
 }
 //#endregion
+//#region src/viewer/hooks/useAutosave.d.ts
+type AutosaveStatus = {
+  state: 'idle';
+} | {
+  state: 'disabled';
+  reason: string;
+} | {
+  state: 'saving';
+} | {
+  state: 'saved';
+  timestamp: number;
+} | {
+  state: 'error';
+  message: string;
+};
+//#endregion
 //#region src/viewer/hooks/useViewerBuildingBlocks.d.ts
 interface UseViewerBuildingBlocksInput {
   /** PPTX content as ArrayBuffer/Uint8Array, or null/undefined while no file is loaded. */
@@ -6656,26 +9703,11 @@ interface ViewerBuildingBlocksResult {
 }
 declare function useViewerBuildingBlocks(input: UseViewerBuildingBlocksInput): ViewerBuildingBlocksResult;
 
-//#region src/viewer/utils/animation-effects.d.ts
-declare function getAnimationInitialStyle(preset: PptxAnimationPreset | undefined, nativeAnimation?: PptxNativeAnimation): React$1__default.CSSProperties;
-//#endregion
-//#region src/viewer/PowerPointViewer.d.ts
-/**
- * Root React component for the PowerPoint viewer/editor.
- *
- * Accepts binary `.pptx` content and renders a full-featured editor with
- * slide canvas, toolbar, inspector panels, presentation mode, and more.
- *
- * Uses `forwardRef` to expose a `PowerPointViewerHandle` for imperative
- * access (e.g. serialising the current content for saving).
- */
-declare const PowerPointViewer: React$1.ForwardRefExoticComponent<PowerPointViewerProps & React$1.RefAttributes<PowerPointViewerHandle>>;
-
 //#region src/viewer/components/Toolbar.d.ts
 declare function Toolbar(p: ToolbarProps): React$1__default.ReactElement;
 //#endregion
 //#region src/viewer/components/SlideCanvas.d.ts
-declare function SlideCanvas({ activeSlide, templateElements, canvasSize, zoom, mode, canEdit, editTemplateMode, selectedElementIdSet, selectedElement, inlineEditingElementId, inlineEditingText, spellCheckEnabled, mediaDataUrls, tableEditorState, marqueeSelectionState, snapLines, showGrid, gridSpacingPx, showRulers, rulerUnit, guides, presentationElementStates, presentationKeyframesCss, onClick, onDoubleClick, onMouseDown, onContextMenu, onCanvasMouseDown, onResizePointerDown, onAdjustmentPointerDown, onRotate, onInlineEditChange, onInlineEditCommit, onInlineEditCancel, onTableCellSelect, onCommitCellEdit, onUpdateSmartArtElement, onFormatText, onResizeTableColumns, onResizeTableRow, findResults, findResultIndex, activeSlideIndex, activeTool, drawingColor, drawingWidth, isDrawingRef, onAddInkElement, onAddFreeformShape, onEraseInkElement, onActionClick, onHyperlinkClick, comments, showCommentMarkers, onCommentMarkerClick, onMoveGuide, onDeleteGuide, onCreateGuideFromRuler, connectorCreationMode, onCreateConnector, allSlides, onZoomClick, sourceSlideIndex, fieldContext, tableStyleContext, collaborationOverlay }: SlideCanvasProps): React$1.JSX.Element;
+declare function SlideCanvas({ activeSlide, templateElements, canvasSize, zoom, mode, canEdit, editTemplateMode, selectedElementIdSet, selectedElement, inlineEditingElementId, inlineEditingText, spellCheckEnabled, mediaDataUrls, tableEditorState, marqueeSelectionState, snapLines, showGrid, gridSpacingPx, showRulers, rulerUnit, guides, presentationElementStates, presentationKeyframesCss, onClick, onDoubleClick, onMouseDown, onContextMenu, onCanvasMouseDown, onResizePointerDown, onAdjustmentPointerDown, onRotate, onInlineEditChange, onInlineEditCommit, onInlineEditCancel, onTableCellSelect, onCommitCellEdit, onUpdateSmartArtElement, onFormatText, onResizeTableColumns, onResizeTableRow, findResults, findResultIndex, activeSlideIndex, activeTool, drawingColor, drawingWidth, isDrawingRef, onAddInkElement, onAddFreeformShape, onEraseInkElement, onActionClick, onHyperlinkClick, comments, showCommentMarkers, onCommentMarkerClick, onMoveGuide, onDeleteGuide, onCreateGuideFromRuler, connectorCreationMode, onCreateConnector, allSlides, onZoomClick, sourceSlideIndex, fieldContext, tableStyleContext, collaborationOverlay, aiActive }: SlideCanvasProps): React$1.JSX.Element;
 //#endregion
 //#region src/lib/canvas-export.d.ts
 /**
@@ -6697,4 +9729,4 @@ declare function SlideCanvas({ activeSlide, templateElements, canvasSize, zoom,
 declare function renderToCanvas(element: HTMLElement, options?: Partial<Options>): Promise<HTMLCanvasElement>;
 
 export { AVATAR_COLOR_SWATCHES, DEFAULT_VIEWER_PROFILE, LOCALE_CATALOG, PowerPointViewer, SlideCanvas, THEME_CATALOG, Toolbar, VIEWER_PREFS_STORAGE_KEY, ViewerThemeProvider, clearAllLocalViewerData, clearStoredViewerPrefs, defaultCssVars, defaultRadius, defaultThemeColors, getAnimationInitialStyle, getLocalStorageUsageSummary, readStoredViewerPrefs, renderToCanvas, resolveProfileInitial, resolveThemeCatalogEntry, saveViewerProfile, themeToCssVars, useViewerBuildingBlocks, useViewerTheme, vermilionDarkColors, vermilionDarkTheme, vermilionLightColors, vermilionLightTheme, vermilionRadius, writeStoredViewerPrefs };
-export type { AccountAuthConfig, LocalStorageUsageSummary, LocaleCatalogEntry, PowerPointViewerAPI, PowerPointViewerHandle, PowerPointViewerProps, SlideCanvasProps, StoredViewerPrefs, ThemeCatalogEntry, ToolbarActionId, ToolbarButtonId, ToolbarProps, ToolbarTabId, UseViewerBuildingBlocksInput, ViewerBuildingBlocksResult, ViewerMode, ViewerProfile, ViewerTheme, ViewerThemeColors };
+export type { AccountAuthConfig, LocalStorageUsageSummary, LocaleCatalogEntry, PowerPointViewerAPI, PowerPointViewerHandle, PowerPointViewerProps, PptxAiBridge, PptxAiConfig, PptxAiConnection, PptxAiContextStrategy, PptxAiToolName, PptxAiWritePolicy, SlideCanvasProps, StoredViewerPrefs, ThemeCatalogEntry, ToolbarActionId, ToolbarButtonId, ToolbarProps, ToolbarTabId, UseViewerBuildingBlocksInput, ViewerBuildingBlocksResult, ViewerMode, ViewerProfile, ViewerTheme, ViewerThemeColors };