pptx-react-viewer 4.8.0 → 4.9.0

package/dist/index.d.ts

@@ -1971,6 +1971,16 @@ interface TextStyle {
   textReflectionEndOpacity?: number;
   /** Text reflection offset distance in px. */
   textReflectionOffset?: number;
+  /**
+   * Text reflection end position (`@endPos`) as a 0-1 fraction of the text
+   * height the fade reaches. Mirrors `ShapeStyle.reflectionEndPosition`.
+   */
+  textReflectionEndPosition?: number;
+  /**
+   * Text reflection offset direction (`@dir`) in degrees. Mirrors
+   * `ShapeStyle.reflectionDirection`.
+   */
+  textReflectionDirection?: number;
   /**
    * Text reflection fade direction (`a:rPr/a:effectLst/a:reflection/@fadeDir`)
    * in degrees. Mirrors `ShapeStyle.reflectionFadeDirection`.
@@ -2289,6 +2299,21 @@ interface TextSegment {
    * populated; unrelated fields fall back to the shape-level style.
    */
   paragraphProperties?: TextStyle;
+  /**
+   * The paragraph this segment starts authored an EMPTY `<a:pPr/>`. Only
+   * meaningful on the first segment of a paragraph. The writer re-emits the
+   * empty element when it has no paragraph property of its own to write, so
+   * a rewritten slide keeps the markup PowerPoint wrote.
+   */
+  emptyParagraphPropertiesAuthored?: boolean;
+  /**
+   * The paragraph this segment starts has no run content and authored no
+   * `a:endParaRPr` (a bare `<a:p/>`, possibly with an `a:pPr`). Only
+   * meaningful on the first segment of a paragraph. It stops the writer
+   * inventing an empty run or an `<a:endParaRPr lang="en-US"/>` stub for a
+   * paragraph that still has no content when saved.
+   */
+  bareParagraph?: boolean;
   /**
    * Phonetic annotation text from `a:ruby > a:rt` (e.g. furigana, pinyin).
    * When present, the renderer should wrap the base text with an HTML `<ruby>` tag.
@@ -7883,6 +7908,84 @@ interface PptxThemeOption {
   name?: string;
 }
 //#endregion
+//#region src/core/types/animation-behavior.d.ts
+/** Timing of one behaviour, from its own `p:cBhvr/p:cTn`. */
+interface PptxAnimationBehaviorTiming {
+  /** `p:cTn/@dur` in ms; absent when `indefinite` or unset. */
+  durationMs?: number;
+  /** Start offset in ms from `p:stCondLst/p:cond/@delay`, relative to the effect start. */
+  delayMs?: number;
+  /** `p:cTn/@accel` as a 0..1 fraction of the behaviour's duration. */
+  accel?: number;
+  /** `p:cTn/@decel` as a 0..1 fraction of the behaviour's duration. */
+  decel?: number;
+  /** `p:cTn/@autoRev`: play forward, then backward, doubling the active time. */
+  autoReverse?: boolean;
+  /** `p:cTn/@repeatCount` in plain iterations (OOXML stores thousandths). */
+  repeatCount?: number;
+  /** `p:cTn/@tmFilter`: the raw `"t,v; t,v; ..."` time remapping list. */
+  tmFilter?: string;
+}
+interface BehaviorBase {
+  /** Lower-cased `p:attrNameLst` entries, in document order. */
+  attrNames: string[];
+  /** `p:cBhvr/@additive` (`base`, `sum`, `repl`, `mult`, `none`). */
+  additive?: string;
+  timing: PptxAnimationBehaviorTiming;
+}
+/** `p:set`: a discrete value held from the behaviour's start. */
+interface PptxSetBehavior extends BehaviorBase {
+  kind: 'set';
+  value: string | number | boolean;
+}
+/** `p:anim`: a `p:tavLst` ramp or a `from`/`to`/`by` formula ramp. */
+interface PptxAnimBehavior extends BehaviorBase {
+  kind: 'anim';
+  calcMode?: 'discrete' | 'lin' | 'fmla';
+  valueType?: string;
+  from?: string;
+  to?: string;
+  by?: string;
+  keyframes: PptxAnimationKeyframe[];
+}
+/** `p:animEffect`: a filter transition (`fade`, `wipe(down)`...). */
+interface PptxAnimEffectBehavior extends BehaviorBase {
+  kind: 'animEffect';
+  filter?: string;
+  transition?: 'in' | 'out' | 'none';
+}
+/** A `p:animScale` factor pair (1 = unscaled) or a `p:animMotion` offset (slide fractions). */
+interface PptxBehaviorPoint {
+  x: number;
+  y: number;
+}
+/** `p:animScale`: scale factors as fractions (OOXML stores percent*1000, so `100000` = 1). */
+interface PptxAnimScaleBehavior extends BehaviorBase {
+  kind: 'animScale';
+  from?: PptxBehaviorPoint;
+  to?: PptxBehaviorPoint;
+  by?: PptxBehaviorPoint;
+  zoomContents?: boolean;
+}
+/** `p:animRot`: rotation in degrees (OOXML stores 60000ths). */
+interface PptxAnimRotBehavior extends BehaviorBase {
+  kind: 'animRot';
+  from?: number;
+  to?: number;
+  by?: number;
+}
+/** `p:animMotion`: a path (slide fractions) or a `from`/`to`/`by` offset. */
+interface PptxAnimMotionBehavior extends BehaviorBase {
+  kind: 'animMotion';
+  path?: string;
+  origin?: string;
+  from?: PptxBehaviorPoint;
+  to?: PptxBehaviorPoint;
+  by?: PptxBehaviorPoint;
+}
+/** One behaviour child of an effect, tagged by its OOXML element. */
+type PptxAnimationBehavior = PptxSetBehavior | PptxAnimBehavior | PptxAnimEffectBehavior | PptxAnimScaleBehavior | PptxAnimRotBehavior | PptxAnimMotionBehavior;
+//#endregion
 //#region src/core/types/animation.d.ts
 /**
  * Built-in animation preset names used for entrance, exit, and emphasis effects.
@@ -8434,6 +8537,14 @@ interface PptxNativeAnimation {
    * shared playback (round-trip/typed-model only so far).
    */
   setAnimations?: PptxSetAnimation[];
+  /**
+   * Every behaviour child of this effect (`p:set`, `p:anim`, `p:animEffect`,
+   * `p:animScale`, `p:animRot`, `p:animMotion`) with its own timing, as
+   * authored. The single-valued fields above flatten a composed preset;
+   * this keeps the whole tree so playback can follow what PowerPoint wrote
+   * (see `animation-behavior-player` in `pptx-viewer-shared`).
+   */
+  behaviors?: PptxAnimationBehavior[];
 }
 /**
  * One `p:set` discrete (non-interpolated) attribute assignment composed
@@ -13580,6 +13691,13 @@ type ToolbarButtonId = 'share' | 'broadcast' | 'export' | 'undo' | 'redo' | 'rec
 /** A top-level ribbon tab. `record` intentionally shares its id with the quick-access Record button above: both surface the same recording feature, so hiding one hides the other. */
 type ToolbarTabId = 'file' | 'home' | 'insert' | 'draw' | 'design' | 'transitions' | 'animations' | 'slideShow' | 'record' | 'review' | 'view' | 'help';
 type ToolbarActionId = ToolbarButtonId | ToolbarTabId;
+/**
+ * PowerPoint's contextual tabs: they join the tab row only while the
+ * selection is of their kind (see `contextualTabsForElement` in
+ * `ribbon-galleries/`). Kept apart from `ToolbarTabId` because they are not
+ * part of the fixed tab order every binding renders.
+ */
+type RibbonContextualTabId = 'shapeFormat' | 'pictureFormat' | 'tableDesign' | 'chartDesign' | 'smartArtDesign';
 //#endregion
 //#region src/render/options/viewer-options.d.ts
 /**
@@ -13783,6 +13901,511 @@ type FreeformToolKind = 'freeformShape' | 'curve';
  */
 type ViewerOptionsTabId = 'general' | 'proofing' | 'save' | 'language' | 'accessibility' | 'advanced' | 'ribbon' | 'quickAccess' | 'addIns' | 'trust';
 //#endregion
+//#region src/render/customization/ribbon-control-catalog.d.ts
+declare const RIBBON_CONTROL_CATALOG: {
+  readonly home: {
+    readonly clipboard: {
+      readonly label: 'Clipboard';
+      readonly controls: {
+        readonly paste: 'Paste';
+        readonly cut: 'Cut';
+        readonly copy: 'Copy';
+        readonly formatPainter: 'Format Painter';
+      };
+    };
+    readonly slides: {
+      readonly label: 'Slides';
+      readonly controls: {
+        readonly newSlide: 'New Slide';
+        readonly layout: 'Layout';
+        readonly reset: 'Reset';
+        readonly section: 'Section';
+        readonly slideTemplates: 'Slide templates';
+      };
+    };
+    readonly font: {
+      readonly label: 'Font';
+      readonly controls: {
+        readonly fontFamily: 'Font';
+        readonly fontSize: 'Font Size';
+        readonly increaseFontSize: 'Increase Font Size';
+        readonly decreaseFontSize: 'Decrease Font Size';
+        readonly clearFormatting: 'Clear All Formatting';
+        readonly bold: 'Bold';
+        readonly italic: 'Italic';
+        readonly underline: 'Underline';
+        readonly strikethrough: 'Strikethrough';
+        readonly shadow: 'Text Shadow';
+        readonly characterSpacing: 'Character Spacing';
+        readonly changeCase: 'Change Case';
+        readonly fontColor: 'Font Color';
+        readonly highlightColor: 'Text Highlight Color';
+        readonly superscript: 'Superscript';
+        readonly subscript: 'Subscript';
+      };
+    };
+    readonly paragraph: {
+      readonly label: 'Paragraph';
+      readonly controls: {
+        readonly bullets: 'Bullets (toggle and gallery)';
+        readonly numbering: 'Numbering (toggle and gallery)';
+        readonly decreaseIndent: 'Decrease List Level';
+        readonly increaseIndent: 'Increase List Level';
+        readonly lineSpacing: 'Line Spacing';
+        readonly alignLeft: 'Align Left';
+        readonly alignCenter: 'Center';
+        readonly alignRight: 'Align Right';
+        readonly justify: 'Justify';
+        readonly columns: 'Columns';
+        readonly textDirection: 'Text Direction';
+        readonly alignText: 'Align Text';
+      };
+    };
+    readonly drawing: {
+      readonly label: 'Drawing';
+      readonly controls: {
+        readonly shapes: 'Shapes';
+        readonly arrange: 'Arrange';
+        readonly quickStyles: 'Quick Styles (Shape Styles gallery)';
+        readonly shapeFill: 'Shape Fill';
+        readonly shapeOutline: 'Shape Outline';
+        readonly shapeEffects: 'Shape Effects gallery';
+      };
+    };
+    readonly arrange: {
+      readonly label: 'Arrange';
+      readonly controls: {
+        readonly bringForward: 'Bring Forward';
+        readonly sendBackward: 'Send Backward';
+        readonly bringToFront: 'Bring to Front';
+        readonly sendToBack: 'Send to Back';
+        readonly flipHorizontal: 'Flip Horizontal';
+        readonly flipVertical: 'Flip Vertical';
+        readonly duplicate: 'Duplicate';
+        readonly delete: 'Delete';
+        readonly group: 'Group';
+        readonly ungroup: 'Ungroup';
+        readonly align: 'Align';
+        readonly mergeShapes: 'Merge Shapes';
+        readonly crop: 'Crop';
+        readonly outlineWidth: 'Outline width';
+      };
+    };
+    readonly editing: {
+      readonly label: 'Editing';
+      readonly controls: {
+        readonly find: 'Find';
+        readonly replace: 'Replace';
+        readonly select: 'Select';
+      };
+    };
+  };
+  readonly insert: {
+    readonly slides: {
+      readonly label: 'Slides';
+      readonly controls: {
+        readonly newSlide: 'New Slide';
+      };
+    };
+    readonly tables: {
+      readonly label: 'Tables';
+      readonly controls: {
+        readonly table: 'Table';
+      };
+    };
+    readonly images: {
+      readonly label: 'Images';
+      readonly controls: {
+        readonly pictures: 'Pictures';
+      };
+    };
+    readonly illustrations: {
+      readonly label: 'Illustrations';
+      readonly controls: {
+        readonly shapes: 'Shapes';
+        readonly smartArt: 'SmartArt';
+        readonly chart: 'Chart';
+      };
+    };
+    readonly links: {
+      readonly label: 'Links';
+      readonly controls: {
+        readonly link: 'Link';
+        readonly action: 'Action button';
+      };
+    };
+    readonly comments: {
+      readonly label: 'Comments';
+      readonly controls: {
+        readonly comment: 'Comment';
+      };
+    };
+    readonly text: {
+      readonly label: 'Text';
+      readonly controls: {
+        readonly textBox: 'Text Box';
+        readonly field: 'Header, date, slide number field';
+      };
+    };
+    readonly symbols: {
+      readonly label: 'Symbols';
+      readonly controls: {
+        readonly equation: 'Equation';
+        readonly symbol: 'Symbol';
+      };
+    };
+    readonly media: {
+      readonly label: 'Media';
+      readonly controls: {
+        readonly media: 'Video / Audio';
+      };
+    };
+  };
+  readonly draw: {
+    readonly tools: {
+      readonly label: 'Drawing Tools';
+      readonly controls: {
+        readonly select: 'Select';
+        readonly pen: 'Pen';
+        readonly highlighter: 'Highlighter';
+        readonly eraser: 'Eraser';
+        readonly penColor: 'Pen colour';
+        readonly penWidth: 'Pen width';
+      };
+    };
+    readonly convert: {
+      readonly label: 'Convert';
+      readonly controls: {
+        readonly inkToShape: 'Ink to Shape';
+      };
+    };
+  };
+  readonly design: {
+    readonly themes: {
+      readonly label: 'Themes';
+      readonly controls: {
+        readonly browseThemes: 'Themes gallery';
+        readonly editTheme: 'Edit theme';
+      };
+    };
+    readonly variants: {
+      readonly label: 'Variants';
+      readonly controls: {
+        readonly colors: 'Variants: Colors gallery';
+        readonly fonts: 'Variants: Fonts gallery';
+      };
+    };
+    readonly customize: {
+      readonly label: 'Customize';
+      readonly controls: {
+        readonly slideSize: 'Slide Size';
+        readonly formatBackground: 'Format Background';
+      };
+    };
+  };
+  readonly transitions: {
+    readonly preview: {
+      readonly label: 'Preview';
+      readonly controls: {
+        readonly preview: 'Preview';
+      };
+    };
+    readonly transitionToThisSlide: {
+      readonly label: 'Transition to This Slide';
+      readonly controls: {
+        readonly gallery: 'Transition gallery';
+        readonly effectOptions: 'Effect Options';
+      };
+    };
+    readonly timing: {
+      readonly label: 'Timing';
+      readonly controls: {
+        readonly sound: 'Sound';
+        readonly duration: 'Duration';
+        readonly applyToAll: 'Apply To All';
+        readonly advanceOnClick: 'On Mouse Click';
+        readonly advanceAfter: 'After';
+      };
+    };
+  };
+  readonly animations: {
+    readonly preview: {
+      readonly label: 'Preview';
+      readonly controls: {
+        readonly preview: 'Preview';
+      };
+    };
+    readonly animation: {
+      readonly label: 'Animation';
+      readonly controls: {
+        readonly gallery: 'Animation gallery';
+        readonly effectOptions: 'Effect Options';
+      };
+    };
+    readonly motionPath: {
+      readonly label: 'Motion Paths';
+      readonly controls: {
+        readonly gallery: 'Motion path gallery';
+      };
+    };
+    readonly advancedAnimation: {
+      readonly label: 'Advanced Animation';
+      readonly controls: {
+        readonly addAnimation: 'Add Animation';
+        readonly animationPane: 'Animation Pane';
+        readonly trigger: 'Trigger';
+        readonly animationPainter: 'Animation Painter';
+        readonly remove: 'Remove animation';
+      };
+    };
+    readonly timing: {
+      readonly label: 'Timing';
+      readonly controls: {
+        readonly start: 'Start';
+        readonly duration: 'Duration';
+        readonly delay: 'Delay';
+        readonly reorder: 'Reorder';
+      };
+    };
+  };
+  readonly slideShow: {
+    readonly startSlideShow: {
+      readonly label: 'Start Slide Show';
+      readonly controls: {
+        readonly fromBeginning: 'From Beginning';
+        readonly fromCurrent: 'From Current Slide';
+        readonly customShow: 'Custom Slide Show';
+      };
+    };
+    readonly present: {
+      readonly label: 'Present';
+      readonly controls: {
+        readonly presenterView: 'Presenter View';
+        readonly broadcast: 'Present Online';
+      };
+    };
+    readonly setUp: {
+      readonly label: 'Set Up';
+      readonly controls: {
+        readonly setUpSlideShow: 'Set Up Slide Show';
+        readonly hideSlide: 'Hide Slide';
+        readonly rehearseTimings: 'Rehearse Timings';
+        readonly record: 'Record';
+        readonly rehearseWithCoach: 'Rehearse with Coach';
+      };
+    };
+    readonly captions: {
+      readonly label: 'Captions & Subtitles';
+      readonly controls: {
+        readonly subtitles: 'Always Use Subtitles';
+        readonly subtitleSettings: 'Subtitle Settings';
+      };
+    };
+  };
+  readonly record: {
+    readonly camera: {
+      readonly label: 'Camera';
+      readonly controls: {
+        readonly cameo: 'Cameo';
+      };
+    };
+    readonly record: {
+      readonly label: 'Record';
+      readonly controls: {
+        readonly fromBeginning: 'From Beginning';
+        readonly fromCurrent: 'From Current Slide';
+      };
+    };
+    readonly manage: {
+      readonly label: 'Manage';
+      readonly controls: {
+        readonly clear: 'Clear';
+        readonly reset: 'Reset to Cameo';
+      };
+    };
+    readonly help: {
+      readonly label: 'Help';
+      readonly controls: {
+        readonly learnMore: 'Learn more';
+      };
+    };
+  };
+  readonly review: {
+    readonly proofing: {
+      readonly label: 'Proofing';
+      readonly controls: {
+        readonly spelling: 'Spelling';
+        readonly thesaurus: 'Thesaurus';
+      };
+    };
+    readonly accessibility: {
+      readonly label: 'Accessibility';
+      readonly controls: {
+        readonly check: 'Check Accessibility';
+      };
+    };
+    readonly language: {
+      readonly label: 'Language';
+      readonly controls: {
+        readonly translate: 'Translate';
+      };
+    };
+    readonly comments: {
+      readonly label: 'Comments';
+      readonly controls: {
+        readonly newComment: 'New Comment';
+        readonly delete: 'Delete';
+        readonly previous: 'Previous';
+        readonly next: 'Next';
+        readonly showComments: 'Show Comments';
+      };
+    };
+    readonly compare: {
+      readonly label: 'Compare';
+      readonly controls: {
+        readonly compare: 'Compare';
+        readonly markAllRead: 'Mark all read';
+      };
+    };
+    readonly protect: {
+      readonly label: 'Protect';
+      readonly controls: {
+        readonly readOnly: 'Read-only';
+        readonly restrictPermission: 'Restrict Permission';
+      };
+    };
+    readonly ink: {
+      readonly label: 'Ink';
+      readonly controls: {
+        readonly hideInk: 'Hide Ink';
+      };
+    };
+  };
+  readonly view: {
+    readonly presentationViews: {
+      readonly label: 'Presentation Views';
+      readonly controls: {
+        readonly normal: 'Normal';
+        readonly outline: 'Outline View';
+        readonly slideSorter: 'Slide Sorter';
+        readonly notesPage: 'Notes Page';
+        readonly readingView: 'Reading View';
+      };
+    };
+    readonly masterViews: {
+      readonly label: 'Master Views';
+      readonly controls: {
+        readonly slideMaster: 'Slide Master';
+        readonly handoutMaster: 'Handout Master';
+        readonly notesMaster: 'Notes Master';
+      };
+    };
+    readonly show: {
+      readonly label: 'Show';
+      readonly controls: {
+        readonly ruler: 'Ruler';
+        readonly gridlines: 'Gridlines';
+        readonly guides: 'Guides';
+        readonly snapToGrid: 'Snap to Grid';
+        readonly snapToShape: 'Snap to Shape';
+        readonly addGuide: 'Add horizontal / vertical guide';
+        readonly selectionPane: 'Selection Pane';
+        readonly eyedropper: 'Eyedropper';
+        readonly notes: 'Notes';
+      };
+    };
+    readonly zoom: {
+      readonly label: 'Zoom';
+      readonly controls: {
+        readonly zoom: 'Zoom';
+        readonly fitToWindow: 'Fit to Window';
+      };
+    };
+    readonly window: {
+      readonly label: 'Window';
+      readonly controls: {
+        readonly templateEditing: 'Edit template elements';
+        readonly macros: 'Macros';
+      };
+    };
+  };
+  readonly help: {
+    readonly help: {
+      readonly label: 'Help';
+      readonly controls: {
+        readonly options: 'Options';
+        readonly keyboardShortcuts: 'Keyboard shortcuts';
+        readonly accessibility: 'Accessibility checker';
+      };
+    };
+  };
+  readonly shapeFormat: {
+    readonly shapeStyles: {
+      readonly label: 'Shape Styles';
+      readonly controls: {
+        readonly gallery: 'Shape Styles gallery';
+        readonly shapeEffects: 'Shape Effects gallery';
+      };
+    };
+    readonly wordArtStyles: {
+      readonly label: 'WordArt Styles';
+      readonly controls: {
+        readonly gallery: 'WordArt Styles gallery';
+      };
+    };
+  };
+  readonly pictureFormat: {
+    readonly pictureStyles: {
+      readonly label: 'Picture Styles';
+      readonly controls: {
+        readonly gallery: 'Picture Styles gallery';
+        readonly pictureEffects: 'Picture Effects gallery';
+      };
+    };
+  };
+  readonly tableDesign: {
+    readonly tableStyles: {
+      readonly label: 'Table Styles';
+      readonly controls: {
+        readonly gallery: 'Table Styles gallery';
+      };
+    };
+  };
+  readonly chartDesign: {
+    readonly chartLayouts: {
+      readonly label: 'Chart Layouts';
+      readonly controls: {
+        readonly quickLayout: 'Quick Layout gallery';
+      };
+    };
+    readonly chartStyles: {
+      readonly label: 'Chart Styles';
+      readonly controls: {
+        readonly changeColors: 'Change Colors gallery';
+        readonly gallery: 'Chart Styles gallery';
+      };
+    };
+  };
+  readonly smartArtDesign: {
+    readonly smartArtStyles: {
+      readonly label: 'SmartArt Styles';
+      readonly controls: {
+        readonly changeColors: 'Change Colors gallery';
+        readonly gallery: 'SmartArt Styles gallery';
+      };
+    };
+  };
+};
+//#endregion
+//#region src/render/customization/ribbon-control-ids.d.ts
+type Catalog = typeof RIBBON_CONTROL_CATALOG;
+/** `<tab>.<group>`, for example `home.font`. */
+type RibbonGroupId = { [T in keyof Catalog]: { [G in keyof Catalog[T]]: `${T & string}.${G & string}`; }[keyof Catalog[T]]; }[keyof Catalog];
+/** `<tab>.<group>.<control>`, for example `home.font.bold`. */
+type RibbonControlId = { [T in keyof Catalog]: { [G in keyof Catalog[T]]: Catalog[T][G] extends {
+  controls: infer C;
+} ? `${T & string}.${G & string}.${keyof C & string}` : never; }[keyof Catalog[T]]; }[keyof Catalog];
+//#endregion
 //#region src/render/customization/customization-types.d.ts
 /** Keys of an options group whose value is a primitive (not an array). */
 type PrimitiveKeys<T> = { [K in keyof T]: T[K] extends ViewerOptionPrimitive ? K : never; }[keyof T] & string;
@@ -13807,10 +14430,20 @@ type OptionsSectionId = `${ViewerOptionsTabId}.${string}`;
 type OptionsSettingValues = Partial<Record<OptionsSettingId, ViewerOptionPrimitive>>;
 /** Ribbon and toolbar customisation. */
 interface RibbonCustomization {
-  /** Ribbon tabs to remove (the File tab included, unlike Customize Ribbon). */
-  hiddenTabs?: readonly ToolbarTabId[];
-  /** Top-level toolbar buttons / control clusters to remove. */
-  hiddenButtons?: readonly ToolbarButtonId[];
+  /**
+   * Ribbon tabs to remove (the File tab included, unlike Customize Ribbon),
+   * and contextual tabs (`shapeFormat`, `pictureFormat`, ...) that should
+   * never appear.
+   */
+  hiddenTabs?: readonly (ToolbarTabId | RibbonContextualTabId)[];
+  /** Groups inside a tab to remove, as `<tab>.<group>` (`home.font`). */
+  hiddenGroups?: readonly RibbonGroupId[];
+  /**
+   * Controls to remove: a top-level toolbar button / control cluster
+   * (`share`, `zoom`, ...) or any ribbon control as
+   * `<tab>.<group>.<control>` (`home.font.bold`).
+   */
+  hiddenButtons?: readonly (ToolbarButtonId | RibbonControlId)[];
 }
 /** File > Options (the Settings dialog) customisation. */
 interface OptionsCustomization {
@@ -13948,6 +14581,12 @@ interface ResolvedKeyboardCustomization {
 /** The normalised, set-based view of a customisation. Treat as immutable. */
 interface ResolvedCustomization {
   hiddenActions: ReadonlySet<ToolbarActionId>;
+  /** Contextual tabs (`shapeFormat`, ...) the host never wants shown. */
+  hiddenContextualTabs: ReadonlySet<RibbonContextualTabId>;
+  /** Catalogued ribbon groups to hide (`ribbon.hiddenGroups`). */
+  hiddenRibbonGroups: ReadonlySet<RibbonGroupId>;
+  /** Catalogued ribbon controls to hide (the `<tab>.<group>.<control>` part of `ribbon.hiddenButtons`). */
+  hiddenRibbonControls: ReadonlySet<RibbonControlId>;
   hiddenOptionsPages: ReadonlySet<OptionsPageId>;
   hiddenOptionsSections: ReadonlySet<OptionsSectionId>;
   hiddenSettings: ReadonlySet<OptionsSettingId>;
@@ -13978,10 +14617,18 @@ interface ViewerCustomizationApi {
   updateCustomization(patch: ViewerCustomization): void;
   /** Drop every customisation, back to the stock UI. */
   resetCustomization(): void;
-  hideRibbonTab(tab: ToolbarTabId): void;
-  showRibbonTab(tab: ToolbarTabId): void;
-  hideToolbarButton(button: ToolbarButtonId): void;
-  showToolbarButton(button: ToolbarButtonId): void;
+  /** Hide a fixed tab, or stop a contextual tab (`shapeFormat`, ...) from appearing. */
+  hideRibbonTab(tab: ToolbarTabId | RibbonContextualTabId): void;
+  showRibbonTab(tab: ToolbarTabId | RibbonContextualTabId): void;
+  /** Hide a group inside a tab (`home.font`). */
+  hideRibbonGroup(group: RibbonGroupId): void;
+  showRibbonGroup(group: RibbonGroupId): void;
+  /** Hide a top-level toolbar button or any ribbon control (`home.font.bold`). */
+  hideToolbarButton(button: ToolbarButtonId | RibbonControlId): void;
+  showToolbarButton(button: ToolbarButtonId | RibbonControlId): void;
+  /** Alias of `hideToolbarButton` for a ribbon control id. */
+  hideRibbonControl(control: RibbonControlId): void;
+  showRibbonControl(control: RibbonControlId): void;
   hideOptionsPage(page: OptionsPageId): void;
   showOptionsPage(page: OptionsPageId): void;
   hideOptionsSection(section: OptionsSectionId): void;
@@ -14580,8 +15227,8 @@ interface PowerPointViewerProps extends ViewportFitOptions {
   smartArt3D?: boolean;
   /**
    * Opt in to the interactive Three.js surface-chart renderer. When `true`,
-   * `surface`/`surface3D` charts render as a camera-orbitable WebGL mesh
-   * (drag to rotate, scroll to zoom) instead of the static SVG isometric
+   * `surface`/`surface3D` charts render as a WebGL mesh
+   * instead of the static SVG isometric
    * projection. Chart marks are not selectable/draggable in this mode.
    * Requires the optional `three` peer dependency; when it is not installed
    * (or the chart has no plottable grid), the viewer transparently falls back
@@ -14590,8 +15237,7 @@ interface PowerPointViewerProps extends ViewportFitOptions {
   surfaceChart3D?: boolean;
   /**
    * Opt in to the interactive Three.js bar3D-chart renderer. When `true`,
-   * `bar3D` charts render as camera-orbitable real box meshes (drag to
-   * rotate, scroll to zoom) instead of the flat SVG oblique-projection
+   * `bar3D` charts render as real box meshes instead of the flat SVG oblique-projection
    * illusion. Chart marks are not selectable/draggable in this mode.
    * Requires the optional `three` peer dependency; when it is not installed
    * (or the chart has no plottable grid, or it is a horizontal 3-D Bar), the
@@ -14601,8 +15247,8 @@ interface PowerPointViewerProps extends ViewportFitOptions {
   barChart3D?: boolean;
   /**
    * Opt in to the interactive Three.js line3D-chart renderer. When `true`,
-   * `line3D` charts render as a camera-orbitable real tube-path mesh per
-   * series, one per depth ("series") plane (drag to rotate, scroll to zoom),
+   * `line3D` charts render as a real tube-path mesh per
+   * series, one per depth ("series") plane,
    * instead of the flat SVG oblique-projection illusion. Chart marks are not
    * selectable/draggable in this mode. Requires the optional `three` peer
    * dependency; when it is not installed (or the chart has no plottable
@@ -14612,9 +15258,8 @@ interface PowerPointViewerProps extends ViewportFitOptions {
   lineChart3D?: boolean;
   /**
    * Opt in to the interactive Three.js area3D-chart renderer. When `true`,
-   * `area3D` charts render as a camera-orbitable real tube path + filled
-   * ribbon mesh per series, one per depth ("series") plane (drag to rotate,
-   * scroll to zoom), instead of the flat SVG oblique-projection illusion.
+   * `area3D` charts render as a real tube path + filled
+   * ribbon mesh per series, one per depth ("series") plane, instead of the flat SVG oblique-projection illusion.
    * Chart marks are not selectable/draggable in this mode. Requires the
    * optional `three` peer dependency; when it is not installed (or the chart
    * has no plottable grid), the viewer transparently falls back to the flat
@@ -14623,8 +15268,7 @@ interface PowerPointViewerProps extends ViewportFitOptions {
   areaChart3D?: boolean;
   /**
    * Opt in to the interactive Three.js pie3D-chart renderer. When `true`,
-   * `pie3D` charts render as camera-orbitable real wedge meshes (drag to
-   * rotate, scroll to zoom) instead of the flat SVG oblique-projection
+   * `pie3D` charts render as real wedge meshes instead of the flat SVG oblique-projection
    * illusion. Chart marks are not selectable/draggable in this mode.
    * Requires the optional `three` peer dependency; when it is not installed
    * (or the chart has no plottable series), the viewer transparently falls