pptx-react-viewer 4.7.0 → 4.9.0

package/dist/internals.d.ts

@@ -1295,6 +1295,27 @@ interface ShapeStyle {
    * `authored-shape-style.ts`'s `effectIsPurelyStyleMatrix`.
    */
   inheritedEffectStyle?: ShapeStyle;
+  /**
+   * Set by a style-matrix pick (the Shape Styles gallery): the shape's own
+   * `spPr` fill, outline and effects were replaced by `<p:style>`, so the
+   * writer clears whatever the retained `spPr` still authored before it
+   * writes the (now reference-owned) style. Never parsed; editor state only.
+   */
+  styleMatrixReset?: boolean;
+}
+/**
+ * The result of resolving a `<p:style>` block against the loaded theme.
+ *
+ * `shapeStyle` is exactly what the load pipeline would have produced for a
+ * shape whose `spPr` authors nothing and whose `<p:style>` is `styleXml`:
+ * the flat fill/outline/effect values a renderer needs, the reference indices
+ * and colours the writer re-emits, and the inheritance baselines that tell the
+ * writer to leave `spPr` empty while the flat values still agree with them.
+ */
+interface ResolvedStyleMatrix {
+  shapeStyle: ShapeStyle;
+  /** The text colour `<a:fontRef>` names, resolved to hex. */
+  fontColor?: string;
 }
 //#endregion
 //#region src/core/types/text.d.ts
@@ -1929,6 +1950,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`.
@@ -2247,6 +2278,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.
@@ -2269,6 +2315,22 @@ interface TextSegment {
    * Used by the renderer to apply font family, colour, etc. to the `<rt>` element.
    */
   rubyStyle?: TextStyle;
+  /**
+   * The parsed `a:rubyPr` node, kept verbatim so its attributes (`hps`,
+   * `hpsRaise`, `hpsBaseText`, `lid`, ...) round-trip exactly; only an
+   * edited {@link rubyAlignment} is written over it on save.
+   */
+  rubyPropertiesXml?: XmlObject;
+  /**
+   * What each of a ruby run's two base-side `a:rPr`s authored on its own:
+   * `outer` is the containing `a:r`'s, `base` the `a:rubyBase` run's. The
+   * flat {@link style} merges both for rendering; these let the writer give
+   * each `a:rPr` back only its own properties (plus any later edit).
+   */
+  rubyRunAuthoredStyles?: {
+    outer?: TextStyle;
+    base?: TextStyle;
+  };
 }
 //#endregion
 //#region src/core/types/element-base.d.ts
@@ -4180,6 +4242,14 @@ interface PptxChartData {
   style?: PptxChartStyle;
   /** Grouping mode for bar/area/line charts: 'clustered' | 'stacked' | 'percentStacked' */
   grouping?: 'clustered' | 'stacked' | 'percentStacked';
+  /**
+   * The source `c:grouping` was `standard`, which {@link grouping} folds into
+   * `'clustered'` (a 2D bar chart draws the two the same). A 3D chart draws
+   * `standard` differently: each series on its own depth row. The writer
+   * emits `standard` again while `grouping` is still `'clustered'`, so the
+   * chart round-trips unchanged.
+   */
+  groupingStandard?: boolean;
   /**
    * Whether the first (or only) series varies its point colours
    * (`c:varyColors/@val`). Pie/doughnut default this on; single-series
@@ -5577,6 +5647,14 @@ interface PptxSmartArtNode {
    * quick-style variation) applied to every other node.
    */
   coherent3DOff?: boolean;
+  /**
+   * The layout variables PowerPoint recorded for each presentation node
+   * this point drives (`dgm:prSet/@presName` -> `dgm:presLayoutVars`
+   * variable -> `@val`), e.g. `{ hierRoot1: { hierBranch: 'l' } }` for an
+   * org-chart manager set to "Left Hanging". Read-only: the presentation
+   * points themselves round-trip verbatim.
+   */
+  presLayoutVarsByName?: Record<string, Record<string, 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
@@ -5646,6 +5724,16 @@ interface PptxSmartArtQuickStyleLabel {
   name: string;
   /** Theme-resolved `dgm:style` refs for this label's role, when available. */
   resolvedStyle?: PptxSmartArtResolvedStyleRef;
+  /**
+   * The label's own `dgm:scene3d` (per-shape camera + light rig). PowerPoint
+   * copies it onto a shape's cached `a:scene3d` unless it is the default
+   * front camera with a `threePt` light (see `applySmartArtQuickStyle3d`).
+   */
+  scene3d?: Pptx3DScene;
+  /** The label's own `dgm:sp3d` (bevel / extrusion / contour / material); absent when empty. */
+  shape3d?: Pptx3DShape;
+  /** The label's `dgm:txPr/a:sp3d` label-text extrusion (Bird's Eye Scene). */
+  text3d?: Text3DStyle;
 }
 /** CT_CTStyleLabel metadata from a color-transform definition. */
 interface PptxSmartArtColorStyleLabel {
@@ -5713,9 +5801,10 @@ interface PptxSmartArtQuickStyle extends PptxSmartArtDefinitionMetadata {
    * for the "Scene" quick styles (Brick, Flat, Metallic, Sunset, Bird's Eye
    * Scene). One camera renders the whole diagram; per-shape `a:scene3d` is
    * absent for those styles (see `PptxSmartArtDrawingShape.scene3d`). Each
-   * `dgm:styleLbl` also carries its own per-label `dgm:scene3d`/`dgm:sp3d`,
-   * but PowerPoint bakes those fully resolved onto each cached shape's own
-   * `dsp:spPr/a:sp3d`, so only the diagram-level scene is exposed here.
+   * `dgm:styleLbl` also carries its own per-label `dgm:scene3d`/`dgm:sp3d`
+   * ({@link PptxSmartArtQuickStyleLabel.scene3d} / `shape3d` / `text3d`),
+   * which PowerPoint bakes onto each cached shape; they are re-applied when a
+   * structural edit regenerates the shapes.
    */
   scene3d?: Pptx3DScene;
 }
@@ -5846,6 +5935,11 @@ interface PptxSmartArtDrawingShape extends PptxCustomPathProperties {
   fillNone?: boolean;
   /** Solid fill colour (hex). */
   fillColor?: string;
+  /**
+   * Opacity (0..1) of the solid fill, from the colour's `a:alpha` (Basic Venn
+   * paints its circles at 50% so overlaps blend). Absent when opaque.
+   */
+  fillOpacity?: number;
   /**
    * Gradient fill stops when the cached shape uses `a:gradFill`. Positions are
    * 0..100 (percent). Renderers emit an SVG/CSS gradient instead of a flat box.
@@ -7803,6 +7897,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.
@@ -8354,6 +8526,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
@@ -11264,6 +11444,8 @@ interface IPptxHandlerRuntime {
   updateThemeColorScheme(colorScheme: PptxThemeColorScheme): Promise<void>;
   updateThemeFontScheme(fontScheme: PptxThemeFontScheme): Promise<void>;
   updateThemeName(name: string): Promise<void>;
+  /** Resolve a `<p:style>` node against the loaded theme (see PptxHandlerRuntimeStyleMatrixResolve). */
+  resolveStyleMatrixReferences(styleXml: XmlObject): ResolvedStyleMatrix;
   applyTheme(colorScheme: PptxThemeColorScheme, fontScheme: PptxThemeFontScheme, themeName?: string): Promise<void>;
   load(data: ArrayBuffer, options?: PptxHandlerLoadOptions): Promise<PptxData>;
   getChartDataForGraphicFrame(slidePath: string, graphicFrame: XmlObject | undefined): Promise<PptxChartData | undefined>;
@@ -11559,6 +11741,14 @@ declare class PptxHandlerCore {
    * @param name - New display name for the theme.
    */
   updateThemeName(name: string): Promise<void>;
+  /**
+   * Resolve a `<p:style>` block (`a:lnRef` / `a:fillRef` / `a:effectRef` /
+   * `a:fontRef`) against the loaded theme, exactly as the load path would for
+   * a shape whose `spPr` authors nothing. Apply the returned `shapeStyle` to a
+   * shape and it renders like PowerPoint's Shape Styles entry and saves as a
+   * bare `<p:style>` with an empty `spPr`, which is what PowerPoint writes.
+   */
+  resolveStyleMatrixReferences(styleXml: XmlObject): ResolvedStyleMatrix;
   /**
    * Apply a complete theme in one call (colour scheme + font scheme + optional name).
    *
@@ -12451,6 +12641,15 @@ interface PictureBulletMarker {
   imageRelId?: string;
 }
 //#endregion
+//#region src/render/text-east-asian-breaks.d.ts
+/** Which of the two behaviours a paragraph asks for. */
+interface EastAsianBreakOptions {
+  /** `a:pPr/@hangingPunct="1"`. */
+  hangingPunctuation: boolean;
+  /** `a:pPr/@eaLnBrk="0"`: break between any two East Asian characters. */
+  breakAnywhere: boolean;
+}
+//#endregion
 //#region src/render/text-run-meta.d.ts
 /** A run's resolved hyperlink target. */
 interface RunHyperlink {
@@ -12624,6 +12823,8 @@ interface ParagraphRun {
    * `paragraph-run-build.ts`).
    */
   underlineWordPieces?: ScriptFontPiece[];
+  /** The advance-carrying space after a hanging `、`/`。` (`text-east-asian-breaks`). */
+  hangingSpace?: true;
   /**
    * `a:reflection` mirrored-sibling wrapper style for this run (the text-run
    * counterpart of a shape/picture's `ComputedEffectStyle.reflection`), or
@@ -12707,6 +12908,12 @@ interface RenderParagraph {
    * break rules, rendered differently in the other four bindings.
    */
   paragraphStyle?: RunStyle;
+  /**
+   * `@hangingPunct` / `@eaLnBrk="0"` as resolved for this paragraph. The runs
+   * above already carry their pieces; React, which rebuilds each segment's
+   * pieces inside one span, re-applies `splitEastAsianBreaks` from this.
+   */
+  eastAsianBreaks?: EastAsianBreakOptions;
 }
 //#endregion
 //#region src/render/inline-list-types.d.ts
@@ -13743,6 +13950,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
 /**
@@ -13959,6 +14173,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;
@@ -13983,10 +14702,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 {
@@ -14169,6 +14898,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>;
@@ -14199,10 +14934,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;