pptx-react-viewer 2.22.0 → 3.0.1

package/dist/viewer/index.d.ts

@@ -743,6 +743,13 @@ interface Pptx3DScene {
  * ```
  */
 interface Pptx3DShape {
+  /**
+   * Position of the shape along the Z axis, in EMU (`a:sp3d/@z`, default 0).
+   * Independent of {@link extrusionHeight}: it moves the whole shape forward
+   * or back in 3D space rather than adding depth to it, most commonly used to
+   * stack several shapes at different depths under one `a:scene3d` camera.
+   */
+  positionZ?: number;
   /** Extrusion height in EMU. */
   extrusionHeight?: number;
   /** Extrusion colour. */
@@ -1283,12 +1290,12 @@ interface TextStyle {
   resolvedParagraphGeometry?: TextStyle;
   fontFamily?: string;
   fontSize?: number;
-  /** When true, renderer should shrink text to fit the shape bounds. */
+  /** When true, some form of autofit is in effect; see {@link autoFitMode} for which. */
   autoFit?: boolean;
   /** Explicit autofit mode from OOXML body properties.
-   * - 'shrink': `a:spAutoFit` — shrink text on overflow
-   * - 'normal': `a:normAutofit` — normal auto-fit (with optional fontScale)
-   * - 'none': `a:noAutofit` — explicitly no auto-fit (text overflows)
+   * - 'shrink': `a:spAutoFit` - resize the SHAPE to fit the text (never the font)
+   * - 'normal': `a:normAutofit` - shrink the TEXT to fit the shape (via `fontScale`/`lnSpcReduction`)
+   * - 'none': `a:noAutofit` - explicitly no auto-fit (text overflows)
    * - undefined: no autofit element present (inherit from layout/master)
    */
   autoFitMode?: 'shrink' | 'normal' | 'none';
@@ -1679,6 +1686,18 @@ interface TextStyle {
   textBodyScene3d?: Pptx3DScene;
   /** Raw `a:scene3d` subtree used to preserve extensions and unmodelled children. */
   textBodyScene3dXml?: XmlObject;
+  /**
+   * `a:bodyPr/a:flatTx` - an explicit "render this text flat" marker. `sp3d`
+   * and `flatTx` are a mutually exclusive OOXML choice (`EG_Text3D`), so a
+   * shape/run that overrides an inherited 3D text body with `<a:flatTx/>`
+   * carries no `text3d` of its own; without this explicit flag a later
+   * inheritance merge has no signal to stop `text3d`/`textBodyScene3d` from
+   * an ancestor (layout/master) leaking back in, the way `noFill` stops an
+   * inherited fill. A renderer must short-circuit 3D-text application
+   * whenever this is `true`, regardless of what `text3d`/`textBodyScene3d`
+   * otherwise hold.
+   */
+  flatText?: boolean;
   /**
    * Raw `<a:extLst>` subtree captured from `<a:bodyPr>`. Preserved verbatim so
    * authored extensions (e.g. content placeholders, custom application data)
@@ -1954,6 +1973,24 @@ interface PptxElementBase {
    * SDK-created elements.
    */
   placeholderType?: string;
+  /**
+   * `p:nvSpPr/p:nvPr/p:ph/@sz` (lower-cased): `"full"`, `"half"`, or
+   * `"quarter"`. Captured on load for round-trip completeness. Per
+   * ECMA-376 §19.3.1.36 (CT_Placeholder) this size hint is only meaningful
+   * when NO `a:xfrm` exists anywhere in the placeholder's inheritance
+   * chain (slide -> layout -> master); every real-world corpus placeholder
+   * that carries `@sz` already has an explicit `a:xfrm` at the master
+   * level, so no renderer currently derives a size from this field.
+   */
+  placeholderSz?: string;
+  /**
+   * `p:nvSpPr/p:nvPr/p:ph/@orient` (only `"vert"` is meaningful per
+   * `ST_Direction`). Captured on load for round-trip completeness. In
+   * practice every placeholder observed with `orient="vert"` also carries
+   * an explicit `a:bodyPr/@vert`, which already drives vertical-text
+   * rendering, so this field is not currently read by any renderer.
+   */
+  placeholderOrient?: 'vert';
   x: number;
   y: number;
   width: number;
@@ -2416,6 +2453,14 @@ interface PptxChartDataTable {
   showVertBorder?: boolean;
   showOutline?: boolean;
   showKeys?: boolean;
+  /** Table border/fill formatting (`c:dTable/c:spPr`). */
+  spPr?: PptxChartShapeProps;
+  /**
+   * Cell text defaults (`c:dTable/c:txPr/a:p/a:pPr/a:defRPr`). Reuses the same
+   * shape as a legend entry's text override since both are a flat paragraph
+   * default-run-property style (size/bold/italic/font/colour).
+   */
+  txPr?: PptxChartLegendTextStyle;
 }
 /**
  * Line appearance for chart helper lines (drop lines, hi-low lines).
@@ -2574,6 +2619,15 @@ interface PptxChart3DSurface {
   thickness?: number;
   spPr?: PptxChartShapeProps;
 }
+/**
+ * One colour band for a surface chart (`c:bandFmts/c:bandFmt`,
+ * ECMA-376 §21.2.2.19 / CT_BandFmt). `index` is the band's position
+ * (`c:idx/@val`) among the value axis's major-unit bands, in authored order.
+ */
+interface PptxChartBandFmt {
+  index: number;
+  spPr?: PptxChartShapeProps;
+}
 /** Office 2016 ChartEx box-and-whisker series layout options. */
 interface PptxChartBoxWhiskerOptions {
   quartileMethod?: 'inclusive' | 'exclusive';
@@ -2989,9 +3043,14 @@ interface PptxChartData {
   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.
+   * Hierarchical category levels in source XML order, for both ChartEx
+   * hierarchy charts (`cx:multiLvlStrRef`) and classic multi-level category
+   * axes (`c:cat/c:multiLvlStrRef`, e.g. a PowerPoint Quarter > Month
+   * grouping). Level 0 contains the leaf labels and remains mirrored by
+   * {@link categories} for consumers that only understand a flat category
+   * axis. Parent (grouping) levels are forward-filled: a blank cache slot
+   * continues the previous group's label, matching how the source stores a
+   * merged category header sparsely.
    */
   categoryLevels?: string[][];
   dateCategories?: PptxChartDateCategories;
@@ -3058,6 +3117,8 @@ interface PptxChartData {
   floor?: PptxChart3DSurface;
   sideWall?: PptxChart3DSurface;
   backWall?: PptxChart3DSurface;
+  /** Per-band surface-chart colour overrides (`c:surfaceChart/c:bandFmts`). */
+  bandFmts?: PptxChartBandFmt[];
   /** External data source reference (c:externalData) linking to an external workbook. */
   externalData?: PptxExternalData;
   /**
@@ -3335,6 +3396,16 @@ interface PptxImageEffects {
     contRawXml?: Record<string, unknown>;
     /** Original effect XML, including foreign attributes. */
     rawXml?: XmlObject;
+    /**
+     * Multiplicative alpha percentage (0..100+), read from a nested
+     * `<a:alphaModFix>` inside `contRawXml` when present - the common
+     * real-world shape of `a:alphaMod` (`<a:cont><a:alphaModFix amt="…"/>
+     * </a:cont>`). Derived/read-only: a renderer multiplies the source alpha
+     * by this, distinct from the top-level {@link alphaModFix} sibling
+     * effect. Not written back independently on save; `contRawXml` is what
+     * round-trips.
+     */
+    amt?: number;
   };
   /** Alpha replace (`a:alphaRepl`) — replaces alpha with the given fixed-percent value (0..100). */
   alphaRepl?: number;
@@ -3379,6 +3450,40 @@ interface PptxImageEffects {
     blend: 'over' | 'mult' | 'screen' | 'darken' | 'lighten';
     /** Raw opaque fill XML preserved for round-trip. */
     fillRawXml?: Record<string, unknown>;
+    /**
+     * Resolved hex colour, when the overlay fill is a plain `a:solidFill`
+     * (the common case for a picture-style colour overlay). `undefined` for
+     * a gradient/pattern/picture overlay fill - see {@link resolvedGradient} /
+     * {@link resolvedPattern} instead. `fillRawXml` still round-trips
+     * losslessly regardless of which of the three resolved.
+     */
+    resolvedColor?: string;
+    /** Resolved opacity (0-1) of the `a:solidFill` overlay colour, when resolved. */
+    resolvedOpacity?: number;
+    /**
+     * Resolved gradient, when the overlay fill is `a:gradFill`. A renderer
+     * composites this as an SVG paint server (`<linearGradient>` /
+     * `<radialGradient>`) rather than a flat flood colour.
+     */
+    resolvedGradient?: {
+      type: 'linear' | 'radial';
+      /** Gradient angle in degrees (`a:lin/@ang`), for a linear gradient. */
+      angle?: number;
+      stops: Array<{
+        color: string;
+        position: number;
+        opacity?: number;
+      }>;
+    };
+    /**
+     * Resolved preset pattern, when the overlay fill is `a:pattFill`. A
+     * renderer composites this as a tiled SVG paint server.
+     */
+    resolvedPattern?: {
+      preset: string;
+      foreground?: string;
+      background?: string;
+    };
   };
   /** Blur (`a:blur`) — radius in EMU and grow flag. */
   blur?: {
@@ -3458,6 +3563,13 @@ interface PptxImageProperties {
   tileFlip?: 'none' | 'x' | 'y' | 'xy';
   /** Image tiling alignment. */
   tileAlignment?: string;
+  /**
+   * Print-resolution hint in DPI (`a:blipFill/@dpi`). PowerPoint records this
+   * when it downsamples an embedded image for a target print quality; it has
+   * no on-screen rendering effect (a `0`/absent value means "use the source
+   * image's native resolution"). Parsed for round-trip / API fidelity only.
+   */
+  dpi?: number;
   /** Image recolour/artistic effect properties. */
   imageEffects?: PptxImageEffects;
   /** Crop-to-shape — CSS clip-path shape name. */
@@ -3638,6 +3750,25 @@ interface PptxSmartArtChoose {
   } | null;
   rawXml?: XmlObject;
 }
+/** A single `dgm:adj/@val` adjustment, keyed by its `@idx` (1-based, like `a:gd`). */
+interface PptxSmartArtShapeAdjustment {
+  index: number;
+  value: number;
+}
+/**
+ * Typed DiagramML CT_Shape data (`dgm:shape`) attached to a layout node: the
+ * per-node preset geometry override real (and third-party/custom) layout
+ * definitions use so a layoutNode can be e.g. an ellipse or a chevron instead
+ * of the arranger family's hardcoded default shape.
+ */
+interface PptxSmartArtLayoutNodeShape {
+  /** `dgm:shape/@type`: a preset geometry name (`roundRect`, `ellipse`, `chevron`, `conn`, ...). */
+  presetGeometry?: string;
+  /** `dgm:adjLst/dgm:adj` entries (adjustment index -> value, as authored). */
+  adjustments?: PptxSmartArtShapeAdjustment[];
+  /** `dgm:shape/@hideGeom`: the shape is present only to size text, never painted. */
+  hideGeometry?: boolean;
+}
 /** Identity and ordering metadata from DiagramML CT_LayoutNode. */
 interface PptxSmartArtLayoutNode {
   name?: string;
@@ -3649,6 +3780,8 @@ interface PptxSmartArtLayoutNode {
   choose?: PptxSmartArtChoose[];
   constraints?: PptxSmartArtConstraint[];
   rules?: PptxSmartArtNumericRule[];
+  /** `dgm:shape`: this node's own preset geometry override, when present. */
+  shape?: PptxSmartArtLayoutNodeShape;
   children?: PptxSmartArtLayoutNode[];
 }
 /** Metadata and root node from DiagramML CT_DiagramDefinition. */
@@ -3772,6 +3905,61 @@ interface PptxSmartArtNodeStyle {
   /** Italic emphasis override for the node's runs. */
   italic?: boolean;
 }
+/**
+ * Manual layout override for a `type="pres"` presentation point, read from its
+ * `dgm:prSet` attributes. PowerPoint writes these when the user drags, resizes,
+ * rotates, or flips a SmartArt node by hand in its own diagram editor; without
+ * them the node silently reverts to its algorithmic position whenever there is
+ * no cached `dsp:` drawing part to fall back on.
+ *
+ * Every field is optional: only the attributes actually present on `prSet` are
+ * populated. Angle and scale/factor units are already normalised to degrees and
+ * plain ratios (a `custScaleX="150000"` becomes `scaleX: 1.5`), so a consumer
+ * never has to know the raw `60000ths-of-a-degree` / `100000ths-of-a-percent`
+ * XML encodings.
+ *
+ * @example
+ * ```ts
+ * const custom: SmartArtNodeCustomLayout = { angle: 15, scaleX: 1.2 };
+ * // => a node manually rotated 15 degrees and widened 20% in PowerPoint
+ * ```
+ */
+interface SmartArtNodeCustomLayout {
+  /** `custAng`: additional rotation in degrees. */
+  angle?: number;
+  /** `custScaleX`: horizontal scale ratio (1 = no change). */
+  scaleX?: number;
+  /** `custScaleY`: vertical scale ratio (1 = no change). */
+  scaleY?: number;
+  /** `custSzX`: horizontal size ratio, layered on top of {@link scaleX}. */
+  sizeX?: number;
+  /** `custSzY`: vertical size ratio, layered on top of {@link scaleY}. */
+  sizeY?: number;
+  /** `custFlipHor`: the node was manually mirrored horizontally. */
+  flipHorizontal?: boolean;
+  /** `custFlipVert`: the node was manually mirrored vertically. */
+  flipVertical?: boolean;
+  /** `custLinFactX`: manual position nudge along X, as a fraction of the container width. */
+  linearFactorX?: number;
+  /** `custLinFactY`: manual position nudge along Y, as a fraction of the container height. */
+  linearFactorY?: number;
+  /**
+   * `custLinFactNeighborX`: spacing compensation applied to a NEIGHBOURING
+   * node when this one is resized. Parsed for round-trip completeness; not
+   * applied by the per-node final transform (it has no effect on this node's
+   * own geometry; folding it into a neighbour's geometry would require
+   * whole-layout awareness the final transform pass does not have).
+   */
+  linearFactorNeighborX?: number;
+  /** `custLinFactNeighborY`: see {@link linearFactorNeighborX} (Y axis). */
+  linearFactorNeighborY?: number;
+  /** `custRadScaleRad`: manual radius scale ratio for a radial/cycle node. */
+  radialScaleRadius?: number;
+  /** `custRadScaleInc`: manual angular-position nudge for a radial/cycle node. */
+  radialScaleIncrement?: number;
+  /** `custT`: whether `prSet` declares a custom transform is present at all. */
+  hasCustomTransform?: boolean;
+}
 /**
  * A single node in the SmartArt data model.
  *
@@ -3797,6 +3985,16 @@ interface PptxSmartArtNode {
   children?: PptxSmartArtNode[];
   /** Node type from `@_type` attribute (e.g. "doc", "node", "asst", "pres"). */
   nodeType?: string;
+  /**
+   * The node's own quick-style role (`dgm:prSet/@presStyleLbl` from its
+   * paired `type="pres"` presentation point, resolved via a `presOf`
+   * connection back to this content point). Structural names like `node1`,
+   * `asst2`, `bgShp`, `revTx`; distinct from {@link nodeType}, which is the
+   * data-model `@_type` ("node"/"asst"/...). Used to pick this node's own
+   * colour list from a colour transform's per-role palettes instead of the
+   * generic cycled palette (see `applySmartArtRoleColors`).
+   */
+  styleRole?: string;
   /**
    * 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
@@ -3817,6 +4015,14 @@ interface PptxSmartArtNode {
    * it round-trips.
    */
   style?: PptxSmartArtNodeStyle;
+  /**
+   * Manual layout override read from the node's `dgm:prSet` `cust*`
+   * attributes (drag/resize/rotate/flip performed in PowerPoint's own diagram
+   * editor). Applied as a final transform after algorithmic layout by
+   * {@link module:smartart-layout-interpreter-custom} so it survives even
+   * when there is no cached `dsp:` drawing to fall back on.
+   */
+  customLayout?: SmartArtNodeCustomLayout;
 }
 //#endregion
 //#region src/core/types/smart-art-style-definition.d.ts
@@ -3879,6 +4085,18 @@ interface PptxSmartArtColorTransform extends PptxSmartArtDefinitionMetadata {
   lineInterpolation?: PptxSmartArtColorListMetadata;
   /** Ordered CT_CTStyleLabel metadata. */
   labels?: PptxSmartArtColorStyleLabel[];
+  /**
+   * Every `styleLbl`'s own resolved fill/line colour list, keyed by name
+   * (e.g. `node1`, `asst0`, `bgShp`, `revTx`). Unlike {@link fillColors} /
+   * {@link lineColors} (which collapse to ONE "primary" node-role list),
+   * this keeps every role so a node can be coloured from its OWN role's
+   * palette (see `PptxSmartArtNode.styleRole` and `applySmartArtRoleColors`)
+   * instead of a generic cycled colour.
+   */
+  roleColors?: Record<string, {
+    fill: string[];
+    line: string[];
+  }>;
 }
 /** Typed CT_StyleDefinition metadata and legacy rendering hint. */
 interface PptxSmartArtQuickStyle extends PptxSmartArtDefinitionMetadata {
@@ -3963,6 +4181,14 @@ interface PptxSmartArtConnection {
   siblingTransitionId?: string | null;
   /** Layout presentation identifier used by presentation connections. */
   presentationId?: string | null;
+  /**
+   * Connector text, read from the linked `parTrans`/`sibTrans` transition
+   * point's `dgm:t` (via {@link parentTransitionId} / {@link siblingTransitionId}).
+   * PowerPoint's own diagram editor lets a user type text directly onto an
+   * org-chart relationship connector; `undefined` when the transition point
+   * carries no text. Written back to that point on save.
+   */
+  label?: string;
 }
 /**
  * A pre-computed shape from `ppt/diagrams/drawing*.xml`.
@@ -4283,8 +4509,8 @@ interface PptxTableCellStyle {
   textGlowRadius?: number;
   /** Cell text glow opacity (0-1). */
   textGlowOpacity?: number;
-  /** Cell fill mode: solid, gradient, pattern, or none. */
-  fillMode?: 'solid' | 'gradient' | 'pattern' | 'none';
+  /** Cell fill mode: solid, gradient, pattern, image, or none. */
+  fillMode?: 'solid' | 'gradient' | 'pattern' | 'image' | 'none';
   /** Gradient fill stops (colours with positions). */
   gradientFillStops?: Array<{
     color: string;
@@ -4317,6 +4543,23 @@ interface PptxTableCellStyle {
   patternFillForeground?: string;
   /** Pattern fill background colour. */
   patternFillBackground?: string;
+  /**
+   * Image fill (`a:tcPr/a:blipFill`, CT_TableCellProperties). Resolved
+   * archive-relative path (or external `http(s):`/`data:` URL) for the
+   * cell's background image, from `a:blipFill/a:blip/@r:embed` (or
+   * `@r:link`). Present when `fillMode` is `'image'`.
+   *
+   * The parser resolves this synchronously (path only, no binary read);
+   * a viewer's load pipeline resolves it further to a displayable
+   * `data:`/`blob:` URL, written back to {@link backgroundImageFillData}.
+   */
+  backgroundImageFillPath?: string;
+  /**
+   * Displayable image data (`data:` or `blob:` URL) for an image cell
+   * fill, once resolved by the load pipeline. Renderers should prefer
+   * this over {@link backgroundImageFillPath} when both are present.
+   */
+  backgroundImageFillData?: string;
   /**
    * Cell 3D bevel + lighting from `a:tcPr/a:cell3D` (CT_Cell3D,
    * ECMA-376 §21.1.3.1). Rendered as a CSS bevel treatment.
@@ -4542,6 +4785,24 @@ interface ParsedTableStyleFill {
   gradient?: ParsedTableStyleGradient;
   /** Preset pattern fill parsed from `a:pattFill`. */
   pattern?: ParsedTableStylePattern;
+  /** Image texture fill parsed from `a:blipFill`. */
+  image?: ParsedTableStyleImage;
+}
+/**
+ * An image texture fill parsed from a table style section's `a:blipFill`.
+ *
+ * `ppt/tableStyles.xml` is a presentation-level part parsed once (not
+ * per-slide), so this mirrors the per-CELL `a:tcPr/a:blipFill` two-field lazy
+ * pattern (`PptxTableCellStyle.backgroundImageFillPath` /
+ * `backgroundImageFillData`): `path` starts out as a raw archive-relative
+ * path (or an already-external `http(s):`/`data:` URL), and a load pipeline
+ * patches it to a displayable URL in `data` once resolved.
+ */
+interface ParsedTableStyleImage {
+  /** Archive-relative path, or an already-displayable external/data URL. */
+  path?: string;
+  /** Displayable URL once a load pipeline has resolved `path`. */
+  data?: string;
 }
 /** A single colour stop within a {@link ParsedTableStyleGradient}. */
 interface ParsedTableStyleGradientStop {
@@ -4968,6 +5229,12 @@ interface OlePptxElement extends PptxElementBase {
   oleEmbeddedMimeType?: string;
   /** Size of the embedded payload in bytes. */
   oleEmbeddedByteSize?: number;
+  /**
+   * `p:link/@followColorScheme` (`ST_OleObjectFollowColorScheme`): whether a
+   * LINKED OLE object's icon recolours to match the presentation theme.
+   * Only meaningful when {@link isLinked} is `true`. ECMA-376 §19.3.1.28.
+   */
+  oleFollowColorScheme?: 'none' | 'full' | 'textAndBackground';
   /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
   extensionXml?: PptxGraphicFrameExtension[];
 }
@@ -5269,6 +5536,16 @@ interface PptxNotesMaster {
   headerFooter?: PptxHeaderFooterFlags;
   /** Colour map from `<p:clrMap>` (12 alias attributes). Applied at save time. */
   clrMap?: Record<string, string>;
+  /**
+   * Notes text defaults from `<p:notesStyle>` (`CT_TextListStyle`, ECMA-376
+   * §19.3.1.34): the same `a:defPPr` + `a:lvl1pPr`..`a:lvl9pPr` shape as
+   * {@link PptxMasterTextStyles}'s per-category styles, keyed 0-8 with the
+   * default at `-1`. Governs the notes body placeholder's font size, indent
+   * levels, and bullet style wherever a notes slide does not override them.
+   * Parsed read-only for the render cascade; the save side preserves the
+   * original `<p:notesStyle>` XML verbatim rather than re-serialising this.
+   */
+  notesStyle?: PptxTextStyleLevels;
 }
 /**
  * Parsed handout master from `ppt/handoutMasters/handoutMaster1.xml`.
@@ -5342,6 +5619,14 @@ interface PptxSlideMaster {
    * accent1-6, hlink, folHlink). Applied at save time when present.
    */
   clrMap?: Record<string, string>;
+  /**
+   * Whether the master is marked as preserved (prevent auto-deletion,
+   * `@preserve`). Mirrors {@link PptxSlideLayout.preserve}: PowerPoint
+   * silently drops an unused master unless this is set.
+   *
+   * ECMA-376 §19.3.1.38 (CT_SlideMaster).
+   */
+  preserve?: boolean;
 }
 /**
  * Per-level paragraph properties for a text style category.
@@ -5531,6 +5816,35 @@ type PptxGraphicBuild = {
   animateBackground: boolean;
   rawXml?: XmlObject;
 };
+/**
+ * A single `p:tmpl` timing template parsed from a TEXT `p:bldP/p:tmplLst`
+ * (CT_TLTemplate, ECMA-376 §19.5.85; the list itself is CT_TLTemplateList,
+ * §19.5.84).
+ *
+ * PowerPoint writes these as the timing PowerPoint would apply to a build
+ * level that does not yet have an instantiated effect, so that promoting or
+ * demoting an outline paragraph, or adding a new bullet at a level with no
+ * prior animation, has a default to clone. They are not consulted at
+ * playback: the animation actually shown for every paragraph level already
+ * visible on the slide is the real, instantiated `p:tnLst` under
+ * `p:timing/p:tnLst`, which the rest of this parser already models in full.
+ *
+ * The nested time-node tree under each template's own `p:tnLst` is kept as
+ * a preserved `XmlObject` rather than deep-parsed into
+ * {@link PptxNativeAnimation} records: it is schema-identical to the
+ * top-level timing tree but scoped to a template that is never itself
+ * executed, so structurally modelling it would stand up a second, unused
+ * parallel animation model. Parsing stops at typed round-trip; see
+ * `docs/guide/limitations.md`.
+ */
+interface PptxTimingTemplate {
+  /** Build level this template targets, from `p:tmpl/@lvl` (ST_TLLevel, default 0). */
+  level: number;
+  /** Preserved `p:tnLst` (CT_TimeNodeList) subtree, verbatim. */
+  timeNodeList: XmlObject;
+  /** Preserved `p:tmpl` XML node (its attributes plus any unmodelled children). */
+  rawXml?: XmlObject;
+}
 /**
  * Parsed native animation record from `p:timing / p:tnLst`.
  *
@@ -5641,6 +5955,58 @@ interface PptxNativeAnimation {
   soundPath?: string;
   /** Whether to stop any currently playing sound (`p:endSnd`). */
   stopSound?: boolean;
+  /**
+   * End-state behaviour from `p:cTn/@fill` (ST_TLTimeNodeFillType, ECMA-376
+   * §19.5.27). `hold`/`freeze` mean the effect's final frame persists after
+   * it finishes; `remove` (the default when absent) means the target reverts
+   * to its pre-effect appearance. `transition` behaves like `hold` until the
+   * next time node starts. Absent means the OOXML default (`remove`).
+   */
+  fill?: 'remove' | 'freeze' | 'hold' | 'transition';
+  /**
+   * Restart behaviour from `p:cTn/@restart` (ST_TLTimeNodeRestartType).
+   * Absent means the OOXML default (`always`).
+   */
+  restart?: 'always' | 'whenNotActive' | 'never';
+  /**
+   * Repeat duration in milliseconds from `p:cTn/@repeatDur`. `Infinity`
+   * represents the literal `"indefinite"` token.
+   */
+  repeatDurMs?: number;
+  /**
+   * Playback speed multiplier from `p:cTn/@spd` (ST_Percentage, normalized
+   * from OOXML's 1000ths-of-a-percent storage to a plain percentage, e.g.
+   * `150` for 150% / double speed). Absent means normal (100%) speed.
+   */
+  speedPct?: number;
+  /**
+   * Reverse the paragraph build order from `p:bldP/@rev` (TEXT build only).
+   * Not to be confused with {@link PptxGraphicBuild}'s `reverse` field, which
+   * carries the unrelated `p:bldDgm`/`@rev` DIAGRAM-build reverse flag.
+   */
+  buildReverse?: boolean;
+  /**
+   * Auto-advance time in milliseconds from `p:bldP/@advAuto`. `Infinity`
+   * represents the literal `"indefinite"` token. Absent means the build
+   * step waits for a click.
+   */
+  buildAdvAutoMs?: number;
+  /**
+   * Per-build-level timing templates from a TEXT `p:bldP/p:tmplLst`
+   * (ECMA-376 §19.5.84 CT_TLTemplateList). Parsed for round-trip only; see
+   * {@link PptxTimingTemplate} for why they are not consulted at playback.
+   */
+  buildTemplates?: PptxTimingTemplate[];
+  /**
+   * Whether the enclosing `p:seq` allows concurrent play with its siblings,
+   * from `p:seq/@concurrent`. Parsed for round-trip; not yet honoured by
+   * playback (see `docs/guide/limitations.md`).
+   */
+  seqConcurrent?: boolean;
+  /** Next-action behaviour from `p:seq/@nextAc` (ST_TLNextActionType). */
+  seqNextAction?: 'none' | 'seek';
+  /** Previous-action behaviour from `p:seq/@prevAc` (ST_TLPreviousActionType). */
+  seqPrevAction?: 'none' | 'skipTimeNode';
   /**
    * Whether the enclosing click-level group (a direct `p:par` child of the
    * `mainSeq`) begins automatically when the slide appears, rather than waiting
@@ -5731,6 +6097,55 @@ interface PptxNativeAnimation {
    * subsequent peer nodes are sequenced when serialised back to OOXML.
    */
   afterEffect?: boolean;
+  /**
+   * "After animation" end-state behaviour carried over from the matching
+   * {@link PptxElementAnimation.afterAnimation} entry for this effect's
+   * element. Not populated by the native-timing parser itself (there is no
+   * single `p:cTn` attribute for it): `applyAfterAnimationFromEditorList` in
+   * `pptx-viewer-shared` merges it in from the editor's per-element
+   * animation list before playback, since that is the model the animation
+   * panel writes `afterAnimation` into.
+   */
+  afterAnimationAction?: PptxAfterAnimationAction;
+  /** Dim-to color hex, present when {@link afterAnimationAction} is `dimToColor`. */
+  afterAnimationColor?: string;
+  /**
+   * Parsed `p:animEffect` filter descriptor. `presetId`/`presetClass` remain
+   * the primary effect selector (see `resolveEffect` in `pptx-viewer-shared`);
+   * this is the fallback used when a preset table lookup misses (unmapped or
+   * absent `presetId`), which happens for decks authored by tools other than
+   * PowerPoint that only emit the SMIL-style filter string.
+   */
+  effectFilter?: PptxAnimationEffectFilter;
+}
+/**
+ * Parsed `p:animEffect/@filter` (+ `@transition`) descriptor. ECMA-376
+ * describes `@filter` as a free-form string of the form `family(subtype)`,
+ * optionally followed by `;`-separated fallback candidates (only the first
+ * is honoured, per ECMA-376 S19.5.3's "first supported filter wins" rule).
+ *
+ * @example
+ * ```ts
+ * const f: PptxAnimationEffectFilter = { family: 'wipe', subtype: 'up', transition: 'in', raw: 'wipe(up)' };
+ * ```
+ */
+interface PptxAnimationEffectFilter {
+  /** Filter family name (e.g. `"wipe"`, `"barn"`, `"checkerboard"`), lowercased. */
+  family: string;
+  /**
+   * Parenthesised subtype/direction token verbatim (e.g. `"up"`,
+   * `"inVertical"`, `"across"`, `"4"`). Absent when the filter has no
+   * subtype (e.g. bare `"dissolve"`).
+   */
+  subtype?: string;
+  /**
+   * `p:animEffect/@transition`: `"in"` reveals the target (the OOXML
+   * default when the attribute is omitted), `"out"` conceals it, `"none"`
+   * applies the filter without a visibility change (a static filter pass).
+   */
+  transition?: 'in' | 'out' | 'none';
+  /** Raw filter string exactly as authored, for round-trip/debugging. */
+  raw: string;
 }
 /**
  * Single keyframe parsed from a `p:tav` element (CT_TLTimeAnimateValue).
@@ -6885,10 +7300,12 @@ interface PptxSlide {
    */
   backgroundPattern?: PptxSlideBackgroundPattern;
   /**
-   * `<p:bgPr/@shadeToTitle>` — boolean flag instructing the renderer to
+   * `<p:bgPr/@shadeToTitle>`: boolean flag instructing the renderer to
    * shade the background toward the title placeholder colour. Captured
-   * for lossless round-trip; the React renderer currently treats it as
-   * a passthrough hint.
+   * for lossless round-trip only; no renderer applies the visual effect.
+   * Documented as a known no-op in `docs/guide/limitations.md` (legacy
+   * PowerPoint 97-2003 hint, not observed in any real-world corpus file
+   * and not settable from any modern PowerPoint UI).
    *
    * ECMA-376 §19.3.1.2 (CT_BackgroundProperties).
    */
@@ -6927,6 +7344,13 @@ interface PptxSlide {
   backgroundShowAnimation?: boolean;
   /** Whether master slide shapes should be shown on this slide (`p:sld/@showMasterSp`). */
   showMasterShapes?: boolean;
+  /**
+   * Whether inherited master placeholder animations should replay on this
+   * slide (`p:sld/@showMasterPhAnim`). Distinct from {@link showMasterShapes}:
+   * this governs animation timing, not shape visibility. Mirrors
+   * `p:sldLayout/@showMasterPhAnim`, ECMA-376 §19.3.1.38.
+   */
+  showMasterPhAnim?: boolean;
   /** Drawing guides parsed from slide extension list. */
   guides?: PptxDrawingGuide[];
   /** When explicitly `false`, the slide is unmodified and save can skip re-serialization. */
@@ -7052,11 +7476,6 @@ interface PptxPresentationProperties {
   printProperties?: PptxPresentationPrintProperties | null;
   /** Most-recently-used colours from the presentation palette. */
   mruColors?: string[];
-  /** Grid spacing in EMUs (cx, cy). Default is 914400 / 8 = 114300. */
-  gridSpacing?: {
-    cx: number;
-    cy: number;
-  };
   /** Pen colour for presentation mode annotations (from `p:showPr/p:penClr`). */
   penColor?: string;
   /** Kiosk auto-restart interval in milliseconds (from `p:kiosk/@restart`). Only meaningful when showType is "kiosk". */
@@ -7264,6 +7683,29 @@ interface PptxData {
   embeddedFonts?: PptxEmbeddedFont[];
   /** Typed `p:embeddedFontLst` package metadata, including unresolved variants. */
   embeddedFontList?: PptxEmbeddedFontList;
+  /**
+   * `p:presentation/@embedTrueTypeFonts` (ECMA-376 §19.2.1.26): the author's
+   * saved preference that TrueType fonts referenced by the deck be embedded.
+   * `undefined` when the attribute is absent (spec default `false`).
+   *
+   * This is purely declarative in this library: fonts are only ever embedded
+   * when the caller explicitly supplies `embeddedFontList`/`embeddedFonts`
+   * (there is no automatic embed-on-save), so toggling this flag does not
+   * gate any embedding behaviour of its own here - it only round-trips the
+   * author's stated preference, the same way real PowerPoint reads it back
+   * as a checkbox state rather than a trigger. See `@saveSubsetFonts`,
+   * which is a separate, deliberately unimplemented flag (no glyph
+   * subsetting) that does not interact with this one.
+   */
+  embedTrueTypeFonts?: boolean;
+  /**
+   * Presentation-level default text style (`p:defaultTextStyle`): the
+   * last-resort paragraph/run-property fallback for every shape (placeholder
+   * or not) whose local and inherited cascade leaves a field undefined.
+   * Keyed the same way as {@link PptxMasterTextStyles} categories: `-1` is
+   * `a:defPPr`, `0`-`8` are `a:lvl1pPr`-`a:lvl9pPr`.
+   */
+  defaultTextStyle?: PptxTextStyleLevels;
   /** Most-recently-used colour list from presentation properties. */
   mruColors?: string[];
   /** Parsed notes master data if present in the PPTX. */
@@ -8113,6 +8555,19 @@ interface PptxHandlerSaveOptions {
   kinsoku?: PptxKinsoku | null;
   /** Write-protection verifier. Set to `null` to remove, `undefined` to preserve existing. */
   modifyVerifier?: PptxModifyVerifier | null;
+  /**
+   * `p:presentation/@embedTrueTypeFonts` to write. `undefined` preserves
+   * whatever was loaded (or omits the attribute for a brand-new deck);
+   * purely declarative here, see {@link PptxData.embedTrueTypeFonts}.
+   */
+  embedTrueTypeFonts?: boolean;
+  /**
+   * Presentation-level default text style edits to save back to
+   * `p:defaultTextStyle`. Only the levels present in the map are touched;
+   * omitted levels and any unmodelled XML on an edited level survive
+   * untouched. See {@link PptxData.defaultTextStyle}.
+   */
+  defaultTextStyle?: PptxTextStyleLevels;
   /** View properties to save back to ppt/viewProps.xml. */
   viewProperties?: PptxViewProperties;
   /**