pptx-vanilla-viewer 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { n, o, m, P, a, e, f, X, p, q, r, s, t, u, v, w, x, y, z, A, B, D, E, F, G, H, J, K, L, i, j, l, k, g, h } from './presentation-BfnrtJV1.js';
+import { n, o, m, P, a, e, f, X, p, q, r, s, t, u, v, w, x, y, z, A, B, D, E, F, G, H, J, K, L, i, j, l, k, g, h, a0, ca } from './presentation-BfnrtJV1.js';
 export { a as PptxElement, P as PptxSlide } from './presentation-BfnrtJV1.js';
 import { ViewerTheme } from './theme/index.js';
 export { ViewerTheme, ViewerThemeColors, defaultCssVars, defaultRadius, defaultThemeColors, themeToCssVars, vermilionDarkTheme, vermilionLightTheme } from './theme/index.js';
@@ -1431,6 +1431,71 @@ interface CollaborationConfig {
 /** A neutral CSS map (framework `CSSProperties` are structurally compatible). */
 type CssStyleMap = Record<string, string | number>;
 
+/**
+ * `animation-authoring` — pure, immutable helpers for the editor's element
+ * animation authoring UI (the Animations ribbon tab / animation panel).
+ *
+ * Animation data lives on the SLIDE (`PptxSlide.animations`), keyed by
+ * `elementId`, NOT on the element itself. The authoring UI reads and emits the
+ * entire slide-level `animations` array. Every function here returns a new
+ * `PptxElementAnimation[]` without mutating its input, so they're trivially
+ * unit-testable and safe to drive editor undo/redo from.
+ *
+ * Two families coexist here, both used across the bindings:
+ *
+ *  - **Granular field setters** (`setAnimationEntrance` / `setTrigger` /
+ *    `setDuration` / … plus `reorderAnimationUp` / `removeAnimation`): the
+ *    Angular authoring panel + React's `useAnimationHandlers` model. They
+ *    upsert a single field on the element's entry, creating the entry with
+ *    sensible defaults when absent and removing it when all three effect
+ *    buckets become empty.
+ *  - **Group preset apply/remove** (`applyAnimationPreset` /
+ *    `removeElementAnimation`): the Vue ribbon model, a coarser
+ *    "set one of entrance/emphasis/exit, keep the rest" upsert.
+ *
+ * The option *catalogs* here are intentionally **value-only** (preset id +
+ * nothing else): the human label / icon / i18n key for each option is
+ * framework-specific (React uses `react-icons` + label keys, Angular uses
+ * Unicode arrow glyphs + plain labels), so each binding maps these ids to its
+ * own display metadata.
+ *
+ * Pure: imports only `pptx-viewer-core` types; no framework, no DOM.
+ *
+ * @module render/animation-authoring
+ */
+
+/** One of the three animation buckets a preset can occupy on an element. */
+type AnimationGroup = 'entrance' | 'emphasis' | 'exit';
+
+/**
+ * Pure geometry helpers for the align / distribute editor operations.
+ *
+ * These functions operate over a list of slide elements (anything carrying the
+ * `{ id, x, y, width, height }` bounding-box fields of {@link PptxElement}) and
+ * return a `Map` keyed by element `id` describing the *new* position(s) for the
+ * elements that need to move. Elements that already sit on the target edge (or
+ * the two outer-most elements during distribution) are still included with
+ * their unchanged coordinate so callers can apply the whole map uniformly — the
+ * map only ever contains the axis that the operation touches.
+ *
+ * The helpers are deliberately framework-agnostic: no DOM, no Vue reactivity,
+ * no side effects. The host wires them into the editor by feeding the current
+ * selection in and applying the returned `Map` via its element-transform
+ * operation (one batched history entry per call).
+ */
+/** Edge / centre that {@link alignElements} can snap a selection to. */
+type AlignEdge = 'left' | 'centerH' | 'right' | 'top' | 'middle' | 'bottom';
+
+/**
+ * "Change Case" text mutation (PowerPoint's Aa dropdown: Sentence case, lower,
+ * UPPER, Capitalize Each Word, tOGGLE cASE). Unlike `textCaps` (a purely
+ * visual `text-transform`-style render hint), these modes rewrite the actual
+ * characters, matching PowerPoint's own behaviour. Framework-agnostic; no
+ * framework imports.
+ */
+
+type ChangeCaseMode = 'sentence' | 'lower' | 'upper' | 'capitalize' | 'toggle';
+
 /**
  * collaboration-presence.ts: Pure, framework-agnostic logic for the real-time
  * collaboration subsystem (Yjs-backed presence + remote cursors).
@@ -1455,6 +1520,54 @@ type CssStyleMap = Record<string, string | number>;
 
 /** Connection lifecycle states for the Yjs WebSocket provider. */
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+
+/**
+ * Pure helpers for the gradient picker editor control, shared by every binding.
+ *
+ * Readers extract current gradient values from a PptxElement (falling back to
+ * sensible defaults), and patch-builders produce shallow-merge-ready
+ * `Partial<PptxElement>` objects safe to pass to each binding's element-update
+ * action.
+ *
+ * No framework imports; every type is concrete or `unknown` + narrowed.
+ */
+
+/** A single gradient stop, mirroring the ShapeStyle array item shape. */
+interface GradientStop {
+    color: string;
+    position: number;
+    opacity?: number;
+}
+/** The editable gradient state surfaced to the component. */
+interface GradientState {
+    type: 'linear' | 'radial';
+    /** Angle in degrees (only meaningful for linear). */
+    angle: number;
+    stops: GradientStop[];
+}
+/** In-memory clipboard payload stored when an element is copied or cut. */
+interface ElementClipboardPayload {
+    element: a;
+    isTemplate: boolean;
+}
+
+/**
+ * shape-preset-catalog.ts: the Insert > Shape picker catalogue shared by every
+ * binding's toolbar/inspector.
+ *
+ * Pure data: each entry carries the preset geometry `type` (OOXML `a:prstGeom`
+ * value the editor can insert), an English fallback `label`, the shared-i18n
+ * `i18nKey`, and a framework-neutral icon descriptor ({@link ShapePresetGlyph}
+ * name + optional utility-class modifier for rotation/skew). Each binding maps
+ * the glyph name onto its own icon component/SVG.
+ *
+ * Order matters: bindings surface the first 12 entries as the quick "top
+ * shapes" row, so new presets should be appended, not inserted.
+ *
+ * @module render/shape-preset-catalog
+ */
+/** Shape preset geometry types offered by the insert picker. */
+type ShapePresetType = 'rect' | 'roundRect' | 'ellipse' | 'cylinder' | 'rtArrow' | 'leftArrow' | 'upArrow' | 'downArrow' | 'triangle' | 'rtTriangle' | 'diamond' | 'parallelogram' | 'trapezoid' | 'pentagon' | 'hexagon' | 'octagon' | 'chevron' | 'star5' | 'star6' | 'star8' | 'plus' | 'heart' | 'cloud' | 'sun' | 'moon' | 'pie' | 'plaque' | 'teardrop' | 'line' | 'connector';
 interface AutosaveRecord {
     key: string;
     data: Uint8Array;
@@ -1506,29 +1619,6 @@ interface PrintSettings {
     customRangeTo: number;
 }
 
-/**
- * Minimal i18n for the vanilla binding.
- *
- * The other bindings delegate to their framework's i18n runtime (react-i18next,
- * vue-i18n, ngx-translate) fed by the shared `pptx.*` dictionary. The vanilla
- * binding has no framework, so this module provides the one missing piece: a
- * `t(key, params)` lookup with `{{param}}` interpolation over the same shared
- * English dictionary, plus per-locale overrides supplied by the host.
- *
- * Resolution order: host dictionary for the active locale, then the built-in
- * English dictionary, then a humanised fallback derived from the key (shared
- * `keyToLabel`), so a missing key never renders as a raw `pptx.*` string.
- */
-/** Translate a dotted `pptx.*` key with optional `{{param}}` interpolation. */
-type Translator = (key: string, params?: Record<string, string | number>) => string;
-/** Locale to flat `key: message` dictionary map supplied by the host. */
-type TranslationMessages = Record<string, Record<string, string>>;
-/**
- * Build a {@link Translator} for a locale. `messages[locale]` (when provided)
- * wins over the built-in English dictionary; English is always the fallback.
- */
-declare function createTranslator(locale?: string, messages?: TranslationMessages): Translator;
-
 /**
  * A tiny framework-free reactive store: `get` / `set(patch)` / `subscribe`.
  *
@@ -1587,6 +1677,81 @@ interface ViewerState {
      * navigation for the life of the viewer instance (in-memory only).
      */
     notesExpanded: boolean;
+    /** In-memory clipboard payload from the last copy/cut, or null. */
+    clipboardPayload: ElementClipboardPayload | null;
+}
+
+/**
+ * Element-animation actions for the ribbon's Animations tab.
+ *
+ * Animation data lives on the SLIDE (`PptxSlide.animations`, keyed by
+ * `elementId`), not on the element itself, matching how the presentation
+ * playback state machine reads it (`buildClickGroups(slide.animations)` in
+ * `animation/presentation-playback.ts`). Both actions target the currently
+ * selected element and route through the shared `animation-authoring.ts`
+ * "coarse group preset" model (`applyAnimationPreset` / `removeElementAnimation`),
+ * the same one the Vue ribbon uses: applying a preset sets one of
+ * entrance/emphasis/exit without touching the others; remove drops the whole
+ * entry.
+ */
+interface AnimationActions {
+    addAnimation(group: AnimationGroup, preset: g): void;
+    removeAnimation(): void;
+}
+
+/**
+ * Z-order, align, flip, and group/ungroup actions for the ribbon's
+ * Home > Arrange group.
+ *
+ * Align/distribute: the vanilla editor's selection model is single-element
+ * only (see `state/viewer-state.ts`), so `alignElements` reaches the
+ * single-selection "align to slide" mode ({@link alignToCanvas}), matching
+ * PowerPoint's own behaviour when nothing else is selected. Multi-selection
+ * "align to selection bounding box" / distribute (needing >= 2 / >= 3
+ * elements, see `editor-arrange-mutations.ts`) is unreachable until a
+ * multi-select model lands; `canDistribute` is therefore always `false` today
+ * (see `editing-chrome-sync.ts`), a documented limitation rather than a bug.
+ *
+ * Group: needs >= 2 selected elements to be meaningful, so it too is
+ * unreachable under single selection; `groupSelected` is a deliberate no-op
+ * kept only so the ribbon button (permanently disabled, with an explanatory
+ * title) has something to call. Ungroup works today: it applies to whichever
+ * single `group` element is selected.
+ */
+interface ArrangeActions {
+    bringForward(): void;
+    sendBackward(): void;
+    bringToFront(): void;
+    sendToBack(): void;
+    alignElements(edge: AlignEdge): void;
+    flipHorizontal(): void;
+    flipVertical(): void;
+    groupSelected(): void;
+    ungroupSelected(): void;
+}
+
+/**
+ * Slide-background actions for the ribbon's Design > Format Background panel.
+ * Solid-colour fill only (matches the docked panel's scope: a single colour
+ * input); clearing removes every background field so the slide falls back to
+ * its layout/master background. Both mutations are history-integrated,
+ * mirroring `editor-slide-actions.ts`.
+ */
+interface SlideBackgroundActions {
+    setSlideBackgroundColor(color: string): void;
+    clearSlideBackground(): void;
+}
+
+/**
+ * Cut/copy/paste actions for the ribbon's Home > Clipboard group, backed by
+ * the shared `element-clipboard.ts` codec. The in-memory clipboard payload
+ * lives on `ViewerState.clipboardPayload` (not a module-level variable) so
+ * the ribbon's selection sync can reactively enable/disable the Paste button.
+ */
+interface ClipboardActions {
+    copy(): void;
+    cut(): void;
+    paste(): void;
 }
 
 /**
@@ -1599,29 +1764,96 @@ interface ViewerState {
  * side effects needed to turn a chosen image file into a data-URL image
  * element; it too returns a centred, ready-to-insert element.
  */
-/** The shape/text/table element kinds the insert menu can create directly. */
-type InsertKind = 'text' | 'rect' | 'ellipse' | 'line' | 'table';
+/** The element kinds the Insert ribbon tab can create directly. */
+type InsertKind = 'text' | 'table' | 'shape';
 
-/** The selection-derived state the toolbar reflects (enable/disable + values). */
-interface FormatSelectionState {
-    hasSelection: boolean;
-    canText: boolean;
-    canShape: boolean;
-    bold: boolean;
-    italic: boolean;
-    underline: boolean;
-    fontSize: number;
-    textColor: string | undefined;
-    highlightColor: string | undefined;
-    fillColor: string | undefined;
-    strokeColor: string | undefined;
+/**
+ * Element-type-aware inspector actions: text vertical-align/wrap/autofit,
+ * gradient fill + fill/stroke opacity, image brightness/contrast/saturation +
+ * crop, and table-level header-row/banded-rows/cell-padding. Every method is a
+ * thin `applyToSelected` wrapper around pure builders from `pptx-viewer-shared`
+ * (or the local `patchShapeStyle`), mirroring `editor-text-actions.ts`.
+ *
+ * These extend the base position/size/rotation + flat fill/stroke inspector
+ * that `editor-edit-ops.ts` already exposes; see `ui/inspector/` for the
+ * per-element-type panels that call these.
+ */
+interface InspectorActions {
+    setTextVerticalAlign(vAlign: NonNullable<a0['vAlign']>): void;
+    setTextWrap(wrap: NonNullable<a0['textWrap']>): void;
+    setAutoFitMode(mode: NonNullable<a0['autoFitMode']>): void;
+    setFillOpacity(opacity: number): void;
+    setStrokeOpacity(opacity: number): void;
+    setGradientFill(state: GradientState): void;
+    addGradientStop(color: string, position: number): void;
+    removeGradientStop(index: number): void;
+    updateGradientStop(index: number, changes: Partial<GradientState['stops'][number]>): void;
+    setImageBrightness(value: number): void;
+    setImageContrast(value: number): void;
+    setImageSaturation(value: number): void;
+    setImageCrop(edge: 'left' | 'top' | 'right' | 'bottom', value: number): void;
+    setTableHeaderRow(enabled: boolean): void;
+    setTableBandedRows(enabled: boolean): void;
+    setTableCellPadding(padding: number): void;
 }
-interface FormatToolbar {
-    el: HTMLElement;
-    /** Reflect the current selection (enable/disable controls + seed values). */
-    update(state: FormatSelectionState): void;
-    /** Show/hide the whole row (editing mode on/off). */
-    setEditable(editable: boolean): void;
+
+/**
+ * New/duplicate/delete-slide actions for the ribbon's Home > Slides group,
+ * backed by the shared `slide-operations.ts` factory. Every mutation is
+ * history-integrated (matches the element-level actions in `editor-edit-ops`)
+ * and renumbers `slideNumber` across the whole deck so it always matches the
+ * array index (mirrors the Vue `useSlideOperations` contract).
+ */
+interface SlideActions {
+    addSlide(): void;
+    duplicateSlide(): void;
+    deleteSlide(): void;
+}
+
+/**
+ * Character + paragraph formatting actions for the ribbon's Home > Font and
+ * Home > Paragraph groups. Every method is a thin `applyToSelected` wrapper
+ * around the pure builders in `editor-format-mutations.ts` /
+ * `editor-paragraph-mutations.ts`; this file owns none of the mutation logic
+ * itself, only the selection/history wiring shared by the whole action set.
+ */
+interface TextActions {
+    toggleBold(): void;
+    toggleItalic(): void;
+    toggleUnderline(): void;
+    toggleStrikethrough(): void;
+    toggleTextShadow(): void;
+    changeFontSize(delta: number): void;
+    setFontSize(size: number): void;
+    setFontFamily(family: string): void;
+    setTextColor(color: string): void;
+    setHighlightColor(color: string): void;
+    setCharacterSpacing(value: number): void;
+    changeCase(mode: ChangeCaseMode): void;
+    clearFormatting(): void;
+    toggleBulletList(): void;
+    toggleNumberedList(): void;
+    increaseIndent(): void;
+    decreaseIndent(): void;
+    setTextAlign(align: a0['align']): void;
+    setLineSpacing(value: number): void;
+}
+
+/**
+ * Slide-transition actions for the ribbon's Transitions tab. Playback already
+ * reads `PptxSlide.transition` (see `animation/presentation-playback.ts`), so
+ * this only needs to write that same field, history-integrated like every
+ * other ribbon mutation.
+ *
+ * `applyTransition` covers both the preset gallery buttons and the duration
+ * input (the tab re-applies the currently-selected preset whenever the
+ * duration changes), plus the "Apply to All Slides" checkbox: when
+ * `applyToAll` is true every slide gets the same fresh `{ type, durationMs }`
+ * transition; otherwise only the current slide is patched, preserving any
+ * advanced fields (direction, sound, ...) it already carried.
+ */
+interface TransitionActions {
+    applyTransition(type: k, durationMs: number, applyToAll: boolean): void;
 }
 
 /** A geometry patch from the inspector (all fields optional). */
@@ -1633,35 +1865,80 @@ interface GeometryPatch {
     rotation?: number;
 }
 /**
- * The formatting / insert / arrange actions exposed to the editing chrome
- * (format toolbar, inspector, insert menu). Every mutating action is
- * history-integrated (push -> mutate -> commit) via the shared {@link EditorOps}.
+ * The full set of formatting / insert / arrange / clipboard / slide actions
+ * exposed to the editing chrome (ribbon, inspector). Composed from the
+ * focused per-concern action files (`editor-text-actions.ts`,
+ * `editor-arrange-actions.ts`, `editor-clipboard-actions.ts`,
+ * `editor-slide-actions.ts`) plus the shape/geometry/insert actions owned
+ * directly here. Every mutating action is history-integrated (push -> mutate
+ * -> commit) via the shared {@link EditorOps}.
  */
-interface EditActions {
-    toggleBold(): void;
-    toggleItalic(): void;
-    toggleUnderline(): void;
-    changeFontSize(delta: number): void;
-    setFontSize(size: number): void;
-    setTextColor(color: string): void;
-    setHighlightColor(color: string): void;
+interface EditActions extends TextActions, ArrangeActions, ClipboardActions, SlideActions, SlideBackgroundActions, TransitionActions, AnimationActions, InspectorActions {
     setShapeFill(color: string): void;
     setShapeStroke(color: string): void;
     setShapeStrokeWidth(width: number): void;
     /** Commit an inspector geometry edit (X/Y/W/H/rotation). */
     setGeometry(patch: GeometryPatch): void;
-    insert(kind: InsertKind): void;
+    insert(kind: InsertKind, shapeType?: ShapePresetType): void;
     insertImage(): Promise<void>;
-    bringForward(): void;
-    sendBackward(): void;
-    bringToFront(): void;
-    sendToBack(): void;
+    insertMedia(): Promise<void>;
+    insertChart(chartType: l): void;
+    insertSmartArt(layout: ca, defaultItems: string[]): void;
+    insertEquation(omml: Record<string, unknown>): void;
+    insertActionButton(shapeType: string): void;
+    insertField(fieldType: string, value?: string): void;
+    duplicateSelected(): void;
+    deleteSelected(): void;
+}
+
+/**
+ * Find & Replace actions for the ribbon's Home > Editing group, backed by the
+ * shared `find-replace.ts` helpers. A lean, docked-panel implementation:
+ * `search` reports a match count for the query, `replaceCurrent` replaces the
+ * first match, and `replaceAll` replaces every match; there is no in-canvas
+ * match highlighting or "next/previous match" cursor (that needs per-match
+ * selection/scroll wiring into the renderer, out of scope for this wave).
+ * Every replace is history-integrated like every other editor action.
+ */
+interface FindReplaceActions {
+    /** Count occurrences of `query` across all slides (does not mutate). */
+    search(query: string, matchCase: boolean): number;
+    /** Replace the first match of `query`; returns the number replaced (0 or 1). */
+    replaceCurrent(query: string, replacement: string, matchCase: boolean): number;
+    /** Replace every match of `query`; returns the number replaced. */
+    replaceAll(query: string, replacement: string, matchCase: boolean): number;
 }
 
-/** Selection-derived state the inspector reflects. */
+/**
+ * Minimal i18n for the vanilla binding.
+ *
+ * The other bindings delegate to their framework's i18n runtime (react-i18next,
+ * vue-i18n, ngx-translate) fed by the shared `pptx.*` dictionary. The vanilla
+ * binding has no framework, so this module provides the one missing piece: a
+ * `t(key, params)` lookup with `{{param}}` interpolation over the same shared
+ * English dictionary, plus per-locale overrides supplied by the host.
+ *
+ * Resolution order: host dictionary for the active locale, then the built-in
+ * English dictionary, then a humanised fallback derived from the key (shared
+ * `keyToLabel`), so a missing key never renders as a raw `pptx.*` string.
+ */
+/** Translate a dotted `pptx.*` key with optional `{{param}}` interpolation. */
+type Translator = (key: string, params?: Record<string, string | number>) => string;
+/** Locale to flat `key: message` dictionary map supplied by the host. */
+type TranslationMessages = Record<string, Record<string, string>>;
+/**
+ * Build a {@link Translator} for a locale. `messages[locale]` (when provided)
+ * wins over the built-in English dictionary; English is always the fallback.
+ */
+declare function createTranslator(locale?: string, messages?: TranslationMessages): Translator;
+
+/** Selection-derived state the inspector reflects, computed by `buildInspectorState`. */
 interface InspectorState {
     hasSelection: boolean;
     canShape: boolean;
+    canText: boolean;
+    isImage: boolean;
+    isTable: boolean;
     x: number;
     y: number;
     width: number;
@@ -1670,6 +1947,23 @@ interface InspectorState {
     fillColor: string | undefined;
     strokeColor: string | undefined;
     strokeWidth: number;
+    fillOpacity: number;
+    strokeOpacity: number;
+    gradientEnabled: boolean;
+    gradient: GradientState;
+    vAlign: 'top' | 'middle' | 'bottom';
+    textWrap: 'square' | 'none';
+    autoFitMode: 'shrink' | 'normal' | 'none';
+    imageBrightness: number;
+    imageContrast: number;
+    imageSaturation: number;
+    cropLeft: number;
+    cropTop: number;
+    cropRight: number;
+    cropBottom: number;
+    tableHeaderRow: boolean;
+    tableBandedRows: boolean;
+    tableCellPadding: number;
 }
 interface Inspector {
     el: HTMLElement;
@@ -1694,52 +1988,52 @@ interface NotesPanel {
     setExpanded(expanded: boolean): void;
 }
 
-interface ThumbnailRail {
-    el: HTMLElement;
-    /** Rebuild the rail for a new slide list (uses `renderStage` per slide). */
-    render(slides: P[], canvasSize: CanvasSize, renderStage: (slide: P, scale: number) => HTMLElement): void;
-    /** Highlight the active slide and scroll it into view. */
-    setActive(index: number): void;
-    /** Show or hide the rail. */
-    setVisible(visible: boolean): void;
-}
-
-interface ToolbarUpdate {
-    /** Zero-based current slide index. */
+/** Nav-row state (prev/next/counter/zoom label). */
+interface RibbonNavState {
     current: number;
-    /** Total slide count. */
     total: number;
-    /** Effective zoom percentage (100 = 1:1). */
     zoomPercent: number;
 }
-/** Editing-cluster state (Save / Undo / Redo buttons). */
-interface ToolbarEditState {
-    /** Shows/hides the whole editing cluster. */
+/** Primary-row + tab-bar visibility state. */
+interface RibbonEditState {
     editable: boolean;
     canUndo: boolean;
     canRedo: boolean;
 }
-interface Toolbar {
+/** Selection-derived state the Home tab's Font/Paragraph/Arrange groups reflect. */
+interface RibbonSelectionState {
+    hasClipboard: boolean;
+    slideCount: number;
+}
+
+interface Ribbon {
     el: HTMLElement;
-    update(state: ToolbarUpdate): void;
-    setEditState(state: ToolbarEditState): void;
-    /** Reflect the notes panel's expanded/collapsed state on the Notes button. */
+    update(state: RibbonNavState): void;
+    setEditState(state: RibbonEditState): void;
     setNotesExpanded(expanded: boolean): void;
-    /**
-     * Show the autosave status pill. `label` is the (already localized) text;
-     * `kind` drives the styling hook (`is-saving` / `is-error`). An empty label
-     * hides the pill.
-     */
     setAutosaveStatus(label: string, kind: 'idle' | 'saving' | 'saved' | 'error'): void;
+    /** Show/hide the whole editing surface (Home/Insert tab content + find/replace). */
+    setEditable(editable: boolean): void;
+    /** Reflect the current selection across the Home tab's Font/Paragraph/Arrange groups. */
+    updateSelection(selectedElement: a | undefined, extra: RibbonSelectionState): void;
+}
+
+interface ThumbnailRail {
+    el: HTMLElement;
+    /** Rebuild the rail for a new slide list (uses `renderStage` per slide). */
+    render(slides: P[], canvasSize: CanvasSize, renderStage: (slide: P, scale: number) => HTMLElement): void;
+    /** Highlight the active slide and scroll it into view. */
+    setActive(index: number): void;
+    /** Show or hide the rail. */
+    setVisible(visible: boolean): void;
 }
 
 /** The viewer's static DOM skeleton plus the mutable overlay controls. */
 interface ViewerChrome {
     /** `.pptxv` root (focusable; keyboard navigation attaches here). */
     root: HTMLElement;
-    toolbar: Toolbar | null;
-    /** Editing format toolbar (bold/fill/insert/z-order); null when disabled. */
-    formatToolbar: FormatToolbar | null;
+    /** The tabbed ribbon (primary row, nav row, tab bar + File/Home/Insert/View content); null when disabled. */
+    ribbon: Ribbon | null;
     /** Property inspector panel; null when disabled. */
     inspector: Inspector | null;
     thumbnails: ThumbnailRail | null;
@@ -1786,6 +2080,8 @@ interface EditorController {
     getSelectedElementId(): string | null;
     /** The formatting / insert / arrange actions for the editing chrome. */
     getEditActions(): EditActions;
+    /** The Find & Replace actions for the ribbon's docked panel. */
+    getFindReplaceActions(): FindReplaceActions;
     /** Commit the speaker-notes textarea's plain text onto the current slide. */
     commitNotes(notes: string): void;
     save(): Promise<Uint8Array>;
@@ -2367,6 +2663,7 @@ interface ChromeHost {
     editor: {
         commitNotes(notes: string): void;
         getEditActions(): EditActions;
+        getFindReplaceActions(): FindReplaceActions;
     };
     prev(): void;
     next(): void;
@@ -2381,6 +2678,12 @@ interface ChromeHost {
     getSlideCount(): number;
     enterPresentation(): Promise<void>;
     exitPresentation(): Promise<void>;
+    exportSlidePng(): Promise<void>;
+    exportPdf(): Promise<void>;
+    exportGif(): Promise<void>;
+    exportVideo(): Promise<void>;
+    print(): Promise<boolean>;
+    setTheme(theme: ViewerTheme | undefined): void;
 }
 
 /** The export slice of the public viewer API (see `PptxViewerInstance`). */