pptx-react-viewer 1.17.1 → 1.19.0

package/dist/hooks-unstable.d.ts

@@ -359,6 +359,8 @@ interface CustomGeometryPath {
  * and the text rectangle are not lost when a custGeom is edited and saved.
  */
 interface CustomGeometryRawData {
+    /** Raw `a:avLst` XML content (adjustment value list). */
+    avLstXml?: unknown;
     /** Raw `a:gdLst` XML content (guide list). */
     gdLstXml?: unknown;
     /** Raw `a:ahLst` XML content (adjustment handles). */
@@ -499,7 +501,7 @@ interface PptxCustomPathProperties {
     pathHeight?: number;
     /** Structured custom geometry paths for editing (maps to a:custGeom/a:pathLst). */
     customGeometryPaths?: CustomGeometryPath[];
-    /** Raw a:gdLst/a:ahLst/a:cxnLst/a:rect XML preserved for round-trip serialization. */
+    /** Raw adjustment/guide/handle/connection/text-rectangle XML preserved for serialization. */
     customGeometryRawData?: CustomGeometryRawData;
     /**
      * Typed XY adjustment handles parsed from `a:custGeom/a:ahLst/a:ahXY`.
@@ -599,6 +601,10 @@ interface Text3DStyle {
 interface Pptx3DScene {
     /** Camera preset type, e.g. "orthographicFront", "perspectiveFront". */
     cameraPreset?: string;
+    /** Camera field of view in 1/60000 degrees (`a:camera/@fov`). */
+    cameraFieldOfView?: number;
+    /** Camera zoom as an OOXML percentage fraction (`a:camera/@zoom`, 1 = 100%). */
+    cameraZoom?: number;
     /** Camera rotation around X axis in 1/60000 degrees. */
     cameraRotX?: number;
     /** Camera rotation around Y axis in 1/60000 degrees. */
@@ -609,6 +615,12 @@ interface Pptx3DScene {
     lightRigType?: string;
     /** Light rig direction, e.g. "t", "b", "l", "r", "tl". */
     lightRigDirection?: string;
+    /** Light-rig rotation latitude in 1/60000 degrees. */
+    lightRigRotX?: number;
+    /** Light-rig rotation longitude in 1/60000 degrees. */
+    lightRigRotY?: number;
+    /** Light-rig rotation revolution in 1/60000 degrees. */
+    lightRigRotZ?: number;
     /** Whether a 3D backdrop plane is present (`a:backdrop`). */
     hasBackdrop?: boolean;
     /** Backdrop plane anchor X in EMU. */
@@ -617,6 +629,18 @@ interface Pptx3DScene {
     backdropAnchorY?: number;
     /** Backdrop plane anchor Z in EMU. */
     backdropAnchorZ?: number;
+    /** Backdrop normal vector X component. */
+    backdropNormalX?: number;
+    /** Backdrop normal vector Y component. */
+    backdropNormalY?: number;
+    /** Backdrop normal vector Z component. */
+    backdropNormalZ?: number;
+    /** Backdrop up vector X component. */
+    backdropUpX?: number;
+    /** Backdrop up vector Y component. */
+    backdropUpY?: number;
+    /** Backdrop up vector Z component. */
+    backdropUpZ?: number;
 }
 /**
  * 3D shape extrusion/bevel from `a:sp3d`.
@@ -688,6 +712,12 @@ type PptxTextWarpPreset = 'textNoShape' | 'textPlain' | 'textStop' | 'textTriang
  * @module pptx-types/shape-style
  */
 
+interface PptxCustomDashSegment {
+    /** Dash length as a non-negative percentage in thousandths of one percent. */
+    dash: number;
+    /** Space length as a non-negative percentage in thousandths of one percent. */
+    space: number;
+}
 /**
  * Comprehensive visual style for a shape, connector, or image element.
  *
@@ -736,9 +766,13 @@ interface ShapeStyle {
      */
     fillColorXml?: XmlObject;
     fillGradient?: string;
+    /** Original `gradFill` XML retained for unknown-child and extension round-tripping. */
+    fillGradientXml?: XmlObject;
     fillMode?: 'solid' | 'gradient' | 'pattern' | 'none' | 'image' | 'theme' | 'group';
     fillPatternPreset?: string;
     fillPatternBackgroundColor?: string;
+    /** Original `pattFill` XML retained for unknown-child round-tripping. */
+    fillPatternXml?: XmlObject;
     /** Raw XML node for pattern fill foreground colour (preserves color transforms). */
     fillPatternFgClrXml?: XmlObject;
     /** Raw XML node for pattern fill background colour (preserves color transforms). */
@@ -804,6 +838,14 @@ interface ShapeStyle {
     /** Pen line alignment (`a:ln/@algn`): `ctr` (centre, default) or `in` (inside). */
     lineAlignment?: 'ctr' | 'in';
     shadowColor?: string;
+    /** Preserved source `a:effectLst`, including unknown effects and extensions. */
+    effectListXml?: XmlObject;
+    /** Original outer-shadow node used for lossless surgical updates. */
+    outerShadowXml?: XmlObject;
+    /** Resolved source shadow colour used to detect colour edits. */
+    outerShadowOriginalColor?: string;
+    /** Source shadow opacity used to detect alpha edits. */
+    outerShadowOriginalOpacity?: number;
     shadowBlur?: number;
     shadowOffsetX?: number;
     shadowOffsetY?: number;
@@ -847,11 +889,23 @@ interface ShapeStyle {
     /** Multiple shadow layers (for advanced effects). */
     shadows?: ShadowEffect[];
     glowColor?: string;
+    /** Original glow node used for lossless surgical updates. */
+    glowXml?: XmlObject;
+    /** Resolved source glow colour used to detect colour edits. */
+    glowOriginalColor?: string;
+    /** Source glow opacity used to detect alpha edits. */
+    glowOriginalOpacity?: number;
     glowRadius?: number;
     glowOpacity?: number;
     softEdgeRadius?: number;
     /** Inner shadow colour (`a:innerShdw`). */
     innerShadowColor?: string;
+    /** Original inner-shadow node used for lossless surgical updates. */
+    innerShadowXml?: XmlObject;
+    /** Resolved source inner-shadow colour used to detect colour edits. */
+    innerShadowOriginalColor?: string;
+    /** Source inner-shadow opacity used to detect alpha edits. */
+    innerShadowOriginalOpacity?: number;
     /** Inner shadow opacity (0-1). */
     innerShadowOpacity?: number;
     /** Inner shadow blur radius in px. */
@@ -860,8 +914,12 @@ interface ShapeStyle {
     innerShadowOffsetX?: number;
     /** Inner shadow vertical offset in px. */
     innerShadowOffsetY?: number;
+    /** Original soft-edge node, including vendor attributes and extensions. */
+    softEdgeXml?: XmlObject;
     /** Reflection effect — distance from shape bottom in px. */
     reflectionBlurRadius?: number;
+    /** Original reflection node, including vendor attributes and extensions. */
+    reflectionXml?: XmlObject;
     /** Reflection start opacity (0-1). */
     reflectionStartOpacity?: number;
     /** Reflection end opacity (0-1). */
@@ -892,11 +950,12 @@ interface ShapeStyle {
     connectorStartConnection?: ConnectorConnectionPoint;
     /** Connection point for the end of a connector. */
     connectorEndConnection?: ConnectorConnectionPoint;
-    /** Custom dash segments array (`a:custDash/a:ds`). Each entry has dash length and space length in EMU. */
-    customDashSegments?: Array<{
-        dash: number;
-        space: number;
-    }>;
+    /** Custom dash pattern, measured relative to line width in thousandths of one percent. */
+    customDashSegments?: PptxCustomDashSegment[];
+    /** Original `a:ds` payloads retained by index for lossless edits. */
+    customDashSegmentXml?: XmlObject[];
+    /** Original `a:custDash` payload retained for lossless edits. */
+    customDashXml?: XmlObject;
     /** 3D scene/camera settings from `a:scene3d`. */
     scene3d?: Pptx3DScene;
     /** 3D shape extrusion/bevel from `a:sp3d`. */
@@ -1008,6 +1067,8 @@ interface ShapeStyle {
  * ```
  */
 interface TextStyle {
+    /** Original `a:rPr` XML retained by projections that share the shape-text model. */
+    runPropertiesXml?: XmlObject;
     fontFamily?: string;
     fontSize?: number;
     /** When true, renderer should shrink text to fit the shape bounds. */
@@ -1357,6 +1418,8 @@ interface TextStyle {
     text3d?: Text3DStyle;
     /** 3D scene (camera + light rig) settings on the text body (`a:bodyPr/a:scene3d`). */
     textBodyScene3d?: Pptx3DScene;
+    /** Raw `a:scene3d` subtree used to preserve extensions and unmodelled children. */
+    textBodyScene3dXml?: XmlObject;
     /**
      * Raw `<a:extLst>` subtree captured from `<a:bodyPr>`. Preserved verbatim so
      * authored extensions (e.g. content placeholders, custom application data)
@@ -1733,12 +1796,126 @@ interface PlaceholderTextLevelStyle {
     spaceAfter?: number;
 }
 
+/** Tick-mark placement from ChartML `ST_TickMark`. */
+type PptxChartTickMark = 'cross' | 'in' | 'none' | 'out';
+/** Typed axis tick and category/date label controls. */
+interface PptxChartAxisLabelFormatting {
+    /** Primary and secondary tick-mark placement. */
+    majorTickMark?: PptxChartTickMark;
+    minorTickMark?: PptxChartTickMark;
+    /** Tick-label position from ChartML `ST_TickLblPos`. */
+    tickLblPos?: 'high' | 'low' | 'nextTo' | 'none';
+    /** Automatic category/date axis behavior (`c:auto`). */
+    auto?: boolean;
+    /** Category-axis label alignment (`c:lblAlgn`). */
+    labelAlignment?: 'ctr' | 'l' | 'r';
+    /** Category/date label distance, from 0 through 1000 percent. */
+    labelOffset?: number;
+    /** Number of category/date labels between rendered labels. */
+    tickLabelSkip?: number;
+    /** Number of category/date tick positions between major tick marks. */
+    tickMarkSkip?: number;
+    /** Suppress multi-level category labels (`c:noMultiLvlLbl`). */
+    noMultiLevelLabels?: boolean;
+}
+
+interface PptxChartPivotFormat {
+    index: number;
+    shapePropertiesXml?: XmlObject | null;
+    markerXml?: XmlObject | null;
+    dataLabelXml?: XmlObject | null;
+    extensionListXml?: XmlObject | null;
+    rawXml?: XmlObject;
+}
+/** Editable classic ChartML `c:pivotFmts` collection. */
+interface PptxChartPivotFormats {
+    formats: PptxChartPivotFormat[];
+    rawXml?: XmlObject;
+}
+
+/** Editable classic ChartML `c:pivotSource` metadata. */
+interface PptxChartPivotSource {
+    /** Pivot table reference stored as `c:name` text. */
+    name: string;
+    /** Required unsigned format identifier stored in `c:fmtId/@val`. */
+    formatId: number;
+    /** Internal source subtree used to preserve extensions and foreign markup. */
+    rawXml?: XmlObject;
+}
+
+/** Headers and footers used when a classic ChartML chart is printed. */
+interface PptxChartPrintHeaderFooter {
+    oddHeader?: string;
+    oddFooter?: string;
+    evenHeader?: string;
+    evenFooter?: string;
+    firstHeader?: string;
+    firstFooter?: string;
+    alignWithMargins?: boolean;
+    differentOddEven?: boolean;
+    differentFirst?: boolean;
+    /** Original subtree retained for foreign attributes and extension children. */
+    rawXml?: unknown;
+}
+/** Required page margins from ChartML `c:pageMargins`, measured in inches. */
+interface PptxChartPageMargins {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    header: number;
+    footer: number;
+    /** Original leaf retained for foreign attributes. */
+    rawXml?: unknown;
+}
+/** Printer page configuration from ChartML `c:pageSetup`. */
+interface PptxChartPageSetup {
+    paperSize?: number;
+    firstPageNumber?: number;
+    orientation?: 'default' | 'portrait' | 'landscape';
+    blackAndWhite?: boolean;
+    draft?: boolean;
+    useFirstPageNumber?: boolean;
+    horizontalDpi?: number;
+    verticalDpi?: number;
+    copies?: number;
+    /** Original leaf retained for foreign attributes. */
+    rawXml?: unknown;
+}
+/** Editable `c:printSettings` content from a classic ChartML chart space. */
+interface PptxChartPrintSettings {
+    headerFooter?: PptxChartPrintHeaderFooter | null;
+    pageMargins?: PptxChartPageMargins | null;
+    pageSetup?: PptxChartPageSetup | null;
+    /** `null` removes the legacy header/footer drawing relationship element. */
+    legacyDrawingHeaderFooterRelationshipId?: string | null;
+    /** Original subtree retained for unknown and extension content. */
+    rawXml?: unknown;
+}
+
+/** Editable classic ChartML `c:protection` settings. */
+interface PptxChartProtection {
+    /** Prevent editing the chart object. */
+    chartObject?: boolean | null;
+    /** Prevent editing the chart data. */
+    data?: boolean | null;
+    /** Prevent editing chart formatting. */
+    formatting?: boolean | null;
+    /** Prevent selecting chart elements. */
+    selection?: boolean | null;
+    /** Prevent chart user-interface operations. */
+    userInterface?: boolean | null;
+    /** Internal source subtree used to preserve foreign markup during edits. */
+    rawXml?: XmlObject;
+}
+
 /**
  * Chart types: chart categories, series data, style metadata, data tables,
  * trendlines, error bars, and the composite `PptxChartData`.
  *
  * @module pptx-types/chart
  */
+
 /**
  * Supported chart type discriminators.
  *
@@ -1775,6 +1952,7 @@ type PptxChartTrendlineType = 'linear' | 'exponential' | 'logarithmic' | 'polyno
  */
 interface PptxChartTrendline {
     trendlineType: PptxChartTrendlineType;
+    name?: string;
     order?: number;
     period?: number;
     forward?: number;
@@ -1783,6 +1961,13 @@ interface PptxChartTrendline {
     displayRSq?: boolean;
     displayEq?: boolean;
     color?: string;
+    label?: PptxChartTrendlineLabel | null;
+}
+/** Typed, commonly edited properties of `c:trendlineLbl`. */
+interface PptxChartTrendlineLabel {
+    layout?: PptxChartManualLayout;
+    numberFormatCode?: string;
+    sourceLinked?: boolean;
 }
 /** Error-bar direction axis. */
 type PptxChartErrBarDir = 'x' | 'y';
@@ -1819,6 +2004,8 @@ interface PptxChartErrBars {
     val?: number;
     customPlus?: number[];
     customMinus?: number[];
+    noEndCap?: boolean;
+    color?: string;
 }
 /**
  * Visibility flags for the chart data table (axes + legend keys).
@@ -1868,9 +2055,17 @@ interface PptxChartShapeProps {
     /** Line dash style (a:prstDash/@val), e.g. 'solid', 'dash', 'dot', 'lgDash'. */
     strokeDashStyle?: string;
 }
+/** Up/down bar formatting on line and stock charts (`c:upDownBars`). */
+interface PptxChartUpDownBars {
+    /** Gap between bars as a percentage, constrained to 0 through 500. */
+    gapWidth?: number;
+    upBars?: PptxChartShapeProps;
+    downBars?: PptxChartShapeProps;
+}
 /** Marker appearance on a chart series or data point. */
 interface PptxChartMarker {
     symbol: PptxChartMarkerSymbol;
+    /** Marker size in points, constrained by ST_MarkerSize to 2 through 72. */
     size?: number;
     spPr?: PptxChartShapeProps;
 }
@@ -1881,26 +2076,43 @@ interface PptxChartDataPoint {
     explosion?: number;
     invertIfNegative?: boolean;
     marker?: PptxChartMarker;
+    /** Render a bubble-chart point with a 3-D appearance. */
+    bubble3D?: boolean;
 }
+/** Schema values accepted by `c:dLblPos`. */
+type PptxChartDataLabelPosition = 'bestFit' | 'b' | 'ctr' | 'inBase' | 'inEnd' | 'l' | 'outEnd' | 'r' | 't';
 /** Individual data label override (c:dLbl). */
 interface PptxChartDataLabel {
     idx: number;
+    /** Suppress this data point's automatically generated label. */
+    deleted?: boolean;
     showVal?: boolean;
     showCatName?: boolean;
     showSerName?: boolean;
     showPercent?: boolean;
     showLegendKey?: boolean;
     showBubbleSize?: boolean;
-    position?: string;
+    position?: PptxChartDataLabelPosition;
     text?: string;
+    separator?: string;
+    showLeaderLines?: boolean;
 }
 /** Axis number format. */
 interface PptxChartAxisNumFmt {
     formatCode: string;
     sourceLinked?: boolean;
 }
+/** Typed contents of a value-axis display-unit label (`c:dispUnitsLbl`). */
+interface PptxChartDisplayUnitsLabel {
+    /** Literal label text. Omit to preserve the source text subtree. */
+    text?: string;
+    /** Manual label placement. `null` removes only the manual layout. */
+    layout?: PptxChartManualLayout | null;
+    /** Label shape formatting. `null` removes `c:spPr`. */
+    spPr?: PptxChartShapeProps | null;
+}
 /** Axis formatting for category, value, or date axes. */
-interface PptxChartAxisFormatting {
+interface PptxChartAxisFormatting extends PptxChartAxisLabelFormatting {
     axisType: 'catAx' | 'valAx' | 'dateAx' | 'serAx';
     /** Axis position: "b" (bottom), "l" (left), "r" (right), "t" (top). */
     axPos?: 'b' | 'l' | 'r' | 't';
@@ -1908,6 +2120,12 @@ interface PptxChartAxisFormatting {
     axisId?: number;
     /** Cross-axis identifier — the axis this axis crosses. */
     crossAxisId?: number;
+    /** Automatic crossing mode (`c:crosses`). Mutually exclusive with `crossesAt`. */
+    crosses?: 'autoZero' | 'min' | 'max';
+    /** Explicit crossing value (`c:crossesAt`). Units depend on the axis type. */
+    crossesAt?: number;
+    /** Whether a value axis crosses between or at category tick marks. */
+    crossBetween?: 'between' | 'midCat';
     numFmt?: PptxChartAxisNumFmt;
     titleText?: string;
     spPr?: PptxChartShapeProps;
@@ -1925,6 +2143,8 @@ interface PptxChartAxisFormatting {
     min?: number;
     /** Maximum axis value override (c:max/@val). */
     max?: number;
+    /** Axis value direction (`c:scaling/c:orientation/@val`). */
+    orientation?: 'minMax' | 'maxMin';
     /** Whether the axis is deleted/hidden (c:delete/@val). */
     deleted?: boolean;
     /**
@@ -1934,8 +2154,12 @@ interface PptxChartAxisFormatting {
     displayUnits?: 'hundreds' | 'thousands' | 'tenThousands' | 'hundredThousands' | 'millions' | 'tenMillions' | 'hundredMillions' | 'billions' | 'trillions' | 'custom';
     /** Custom display unit divisor value (c:dispUnits/c:custUnit/@val). Only used when displayUnits is 'custom'. */
     displayUnitsValue?: number;
-    /** Display units label text (c:dispUnits/c:dispUnitsLbl). Overrides the built-in default label when present. */
-    displayUnitsLabel?: string;
+    /**
+     * Display-unit label contents (`c:dispUnits/c:dispUnitsLbl`). A string is
+     * retained as a compatibility shorthand for `{ text: string }`; `null`
+     * explicitly removes the label.
+     */
+    displayUnitsLabel?: string | PptxChartDisplayUnitsLabel | null;
     /** Whether logarithmic scaling is enabled (presence of c:scaling/c:logBase). */
     logScale?: boolean;
     /** Logarithmic base value (c:scaling/c:logBase/@val), typically 10 or e. */
@@ -1944,14 +2168,69 @@ interface PptxChartAxisFormatting {
     majorUnit?: number;
     /** Minor-unit interval between secondary tick marks (c:minorUnit/@val). */
     minorUnit?: number;
-    /** Tick-label position (c:tickLblPos/@val): 'high', 'low', 'nextTo', or 'none'. */
-    tickLblPos?: 'high' | 'low' | 'nextTo' | 'none';
+    /** Calendar unit used to interpret date-axis serial values. */
+    baseTimeUnit?: 'days' | 'months' | 'years';
+    majorTimeUnit?: 'days' | 'months' | 'years';
+    minorTimeUnit?: 'days' | 'months' | 'years';
 }
 /** 3D wall or floor element formatting. */
 interface PptxChart3DSurface {
     thickness?: number;
     spPr?: PptxChartShapeProps;
 }
+/** Office 2016 ChartEx box-and-whisker series layout options. */
+interface PptxChartBoxWhiskerOptions {
+    quartileMethod?: 'inclusive' | 'exclusive';
+    showMeanLine?: boolean;
+    showMeanMarker?: boolean;
+    /** Show non-outlier (inner) data points. */
+    showInnerPoints?: boolean;
+    showOutlierPoints?: boolean;
+}
+/** Office 2016 ChartEx histogram and Pareto series layout options. */
+interface PptxChartHistogramOptions {
+    /** Maps to `clusteredColumn` for histogram columns or `paretoLine`. */
+    layout?: 'histogram' | 'pareto';
+    /** Exactly one of binSize and binCount is emitted by the ChartEx writer. */
+    binSize?: number;
+    binCount?: number;
+    intervalClosed?: 'l' | 'r';
+    underflow?: number | 'auto';
+    overflow?: number | 'auto';
+}
+/** Office 2016 ChartEx waterfall series layout options. */
+interface PptxChartWaterfallOptions {
+    /** Zero-based data point indexes rendered as absolute subtotal or total bars. */
+    subtotalIndices?: number[];
+    /** Whether connector lines are visible between adjacent bars. */
+    connectorLines?: boolean;
+}
+/** Office 2016 ChartEx geographic series dimensions and layout options. */
+interface PptxChartRegionMapOptions {
+    /** Optional provider entity identifiers aligned with categories and values. */
+    entityIds?: string[];
+    /** Original `cx:pt/@idx` values for category points. */
+    categorySourceIndices?: number[];
+    /** Original `cx:pt/@idx` values for colour-value points. */
+    valueSourceIndices?: number[];
+    /** Original `cx:pt/@idx` values for entity-ID points. */
+    entityIdSourceIndices?: number[];
+    regionLabelLayout?: 'none' | 'bestFitOnly' | 'showAll';
+    projectionType?: 'mercator' | 'miller' | 'robinson' | 'albers';
+    viewedRegionType?: 'dataOnly' | 'postalCode' | 'county' | 'state' | 'countryRegion' | 'countryRegionList' | 'world';
+    cultureLanguage?: string;
+    /** ISO-3166-1 alpha-2 region code. */
+    cultureRegion?: string;
+    attribution?: string;
+    /** Opaque authored provider cache under `cx:geography/cx:geoCache`. */
+    geographyCache?: XmlObject;
+}
+/** Layout for parent category labels in a hierarchical ChartEx treemap. */
+type PptxChartParentLabelLayout = 'none' | 'banner' | 'overlapping';
+/** Per-series layout options for an Office 2016+ ChartEx treemap. */
+interface PptxChartTreemapOptions {
+    parentLabelLayout?: PptxChartParentLabelLayout;
+}
 /**
  * A single data series within a chart.
  *
@@ -1987,6 +2266,11 @@ interface PptxChartSeries {
      * series.
      */
     seriesChartType?: PptxChartType;
+    boxWhiskerOptions?: PptxChartBoxWhiskerOptions;
+    histogramOptions?: PptxChartHistogramOptions;
+    waterfallOptions?: PptxChartWaterfallOptions;
+    regionMapOptions?: PptxChartRegionMapOptions;
+    treemapOptions?: PptxChartTreemapOptions;
 }
 /**
  * Chart-level data-label options (`c:dLbls` directly under a chart-type
@@ -2004,12 +2288,32 @@ interface PptxChartDataLabelOptions {
     showPercent?: boolean;
     /** Show the legend key swatch (`c:showLegendKey`). */
     showLegendKey?: boolean;
+    /** Show bubble size (`c:showBubbleSize`). */
+    showBubbleSize?: boolean;
+    /** Text placed between combined label components (`c:separator`). */
+    separator?: string;
+    /** Show leader lines where supported (`c:showLeaderLines`). */
+    showLeaderLines?: boolean;
     /**
      * Label position (`c:dLblPos`). Valid values depend on the chart type
      * (`ctr`, `inEnd`, `inBase`, `outEnd`, `bestFit`, `l`, `r`, `t`, `b`).
      * Omit to let PowerPoint use the type default.
      */
-    position?: 'ctr' | 'inEnd' | 'inBase' | 'outEnd' | 'bestFit' | 'l' | 'r' | 't' | 'b';
+    position?: PptxChartDataLabelPosition;
+}
+/** Typed text defaults for a single chart legend entry. */
+interface PptxChartLegendTextStyle {
+    fontFamily?: string;
+    fontSize?: number;
+    bold?: boolean;
+    italic?: boolean;
+    color?: string;
+}
+/** Per-series legend entry override (`c:legendEntry`). */
+interface PptxChartLegendEntry {
+    index: number;
+    deleted?: boolean;
+    textStyle?: PptxChartLegendTextStyle;
 }
 /**
  * Style / formatting metadata for a chart.
@@ -2032,6 +2336,8 @@ interface PptxChartStyle {
     hasLegend?: boolean;
     /** Legend position (t, b, l, r, tr). */
     legendPosition?: string;
+    /** Per-series visibility and text-style overrides. */
+    legendEntries?: PptxChartLegendEntry[];
     /** Whether the chart has a title. */
     hasTitle?: boolean;
     /** Whether gridlines are visible. */
@@ -2092,6 +2398,14 @@ interface PptxChartOfPieOptions {
     serLines?: boolean;
     gapWidth?: number;
 }
+/** Classic `c:bubbleChart` options from CT_BubbleChart. */
+interface PptxBubbleChartOptions {
+    bubble3D?: boolean;
+    /** Bubble diameter scale in percent, constrained to 0 through 300. */
+    bubbleScale?: number;
+    showNegativeBubbles?: boolean;
+    sizeRepresents?: 'area' | 'w';
+}
 /**
  * 3D viewing parameters for a chart (`c:view3D`, ECMA-376 §21.2.2.228 /
  * CT_View3D).
@@ -2132,6 +2446,27 @@ interface PptxChartChrome {
     dispBlanksAs?: 'gap' | 'zero' | 'span';
     showDLblsOverMax?: boolean;
 }
+/** Manual chart placement from `c:layout/c:manualLayout` (CT_ManualLayout). */
+interface PptxChartManualLayout {
+    layoutTarget?: 'inner' | 'outer';
+    xMode?: 'edge' | 'factor';
+    yMode?: 'edge' | 'factor';
+    widthMode?: 'edge' | 'factor';
+    heightMode?: 'edge' | 'factor';
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+/**
+ * Typed manual layouts for chart regions that accept `c:layout`.
+ * A `null` region removes its manual layout without removing extensions.
+ */
+interface PptxChartLayouts {
+    title?: PptxChartManualLayout | null;
+    plotArea?: PptxChartManualLayout | null;
+    legend?: PptxChartManualLayout | null;
+}
 /** Parsed data extracted from an embedded xlsx workbook. */
 interface PptxEmbeddedWorkbookData {
     /** Category labels from the first column/row. */
@@ -2141,6 +2476,16 @@ interface PptxEmbeddedWorkbookData {
         name: string;
         values: number[];
     }>;
+    /** Whether the workbook uses the 1904 date system. */
+    date1904?: boolean;
+}
+/** Raw numeric category cache used by a classic ChartML date axis. */
+interface PptxChartDateCategories {
+    values: number[];
+    /** False/default uses Excel's 1900 date system; true uses the 1904 system. */
+    date1904?: boolean;
+    /** Number format copied from the numeric category cache. */
+    formatCode?: string;
 }
 /**
  * Complete parsed chart data for a {@link ChartPptxElement}.
@@ -2164,6 +2509,13 @@ interface PptxChartData {
     title?: string;
     chartType: PptxChartType;
     categories: string[];
+    /**
+     * Hierarchical category levels in source XML order for ChartEx hierarchy charts.
+     * Level 0 contains the leaf labels and remains mirrored by {@link categories}
+     * for consumers that only understand a flat category axis.
+     */
+    categoryLevels?: string[][];
+    dateCategories?: PptxChartDateCategories;
     series: PptxChartSeries[];
     /** Chart style/formatting metadata. */
     style?: PptxChartStyle;
@@ -2173,9 +2525,12 @@ interface PptxChartData {
     chartPartPath?: string;
     /** Internal: relationship ID linking the graphic frame to the chart part. */
     chartRelationshipId?: string;
-    dataTable?: PptxChartDataTable;
+    /** `null` explicitly removes an existing ChartML data table. */
+    dataTable?: PptxChartDataTable | null;
     dropLines?: PptxChartLineStyle;
     hiLowLines?: PptxChartLineStyle;
+    /** `null` explicitly removes an existing up/down-bars container. */
+    upDownBars?: PptxChartUpDownBars | null;
     axes?: PptxChartAxisFormatting[];
     floor?: PptxChart3DSurface;
     sideWall?: PptxChart3DSurface;
@@ -2197,12 +2552,7 @@ interface PptxChartData {
      * The chart still renders using its cached series data; this field
      * is metadata about the data origin, preserved for round-trip fidelity.
      */
-    pivotSource?: {
-        /** Pivot table reference name, e.g. "[workbook.xlsx]Sheet1!PivotTable1". */
-        name: string;
-        /** Format identifier from c:fmtId/@val. */
-        formatId?: number;
-    };
+    pivotSource?: PptxChartPivotSource | null;
     /**
      * Whether only visible cells are plotted (c:plotVisOnly).
      * When `true` (the default), hidden cells are excluded from the chart.
@@ -2225,6 +2575,12 @@ interface PptxChartData {
      * - `"acrossLinear"` — gradient across series
      */
     colorMethod?: 'cycle' | 'withinLinear' | 'acrossLinear';
+    /** Internal source color-style part path used for lossless dirty saves. */
+    colorStylePartPath?: string;
+    /** Internal parsed palette snapshot used to detect actual edits. */
+    colorStyleOriginalPalette?: string[];
+    /** Internal parsed method snapshot used to detect actual edits. */
+    colorStyleOriginalMethod?: 'cycle' | 'withinLinear' | 'acrossLinear';
     /**
      * Pie-of-pie / Bar-of-pie options (`c:ofPieChart`, CT_OfPieChart).
      *
@@ -2233,6 +2589,8 @@ interface PptxChartData {
      * `ofPieChart` element can be re-emitted on save with full fidelity.
      */
     ofPieOptions?: PptxChartOfPieOptions;
+    /** Classic bubble-chart display options (`c:bubbleChart`). */
+    bubbleOptions?: PptxBubbleChartOptions;
     /**
      * 3D viewing parameters (`c:view3D`, CT_View3D).
      *
@@ -2248,6 +2606,12 @@ interface PptxChartData {
      * source data, so absence does not produce empty `<c:…/>` placeholders.
      */
     chartChrome?: PptxChartChrome;
+    /** `c:chartSpace/c:printSettings`; `null` removes the container on save. */
+    printSettings?: PptxChartPrintSettings | null;
+    /** `c:chartSpace/c:protection`; `null` removes the container on save. */
+    protection?: PptxChartProtection | null;
+    /** Editable manual placement for the title, plot area, and legend. */
+    layouts?: PptxChartLayouts;
     /**
      * Raw `c:userShapes` XML subtree (a drawing tree) preserved verbatim.
      *
@@ -2264,7 +2628,8 @@ interface PptxChartData {
      * for charts whose data originates from a PivotTable. Preserved
      * verbatim for round-trip fidelity.
      */
-    pivotFmtsXml?: unknown;
+    /** Typed pivot-chart format persistence; `null` removes `c:pivotFmts`. */
+    pivotFormats?: PptxChartPivotFormats | null;
     /**
      * Color-map override (`c:clrMapOvr`) carrying 12 attributes that
      * remap theme colour roles for this chart only. Preserved as a flat
@@ -2273,107 +2638,61 @@ interface PptxChartData {
     clrMapOvr?: Record<string, string>;
 }
 
-/**
- * Image types: effects, crop shapes, and properties shared by image/picture
- * elements.
- *
- * @module pptx-types/image
- */
-/**
- * Blend mode for `a:blend` container nodes inside an `a:effectDag` (CT_BlendEffect).
- *
- * Per ECMA-376 §20.1.8.10, valid values are: `darken`, `lighten`, `mult`,
- * `over`, `screen`.
- */
 type EffectDagBlendMode = 'darken' | 'lighten' | 'mult' | 'over' | 'screen';
-/**
- * Container node kind inside an `a:effectDag` (CT_EffectContainer @type).
- *
- * Per ECMA-376 §20.1.8.20, `sib` (sibling) draws each child independently
- * over the same source; `tree` (tree) chains effects so each sees the output
- * of its siblings.
- */
 type EffectDagContainerType = 'sib' | 'tree';
-/**
- * Typed model of the directed-acyclic effect graph stored in `a:effectDag`.
- *
- * The four "structural" container/transform nodes are typed; any other inner
- * effect (e.g. `a:outerShdw`, `a:glow`, `a:alphaInv`) is preserved verbatim
- * as a raw XML object via the {@link EffectDagRawLeaf} variant so we never
- * have to recurse into the full effect taxonomy.
- *
- * @example
- * ```ts
- * // <a:effectDag>
- * //   <a:cont type="sib">
- * //     <a:blend blend="mult"><a:cont type="tree" /></a:blend>
- * //   </a:cont>
- * // </a:effectDag>
- * const dag: EffectDagContainer = {
- *   kind: "cont",
- *   type: "sib",
- *   children: [{
- *     kind: "blend",
- *     mode: "mult",
- *     container: { kind: "cont", type: "tree", children: [] },
- *   }],
- * };
- * ```
- */
-type EffectDagNode = EffectDagContainer | EffectDagBlend | EffectDagXfrm | EffectDagRelOff | EffectDagRawLeaf;
-/** `a:cont` — CT_EffectContainer. Recursive; mirrors the top-level `effectDag`. */
+type EffectDagNode = EffectDagContainer | EffectDagBlend | EffectDagXfrm | EffectDagRelOff | EffectDagBlur | EffectDagAlphaOutset | EffectDagPresetShadow | EffectDagRawLeaf;
 interface EffectDagContainer {
     kind: 'cont';
-    /** `@type` — `sib` or `tree`. */
     type: EffectDagContainerType;
-    /** Optional `@name` attribute. */
     name?: string;
-    /** Ordered children. */
     children: EffectDagNode[];
 }
-/** `a:blend` — CT_BlendEffect. Always wraps a single `a:cont` child. */
 interface EffectDagBlend {
     kind: 'blend';
-    /** `@blend` attribute. */
     mode: EffectDagBlendMode;
-    /** Required child `a:cont` container. */
     container: EffectDagContainer;
 }
-/** `a:xfrmEffect` — CT_TransformEffect. Affine transform with no children. */
 interface EffectDagXfrm {
     kind: 'xfrmEffect';
-    /** Horizontal scale, percentage * 1000 (e.g. 100000 = 100%). */
     sx?: number;
-    /** Vertical scale, percentage * 1000. */
     sy?: number;
-    /** Horizontal skew, degrees * 60000. */
     kx?: number;
-    /** Vertical skew, degrees * 60000. */
     ky?: number;
-    /** Horizontal translation in EMU. */
     tx?: number;
-    /** Vertical translation in EMU. */
     ty?: number;
 }
-/** `a:relOff` — CT_RelativeOffsetEffect. Relative offset in 1000ths of a percent. */
 interface EffectDagRelOff {
     kind: 'relOff';
-    /** Horizontal offset, percentage * 1000. */
     tx?: number;
-    /** Vertical offset, percentage * 1000. */
     ty?: number;
 }
-/**
- * Catch-all leaf preserving any non-container effect (e.g. `a:outerShdw`,
- * `a:glow`, `a:alphaInv`) as raw XML. Re-emitted verbatim on save.
- */
+/** Typed CT_BlurEffect with its original payload retained for lossless edits. */
+interface EffectDagBlur {
+    kind: 'blur';
+    radiusEmu?: number;
+    grow?: boolean;
+    xml: XmlObject;
+}
+/** Typed CT_AlphaOutsetEffect with original XML retained for lossless edits. */
+interface EffectDagAlphaOutset {
+    kind: 'alphaOutset';
+    radiusEmu?: number;
+    xml: XmlObject;
+}
+/** Typed CT_PresetShadowEffect with colour and extension XML retained verbatim. */
+interface EffectDagPresetShadow {
+    kind: 'prstShdw';
+    preset?: `shdw${number}`;
+    distanceEmu?: number;
+    direction?: number;
+    xml: XmlObject;
+}
 interface EffectDagRawLeaf {
     kind: 'raw';
-    /** Local element name without the `a:` prefix (e.g. `outerShdw`, `glow`). */
     tag: string;
-    /** Raw XML object captured at load — preserved verbatim on save. */
     xml: Record<string, unknown>;
 }
+
 /**
  * Image recolour/adjustment properties parsed from blip extensions.
  *
@@ -2399,6 +2718,8 @@ interface PptxImageEffects {
     duotone?: {
         color1: string;
         color2: string;
+        /** Original effect XML, retained while the resolved colours are unchanged. */
+        rawXml?: XmlObject;
     };
     /** Grayscale flag. */
     grayscale?: boolean;
@@ -2413,8 +2734,10 @@ interface PptxImageEffects {
     artisticEffect?: string;
     /** Artistic effect radius/amount. */
     artisticRadius?: number;
-    /** Alpha modulation fixed — overall opacity (0-100, where 100 = fully opaque). */
+    /** Alpha modulation fixed: non-negative percentage (100 means unchanged opacity). */
     alphaModFix?: number;
+    /** Original alpha modulation fixed node, including foreign attributes. */
+    alphaModFixRawXml?: XmlObject;
     /** Bi-level threshold — converts to 1-bit black/white (0-100). */
     biLevel?: number;
     /** Colour change — swap one colour range for another (used for transparency keying). */
@@ -2423,7 +2746,13 @@ interface PptxImageEffects {
         clrTo: string;
         /** Whether the target colour is fully transparent (alpha = 0). */
         clrToTransparent?: boolean;
+        /** Original effect XML, including colour transforms and extensions. */
+        rawXml?: XmlObject;
     };
+    /** Original grayscale node, including extension or foreign attributes. */
+    grayscaleRawXml?: XmlObject;
+    /** Original bi-level node, including extension or foreign attributes. */
+    biLevelRawXml?: XmlObject;
     /**
      * Alpha inverse effect (`a:alphaInv`). Inverts the alpha channel; an optional
      * colour child shifts the inversion baseline.
@@ -2431,11 +2760,17 @@ interface PptxImageEffects {
     alphaInv?: {
         /** Optional baseline colour (hex). */
         color?: string;
+        /** Original effect XML, including colour transforms and foreign attributes. */
+        rawXml?: XmlObject;
     };
     /** Alpha ceiling (`a:alphaCeiling`) — clamps any non-zero alpha to fully opaque. Boolean flag. */
     alphaCeiling?: boolean;
+    /** Original alpha ceiling node, including foreign attributes. */
+    alphaCeilingRawXml?: XmlObject;
     /** Alpha floor (`a:alphaFloor`) — clamps any non-fully-opaque alpha to fully transparent. Boolean flag. */
     alphaFloor?: boolean;
+    /** Original alpha floor node, including foreign attributes. */
+    alphaFloorRawXml?: XmlObject;
     /**
      * Alpha modulate (`a:alphaMod`). The schema requires a single `cont` (effect
      * container) child; we preserve the inner XML opaquely for round-trip.
@@ -2443,11 +2778,17 @@ interface PptxImageEffects {
     alphaMod?: {
         /** Raw opaque XML for the `a:cont` child to preserve on save. */
         contRawXml?: Record<string, unknown>;
+        /** Original effect XML, including foreign attributes. */
+        rawXml?: XmlObject;
     };
     /** Alpha replace (`a:alphaRepl`) — replaces alpha with the given fixed-percent value (0..100). */
     alphaRepl?: number;
+    /** Original alpha replace node, including foreign attributes. */
+    alphaReplRawXml?: XmlObject;
     /** Alpha bi-level (`a:alphaBiLevel`) — threshold (0..100) above which alpha becomes fully opaque. */
     alphaBiLevel?: number;
+    /** Original alpha bi-level node, including foreign attributes. */
+    alphaBiLevelRawXml?: XmlObject;
     /**
      * Colour replace (`a:clrRepl`) — replaces all colour information in an image
      * with the given solid colour. Stores the raw colour child to preserve scheme
@@ -2590,6 +2931,7 @@ declare module "./hooks-unstable" {
  *
  * @module pptx-types/media
  */
+
 /**
  * Discriminator for embedded media element types.
  *
@@ -2600,6 +2942,13 @@ declare module "./hooks-unstable" {
  * ```
  */
 type PptxMediaType = 'video' | 'audio' | 'unknown';
+type PptxMediaReferenceKind = 'audioCd' | 'wavAudioFile' | 'audioFile' | 'videoFile' | 'quickTimeFile';
+interface PptxAudioCdPosition {
+    track: number;
+    time?: number;
+    /** Original `st` or `end` node, retained for lossless edits. */
+    rawXml?: XmlObject;
+}
 /**
  * A named bookmark within a media clip timeline.
  *
@@ -2676,6 +3025,112 @@ interface MediaCaptionTrack {
     isDefault?: boolean;
 }
 
+type PptxSmartArtConstraintRelationship = 'self' | 'ch' | 'des';
+type PptxSmartArtConstraintOperator = 'none' | 'equ' | 'gte' | 'lte';
+type PptxSmartArtConstraintPointType = 'all' | 'doc' | 'node' | 'norm' | 'nonNorm' | 'asst' | 'nonAsst' | 'parTrans' | 'pres' | 'sibTrans';
+interface PptxSmartArtConstraintTarget {
+    for?: PptxSmartArtConstraintRelationship;
+    forName?: string;
+    pointType?: PptxSmartArtConstraintPointType;
+}
+/** Editable DiagramML CT_Constraint. */
+interface PptxSmartArtConstraint extends PptxSmartArtConstraintTarget {
+    type: string;
+    referenceType?: string;
+    referenceFor?: PptxSmartArtConstraintRelationship;
+    referenceForName?: string;
+    referencePointType?: PptxSmartArtConstraintPointType;
+    operator?: PptxSmartArtConstraintOperator;
+    value?: number;
+    factor?: number;
+    /** Original constraint retained for foreign attributes and extension content. */
+    rawXml?: XmlObject;
+}
+/** Editable DiagramML CT_NumericRule. */
+interface PptxSmartArtNumericRule extends PptxSmartArtConstraintTarget {
+    type: string;
+    value?: number;
+    factor?: number;
+    max?: number;
+    /** Original rule retained for foreign attributes and extension content. */
+    rawXml?: XmlObject;
+}
+
+/** Typed, editable metadata from a DiagramML layout-definition part. */
+
+interface PptxSmartArtLocalizedText {
+    value: string;
+    language?: string;
+}
+interface PptxSmartArtLayoutCategory {
+    type: string;
+    priority: number;
+}
+interface PptxSmartArtAlgorithmParameter {
+    type: string;
+    value?: string;
+}
+/** Typed DiagramML CT_Algorithm data attached to a layout node. */
+interface PptxSmartArtLayoutAlgorithm {
+    type: string;
+    revision?: number;
+    parameters?: PptxSmartArtAlgorithmParameter[];
+}
+interface PptxSmartArtIteratorAttributes {
+    name?: string;
+    reference?: string;
+    axis?: string[];
+    pointTypes?: string[];
+    hideLastTransition?: boolean[];
+    start?: number[];
+    count?: number[];
+    step?: number[];
+}
+interface PptxSmartArtForEach extends PptxSmartArtIteratorAttributes {
+    rawXml?: XmlObject;
+}
+interface PptxSmartArtWhen extends PptxSmartArtIteratorAttributes {
+    function: string;
+    argument?: string;
+    operator: string;
+    value: string;
+    rawXml?: XmlObject;
+}
+interface PptxSmartArtChoose {
+    name?: string;
+    when: PptxSmartArtWhen[];
+    otherwise?: {
+        name?: string;
+        rawXml?: XmlObject;
+    } | null;
+    rawXml?: XmlObject;
+}
+/** Identity and ordering metadata from DiagramML CT_LayoutNode. */
+interface PptxSmartArtLayoutNode {
+    name?: string;
+    styleLabel?: string;
+    childOrder?: 'b' | 't';
+    moveWith?: string;
+    algorithm?: PptxSmartArtLayoutAlgorithm;
+    forEach?: PptxSmartArtForEach[];
+    choose?: PptxSmartArtChoose[];
+    constraints?: PptxSmartArtConstraint[];
+    rules?: PptxSmartArtNumericRule[];
+    children?: PptxSmartArtLayoutNode[];
+}
+/** Metadata and root node from DiagramML CT_DiagramDefinition. */
+interface PptxSmartArtLayoutDefinition {
+    uniqueId?: string;
+    minimumVersion?: string;
+    defaultStyle?: string;
+    titles?: PptxSmartArtLocalizedText[];
+    descriptions?: PptxSmartArtLocalizedText[];
+    categories?: PptxSmartArtLayoutCategory[];
+    rootNode: PptxSmartArtLayoutNode;
+    /** Original definition retained for constraint evaluation and foreign rules. */
+    rawXml?: XmlObject;
+}
+
 /**
  * SmartArt node types: per-run text, per-node visual override, and the
  * data-model node itself. Split out of `smart-art.ts` to keep each type file
@@ -2685,6 +3140,7 @@ interface MediaCaptionTrack {
  *
  * @module pptx-types/smart-art-node
  */
+
 /**
  * A single run of text inside a SmartArt node, capturing the run text and the
  * raw `a:rPr` run-properties object verbatim so per-run formatting (bold,
@@ -2708,6 +3164,54 @@ interface PptxSmartArtTextRun {
      * round-trip. Untyped XML, hence the loose record shape.
      */
     rPr?: Record<string, unknown>;
+    /** Resolved standard shape-text style derived from {@link rPr}. */
+    style?: TextStyle;
+    /** Raw run XML used to retain unmodelled extension children on save. */
+    rawXml?: Record<string, unknown>;
+    /** Original direct-child order, including unmodelled extension children. */
+    childOrder?: string[];
+}
+/** An ordered item within a SmartArt text paragraph. */
+type PptxSmartArtTextParagraphItem = {
+    kind: 'run';
+    run: PptxSmartArtTextRun;
+} | {
+    kind: 'break';
+    rPr?: Record<string, unknown>;
+    style?: TextStyle;
+    rawXml?: Record<string, unknown>;
+    childOrder?: string[];
+} | {
+    kind: 'field';
+    id?: string;
+    fieldType?: string;
+    text: string;
+    rPr?: Record<string, unknown>;
+    style?: TextStyle;
+    pPr?: Record<string, unknown>;
+    rawXml?: Record<string, unknown>;
+    childOrder?: string[];
+} | {
+    kind: 'tab';
+    rawXml?: Record<string, unknown>;
+    childOrder?: string[];
+} | {
+    kind: 'raw';
+    name: string;
+    value: unknown;
+};
+/** A complete `a:p` paragraph in a SmartArt data-model text body. */
+interface PptxSmartArtTextParagraph {
+    /** Paragraph properties (`a:pPr`) preserved verbatim. */
+    pPr?: Record<string, unknown>;
+    /** Text children in source order. */
+    items: PptxSmartArtTextParagraphItem[];
+    /** End-paragraph run properties (`a:endParaRPr`) preserved verbatim. */
+    endParaRPr?: Record<string, unknown>;
+    /** Resolved style for the paragraph terminator. */
+    endParaStyle?: TextStyle;
+    /** Raw paragraph XML used to retain unmodelled extension children on save. */
+    rawXml?: Record<string, unknown>;
 }
 /**
  * Per-node visual override for a SmartArt node.
@@ -2763,6 +3267,8 @@ interface PptxSmartArtNodeStyle {
 interface PptxSmartArtNode {
     id: string;
     text: string;
+    /** CT_Pt connection identifier, when the point references a connection. */
+    connectionId?: string | null;
     parentId?: string;
     children?: PptxSmartArtNode[];
     /** Node type from `@_type` attribute (e.g. "doc", "node", "asst", "pres"). */
@@ -2775,6 +3281,11 @@ interface PptxSmartArtNode {
      * is not flattened. When {@link text} diverges, the runs are ignored.
      */
     runs?: PptxSmartArtTextRun[];
+    /**
+     * Complete typed paragraph model. Unlike {@link runs}, this retains every
+     * paragraph and the ordered run, field, break, and tab children within it.
+     */
+    paragraphs?: PptxSmartArtTextParagraph[];
     /**
      * Optional per-node visual override (fill / line / font colour, bold /
      * italic). Read at parse time from the point's `spPr` / first-run `rPr`, set
@@ -2784,6 +3295,64 @@ interface PptxSmartArtNode {
     style?: PptxSmartArtNodeStyle;
 }
 
+/** Editable metadata shared by DiagramML quick-style and color definitions. */
+interface PptxSmartArtDefinitionText {
+    value: string;
+    language?: string;
+}
+interface PptxSmartArtDefinitionCategory {
+    type: string;
+    priority: number;
+}
+type PptxSmartArtColorApplicationMethod = 'span' | 'cycle' | 'repeat';
+type PptxSmartArtHueDirection = 'cw' | 'ccw';
+/** CT_Colors application metadata. Color-choice children remain preserved XML. */
+interface PptxSmartArtColorListMetadata {
+    method?: PptxSmartArtColorApplicationMethod;
+    hueDirection?: PptxSmartArtHueDirection;
+}
+/** CT_StyleLabel metadata from a quick-style definition. */
+interface PptxSmartArtQuickStyleLabel {
+    name: string;
+}
+/** CT_CTStyleLabel metadata from a color-transform definition. */
+interface PptxSmartArtColorStyleLabel {
+    name: string;
+    fill?: PptxSmartArtColorListMetadata;
+    line?: PptxSmartArtColorListMetadata;
+    effect?: PptxSmartArtColorListMetadata;
+    textLine?: PptxSmartArtColorListMetadata;
+    textFill?: PptxSmartArtColorListMetadata;
+    textEffect?: PptxSmartArtColorListMetadata;
+}
+interface PptxSmartArtDefinitionMetadata {
+    uniqueId?: string;
+    minimumVersion?: string;
+    titles?: PptxSmartArtDefinitionText[];
+    descriptions?: PptxSmartArtDefinitionText[];
+    categories?: PptxSmartArtDefinitionCategory[];
+}
+/** Typed CT_ColorTransform metadata and the resolved legacy color palette. */
+interface PptxSmartArtColorTransform extends PptxSmartArtDefinitionMetadata {
+    /** Legacy resolved display name. */
+    name?: string;
+    /** Ordered resolved fill colors for rendering. */
+    fillColors: string[];
+    /** Ordered resolved line colors for rendering. */
+    lineColors: string[];
+    /** Ordered CT_CTStyleLabel metadata. */
+    labels?: PptxSmartArtColorStyleLabel[];
+}
+/** Typed CT_StyleDefinition metadata and legacy rendering hint. */
+interface PptxSmartArtQuickStyle extends PptxSmartArtDefinitionMetadata {
+    /** Legacy resolved display name. */
+    name?: string;
+    /** Legacy effect-intensity rendering hint. */
+    effectIntensity?: string;
+    /** Ordered CT_StyleLabel metadata. Complex style payload remains preserved XML. */
+    labels?: PptxSmartArtQuickStyleLabel[];
+}
+
 /**
  * SmartArt types: layout categories, layout presets, colour schemes,
  * data-model nodes/connections, drawing shapes, chrome, and the composite
@@ -2846,6 +3415,8 @@ type SmartArtStyle = 'flat' | 'moderate' | 'intense';
  * ```
  */
 interface PptxSmartArtConnection {
+    /** Stable CT_Cxn model identifier. Required when serialized. */
+    modelId?: string | null;
     /** Model ID of the source node. */
     sourceId: string;
     /** Model ID of the destination node. */
@@ -2856,6 +3427,12 @@ interface PptxSmartArtConnection {
     srcOrd?: number;
     /** Destination index for ordering. */
     destOrd?: number;
+    /** Model ID of the parent transition point associated with this edge. */
+    parentTransitionId?: string | null;
+    /** Model ID of the sibling transition point associated with this edge. */
+    siblingTransitionId?: string | null;
+    /** Layout presentation identifier used by presentation connections. */
+    presentationId?: string | null;
 }
 /**
  * A pre-computed shape from `ppt/diagrams/drawing*.xml`.
@@ -2872,7 +3449,7 @@ interface PptxSmartArtConnection {
  * // => satisfies PptxSmartArtDrawingShape
  * ```
  */
-interface PptxSmartArtDrawingShape {
+interface PptxSmartArtDrawingShape extends PptxCustomPathProperties {
     /** Shape ID within the drawing. */
     id: string;
     /** Preset geometry type (e.g. "roundRect", "ellipse"). */
@@ -2896,6 +3473,8 @@ interface PptxSmartArtDrawingShape {
     strokeWidth?: number;
     /** Text content of the shape. */
     text?: string;
+    /** Standard rich-text segments projected from the associated SmartArt node. */
+    textSegments?: TextSegment[];
     /** Font size in points. */
     fontSize?: number;
     /** Font colour (hex). */
@@ -2922,45 +3501,6 @@ interface PptxSmartArtChrome {
     /** Outline stroke width in points. */
     outlineWidth?: number;
 }
-/**
- * Colour transform entry from `ppt/diagrams/colors*.xml`.
- *
- * @example
- * ```ts
- * const transform: PptxSmartArtColorTransform = {
- *   name: "Colorful - Accent Colors",
- *   fillColors: ["#4F81BD", "#C0504D", "#9BBB59"],
- *   lineColors: ["#385D8A", "#8C3836", "#71893F"],
- * };
- * // => satisfies PptxSmartArtColorTransform
- * ```
- */
-interface PptxSmartArtColorTransform {
-    /** Colour scheme name / title. */
-    name?: string;
-    /** Ordered list of fill colours (hex) for each node. */
-    fillColors: string[];
-    /** Ordered list of line colours (hex). */
-    lineColors: string[];
-}
-/**
- * Style entry from `ppt/diagrams/quickStyles*.xml`.
- *
- * @example
- * ```ts
- * const qs: PptxSmartArtQuickStyle = {
- *   name: "Moderate Effect",
- *   effectIntensity: "moderate",
- * };
- * // => satisfies PptxSmartArtQuickStyle
- * ```
- */
-interface PptxSmartArtQuickStyle {
-    /** Style name / title. */
-    name?: string;
-    /** Effect intensity identifier (e.g. "subtle", "moderate", "intense"). */
-    effectIntensity?: string;
-}
 /**
  * Complete parsed SmartArt data for a {@link SmartArtPptxElement}.
  *
@@ -3000,14 +3540,28 @@ interface PptxSmartArtData {
     colorTransform?: PptxSmartArtColorTransform;
     /** Quick style from `ppt/diagrams/quickStyles*.xml`. */
     quickStyle?: PptxSmartArtQuickStyle;
+    /** Editable metadata from the related DiagramML layout definition. */
+    layoutDefinition?: PptxSmartArtLayoutDefinition;
     /** Relationship ID for the diagram data part (for round-trip save). */
     dataRelId?: string;
+    /** Relationship ID for the diagram layout part. */
+    layoutRelId?: string;
     /** Relationship ID for the drawing part. */
     drawingRelId?: string;
     /** Relationship ID for the colours part. */
     colorsRelId?: string;
     /** Relationship ID for the quick-styles part. */
     styleRelId?: string;
+    /** Internal save hint: the layout definition changed in the editor. */
+    layoutDirty?: boolean;
+    /** Internal save hint: typed layout-definition metadata changed. */
+    layoutDefinitionDirty?: boolean;
+    /** Internal save hint: quick-style definition metadata changed. */
+    quickStyleDirty?: boolean;
+    /** Internal save hint: color-transform definition metadata changed. */
+    colorTransformDirty?: boolean;
+    /** Internal save hint: cached drawing geometry or text changed in the editor. */
+    drawingDirty?: boolean;
 }
 
 /**
@@ -3616,6 +4170,13 @@ interface MediaPptxElement extends PptxElementBase {
     mediaPath?: string;
     mediaData?: string;
     mediaMimeType?: string;
+    mediaReferenceKind?: PptxMediaReferenceKind;
+    mediaReferenceName?: string;
+    /** Explicit DrawingML `audioFile/@contentType` value when present. */
+    mediaReferenceContentType?: string;
+    audioCdStart?: PptxAudioCdPosition;
+    audioCdEnd?: PptxAudioCdPosition;
+    rawMediaReferenceXml?: XmlObject;
     /** Trim start in milliseconds (from p:cMediaNode p:cTn @st). */
     trimStartMs?: number;
     /** Trim end in milliseconds (from p:cMediaNode p:cTn @end). */
@@ -3736,6 +4297,10 @@ interface ContentPartPptxElement extends PptxElementBase {
     type: 'contentPart';
     /** Ink strokes contained in this content part. */
     inkStrokes?: ContentPartInkStroke[];
+    /** Package path of the related InkML part. */
+    inkPartPath?: string;
+    /** Parsed InkML root retained for unknown-node preservation on dirty save. */
+    inkPartRawXml?: XmlObject;
 }
 /**
  * A Slide Zoom or Section Zoom element (PowerPoint Zoom Object).
@@ -3756,12 +4321,32 @@ interface ContentPartPptxElement extends PptxElementBase {
  */
 interface ZoomPptxElement extends PptxElementBase, PptxImageProperties {
     type: 'zoom';
-    /** Type of zoom: slide-level or section-level. */
-    zoomType: 'slide' | 'section';
+    /** Type of zoom: slide-level, section-level, or a multi-section summary. */
+    zoomType: 'slide' | 'section' | 'summary';
     /** Zero-based index of the target slide. */
     targetSlideIndex: number;
     /** Section ID for section zoom. */
     targetSectionId?: string;
+    /** Ordered section tiles in a Summary Zoom container. */
+    summaryTargets?: SummaryZoomTarget[];
+    /** Layout mode authored on the Summary Zoom container. */
+    summaryLayout?: 'grid' | 'fixed';
+}
+/** A single section tile within a PowerPoint Summary Zoom container. */
+interface SummaryZoomTarget extends PptxImageProperties {
+    sectionId: string;
+    targetSlideIndex: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    title?: string;
+    description?: string;
+    offsetFactorX?: number;
+    offsetFactorY?: number;
+    scaleFactorX?: number;
+    scaleFactorY?: number;
+    rawXml?: XmlObject;
 }
 /**
  * A 3D model object embedded via `p16:model3D` inside an
@@ -4050,6 +4635,44 @@ type PptxAnimationTrigger = 'onClick' | 'onShapeClick' | 'onHover' | 'afterPrevi
  * is preserved alongside other animations.
  */
 type PptxNativeAnimationKind = 'media';
+/** A target selected by `p:tgtEl` in the PresentationML timing model. */
+type PptxAnimationTarget = {
+    type: 'shape';
+    shapeId: string;
+    rawXml?: XmlObject;
+} | {
+    type: 'slide';
+    rawXml?: XmlObject;
+} | {
+    type: 'sound';
+    relationshipId: string;
+    name?: string;
+    rawXml?: XmlObject;
+} | {
+    type: 'ink';
+    shapeId: string;
+    rawXml?: XmlObject;
+} | {
+    type: 'unknown';
+    rawXml: XmlObject;
+};
+/** Nested build choice carried by `p:bldGraphic`. */
+type PptxGraphicBuild = {
+    mode: 'asOne';
+    rawXml?: XmlObject;
+} | {
+    mode: 'sub';
+    kind: 'diagram';
+    build: string;
+    reverse: boolean;
+    rawXml?: XmlObject;
+} | {
+    mode: 'sub';
+    kind: 'chart';
+    build: string;
+    animateBackground: boolean;
+    rawXml?: XmlObject;
+};
 /**
  * Parsed native animation record from `p:timing / p:tnLst`.
  *
@@ -4071,6 +4694,8 @@ type PptxNativeAnimationKind = 'media';
 interface PptxNativeAnimation {
     /** Target element/shape ID. */
     targetId?: string;
+    /** Full timing target, including sound and ink target variants. */
+    target?: PptxAnimationTarget;
     /** Trigger type. */
     trigger?: PptxAnimationTrigger;
     /** Shape ID that triggers this animation when clicked (interactive sequence). */
@@ -4175,6 +4800,8 @@ interface PptxNativeAnimation {
      * that aren't OLE charts).
      */
     graphicBuild?: string;
+    /** Schema-accurate `p:bldGraphic/p:bldAsOne|p:bldSub` representation. */
+    graphicBuildProperties?: PptxGraphicBuild;
     /**
      * Opaque map of `p:cTn` attributes that don't have a typed home on this
      * interface but must round-trip through parse → save. Keys are stored
@@ -4291,6 +4918,8 @@ interface AnimationCondition {
     targetShapeId?: string;
     /** Whether the condition targets a slide (from `p:tgtEl/p:sldTgt`). */
     targetSlide?: boolean;
+    /** Full target choice, including `p:sndTgt` and `p:inkTgt`. */
+    target?: PptxAnimationTarget;
 }
 /** Iteration configuration from `p:iterate`. */
 interface PptxAnimationIterate {
@@ -4369,12 +4998,40 @@ interface PptxElementAnimation {
     stopSound?: boolean;
 }
 
+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;
+}
+
 /**
  * Metadata types: slide comments, compatibility warnings, tags,
  * custom properties, core/app document properties.
  *
  * @module pptx-types/metadata
  */
+
 /**
  * A slide comment — may be a legacy positional comment or a modern
  * threaded comment with replies.
@@ -4394,6 +5051,10 @@ interface PptxElementAnimation {
 interface PptxComment {
     id: string;
     text: string;
+    /** Storage vocabulary used by this comment. Omitted means legacy PresentationML. */
+    format?: 'legacy' | 'modern';
+    /** Stable GUID author identifier used by Office 2021 modern comments. */
+    authorId?: string;
     /** Optional parent comment id for reply threading metadata. */
     parentId?: string;
     author?: string;
@@ -4402,12 +5063,35 @@ interface PptxComment {
     y?: number;
     /** Whether this comment has been resolved/marked done. */
     resolved?: boolean;
+    /** Native p188 status token. */
+    status?: 'active' | 'resolved' | 'closed';
+    /** Modern comment classification tags and author IDs that liked the comment. */
+    tags?: string[];
+    likes?: string[];
+    startDate?: string;
+    dueDate?: string;
+    assignedTo?: string[];
+    /** Task completion in thousandths of a percent, from 0 through 100000. */
+    complete?: number;
+    priority?: number;
+    title?: string;
     /** Modern threaded comment support (p15:threadingInfo). */
     threadId?: string;
     /** Replies to this comment (for modern threaded comments). */
     replies?: PptxComment[];
     /** ID of the element this comment is associated with (if any). */
     elementId?: string;
+    /** Original `p:cm` subtree, retained for unknown child and extension preservation. */
+    rawXml?: XmlObject;
+}
+/** 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`.
@@ -4440,6 +5124,8 @@ interface PptxCommentAuthor {
     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
@@ -4494,9 +5180,17 @@ interface PptxTag {
  */
 interface PptxTagCollection {
     /** File path within the PPTX archive. */
-    path: string;
+    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`.
@@ -4601,6 +5295,19 @@ interface PptxAppProperties {
     /** Hyperlink base URL. */
     hyperlinkBase?: string;
 }
+
+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.
  *
@@ -4887,6 +5594,8 @@ interface PptxTheme {
 type PptxTransitionType = 'none' | 'cut' | 'fade' | 'push' | 'wipe' | 'split' | 'randomBar' | 'blinds' | 'checker' | 'circle' | 'comb' | 'cover' | 'diamond' | 'dissolve' | 'plus' | 'pull' | 'random' | 'strips' | 'uncover' | 'wedge' | 'wheel' | 'zoom' | 'newsflash' | 'morph' | 'conveyor' | 'doors' | 'ferris' | 'flash' | 'flythrough' | 'gallery' | 'glitter' | 'honeycomb' | 'pan' | 'prism' | 'reveal' | 'ripple' | 'shred' | 'switch' | 'vortex' | 'warp' | 'wheelReverse' | 'window' | 'cube' | 'flip' | 'rotate' | 'orbit';
 /** Split orientation from OOXML `@_orient`. */
 type PptxSplitOrientation = 'horz' | 'vert';
+/** Schema-defined `ST_TransitionSpeed` values. */
+type PptxTransitionSpeed = 'slow' | 'med' | 'fast';
 /**
  * Slide transition configuration.
  *
@@ -4903,6 +5612,8 @@ type PptxSplitOrientation = 'horz' | 'vert';
  */
 interface PptxSlideTransition {
     type: PptxTransitionType;
+    /** Schema-defined transition speed. Defaults to `fast` when omitted. */
+    speed?: PptxTransitionSpeed;
     durationMs?: number;
     direction?: string;
     advanceOnClick?: boolean;
@@ -4917,6 +5628,10 @@ interface PptxSlideTransition {
     orient?: PptxSplitOrientation;
     /** Relationship ID of transition sound from `p:sndAc/p:stSnd/@r:embed` when present. */
     soundRId?: string;
+    /** Embedded WAV display name from `p:stSnd/p:snd/@name`. */
+    soundName?: string;
+    /** Whether the transition sound repeats until another sound starts. */
+    soundLoop?: boolean;
     /** Resolved transition sound media path within the package. */
     soundPath?: string;
     /** Human-readable sound file name (extracted from soundPath). */
@@ -4930,6 +5645,8 @@ interface PptxSlideTransition {
     rawSoundAction?: XmlObject;
     /** Preserved extension-list XML node from `p:extLst` within the transition for lossless round-trip. */
     rawExtLst?: XmlObject;
+    /** Original transition node, retained to preserve unknown attributes and children. */
+    rawTransition?: XmlObject;
 }
 
 /**
@@ -4949,6 +5666,11 @@ interface PptxViewScale {
     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).
@@ -4957,6 +5679,16 @@ 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`.
@@ -4998,6 +5730,10 @@ interface PptxCommonSlideViewProperties {
     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. */
@@ -5025,6 +5761,8 @@ interface PptxViewProperties {
     };
     /** 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>;
 }
@@ -5039,12 +5777,16 @@ interface PptxViewProperties {
  * @see ECMA-376 Part 1, §19.2.1.3 (custDataLst), §19.3.1.6 (custData)
  */
 interface PptxCustomerData {
-    /** Resolved part path inside the package (e.g. `ppt/customerData/item1.xml`). */
-    id: string;
+    /** Resolved part path inside the package (e.g. `customXml/item1.xml`). */
+    id?: string;
     /** Relationship ID referencing the custom data part. */
-    relId: string;
+    relId?: string;
     /** Raw string content of the custom data part (if resolvable). */
     data?: string;
+    /** OPC content type for the custom data part. */
+    contentType?: string;
+    /** Raw `p:custData` XML retained for unknown-node preservation. */
+    rawXml?: XmlObject;
 }
 /**
  * An ActiveX control reference from `p:controls / p:control`.
@@ -5169,6 +5911,8 @@ interface PptxSlide {
     /** Optional `<p:cSld @name>` value of the notes slide, for round-trip. */
     notesCSldName?: string;
     comments?: PptxComment[];
+    /** Source package metadata for an Office 2021 p188 comment part. */
+    modernCommentPart?: PptxModernCommentPart;
     warnings?: PptxCompatibilityWarning[];
     rawXml?: XmlObject;
     /** Per-slide colour map override parsed from `p:clrMapOvr`. */
@@ -5187,6 +5931,24 @@ interface PptxSlide {
     activeXControls?: PptxActiveXControl[];
     /** Per-slide header/footer flags from `<p:hf>` (P-H3). */
     headerFooterFlags?: PptxHeaderFooterFlags;
+    /** Server-backed slide synchronization metadata stored in a related OPC part. */
+    slideSynchronization?: PptxSlideSyncProperties;
+}
+interface PptxModernCommentPart {
+    path: string;
+    relationshipId: string;
+    /** Original p188:cmLst root, including unknown attributes and extensions. */
+    rawXml?: XmlObject;
+}
+/** Metadata from a `p:sldSyncPr` slide synchronization data part. */
+interface PptxSlideSyncProperties {
+    serverSlideId: string;
+    serverSlideModifiedTime: string;
+    clientInsertedTime: string;
+    extensionList?: XmlObject;
+    rawXml?: XmlObject;
+    partPath?: string;
+    relationshipId?: string;
 }
 /**
  * A slide layout available in the loaded presentation.
@@ -5273,11 +6035,13 @@ interface PptxPresentationProperties {
     showSlidesTo?: number;
     /** Whether to show subtitles/captions during presentation mode. */
     showSubtitles?: boolean;
-    /** Print settings: slides per page. */
+    /** Typed `p:prnPr` settings. Set to null during save to remove the element. */
+    printProperties?: PptxPresentationPrintProperties | null;
+    /** @deprecated Use `printProperties.printWhat`; retained as a handout compatibility alias. */
     printSlidesPerPage?: number;
-    /** Print settings: frame slides. */
+    /** @deprecated Use `printProperties.frameSlides`. */
     printFrameSlides?: boolean;
-    /** Print settings: colour mode (from `p:prnPr/@clrMode`). */
+    /** @deprecated Use `printProperties.colorMode`. */
     printColorMode?: 'clr' | 'gray' | 'bw';
     /** Most-recently-used colours from the presentation palette. */
     mruColors?: string[];
@@ -5314,6 +6078,8 @@ interface PptxCustomShow {
     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`).
@@ -5342,6 +6108,8 @@ interface PptxSection {
     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`.
@@ -5410,11 +6178,13 @@ interface PptxPhotoAlbum {
  */
 interface PptxKinsoku {
     /** Language code (e.g. "ja-JP", "zh-CN"). */
-    lang?: string;
+    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}.
@@ -5465,6 +6235,8 @@ interface PptxData {
     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. */
@@ -5505,6 +6277,8 @@ interface PptxData {
     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)
@@ -5797,10 +6571,17 @@ 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';
@@ -6314,10 +7095,12 @@ interface PptxHandlerSaveOptions {
     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;
+    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. */
@@ -6349,6 +7132,8 @@ interface PptxHandlerSaveOptions {
      * 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.
@@ -7082,10 +7867,12 @@ type CollaborationRole = 'owner' | 'collaborator' | 'viewer';
  *   any signaling server, which makes this mode usable from static hosting.
  */
 type CollaborationTransport = 'websocket' | 'webrtc';
+/** How the local user entered a collaboration session. */
+type CollaborationSessionIntent = 'create' | 'join';
 /**
  * Real-time collaboration configuration.
  *
- * The same shape is accepted by the React, Vue, and Angular bindings.
+ * The same shape is accepted by every framework binding.
  */
 interface CollaborationConfig {
     /** Unique identifier for the collaboration room (alphanumeric, hyphens, underscores). */
@@ -7113,6 +7900,13 @@ interface CollaborationConfig {
     authToken?: string;
     /** Role in the session; defaults to `'collaborator'`. */
     role?: CollaborationRole;
+    /**
+     * Whether this client created the room or joined an existing room. Providers
+     * do not use this value, but hosts can use it to avoid publishing local file
+     * bytes when handling a join request. Omitted values retain the legacy
+     * create-session behaviour.
+     */
+    sessionIntent?: CollaborationSessionIntent;
     /**
      * Elected-writer write-back callback (Area 3 of the C3 hardening plan).
      *
@@ -7212,6 +8006,44 @@ declare const MOBILE_BREAKPOINT = 768;
 declare const TABLET_BREAKPOINT = 1024;
 /** Device orientation as reported by the screen / viewport aspect ratio. */
 type DeviceOrientation = 'portrait' | 'landscape';
+
+interface PresentationSnapshot {
+    slideIndex: number;
+    buildStep: number;
+    sequence: number;
+    blackout: 'none' | 'black' | 'white';
+    paused: boolean;
+    elapsedMs: number;
+    zoom?: PresentationZoomState;
+    pointer?: PresentationPointerState;
+    inkStrokes?: PresentationInkStroke[];
+    caption?: string;
+    subtitlesVisible?: boolean;
+}
+interface PresentationZoomState {
+    scale: number;
+    originX: number;
+    originY: number;
+}
+type PresentationPointerTool = 'none' | 'laser' | 'pen' | 'highlighter' | 'eraser';
+interface PresentationPointerState {
+    tool: PresentationPointerTool;
+    x: number;
+    y: number;
+    color: string;
+}
+interface PresentationInkPoint {
+    x: number;
+    y: number;
+}
+interface PresentationInkStroke {
+    id: string;
+    slideIndex: number;
+    tool: 'pen' | 'highlighter';
+    color: string;
+    width: number;
+    points: PresentationInkPoint[];
+}
 interface TouchGestureCallbacks {
     /** Called continuously during a pinch gesture with the new (clamped) scale. */
     onPinchZoom?: (newScale: number) => void;
@@ -7226,6 +8058,20 @@ interface ElementClipboardPayload {
     isTemplate: boolean;
 }
 
+/** Framework-neutral virtual-list range used by every thumbnail sidebar. */
+interface VirtualizedRange {
+    startIndex: number;
+    endIndex: number;
+    totalHeight: number;
+    offsetY: number;
+    visibleRange: {
+        start: number;
+        end: number;
+    };
+}
+/** Compute the rendered item window for fixed-height virtual lists. */
+declare function computeVirtualRange(totalItems: number, itemHeight: number, scrollTop: number, viewportHeight: number, overscan?: number): VirtualizedRange;
+
 /**
  * Pure handout layout calculations, shared by every binding's print path.
  *
@@ -7622,6 +8468,17 @@ interface UsePresentationModeResult {
   isAudienceWindowOpen: () => boolean;
   /** Send a slide index to the audience window explicitly. */
   syncSlideToAudience: (slideIndex: number) => void;
+  syncStateToAudience: (snapshot: PresentationSnapshot) => void;
+  presenterSnapshot: PresentationSnapshot;
+  setPresenterBlackout: (blackout: PresentationSnapshot['blackout']) => void;
+  togglePresenterTimer: () => void;
+  resetPresenterTimer: () => void;
+  stepPresenterZoom: (direction: 1 | -1) => void;
+  resetPresenterZoom: () => void;
+  setPresenterCaption: (caption: string) => void;
+  setPresenterSubtitlesVisible: (visible: boolean) => void;
+  updatePresenterSnapshot: (patch: Partial<PresentationSnapshot>) => void;
+  swapPresenterDisplays: () => Promise<boolean>;
 }
 //#endregion
 //#region src/viewer/hooks/useThemeSwitching.d.ts
@@ -8028,6 +8885,8 @@ interface UsePresentationKeyboardInput {
   onToggleToolbar?: () => void;
   /** Toggle between presenter view (split-screen with notes) and fullscreen. */
   onTogglePresenterView?: () => void;
+  onToggleBlackScreen?: () => void;
+  onToggleWhiteScreen?: () => void;
   rehearsing: boolean;
   recordCurrentSlideTime: (slideIndex: number) => void;
   presentationSlideIndex: number;
@@ -8075,12 +8934,15 @@ interface UsePresenterWindowInput {
   isPresenterMode: boolean;
   /** Raw PPTX bytes to share with the audience tab via IndexedDB. */
   content?: ArrayBuffer | Uint8Array | null;
+  snapshot: PresentationSnapshot;
 }
 interface UsePresenterWindowResult {
   openAudienceWindow: () => boolean;
   closeAudienceWindow: () => void;
   isAudienceWindowOpen: () => boolean;
   syncSlideToAudience: (slideIndex: number) => void;
+  syncStateToAudience: (snapshot: PresentationSnapshot) => void;
+  swapDisplays: () => Promise<boolean>;
 }
 declare function usePresenterWindow(input: UsePresenterWindowInput): UsePresenterWindowResult;
 //#endregion
@@ -8090,6 +8952,7 @@ interface UseAudienceModeInput {
   onSetMode: (mode: ViewerMode) => void;
   onSetActiveSlideIndex: (index: number) => void;
   containerRef: React.RefObject<HTMLElement | null>;
+  onSnapshot?: (snapshot: PresentationSnapshot) => void;
 }
 /**
  * When the page was opened with the `#pptx-audience` hash, this hook:
@@ -9751,34 +10614,12 @@ interface VirtualizedSlidesOptions {
   /** Number of extra items to render above/below the viewport. */
   overscan?: number;
 }
-interface VirtualizedRange {
-  /** The first index to render (inclusive). */
-  startIndex: number;
-  /** The last index to render (inclusive). */
-  endIndex: number;
-  /** Total height of the virtual container (for scrollbar sizing). */
-  totalHeight: number;
-  /** Offset (top padding) to position the rendered window correctly. */
-  offsetY: number;
-  /** The visible range without overscan (for analytics/testing). */
-  visibleRange: {
-    start: number;
-    end: number;
-  };
-}
 interface VirtualizedSlidesResult extends VirtualizedRange {
   /** Ref to attach to the scroll container element. */
   scrollContainerRef: React.RefObject<HTMLDivElement | null>;
   /** Call this to scroll a specific index into view. */
   scrollToIndex: (index: number, behavior?: ScrollBehavior) => void;
 }
-/**
- * Compute the rendered index range given scroll state and item dimensions.
- *
- * This is a pure function with no React or DOM dependencies so it can
- * be unit-tested without `renderHook` or a DOM environment.
- */
-declare function computeVirtualRange(totalItems: number, itemHeight: number, scrollTop: number, viewportHeight: number, overscan?: number): VirtualizedRange;
 declare function useVirtualizedSlides({ totalItems, itemHeight, overscan }: VirtualizedSlidesOptions): VirtualizedSlidesResult;
 //#endregion
 //#region src/viewer/hooks/useIsMobile.d.ts