pptx-vanilla-viewer 0.1.3 → 0.3.0

package/dist/index.d.cts

@@ -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 } 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';
@@ -1368,9 +1368,403 @@ interface CanvasSize {
     width: number;
     height: number;
 }
+/** 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;
+}
 /** A neutral CSS map (framework `CSSProperties` are structurally compatible). */
 type CssStyleMap = Record<string, string | number>;
 
+/**
+ * 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).
+ *
+ * Everything here is a plain function with no framework / Yjs dependency, so it
+ * can be unit-tested in isolation and shared across the React, Vue, and Angular
+ * bindings. The bindings own the stateful provider lifecycle (creating the
+ * Y.Doc / WebsocketProvider, wiring awareness listeners) and call into these
+ * helpers to validate config, sanitise inbound awareness data, and project it
+ * into render-ready view-models.
+ *
+ * Responsibilities:
+ *  - Validate the room id and detect mixed-content (ws:// from https) up front.
+ *  - Sanitise inbound awareness data (XSS, bounds, colour, avatar, room id).
+ *  - Map awareness state into a `RemoteCursor` view-model for rendering.
+ *  - Derive the presence list (remote users only, stale entries dropped).
+ *  - Deterministic per-user colour assignment + cursor label formatting.
+ *
+ * This mirrors the React `sanitize.ts` / `usePresenceTracking.ts` helpers and
+ * the Angular `collaboration-helpers.ts` (which predates this shared copy).
+ */
+
+/** Connection lifecycle states for the Yjs WebSocket provider. */
+type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+/** 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;
+    timestamp: number;
+    size: number;
+}
+
+/**
+ * Pure handout layout calculations, shared by every binding's print path.
+ *
+ * Handles distributing slides across pages, computing grid dimensions, and
+ * positioning cells within A4 page space. No DOM/framework dependency: callers
+ * render the resulting rectangles however their view layer prefers.
+ */
+/** Supported slides-per-page values. */
+type HandoutSlidesPerPage = 1 | 2 | 3 | 4 | 6 | 9;
+
+/**
+ * Pure print helpers shared by every binding's print path: settings validation,
+ * slide-range / colour-filter resolution, page-count estimation, HTML markup
+ * builders, escaping, and the full print-document assembler.
+ *
+ * No DOM side effects and no `window.print()`: everything is deterministic and
+ * the binding writes the returned HTML string into a print window. The handout
+ * grid geometry lives in `handout-layout`; this module reuses it.
+ *
+ * ng-packagr constraint honoured here (the Angular binding inlines this source
+ * and compiles it through ng-packagr): NO `String.prototype.replaceAll`
+ * (`escapeHtml` uses `.split(x).join(y)` instead).
+ */
+
+/** What to print. */
+type PrintWhat = 'slides' | 'handouts' | 'notes' | 'outline';
+/** Page orientation for the printed output. */
+type PrintOrientation = 'portrait' | 'landscape';
+/** Colour mode for the printed output. */
+type PrintColorMode = 'color' | 'grayscale' | 'blackAndWhite';
+/** Slide range mode. */
+type PrintSlideRange = 'all' | 'current' | 'custom';
+/** Resolved print settings emitted on confirm. */
+interface PrintSettings {
+    printWhat: PrintWhat;
+    orientation: PrintOrientation;
+    colorMode: PrintColorMode;
+    frameSlides: boolean;
+    slidesPerPage: HandoutSlidesPerPage;
+    slideRange: PrintSlideRange;
+    customRangeFrom: number;
+    customRangeTo: number;
+}
+
+/**
+ * A tiny framework-free reactive store: `get` / `set(patch)` / `subscribe`.
+ *
+ * This is deliberately minimal (a few dozen lines, no external deps). It only
+ * carries the vanilla binding's *view state*; all domain logic (parsing,
+ * styles, geometry, text building) stays in `pptx-viewer-core` and
+ * `pptx-viewer-shared`.
+ */
+/** Listener invoked after every state change with the next and previous state. */
+type StoreListener<T> = (state: T, previous: T) => void;
+interface Store<T extends object> {
+    /** Current state snapshot (do not mutate). */
+    get(): T;
+    /** Shallow-merge a partial patch into the state and notify subscribers. */
+    set(patch: Partial<T>): void;
+    /** Subscribe to state changes; returns an unsubscribe function. */
+    subscribe(listener: StoreListener<T>): () => void;
+}
+
+/** `zoom` is either an explicit scale factor (1 = 100%) or fit-to-viewport. */
+type ZoomLevel = number | 'fit';
+/**
+ * The vanilla viewer's reactive view state. Kept intentionally flat and small;
+ * everything here is what the DOM render layer consumes.
+ */
+interface ViewerState {
+    /** Parsed slides (image/media URLs already patched in by the load pipeline). */
+    slides: P[];
+    /** Slide canvas size in CSS pixels. */
+    canvasSize: CanvasSize;
+    /** Archive-path to displayable URL map for media + poster frames. */
+    mediaDataUrls: Map<string, string>;
+    /** Zero-based index of the visible slide. */
+    currentSlide: number;
+    /** Requested zoom (explicit factor or fit-to-viewport). */
+    zoom: ZoomLevel;
+    /** True while a load is in flight. */
+    loading: boolean;
+    /** Error message from the last failed load, or null. */
+    error: string | null;
+    /** True while presentation (fullscreen) mode is active. */
+    presenting: boolean;
+    /** True when editing interactions (select/move/resize/...) are enabled. */
+    editable: boolean;
+    /** Id of the selected element on the current slide, or null. */
+    selectedElementId: string | null;
+    /** True when the document has unsaved edits (cleared by a save). */
+    dirty: boolean;
+    /**
+     * True while a pointer gesture (drag/resize/rotate) is in flight. Thumbnail
+     * re-renders are deferred until the gesture ends.
+     */
+    interactionActive: boolean;
+    /**
+     * True when the speaker-notes panel body is expanded. Persists across slide
+     * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Insert-element factories for the vanilla editor.
+ *
+ * The pure builders wrap the framework-agnostic core/shared factories
+ * (`createTextElement`, `createShapeElement`, `createConnectorElement`,
+ * `newTableElement`) and centre the new element on the slide canvas. The one
+ * async helper (`pickImageElement`) owns the file-picker + `FileReader` DOM
+ * 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 element kinds the Insert ribbon tab can create directly. */
+type InsertKind = 'text' | 'table' | 'shape';
+
+/**
+ * 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;
+}
+
+/** A geometry patch from the inspector (all fields optional). */
+interface GeometryPatch {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    rotation?: number;
+}
+/**
+ * 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 extends TextActions, ArrangeActions, ClipboardActions, SlideActions {
+    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, shapeType?: ShapePresetType): void;
+    insertImage(): Promise<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;
+}
+
 /**
  * Minimal i18n for the vanilla binding.
  *
@@ -1394,6 +1788,25 @@ type TranslationMessages = Record<string, Record<string, string>>;
  */
 declare function createTranslator(locale?: string, messages?: TranslationMessages): Translator;
 
+/** Selection-derived state the inspector reflects. */
+interface InspectorState {
+    hasSelection: boolean;
+    canShape: boolean;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+    fillColor: string | undefined;
+    strokeColor: string | undefined;
+    strokeWidth: number;
+}
+interface Inspector {
+    el: HTMLElement;
+    update(state: InspectorState): void;
+    setEditable(editable: boolean): void;
+}
+
 /** State the panel needs to reflect: the slide to read notes from, and whether edits are allowed. */
 interface NotesPanelUpdate {
     slide: P | undefined;
@@ -1411,44 +1824,54 @@ 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;
+    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;
+    /** 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;
     /** Scrollable centring viewport around the stage. */
     viewport: HTMLElement;
@@ -1473,6 +1896,80 @@ interface PresentationController {
     dispose(): void;
 }
 
+interface EditorController {
+    /** (Re)wire listeners + overlay into the current chrome (after mount). */
+    attachChrome(): void;
+    detachChrome(): void;
+    /** Called by the render controller after every stage render. */
+    onStageRendered(): void;
+    /** True while editing owns the keyboard (selection or inline editing). */
+    capturesKeyboard(): boolean;
+    /** Drop history/selection/dirty state (new content loaded). */
+    reset(): void;
+    setEditable(editable: boolean): void;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    deleteSelected(): void;
+    duplicateSelected(): string | null;
+    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>;
+    downloadPptx(fileName?: string): Promise<void>;
+    destroy(): void;
+}
+
+/** Everything the controller needs after a stage (re)render. */
+interface SyncStageParams {
+    doc: Document;
+    /** The stage host (position: relative), for layering a transition overlay. */
+    stageWrap: HTMLElement;
+    /** The freshly rendered, fully-visible main stage node. */
+    stage: HTMLElement;
+    /** The slide the stage renders, or `undefined` when empty. */
+    slide: P | undefined;
+    /** Zero-based index of the rendered slide. */
+    slideIndex: number;
+    /** True only when the live (fullscreen) presentation stage is active. */
+    presenting: boolean;
+}
+/**
+ * The presentation-mode playback state machine for the vanilla binding.
+ *
+ * It owns the click-stepped animation cursor and the slide-transition overlay,
+ * both driven by the shared framework-agnostic helpers. It is consulted from
+ * two seams in the rebuild-per-change render flow:
+ *
+ *  - {@link PresentationPlayback.syncStage} runs after every stage render:
+ *    on a slide entry it rebuilds the click groups, resets the step, hides
+ *    pending entrances, and (when the slide changed mid-show) plays the
+ *    incoming slide's transition over a snapshot of the outgoing stage.
+ *  - {@link PresentationPlayback.advance} runs on each forward navigation
+ *    key/tap while presenting: it reveals the next animation build in place
+ *    (no rebuild) and reports whether a build remained, so the caller only
+ *    advances the slide once the timeline is exhausted.
+ */
+interface PresentationPlayback {
+    /**
+     * Reveal the next on-click animation build for the current slide. Returns
+     * `true` if a build was revealed (stay on the slide); `false` when the
+     * slide's builds are exhausted (the caller should advance to the next slide).
+     */
+    advance(): boolean;
+    /** True when every click group on the current slide has been revealed. */
+    isComplete(): boolean;
+    /** Sync playback + transitions after a stage (re)render. */
+    syncStage(params: SyncStageParams): void;
+    /** Cancel any running transition and forget all per-slide state. */
+    reset(): void;
+}
+
 /** Discriminant values of the {@link PptxElement} union (`'text'`, `'chart'`, ...). */
 type PptxElementType = a['type'];
 /**
@@ -1620,79 +2117,137 @@ declare function renderSlideStage(options: SlideStageOptions): HTMLElement;
  */
 declare function createDefaultRegistry(): ElementRendererRegistry;
 
+interface RenderController {
+    /** Re-render everything (used after a chrome rebuild). */
+    renderAll(): void;
+    /** Re-render the main stage + toolbar counters at the current state. */
+    renderStage(): void;
+    /** Rebuild the thumbnail rail from the current slide list. */
+    renderThumbnails(): void;
+    /** Resolve the requested zoom into a concrete scale factor. */
+    effectiveScale(): number;
+    /**
+     * Presentation-mode animation/transition playback, driven by the stage
+     * rebuild flow. Navigation (`viewer-controls`) consults `advance()` so a
+     * "next" first steps the on-click animation timeline before advancing slides.
+     */
+    readonly presentationPlayback: PresentationPlayback;
+}
+
 /**
- * A tiny framework-free reactive store: `get` / `set(patch)` / `subscribe`.
+ * Debounced autosave for the vanilla viewer, layered on the shared IndexedDB
+ * recovery store (`pptx-viewer-shared/autosave-store`).
  *
- * This is deliberately minimal (a few dozen lines, no external deps). It only
- * carries the vanilla binding's *view state*; all domain logic (parsing,
- * styles, geometry, text building) stays in `pptx-viewer-core` and
- * `pptx-viewer-shared`.
+ * Semantics mirror the React/Vue bindings: a local edit marks the document
+ * dirty; a debounce timer then re-serializes the deck through
+ * `PptxHandler.save` and persists it under `filePath` via
+ * `saveAutosaveSnapshot` (evicting the oldest record on quota exhaustion). The
+ * recovery blob is a crash-safety net only; it never clears the editor's dirty
+ * flag or stands in for the user's real Save.
+ *
+ * On construction it probes `getAutosaveSnapshot(filePath)` and, when a snapshot
+ * from a previous session exists, offers it back through `onRecovery` so the
+ * host can decide whether to restore it (e.g. via `loadFile`).
  */
-/** Listener invoked after every state change with the next and previous state. */
-type StoreListener<T> = (state: T, previous: T) => void;
-interface Store<T extends object> {
-    /** Current state snapshot (do not mutate). */
-    get(): T;
-    /** Shallow-merge a partial patch into the state and notify subscribers. */
-    set(patch: Partial<T>): void;
-    /** Subscribe to state changes; returns an unsubscribe function. */
-    subscribe(listener: StoreListener<T>): () => void;
-}
+type AutosaveStatus = 'idle' | 'saving' | 'saved' | 'error';
+
+/** Per-slide progress callback: `(currentSlideIndex, totalSlides)`. */
+type ExportProgress = (current: number, total: number) => void;
 
-/** `zoom` is either an explicit scale factor (1 = 100%) or fit-to-viewport. */
-type ZoomLevel = number | 'fit';
 /**
- * The vanilla viewer's reactive view state. Kept intentionally flat and small;
- * everything here is what the DOM render layer consumes.
+ * Animated-GIF export for the vanilla binding. All slides are captured (one
+ * frame per slide) via the injected `rasterizeSlide`, then encoded with the
+ * shared pure-JS GIF89a encoder (`pptx-viewer-shared` `gif-encoder`: median-cut
+ * quantisation + LZW). Frame timing comes from the shared `planGifFrames`
+ * planner and oversized captures are downscaled via `clampGifDimensions`; only
+ * the DOM capture / canvas scaling / Blob download driver lives here.
  */
-interface ViewerState {
-    /** Parsed slides (image/media URLs already patched in by the load pipeline). */
-    slides: P[];
-    /** Slide canvas size in CSS pixels. */
-    canvasSize: CanvasSize;
-    /** Archive-path to displayable URL map for media + poster frames. */
-    mediaDataUrls: Map<string, string>;
-    /** Zero-based index of the visible slide. */
-    currentSlide: number;
-    /** Requested zoom (explicit factor or fit-to-viewport). */
-    zoom: ZoomLevel;
-    /** True while a load is in flight. */
-    loading: boolean;
-    /** Error message from the last failed load, or null. */
-    error: string | null;
-    /** True while presentation (fullscreen) mode is active. */
-    presenting: boolean;
-    /** True when editing interactions (select/move/resize/...) are enabled. */
-    editable: boolean;
-    /** Id of the selected element on the current slide, or null. */
-    selectedElementId: string | null;
-    /** True when the document has unsaved edits (cleared by a save). */
-    dirty: boolean;
+/** Options for the animated-GIF export (all slides, one frame per slide). */
+interface ExportGifOptions {
     /**
-     * True while a pointer gesture (drag/resize/rotate) is in flight. Thumbnail
-     * re-renders are deferred until the gesture ends.
+     * Duration each slide is shown, in milliseconds (default 2000). Per-slide
+     * overrides can be supplied via {@link ExportGifOptions.slideTimingsMs}.
      */
-    interactionActive: boolean;
+    slideDurationMs?: number;
     /**
-     * True when the speaker-notes panel body is expanded. Persists across slide
-     * navigation for the life of the viewer instance (in-memory only).
+     * Per-slide duration overrides in milliseconds (index maps to slide index,
+     * e.g. rehearsed timings). Flows through the shared `planGifFrames` plan
+     * into per-frame GIF delays.
      */
-    notesExpanded: boolean;
+    slideTimingsMs?: number[];
+    /**
+     * Cap on the longer side of the encoded frames, in pixels (default 1920).
+     * Captured canvases larger than this are downscaled before quantisation,
+     * keeping encode time and file size manageable.
+     */
+    maxDimension?: number;
+    /** Capture-phase progress callback: `(currentSlide, totalSlides)`. */
+    onProgress?: ExportProgress;
+    /** Abort the export early; the capture loop checks this between slides. */
+    signal?: AbortSignal;
 }
 
-interface RenderController {
-    /** Re-render everything (used after a chrome rebuild). */
-    renderAll(): void;
-    /** Re-render the main stage + toolbar counters at the current state. */
-    renderStage(): void;
-    /** Rebuild the thumbnail rail from the current slide list. */
-    renderThumbnails(): void;
-    /** Resolve the requested zoom into a concrete scale factor. */
-    effectiveScale(): number;
+/**
+ * Print for the vanilla binding, assembled entirely from the shared print
+ * module (`pptx-viewer-shared` `print-document`): `validatePrintSettings`,
+ * `computeSlideIndices` / `computeColorFilter`, the `build*Html` body markup
+ * builders, and the DOMPurify-hardened `buildPrintHtmlDocument` assembler.
+ * Only the drivers live here: rasterising the selected slides to data URLs and
+ * writing the document into a print window. Vanilla port of Vue's `usePrint`
+ * raster path (slides / notes / handouts / outline).
+ */
+/**
+ * Open a print window for a complete HTML document and trigger printing.
+ * Returns `false` when the window could not be opened (popup blocker).
+ */
+type OpenPrintWindow = (htmlDocument: string) => boolean;
+/**
+ * Options for `print`: any subset of the shared `PrintSettings` (unspecified
+ * fields fall back to `DEFAULT_PRINT_SETTINGS`, i.e. all slides, landscape,
+ * full colour) plus progress/abort and a print-window override.
+ */
+interface PrintOptions extends Partial<PrintSettings> {
+    /** Rasterisation progress callback: `(currentSlide, totalSlidesToPrint)`. */
+    onProgress?: ExportProgress;
+    /** Abort before the window opens; checked between slide captures. */
+    signal?: AbortSignal;
+    /**
+     * Override how the assembled document is opened (e.g. write it into a
+     * hidden iframe). Popup-blocker caveat: the default opener uses
+     * `window.open`, which browsers typically only allow inside a user
+     * gesture, so call `print()` from a click handler; when the popup is
+     * blocked the returned promise resolves `false`.
+     */
+    openPrintWindow?: OpenPrintWindow;
+}
+
+/**
+ * WebM video export for the vanilla binding, driven by the shared `video-plan`
+ * module: `planVideoSegments` (per-slide segment timing + frame counts),
+ * `fpsToFrameIntervalMs` (draw-loop pacing), and `pickSupportedMimeType` over
+ * `WEBM_MIME_CANDIDATES` (MediaRecorder codec selection). Only the browser
+ * driver lives here: capture each slide to a canvas, replay the canvases onto
+ * a recording canvas fed to `captureStream()` + `MediaRecorder`, and download
+ * the resulting Blob. Vanilla port of React's `exportAllSlidesAsVideo`.
+ */
+/** Options for the WebM video export (all slides). */
+interface ExportVideoOptions {
+    /** Duration each slide is held, in milliseconds (default 3000). */
+    slideDurationMs?: number;
+    /** Per-slide duration overrides in milliseconds (index maps to slide index). */
+    slideTimingsMs?: number[];
+    /** Recording frame rate in frames per second (default 30). */
+    fps?: number;
+    /** MediaRecorder video bitrate in bits per second (default 5,000,000). */
+    videoBitsPerSecond?: number;
+    /** Capture-phase progress callback: `(currentSlide, totalSlides)`. */
+    onProgress?: ExportProgress;
+    /** Recording-phase progress callback: `(currentSlide, totalSlides)`. */
+    onRecordProgress?: ExportProgress;
+    /** Abort the export early; checked between slides and between frames. */
+    signal?: AbortSignal;
 }
 
-/** Per-slide progress callback: `(currentSlideIndex, totalSlides)`. */
-type ExportProgress = (current: number, total: number) => void;
 /** Options for the multi-slide PDF export (progress + cooperative cancel). */
 interface ExportPdfOptions {
     /** Capture-phase progress callback: `(currentSlide, totalSlides)`. */
@@ -1707,13 +2262,6 @@ interface ExportPdfOptions {
  */
 type PptxViewerSource = ArrayBuffer | Uint8Array | Blob | string;
 
-/**
- * Public API types for the vanilla (zero-framework) PowerPoint viewer.
- *
- * Derived from the Vue binding's `PowerPointViewerProps` / emits, translated
- * to plain options + callback functions (there is no framework event system
- * to emit through).
- */
 /** Callbacks mirroring the Vue component's emits. */
 interface PptxViewerCallbacks {
     /** Fired after a presentation loads successfully. */
@@ -1735,6 +2283,16 @@ interface PptxViewerCallbacks {
     onDirtyChange?: (dirty: boolean) => void;
     /** Fired when the selected element changes (`null` = no selection). */
     onSelectionChange?: (elementId: string | null) => void;
+    /** Fired on every autosave lifecycle transition (`saving`/`saved`/`error`). */
+    onAutosaveStatus?: (status: AutosaveStatus) => void;
+    /**
+     * Offered a recovery snapshot found in the shared IndexedDB store on start
+     * (a previous session's autosave for the same `autosaveFilePath`). The host
+     * decides whether to restore it, e.g. `viewer.loadFile(record.data)`.
+     */
+    onAutosaveRecovery?: (record: AutosaveRecord) => void;
+    /** Fired on every collaboration connection-status transition. */
+    onCollaborationStatus?: (status: ConnectionStatus) => void;
 }
 interface PptxViewerOptions extends PptxViewerCallbacks {
     /**
@@ -1769,6 +2327,16 @@ interface PptxViewerOptions extends PptxViewerCallbacks {
     showToolbar?: boolean;
     /** Show the thumbnail sidebar (default `true`). */
     showThumbnails?: boolean;
+    /**
+     * Build the editing format toolbar row (bold/fill/insert/z-order); default
+     * `true`. The row is only *visible* while editing is enabled.
+     */
+    showFormatToolbar?: boolean;
+    /**
+     * Build the property inspector panel (position/size/fill/line); default
+     * `true`. Only *visible* while editing is enabled.
+     */
+    showInspector?: boolean;
     /**
      * Custom element-renderer registry. Defaults to `createDefaultRegistry()`;
      * pass your own (or mutate the default via `getRegistry()`) to add or
@@ -1784,6 +2352,30 @@ interface PptxViewerOptions extends PptxViewerCallbacks {
      * mirroring the Vue/React/Angular bindings).
      */
     smartArt3D?: boolean;
+    /**
+     * Enable debounced autosave (default `false`): after each local edit the deck
+     * is re-serialized and stashed in the shared IndexedDB recovery store as a
+     * crash-safety net (it never replaces the user's real Save). The toolbar shows
+     * a small status pill; a snapshot from a prior session is offered through
+     * {@link PptxViewerCallbacks.onAutosaveRecovery}.
+     */
+    autosave?: boolean;
+    /** Debounce window (ms) between an edit and the persisted snapshot (default 2000). */
+    autosaveIntervalMs?: number;
+    /** IndexedDB recovery key for autosave (default `'presentation.pptx'`). */
+    autosaveFilePath?: string;
+    /**
+     * Start a real-time collaboration session immediately (Yjs over y-websocket
+     * or serverless y-webrtc). Local edits publish to peers and remote edits
+     * merge in granularly; a `role: 'viewer'` config forces read-only. Start or
+     * stop a session later with {@link PptxViewerInstance.startCollaboration} /
+     * {@link PptxViewerInstance.stopCollaboration}.
+     *
+     * Note: media/OLE/3D/ink binary payloads are not carried over the wire (a
+     * shared codec limitation), and a remote update replaces the whole local
+     * slide array, so a joiner's host-provided media can degrade.
+     */
+    collaboration?: CollaborationConfig;
 }
 /** The viewer handle returned by `createPptxViewer`. */
 interface PptxViewerInstance {
@@ -1843,6 +2435,26 @@ interface PptxViewerInstance {
      * `jspdf` is dynamically imported on first use.
      */
     exportPdf(options?: ExportPdfOptions): Promise<void>;
+    /**
+     * Export every slide as an animated GIF download (one frame per slide,
+     * `slideDurationMs` per frame). Slides are captured off-screen like
+     * `exportSlidePng` and encoded with the shared pure-JS GIF89a encoder.
+     */
+    exportGif(options?: ExportGifOptions): Promise<void>;
+    /**
+     * Export every slide as a WebM video download: each captured slide is held
+     * for its configured duration on a canvas stream recorded by
+     * `MediaRecorder` (codec picked from the shared WebM candidates).
+     */
+    exportVideo(options?: ExportVideoOptions): Promise<void>;
+    /**
+     * Assemble the printable document (slides / notes / handouts / outline)
+     * and open it in a new print window. Resolves `false` when the popup was
+     * blocked: browsers typically only allow `window.open` inside a user
+     * gesture, so call this from a click handler (or pass a custom
+     * `openPrintWindow` that writes into an iframe you own).
+     */
+    print(options?: PrintOptions): Promise<boolean>;
     /** The element-renderer registry in effect (extension point). */
     getRegistry(): ElementRendererRegistry;
     /**
@@ -1851,6 +2463,18 @@ interface PptxViewerInstance {
      * archive access) without extra APIs here.
      */
     getHandler(): PptxHandler | null;
+    /**
+     * Start (or restart) a real-time collaboration session. Resolves once the
+     * transport is created; connection status arrives via
+     * {@link PptxViewerCallbacks.onCollaborationStatus}.
+     */
+    startCollaboration(config: CollaborationConfig): Promise<void>;
+    /** Stop the active collaboration session (no-op when none is running). */
+    stopCollaboration(): void;
+    /** Current collaboration connection status (`'disconnected'` when inactive). */
+    getCollaborationStatus(): ConnectionStatus;
+    /** Force an immediate autosave snapshot (no-op when autosave is disabled). */
+    autosaveNow(): Promise<void>;
     /** Tear down DOM, listeners, Blob URLs, and the core handler. */
     destroy(): void;
 }
@@ -1874,6 +2498,8 @@ interface ChromeHost {
     lifecycle: ChromeLifecycle;
     editor: {
         commitNotes(notes: string): void;
+        getEditActions(): EditActions;
+        getFindReplaceActions(): FindReplaceActions;
     };
     prev(): void;
     next(): void;
@@ -1888,41 +2514,51 @@ 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>;
 }
 
-interface EditorController {
-    /** (Re)wire listeners + overlay into the current chrome (after mount). */
-    attachChrome(): void;
-    detachChrome(): void;
-    /** Called by the render controller after every stage render. */
-    onStageRendered(): void;
-    /** True while editing owns the keyboard (selection or inline editing). */
-    capturesKeyboard(): boolean;
-    /** Drop history/selection/dirty state (new content loaded). */
-    reset(): void;
-    setEditable(editable: boolean): void;
-    undo(): void;
-    redo(): void;
-    canUndo(): boolean;
-    canRedo(): boolean;
-    deleteSelected(): void;
-    duplicateSelected(): string | null;
-    getSelectedElementId(): string | null;
-    /** Commit the speaker-notes textarea's plain text onto the current slide. */
-    commitNotes(notes: string): void;
-    save(): Promise<Uint8Array>;
-    downloadPptx(fileName?: string): Promise<void>;
+/** The export slice of the public viewer API (see `PptxViewerInstance`). */
+interface ViewerExportApi {
+    /** Export a single slide as a PNG download. Defaults to the current slide. */
+    exportSlidePng(index?: number): Promise<void>;
+    /** Export every slide as a multi-page PDF download (one slide per page). */
+    exportPdf(options?: ExportPdfOptions): Promise<void>;
+    /** Export every slide as an animated GIF download (one frame per slide). */
+    exportGif(options?: ExportGifOptions): Promise<void>;
+    /** Export every slide as a WebM video download (MediaRecorder). */
+    exportVideo(options?: ExportVideoOptions): Promise<void>;
+    /** Open the assembled print document in a print window (`false` = blocked). */
+    print(options?: PrintOptions): Promise<boolean>;
+}
+interface ExportLifecycle extends ViewerExportApi {
+    /** Remove the off-screen capture stage from the DOM. */
     destroy(): void;
 }
+/**
+ * Base class implementing the export slice of `PptxViewerInstance` by
+ * delegating to the instance's {@link ExportLifecycle}. `PptxViewer` extends
+ * this, so new export formats are wired here (and in the export controller)
+ * without growing the size-capped `PptxViewer.ts`.
+ */
+declare abstract class ViewerExportHost implements ViewerExportApi {
+    protected abstract readonly exporter: ExportLifecycle;
+    exportSlidePng(index?: number): Promise<void>;
+    exportPdf(options?: ExportPdfOptions): Promise<void>;
+    exportGif(options?: ExportGifOptions): Promise<void>;
+    exportVideo(options?: ExportVideoOptions): Promise<void>;
+    print(options?: PrintOptions): Promise<boolean>;
+}
 
 /**
- * The zero-framework PowerPoint viewer. Construct via {@link createPptxViewer}
- * (or `new PptxViewer(container, options)`): builds its chrome inside
- * `container`, loads `options.source` when given, and re-renders through a
- * tiny reactive store. All parsing lives in `pptx-viewer-core`; all pure
- * render logic in `pptx-viewer-shared`.
+ * The zero-framework PowerPoint viewer. Construct via {@link createPptxViewer}:
+ * builds chrome inside `container`, loads `options.source` when given, and
+ * re-renders through a tiny reactive store.
  */
-declare class PptxViewer implements PptxViewerInstance, ChromeHost {
+declare class PptxViewer extends ViewerExportHost implements PptxViewerInstance, ChromeHost {
     readonly container: HTMLElement;
     readonly doc: Document;
     readonly options: PptxViewerOptions;
@@ -1931,9 +2567,11 @@ declare class PptxViewer implements PptxViewerInstance, ChromeHost {
     t: Translator;
     lifecycle: ChromeLifecycle;
     editor: EditorController;
+    protected readonly exporter: ExportLifecycle;
     private readonly loading;
-    private readonly exportLifecycle;
     private readonly registry;
+    private readonly sessions;
+    private readonly controls;
     private destroyed;
     constructor(container: HTMLElement, options?: PptxViewerOptions);
     loadFile(file: Blob | ArrayBuffer | Uint8Array): Promise<void>;
@@ -1960,30 +2598,22 @@ declare class PptxViewer implements PptxViewerInstance, ChromeHost {
     save(): Promise<Uint8Array>;
     downloadPptx(fileName?: string): Promise<void>;
     deleteSelected(): void;
-    exportSlidePng(index?: number): Promise<void>;
-    exportPdf(options?: ExportPdfOptions): Promise<void>;
     getSelectedElementId(): string | null;
     enterPresentation(): Promise<void>;
     exitPresentation(): Promise<void>;
     getRegistry(): ElementRendererRegistry;
     getHandler(): PptxHandler | null;
+    startCollaboration(config: CollaborationConfig): Promise<void>;
+    stopCollaboration(): void;
+    getCollaborationStatus(): ConnectionStatus;
+    autosaveNow(): Promise<void>;
     destroy(): void;
     private remountChrome;
 }
-/**
- * Create a PowerPoint viewer inside `container`.
- *
- * ```ts
- * import { createPptxViewer } from 'pptx-vanilla-viewer';
- * const viewer = createPptxViewer(document.querySelector('#host')!, {
- * 	source: '/deck.pptx',
- * 	onSlideChange: (i) => console.log('slide', i + 1),
- * });
- * ```
- */
+/** Create a PowerPoint viewer inside `container` (see {@link PptxViewerOptions}). */
 declare function createPptxViewer(container: HTMLElement, options?: PptxViewerOptions): PptxViewerInstance;
 
 /** The complete viewer stylesheet text (for hosts that self-manage CSS). */
 declare function getViewerCss(): string;
 
-export { type CssStyleMap, type ElementRenderContext, type ElementRenderer, type ElementRendererRegistry, type ExportPdfOptions, type ExportProgress, type PptxElementType, PptxHandler, PptxViewer, type PptxViewerCallbacks, type PptxViewerInstance, type PptxViewerOptions, type PptxViewerSource, type SlideStageOptions, type TranslationMessages, type Translator, type ViewerState, type ZoomLevel, applyStyleMap, createDefaultRegistry, createEl, createElementRendererRegistry, createPptxViewer, createSvgEl, createTranslator, getViewerCss, renderSlideStage };
+export { type AutosaveRecord, type AutosaveStatus, type CollaborationConfig, type CollaborationRole, type CollaborationTransport, type ConnectionStatus, type CssStyleMap, type ElementRenderContext, type ElementRenderer, type ElementRendererRegistry, type ExportGifOptions, type ExportPdfOptions, type ExportProgress, type ExportVideoOptions, type OpenPrintWindow, type PptxElementType, PptxHandler, PptxViewer, type PptxViewerCallbacks, type PptxViewerInstance, type PptxViewerOptions, type PptxViewerSource, type PrintOptions, type SlideStageOptions, type TranslationMessages, type Translator, type ViewerState, type ZoomLevel, applyStyleMap, createDefaultRegistry, createEl, createElementRendererRegistry, createPptxViewer, createSvgEl, createTranslator, getViewerCss, renderSlideStage };