pptx-svelte-viewer 2.7.1 → 2.9.0

package/dist/viewer/index.d.ts

@@ -910,6 +910,27 @@ interface ShapeStyle {
   /** Raw `a:ln/a:pattFill` XML preserved for round-trip when the outline is
    *  pattern-filled. Re-emitted verbatim as the line's single fill on save. */
   strokePatternXml?: XmlObject;
+  /**
+   * Structured stops of a gradient outline (`a:ln/a:gradFill/a:gsLst`), in the
+   * same shape as {@link fillGradientStops}.
+   *
+   * The raw XML above round-trips a gradient outline on save, but a renderer
+   * cannot paint from it: it needs resolved colours and positions. Without
+   * these, every binding fell back to {@link strokeColor} - a single averaged
+   * colour - so a two-tone outline painted flat and a fade-to-transparent
+   * outline painted fully opaque.
+   */
+  strokeGradientStops?: ShapeStyle['fillGradientStops'];
+  /** Gradient outline angle in OOXML degrees (`a:lin/@ang`), 0 = left to right. */
+  strokeGradientAngle?: number;
+  /** Gradient outline kind: `linear` (`a:lin`) or `radial` (`a:path`). */
+  strokeGradientType?: ShapeStyle['fillGradientType'];
+  /** Path-gradient shape for a radial outline (`a:path/@path`). */
+  strokeGradientPathType?: ShapeStyle['fillGradientPathType'];
+  /** Preset name of a pattern outline (`a:ln/a:pattFill/@prst`). */
+  strokePatternPreset?: string;
+  /** Background colour of a pattern outline (`a:ln/a:pattFill/a:bgClr`). */
+  strokePatternBackgroundColor?: string;
   strokeWidth?: number;
   strokeOpacity?: number;
   strokeDash?: StrokeDashType;
@@ -8607,6 +8628,37 @@ interface SnapLine {
   position: number;
 }
 //#endregion
+//#region src/render/text-field-substitution.d.ts
+/**
+ * Text-field placeholder substitution, shared by every binding's text
+ * renderer.
+ *
+ * Pure string logic: resolves OOXML field runs (slide number, date/time,
+ * header/footer, document properties, slide title) into their display text.
+ * Extracted from the React `viewer/utils/text-field-substitution` module so
+ * every binding substitutes identically.
+ */
+/** Context for substituting field placeholders (slide number, date/time, header/footer, etc.). */
+interface FieldSubstitutionContext {
+  slideNumber?: number;
+  dateTimeText?: string;
+  /** OOXML date-format pattern from header/footer settings (e.g. "M/d/yyyy"). */
+  dateFormat?: string;
+  /** Footer text from PptxHeaderFooter settings. */
+  footerText?: string;
+  /** Header text from PptxHeaderFooter settings. */
+  headerText?: string;
+  /** Custom document properties for `docproperty` field substitution (keyed by property name). */
+  customProperties?: ReadonlyArray<{
+    name: string;
+    value: string;
+  }>;
+  /** Locale string for date/time formatting (e.g. "en-US"). Falls back to browser default. */
+  locale?: string;
+  /** Title text extracted from the first title placeholder on the slide. */
+  slideTitle?: string;
+}
+//#endregion
 //#region src/render/collaboration-presence.d.ts
 /** Connection lifecycle states for the Yjs WebSocket provider. */
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
@@ -8879,6 +8931,10 @@ interface ElementClipboardPayload {
 //#endregion
 //#region src/render/template-editing.d.ts
 type TemplateElementMap = Record<string, PptxElement[]>;
+/** The percentage one zoom-in press moves to, clamped. */
+declare function zoomInPercent(percent: number): number;
+/** The percentage one zoom-out press moves to, clamped. */
+declare function zoomOutPercent(percent: number): number;
 //#endregion
 //#region src/render/viewer-preferences.d.ts
 /** Framework-neutral viewer preferences surfaced by Settings dialogs. */
@@ -8932,6 +8988,125 @@ type ToolbarButtonId = 'share' | 'broadcast' | 'export' | 'undo' | 'redo' | 'rec
 type ToolbarTabId = 'file' | 'home' | 'insert' | 'draw' | 'design' | 'transitions' | 'animations' | 'slideShow' | 'record' | 'review' | 'view' | 'help';
 type ToolbarActionId = ToolbarButtonId | ToolbarTabId;
 //#endregion
+//#region src/render/options/viewer-options.d.ts
+/**
+ * Full PowerPoint "File > Options" parity model.
+ *
+ * Groups mirror the ten categories of PowerPoint's Options dialog. Values are
+ * flat primitives per group so the dialog panes can be rendered generically
+ * from `VIEWER_OPTIONS_SCHEMA` in every binding. The legacy six-toggle
+ * `ViewerPreferences` surface stays supported via the mapping helpers below.
+ */
+type ScreenTipStyle = 'descriptions' | 'plain' | 'off';
+type DisplayOptimization = 'appearance' | 'compatibility';
+type ImageResolutionPreset = 'highFidelity' | 'ppi330' | 'ppi220' | 'ppi150' | 'ppi96';
+type OpenDocumentsView = 'savedView' | 'normal' | 'outline' | 'slideSorter' | 'notes';
+type DefaultExportFormat = 'pptx' | 'pdf' | 'png';
+type QuickAccessPosition = 'above' | 'below';
+type FeedbackSoundScheme = 'modern' | 'classic';
+type OptionsPrintWhat = 'slides' | 'handouts' | 'notes' | 'outline';
+type OptionsPrintColorMode = 'color' | 'grayscale' | 'blackAndWhite';
+interface ViewerGeneralOptions {
+  displayOptimization: DisplayOptimization;
+  showMiniToolbar: boolean;
+  enableLivePreview: boolean;
+  collapseRibbonAutomatically: boolean;
+  collapseSearchByDefault: boolean;
+  screenTipStyle: ScreenTipStyle;
+  userName: string;
+  userInitials: string;
+  showStartScreen: boolean;
+}
+interface ViewerProofingOptions {
+  autoCorrectTwoInitialCapitals: boolean;
+  autoCorrectCapitalizeFirstLetter: boolean;
+  autoCorrectCapitalizeDayNames: boolean;
+  autoCorrectSmartQuotes: boolean;
+  autoCorrectHyphensToDash: boolean;
+  autoCorrectFractions: boolean;
+  autoCorrectOrdinals: boolean;
+  ignoreUppercase: boolean;
+  ignoreWordsWithNumbers: boolean;
+  ignoreInternetAddresses: boolean;
+  flagRepeatedWords: boolean;
+  checkSpellingAsYouType: boolean;
+  hideSpellingErrors: boolean;
+}
+interface ViewerSaveOptions {
+  autoSave: boolean;
+  autoRecoverIntervalMinutes: number;
+  keepLastAutoRecoveredVersion: boolean;
+  defaultExportFormat: DefaultExportFormat;
+  embedFonts: boolean;
+  embedAllFontCharacters: boolean;
+  cacheRetentionDays: number;
+  clearCacheOnClose: boolean;
+}
+interface ViewerAccessibilityOptions {
+  showAccessibilityStatus: boolean;
+  feedbackWithSound: boolean;
+  soundScheme: FeedbackSoundScheme;
+  showShortcutKeysInScreenTips: boolean;
+  reducedMotion: boolean;
+}
+interface ViewerAdvancedOptions {
+  autoSelectEntireWord: boolean;
+  allowTextDragAndDrop: boolean;
+  maximumUndoSteps: number;
+  useSmartCutAndPaste: boolean;
+  showPasteOptionsButton: boolean;
+  imageDefaultResolution: ImageResolutionPreset;
+  doNotCompressImages: boolean;
+  chartPropertiesFollowDataPoint: boolean;
+  recentPresentationsCount: number;
+  showVerticalRuler: boolean;
+  showGrid: boolean;
+  snapToGrid: boolean;
+  disableHardwareAcceleration: boolean;
+  openDocumentsView: OpenDocumentsView;
+  slideShowShowMenuOnRightClick: boolean;
+  slideShowShowPopupToolbar: boolean;
+  slideShowPromptKeepInkAnnotations: boolean;
+  slideShowEndWithBlackSlide: boolean;
+  printInBackground: boolean;
+  printHighQuality: boolean;
+  printUseMostRecentSettings: boolean;
+  printWhat: OptionsPrintWhat;
+  printColorMode: OptionsPrintColorMode;
+  printHiddenSlides: boolean;
+  printScaleToFit: boolean;
+  printFrameSlides: boolean;
+}
+interface ViewerRibbonOptions {
+  /** Ribbon tabs unticked in Customize Ribbon. The File tab can never be hidden. */
+  hiddenTabIds: ToolbarTabId[];
+}
+interface ViewerQuickAccessOptions {
+  visible: boolean;
+  position: QuickAccessPosition;
+  showCommandLabels: boolean;
+  /** Ordered ids from `QUICK_ACCESS_COMMAND_CATALOG`. */
+  commandIds: string[];
+}
+interface ViewerTrustOptions {
+  openInProtectedView: boolean;
+  allowExternalContent: boolean;
+  confirmExternalHyperlinks: boolean;
+}
+interface ViewerOptions {
+  general: ViewerGeneralOptions;
+  proofing: ViewerProofingOptions;
+  save: ViewerSaveOptions;
+  accessibility: ViewerAccessibilityOptions;
+  advanced: ViewerAdvancedOptions;
+  ribbon: ViewerRibbonOptions;
+  quickAccess: ViewerQuickAccessOptions;
+  trust: ViewerTrustOptions;
+}
+type ViewerOptionsGroupId = keyof ViewerOptions;
+type ViewerOptionPrimitive = boolean | number | string;
+type StoredViewerOptions = { [G in ViewerOptionsGroupId]?: Partial<ViewerOptions[G]>; };
+//#endregion
 //#region src/export/handout-layout.d.ts
 /**
  * Pure handout layout calculations, shared by every binding's print path.
@@ -8963,7 +9138,34 @@ interface PrintSettings {
   customRangeFrom: number;
   customRangeTo: number;
 }
+interface ViewerOptionsStoreInit {
+  /** Seed values layered over defaults before persisted values are applied. */
+  initial?: StoredViewerOptions;
+  /** Skip localStorage entirely (hosts that own persistence themselves). */
+  persist?: boolean;
+}
 
+//#endregion
+//#region src/ai/change-diff.d.ts
+/** What kind of change an element underwent. */
+type AiChangeKind = 'added' | 'removed' | 'moved' | 'resized' | 'restyled' | 'text';
+/** Axis-aligned bounds in slide (CSS pixel) coordinates. */
+interface AiChangeBounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+/** One element's change, with old/new bounds for motion. */
+interface AiElementChange {
+  slideIndex: number;
+  elementId: string;
+  kind: AiChangeKind;
+  /** Bounds before the edit (present for removed / moved / resized). */
+  from?: AiChangeBounds;
+  /** Bounds after the edit (present for added / moved / resized / restyled / text). */
+  to?: AiChangeBounds;
+}
 //#endregion
 //#region src/ai/change-animator.d.ts
 /** Host-tunable options for how AI edits are animated on the canvas. */
@@ -8979,6 +9181,23 @@ interface AiChangeAnimationConfig {
   /** Accent colour (any CSS colour) for the glow/ghosts. Default a blue. */
   color?: string;
 }
+/** Config with every field resolved to a concrete value. */
+interface ResolvedAiChangeAnimationConfig {
+  enabled: boolean;
+  durationMs: number;
+  glow: boolean;
+  tween: boolean;
+  color: string;
+}
+/** One batch of changes to animate, plus the slide to reveal for it. */
+interface AiChangeBatch {
+  changes: AiElementChange[];
+  /** Slide index the first change lives on (reveal this to show the edit). */
+  slideIndex: number;
+  /** Monotonic id so a binding can restart its animation on each new batch. */
+  nonce: number;
+  config: ResolvedAiChangeAnimationConfig;
+}
 //#endregion
 //#region src/ai/config.d.ts
 /** The UI message shape exchanged with the assistant. Alias of the SDK type. */
@@ -9184,6 +9403,26 @@ interface PptxAiBridge {
   /** Surface a transient message in the host UI (toast / status line). */
   notify?(message: string, level?: PptxAiNotifyLevel): void;
 }
+//#endregion
+//#region src/ai/tool-target.d.ts
+/**
+ * Pure derivation of the on-canvas focus target a running tool refers to, so
+ * the viewer can behave like a live collaborator: as the assistant reads or
+ * edits the deck, the canvas navigates to the relevant slide and highlights the
+ * element(s) the tool is touching.
+ *
+ * The mapping is intentionally structural (it reads well-known input fields:
+ * `slideIndex`, `elementId`, `elementIdA/B`, `elementIds`, `slideIndexes`,
+ * `newOrder`) and framework-agnostic, so every binding drives the same live
+ * focus. It NEVER performs navigation itself; it only says "what to look at".
+ */
+/** The slide / element(s) a tool invocation is focused on. */
+interface ToolCanvasTarget {
+  /** Zero-based slide index to navigate to, when the tool names one. */
+  slideIndex?: number;
+  /** Element ids on that slide to highlight (may be empty for slide-level tools). */
+  elementIds: string[];
+}
 
 //#endregion
 //#region src/i18n/locale-catalog.d.ts
@@ -9654,101 +9893,256 @@ interface PowerPointViewerApi extends PowerPointViewerAPI {
  */
 declare const PowerPointViewer: Component<PowerPointViewerProps, PowerPointViewerApi>;
 
-/**
- * Shared value types for the Svelte editing layer.
- */
-/** Box geometry in element (unscaled slide) px. */
-interface OverlayBox {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    rotation: number;
-}
-
-interface EditorControllerDeps {
-    getScale(): number;
-    getCurrent(): number;
-    getPresenting(): boolean;
-    getStageRoot(): Element | null;
-    getHolderEl(): HTMLElement | null;
-    onCursorMove?(x: number, y: number): void;
-    onContextMenu?(x: number, y: number): void;
-    getSnapToGrid?(): boolean;
-    getSnapToShape?(): boolean;
-    getGuides?(): readonly {
-        axis: 'h' | 'v';
-        position: number;
-    }[];
+interface SlideCanvasProps {
+    slide: PptxSlide | undefined;
+    canvasSize: CanvasSize;
+    mediaDataUrls: Map<string, string>;
+    /** Effective scale (fit-to-viewport x user zoom), pre-computed by the host. */
+    scale: number;
+    /** True only on the live presentation stage; see `SlideStageProps.presenting`. */
+    presenting?: boolean;
+    /** True while in-place editing is available; gates the pointer handlers and the editing cursor/class. */
+    editingActive?: boolean;
+    editTemplateMode?: boolean;
+    ontablecellcommit?: (elementId: string, rowIndex: number, cellIndex: number, text: string) => void;
+    onsmartartnodecommit?: (elementId: string, nodeId: string, text: string) => void;
+    onsmartartnodefill?: (elementId: string, nodeId: string, fill: string) => void;
+    /** Reports the stage-holder node to the host on mount/teardown (editing hit-surface, export capture anchor). */
+    onstageholder?: (el: HTMLDivElement | null) => void;
+    onstagepointerdown?: (event: PointerEvent) => void;
+    onstagepointermove?: (event: PointerEvent) => void;
+    onstagedblclick?: (event: MouseEvent) => void;
+    onstagecontextmenu?: (event: MouseEvent) => void;
+    /** Fired on any stage click; the host wires this to advance presentation playback. */
+    onstageclick?: (event: MouseEvent) => void;
     /**
-     * Transform inline-editor text at commit time (File > Options > Proofing
-     * AutoCorrect); identity when unset.
+     * True while the AI panel is picking an element: the next element click(s)
+     * become the assistant's focus (highlighted) instead of selecting / editing.
      */
-    transformCommittedText?(text: string): string;
+    aiPickMode?: boolean;
     /**
-     * Collaboration live-preview channel. Inline text only reaches the slides
-     * state on commit, so peers saw nothing while a peer typed; each keystroke is
-     * published through this instead. Omit outside a collaborative viewer.
+     * True while a running AI tool is active: the stage marks itself
+     * `data-pptx-ai-active` so element colour changes tween while the assistant
+     * works (see AiFocusHighlightOverlay's tween rule).
      */
-    getLivePatcher?(): CollaborationLivePatcher | undefined;
-    /** The slide the inline-edited element belongs to (live-preview lookup). */
-    getActiveSlide?(): PptxSlide | undefined;
+    aiActive?: boolean;
+    /** Route a picked canvas element to the AI focus (pick mode only). */
+    onaipickelement?: (elementId: string) => void;
+    /**
+     * Overlay content layered above the slide (selection/editor layer, ink
+     * drawing, alignment guides, presentation annotations, collaboration
+     * cursors, transition overlay, ...). Rendered inside the same
+     * fixed-size, scaled stage-holder as the slide itself. Kept out of this
+     * component's own props (rather than a fixed list of overlay slots) so it
+     * stays free of the live editor/controller instances those overlays need.
+     */
+    children?: svelte.Snippet;
 }
 
 /**
- * Pure, immutable slide-array mutations for the Svelte editor.
+ * ExportUiState: reactive state behind the toolbar `ExportMenu` and the
+ * `ExportProgressModal`. Svelte port of Vue's `useExportProgress` composable:
+ * it owns the modal state (open / title / progress / status), the
+ * `AbortController` the export loops check between slides, and wraps each
+ * multi-slide export (PDF / GIF / WebM) in a `begin -> run -> end` envelope.
+ * All percentage maths + status labels come from `pptx-viewer-shared`
+ * (`export-progress.ts`) so every binding shows identical progress.
  *
- * Mirrors the vanilla binding's `editor-mutations` (in turn the Vue binding's
- * `useEditorOperations` commit helpers), minus the reactivity: every function
- * takes the current `PptxSlide[]` and returns a brand-new array (untouched
- * slides are reused by reference so the render layer can cheaply detect
- * changes). All cloning defers to the core helpers (`cloneSlide`,
- * `cloneElement`, `duplicateElement`); nothing is mutated in place.
+ * PNG (single slide, fast) and print (opens its own surface) run without the
+ * modal; the menu trigger still disables via {@link exporting} while they run.
  */
-/** Geometry patch applied by drag / resize / rotate / nudge. */
-interface ElementBoxPatch {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    rotation: number;
+interface ExportUiDeps {
+    controller: ExportController;
+    getTranslator(): Translator;
+    /**
+     * Fired after an export completes successfully (Options > Accessibility
+     * "feedback with sound" hook); not called on abort or failure.
+     */
+    onComplete?(): void;
 }
-
-interface EditorMarqueeRect extends MarqueeRect {
-    additive: boolean;
+declare class ExportUiState {
+    #private;
+    /** Whether the progress modal is visible. */
+    open: boolean;
+    /** Modal heading (e.g. "Export as PDF"). */
+    title: string;
+    /** Current progress, 0-100. */
+    progress: number;
+    /** Status line under the bar (e.g. "Rendering slide 3 of 10..."). */
+    status: string;
+    constructor(deps: ExportUiDeps);
+    /** True while any export runs (disables the menu trigger). */
+    get exporting(): boolean;
+    /** Export the current slide as PNG (no modal; quick single capture). */
+    runPng(): void;
+    /** Copy the current slide to the system image clipboard. */
+    runCopyImage(): void;
+    /** Run the PDF export with the progress modal wired. */
+    runPdf(): Promise<void>;
+    /** Run the animated-GIF export with the progress modal wired. */
+    runGif(): Promise<void>;
+    /** Run the WebM video export with the progress modal wired. */
+    runVideo(): Promise<void>;
+    /** Run the print flow (no modal; the print surface takes over). */
+    runPrint(options?: PrintOptions): void;
+    /** Cancel the in-flight export (aborts the loop, closes the modal). */
+    cancel(): void;
 }
 
 /**
- * Element-animation actions for the ribbon's Animations tab, split out of
- * `EditorState` to keep it under the repo's 300-LOC budget.
+ * autosave.svelte.ts: debounced crash-recovery autosave for the Svelte viewer.
  *
- * 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` in
- * `presentation/animation-playback.svelte.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/vanilla ribbons use:
- * applying a preset sets one of entrance/emphasis/exit without touching the
- * others; remove drops the whole entry. Both mutations go through
- * `EditorState.commitSlides`, so they are history-integrated (undoable).
+ * A runes port that fuses the two shared semantics the other bindings use:
+ *  - React's persistence target: each successful save writes the serialized
+ *    `.pptx` bytes to the shared IndexedDB recovery store
+ *    (`saveAutosaveSnapshot`, keyed by `filePath`), so a host can offer
+ *    restore-on-load with `getAutosaveSnapshot` / `listAutosaveSnapshots`
+ *    (both re-exported from this package). This binding does NOT auto-restore;
+ *    matching React/Vue, recovery is a host concern.
+ *  - Vue's debounce-on-edit trigger: an edit marks the document dirty and
+ *    (re)arms a debounce timer instead of polling on a fixed interval.
+ *
+ * The controller registers its own edit-watching `$effect` in the constructor,
+ * so the SFC only has to construct it once during setup and read its reactive
+ * `status` / `isDirty` for the toolbar indicator.
  */
-declare class EditorAnimationController {
+/**
+ * Autosave status, surfaced for the toolbar status pill.
+ *
+ *  - `idle`     : nothing has been saved yet (or no edits since mount).
+ *  - `disabled` : autosave is inactive (off, not editable, or no file path).
+ *  - `saving`   : a save is currently in flight.
+ *  - `saved`    : the most recent save succeeded.
+ *  - `error`    : the most recent save threw.
+ */
+type AutosaveStatus = 'idle' | 'disabled' | 'saving' | 'saved' | 'error';
+interface AutosaveDeps {
+    /** Master on/off: host `autosave` prop AND editing allowed. */
+    getEnabled: () => boolean;
+    /** Debounce window in milliseconds. */
+    getIntervalMs: () => number;
+    /** IndexedDB record key (host `filePath`); autosave is disabled without one. */
+    getFilePath: () => string | undefined;
+    /** The current editable slides (watched for edits). */
+    getSlides: () => PptxSlide[];
+    getSlideMasters?: () => PptxSlideMaster[];
+    getNotesMaster?: () => PptxNotesMaster | undefined;
+    getHandoutMaster?: () => PptxHandoutMaster | undefined;
+    getSections?: () => PptxSection[];
+    /** The live core handler used to serialize slides to `.pptx` bytes. */
+    getHandler: () => PptxHandler | null;
+    /**
+     * Monotonic load counter: a change means a fresh presentation was seeded (not
+     * a user edit), so the watcher clears dirty instead of arming a save.
+     */
+    getLoadCount: () => number;
+    /** Host callback with the freshly-serialized bytes on each successful save. */
+    onSaved?: (bytes: Uint8Array) => void;
+}
+declare class AutosaveController {
     #private;
-    constructor(editor: EditorState);
-    addAnimation(group: AnimationGroup, preset: PptxAnimationPreset): void;
-    removeAnimation(): void;
+    /** Current autosave lifecycle status (reactive). */
+    status: AutosaveStatus;
+    /** Whether there are unsaved edits pending (reactive). */
+    isDirty: boolean;
+    /** Epoch ms of the last successful save, or null (reactive). */
+    lastSavedAt: number | null;
+    constructor(deps: AutosaveDeps);
+    /** Force an immediate save, bypassing the debounce window. */
+    save(): Promise<void>;
 }
 
 /**
- * The Home tab's multi-select-aware Arrange group (align / distribute /
- * flip / group / ungroup), split out of `EditorState` to keep it under the
- * repo's 300-LOC budget. Reads `editor.selection.ids` (the ordered
- * multi-selection) rather than just the primary id, matching React's
- * `selectedElementIds` semantics.
+ * Prop contracts for the viewer chrome around the canvas: the compact
+ * toolbar, the thumbnail rail, and the speaker-notes panel. Split out of
+ * `props.ts` for the repo's file-size budget; import them from `./props`,
+ * which re-exports this module.
  */
-declare class EditorArrangeController {
-    #private;
+interface ViewerToolbarProps {
+    /** Active slide (0-based). */
+    current: number;
+    total: number;
+    /** Currently-effective zoom percent (rounded). */
+    zoomPercent: number;
+    isFullscreen: boolean;
+    onprev: () => void;
+    onnext: () => void;
+    onzoomin: () => void;
+    onzoomout: () => void;
+    onzoomfit: () => void;
+    onfullscreen: () => void;
+    /** Whether the Notes toggle button is shown (host has a notes panel). */
+    showNotes?: boolean;
+    /** Whether the notes panel is currently expanded (drives the pressed state). */
+    notesExpanded?: boolean;
+    onnotestoggle?: () => void;
+    /** Show the editing action group (Undo / Redo / Save). Default false. */
+    editable?: boolean;
+    /** Whether an undo step is available (drives the Undo button's disabled state). */
+    canUndo?: boolean;
+    /** Whether a redo step is available (drives the Redo button's disabled state). */
+    canRedo?: boolean;
+    /** Whether there are unsaved edits (drives the Save button's emphasis). */
+    dirty?: boolean;
+    onundo?: () => void;
+    onredo?: () => void;
+    onsave?: () => void;
+    ondownload?: () => void;
+    /**
+     * Autosave lifecycle status; when set (host opted into `autosave`) a small
+     * status pill renders in the editing group. Omit to hide the pill entirely.
+     */
+    autosaveStatus?: AutosaveStatus;
+    /** Whether there are unsaved autosave edits (drives the pill's "dirty" tone). */
+    autosaveDirty?: boolean;
+    /**
+     * Export menu state (PNG / PDF / GIF / video / print). When set, the
+     * toolbar renders the `ExportMenu` dropdown in its right-hand group,
+     * matching the export affordance the React/Vue/Angular chrome exposes.
+     * Omit to hide the menu (e.g. while no presentation is loaded).
+     */
+    exportUi?: ExportUiState;
+    /** Opens the Share (collaboration) dialog. Omit to hide the button. */
+    onshare?: () => void;
+    /** Opens the Broadcast dialog. Omit to hide the button. */
+    onbroadcast?: () => void;
+    /** Whether a collaboration session is currently active (highlights the Share button). */
+    collabActive?: boolean;
+    /** Toolbar buttons to hide; see `PowerPointViewerProps.hiddenActions`. Default undefined: nothing hidden. */
+    hiddenActions?: ToolbarActionId[];
+}
+
+/**
+ * Element-animation actions for the ribbon's Animations tab, split out of
+ * `EditorState` to keep it under the repo's 300-LOC budget.
+ *
+ * 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` in
+ * `presentation/animation-playback.svelte.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/vanilla ribbons use:
+ * applying a preset sets one of entrance/emphasis/exit without touching the
+ * others; remove drops the whole entry. Both mutations go through
+ * `EditorState.commitSlides`, so they are history-integrated (undoable).
+ */
+declare class EditorAnimationController {
+    #private;
+    constructor(editor: EditorState);
+    addAnimation(group: AnimationGroup, preset: PptxAnimationPreset): void;
+    removeAnimation(): void;
+}
+
+/**
+ * The Home tab's multi-select-aware Arrange group (align / distribute /
+ * flip / group / ungroup), split out of `EditorState` to keep it under the
+ * repo's 300-LOC budget. Reads `editor.selection.ids` (the ordered
+ * multi-selection) rather than just the primary id, matching React's
+ * `selectedElementIds` semantics.
+ */
+declare class EditorArrangeController {
+    #private;
     constructor(editor: EditorState);
     /** Align every selected element to `edge` (needs >= 2 selected). */
     alignSelected(edge: AlignEdge): void;
@@ -9799,6 +10193,71 @@ declare class EditorClipboardController {
     pasteClipboard(): string | null;
 }
 
+interface EditorSnapshot {
+    slides: PptxSlide[];
+    templateElementsBySlideId: TemplateElementMap;
+    slideMasters: PptxSlideMaster[];
+    notesMaster: PptxNotesMaster | undefined;
+    handoutMaster: PptxHandoutMaster | undefined;
+    sections: PptxSection[];
+    headerFooter: PptxHeaderFooter;
+    presentationProperties: PptxPresentationProperties;
+    customShows: PptxCustomShow[];
+    coreProperties: PptxCoreProperties | undefined;
+    appProperties: PptxAppProperties | undefined;
+    customProperties: PptxCustomProperty[];
+    /** `ppt/tags/*.xml` name/value metadata, editable in the inspector. */
+    tagCollections: PptxTagCollection[];
+}
+
+/**
+ * Deck-level lifecycle for {@link EditorState}: adopting a freshly loaded
+ * document, resetting, taking a remote (collaboration) snapshot, restoring an
+ * undo snapshot, editing document metadata, and serialising back to bytes.
+ *
+ * These are free functions over the state rather than methods because
+ * `EditorState` is already a facade over thirteen focused controllers, and
+ * document lifecycle is simply the fourteenth concern; keeping it here is what
+ * holds that file within the repo's file-size budget.
+ */
+/**
+ * Everything a load hands the editor, in the order `PptxHandler` produces it.
+ * Declared once here as a labelled tuple so `EditorState.setSlides` can forward
+ * it verbatim without restating eleven parameters (and their defaults).
+ */
+type LoadDocumentArgs = [
+    slides: PptxSlide[],
+    slideMasters?: PptxSlideMaster[],
+    notesMaster?: PptxNotesMaster,
+    handoutMaster?: PptxHandoutMaster,
+    sections?: PptxSection[],
+    coreProperties?: PptxCoreProperties,
+    appProperties?: PptxAppProperties,
+    customProperties?: PptxCustomProperty[],
+    headerFooter?: PptxHeaderFooter,
+    presentationProperties?: PptxPresentationProperties,
+    customShows?: PptxCustomShow[]
+];
+
+/**
+ * Pure, immutable slide-array mutations for the Svelte editor.
+ *
+ * Mirrors the vanilla binding's `editor-mutations` (in turn the Vue binding's
+ * `useEditorOperations` commit helpers), minus the reactivity: every function
+ * takes the current `PptxSlide[]` and returns a brand-new array (untouched
+ * slides are reused by reference so the render layer can cheaply detect
+ * changes). All cloning defers to the core helpers (`cloneSlide`,
+ * `cloneElement`, `duplicateElement`); nothing is mutated in place.
+ */
+/** Geometry patch applied by drag / resize / rotate / nudge. */
+interface ElementBoxPatch {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+}
+
 /**
  * Z-order (paint-order) reordering for the Svelte editor.
  *
@@ -9852,13 +10311,44 @@ declare class EditorFormatPainterController {
     cancel(): void;
 }
 
+/**
+ * The editor's undo/redo stack, wrapped so `canUndo` / `canRedo` are runes the
+ * chrome can read directly.
+ *
+ * The shared {@link EditorHistory} is a plain (non-reactive) structure, so
+ * every mutation has to be followed by a flag re-read; doing that in one place
+ * here is what stops a missed `#syncHistoryFlags()` call leaving the ribbon's
+ * Undo button greyed out after a real edit. Extracted from `EditorState` to
+ * keep that file within the repo's file-size budget.
+ */
+declare class EditorHistoryState {
+    #private;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    /** Re-read the stack's availability flags onto the reactive mirrors. */
+    sync(): void;
+    /**
+     * Apply the File > Options "maximum number of undos" value. Recreates the
+     * stack when the depth changes (PowerPoint likewise applies the new maximum
+     * going forward; existing entries are dropped).
+     */
+    setDepth(depth: number): void;
+    record(snapshot: EditorSnapshot): void;
+    clear(): void;
+    undo(current: EditorSnapshot): EditorSnapshot | undefined;
+    redo(current: EditorSnapshot): EditorSnapshot | undefined;
+}
+
 /**
  * The ribbon Draw tab's active tool. `'select'` means "not drawing": the
  * stage's normal selection/drag/resize gestures own the pointer, matching
- * React's `DrawingTool` / Angular's `DrawTool` conventions (minus `freeform`,
- * out of scope for this wave; see the Draw tab's JSDoc).
+ * React's `DrawingTool` / Angular's `DrawTool`.
+ *
+ * `freeform` shares the pen's gesture but commits a closed custom-geometry
+ * SHAPE rather than an ink stroke, so the result is editable/fillable like any
+ * other shape; see `editor-freeform.ts`.
  */
-type InkDrawTool = 'select' | 'pen' | 'highlighter' | 'eraser';
+type InkDrawTool = 'select' | 'pen' | 'highlighter' | 'eraser' | 'freeform';
 /**
  * EditorInkController: the ribbon Draw tab's tool/colour/width state plus the
  * pure element-factory / erase mutations, split out of `EditorState` to keep
@@ -9897,9 +10387,10 @@ declare class EditorInkController {
     /** Update the live preview path while a pen/highlighter stroke is in progress. */
     previewStroke(points: readonly InkPoint[]): void;
     /**
-     * Finalise the in-progress stroke into a new `ink` element (undoable via
-     * `EditorState.insertElement`), or discard it silently when too short (a
-     * plain tap) or the tool changed mid-gesture.
+     * Finalise the in-progress stroke (undoable via `EditorState.insertElement`),
+     * or discard it silently when too short (a plain tap) or the tool changed
+     * mid-gesture. Pen/highlighter commit an `ink` element; freeform commits a
+     * closed custom-geometry `shape`.
      */
     commitStroke(points: readonly InkPoint[]): void;
     /**
@@ -9964,16 +10455,6 @@ declare class EditorSectionController {
     private commit;
 }
 
-/**
- * EditorSelection: the reactive multi-element selection for the Svelte editor.
- *
- * Holds an ordered list of selected element ids; the LAST id is the primary
- * selection (the one the overlay handles, gestures, and inline editing act
- * on), matching the React binding's `selectedElementIds` + primary convention.
- * Plain clicks call {@link set} (single selection), shift/ctrl clicks call
- * {@link toggle} (additive), and mutations that invalidate ids call
- * {@link prune}.
- */
 declare class EditorSelection {
     #private;
     /** All selected ids in selection order (primary last). */
@@ -10078,6 +10559,12 @@ declare class EditorState {
     coreProperties: PptxCoreProperties | undefined;
     appProperties: PptxAppProperties | undefined;
     customProperties: PptxCustomProperty[];
+    /**
+     * The deck's `ppt/tags/*.xml` name/value metadata. Seeded from the load via
+     * {@link adoptTagCollections} and edited by the inspector's Tags section;
+     * carried through the undo snapshot and re-emitted on save.
+     */
+    tagCollections: PptxTagCollection[];
     masterViewTarget: MasterViewTarget | null;
     readonly selection: EditorSelection;
     editable: boolean;
@@ -10085,6 +10572,8 @@ declare class EditorState {
     editTemplateMode: boolean;
     interactionActive: boolean;
     clipboard: ElementClipboardPayload | null;
+    /** Undo/redo stack; the `canUndo` / `canRedo` getters below mirror it. */
+    readonly history: EditorHistoryState;
     readonly clipboardOps: EditorClipboardController;
     readonly elementOps: EditorElementController;
     readonly templateOps: EditorTemplateController;
@@ -10114,29 +10603,15 @@ declare class EditorState {
     /** The loaded core handler, or null before a deck is open. Used by the
      *  Slides group for layout switching (`applyLayoutToSlide`). */
     getHandler(): PptxHandler | null;
-    setSlides(slides: PptxSlide[], slideMasters?: PptxSlideMaster[], notesMaster?: PptxNotesMaster, handoutMaster?: PptxHandoutMaster, sections?: PptxSection[], coreProperties?: PptxCoreProperties, appProperties?: PptxAppProperties, customProperties?: PptxCustomProperty[], headerFooter?: PptxHeaderFooter, presentationProperties?: PptxPresentationProperties, customShows?: PptxCustomShow[]): void;
-    /**
-     * Replace the working slides with a remote (collaboration) snapshot without
-     * recording an undo step or touching the dirty flag: the granular reconcile
-     * already merged the peer's change, and treating an incoming remote edit as
-     * a local mutation would both pollute the undo stack and re-broadcast it.
-     *
-     * Selection is preserved when the selected element still exists so a remote
-     * edit does not yank the local user's selection out from under them. Local
-     * undo history is intentionally kept (see the collaboration module JSDoc):
-     * shared defines no collaborative-undo semantics, so, matching React/Vue,
-     * local undo may fight a concurrent remote edit.
-     */
+    /** Adopt a freshly loaded deck as the working document (see `loadEditorDocument`). */
+    setSlides(...args: LoadDocumentArgs): void;
+    /** Adopt a remote (collaboration) snapshot; see `applyRemoteEditorSlides`. */
     applyRemoteSlides(slides: PptxSlide[]): void;
     reset(): void;
     select(id: string | null): void;
     isElementInteractive(id: string): boolean;
     setTemplateEditing(enabled: boolean): void;
-    /**
-     * Apply the File > Options "maximum number of undos" value. Recreates the
-     * history stack when the depth changes (PowerPoint likewise applies the new
-     * maximum going forward; existing entries are dropped).
-     */
+    /** Apply the File > Options "maximum number of undos" value. */
     setHistoryDepth(depth: number): void;
     pushHistory(): void;
     commitChange(): void;
@@ -10152,6 +10627,8 @@ declare class EditorState {
      * undoable step). No-op when not editable.
      */
     commitSlides(next: PptxSlide[]): void;
+    /** A deep clone of the whole editable document (one undo entry, or save input). */
+    snapshot(): EditorSnapshot;
     deleteSelected: () => void;
     duplicateSelected: () => string | null;
     applyElementPatch: (id: string, patch: Partial<PptxElement>) => void;
@@ -10162,11 +10639,107 @@ declare class EditorState {
     commitInlineText: (id: string, text: string) => void;
     commitNotes: (notes: string, notesSegments?: TextSegment[]) => void;
     updateDocumentProperties(core: PptxCoreProperties, app: PptxAppProperties, custom: PptxCustomProperty[]): void;
+    /**
+     * Seed the deck's tag parts straight after a load. Deliberately NOT an undo
+     * step: the load already cleared history, and treating the parsed value as
+     * a user edit would mark a pristine deck dirty.
+     */
+    adoptTagCollections(tags: readonly PptxTagCollection[]): void;
+    /** Replace the tag collections as one undoable edit (inspector Tags section). */
+    updateTagCollections(next: readonly PptxTagCollection[]): void;
     undo(): void;
     redo(): void;
     save(format?: PptxSaveFormat): Promise<Uint8Array>;
 }
 
+/**
+ * What the canvas context menu offers, and what each command does.
+ *
+ * The item list is deliberately NOT decided here: `buildContextMenuEntries` in
+ * `pptx-viewer-shared` owns the command ids, labels, order and separators for
+ * all five bindings, so a command added there appears in all five at once. This
+ * module only supplies the context (what is selected, which table cell was
+ * right-clicked) and routes the chosen id at the editor's existing operations.
+ * Svelte's menu used to hand-write its own items, which is exactly how it ended
+ * up shipping without Group, Ungroup, Add Comment, Edit Hyperlink, or a single
+ * table command.
+ *
+ * It lives in a plain `.ts` module rather than inside `ElementContextMenu.svelte`
+ * so the SFC stays thin presentation (repo convention) and so the dispatch is
+ * unit-testable without mounting a component.
+ *
+ * @module editor/context-menu-dispatch
+ */
+/** The table cell a right-click landed on, in model (unmerged) coordinates. */
+interface ContextMenuCellTarget {
+    rowIndex: number;
+    columnIndex: number;
+}
+
+/**
+ * Shared value types for the Svelte editing layer.
+ */
+/** Box geometry in element (unscaled slide) px. */
+interface OverlayBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+}
+
+interface EditorControllerDeps {
+    getScale(): number;
+    getCurrent(): number;
+    getPresenting(): boolean;
+    getStageRoot(): Element | null;
+    getHolderEl(): HTMLElement | null;
+    /**
+     * The focusable viewer root. The stage gesture preventDefault()s the click, so
+     * focus has to be put back here or the root's keydown listener stops seeing
+     * anything (see `armEditorKeyboard`).
+     */
+    getRootEl?(): HTMLElement | null;
+    onCursorMove?(x: number, y: number): void;
+    /**
+     * Open the canvas context menu at viewport `x`/`y`. `cell` is the table cell
+     * the right-click landed on (null elsewhere): the menu's row / column /
+     * merge commands need a target, and this binding has no cell-selection
+     * model, so the cell under the pointer is the target.
+     */
+    onContextMenu?(x: number, y: number, cell: ContextMenuCellTarget | null): void;
+    getSnapToGrid?(): boolean;
+    getSnapToShape?(): boolean;
+    getGuides?(): readonly {
+        axis: 'h' | 'v';
+        position: number;
+    }[];
+    /**
+     * Transform inline-editor text at commit time (File > Options > Proofing
+     * AutoCorrect); identity when unset.
+     */
+    transformCommittedText?(text: string): string;
+    /**
+     * Collaboration live-preview channel. Inline text only reaches the slides
+     * state on commit, so peers saw nothing while a peer typed; each keystroke is
+     * published through this instead. Omit outside a collaborative viewer.
+     */
+    getLivePatcher?(): CollaborationLivePatcher | undefined;
+    /** The slide the inline-edited element belongs to (live-preview lookup). */
+    getActiveSlide?(): PptxSlide | undefined;
+    /**
+     * Show or hide the keyboard-shortcut cheat sheet ("?"). The panel is parity
+     * UI state owned by the shell, so the controller only signals the intent.
+     */
+    toggleShortcuts?(): void;
+    /** Close the cheat sheet on Escape; true when it was open (Escape consumed). */
+    closeShortcuts?(): boolean;
+}
+
+interface EditorMarqueeRect extends MarqueeRect {
+    additive: boolean;
+}
+
 declare class EditorController {
     #private;
     snapLines: readonly SnapLine[];
@@ -10203,215 +10776,15 @@ declare class EditorController {
 }
 
 /**
- * ExportUiState: reactive state behind the toolbar `ExportMenu` and the
- * `ExportProgressModal`. Svelte port of Vue's `useExportProgress` composable:
- * it owns the modal state (open / title / progress / status), the
- * `AbortController` the export loops check between slides, and wraps each
- * multi-slide export (PDF / GIF / WebM) in a `begin -> run -> end` envelope.
- * All percentage maths + status labels come from `pptx-viewer-shared`
- * (`export-progress.ts`) so every binding shows identical progress.
- *
- * PNG (single slide, fast) and print (opens its own surface) run without the
- * modal; the menu trigger still disables via {@link exporting} while they run.
- */
-interface ExportUiDeps {
-    controller: ExportController;
-    getTranslator(): Translator;
-    /**
-     * Fired after an export completes successfully (Options > Accessibility
-     * "feedback with sound" hook); not called on abort or failure.
-     */
-    onComplete?(): void;
-}
-declare class ExportUiState {
-    #private;
-    /** Whether the progress modal is visible. */
-    open: boolean;
-    /** Modal heading (e.g. "Export as PDF"). */
-    title: string;
-    /** Current progress, 0-100. */
-    progress: number;
-    /** Status line under the bar (e.g. "Rendering slide 3 of 10..."). */
-    status: string;
-    constructor(deps: ExportUiDeps);
-    /** True while any export runs (disables the menu trigger). */
-    get exporting(): boolean;
-    /** Export the current slide as PNG (no modal; quick single capture). */
-    runPng(): void;
-    /** Copy the current slide to the system image clipboard. */
-    runCopyImage(): void;
-    /** Run the PDF export with the progress modal wired. */
-    runPdf(): Promise<void>;
-    /** Run the animated-GIF export with the progress modal wired. */
-    runGif(): Promise<void>;
-    /** Run the WebM video export with the progress modal wired. */
-    runVideo(): Promise<void>;
-    /** Run the print flow (no modal; the print surface takes over). */
-    runPrint(options?: PrintOptions): void;
-    /** Cancel the in-flight export (aborts the loop, closes the modal). */
-    cancel(): void;
-}
-
-/**
- * autosave.svelte.ts: debounced crash-recovery autosave for the Svelte viewer.
+ * Where the canvas context menu opened, and on which table cell.
  *
- * A runes port that fuses the two shared semantics the other bindings use:
- *  - React's persistence target: each successful save writes the serialized
- *    `.pptx` bytes to the shared IndexedDB recovery store
- *    (`saveAutosaveSnapshot`, keyed by `filePath`), so a host can offer
- *    restore-on-load with `getAutosaveSnapshot` / `listAutosaveSnapshots`
- *    (both re-exported from this package). This binding does NOT auto-restore;
- *    matching React/Vue, recovery is a host concern.
- *  - Vue's debounce-on-edit trigger: an edit marks the document dirty and
- *    (re)arms a debounce timer instead of polling on a fixed interval.
- *
- * The controller registers its own edit-watching `$effect` in the constructor,
- * so the SFC only has to construct it once during setup and read its reactive
- * `status` / `isDirty` for the toolbar indicator.
- */
-/**
- * Autosave status, surfaced for the toolbar status pill.
- *
- *  - `idle`     : nothing has been saved yet (or no edits since mount).
- *  - `disabled` : autosave is inactive (off, not editable, or no file path).
- *  - `saving`   : a save is currently in flight.
- *  - `saved`    : the most recent save succeeded.
- *  - `error`    : the most recent save threw.
+ * Owned by the viewer shell and handed straight to `ElementContextMenu`; the
+ * cell is what turns the shared menu's table block on and gives it a target.
  */
-type AutosaveStatus = 'idle' | 'disabled' | 'saving' | 'saved' | 'error';
-interface AutosaveDeps {
-    /** Master on/off: host `autosave` prop AND editing allowed. */
-    getEnabled: () => boolean;
-    /** Debounce window in milliseconds. */
-    getIntervalMs: () => number;
-    /** IndexedDB record key (host `filePath`); autosave is disabled without one. */
-    getFilePath: () => string | undefined;
-    /** The current editable slides (watched for edits). */
-    getSlides: () => PptxSlide[];
-    getSlideMasters?: () => PptxSlideMaster[];
-    getNotesMaster?: () => PptxNotesMaster | undefined;
-    getHandoutMaster?: () => PptxHandoutMaster | undefined;
-    getSections?: () => PptxSection[];
-    /** The live core handler used to serialize slides to `.pptx` bytes. */
-    getHandler: () => PptxHandler | null;
-    /**
-     * Monotonic load counter: a change means a fresh presentation was seeded (not
-     * a user edit), so the watcher clears dirty instead of arming a save.
-     */
-    getLoadCount: () => number;
-    /** Host callback with the freshly-serialized bytes on each successful save. */
-    onSaved?: (bytes: Uint8Array) => void;
-}
-declare class AutosaveController {
-    #private;
-    /** Current autosave lifecycle status (reactive). */
-    status: AutosaveStatus;
-    /** Whether there are unsaved edits pending (reactive). */
-    isDirty: boolean;
-    /** Epoch ms of the last successful save, or null (reactive). */
-    lastSavedAt: number | null;
-    constructor(deps: AutosaveDeps);
-    /** Force an immediate save, bypassing the debounce window. */
-    save(): Promise<void>;
-}
-
-interface SlideCanvasProps {
-    slide: PptxSlide | undefined;
-    canvasSize: CanvasSize;
-    mediaDataUrls: Map<string, string>;
-    /** Effective scale (fit-to-viewport x user zoom), pre-computed by the host. */
-    scale: number;
-    /** True only on the live presentation stage; see `SlideStageProps.presenting`. */
-    presenting?: boolean;
-    /** True while in-place editing is available; gates the pointer handlers and the editing cursor/class. */
-    editingActive?: boolean;
-    editTemplateMode?: boolean;
-    ontablecellcommit?: (elementId: string, rowIndex: number, cellIndex: number, text: string) => void;
-    onsmartartnodecommit?: (elementId: string, nodeId: string, text: string) => void;
-    onsmartartnodefill?: (elementId: string, nodeId: string, fill: string) => void;
-    /** Reports the stage-holder node to the host on mount/teardown (editing hit-surface, export capture anchor). */
-    onstageholder?: (el: HTMLDivElement | null) => void;
-    onstagepointerdown?: (event: PointerEvent) => void;
-    onstagepointermove?: (event: PointerEvent) => void;
-    onstagedblclick?: (event: MouseEvent) => void;
-    onstagecontextmenu?: (event: MouseEvent) => void;
-    /** Fired on any stage click; the host wires this to advance presentation playback. */
-    onstageclick?: (event: MouseEvent) => void;
-    /**
-     * True while the AI panel is picking an element: the next element click(s)
-     * become the assistant's focus (highlighted) instead of selecting / editing.
-     */
-    aiPickMode?: boolean;
-    /**
-     * True while a running AI tool is active: the stage marks itself
-     * `data-pptx-ai-active` so element colour changes tween while the assistant
-     * works (see AiFocusHighlightOverlay's tween rule).
-     */
-    aiActive?: boolean;
-    /** Route a picked canvas element to the AI focus (pick mode only). */
-    onaipickelement?: (elementId: string) => void;
-    /**
-     * Overlay content layered above the slide (selection/editor layer, ink
-     * drawing, alignment guides, presentation annotations, collaboration
-     * cursors, transition overlay, ...). Rendered inside the same
-     * fixed-size, scaled stage-holder as the slide itself. Kept out of this
-     * component's own props (rather than a fixed list of overlay slots) so it
-     * stays free of the live editor/controller instances those overlays need.
-     */
-    children?: svelte.Snippet;
-}
-interface ViewerToolbarProps {
-    /** Active slide (0-based). */
-    current: number;
-    total: number;
-    /** Currently-effective zoom percent (rounded). */
-    zoomPercent: number;
-    isFullscreen: boolean;
-    onprev: () => void;
-    onnext: () => void;
-    onzoomin: () => void;
-    onzoomout: () => void;
-    onzoomfit: () => void;
-    onfullscreen: () => void;
-    /** Whether the Notes toggle button is shown (host has a notes panel). */
-    showNotes?: boolean;
-    /** Whether the notes panel is currently expanded (drives the pressed state). */
-    notesExpanded?: boolean;
-    onnotestoggle?: () => void;
-    /** Show the editing action group (Undo / Redo / Save). Default false. */
-    editable?: boolean;
-    /** Whether an undo step is available (drives the Undo button's disabled state). */
-    canUndo?: boolean;
-    /** Whether a redo step is available (drives the Redo button's disabled state). */
-    canRedo?: boolean;
-    /** Whether there are unsaved edits (drives the Save button's emphasis). */
-    dirty?: boolean;
-    onundo?: () => void;
-    onredo?: () => void;
-    onsave?: () => void;
-    ondownload?: () => void;
-    /**
-     * Autosave lifecycle status; when set (host opted into `autosave`) a small
-     * status pill renders in the editing group. Omit to hide the pill entirely.
-     */
-    autosaveStatus?: AutosaveStatus;
-    /** Whether there are unsaved autosave edits (drives the pill's "dirty" tone). */
-    autosaveDirty?: boolean;
-    /**
-     * Export menu state (PNG / PDF / GIF / video / print). When set, the
-     * toolbar renders the `ExportMenu` dropdown in its right-hand group,
-     * matching the export affordance the React/Vue/Angular chrome exposes.
-     * Omit to hide the menu (e.g. while no presentation is loaded).
-     */
-    exportUi?: ExportUiState;
-    /** Opens the Share (collaboration) dialog. Omit to hide the button. */
-    onshare?: () => void;
-    /** Opens the Broadcast dialog. Omit to hide the button. */
-    onbroadcast?: () => void;
-    /** Whether a collaboration session is currently active (highlights the Share button). */
-    collabActive?: boolean;
-    /** Toolbar buttons to hide; see `PowerPointViewerProps.hiddenActions`. Default undefined: nothing hidden. */
-    hiddenActions?: ToolbarActionId[];
+interface StageContextMenu {
+    x: number;
+    y: number;
+    cell: ContextMenuCellTarget | null;
 }
 
 /**
@@ -10549,6 +10922,8 @@ interface RibbonProps {
     oncustomshows: () => void;
     onselectionpane: () => void;
     onslidesorter: () => void;
+    /** View tab > Normal: leave slide sorter / slide show for the editing view. */
+    onnormal?: () => void;
     preferences: ViewerPreferences;
     onpreferenceschange: (preferences: ViewerPreferences) => void;
     showGuides: boolean;
@@ -10673,10 +11048,7 @@ type NavigationAction = 'next' | 'prev' | 'first' | 'last';
  * conventions used by the other bindings (arrows, paging keys, space, Home/End).
  */
 declare function resolveNavigationKey(key: string): NavigationAction | undefined;
-/** Next zoom level up from `current` percent, clamped. */
-declare function zoomInPercent(current: number): number;
-/** Next zoom level down from `current` percent, clamped. */
-declare function zoomOutPercent(current: number): number;
+
 /**
  * Fit-to-viewport scale for a canvas inside a viewport, with breathing room.
  * Returns a strictly positive scale (falls back to 1 while unmeasured).
@@ -10707,6 +11079,8 @@ declare class PresentationLoader {
     coreProperties: PptxCoreProperties | undefined;
     appProperties: PptxAppProperties | undefined;
     customProperties: PptxCustomProperty[];
+    /** Parsed `ppt/tags/*.xml` collections, editable in the inspector's Tags section. */
+    tagCollections: PptxTagCollection[];
     embeddedFonts: PptxEmbeddedFont[];
     hasDigitalSignatures: boolean;
     digitalSignatureCount: number;
@@ -10911,6 +11285,13 @@ declare class CollaborationDialogsState {
     retry(propConfig: CollaborationConfig | undefined): void;
 }
 
+/**
+ * The navigation / zoom / mode / slide / element half of the imperative
+ * `PowerPointViewer` instance API. The undo/redo/save half lives in
+ * `editing-api.ts` and the export half in `export/exporting-api.ts`.
+ */
+type DeckApi = Omit<PowerPointViewerAPI, 'getContent' | 'undo' | 'redo' | 'canUndo' | 'canRedo'>;
+
 /** The imperative editing API exposed on the `PowerPointViewer` instance. */
 interface EditingApi {
     undo(): void;
@@ -11133,6 +11514,146 @@ declare class PresenterSession {
     private getChannel;
 }
 
+/** One element ring to draw on the canvas: an explicit pick or a live-tool focus. */
+interface AiCanvasHighlight {
+    slideIndex: number;
+    elementId: string;
+    /** `pick` = persistent user pick; `active` = transient AI-is-working ring. */
+    variant: 'pick' | 'active';
+}
+/** Live viewer accessors + the panel-open hook the controller closes over. */
+interface AiPanelControllerDeps {
+    getActiveSlideIndex(): number;
+    getSelectedElementId(): string | null;
+    getSelectedElementIds(): readonly string[];
+    /** The primary selected element, for building the "Fix with AI" directive. */
+    getSelectedElement(): PptxElement | undefined;
+    /** Open the panel (askAboutSelection / fixSelection / startPicking need it). */
+    openPanel(): void;
+}
+declare class AiPanelController {
+    #private;
+    /** Pinned focus override (null follows the live selection). */
+    pinnedFocus: PptxAiFocusedTarget[] | null;
+    /** One-shot composer prefill. `nonce` bumps on every ask/fix. */
+    prefill: {
+        text: string;
+        nonce: number;
+    };
+    /** True while the user is picking element(s) on the canvas for the assistant. */
+    pickMode: boolean;
+    /** The elements the user has explicitly handed to the assistant. */
+    pickTargets: PptxAiFocusedTarget[];
+    /** The batch of just-applied element changes the canvas should animate. */
+    changeBatch: AiChangeBatch | null;
+    constructor(deps: AiPanelControllerDeps);
+    /** Focused targets derived live from the current canvas selection. */
+    get liveFocusTargets(): PptxAiFocusedTarget[];
+    /** True when there are explicit picks (they win over a pin / live selection). */
+    get hasPicks(): boolean;
+    /** The targets the assistant should scope to: picks > pin > live selection. */
+    get effectiveTargets(): PptxAiFocusedTarget[];
+    /** Whether a pin is currently the active focus (no picks override it). */
+    get isPinned(): boolean;
+    /** Element rings the canvas should draw (picks + the live tool focus). */
+    get canvasHighlights(): AiCanvasHighlight[];
+    /** True while the canvas should tween colour changes (AI is active). */
+    get canvasAnimating(): boolean;
+    pinFocus(): void;
+    clearPinnedFocus(): void;
+    /** Open the panel scoped to the current selection, empty composer (focused). */
+    askAboutSelection(): void;
+    /** Open the panel scoped to the current selection, prefilled fix directive. */
+    fixSelection(): void;
+    /** Enter pick mode (the next canvas element clicks become picks). */
+    startPicking(): void;
+    /** Leave pick mode without clearing the accumulated picks. */
+    stopPicking(): void;
+    /** Add one clicked canvas element to the pick set (and highlight it). */
+    addPick(slideIndex: number, elementId: string): void;
+    /** Empty the pick set and leave pick mode. */
+    clearPicks(): void;
+    /**
+     * Flash a transient "the AI is working on this" highlight for a running tool,
+     * and enable colour tweening for a short settle window. Pass `null` to just
+     * enable tweening (e.g. a theme-colour edit with no single element target).
+     */
+    flashToolTarget(target: ToolCanvasTarget | null): void;
+    /**
+     * Push (or clear) the change batch the AI apply path published, so the canvas
+     * overlay animates the just-applied edit (glide old->new, fade/scale in-out,
+     * glow). Pass `null` to clear once the animation has settled.
+     */
+    showChangeBatch(batch: AiChangeBatch | null): void;
+    /** Cancel the pending flash timer (call on teardown). */
+    dispose(): void;
+}
+
+interface AiCluster {
+    /** The SDK-free bridge handed to the (lazily imported) chat panel. */
+    readonly bridge: PptxAiBridge;
+    /** On-canvas scope: focus targets, pick mode, live tool-focus highlights. */
+    readonly panel: AiPanelController;
+    /** Whether the right-side chat panel is open (ribbon Sparkles toggle). */
+    panelOpen: boolean;
+    /** Element rings to draw on the active slide; empty when AI is disabled. */
+    readonly canvasHighlights: readonly AiCanvasHighlight[];
+}
+
+/**
+ * ViewerOptionsState: the runes wrapper around the shared File > Options
+ * store. Owns the reactive `options` snapshot (updated via the store's
+ * subscribe callback, persisted by the store to the shared
+ * `pptx-viewer-prefs` localStorage entry) plus the derived behavior values
+ * the viewer wires: history depth, ribbon visibility, print defaults,
+ * screen tips, root classes, trust gates, and feedback sounds.
+ */
+declare class ViewerOptionsState {
+    #private;
+    /** Reactive File > Options snapshot; a new object per change. */
+    options: ViewerOptions;
+    constructor(init?: ViewerOptionsStoreInit);
+    /** The legacy six-toggle projection of the current options. */
+    get preferences(): ViewerPreferences;
+    /** Undo depth for the editor history (Advanced > maximum undos). */
+    get historyDepth(): number;
+    /** Ribbon tabs unticked in Customize Ribbon (File never hides). */
+    get hiddenRibbonTabIds(): readonly ToolbarTabId[];
+    /** Print dialog seed, or undefined for "use most recent settings". */
+    get printDefaults(): Partial<PrintSettings> | undefined;
+    /** Viewer-root CSS classes reflecting display-affecting options. */
+    get rootClasses(): string[];
+    setValue(group: ViewerOptionsGroupId, key: string, value: ViewerOptionPrimitive): void;
+    /** Restore a snapshot wholesale (the dialog's Cancel semantics). */
+    restore(snapshot: ViewerOptions): void;
+    setRibbonTabHidden(tabId: ToolbarTabId, hidden: boolean): void;
+    setQuickAccessCommands(commandIds: readonly string[]): void;
+    reset(group?: ViewerOptionsGroupId): void;
+    /**
+     * Push the legacy preference toggles (ribbon View tab, title-bar autosave)
+     * back into the options model. Only writes when a value actually differs,
+     * so the bidirectional sync with `preferences` cannot loop.
+     */
+    applyPreferences(prefs: ViewerPreferences): void;
+    /** Tooltip text under the current ScreenTip style, or undefined for none. */
+    screenTip(label: string, description?: string, shortcut?: string): string | undefined;
+    /**
+     * Trust Center gate for following an external hyperlink. Returns true when
+     * navigation may proceed (gate off, non-http(s) target, or confirmed).
+     */
+    confirmHyperlink(href: string, message: string): boolean;
+    /** Accessibility > "feedback with sound" cue for a completed action. */
+    playFeedback(): void;
+    /**
+     * Autosave debounce in ms: the host prop until the user picks a custom
+     * AutoRecover cadence in Options > Save, which then takes over.
+     */
+    autosaveDebounceMs(hostIntervalMs: number, defaultMinutes: number): number;
+    /** Options > Save > "Delete cached files": drop all recovery snapshots. */
+    clearCache(): Promise<void>;
+    dispose(): void;
+}
+
 declare class CompareController {
     #private;
     result: CompareResult | null;
@@ -11238,8 +11759,16 @@ interface CreateViewerStateOptions {
     /** Already locale-bound translator; propagated to descendants via context. */
     t: Translator;
     getSmartArt3D: () => boolean;
-    /** Whether in-place editing is enabled (host `editable` prop, post-effect value). */
+    /**
+     * The host `editable` prop. The factory mirrors it into its own
+     * {@link ViewerStateBag.editable} flag, which the AI seam, `setMode()` and
+     * Trust Center's Protected View can then flip without the host round-trip.
+     */
     getEditable: () => boolean;
+    /** Display file name, used by the AI seam as a friendly deck title. */
+    getFileName?: () => string | undefined;
+    /** Whether the host enabled the AI assistant (the `ai` prop). */
+    getAiEnabled?: () => boolean;
     onload?: (detail: ViewerLoadDetail) => void;
     onerror?: (message: string) => void;
     onslidechange?: (index: number) => void;
@@ -11256,6 +11785,12 @@ interface CreateViewerStateOptions {
     onautosavetoggle?: (enabled: boolean) => void;
     onstartcollaboration?: (config: CollaborationConfig) => void;
     onstopcollaboration?: () => void;
+    /**
+     * Host override for File > Open > "Browse this device". Without it
+     * {@link ViewerStateBag.openFile} falls back to the built-in native picker
+     * and loads the chosen deck in place, so the control is never inert.
+     */
+    onopenfile?: () => void;
     /** DOM-bound getters, supplied by the component that owns the markup. */
     getStageHolderEl: () => HTMLDivElement | undefined;
     getRootEl: () => HTMLDivElement | undefined;
@@ -11285,11 +11820,17 @@ interface ViewerStateBag {
     readonly presenterSession: PresenterSession;
     readonly exportWiring: ExportWiring;
     readonly exportUi: ExportUiState;
+    /** The full PowerPoint File > Options model (persisted), provided via context. */
+    readonly optionsState: ViewerOptionsState;
+    /** AI assistant bridge + on-canvas focus controller + panel open flag. */
+    readonly ai: AiCluster;
     readonly t: Translator;
     /** Imperative undo/redo/save/download API, matching `PowerPointViewerApi`'s editing subset. */
     readonly editingApi: EditingApi;
     /** Imperative PNG/PDF/GIF/video/print API, matching `PowerPointViewerApi`'s export subset. */
     readonly exportingApi: ExportingApi;
+    /** Imperative navigation/zoom/mode/slide/element API (the rest of `PowerPointViewerApi`). */
+    readonly deck: DeckApi;
     /** Effective scale (fit-to-viewport x user zoom), matching the main canvas. */
     readonly scale: number;
     /** User-facing zoom percent (rounded, never below 1). */
@@ -11304,16 +11845,19 @@ interface ViewerStateBag {
     readonly viewerMode: ViewerMode;
     /** True while the autosave debounce/write cycle is armed. */
     readonly autosaveActive: boolean;
+    /**
+     * The live editable flag: seeded from the host `editable` prop, then
+     * writable so an AI edit, `deck.setMode()` or Trust Center's Protected View
+     * can flip it without waiting on the host.
+     */
+    editable: boolean;
     /** Read-only: mutate via {@link setAutosaveEnabled}, which also fires `onautosavetoggle`. */
     readonly autosaveEnabled: boolean;
     setAutosaveEnabled(enabled: boolean): void;
     presenterMode: boolean;
     /** `Date.now()` timestamp of the last `enterPresenterView()` call; the presenter view's elapsed-time display. */
     readonly presenterStartedAt: number;
-    stageContextMenu: {
-        x: number;
-        y: number;
-    } | null;
+    stageContextMenu: StageContextMenu | null;
     readonly activeMobileSheet: MobileSheetKey;
     setActiveMobileSheet(next: MobileSheetKey): void;
     readonly notesExpanded: boolean;
@@ -11321,6 +11865,16 @@ interface ViewerStateBag {
     readonly signatureWarningOpen: boolean;
     enterPresenterView(): void;
     closeSignatureWarning(): void;
+    /** File > Open > "Browse this device" (host override, else the native picker). */
+    openFile(): void;
+    /** Run a Quick Access Toolbar command by catalog id (unknown ids no-op). */
+    runQuickAccessCommand(id: string): void;
+    /**
+     * Deck-level OOXML field-substitution context (date/time, header/footer,
+     * document properties, plus the active slide's number and title), also
+     * published to descendants via `provideFieldContext`.
+     */
+    fieldContext(): FieldSubstitutionContext;
     onNotesToggle(): void;
     onNotesCommit(notes: string, segments?: TextSegment[]): void;
     onFullscreenToggle(): void;
@@ -11334,28 +11888,29 @@ interface ViewerStateBag {
 
 /**
  * Builds every reactive controller the ribbon, toolbar, and slide canvas
- * need: the runes port of `PowerPointViewer.svelte`'s own construction block
- * (originally inlined at the top of its `<script>`), extracted so a host can
- * compose its own viewer shell out of `Ribbon` / `ViewerToolbar` / the state
- * classes without pulling in the whole `PowerPointViewer` component.
+ * need. This is `PowerPointViewer.svelte`'s entire construction block,
+ * extracted so that SFC stays thin composition and so a host can build its
+ * own viewer shell out of `Ribbon` / `ViewerToolbar` / the state classes
+ * without pulling in the whole `PowerPointViewer` component.
  *
  * MUST be called synchronously from a `.svelte` component's own script body
  * (top level, not inside a callback or after an `await`): it registers
  * `onMount` / `onDestroy` hooks and Svelte context (`setContext`) via
  * `provideTranslator` / `provideSmartArt3D` / `provideRenderContext` /
- * `provideZoomNavigation` (inside the editor-ui cluster) / `provideInspectorDeck`,
- * all of which require an active component-initialisation context. Svelte's
- * lifecycle context stays active for the whole synchronous execution of a
- * component's script, not just its top-level statements, so calling this
- * from a component's script works exactly like inlining the same code would.
- *
- * Construction is split across a few `create-viewer-state-*.svelte.ts`
- * helpers purely to stay under the repo's file-size budget; the ORDER those
- * helpers are invoked in below mirrors the original inline code (later
- * clusters close over earlier ones), with one deliberate reordering: the
- * collaboration cluster is now built right after `editor` (it doesn't need
- * the editing-chrome cluster), which lets `controller` close over the real
- * `collab.setCursor` instead of a forward reference.
+ * `provideInspectorDeck` / `provideFieldContext` (plus more inside the
+ * clusters), all of which require an active component-initialisation
+ * context. Svelte's lifecycle context stays active for the whole synchronous
+ * execution of a component's script, not just its top-level statements, so
+ * calling this from a component's script works exactly like inlining the
+ * same code would.
+ *
+ * Construction is split across the `create-viewer-state-*.svelte.ts` helpers
+ * purely to stay under the repo's file-size budget; the ORDER they are
+ * invoked in below mirrors the original inline code (later clusters close
+ * over earlier ones), with one deliberate reordering: the collaboration
+ * cluster is built right after `editor` (it doesn't need the editing-chrome
+ * cluster), which lets `controller` close over the real `collab.setCursor`
+ * instead of a forward reference.
  *
  * Call the returned `destroy()` from the host component's own `onDestroy`.
  */