pptx-react-viewer 1.5.2 → 1.6.0

package/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project are documented here.
 This file is generated from [Conventional Commits](https://www.conventionalcommits.org)
 by [git-cliff](https://git-cliff.org); do not edit it by hand.
 
+## [1.5.3](https://github.com/ChristopherVR/pptx-viewer/releases/tag/pptx-react-viewer@1.5.3) - 2026-07-04
+
+## [1.5.2](https://github.com/ChristopherVR/pptx-viewer/releases/tag/pptx-react-viewer@1.5.2) - 2026-07-04
+
 ## [1.5.1](https://github.com/ChristopherVR/pptx-viewer/releases/tag/pptx-react-viewer@1.5.1) - 2026-07-04
 
 ## [1.5.0](https://github.com/ChristopherVR/pptx-viewer/releases/tag/pptx-react-viewer@1.5.0) - 2026-07-04

package/README.md

@@ -101,13 +101,37 @@ const bytes = await viewerRef.current?.getContent(); // Uint8Array of a valid .p
 | `onContentChange`     | `(dirty: boolean) => void`          | n/a      | Called when content changes                                       |
 | `onDirtyChange`       | `(isDirty: boolean) => void`        | n/a      | Called when dirty state changes                                   |
 | `onActiveSlideChange` | `(index: number) => void`           | n/a      | Called when the active slide changes                              |
+| `onModeChange`        | `(mode: ViewerMode) => void`        | n/a      | Called when the viewer mode changes                               |
+| `onZoomChange`        | `(zoom: number) => void`            | n/a      | Called when the zoom level changes                                |
+| `onSelectionChange`   | `(ids: string[]) => void`           | n/a      | Called when element selection changes                             |
+| `onSlideCountChange`  | `(count: number) => void`           | n/a      | Called when the total slide count changes                         |
 | `theme`               | `ViewerTheme`                       | n/a      | Theme configuration for customising colours, radius, and CSS vars |
 
 ### `PowerPointViewerHandle` (via `ref`)
 
-| Method       | Signature                             | Description                            |
-| ------------ | ------------------------------------- | -------------------------------------- |
-| `getContent` | `() => Promise<string \| Uint8Array>` | Serialise current state to .pptx bytes |
+| Method                  | Signature                    | Description                              |
+| ----------------------- | ---------------------------- | ---------------------------------------- |
+| `getContent`            | `() => Promise<Uint8Array>`  | Serialise current state to .pptx bytes   |
+| `goTo`                  | `(index: number) => void`    | Navigate to a slide by zero-based index  |
+| `goPrev`                | `() => void`                 | Navigate to the previous slide           |
+| `goNext`                | `() => void`                 | Navigate to the next slide               |
+| `undo`                  | `() => void`                 | Undo the last editing action             |
+| `redo`                  | `() => void`                 | Redo the last undone action              |
+| `canUndo`               | `() => boolean`              | Whether an undo action is available      |
+| `canRedo`               | `() => boolean`              | Whether a redo action is available       |
+| `getZoom`               | `() => number`               | Get the current zoom level (1 = 100%)    |
+| `setZoom`               | `(level: number) => void`    | Set the zoom level                       |
+| `zoomIn`                | `() => void`                 | Zoom in by one step                      |
+| `zoomOut`               | `() => void`                 | Zoom out by one step                     |
+| `zoomReset`             | `() => void`                 | Reset zoom to 100%                       |
+| `getMode`               | `() => ViewerMode`           | Get the current viewer mode              |
+| `setMode`               | `(mode: ViewerMode) => void` | Switch mode programmatically             |
+| `getActiveSlideIndex`   | `() => number`               | Get the zero-based active slide index    |
+| `getSlideCount`         | `() => number`               | Get the total number of slides           |
+| `isDirty`               | `() => boolean`              | Whether the document has unsaved changes |
+| `getSelectedElementIds` | `() => string[]`             | Get IDs of selected elements             |
+| `selectElements`        | `(ids: string[]) => void`    | Programmatically select elements by ID   |
+| `clearSelection`        | `() => void`                 | Clear the current selection              |
 
 ### `renderToCanvas`
 

package/dist/{PowerPointViewer-BqfQdZFN.d.mts → PowerPointViewer-e7LyTw3o.d.mts}

@@ -3,6 +3,163 @@ import * as React from 'react';
 import React__default from 'react';
 import { ViewerTheme } from './theme/index.js';
 
+/** Viewer interaction mode: read-only, edit, presentation, or master-view. */
+type ViewerMode = 'preview' | 'edit' | 'present' | 'master';
+/**
+ * Framework-agnostic imperative API contract for the PowerPoint viewer.
+ *
+ * Each binding (React `forwardRef` handle, Vue `defineExpose`, Angular public
+ * methods) implements this interface so consumers get a consistent progressive
+ * API regardless of framework.
+ */
+interface PowerPointViewerAPI {
+    /** Serialise the current presentation to `.pptx` bytes. */
+    getContent: () => Promise<Uint8Array>;
+    /** Navigate to a specific slide by zero-based index. */
+    goTo: (slideIndex: number) => void;
+    /** Navigate to the previous slide. */
+    goPrev: () => void;
+    /** Navigate to the next slide. */
+    goNext: () => void;
+    /** Undo the last editing action. No-op when nothing to undo. */
+    undo: () => void;
+    /** Redo the last undone action. No-op when nothing to redo. */
+    redo: () => void;
+    /** Whether an undo action is available. */
+    canUndo: () => boolean;
+    /** Whether a redo action is available. */
+    canRedo: () => boolean;
+    /** Get the current zoom level (1 = 100%). */
+    getZoom: () => number;
+    /** Set the zoom level (clamped to min/max bounds). */
+    setZoom: (level: number) => void;
+    /** Zoom in by one step. */
+    zoomIn: () => void;
+    /** Zoom out by one step. */
+    zoomOut: () => void;
+    /** Reset zoom to 100%. */
+    zoomReset: () => void;
+    /** Get the current viewer mode. */
+    getMode: () => ViewerMode;
+    /** Switch the viewer mode (e.g. 'edit', 'preview', 'present'). */
+    setMode: (mode: ViewerMode) => void;
+    /** Get the zero-based active slide index. */
+    getActiveSlideIndex: () => number;
+    /** Set the active slide by zero-based index (alias of goTo). */
+    setActiveSlideIndex: (index: number) => void;
+    /** Get the total number of slides. */
+    getSlideCount: () => number;
+    /** Whether the document has unsaved changes. */
+    isDirty: () => boolean;
+    /**
+     * Get the full slide array. Returns the actual `PptxSlide[]` from the
+     * internal model with full type information (elements, notes, transitions,
+     * animations, etc.). The returned reference is a snapshot; mutations are
+     * not reflected back unless done via the manipulation methods.
+     */
+    getSlides: () => readonly l[];
+    /** Get a single slide by zero-based index, or undefined if out of range. */
+    getSlide: (index: number) => l | undefined;
+    /** Get the currently active slide. */
+    getActiveSlide: () => l | undefined;
+    /** Add a blank slide after the given index (or at end if omitted). */
+    addSlide: (afterIndex?: number) => void;
+    /** Delete slides at the given zero-based indexes. At least one slide is kept. */
+    deleteSlides: (indexes: number[]) => void;
+    /** Duplicate slides at the given zero-based indexes. */
+    duplicateSlides: (indexes: number[]) => void;
+    /** Move a slide from one position to another. */
+    moveSlide: (fromIndex: number, toIndex: number) => void;
+    /** Toggle the hidden flag on slides at the given indexes. */
+    toggleHideSlides: (indexes: number[]) => void;
+    /**
+     * Get the elements on a slide. Defaults to the active slide when
+     * `slideIndex` is omitted. Returns the full `PptxElement[]` with
+     * all type-specific properties intact.
+     */
+    getElements: (slideIndex?: number) => readonly P[];
+    /** Get a single element by ID from the active slide (or a specified slide). */
+    getElementById: (elementId: string, slideIndex?: number) => P | undefined;
+    /**
+     * Update one or more properties of an element by ID on the active slide.
+     * Accepts a `Partial<PptxElement>` patch (e.g. `{ x: 100, width: 300 }`).
+     */
+    updateElement: (elementId: string, updates: Partial<P>) => void;
+    /** Delete elements by their IDs from the active slide. */
+    deleteElements: (elementIds: string[]) => void;
+    /**
+     * Duplicate an element on the active slide.
+     * Returns the new element's ID, or undefined if the source was not found.
+     */
+    duplicateElement: (elementId: string) => string | undefined;
+    /** Get the IDs of currently selected elements. */
+    getSelectedElementIds: () => string[];
+    /** Programmatically select elements by their IDs. */
+    selectElements: (ids: string[]) => void;
+    /** Clear the current selection. */
+    clearSelection: () => void;
+}
+/** Collaboration role within a session. */
+type CollaborationRole = 'owner' | 'collaborator' | 'viewer';
+/**
+ * Collaboration transport.
+ *
+ * - `'websocket'` (default): y-websocket against `serverUrl`.
+ * - `'webrtc'`: y-webrtc peer-to-peer; needs no document server. Peers meet
+ *   through the `signaling` servers (WebRTC signaling only, no document data)
+ *   and same-browser tabs additionally sync via BroadcastChannel even without
+ *   any signaling server, which makes this mode usable from static hosting.
+ */
+type CollaborationTransport = 'websocket' | 'webrtc';
+/**
+ * Real-time collaboration configuration.
+ *
+ * The same shape is accepted by the React, Vue, and Angular bindings.
+ */
+interface CollaborationConfig {
+    /** Unique identifier for the collaboration room (alphanumeric, hyphens, underscores). */
+    roomId: string;
+    /**
+     * WebSocket server URL for the Yjs provider (e.g. "wss://collab.example.com").
+     * Ignored (may be empty) when `transport` is `'webrtc'`.
+     */
+    serverUrl: string;
+    /** Transport to use. Defaults to `'websocket'`. */
+    transport?: CollaborationTransport;
+    /**
+     * WebRTC signaling server URLs (only used when `transport` is `'webrtc'`).
+     * Defaults to y-webrtc's built-in public signaling list. Same-browser tabs
+     * sync via BroadcastChannel regardless of signaling availability.
+     */
+    signaling?: string[];
+    /** Display name for the local user. */
+    userName: string;
+    /** Avatar URL for the local user (optional). */
+    userAvatar?: string;
+    /** Hex colour for the local user's cursor/presence indicator. */
+    userColor?: string;
+    /** Optional authentication token sent with the WebSocket handshake. */
+    authToken?: string;
+    /** Role in the session; defaults to `'collaborator'`. */
+    role?: CollaborationRole;
+    /**
+     * Elected-writer write-back callback (Area 3 of the C3 hardening plan).
+     *
+     * When the local user has `role: 'owner'`, the binding debounces changes and
+     * serializes the current Y.Doc state to a PPTX byte array, then calls this
+     * callback so the host can persist the snapshot. Only one writer (the owner)
+     * does this; other collaborators never trigger write-back, eliminating the
+     * last-save-wins problem.
+     */
+    onWriteBack?: (bytes: Uint8Array) => void;
+    /**
+     * Debounce delay (ms) between the last Y.Doc change and the write-back
+     * invocation. Defaults to 5000 ms. Set to 0 to write back on every change
+     * (not recommended for large documents).
+     */
+    writeBackDebounceMs?: number;
+}
+
 /**
  * Core data-model types for the PowerPoint viewer/editor plugin.
  *
@@ -12,15 +169,6 @@ import { ViewerTheme } from './theme/index.js';
  * clipboard operations, undo/redo history, geometry, and shape quick styles.
  */
 
-/**
- * The current operating mode of the PowerPoint viewer.
- *
- * - `"preview"` -- Read-only viewing with no editing controls.
- * - `"edit"` -- Full editing mode with toolbar, inspector, and canvas interaction.
- * - `"present"` -- Fullscreen presentation/slideshow mode with animations.
- * - `"master"` -- Slide master editing mode for template/layout manipulation.
- */
-type ViewerMode = 'preview' | 'edit' | 'present' | 'master';
 /**
  * Union of all shape preset types that the viewer can insert or render.
  * Maps to OOXML `a:prstGeom` preset values (e.g. "rect", "ellipse").
@@ -174,67 +322,6 @@ interface ShapeQuickStyle {
     style: Partial<$>;
 }
 
-/** Collaboration role within a session. */
-type CollaborationRole = 'owner' | 'collaborator' | 'viewer';
-/**
- * Collaboration transport.
- *
- * - `'websocket'` (default): y-websocket against `serverUrl`.
- * - `'webrtc'`: y-webrtc peer-to-peer; needs no document server. Peers meet
- *   through the `signaling` servers (WebRTC signaling only, no document data)
- *   and same-browser tabs additionally sync via BroadcastChannel even without
- *   any signaling server, which makes this mode usable from static hosting.
- */
-type CollaborationTransport = 'websocket' | 'webrtc';
-/**
- * Real-time collaboration configuration.
- *
- * The same shape is accepted by the React, Vue, and Angular bindings.
- */
-interface CollaborationConfig {
-    /** Unique identifier for the collaboration room (alphanumeric, hyphens, underscores). */
-    roomId: string;
-    /**
-     * WebSocket server URL for the Yjs provider (e.g. "wss://collab.example.com").
-     * Ignored (may be empty) when `transport` is `'webrtc'`.
-     */
-    serverUrl: string;
-    /** Transport to use. Defaults to `'websocket'`. */
-    transport?: CollaborationTransport;
-    /**
-     * WebRTC signaling server URLs (only used when `transport` is `'webrtc'`).
-     * Defaults to y-webrtc's built-in public signaling list. Same-browser tabs
-     * sync via BroadcastChannel regardless of signaling availability.
-     */
-    signaling?: string[];
-    /** Display name for the local user. */
-    userName: string;
-    /** Avatar URL for the local user (optional). */
-    userAvatar?: string;
-    /** Hex colour for the local user's cursor/presence indicator. */
-    userColor?: string;
-    /** Optional authentication token sent with the WebSocket handshake. */
-    authToken?: string;
-    /** Role in the session; defaults to `'collaborator'`. */
-    role?: CollaborationRole;
-    /**
-     * Elected-writer write-back callback (Area 3 of the C3 hardening plan).
-     *
-     * When the local user has `role: 'owner'`, the binding debounces changes and
-     * serializes the current Y.Doc state to a PPTX byte array, then calls this
-     * callback so the host can persist the snapshot. Only one writer (the owner)
-     * does this; other collaborators never trigger write-back, eliminating the
-     * last-save-wins problem.
-     */
-    onWriteBack?: (bytes: Uint8Array) => void;
-    /**
-     * Debounce delay (ms) between the last Y.Doc change and the write-back
-     * invocation. Defaults to 5000 ms. Set to 0 to write back on every change
-     * (not recommended for large documents).
-     */
-    writeBackDebounceMs?: number;
-}
-
 /**
  * Base handle interface for file viewer components.
  * Defined locally to avoid dependency on external file-viewer plugin packages.
@@ -377,6 +464,14 @@ interface PowerPointViewerProps {
     onContentChange?: (content: Uint8Array) => void;
     /** Callback when active slide changes */
     onActiveSlideChange?: (slideIndex: number) => void;
+    /** Callback when the viewer mode changes (e.g. edit to present). */
+    onModeChange?: (mode: ViewerMode) => void;
+    /** Callback when the zoom level changes. */
+    onZoomChange?: (zoom: number) => void;
+    /** Callback when element selection changes. */
+    onSelectionChange?: (elementIds: string[]) => void;
+    /** Callback when the total slide count changes (slide added/deleted). */
+    onSlideCountChange?: (count: number) => void;
     /**
      * Host override for the File ▸ Open action. When provided, the built-in
      * native file picker is bypassed and this is invoked instead; the host is
@@ -476,7 +571,7 @@ interface PowerPointViewerProps {
      */
     smartArt3D?: boolean;
 }
-interface PowerPointViewerHandle extends FileViewerHandle {
+interface PowerPointViewerHandle extends FileViewerHandle, PowerPointViewerAPI {
     getContent: () => Promise<Uint8Array>;
 }
 
@@ -500,4 +595,4 @@ declare function getAnimationInitialStyle(preset: f | undefined, nativeAnimation
  */
 declare const PowerPointViewer: React.ForwardRefExoticComponent<PowerPointViewerProps & React.RefAttributes<PowerPointViewerHandle>>;
 
-export { type AccessibilityIssue as A, type StrokeDashOption as B, type CollaborationRole as C, type DragState as D, type EditorHistorySnapshot as E, type FileViewerHandle as F, type SupportedShapeType as G, type ToolbarSection as H, type MarqueeSelectionState as M, PowerPointViewer as P, type ResizeHandle as R, type ShapeAdjustmentDragState as S, type TableCellEditorState as T, type ViewerMode as V, type PowerPointViewerHandle as a, type PowerPointViewerProps as b, type CollaborationConfig as c, type AnimationPresetOption as d, type CanvasSize as e, type ConnectorArrowOption as f, getAnimationInitialStyle as g, type ConnectorGeometryOption as h, type ConnectorGeometryType as i, type ConnectorPathGeometry as j, type DrawingTool as k, type ElementBounds as l, type ElementClipboardPayload as m, type ElementContextMenuAction as n, type ElementContextMenuState as o, type ParsedTableCell as p, type ParsedTableData as q, type PresentationAnimationRuntime as r, type ResizeState as s, type ShapeAdjustmentHandleDescriptor as t, type ShapePreset as u, type ShapeQuickStyle as v, type ShortcutReferenceItem as w, type SlideAlignment as x, type SlideSectionGroup as y, type SlideTransitionOption as z };
+export { type AccessibilityIssue as A, type SlideTransitionOption as B, type CollaborationRole as C, type DragState as D, type EditorHistorySnapshot as E, type FileViewerHandle as F, type StrokeDashOption as G, type SupportedShapeType as H, type ToolbarSection as I, type MarqueeSelectionState as M, PowerPointViewer as P, type ResizeHandle as R, type ShapeAdjustmentDragState as S, type TableCellEditorState as T, type ViewerMode as V, type PowerPointViewerAPI as a, type PowerPointViewerHandle as b, type PowerPointViewerProps as c, type CollaborationConfig as d, type AnimationPresetOption as e, type CanvasSize as f, getAnimationInitialStyle as g, type ConnectorArrowOption as h, type ConnectorGeometryOption as i, type ConnectorGeometryType as j, type ConnectorPathGeometry as k, type DrawingTool as l, type ElementBounds as m, type ElementClipboardPayload as n, type ElementContextMenuAction as o, type ElementContextMenuState as p, type ParsedTableCell as q, type ParsedTableData as r, type PresentationAnimationRuntime as s, type ResizeState as t, type ShapeAdjustmentHandleDescriptor as u, type ShapePreset as v, type ShapeQuickStyle as w, type ShortcutReferenceItem as x, type SlideAlignment as y, type SlideSectionGroup as z };

package/dist/{PowerPointViewer-BqfQdZFN.d.ts → PowerPointViewer-e7LyTw3o.d.ts}

@@ -3,6 +3,163 @@ import * as React from 'react';
 import React__default from 'react';
 import { ViewerTheme } from './theme/index.js';
 
+/** Viewer interaction mode: read-only, edit, presentation, or master-view. */
+type ViewerMode = 'preview' | 'edit' | 'present' | 'master';
+/**
+ * Framework-agnostic imperative API contract for the PowerPoint viewer.
+ *
+ * Each binding (React `forwardRef` handle, Vue `defineExpose`, Angular public
+ * methods) implements this interface so consumers get a consistent progressive
+ * API regardless of framework.
+ */
+interface PowerPointViewerAPI {
+    /** Serialise the current presentation to `.pptx` bytes. */
+    getContent: () => Promise<Uint8Array>;
+    /** Navigate to a specific slide by zero-based index. */
+    goTo: (slideIndex: number) => void;
+    /** Navigate to the previous slide. */
+    goPrev: () => void;
+    /** Navigate to the next slide. */
+    goNext: () => void;
+    /** Undo the last editing action. No-op when nothing to undo. */
+    undo: () => void;
+    /** Redo the last undone action. No-op when nothing to redo. */
+    redo: () => void;
+    /** Whether an undo action is available. */
+    canUndo: () => boolean;
+    /** Whether a redo action is available. */
+    canRedo: () => boolean;
+    /** Get the current zoom level (1 = 100%). */
+    getZoom: () => number;
+    /** Set the zoom level (clamped to min/max bounds). */
+    setZoom: (level: number) => void;
+    /** Zoom in by one step. */
+    zoomIn: () => void;
+    /** Zoom out by one step. */
+    zoomOut: () => void;
+    /** Reset zoom to 100%. */
+    zoomReset: () => void;
+    /** Get the current viewer mode. */
+    getMode: () => ViewerMode;
+    /** Switch the viewer mode (e.g. 'edit', 'preview', 'present'). */
+    setMode: (mode: ViewerMode) => void;
+    /** Get the zero-based active slide index. */
+    getActiveSlideIndex: () => number;
+    /** Set the active slide by zero-based index (alias of goTo). */
+    setActiveSlideIndex: (index: number) => void;
+    /** Get the total number of slides. */
+    getSlideCount: () => number;
+    /** Whether the document has unsaved changes. */
+    isDirty: () => boolean;
+    /**
+     * Get the full slide array. Returns the actual `PptxSlide[]` from the
+     * internal model with full type information (elements, notes, transitions,
+     * animations, etc.). The returned reference is a snapshot; mutations are
+     * not reflected back unless done via the manipulation methods.
+     */
+    getSlides: () => readonly l[];
+    /** Get a single slide by zero-based index, or undefined if out of range. */
+    getSlide: (index: number) => l | undefined;
+    /** Get the currently active slide. */
+    getActiveSlide: () => l | undefined;
+    /** Add a blank slide after the given index (or at end if omitted). */
+    addSlide: (afterIndex?: number) => void;
+    /** Delete slides at the given zero-based indexes. At least one slide is kept. */
+    deleteSlides: (indexes: number[]) => void;
+    /** Duplicate slides at the given zero-based indexes. */
+    duplicateSlides: (indexes: number[]) => void;
+    /** Move a slide from one position to another. */
+    moveSlide: (fromIndex: number, toIndex: number) => void;
+    /** Toggle the hidden flag on slides at the given indexes. */
+    toggleHideSlides: (indexes: number[]) => void;
+    /**
+     * Get the elements on a slide. Defaults to the active slide when
+     * `slideIndex` is omitted. Returns the full `PptxElement[]` with
+     * all type-specific properties intact.
+     */
+    getElements: (slideIndex?: number) => readonly P[];
+    /** Get a single element by ID from the active slide (or a specified slide). */
+    getElementById: (elementId: string, slideIndex?: number) => P | undefined;
+    /**
+     * Update one or more properties of an element by ID on the active slide.
+     * Accepts a `Partial<PptxElement>` patch (e.g. `{ x: 100, width: 300 }`).
+     */
+    updateElement: (elementId: string, updates: Partial<P>) => void;
+    /** Delete elements by their IDs from the active slide. */
+    deleteElements: (elementIds: string[]) => void;
+    /**
+     * Duplicate an element on the active slide.
+     * Returns the new element's ID, or undefined if the source was not found.
+     */
+    duplicateElement: (elementId: string) => string | undefined;
+    /** Get the IDs of currently selected elements. */
+    getSelectedElementIds: () => string[];
+    /** Programmatically select elements by their IDs. */
+    selectElements: (ids: string[]) => void;
+    /** Clear the current selection. */
+    clearSelection: () => void;
+}
+/** Collaboration role within a session. */
+type CollaborationRole = 'owner' | 'collaborator' | 'viewer';
+/**
+ * Collaboration transport.
+ *
+ * - `'websocket'` (default): y-websocket against `serverUrl`.
+ * - `'webrtc'`: y-webrtc peer-to-peer; needs no document server. Peers meet
+ *   through the `signaling` servers (WebRTC signaling only, no document data)
+ *   and same-browser tabs additionally sync via BroadcastChannel even without
+ *   any signaling server, which makes this mode usable from static hosting.
+ */
+type CollaborationTransport = 'websocket' | 'webrtc';
+/**
+ * Real-time collaboration configuration.
+ *
+ * The same shape is accepted by the React, Vue, and Angular bindings.
+ */
+interface CollaborationConfig {
+    /** Unique identifier for the collaboration room (alphanumeric, hyphens, underscores). */
+    roomId: string;
+    /**
+     * WebSocket server URL for the Yjs provider (e.g. "wss://collab.example.com").
+     * Ignored (may be empty) when `transport` is `'webrtc'`.
+     */
+    serverUrl: string;
+    /** Transport to use. Defaults to `'websocket'`. */
+    transport?: CollaborationTransport;
+    /**
+     * WebRTC signaling server URLs (only used when `transport` is `'webrtc'`).
+     * Defaults to y-webrtc's built-in public signaling list. Same-browser tabs
+     * sync via BroadcastChannel regardless of signaling availability.
+     */
+    signaling?: string[];
+    /** Display name for the local user. */
+    userName: string;
+    /** Avatar URL for the local user (optional). */
+    userAvatar?: string;
+    /** Hex colour for the local user's cursor/presence indicator. */
+    userColor?: string;
+    /** Optional authentication token sent with the WebSocket handshake. */
+    authToken?: string;
+    /** Role in the session; defaults to `'collaborator'`. */
+    role?: CollaborationRole;
+    /**
+     * Elected-writer write-back callback (Area 3 of the C3 hardening plan).
+     *
+     * When the local user has `role: 'owner'`, the binding debounces changes and
+     * serializes the current Y.Doc state to a PPTX byte array, then calls this
+     * callback so the host can persist the snapshot. Only one writer (the owner)
+     * does this; other collaborators never trigger write-back, eliminating the
+     * last-save-wins problem.
+     */
+    onWriteBack?: (bytes: Uint8Array) => void;
+    /**
+     * Debounce delay (ms) between the last Y.Doc change and the write-back
+     * invocation. Defaults to 5000 ms. Set to 0 to write back on every change
+     * (not recommended for large documents).
+     */
+    writeBackDebounceMs?: number;
+}
+
 /**
  * Core data-model types for the PowerPoint viewer/editor plugin.
  *
@@ -12,15 +169,6 @@ import { ViewerTheme } from './theme/index.js';
  * clipboard operations, undo/redo history, geometry, and shape quick styles.
  */
 
-/**
- * The current operating mode of the PowerPoint viewer.
- *
- * - `"preview"` -- Read-only viewing with no editing controls.
- * - `"edit"` -- Full editing mode with toolbar, inspector, and canvas interaction.
- * - `"present"` -- Fullscreen presentation/slideshow mode with animations.
- * - `"master"` -- Slide master editing mode for template/layout manipulation.
- */
-type ViewerMode = 'preview' | 'edit' | 'present' | 'master';
 /**
  * Union of all shape preset types that the viewer can insert or render.
  * Maps to OOXML `a:prstGeom` preset values (e.g. "rect", "ellipse").
@@ -174,67 +322,6 @@ interface ShapeQuickStyle {
     style: Partial<$>;
 }
 
-/** Collaboration role within a session. */
-type CollaborationRole = 'owner' | 'collaborator' | 'viewer';
-/**
- * Collaboration transport.
- *
- * - `'websocket'` (default): y-websocket against `serverUrl`.
- * - `'webrtc'`: y-webrtc peer-to-peer; needs no document server. Peers meet
- *   through the `signaling` servers (WebRTC signaling only, no document data)
- *   and same-browser tabs additionally sync via BroadcastChannel even without
- *   any signaling server, which makes this mode usable from static hosting.
- */
-type CollaborationTransport = 'websocket' | 'webrtc';
-/**
- * Real-time collaboration configuration.
- *
- * The same shape is accepted by the React, Vue, and Angular bindings.
- */
-interface CollaborationConfig {
-    /** Unique identifier for the collaboration room (alphanumeric, hyphens, underscores). */
-    roomId: string;
-    /**
-     * WebSocket server URL for the Yjs provider (e.g. "wss://collab.example.com").
-     * Ignored (may be empty) when `transport` is `'webrtc'`.
-     */
-    serverUrl: string;
-    /** Transport to use. Defaults to `'websocket'`. */
-    transport?: CollaborationTransport;
-    /**
-     * WebRTC signaling server URLs (only used when `transport` is `'webrtc'`).
-     * Defaults to y-webrtc's built-in public signaling list. Same-browser tabs
-     * sync via BroadcastChannel regardless of signaling availability.
-     */
-    signaling?: string[];
-    /** Display name for the local user. */
-    userName: string;
-    /** Avatar URL for the local user (optional). */
-    userAvatar?: string;
-    /** Hex colour for the local user's cursor/presence indicator. */
-    userColor?: string;
-    /** Optional authentication token sent with the WebSocket handshake. */
-    authToken?: string;
-    /** Role in the session; defaults to `'collaborator'`. */
-    role?: CollaborationRole;
-    /**
-     * Elected-writer write-back callback (Area 3 of the C3 hardening plan).
-     *
-     * When the local user has `role: 'owner'`, the binding debounces changes and
-     * serializes the current Y.Doc state to a PPTX byte array, then calls this
-     * callback so the host can persist the snapshot. Only one writer (the owner)
-     * does this; other collaborators never trigger write-back, eliminating the
-     * last-save-wins problem.
-     */
-    onWriteBack?: (bytes: Uint8Array) => void;
-    /**
-     * Debounce delay (ms) between the last Y.Doc change and the write-back
-     * invocation. Defaults to 5000 ms. Set to 0 to write back on every change
-     * (not recommended for large documents).
-     */
-    writeBackDebounceMs?: number;
-}
-
 /**
  * Base handle interface for file viewer components.
  * Defined locally to avoid dependency on external file-viewer plugin packages.
@@ -377,6 +464,14 @@ interface PowerPointViewerProps {
     onContentChange?: (content: Uint8Array) => void;
     /** Callback when active slide changes */
     onActiveSlideChange?: (slideIndex: number) => void;
+    /** Callback when the viewer mode changes (e.g. edit to present). */
+    onModeChange?: (mode: ViewerMode) => void;
+    /** Callback when the zoom level changes. */
+    onZoomChange?: (zoom: number) => void;
+    /** Callback when element selection changes. */
+    onSelectionChange?: (elementIds: string[]) => void;
+    /** Callback when the total slide count changes (slide added/deleted). */
+    onSlideCountChange?: (count: number) => void;
     /**
      * Host override for the File ▸ Open action. When provided, the built-in
      * native file picker is bypassed and this is invoked instead; the host is
@@ -476,7 +571,7 @@ interface PowerPointViewerProps {
      */
     smartArt3D?: boolean;
 }
-interface PowerPointViewerHandle extends FileViewerHandle {
+interface PowerPointViewerHandle extends FileViewerHandle, PowerPointViewerAPI {
     getContent: () => Promise<Uint8Array>;
 }
 
@@ -500,4 +595,4 @@ declare function getAnimationInitialStyle(preset: f | undefined, nativeAnimation
  */
 declare const PowerPointViewer: React.ForwardRefExoticComponent<PowerPointViewerProps & React.RefAttributes<PowerPointViewerHandle>>;
 
-export { type AccessibilityIssue as A, type StrokeDashOption as B, type CollaborationRole as C, type DragState as D, type EditorHistorySnapshot as E, type FileViewerHandle as F, type SupportedShapeType as G, type ToolbarSection as H, type MarqueeSelectionState as M, PowerPointViewer as P, type ResizeHandle as R, type ShapeAdjustmentDragState as S, type TableCellEditorState as T, type ViewerMode as V, type PowerPointViewerHandle as a, type PowerPointViewerProps as b, type CollaborationConfig as c, type AnimationPresetOption as d, type CanvasSize as e, type ConnectorArrowOption as f, getAnimationInitialStyle as g, type ConnectorGeometryOption as h, type ConnectorGeometryType as i, type ConnectorPathGeometry as j, type DrawingTool as k, type ElementBounds as l, type ElementClipboardPayload as m, type ElementContextMenuAction as n, type ElementContextMenuState as o, type ParsedTableCell as p, type ParsedTableData as q, type PresentationAnimationRuntime as r, type ResizeState as s, type ShapeAdjustmentHandleDescriptor as t, type ShapePreset as u, type ShapeQuickStyle as v, type ShortcutReferenceItem as w, type SlideAlignment as x, type SlideSectionGroup as y, type SlideTransitionOption as z };
+export { type AccessibilityIssue as A, type SlideTransitionOption as B, type CollaborationRole as C, type DragState as D, type EditorHistorySnapshot as E, type FileViewerHandle as F, type StrokeDashOption as G, type SupportedShapeType as H, type ToolbarSection as I, type MarqueeSelectionState as M, PowerPointViewer as P, type ResizeHandle as R, type ShapeAdjustmentDragState as S, type TableCellEditorState as T, type ViewerMode as V, type PowerPointViewerAPI as a, type PowerPointViewerHandle as b, type PowerPointViewerProps as c, type CollaborationConfig as d, type AnimationPresetOption as e, type CanvasSize as f, getAnimationInitialStyle as g, type ConnectorArrowOption as h, type ConnectorGeometryOption as i, type ConnectorGeometryType as j, type ConnectorPathGeometry as k, type DrawingTool as l, type ElementBounds as m, type ElementClipboardPayload as n, type ElementContextMenuAction as o, type ElementContextMenuState as p, type ParsedTableCell as q, type ParsedTableData as r, type PresentationAnimationRuntime as s, type ResizeState as t, type ShapeAdjustmentHandleDescriptor as u, type ShapePreset as v, type ShapeQuickStyle as w, type ShortcutReferenceItem as x, type SlideAlignment as y, type SlideSectionGroup as z };

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-export { P as PowerPointViewer, a as PowerPointViewerHandle, b as PowerPointViewerProps, g as getAnimationInitialStyle } from './PowerPointViewer-BqfQdZFN.mjs';
+export { P as PowerPointViewer, a as PowerPointViewerAPI, b as PowerPointViewerHandle, c as PowerPointViewerProps, V as ViewerMode, g as getAnimationInitialStyle } from './PowerPointViewer-e7LyTw3o.mjs';
 import { Options } from 'html2canvas-pro';
+import * as React$1 from 'react';
 import { ViewerTheme } from './theme/index.js';
 export { ViewerTheme, ViewerThemeColors, defaultCssVars, defaultRadius, defaultThemeColors, themeToCssVars } from './theme/index.js';
-import * as React$1 from 'react';
 import './presentation-BRAUjTRt.js';
 
 interface ViewerThemeProviderProps {

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { P as PowerPointViewer, a as PowerPointViewerHandle, b as PowerPointViewerProps, g as getAnimationInitialStyle } from './PowerPointViewer-BqfQdZFN.js';
+export { P as PowerPointViewer, a as PowerPointViewerAPI, b as PowerPointViewerHandle, c as PowerPointViewerProps, V as ViewerMode, g as getAnimationInitialStyle } from './PowerPointViewer-e7LyTw3o.js';
 import { Options } from 'html2canvas-pro';
+import * as React$1 from 'react';
 import { ViewerTheme } from './theme/index.js';
 export { ViewerTheme, ViewerThemeColors, defaultCssVars, defaultRadius, defaultThemeColors, themeToCssVars } from './theme/index.js';
-import * as React$1 from 'react';
 import './presentation-BRAUjTRt.js';
 
 interface ViewerThemeProviderProps {