pptx-react-viewer 1.25.5 → 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.
@@ -1023,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). */
@@ -1795,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`. */
@@ -1914,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.
@@ -2247,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[];
@@ -2468,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`.
@@ -2659,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.
    *
@@ -3679,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
@@ -3807,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.
@@ -4030,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;
 }
 /**
@@ -4601,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
@@ -4617,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
 /**
@@ -4827,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;
   /**
@@ -5025,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
@@ -5078,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.
@@ -5104,6 +5582,174 @@ interface PptxCompatibilityWarning {
   elementId?: string;
   xmlPath?: string;
 }
+/**
+ * A single name–value tag from `ppt/tags/*.xml`.
+ *
+ * @example
+ * ```ts
+ * const tag: PptxTag = { name: "CUSTOM_ID", value: "12345" };
+ * // => satisfies PptxTag
+ * ```
+ */
+interface PptxTag {
+  name: string;
+  value: string;
+}
+/**
+ * A collection of tags from a single tags XML part.
+ *
+ * @example
+ * ```ts
+ * const coll: PptxTagCollection = {
+ *   path: "ppt/tags/tag1.xml",
+ *   tags: [{ name: "CUSTOM_ID", value: "12345" }],
+ * };
+ * // => satisfies PptxTagCollection
+ * ```
+ */
+interface PptxTagCollection {
+  /** File path within the PPTX archive. */
+  path?: string;
+  /** Package owner of the tags relationship. New collections default to presentation. */
+  owner?: 'presentation' | 'slide' | 'part';
+  /** Source OPC part that owns the relationship, e.g. ppt/slides/slide1.xml. */
+  sourcePartPath?: string;
+  /** Durable relationship identifier from the owning part. */
+  relationshipId?: string;
+  /** Tags in this collection. */
+  tags: PptxTag[];
+  /** Parsed tag-list XML retained for unknown-node preservation. */
+  rawXml?: XmlObject;
+}
+/**
+ * A custom document property from `docProps/custom.xml`.
+ *
+ * @example
+ * ```ts
+ * const prop: PptxCustomProperty = {
+ *   name: "Project",
+ *   value: "pptx",
+ *   type: "lpwstr",
+ * };
+ * // => satisfies PptxCustomProperty
+ * ```
+ */
+interface PptxCustomProperty {
+  /** Property name. */
+  name: string;
+  /** Property value (always stringified). */
+  value: string;
+  /** Original VT type (e.g. "lpwstr", "i4", "bool", "filetime"). */
+  type: string;
+}
+/**
+ * Core document properties from `docProps/core.xml` (Dublin Core + OOXML).
+ *
+ * @example
+ * ```ts
+ * const core: PptxCoreProperties = {
+ *   title: "Q4 Business Review",
+ *   creator: "Alice",
+ *   created: "2024-01-15T08:00:00Z",
+ *   modified: "2024-06-01T12:30:00Z",
+ *   lastModifiedBy: "Bob",
+ * };
+ * // => satisfies PptxCoreProperties
+ * ```
+ */
+interface PptxCoreProperties {
+  /** dc:title */
+  title?: string;
+  /** dc:subject */
+  subject?: string;
+  /** dc:creator */
+  creator?: string;
+  /** cp:keywords */
+  keywords?: string;
+  /** dc:description */
+  description?: string;
+  /** cp:lastModifiedBy */
+  lastModifiedBy?: string;
+  /** cp:revision */
+  revision?: string;
+  /** dcterms:created (ISO 8601) */
+  created?: string;
+  /** dcterms:modified (ISO 8601) */
+  modified?: string;
+  /** cp:category */
+  category?: string;
+  /** cp:contentStatus */
+  contentStatus?: string;
+}
+/**
+ * Extended (application) properties from `docProps/app.xml`.
+ *
+ * @example
+ * ```ts
+ * const app: PptxAppProperties = {
+ *   application: "Microsoft Office PowerPoint",
+ *   appVersion: "16.0000",
+ *   slides: 24,
+ *   words: 1500,
+ *   company: "Acme Corp",
+ * };
+ * // => satisfies PptxAppProperties
+ * ```
+ */
+interface PptxAppProperties {
+  /** Application name (e.g. "Microsoft Office PowerPoint"). */
+  application?: string;
+  /** Application version string. */
+  appVersion?: string;
+  /** Presentation format (e.g. "On-screen Show (16:9)"). */
+  presentationFormat?: string;
+  /** Total number of slides. */
+  slides?: number;
+  /** Number of hidden slides. */
+  hiddenSlides?: number;
+  /** Number of notes slides. */
+  notes?: number;
+  /** Total editing time in minutes. */
+  totalTime?: number;
+  /** Number of words. */
+  words?: number;
+  /** Number of paragraphs. */
+  paragraphs?: number;
+  /** Company name. */
+  company?: string;
+  /** Manager name. */
+  manager?: string;
+  /** Template name. */
+  template?: string;
+  /** Hyperlink base URL. */
+  hyperlinkBase?: string;
+  /** Document security bitmask (`<DocSecurity>`). */
+  docSecurity?: number;
+  /** Number of multimedia clips (`<MMClips>`). */
+  mmClips?: number;
+  /** Whether thumbnail images were scaled to fit (`<ScaleCrop>`). */
+  scaleCrop?: boolean;
+  /** Whether hyperlinks are current (`<LinksUpToDate>`). */
+  linksUpToDate?: boolean;
+  /** Whether the document is shared (`<SharedDoc>`). */
+  sharedDoc?: boolean;
+  /** Whether hyperlinks changed since last save (`<HyperlinksChanged>`). */
+  hyperlinksChanged?: boolean;
+}
+//#endregion
+//#region 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.
  *
@@ -5437,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`.
@@ -5474,8 +6239,23 @@ interface PptxActiveXControl {
   name?: string;
   /** Shape ID this control is linked to (from @spid). */
   shapeId?: string;
-  /** Raw XML for round-trip preservation. */
-  rawXml?: XmlObject;
+  /** X position (px) of the control's fallback picture, if present. */
+  x?: number;
+  /** Y position (px) of the control's fallback picture, if present. */
+  y?: number;
+  /** Width (px) of the control's fallback picture, if present. */
+  width?: number;
+  /** Height (px) of the control's fallback picture, if present. */
+  height?: number;
+  /**
+   * Relationship ID of the control's static fallback picture
+   * (`mc:AlternateContent > mc:Fallback > p:pic > p:blipFill > a:blip@r:embed`).
+   * Renderers resolve this to an image so a control shows its last static
+   * frame instead of a blank area (the live ActiveX cannot run in a viewer).
+   */
+  fallbackImageRelId?: string;
+  /** Raw XML for round-trip preservation. */
+  rawXml?: XmlObject;
 }
 /**
  * Pattern fill on a slide background.
@@ -5600,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. */
@@ -5622,30 +6409,1764 @@ interface PptxSlideSyncProperties {
   relationshipId?: string;
 }
 /**
- * A named custom slide show (`p:custShowLst / p:custShow`).
- *
- * Custom shows define ordered subsets of slides that can be presented
- * independently of the full deck.
+ * 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`).
+ *
+ * Custom shows define ordered subsets of slides that can be presented
+ * independently of the full deck.
+ *
+ * @example
+ * ```ts
+ * const show: PptxCustomShow = {
+ *   name: "Executive Summary",
+ *   id: "0",
+ *   slideRIds: ["rId2", "rId5", "rId8"],
+ * };
+ * // => satisfies PptxCustomShow
+ * ```
+ */
+interface PptxCustomShow {
+  /** Custom show name. */
+  name: string;
+  /** Custom show id. */
+  id: string;
+  /** Ordered list of slide relationship IDs included in this custom show. */
+  slideRIds: string[];
+  /** Original `p:custShow` subtree used to preserve unmodelled attributes and extensions. */
+  rawXml?: XmlObject;
+}
+/**
+ * An ordered section in the presentation (from `p:sectionLst` / `p14:sectionLst`).
+ *
+ * Sections group consecutive slides under a named heading (visible
+ * in the PowerPoint slide sorter).
+ *
+ * @example
+ * ```ts
+ * const section: PptxSection = {
+ *   id: "sec_1",
+ *   name: "Introduction",
+ *   slideIds: ["256", "257"],
+ * };
+ * // => satisfies PptxSection
+ * ```
+ */
+interface PptxSection {
+  /** Section unique identifier (GUID or synthetic). */
+  id: string;
+  /** Human-readable section name. */
+  name: string;
+  /** Ordered list of numeric slide IDs that belong to this section. */
+  slideIds: string[];
+  /** Whether the section is collapsed in the slide sorter (from p15:sectionPr). */
+  collapsed?: boolean;
+  /** Section highlight color hex (from p15:sectionPr/@clr). */
+  color?: string;
+  /** Original section subtree used to preserve unmodelled attributes and extensions. */
+  rawXml?: XmlObject;
+}
+/**
+ * Write-protection hash data parsed from `p:modifyVerifier` in `presentation.xml`.
+ *
+ * When present, the presentation is marked as "read-only recommended" or
+ * write-protected with a password hash.  The hash parameters follow the
+ * ECMA-376 Part 1, section 19.2.1.22 specification.
+ *
+ * @example
+ * ```ts
+ * const verifier: PptxModifyVerifier = {
+ *   algorithmName: "SHA-512",
+ *   hashData: "base64EncodedHash==",
+ *   saltData: "base64EncodedSalt==",
+ *   spinValue: 100000,
+ * };
+ * // => satisfies PptxModifyVerifier
+ * ```
+ */
+interface PptxModifyVerifier {
+  /** Hash algorithm name (e.g. "SHA-512", "SHA-1"). */
+  algorithmName?: string;
+  /** Base64-encoded hash value. */
+  hashData?: string;
+  /** Base64-encoded salt value. */
+  saltData?: string;
+  /** Number of hash iterations (spin count). */
+  spinValue?: number;
+  /** Legacy algorithm ID extension. */
+  algIdExt?: string;
+  /** Legacy algorithm ID. */
+  cryptAlgorithmSid?: number;
+  /** Cryptographic algorithm type (e.g. "typeAny"). */
+  cryptAlgorithmType?: string;
+  /** Cryptographic provider name. */
+  cryptProvider?: string;
+  /** Cryptographic provider type (e.g. "providerTypeRsaFull"). */
+  cryptProviderType?: string;
+  /** Cryptographic algorithm class (e.g. "hash"). */
+  cryptAlgorithmClass?: string;
+}
+/**
+ * Photo album metadata from `p:photoAlbum` in `presentation.xml`.
+ *
+ * Stores settings for presentations created via Insert > Photo Album.
+ *
+ * @see ECMA-376 Part 1, §19.2.1.27
+ */
+interface PptxPhotoAlbum {
+  /** Whether photos are displayed in black-and-white. */
+  bw?: boolean;
+  /** Whether captions are shown below each photo. */
+  showCaptions?: boolean;
+  /** Photo album layout (e.g. "1pic", "2pic", "4pic", "fitToSlide"). */
+  layout?: string;
+  /** Frame style applied to each photo (e.g. "frameStyle1"). */
+  frame?: string;
+}
+/**
+ * East Asian line-break (kinsoku) settings from `p:kinsoku` in `presentation.xml`.
+ *
+ * Defines forbidden start/end characters for a given language so that
+ * line-breaking follows East Asian typographic rules.
+ *
+ * @see ECMA-376 Part 1, §19.2.1.17
+ */
+interface PptxKinsoku {
+  /** Language code (e.g. "ja-JP", "zh-CN"). */
+  lang?: string | null;
+  /** Characters that cannot begin a line. */
+  invalStChars?: string;
+  /** Characters that cannot end a line. */
+  invalEndChars?: string;
+  /** Original leaf retained for unknown attribute preservation. */
+  rawXml?: XmlObject;
+}
+/**
+ * Root data structure returned by {@link PptxHandlerCore.load}.
+ *
+ * Contains every slide, canvas dimensions, theme data, layout options,
+ * metadata, and optional features (custom shows, sections, macros,
+ * digital signatures, embedded fonts).
+ *
+ * @example
+ * ```ts
+ * const data: PptxData = await handler.load(buffer);
+ * console.log(`${data.slides.length} slides, ${data.width}×${data.height}`);
+ * // => e.g. "24 slides, 960×540"
+ * ```
+ */
+interface PptxData {
+  slides: PptxSlide[];
+  width: number;
+  height: number;
+  /** Slide width in EMU (for save round-trip). */
+  widthEmu?: number;
+  /** Slide height in EMU (for save round-trip). */
+  heightEmu?: number;
+  /** Slide size type from `p:sldSz/@type` (e.g. "screen4x3", "screen16x9", "custom"). */
+  slideSizeType?: string;
+  /** Notes page width in EMU (from `p:notesSz`). */
+  notesWidthEmu?: number;
+  /** Notes page height in EMU (from `p:notesSz`). */
+  notesHeightEmu?: number;
+  layoutOptions?: PptxLayoutOption[];
+  headerFooter?: PptxHeaderFooter;
+  /** Presentation-level properties parsed from `presentationPr.xml`. */
+  presentationProperties?: PptxPresentationProperties;
+  /** Named custom slide shows from `p:custShowLst`. */
+  customShows?: PptxCustomShow[];
+  /** Ordered presentation sections from `p:sectionLst` / `p14:sectionLst`. */
+  sections?: PptxSection[];
+  warnings?: PptxCompatibilityWarning[];
+  /** Map of theme colour scheme keys to resolved hex values. */
+  themeColorMap?: Record<string, string>;
+  /** Full parsed theme object with colours, fonts, and name. */
+  theme?: PptxTheme;
+  /** Available theme parts discovered in `ppt/theme/`. */
+  themeOptions?: PptxThemeOption[];
+  /** Parsed table style definitions from `ppt/tableStyles.xml`. */
+  tableStyleMap?: ParsedTableStyleMap;
+  /** 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[];
+  /**
+   * OOXML conformance class of the loaded file.
+   * - `'strict'` -- ISO/IEC 29500 Strict (uses `purl.oclc.org` namespace URIs)
+   * - `'transitional'` -- ECMA-376 Transitional (uses `schemas.openxmlformats.org` URIs)
+   *
+   * When saving, if the save option `conformance` is `'preserve'` (default),
+   * the file will be saved using the same conformance class as the original.
+   */
+  conformance?: 'strict' | 'transitional';
+}
+/**
+ * Target format for slide export.
+ *
+ * @see {@link PptxExportOptions}
+ */
+type PptxExportFormat = 'pdf' | 'png' | 'svg';
+/**
+ * Options controlling slide export to raster or vector formats.
+ *
+ * @example
+ * ```ts
+ * const opts: PptxExportOptions = {
+ *   format: "png",
+ *   slideIndices: [0, 2, 4],
+ *   dpi: 300,
+ * };
+ * // => satisfies PptxExportOptions
+ * ```
+ */
+interface PptxExportOptions {
+  /** Target format. */
+  format: PptxExportFormat;
+  /** Slide indices to export (0-based). If omitted, all slides are exported. */
+  slideIndices?: number[];
+  /** Output width in pixels (for PNG). Height is derived from aspect ratio. */
+  width?: number;
+  /** DPI for raster export (default 150). */
+  dpi?: number;
+  /** Whether to include hidden slides. */
+  includeHidden?: boolean;
+}
+/**
+ * Embedded font data extracted from a PPTX file.
+ *
+ * Used to register `@font-face` rules so the renderer can display
+ * the correct typeface even when the system font is missing.
+ *
+ * @example
+ * ```ts
+ * const font: PptxEmbeddedFont = {
+ *   name: "CustomSans",
+ *   dataUrl: "data:font/truetype;base64,AAEAK...",
+ *   format: "truetype",
+ * };
+ * // => satisfies PptxEmbeddedFont
+ * ```
+ */
+/**
+ * A single Custom XML Data Part stored in `customXml/` within the OPC package.
+ *
+ * These parts are used by add-ins, data-binding, and enterprise templates
+ * to store structured data alongside the presentation.
+ *
+ * @see ECMA-376 Part 1, §15.2.5
+ */
+interface PptxCustomXmlPart {
+  /** Item number (e.g. "1" for `customXml/item1.xml`). */
+  id: string;
+  /** Raw XML string content of the custom XML item. */
+  data: string;
+  /** Schema target namespace URI from `itemProps` (ds:schemaRef/@ds:uri). */
+  schemaUri?: string;
+  /** Raw XML string content of the associated `itemProps` file. */
+  properties?: string;
+  /** Raw XML string content of the OPC relationship file (`customXml/_rels/item{id}.xml.rels`). */
+  rels?: string;
+}
+interface PptxEmbeddedFont {
+  name: string;
+  dataUrl: string;
+  bold?: boolean;
+  italic?: boolean;
+  /** CSS font format hint (e.g. "truetype", "opentype"). */
+  format?: 'truetype' | 'opentype' | 'woff' | 'woff2';
+  /**
+   * Deobfuscated (clear-text) font binary data preserved from load
+   * for round-trip re-embedding on save. When present, the save
+   * pipeline will re-obfuscate and write this data back into the ZIP.
+   */
+  rawFontData?: Uint8Array;
+  /**
+   * Original ZIP path of the font part (e.g. `ppt/fonts/{GUID}.fntdata`).
+   * Preserved from load for round-trip.
+   */
+  partPath?: string;
+  /**
+   * The GUID used for obfuscation, either from the `fontKey` attribute
+   * or extracted from the part path. Preserved from load for round-trip.
+   */
+  fontGuid?: string;
+  /**
+   * Relationship ID (e.g. `rId21`) of the font part in
+   * `ppt/_rels/presentation.xml.rels`. Preserved from load so the save
+   * pipeline can reuse the original part/rel instead of minting a new
+   * GUID-named copy alongside the stale original.
+   */
+  originalRId?: string;
+  /**
+   * Raw bytes of the original obfuscated font part exactly as they were
+   * stored in the source ZIP. When the loader could not determine a
+   * usable GUID (e.g. EOT extraction path), the save pipeline preserves
+   * these bytes verbatim under the original path/rel.
+   */
+  originalPartBytes?: Uint8Array;
+}
+
+//#endregion
+//#region 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.
  *
- * @example
- * ```ts
- * const show: PptxCustomShow = {
- *   name: "Executive Summary",
- *   id: "0",
- *   slideRIds: ["rId2", "rId5", "rId8"],
- * };
- * // => satisfies PptxCustomShow
- * ```
+ * The implementation lives in `PptxHandlerCore` so this surface can stay small,
+ * stable, and easy to replace with alternate implementations in the future.
  */
-interface PptxCustomShow {
-  /** Custom show name. */
-  name: string;
-  /** Custom show id. */
-  id: string;
-  /** Ordered list of slide relationship IDs included in this custom show. */
-  slideRIds: string[];
-  /** Original `p:custShow` subtree used to preserve unmodelled attributes and extensions. */
-  rawXml?: XmlObject;
+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
@@ -5962,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';
@@ -6241,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.
@@ -6295,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.
@@ -6495,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;
   /**
@@ -6520,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;
@@ -6828,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. */
@@ -6878,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
 /**
@@ -6919,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 };