pptx-react-viewer 3.5.4 → 3.7.0

package/dist/viewer/index.d.ts

@@ -45,6 +45,12 @@ interface PptxAction {
   soundRId?: string;
   /** Resolved media target path for the optional click sound. */
   soundPath?: string;
+  /**
+   * `CT_Hyperlink/@endSnd` (ECMA-376 20.1.2.2.23): PowerPoint's Action
+   * Settings "Stop previous sound" checkbox. Round-tripped for now (issue
+   * G14); not yet wired into playback.
+   */
+  endSnd?: boolean;
 }
 //#endregion
 //#region src/core/types/common.d.ts
@@ -67,7 +73,7 @@ interface PptxAction {
  * // => "wavy" — one of: sng | dbl | heavy | dotted | dash | wavy | none | ...
  * ```
  */
-type UnderlineStyle = 'sng' | 'dbl' | 'heavy' | 'dotted' | 'dottedHeavy' | 'dash' | 'dashHeavy' | 'dashLong' | 'dashLongHeavy' | 'dotDash' | 'dotDashHeavy' | 'dotDotDash' | 'dotDotDashHeavy' | 'wavy' | 'wavyHeavy' | 'wavyDbl' | 'none';
+type UnderlineStyle = 'sng' | 'dbl' | 'heavy' | 'dotted' | 'dottedHeavy' | 'dash' | 'dashHeavy' | 'dashLong' | 'dashLongHeavy' | 'dotDash' | 'dotDashHeavy' | 'dotDotDash' | 'dotDotDashHeavy' | 'wavy' | 'wavyHeavy' | 'wavyDbl' | 'words' | 'none';
 /**
  * Connector connection point reference — links a connector endpoint to a
  * specific shape on the slide.
@@ -402,6 +408,16 @@ interface CustomGeometryRawData {
   cxnLstXml?: unknown;
   /** Raw `a:rect` XML content (text rectangle). */
   rectXml?: unknown;
+  /**
+   * Raw `a:pathLst` XML content: every `a:path`'s formula-bearing `a:pt`
+   * x/y attributes, `a:arcTo` params, `a:close`, and per-path `@w`/`@h`/
+   * `@fill`/`@stroke`/`@extrusionOk`, preserved verbatim (not the
+   * parse-time-resolved numbers in `customGeometryPaths`). Lets a live
+   * `shapeAdjustments` drag re-evaluate the outline against the CURRENT
+   * guide values instead of the ones baked in at parse time; see
+   * `geometry/custom-geometry-live-eval.ts`.
+   */
+  pathLstXml?: unknown;
 }
 /**
  * XY-style adjustment handle (`a:ahXY`) on a custom geometry.
@@ -557,6 +573,44 @@ interface PptxCustomPathProperties {
   customGeometryTextRect?: CustomGeometryTextRect;
 }
 //#endregion
+//#region src/core/types/color-ref.d.ts
+/**
+ * Theme colour references: the typed counterpart of `<a:schemeClr>`.
+ *
+ * A colour picked from the theme palette is remembered as a scheme slot plus
+ * PowerPoint's luminance variants rather than as the sRGB it currently
+ * resolves to, so a later theme change re-colours the shape (and a saved file
+ * keeps `<a:schemeClr>` instead of a canonical `<a:srgbClr>`).
+ *
+ * @module types/color-ref
+ */
+/**
+ * The scheme slot names `a:schemeClr/@val` accepts (ECMA-376 `ST_SchemeColorIndex`).
+ * `bg1`/`tx1`/`bg2`/`tx2` are the colour-map aliases a slide resolves through
+ * `p:clrMap`; `phClr` is the placeholder colour used inside a theme's style
+ * matrix and is never chosen from a picker.
+ */
+type PptxThemeColorSchemeName = 'dk1' | 'lt1' | 'dk2' | 'lt2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hlink' | 'folHlink' | 'bg1' | 'tx1' | 'bg2' | 'tx2' | 'phClr';
+/**
+ * A theme colour choice. Every transform is a 0..1 fraction of the OOXML
+ * percentage (`lumMod val="20000"` is `lumMod: 0.2`), matching how the parser
+ * reads them, and is applied in the order `a:schemeClr` children are written:
+ * `tint`, `shade`, `lumMod`, `lumOff`, `alpha`.
+ */
+interface PptxThemeColorRef {
+  scheme: PptxThemeColorSchemeName;
+  /** `a:lumMod`: multiply HSL luminance (PowerPoint's "Lighter/Darker" rows). */
+  lumMod?: number;
+  /** `a:lumOff`: add to HSL luminance after `lumMod` ("Lighter N%" rows). */
+  lumOff?: number;
+  /** `a:tint`: blend towards white. */
+  tint?: number;
+  /** `a:shade`: blend towards black. */
+  shade?: number;
+  /** `a:alpha`: opacity fraction (1 = opaque). */
+  alpha?: number;
+}
+//#endregion
 //#region src/core/types/effect-dag.d.ts
 type EffectDagBlendMode = 'darken' | 'lighten' | 'mult' | 'over' | 'screen';
 type EffectDagContainerType = 'sib' | 'tree';
@@ -846,6 +900,15 @@ interface ShapeStyle {
    * back to canonical `<a:srgbClr>`.
    */
   fillColorXml?: XmlObject;
+  /**
+   * Typed theme colour reference for the fill, set when {@link fillColorXml}
+   * is a plain `a:schemeClr` (see `themeColorRefFromColorChoice`). When
+   * present it WINS on save: the writer emits `<a:schemeClr>` from this ref
+   * instead of the resolved {@link fillColor}, so the fill keeps following
+   * the theme palette after a later theme change. `undefined` means the fill
+   * is a plain hex (or a colour kind a ref cannot express).
+   */
+  fillColorRef?: PptxThemeColorRef;
   fillGradient?: string;
   /** Original `gradFill` XML retained for unknown-child and extension round-tripping. */
   fillGradientXml?: XmlObject;
@@ -880,6 +943,12 @@ interface ShapeStyle {
     opacity?: number;
     /** Raw XML colour node preserved for round-trip (e.g. a:schemeClr with transforms). */
     originalColorXml?: XmlObject;
+    /**
+     * Typed theme colour reference for this stop, set when
+     * {@link originalColorXml} is a plain `a:schemeClr`. Wins on save, same
+     * as {@link ShapeStyle.fillColorRef}.
+     */
+    colorRef?: PptxThemeColorRef;
   }>;
   fillGradientAngle?: number;
   fillGradientType?: 'linear' | 'radial';
@@ -926,6 +995,12 @@ interface ShapeStyle {
    * round-trip serialisation. See {@link fillColorXml} for the rationale.
    */
   strokeColorXml?: XmlObject;
+  /**
+   * Typed theme colour reference for the outline, mirroring
+   * {@link fillColorRef}: set when {@link strokeColorXml} is a plain
+   * `a:schemeClr`, and wins on save.
+   */
+  strokeColorRef?: PptxThemeColorRef;
   /**
    * Kind of fill painted on the outline (`a:ln` child). Distinguishes a solid
    * outline from a gradient/pattern/none outline so save can emit the correct
@@ -1159,6 +1234,21 @@ interface ShapeStyle {
   dagFillOverlayColor?: string;
   /** Fill overlay tint opacity (0-1), from the overlay fill colour's alpha. */
   dagFillOverlayOpacity?: number;
+  /** Fill overlay blend mode from a direct `a:effectLst/a:fillOverlay/@blend`. */
+  shapeFillOverlayBlend?: 'over' | 'mult' | 'screen' | 'darken' | 'lighten';
+  /**
+   * Fill overlay tint colour (hex `#RRGGBB`) from a direct
+   * `a:effectLst/a:fillOverlay`'s `a:solidFill`/`a:gradFill`.
+   */
+  shapeFillOverlayColor?: string;
+  /** Fill overlay tint opacity (0-1), from the overlay fill colour's alpha. */
+  shapeFillOverlayOpacity?: number;
+  /** Original source `a:fillOverlay` node, preserved for lossless surgical updates. */
+  fillOverlayXml?: XmlObject;
+  /** Resolved source fill-overlay colour used to detect colour edits. */
+  shapeFillOverlayOriginalColor?: string;
+  /** Source fill-overlay opacity used to detect alpha edits. */
+  shapeFillOverlayOriginalOpacity?: 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). */
@@ -1414,8 +1504,25 @@ interface TextStyle {
    * verbatim when the resolved {@link color} still matches this node.
    */
   colorXml?: XmlObject;
+  /**
+   * Typed theme colour reference for the run's text colour, set when
+   * {@link colorXml} is a plain `a:schemeClr` (see
+   * `themeColorRefFromColorChoice`). When present it WINS on save: the
+   * writer emits `<a:schemeClr>` from this ref instead of the resolved
+   * {@link color}, so the text keeps following the theme palette after a
+   * later theme change.
+   */
+  colorRef?: PptxThemeColorRef;
   align?: 'left' | 'center' | 'right' | 'justify' | 'justLow' | 'dist' | 'thaiDist';
-  vAlign?: 'top' | 'middle' | 'bottom';
+  /**
+   * Vertical text-box anchor (`a:bodyPr/@anchor`, `ST_TextAnchoringType`).
+   * `distributed`/`justified` (`dist`/`just`) stretch line spacing so the
+   * paragraph block fills the box's full vertical extent, distinct from true
+   * centering (`middle`/`ctr`); both approximate to a middle-anchored render
+   * (see `text-body-layout.ts`) since CSS has no native vertical-justify
+   * primitive, but round-trip losslessly through parse/save.
+   */
+  vAlign?: 'top' | 'middle' | 'bottom' | 'distributed' | 'justified';
   /** Right-to-left paragraph/run direction (`a:pPr/@rtl`, `a:rPr/@rtl`). */
   rtl?: boolean;
   /** Body text direction (`a:bodyPr/@vert`).
@@ -1831,6 +1938,12 @@ interface BulletInfo {
    * identity rather than being flattened to `<a:srgbClr/>` on save.
    */
   colorXml?: XmlObject;
+  /**
+   * Typed theme colour reference for the bullet colour, set when
+   * {@link colorXml} is a plain `a:schemeClr`. Wins on save, same as
+   * {@link TextStyle.colorRef}.
+   */
+  colorRef?: PptxThemeColorRef;
   /** True when `a:buNone` explicitly suppresses bullets. */
   none?: boolean;
   /** Picture bullet: relationship ID from `a:buBlip` → `a:blip[@r:embed]`. */
@@ -2236,6 +2349,50 @@ interface PptxChartAxisLabelFormatting {
   noMultiLevelLabels?: boolean;
 }
 //#endregion
+//#region src/core/types/chart-ex.d.ts
+/**
+ * Chart-formatting types that don't fit an existing, owned type module for
+ * this wave (`types/chart.ts` is owned elsewhere; see its own module doc).
+ * Despite the file name, `PptxChartDataPointPicture` is a CLASSIC (`c:`)
+ * construct, not ChartEx (`cx:`) - it landed here only because it needs a
+ * home outside `chart.ts`.
+ *
+ * @module pptx-types/chart-ex
+ */
+/** `c:dPt/c:pictureOptions/c:pictureFormat/@val` (ST_PictureFormat). */
+type PptxChartPictureFormat = 'stretch' | 'stack' | 'stackScale';
+/**
+ * Per-data-point picture-fill flags (`c:dPt/c:pictureOptions`): PowerPoint's
+ * "Picture or texture fill" with "Stack"/"Stretch" semantics on a bar/column
+ * data point, distinct from the point's plain `c:spPr` solid/gradient fill.
+ *
+ * The flags parse purely (`parseChartDataPointPicture` in
+ * `utils/chart-datapoint-serializer.ts`); {@link imageUrl} is a separate,
+ * later addition populated by the runtime (`PptxHandlerRuntimeChartParsing.ts`)
+ * once the sibling `c:spPr/a:blipFill/a:blip`'s `r:embed`/`r:link` is resolved
+ * against the chart part's relationships, since that resolution needs zip/file
+ * access the pure parser does not have.
+ */
+interface PptxChartDataPointPicture {
+  /** Apply the picture to the front face of a 3-D bar/column (`c:applyToFront`). */
+  applyToFront?: boolean;
+  /** Apply the picture to the side faces of a 3-D bar/column (`c:applyToSides`). */
+  applyToSides?: boolean;
+  /** Apply the picture to the end face of a 3-D bar/column (`c:applyToEnd`). */
+  applyToEnd?: boolean;
+  /** Stretch, or stack repeated tiles at their natural size (or scaled). */
+  pictureFormat?: PptxChartPictureFormat;
+  /** Height, in points, of one repeated picture tile for "stack"/"stackScale" (`c:pictureStackUnit/@val`). */
+  pictureStackUnit?: number;
+  /**
+   * Resolved picture source (a `data:`/`blob:` URL) for the point's sibling
+   * `c:spPr/a:blipFill/a:blip`. Populated by the runtime after relationship
+   * resolution (C2-G9 render half); absent until then, and absent entirely
+   * when the point has no picture fill or the image could not be resolved.
+   */
+  imageUrl?: string;
+}
+//#endregion
 //#region src/core/types/chart-pivot-format.d.ts
 interface PptxChartPivotFormat {
   index: number;
@@ -2299,6 +2456,15 @@ interface PptxChartPageSetup {
   horizontalDpi?: number;
   verticalDpi?: number;
   copies?: number;
+  /**
+   * Custom paper height, used when {@link paperSize} is `0`
+   * (`c:pageSetup/@paperHeight`, ST_PositiveUniversalMeasure, e.g. `"297mm"`).
+   * Kept as the raw measure string rather than converted, matching how the
+   * schema stores it.
+   */
+  paperHeight?: string;
+  /** Custom paper width, used when {@link paperSize} is `0` (`@paperWidth`). */
+  paperWidth?: string;
   /** Original leaf retained for foreign attributes. */
   rawXml?: unknown;
 }
@@ -2330,6 +2496,98 @@ interface PptxChartProtection {
   rawXml?: XmlObject;
 }
 //#endregion
+//#region src/core/types/chart-style-definition.d.ts
+/**
+ * Typed subset of an Office 2013+ chart-style part (`ppt/charts/style#.xml`,
+ * root element `cs:chartStyle`, relationship type
+ * `.../2012/relationships/chartStyle`).
+ *
+ * PowerPoint's Design-tab "Chart Styles" gallery (1-48) writes `c:style/@val`
+ * on the chart part itself (already modeled as `PptxChartStyle.styleId`) and,
+ * for most styles, this SEPARATE part spelling out the per-element
+ * `cs:lnRef`/`cs:fillRef`/`cs:effectRef`/`cs:fontRef`/`cs:defRPr` defaults a
+ * chart element falls back to when its own XML leaves it unstyled. Without
+ * parsing this part, styles beyond the one PowerPoint happens to have baked
+ * inline are visually inert.
+ *
+ * @module pptx-types/chart-style-definition
+ */
+/**
+ * One styled chart-element entry (`cs:title`, `cs:axisTitle`,
+ * `cs:categoryAxis`, ...). Colours are resolved to hex at parse time (scheme
+ * colour references via `cs:fontRef`/`cs:lnRef`/`cs:fillRef` are already
+ * flattened against the theme, matching how classic chart colours resolve
+ * elsewhere in this codebase). Fields are present only when the source XML
+ * carried a value for them.
+ */
+interface PptxChartStylePartEntry {
+  /** Text size in points, from `cs:defRPr/@sz` (hundredths of a point). */
+  fontSize?: number;
+  bold?: boolean;
+  italic?: boolean;
+  /** Resolved text colour: `cs:defRPr/a:solidFill`, or `cs:fontRef`'s scheme colour. */
+  color?: string;
+  /** Resolved line colour from `cs:lnRef`'s scheme colour reference. */
+  lineColor?: string;
+  /** Line width in points, when directly authored (rare; most styles reference a theme line style by index only). */
+  lineWidth?: number;
+  /** Resolved fill colour from `cs:fillRef`'s scheme colour reference. */
+  fillColor?: string;
+}
+/**
+ * Parsed per-element style defaults from a chart-style part. Only the
+ * elements this viewer actually renders distinct defaults for are modeled;
+ * elements PowerPoint's style gallery also styles (data table, trendlines,
+ * up/down bars, ...) are out of scope until a renderer needs them.
+ */
+interface PptxChartStyleDefinition {
+  title?: PptxChartStylePartEntry;
+  axisTitle?: PptxChartStylePartEntry;
+  categoryAxis?: PptxChartStylePartEntry;
+  valueAxis?: PptxChartStylePartEntry;
+  legend?: PptxChartStylePartEntry;
+  dataLabel?: PptxChartStylePartEntry;
+  dataPoint?: PptxChartStylePartEntry;
+  dataPointLine?: PptxChartStylePartEntry;
+  gridlineMajor?: PptxChartStylePartEntry;
+  gridlineMinor?: PptxChartStylePartEntry;
+  chartArea?: PptxChartStylePartEntry;
+  plotArea?: PptxChartStylePartEntry;
+}
+//#endregion
+//#region src/core/types/chart-title.d.ts
+/**
+ * Chart title rich-text run type, split out of `types/chart.ts` (already at
+ * the repo's file-size limit) to keep that module from growing further.
+ *
+ * @module pptx-types/chart-title
+ */
+/**
+ * One run of a chart title's rich text (`c:title/c:tx/c:rich/a:p/a:r`).
+ *
+ * The flat `PptxChartData.title` field only ever captured the FIRST run's
+ * text with no per-run formatting; `titleRuns` (when present) is the
+ * lossless, multi-run replacement parsed from the same `c:rich` body. Absent
+ * when the title has no rich text at all (an empty/auto title, or one
+ * authored as a linked-cell reference).
+ */
+interface PptxChartTitleRun {
+  /** This run's text (`a:t`). */
+  text: string;
+  /** `a:rPr/@_b`. */
+  bold?: boolean;
+  /** `a:rPr/@_i`. */
+  italic?: boolean;
+  /**
+   * Font size in POINTS (`a:rPr/@_sz`, hundredths of a point / 100), matching
+   * `PptxChartLegendTextStyle.fontSize`'s convention rather than the pixel
+   * convention `TextStyle.fontSize` uses for slide text.
+   */
+  fontSize?: number;
+  /** Resolved hex colour (e.g. `"#FF0000"`) from `a:rPr/a:solidFill`. */
+  color?: string;
+}
+//#endregion
 //#region src/core/types/chart-user-shapes.d.ts
 /**
  * Types for chart drawing-overlay shapes (`c:userShapes`).
@@ -2368,8 +2626,16 @@ interface PptxChartUserShapeParagraph {
  * `absSizeAnchor` the extent is {@link ext} in EMU.
  */
 interface PptxChartUserShape {
-  /** Shape kind: text/preset shape, connector, or picture. */
-  kind: 'sp' | 'cxnSp' | 'pic';
+  /**
+   * Shape kind: text/preset shape, connector, picture, a group of the
+   * above (`grpSp`, flattened: each grouped child becomes its own entry
+   * reusing the anchor's own bounding box, an approximation since the
+   * group's internal chOff/chExt transform is not applied), or a bare
+   * placeholder for a `graphicFrame` anchor child (deep content such as a
+   * nested chart or table is out of scope; it only keeps the anchor's
+   * space accounted for instead of the whole overlay disappearing).
+   */
+  kind: 'sp' | 'cxnSp' | 'pic' | 'grpSp' | 'graphicFrame';
   /** Anchor kind that positioned the shape. */
   anchor: 'rel' | 'abs';
   /** Top-left corner as chart-relative fractions (0-1). */
@@ -2470,6 +2736,10 @@ interface PptxChartTrendline {
   displayRSq?: boolean;
   displayEq?: boolean;
   color?: string;
+  /** Trendline width in points (`c:trendline/c:spPr/a:ln/@w`, EMU / 12700). */
+  lineWidth?: number;
+  /** Trendline dash style (`c:trendline/c:spPr/a:ln/a:prstDash/@val`). */
+  lineDashStyle?: string;
   label?: PptxChartTrendlineLabel | null;
 }
 /** Typed, commonly edited properties of `c:trendlineLbl`. */
@@ -2515,6 +2785,10 @@ interface PptxChartErrBars {
   customMinus?: number[];
   noEndCap?: boolean;
   color?: string;
+  /** Error-bar line width in points (`c:errBars/c:spPr/a:ln/@w`, EMU / 12700). */
+  width?: number;
+  /** Error-bar line dash style (`c:errBars/c:spPr/a:ln/a:prstDash/@val`). */
+  dashStyle?: string;
 }
 /**
  * Visibility flags for the chart data table (axes + legend keys).
@@ -2601,6 +2875,8 @@ interface PptxChartDataPoint {
   marker?: PptxChartMarker;
   /** Render a bubble-chart point with a 3-D appearance. */
   bubble3D?: boolean;
+  /** Per-point picture-fill flags (`c:dPt/c:pictureOptions`). */
+  picture?: PptxChartDataPointPicture;
 }
 /** Schema values accepted by `c:dLblPos`. */
 type PptxChartDataLabelPosition = 'bestFit' | 'b' | 'ctr' | 'inBase' | 'inEnd' | 'l' | 'outEnd' | 'r' | 't';
@@ -2619,6 +2895,32 @@ interface PptxChartDataLabel {
   text?: string;
   separator?: string;
   showLeaderLines?: boolean;
+  /**
+   * Per-label number-format override (`c:dLbl/c:numFmt/@formatCode`), taking
+   * precedence over the chart-level {@link PptxChartDataLabelOptions.numberFormat}
+   * and the series' own {@link PptxChartSeries.numberFormat} when set.
+   */
+  numberFormat?: string;
+  /**
+   * Manually dragged label position (`c:dLbl/c:layout/c:manualLayout`), the
+   * same CT_ManualLayout shape used for title/legend/plotArea. `null`
+   * explicitly clears a drag back to the automatic position.
+   */
+  layout?: PptxChartManualLayout | null;
+  /**
+   * This label's own font (`c:dLbl/c:txPr/a:p/a:pPr/a:defRPr`, or ChartEx
+   * `cx:dataLabel/cx:txPr`), taking precedence over the chart/series-level
+   * {@link PptxChartDataLabelOptions.txPr} when set. Reuses the legend
+   * entry's flat text-style shape since both are the same
+   * `.../a:p/a:pPr/a:defRPr` default-run-property style.
+   */
+  txPr?: PptxChartLegendTextStyle;
+  /**
+   * This label's own shape formatting (`c:dLbl/c:spPr`): fill/line colour,
+   * width, and dash style for the label's callout box, taking precedence
+   * over any chart/series-level default when set.
+   */
+  spPr?: PptxChartShapeProps;
 }
 /** Axis number format. */
 interface PptxChartAxisNumFmt {
@@ -2633,6 +2935,16 @@ interface PptxChartDisplayUnitsLabel {
   layout?: PptxChartManualLayout | null;
   /** Label shape formatting. `null` removes `c:spPr`. */
   spPr?: PptxChartShapeProps | null;
+  /**
+   * The label's own run font, when it carries a distinct `txPr` from the
+   * axis's own (ChartEx `cx:unitsLabel/cx:txPr`; classic `c:dispUnitsLbl`
+   * has no equivalent child, so this is only ever populated from a ChartEx
+   * axis).
+   */
+  fontFamily?: string;
+  fontSize?: number;
+  fontBold?: boolean;
+  fontColor?: string;
 }
 /** Axis formatting for category, value, or date axes. */
 interface PptxChartAxisFormatting extends PptxChartAxisLabelFormatting {
@@ -2737,8 +3049,27 @@ interface PptxChartWaterfallOptions {
   /** Whether connector lines are visible between adjacent bars. */
   connectorLines?: boolean;
 }
+/**
+ * A single breakpoint in a ChartEx colour-by-value scale
+ * (`cx:valueColorPositions/cx:colorPosition`). `kind` selects which of
+ * CT_ColorPosition's union members was authored; `value` is absent for
+ * `min`/`max` (they are implicit endpoints) and required otherwise.
+ */
+interface PptxCxValueColorPosition {
+  kind: 'min' | 'max' | 'number' | 'percent';
+  value?: number;
+}
 /** Office 2016 ChartEx geographic series dimensions and layout options. */
 interface PptxChartRegionMapOptions {
+  /**
+   * Colour-by-value gradient stops (`cx:valueColors/cx:colors/cx:color`),
+   * resolved to hex, 2 or 3 entries (matching PowerPoint's two- and
+   * three-colour scale UI). Paired index-for-index with
+   * {@link valueColorPositions} when both are present.
+   */
+  valueColors?: string[];
+  /** Gradient breakpoints for {@link valueColors} (`cx:valueColorPositions`). */
+  valueColorPositions?: PptxCxValueColorPosition[];
   /** Optional provider entity identifiers aligned with categories and values. */
   entityIds?: string[];
   /** Original `cx:pt/@idx` values for category points. */
@@ -2903,6 +3234,20 @@ interface PptxChartDataLabelOptions {
    * Omit to let PowerPoint use the type default.
    */
   position?: PptxChartDataLabelPosition;
+  /**
+   * Chart-level number-format override (`c:dLbls/c:numFmt/@formatCode`),
+   * applied to every label of the series/chart-type unless a per-point
+   * {@link PptxChartDataLabel.numberFormat} overrides it.
+   */
+  numberFormat?: string;
+  /**
+   * Default font for every label at this level (`c:dLbls/c:txPr`, or
+   * ChartEx `cx:dataLabels/cx:txPr`), overridden by a per-point
+   * {@link PptxChartDataLabel.txPr} when set. `c:dLbls` at the chart-type
+   * level and the series level cascade the same way the show flags do
+   * (point > series > chart-type).
+   */
+  txPr?: PptxChartLegendTextStyle;
 }
 /** Typed text defaults for a single chart legend entry. */
 interface PptxChartLegendTextStyle {
@@ -2959,6 +3304,17 @@ interface PptxChartStyle {
   hasDataLabels?: boolean;
   /** Chart-level data-label content/position options (when `hasDataLabels`). */
   dataLabels?: PptxChartDataLabelOptions;
+  /**
+   * Font styling for the chart's own title (`c:title/c:txPr`), edited via
+   * `applyChartTitleStyleToXml` (chart-title-style-serializer.ts). Distinct
+   * from an axis title's styling (`PptxChartAxisFormatting.fontFamily` etc.).
+   */
+  titleFontFamily?: string;
+  titleFontSize?: number;
+  titleFontBold?: boolean;
+  titleFontColor?: string;
+  /** Title text-box fill/border (`c:title/c:spPr`). `null` removes it. */
+  titleSpPr?: PptxChartShapeProps | null;
 }
 /**
  * External data source reference for a chart (c:externalData).
@@ -3128,6 +3484,16 @@ interface PptxChartDateCategories {
  */
 interface PptxChartData {
   title?: string;
+  /**
+   * Rich-text runs of the title, parsed from `c:title/c:tx/c:rich` (issue:
+   * chart title rich text). Lossless multi-run alternative to the flat
+   * {@link title}: when present, the writer serialises every run's own
+   * bold/italic/size/color; when absent, save falls back to the flat
+   * `title` path as before. Only populated for a classic (`c:`) chart's
+   * rich (typed) title, not a ChartEx (`cx:`) title or one authored as a
+   * linked-cell reference.
+   */
+  titleRuns?: PptxChartTitleRun[];
   chartType: PptxChartType;
   categories: string[];
   /**
@@ -3219,8 +3585,10 @@ interface PptxChartData {
   chartRelationshipId?: string;
   /** `null` explicitly removes an existing ChartML data table. */
   dataTable?: PptxChartDataTable | null;
-  dropLines?: PptxChartLineStyle;
-  hiLowLines?: PptxChartLineStyle;
+  /** `null` explicitly removes an existing `c:dropLines` element. */
+  dropLines?: PptxChartLineStyle | null;
+  /** `null` explicitly removes an existing `c:hiLowLines` element. */
+  hiLowLines?: PptxChartLineStyle | null;
   /** `null` explicitly removes an existing up/down-bars container. */
   upDownBars?: PptxChartUpDownBars | null;
   axes?: PptxChartAxisFormatting[];
@@ -3335,10 +3703,45 @@ interface PptxChartData {
   pivotFormats?: PptxChartPivotFormats | null;
   /**
    * Color-map override (`c:clrMapOvr`) carrying 12 attributes that
-   * remap theme colour roles for this chart only. Preserved as a flat
-   * `attribute → value` map for round-trip fidelity.
+   * remap theme colour roles for this chart only. Modeled as a flat
+   * `attribute -> value` map (e.g. `{ bg1: 'lt1', accent1: 'accent2' }`)
+   * so unknown/future attributes round-trip without code changes.
+   * `null` explicitly removes an existing `c:clrMapOvr`; an empty object
+   * is treated the same as `null` on save.
+   */
+  clrMapOvr?: Record<string, string> | null;
+  /**
+   * Whether the chart's own cached numeric values use the 1904 date epoch
+   * (`c:chartSpace/c:date1904/@val`). Independent of, and authoritative over,
+   * any embedded workbook's `workbookPr/@date1904` (a chart can lack an
+   * embedded workbook entirely, or its cache can legitimately differ from the
+   * workbook's current setting). Absent when the source XML omits the
+   * element, in which case the 1900 system applies (the schema default).
    */
-  clrMapOvr?: Record<string, string>;
+  date1904?: boolean;
+  /**
+   * PowerPoint's "Rounded corners" chart-area option
+   * (`c:chartSpace/c:roundedCorners/@val`, default `false`). Absent when the
+   * source XML omits the element.
+   */
+  roundedCorners?: boolean;
+  /**
+   * 3-D chart depth/spacing along the series axis, as a percentage
+   * (`c:gapDepth/@val`, `ST_GapAmount`, 0 through 500). Legal on
+   * `bar3D`/`area3D`/`line3D`/`surface` chart-type containers only. Read-only
+   * for rendering, matching {@link barGapWidth}/{@link barOverlap}: save
+   * round-trips it via the preserved chart XML rather than a typed edit path.
+   */
+  gapDepth?: number;
+  /**
+   * Parsed Office 2013+ chart-style part (`ppt/charts/style#.xml`,
+   * `cs:chartStyle`), providing per-element font/line/fill defaults for
+   * whichever built-in "Chart Styles" gallery entry ({@link PptxChartStyle.styleId})
+   * is active. Absent when the chart has no such part (common for
+   * automation-authored charts, where PowerPoint still implies style 2's
+   * look via its own bundled defaults).
+   */
+  chartStyleDefinition?: PptxChartStyleDefinition;
 }
 //#endregion
 //#region src/core/types/image.d.ts
@@ -3862,6 +4265,52 @@ interface MediaCaptionTrack {
   isDefault?: boolean;
 }
 //#endregion
+//#region src/core/types/smart-art-chrome.d.ts
+/**
+ * Background / outline extracted from `dgm:bg` and `dgm:whole`.
+ *
+ * @example
+ * ```ts
+ * const chrome: PptxSmartArtChrome = {
+ *   backgroundColor: "#F0F0F0",
+ *   outlineColor: "#333333",
+ *   outlineWidth: 1,
+ * };
+ * // => satisfies PptxSmartArtChrome
+ * ```
+ */
+interface PptxSmartArtChrome {
+  /**
+   * Background fill colour (hex). When the real `dgm:bg` fill is a gradient
+   * or pattern (see {@link PptxSmartArtChrome.backgroundFillXml}), this is an
+   * APPROXIMATION (the gradient's first stop, or the pattern's foreground
+   * colour) for a consumer that only wants one display colour, not the full fill.
+   */
+  backgroundColor?: string;
+  /**
+   * Raw `dgm:bg` fill XML, present only when the background is a gradient or
+   * pattern fill (a solid fill is fully captured by {@link PptxSmartArtChrome.backgroundColor}
+   * alone). Round-trip only: `smartart-save-chrome.ts` re-emits this verbatim
+   * instead of flattening the fill to a solid colour on save.
+   */
+  backgroundFillXml?: PptxSmartArtRawBackgroundFill;
+  /** Outline stroke colour (hex). */
+  outlineColor?: string;
+  /** Outline stroke width in points. */
+  outlineWidth?: number;
+}
+/**
+ * A `dgm:bg` fill this viewer doesn't fully model as first-class chrome
+ * (gradient or pattern), preserved verbatim for round-trip. See
+ * {@link PptxSmartArtChrome.backgroundFillXml}.
+ */
+interface PptxSmartArtRawBackgroundFill {
+  /** Local element name of the fill under `dgm:bg` (`gradFill` or `pattFill`). */
+  localName: 'gradFill' | 'pattFill';
+  /** The fill element's own attributes/children, as parsed. */
+  xml: XmlObject;
+}
+//#endregion
 //#region src/core/types/smart-art-constraint-rules.d.ts
 type PptxSmartArtConstraintRelationship = 'self' | 'ch' | 'des';
 type PptxSmartArtConstraintOperator = 'none' | 'equ' | 'gte' | 'lte';
@@ -3960,6 +4409,14 @@ interface PptxSmartArtLayoutNodeShape {
   adjustments?: PptxSmartArtShapeAdjustment[];
   /** `dgm:shape/@hideGeom`: the shape is present only to size text, never painted. */
   hideGeometry?: boolean;
+  /**
+   * `dgm:shape/@lkTxEntry` (CT_Shape, boolean, default false): this node is a
+   * decorative shape that should mirror its paired content node's text
+   * rather than always rendering blank. See `smartart-layout-interpreter-
+   * pyramid.ts`'s `arrangePyramid`, the interpreter's one existing
+   * synthesized-decorative-shape call site.
+   */
+  lkTxEntry?: boolean;
 }
 /** Identity and ordering metadata from DiagramML CT_LayoutNode. */
 interface PptxSmartArtLayoutNode {
@@ -4187,6 +4644,13 @@ interface PptxSmartArtNode {
    * generic cycled palette (see `applySmartArtRoleColors`).
    */
   styleRole?: string;
+  /**
+   * `dgm:prSet/@coherent3DOff` (`CT_ElemPropSet`) resolved from the node's
+   * paired presentation point: when true, this node opts out of the
+   * diagram's overall coherent-3D scene rotation (a `dgm:scene3d`/`dgm:sp3d`
+   * quick-style variation) applied to every other node.
+   */
+  coherent3DOff?: boolean;
   /**
    * Per-run text + run-properties for the node's first paragraph, captured at
    * parse time. When the joined run text still equals {@link text} (the node
@@ -4234,9 +4698,29 @@ interface PptxSmartArtColorListMetadata {
   method?: PptxSmartArtColorApplicationMethod;
   hueDirection?: PptxSmartArtHueDirection;
 }
+/**
+ * A quick-style label's `a:lnRef`/`a:fillRef`/`a:effectRef`/`a:fontRef`
+ * (`CT_ShapeStyle`, the same complex type an ordinary shape's `p:style`
+ * uses), resolved against the theme's `fmtScheme` at parse time instead of
+ * the coarse subtle/moderate/intense enum ({@link PptxSmartArtQuickStyle.effectIntensity}).
+ * Only populated when a theme format scheme was available when the quick
+ * style was parsed. See G13 in the 2026-09 diagram audit.
+ */
+interface PptxSmartArtResolvedStyleRef {
+  fillColor?: string;
+  fillMode?: 'solid' | 'gradient' | 'pattern' | 'none' | 'theme';
+  strokeColor?: string;
+  strokeWidth?: number;
+  /** `a:effectRef`'s theme-resolved outer shadow colour, when the style has one. */
+  shadowColor?: string;
+  /** `a:fontRef`'s theme-resolved typeface (`+mn-lt`/`+mj-lt` -> the theme's actual font). */
+  fontTypeface?: string;
+}
 /** CT_StyleLabel metadata from a quick-style definition. */
 interface PptxSmartArtQuickStyleLabel {
   name: string;
+  /** Theme-resolved `dgm:style` refs for this label's role, when available. */
+  resolvedStyle?: PptxSmartArtResolvedStyleRef;
 }
 /** CT_CTStyleLabel metadata from a color-transform definition. */
 interface PptxSmartArtColorStyleLabel {
@@ -4499,27 +4983,6 @@ interface PptxSmartArtDrawingShape extends PptxCustomPathProperties {
   textFrameWidth?: number;
   textFrameHeight?: number;
 }
-/**
- * Background / outline extracted from `dgm:bg` and `dgm:whole`.
- *
- * @example
- * ```ts
- * const chrome: PptxSmartArtChrome = {
- *   backgroundColor: "#F0F0F0",
- *   outlineColor: "#333333",
- *   outlineWidth: 1,
- * };
- * // => satisfies PptxSmartArtChrome
- * ```
- */
-interface PptxSmartArtChrome {
-  /** Background fill colour (hex). */
-  backgroundColor?: string;
-  /** Outline stroke colour (hex). */
-  outlineColor?: string;
-  /** Outline stroke width in points. */
-  outlineWidth?: number;
-}
 /**
  * Presentation layout variables from `dgm:prSet/dgm:presLayoutVars` (data model)
  * or `dgm:varLst` (layout definition defaults).
@@ -4623,13 +5086,55 @@ interface PptxSmartArtData {
   drawingDirty?: boolean;
 }
 //#endregion
-//#region src/core/types/table.d.ts
+//#region src/core/types/table-style-edit.d.ts
 /**
- * Table types: cell styling, cell data, rows, table data, and the parsed
- * table style map from `ppt/tableStyles.xml`.
+ * A `a:fillRef`/`a:lnRef`/`a:effectRef`-style style-matrix reference: an
+ * index into the theme's format scheme (`a:fmtScheme/a:fillStyleLst`, 1-based
+ * per ECMA-376 §20.1.4.1.12) plus an optional colour transform child.
+ *
+ * Distinct from an already-resolved {@link ParsedTableStyleFill}: a fill ref
+ * points AT a theme style-matrix entry rather than carrying a colour choice
+ * directly, though the two commonly appear together (`<a:fillRef idx="2">
+ * <a:schemeClr val="accent1"/></a:fillRef>`).
  *
- * @module pptx-types/table
+ * @example
+ * ```ts
+ * const ref: ParsedTableFillRef = { idx: 2, color: { schemeColor: 'accent1' } };
+ * // => satisfies ParsedTableFillRef
+ * ```
  */
+interface ParsedTableFillRef {
+  /** 1-based index into the theme format scheme's fill style list. */
+  idx: number;
+  /** Colour transform child (`a:schemeClr`/`a:srgbClr`) applied to the referenced style. */
+  color?: ParsedTableStyleFill;
+}
+/**
+ * One leaf (or `effectDag`-wrapped) node of an `a:effectLst`/`a:effectDag`
+ * effect chain, kept mostly opaque: {@link kind} names the OOXML element so a
+ * consumer can recognise common effects (`outerShdw`, `glow`, `softEdge`,
+ * `reflection`, `blur`, `innerShdw`, `prstShdw`, `fillOverlay`, `alphaModFix`,
+ * `alphaInv`, `grayscl`, `biLevel`, `duotone`, `hsl`, `lum`, `tint`) without
+ * this module re-deriving the full shape-effect taxonomy already modelled on
+ * `ShapeStyle`; {@link xml} preserves the node verbatim for lossless re-emit.
+ *
+ * @example
+ * ```ts
+ * const effect: ParsedTableStyleEffect = {
+ *   kind: 'outerShdw',
+ *   xml: { '@_blurRad': '40000', '@_dist': '20000', '@_dir': '5400000' },
+ * };
+ * // => satisfies ParsedTableStyleEffect
+ * ```
+ */
+interface ParsedTableStyleEffect {
+  /** The OOXML element's local name, e.g. `outerShdw`, `glow`, `softEdge`. */
+  kind: string;
+  /** Verbatim XML node (attributes + children) for lossless round-trip. */
+  xml: XmlObject;
+}
+//#endregion
+//#region src/core/types/table.d.ts
 /**
  * Per-cell visual style for a table cell.
  *
@@ -4666,6 +5171,14 @@ interface PptxTableCellStyle {
    * future expansion alongside the run-properties round-trip path.
    */
   colorXml?: XmlObject;
+  /**
+   * Typed theme colour reference for the cell text colour, set when
+   * {@link colorXml} is a plain `a:schemeClr`. Wins on save, mirroring
+   * `TextStyle.colorRef`. Distinct from {@link ParsedTableStyleFill.schemeColor},
+   * which describes a `ppt/tableStyles.xml` section fill rather than an
+   * individual cell override.
+   */
+  colorRef?: PptxThemeColorRef;
   backgroundColor?: string;
   /**
    * Raw XML colour-choice node preserved from cell `a:tcPr/a:solidFill` for
@@ -4673,6 +5186,12 @@ interface PptxTableCellStyle {
    * {@link backgroundColor} still matches the original colour.
    */
   backgroundColorXml?: XmlObject;
+  /**
+   * Typed theme colour reference for the cell fill, set when
+   * {@link backgroundColorXml} is a plain `a:schemeClr`. Wins on save,
+   * mirroring `ShapeStyle.fillColorRef`.
+   */
+  backgroundColorRef?: PptxThemeColorRef;
   borderColor?: string;
   /** Top border width in px. */
   borderTopWidth?: number;
@@ -4976,6 +5495,24 @@ interface PptxTableData {
   bandColCycle?: number;
   /** Right-to-left table layout from `a:tblPr/@rtl`. */
   rtl?: boolean;
+  /**
+   * `a:tblPr`'s OWN fill (`CT_TableProperties` §21.1.3.15's
+   * `EG_FillProperties`), independent of any `a:tblStyleLst`-referenced style
+   * or that style's `a:tblBg`. Applied as the lowest-priority fill layer,
+   * beneath the table style's `wholeTbl` fill. Real PowerPoint decks route
+   * table appearance through `tableStyleId` instead, so this mainly matters
+   * for non-PowerPoint authoring tools (issue G6).
+   */
+  tableFill?: ParsedTableStyleFill;
+  /**
+   * `a:tblPr`'s own `a:effectLst` (or `a:effectDag`) effect chain,
+   * independent of the referenced table style, decomposed into a typed
+   * sequence of {@link ParsedTableStyleEffect} nodes (issue G6). Each node
+   * keeps its own XML verbatim for lossless round-trip; empty array is
+   * normalised to `undefined` by the parser so `tableEffects` is only ever
+   * present when there is at least one effect.
+   */
+  tableEffects?: ParsedTableStyleEffect[];
 }
 /**
  * A single fill reference within a table style section.
@@ -5097,7 +5634,7 @@ interface ParsedTableStyleText {
  * A single border side within a table style's `a:tcStyle/a:tcBdr`.
  *
  * Corresponds to one of `a:left`, `a:right`, `a:top`, `a:bottom`,
- * `a:insideH`, `a:insideV`, `a:tl2br`, `a:bl2tr` (each a
+ * `a:insideH`, `a:insideV`, `a:tl2br`, `a:tr2bl` (each a
  * `CT_ThemeableLineStyle` wrapping an `a:ln`).
  *
  * @example
@@ -5137,19 +5674,34 @@ interface ParsedTableStyleBorders {
   insideV?: ParsedTableStyleBorder;
   /** Top-left to bottom-right diagonal. */
   tl2br?: ParsedTableStyleBorder;
-  /** Bottom-left to top-right diagonal. */
-  bl2tr?: ParsedTableStyleBorder;
+  /**
+   * Top-right to bottom-left diagonal (`a:tr2bl`, ECMA-376's
+   * `CT_TableCellBorderStyle` sequence: left/right/top/bottom/insideH/
+   * insideV/tl2br/tr2bl). The field keeps its historical `bl2tr` spelling
+   * only in the sense that it names the same geometric anti-diagonal line
+   * (top-right-to-bottom-left and bottom-left-to-top-right describe one
+   * undirected diagonal); the parser accepts the real `a:tr2bl` element and,
+   * leniently, a legacy `a:bl2tr` this app previously wrote (issue G4).
+   */
+  tr2bl?: ParsedTableStyleBorder;
 }
 /**
  * Table background style (CT_TableBackgroundStyle, ECMA-376 §21.1.3.7).
  *
- * Corresponds to the `<a:tblBg>` child of `<a:tblStyle>`. Currently
- * captures only the resolved scheme-fill colour (verbatim XML for fill
- * / effect references is preserved separately by the save path).
+ * Corresponds to the `<a:tblBg>` child of `<a:tblStyle>`. Captures the
+ * resolved scheme-fill colour, an unresolved style-matrix `a:fillRef`, and a
+ * presence flag for effects (verbatim XML for the effect list is preserved
+ * separately by the save path).
  */
 interface ParsedTableBackground {
   /** Solid fill (resolved from `a:fill > a:solidFill > a:schemeClr`). */
   fill?: ParsedTableStyleFill;
+  /**
+   * Style-matrix fill reference (`<a:fillRef idx="N">...</a:fillRef>`),
+   * mutually exclusive with {@link fill} (`a:fill` is the choice sibling of
+   * `a:fillRef` in `CT_TableBackgroundStyle`).
+   */
+  fillRef?: ParsedTableFillRef;
   /** Has an `a:effectLst` child that should be round-tripped. */
   hasEffectLst?: boolean;
 }
@@ -5206,6 +5758,26 @@ interface ParsedTableStyleEntry {
   swCellText?: ParsedTableStyleText;
   neCellText?: ParsedTableStyleText;
   nwCellText?: ParsedTableStyleText;
+  /**
+   * Per-role 3D bevel + lighting from `a:tcStyle/a:cell3D` (CT_Cell3D),
+   * distinct from the per-cell `a:tcPr/a:cell3D` {@link PptxTableCellStyle}
+   * already supports. None of PowerPoint's 74 built-in gallery styles use
+   * this (0 hits in the built-in catalogue), so it only matters for a
+   * hand-authored or third-party table style.
+   */
+  wholeTblCell3D?: PptxTableCell3D;
+  firstRowCell3D?: PptxTableCell3D;
+  lastRowCell3D?: PptxTableCell3D;
+  firstColCell3D?: PptxTableCell3D;
+  lastColCell3D?: PptxTableCell3D;
+  band1HCell3D?: PptxTableCell3D;
+  band2HCell3D?: PptxTableCell3D;
+  band1VCell3D?: PptxTableCell3D;
+  band2VCell3D?: PptxTableCell3D;
+  seCellCell3D?: PptxTableCell3D;
+  swCellCell3D?: PptxTableCell3D;
+  neCellCell3D?: PptxTableCell3D;
+  nwCellCell3D?: PptxTableCell3D;
 }
 /**
  * Map of GUID → table style entry.
@@ -5228,6 +5800,38 @@ interface ParsedTableStyleEntry {
 type ParsedTableStyleMap = Record<string, ParsedTableStyleEntry>;
 //#endregion
 //#region src/core/types/elements.d.ts
+/**
+ * Accessibility metadata from `p:cNvPr/a:extLst`'s "Mark as decorative"
+ * vendor extension (issue G16). PowerPoint's Alt Text pane writes
+ * `a:ext[@uri='{C183D7F6-B498-43B3-948B-1728B52AA6E4}']/adec:decorative
+ * val="1"` when a shape or image is marked decorative; mixed into the
+ * element variants whose `p:cNvPr` that pane covers.
+ */
+interface PptxAccessibilityProperties {
+  /**
+   * Whether the element is marked decorative. When true, alt text /
+   * aria-label / Markdown export should skip describing the element even
+   * when {@link PptxImageProperties.altText} (or similar) is present.
+   */
+  isDecorative?: boolean;
+}
+/**
+ * `a:cNvPicPr/@preferRelativeResize` (issue G13), a picture-only non-visual
+ * property distinct from `a:picLocks`.
+ */
+interface PptxPictureNonVisualProperties {
+  /**
+   * `a:cNvPicPr/@preferRelativeResize` (ST_Boolean, defaults to `true` when
+   * absent). Controls whether a picture's crop rectangle is reinterpreted
+   * relative to the picture's ORIGINAL dimensions or its CURRENT
+   * (already-resized) dimensions when it is resized again after being
+   * cropped. Parsed and round-tripped for now; not yet wired into
+   * resize-after-crop arithmetic (this app always uses current-size
+   * semantics, which only diverges from `preferRelativeResize="0"` on a
+   * second resize after a crop).
+   */
+  preferRelativeResize?: boolean;
+}
 /**
  * A text box — a plain rectangle containing text, typically with no
  * visible fill or stroke.
@@ -5261,7 +5865,7 @@ interface TextPptxElement extends PptxElementBase, PptxTextProperties, PptxShape
  * // => satisfies ShapePptxElement
  * ```
  */
-interface ShapePptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties, PptxCustomPathProperties {
+interface ShapePptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties, PptxCustomPathProperties, PptxAccessibilityProperties {
   type: 'shape';
 }
 /**
@@ -5300,7 +5904,7 @@ interface ConnectorPptxElement extends PptxElementBase, PptxTextProperties, Pptx
  * // => satisfies ImagePptxElement
  * ```
  */
-interface ImagePptxElement extends PptxElementBase, PptxShapeProperties, PptxCustomPathProperties, PptxImageProperties {
+interface ImagePptxElement extends PptxElementBase, PptxShapeProperties, PptxCustomPathProperties, PptxImageProperties, PptxAccessibilityProperties, PptxPictureNonVisualProperties {
   type: 'image';
 }
 /**
@@ -5309,7 +5913,7 @@ interface ImagePptxElement extends PptxElementBase, PptxShapeProperties, PptxCus
  * Functionally identical to {@link ImagePptxElement} but distinguished by
  * the `type` discriminant for semantic clarity.
  */
-interface PicturePptxElement extends PptxElementBase, PptxShapeProperties, PptxCustomPathProperties, PptxImageProperties {
+interface PicturePptxElement extends PptxElementBase, PptxShapeProperties, PptxCustomPathProperties, PptxImageProperties, PptxAccessibilityProperties, PptxPictureNonVisualProperties {
   type: 'picture';
 }
 /**
@@ -5349,6 +5953,13 @@ interface TablePptxElement extends PptxElementBase {
   type: 'table';
   /** Parsed table cell data for editing. */
   tableData?: PptxTableData;
+  /**
+   * Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`, the
+   * same non-visual-properties attribute a picture's alt text comes from.
+   */
+  altText?: string;
+  /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */
+  title?: string;
   /**
    * Unrecognised extensions captured from `a:graphicData/a:extLst` so they
    * round-trip losslessly. See {@link PptxGraphicFrameExtension}.
@@ -5364,6 +5975,10 @@ interface TablePptxElement extends PptxElementBase {
 interface ChartPptxElement extends PptxElementBase {
   type: 'chart';
   chartData?: PptxChartData;
+  /** Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`. */
+  altText?: string;
+  /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */
+  title?: string;
   /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
   extensionXml?: PptxGraphicFrameExtension[];
 }
@@ -5381,6 +5996,10 @@ interface ChartPptxElement extends PptxElementBase {
 interface SmartArtPptxElement extends PptxElementBase {
   type: 'smartArt';
   smartArtData?: PptxSmartArtData;
+  /** Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`. */
+  altText?: string;
+  /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */
+  title?: string;
   /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
   extensionXml?: PptxGraphicFrameExtension[];
 }
@@ -5459,6 +6078,18 @@ interface OlePptxElement extends PptxElementBase {
    * Only meaningful when {@link isLinked} is `true`. ECMA-376 §19.3.1.28.
    */
   oleFollowColorScheme?: 'none' | 'full' | 'textAndBackground';
+  /**
+   * `p:link/@updateAutomatic` (`CT_OleObjectLink`, ECMA-376 §19.3.2.4):
+   * whether a LINKED OLE object refreshes automatically from its source
+   * (PowerPoint's Edit Links dialog "Automatic" vs. "Manual" radio buttons).
+   * Only meaningful when {@link isLinked} is `true`. The schema default is
+   * `false`; `undefined` means the source authored no explicit value.
+   */
+  oleUpdateAutomatic?: boolean;
+  /** Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`. */
+  altText?: string;
+  /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */
+  title?: string;
   /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
   extensionXml?: PptxGraphicFrameExtension[];
 }
@@ -5550,6 +6181,15 @@ interface MediaPptxElement extends PptxElementBase {
    * (`r:embed`). Defaults to embedded when undefined.
    */
   isLinked?: boolean;
+  /**
+   * Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`.
+   * Only populated for the `p:graphicFrame`-shaped (SDK-created) media
+   * form; a `p:pic`-shaped media element's alt text is not currently
+   * parsed (see `PptxHandlerRuntimePictureParsing.ts`).
+   */
+  altText?: string;
+  /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. Same scope note as {@link altText}. */
+  title?: string;
   /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
   extensionXml?: PptxGraphicFrameExtension[];
 }
@@ -6043,12 +6683,63 @@ type PptxAnimationTrigger = 'onClick' | 'onShapeClick' | 'onHover' | 'afterPrevi
  * is preserved alongside other animations.
  */
 type PptxNativeAnimationKind = 'media';
+/**
+ * `p:spTgt/p:graphicEl` (CT_TLGraphicalObjectBuildElement, ECMA-376 S19.5.34):
+ * identifies exactly which series/category/element of a chart or diagram
+ * build a per-stage effect reveals, when a deck authors one effect per stage
+ * instead of a single staged `p:bldGraphic` reveal.
+ */
+interface PptxAnimationGraphicElementTarget {
+  /** Which graphic kind: `p:dgm` (diagram) or `p:chart`. */
+  kind: 'dgm' | 'chart';
+  /** `@_seriesIdx`, 0-based series index, when the target is series-scoped. */
+  seriesIdx?: number;
+  /** `@_categoryIdx`, 0-based category index, when the target is category-scoped. */
+  categoryIdx?: number;
+  /**
+   * `p:dgm/@_id` (CT_TLBuildDiagram, ECMA-376 S19.5.10): the diagram DATA MODEL
+   * point id (`dgm:pt/@modelId`) this per-stage effect reveals, when a
+   * `p:bldDgm` build authors one effect per node instead of a single staged
+   * reveal. `dgm`-kind targets only; a `chart`-kind target never carries this.
+   * Matches `PptxSmartArtNode.id` (parsed from the same `@modelId`), so a
+   * diagram renderer can reveal the exact authored node.
+   */
+  id?: string;
+  /**
+   * `@_bldStep`: `ST_TLChartBuildStep` (`category` / `categoryEl` / `series` /
+   * `seriesEl`) for a `chart`-kind target, or `ST_TLDiagramBuildStep`
+   * (`sp` / `bg`) for a `dgm`-kind target.
+   */
+  bldStep?: string;
+}
+/**
+ * `p:spTgt/p:oleChartEl` (CT_TLOleChartTargetElement, ECMA-376 S19.5.44):
+ * legacy pre-DrawingML OLE Graph chart sub-element targeting.
+ */
+interface PptxAnimationOleChartElementTarget {
+  /** `@_type` (ST_TLOleChartSubelementType): entireChart / series / category / ... */
+  subelementType: string;
+  /** `@_lvl`, optional sub-element level. */
+  level?: number;
+}
 /** A target selected by `p:tgtEl` in the PresentationML timing model. */
 type PptxAnimationTarget = {
   type: 'shape';
   shapeId: string;
   /** Whether `p:spTgt/p:bg` limits the effect to the shape background. */
   backgroundOnly?: boolean;
+  /**
+   * `p:spTgt/p:subSp/@_spid`: the id of a shape NESTED inside the group
+   * named by {@link shapeId} (CT_TLSubShapeId, ECMA-376 S19.5.71).
+   * PowerPoint authors this when a user animates one member of a group
+   * without ungrouping it: `shapeId` stays the outer group's id for
+   * round-trip, but this sub-shape is the real playback target.
+   */
+  subShapeId?: string;
+  /** `p:spTgt/p:graphicEl`: chart/diagram series/category/element target. */
+  graphicElement?: PptxAnimationGraphicElementTarget;
+  /** `p:spTgt/p:oleChartEl`: legacy OLE chart sub-element target. */
+  oleChartElement?: PptxAnimationOleChartElementTarget;
   rawXml?: XmlObject;
 } | {
   type: 'slide';
@@ -6428,6 +7119,74 @@ interface PptxNativeAnimation {
    * PowerPoint that only emit the SMIL-style filter string.
    */
   effectFilter?: PptxAnimationEffectFilter;
+  /**
+   * This effect's own `p:cTn/@_id` (a raw OOXML time-node id, not a shape
+   * id). Lets playback resolve a `p:cond/@tn` dependency (see
+   * {@link AnimationCondition.targetTimeNodeId}) against the SPECIFIC node
+   * it names rather than assuming it is always the positionally-previous
+   * effect. Absent when the node carried no `@_id`.
+   */
+  nodeId?: number;
+  /**
+   * Interpolation mode for this effect's PRIMARY `p:anim`-family behaviour
+   * (the same node {@link keyframes}/{@link attrName} were read from), from
+   * `@_calcmode` (ST_TLAnimateBehaviorCalcMode, ECMA-376 S19.5.2). See
+   * {@link PptxAttributeAnimation.calcMode} for the per-component version.
+   */
+  calcMode?: 'discrete' | 'lin' | 'fmla';
+  /**
+   * `p:cBhvr/@_additive` (ST_TLBehaviorAdditiveType, ECMA-376 S19.5.4):
+   * controls how this behaviour's value composites with sibling behaviours
+   * driving the same attribute on the same target. `sum` accumulates
+   * (e.g. a combined scale+rotate), `repl`/`base`/`none`/`mult` replace or
+   * otherwise combine. Absent means the OOXML default (`base`).
+   */
+  cBhvrAdditive?: 'base' | 'sum' | 'repl' | 'mult' | 'none';
+  /**
+   * `p:cBhvr/@_accumulate` (ST_TLBehaviorAccumulateType): `always` means
+   * each `p:cTn/@repeatCount` repeat starts from the PREVIOUS repeat's end
+   * value (e.g. a 3x Spin totals 1080deg instead of replaying 0-360 three
+   * times); `none` (the OOXML default) resets every repeat.
+   */
+  cBhvrAccumulate?: 'none' | 'always';
+  /**
+   * `p:cBhvr/@_xfrmType` (only meaningful on `p:animMotion`): `point`
+   * (default) or `img`, a legacy compatibility hint. Round-tripped only.
+   */
+  cBhvrXfrmType?: 'point' | 'img';
+  /**
+   * `p:cBhvr/@_override` (ST_TLBehaviorOverrideType): `normal` (default) or
+   * `childStyle`, a legacy compatibility hint. Round-tripped only.
+   */
+  cBhvrOverride?: 'normal' | 'childStyle';
+  /**
+   * `p:set` discrete attribute assignments composed alongside this effect
+   * (ECMA-376 S19.5.79 CT_TLSetBehavior): an instantaneous (non-interpolated)
+   * value change, as opposed to {@link attributeAnimations}'s `p:anim`
+   * keyframe ramps. PowerPoint authors several font-style emphasis effects
+   * this way (Bold Reveal, Underline, Bold Flash, Change Font Size), since
+   * "on/off" or "size N" has nothing to interpolate. Not yet consulted by
+   * shared playback (round-trip/typed-model only so far).
+   */
+  setAnimations?: PptxSetAnimation[];
+}
+/**
+ * One `p:set` discrete (non-interpolated) attribute assignment composed
+ * alongside an authored effect. See {@link PptxNativeAnimation.setAnimations}.
+ *
+ * @see ECMA-376 S19.5.79 CT_TLSetBehavior
+ */
+interface PptxSetAnimation {
+  /** Lowercased target attribute from `p:cBhvr/p:attrNameLst/p:attrName`. */
+  attrName: string;
+  /** Decoded value from `p:to` (same variant shape as a `p:tav/p:val`). */
+  value: string | boolean | number;
+  /** Discriminant indicating which `p:to` child carried the value. */
+  valueType: 'str' | 'bool' | 'int' | 'flt' | 'clr';
+  /** Duration from this behaviour's nested `p:cTn/@dur`. */
+  durationMs?: number;
+  /** Start offset from this behaviour's nested `p:stCondLst`. */
+  delayMs?: number;
 }
 /**
  * Parsed `p:animEffect/@filter` (+ `@transition`) descriptor. ECMA-376
@@ -6494,6 +7253,14 @@ interface PptxAttributeAnimation {
   durationMs?: number;
   /** Start offset from this behaviour's nested `p:stCondLst`. */
   delayMs?: number;
+  /**
+   * Interpolation mode from this behaviour's own `@_calcmode`
+   * (ST_TLAnimateBehaviorCalcMode, ECMA-376 S19.5.2): `discrete` snaps to
+   * each `p:tav` stop with no interpolation, `lin` (the OOXML default)
+   * interpolates linearly, `fmla` evaluates `p:tav/@fmla` (not consulted at
+   * playback here; formulas are round-tripped only). Absent means `lin`.
+   */
+  calcMode?: 'discrete' | 'lin' | 'fmla';
 }
 /** Signed HSL channel deltas parsed from `p:animClr/p:by/p:hsl`. */
 interface PptxHslColorDelta {
@@ -6560,7 +7327,7 @@ interface PptxTextAnimationTarget {
  * These map directly to OOXML condition event attribute values
  * (ISO/IEC 29500-1 S19.5.28 CT_TLTimeCondition).
  */
-type AnimationConditionEvent = 'onBegin' | 'onEnd' | 'begin' | 'end' | 'onClick' | 'onMouseOver' | 'onMouseOut' | 'onNext' | 'onPrev' | 'onStopAudio';
+type AnimationConditionEvent = 'onBegin' | 'onEnd' | 'begin' | 'end' | 'onClick' | 'onMouseOver' | 'onMouseOut' | 'onNext' | 'onPrev' | 'onStopAudio' | 'onDblClick';
 /**
  * Structured representation of a single OOXML animation condition
  * from `p:cond` elements inside `p:stCondLst` or `p:endCondLst`.
@@ -6687,6 +7454,16 @@ interface PptxElementAnimation {
    * OOXML equivalent and is not required for playback.
    */
   soundFileName?: string;
+  /**
+   * Per-build-level timing template(s) from the {@link sequence}'s own
+   * `p:bldP/p:tmplLst` (ECMA-376 §19.5.84), carried over from the loaded
+   * `PptxNativeAnimation.buildTemplates` this element animation was derived
+   * from so a full timing-tree rebuild (`PptxAnimationWriteService`'s
+   * `buildTimingXml`, when the slide had no prior `p:timing`) can re-emit
+   * them instead of silently dropping the deck's authored per-level
+   * defaults. Absent when {@link sequence} carries no such template.
+   */
+  buildTemplates?: PptxTimingTemplate[];
 }
 /**
  * A read-only anchor representing one of the deck's own effect groups: a
@@ -7603,6 +8380,22 @@ interface PptxActiveXControl {
   name?: string;
   /** Shape ID this control is linked to (from @spid). */
   shapeId?: string;
+  /**
+   * `p:control/@showAsIcon` (CT_Control, ECMA-376 S19.3.1.2): whether the
+   * control renders as its static icon rather than its live appearance.
+   * `undefined` when the source authored no explicit value (schema default
+   * `false`).
+   */
+  showAsIcon?: boolean;
+  /**
+   * `p:control/@imgW` in EMU (ST_PositiveCoordinate32): the width the host
+   * reserves for the control's icon/preview image. Distinct from
+   * {@link width}, which is the fallback `p:pic`'s own `a:ext/@cx` in px;
+   * `imgW`/`imgH` are direct attributes on `p:control` itself.
+   */
+  imgWidthEmu?: number;
+  /** `p:control/@imgH` in EMU (ST_PositiveCoordinate32). @see imgWidthEmu */
+  imgHeightEmu?: number;
   /** X position (px) of the control's fallback picture, if present. */
   x?: number;
   /** Y position (px) of the control's fallback picture, if present. */
@@ -7900,10 +8693,32 @@ interface PptxPresentationProperties {
   printProperties?: PptxPresentationPrintProperties | null;
   /** Most-recently-used colours from the presentation palette. */
   mruColors?: string[];
-  /** Pen colour for presentation mode annotations (from `p:showPr/p:penClr`). */
+  /**
+   * Pen colour for presentation mode annotations (from `p:showPr/p:penClr`).
+   * `p:penClr` is a full `EG_ColorChoice` (P1-G2): a scheme/preset/system
+   * swatch resolves to a hex string here just like a direct `a:srgbClr`.
+   */
   penColor?: string;
+  /**
+   * The resolved hex value {@link penColor} had at parse time, and the
+   * original `p:penClr` colour-choice XML node, preserved so a save that
+   * never touches the pen colour re-emits the original scheme/preset
+   * reference verbatim instead of flattening it to a baked `a:srgbClr`.
+   * Internal round-trip bookkeeping; not meant to be set by API callers.
+   */
+  penColorOriginal?: string;
+  /** @see penColorOriginal */
+  penColorXml?: XmlObject;
   /** Kiosk auto-restart interval in milliseconds (from `p:kiosk/@restart`). Only meaningful when showType is "kiosk". */
   kioskRestartTime?: number;
+  /**
+   * `p:showPr/p:browse/@showScrollbar` (CT_ShowInfoBrowse §19.2.1.10 /
+   * §19.3.1.43), the "Show scrollbar" checkbox in PowerPoint's Set Up Show
+   * dialog. Only meaningful when `showType` is `"browsed"`; the schema
+   * default is `true`. `undefined` means the source authored no explicit
+   * value (or `showType` is not `"browsed"`).
+   */
+  showScrollbar?: boolean;
 }
 /**
  * Slide dimensions from `p:sldSz` (CT_SlideSize, ECMA-376 §19.2.1.39).
@@ -8037,6 +8852,34 @@ interface PptxPhotoAlbum {
   layout?: string;
   /** Frame style applied to each photo (e.g. "frameStyle1"). */
   frame?: string;
+  /**
+   * `p:photoAlbum/@isPhoto` (ECMA-376 S19.2.1.27, CT_PhotoAlbum): whether
+   * the pictures placed by the album wizard are real photographs, as
+   * opposed to clip art or other embedded images. `undefined` when the
+   * source authored no explicit value (schema default `false`); this is a
+   * purely declarative wizard-provenance flag, not something this library
+   * gates any layout/frame behaviour on.
+   */
+  isPhoto?: boolean;
+}
+/**
+ * A recognizer-owned `p:smartTags` reference from `presentation.xml`
+ * (CT_SmartTags, ECMA-376 S19.2.1.42): a bare relationship id pointing at a
+ * legacy Office "Smart Tags" recognizer part, distinct from the
+ * user-authored `p:tags` construct (see {@link PptxTagCollection}).
+ *
+ * This library has no data model for recognizer part CONTENT (there is no
+ * way to create, inspect, or edit one through the public API), so this type
+ * only captures enough to preserve an authored reference losslessly: the
+ * relationship id and, when resolvable, the target part path.
+ */
+interface PptxSmartTagsReference {
+  /** Relationship id from `p:smartTags/@r:id`. */
+  relId: string;
+  /** Resolved ZIP path of the referenced recognizer part, when resolvable. */
+  targetPath?: string;
+  /** Raw `p:smartTags` XML retained for lossless round-trip. */
+  rawXml?: XmlObject;
 }
 /**
  * East Asian line-break (kinsoku) settings from `p:kinsoku` in `presentation.xml`.
@@ -8101,6 +8944,13 @@ interface PptxData {
   themeOptions?: PptxThemeOption[];
   /** Parsed table style definitions from `ppt/tableStyles.xml`. */
   tableStyleMap?: ParsedTableStyleMap;
+  /**
+   * The current default table style GUID (`ppt/tableStyles.xml`'s
+   * `a:tblStyleLst/@def`): the style PowerPoint applies to a newly inserted
+   * table. Matches `PptxSaveOptions.tableStylesDefaultId` so a save call
+   * that omits it can fall back to what was loaded.
+   */
+  tableStylesDefaultId?: string;
   /** Whether the presentation is password-protected. */
   isPasswordProtected?: boolean;
   /** Embedded font data (name + binary data URL) extracted from the presentation. */
@@ -8160,6 +9010,14 @@ interface PptxData {
   modifyVerifier?: PptxModifyVerifier;
   /** Photo album metadata from `p:photoAlbum` in `presentation.xml`. */
   photoAlbum?: PptxPhotoAlbum;
+  /**
+   * Legacy Smart Tags recognizer reference from `p:smartTags` in
+   * `presentation.xml`. Read-only: there is no data model for the
+   * recognizer part's own content, so this exists to make the reference
+   * inspectable and to prove it survives a save (the owning part and its
+   * relationship are preserved passively, like any other unmodelled part).
+   */
+  smartTags?: PptxSmartTagsReference;
   /** East Asian line-break settings from `p:kinsoku` in `presentation.xml`. */
   kinsoku?: PptxKinsoku;
   /** Custom XML data parts from `customXml/` in the OPC package. */
@@ -8324,6 +9182,14 @@ type FillInput = {
   type: 'solid';
   color: string;
   opacity?: number;
+  /**
+   * A theme colour to use instead of a plain hex. When set, the shape
+   * saves as `<a:schemeClr>` (e.g. `{ scheme: 'accent1', lumMod: 0.8 }`
+   * for "Accent 1, Lighter 80%") so it keeps following the theme after a
+   * later theme change; `color` still supplies the immediate resolved
+   * hex for renderers that read it directly.
+   */
+  themeColorRef?: PptxThemeColorRef;
 } | {
   type: 'gradient';
   /**
@@ -8359,6 +9225,8 @@ interface StrokeInput {
   opacity?: number;
   join?: 'round' | 'bevel' | 'miter';
   cap?: 'flat' | 'rnd' | 'sq';
+  /** A theme colour for the outline; see {@link FillInput}'s `themeColorRef`. */
+  themeColorRef?: PptxThemeColorRef;
 }
 interface ShadowInput {
   color?: string;
@@ -8375,6 +9243,8 @@ interface TextStyleInput {
   underline?: boolean;
   strikethrough?: boolean;
   color?: string;
+  /** A theme colour for the run; see {@link FillInput}'s `themeColorRef`. */
+  themeColorRef?: PptxThemeColorRef;
   alignment?: 'left' | 'center' | 'right' | 'justify';
   verticalAlignment?: 'top' | 'middle' | 'bottom';
   lineSpacing?: number;
@@ -9002,6 +9872,24 @@ interface PptxHandlerSaveOptions {
    * part untouched.
    */
   tableStyles?: ParsedTableStyleMap;
+  /**
+   * Set `ppt/tableStyles.xml`'s `<a:tblStyleLst @def>` to this style GUID
+   * (normalised to uppercase-with-braces). `undefined` preserves the
+   * existing default; there is no removal form (`@def` is required by the
+   * schema and PowerPoint always points it at a real style). No-op when the
+   * archive has no `ppt/tableStyles.xml`, same as {@link tableStyles}.
+   */
+  tableStylesDefaultId?: string;
+  /**
+   * Style GUIDs to remove from `ppt/tableStyles.xml` entirely, kept as a
+   * separate opt-in list rather than inferred from omission on
+   * {@link tableStyles}: that map is documented as safe to pass a PARTIAL
+   * edit (only the entries a caller actually touched), so treating every
+   * GUID missing from it as "delete this" would silently destroy untouched
+   * styles on an ordinary targeted edit. A GUID here that is also the
+   * current (or newly requested) default is left in place and skipped.
+   */
+  tableStylesToDelete?: string[];
   /**
    * Target output format.
    * - `'pptx'` (default): Standard presentation.