pptx-react-viewer 1.25.5 → 2.0.0

package/dist/{hooks-unstable.d.ts → internals.d.ts}

@@ -1023,6 +1023,14 @@ interface ShapeStyle {
   };
   /** Fill overlay blend mode from effectDag `a:fillOverlay/@blend`. */
   dagFillOverlayBlend?: 'over' | 'mult' | 'screen' | 'darken' | 'lighten';
+  /**
+   * Fill overlay tint colour (hex `#RRGGBB`) from effectDag `a:fillOverlay`'s
+   * `a:solidFill`/`a:gradFill`. Painted as a blended overlay layer over the
+   * element; the blend mode comes from {@link dagFillOverlayBlend}.
+   */
+  dagFillOverlayColor?: string;
+  /** Fill overlay tint opacity (0-1), from the overlay fill colour's alpha. */
+  dagFillOverlayOpacity?: number;
   /** `<a:lnRef @idx>` — 1-based index into the theme's lnStyleLst. */
   lnRefIdx?: number;
   /** Raw XML colour child of `<a:lnRef>` (e.g. `<a:schemeClr>` with transforms). */
@@ -1955,6 +1963,75 @@ interface PptxChartProtection {
   rawXml?: XmlObject;
 }
 //#endregion
+//#region src/core/types/chart-user-shapes.d.ts
+/**
+ * Types for chart drawing-overlay shapes (`c:userShapes`).
+ *
+ * A chart's `c:userShapes` element carries an `r:id` that references a
+ * separate drawing part (`ppt/drawings/drawingN.xml`) whose root is a
+ * `c:userShapes` element populated with `cdr:relSizeAnchor` /
+ * `cdr:absSizeAnchor` wrappers around `sp` / `pic` / `cxnSp` shapes drawn on
+ * top of the chart plot. These interfaces describe the parsed, renderable
+ * overlay model. The raw reference is preserved separately on
+ * {@link PptxChartData.userShapesXml} for verbatim round-trip save; this model
+ * is render-only.
+ *
+ * @module pptx-types/chart-user-shapes
+ */
+/** A single paragraph of overlay-shape text with light formatting. */
+interface PptxChartUserShapeParagraph {
+  /** Joined run text of the paragraph. */
+  text: string;
+  /** Font size in points (`a:rPr/@sz` divided by 100), when present. */
+  fontSize?: number;
+  /** Whether the first run is bold (`a:rPr/@b`). */
+  bold?: boolean;
+  /** Whether the first run is italic (`a:rPr/@i`). */
+  italic?: boolean;
+  /** Resolved run colour hex (e.g. `"#FF0000"`), when present. */
+  color?: string;
+  /** Paragraph alignment (`a:pPr/@algn`): left / centre / right. */
+  align?: 'l' | 'ctr' | 'r';
+}
+/**
+ * A parsed chart-overlay shape positioned by a drawing anchor.
+ *
+ * Position is expressed as chart-relative fractions in {@link from}. For a
+ * `relSizeAnchor` the opposite corner is {@link to} (also fractional); for an
+ * `absSizeAnchor` the extent is {@link ext} in EMU.
+ */
+interface PptxChartUserShape {
+  /** Shape kind: text/preset shape, connector, or picture. */
+  kind: 'sp' | 'cxnSp' | 'pic';
+  /** Anchor kind that positioned the shape. */
+  anchor: 'rel' | 'abs';
+  /** Top-left corner as chart-relative fractions (0-1). */
+  from: {
+    x: number;
+    y: number;
+  };
+  /** Bottom-right corner as chart-relative fractions (0-1); relSizeAnchor only. */
+  to?: {
+    x: number;
+    y: number;
+  };
+  /** Extent in EMU (cx, cy); absSizeAnchor only. */
+  ext?: {
+    cx: number;
+    cy: number;
+  };
+  /** Preset geometry name (`a:prstGeom/@prst`), defaulting to `"rect"`. */
+  prst?: string;
+  /** Resolved solid-fill hex colour, when present. */
+  fill?: string;
+  /** Resolved line/stroke hex colour, when present. */
+  stroke?: string;
+  /** Line width in points (`a:ln/@w` divided by 12700), when present. */
+  strokeWidth?: number;
+  /** Text paragraphs of the shape's `txBody`, when present. */
+  paragraphs?: PptxChartUserShapeParagraph[];
+}
+//#endregion
 //#region src/core/types/chart.d.ts
 /**
  * Supported chart type discriminators.
@@ -2288,6 +2365,15 @@ interface PptxChartTreemapOptions {
 interface PptxChartSeries {
   name: string;
   values: number[];
+  /**
+   * Blank-value mask aligned index-for-index with {@link values}: `true` marks
+   * a category whose numeric cache point (`c:numCache/c:pt`) was absent or
+   * empty, i.e. a genuine blank rather than a real `0`. Present only when the
+   * source series actually contains blanks; when set, blank slots in
+   * {@link values} carry `0` as a placeholder. Renderers honour
+   * `c:dispBlanksAs` (gap / zero / span) using this mask.
+   */
+  blanks?: boolean[];
   color?: string;
   trendlines?: PptxChartTrendline[];
   errBars?: PptxChartErrBars[];
@@ -2509,6 +2595,14 @@ interface PptxChartManualLayout {
   y?: number;
   width?: number;
   height?: number;
+  /**
+   * Raw `c:extLst` (CT_ExtensionList) of the `c:manualLayout`, captured
+   * verbatim so it round-trips through the typed model. Without this, a dirty
+   * write of an edited layout would drop the extension list (the manual node
+   * is rebuilt from the typed fields). Emitted as the trailing child, matching
+   * the CT_ManualLayout schema order.
+   */
+  ext?: XmlObject;
 }
 /**
  * Typed manual layouts for chart regions that accept `c:layout`.
@@ -2700,6 +2794,15 @@ interface PptxChartData {
    * attempting to parse the nested drawing tree.
    */
   userShapesXml?: unknown;
+  /**
+   * Parsed, renderable drawing-overlay shapes resolved from the separate
+   * drawing part referenced by `c:userShapes/@r:id`
+   * (`ppt/drawings/drawingN.xml`). Each entry carries chart-relative anchor
+   * geometry plus light shape/text formatting so the viewer can render an
+   * overlay on top of the chart plot. Render-only: {@link userShapesXml}
+   * remains the source of truth for round-trip save.
+   */
+  userShapes?: PptxChartUserShape[];
   /**
    * Raw `c:pivotFmts` XML subtree preserved verbatim.
    *
@@ -2975,7 +3078,7 @@ interface PptxImageProperties {
   /** Crop-to-shape — CSS clip-path shape name. */
   cropShape?: PptxCropShape;
 }
-declare module "./hooks-unstable" {
+declare module "./internals" {
   interface TextStyle {
     /**
      * Raw `a:effectDag` XML node from `a:rPr`, preserved verbatim for
@@ -2993,7 +3096,7 @@ declare module "./hooks-unstable" {
     textEffectDagTree?: EffectDagContainer;
   }
 }
-declare module "./hooks-unstable" {
+declare module "./internals" {
   interface ShapeStyle {
     /**
      * Typed effect graph parsed from {@link ShapeStyle.effectDagXml}. The four
@@ -3720,7 +3823,7 @@ interface PptxSmartArtData {
 /**
  * Per-cell visual style for a table cell.
  *
- * All fields are optional — unset values inherit from the table style.
+ * All fields are optional - unset values inherit from the table style.
  *
  * @example
  * ```ts
@@ -3848,6 +3951,52 @@ interface PptxTableCellStyle {
   patternFillForeground?: string;
   /** Pattern fill background colour. */
   patternFillBackground?: string;
+  /**
+   * Cell 3D bevel + lighting from `a:tcPr/a:cell3D` (CT_Cell3D,
+   * ECMA-376 §21.1.3.1). Rendered as a CSS bevel treatment.
+   */
+  cell3D?: PptxTableCell3D;
+  /**
+   * `a:tcPr/@anchorCtr` - centre the text block in the direction
+   * perpendicular to the text flow (horizontal centring for horizontal text).
+   */
+  anchorCtr?: boolean;
+  /**
+   * `a:tcPr/@horzOverflow` (ST_TextHorzOverflowType): `clip` clips text at
+   * the cell edge, `overflow` (the default) lets it spill.
+   */
+  horzOverflow?: 'clip' | 'overflow';
+}
+/**
+ * Cell 3D bevel + lighting parsed from `a:tcPr/a:cell3D` (CT_Cell3D).
+ *
+ * Only the fields needed to render a plausible bevel treatment are captured;
+ * verbatim round-trip of the full node is handled separately by the save path.
+ *
+ * @example
+ * ```ts
+ * const c3d: PptxTableCell3D = {
+ *   bevelWidth: 8,
+ *   bevelHeight: 8,
+ *   bevelPreset: 'circle',
+ *   material: 'plastic',
+ * };
+ * // => satisfies PptxTableCell3D
+ * ```
+ */
+interface PptxTableCell3D {
+  /** Bevel width in px (from `a:bevel@w`, EMU converted). */
+  bevelWidth?: number;
+  /** Bevel height in px (from `a:bevel@h`, EMU converted). */
+  bevelHeight?: number;
+  /** Bevel preset name (`a:bevel@prst`, e.g. `circle`, `relaxedInset`). */
+  bevelPreset?: string;
+  /** Preset material (`a:cell3D@prstMaterial`, e.g. `plastic`, `metal`). */
+  material?: string;
+  /** Light rig type (`a:lightRig@rig`, e.g. `threePt`, `soft`). */
+  lightRig?: string;
+  /** Light rig direction (`a:lightRig@dir`, e.g. `tl`, `t`, `tr`). */
+  lightRigDirection?: string;
 }
 /**
  * A single table cell with text content, optional style, and merge info.
@@ -4071,7 +4220,7 @@ interface ParsedTableStyleBorder {
   fill?: ParsedTableStyleFill;
   /** Explicit hex colour when the line used `a:srgbClr` (e.g. `#808080`). */
   color?: string;
-  /** The line was `a:noFill` — an explicit "no border" that clears lower layers. */
+  /** The line was `a:noFill` - an explicit "no border" that clears lower layers. */
   noFill?: boolean;
 }
 /**
@@ -5067,6 +5216,14 @@ interface PptxNativeAnimation {
    * that aren't OLE charts).
    */
   graphicBuild?: string;
+  /**
+   * OLE-embedded chart build attribute (`p:bldOleChart/@bld`) when this
+   * animation stages an OLE chart graphic frame. Values follow
+   * ST_TLOleChartBuildType: `allAtOnce`, `series`, `category`, `seriesEl`,
+   * `categoryEl`. Lets a staged-reveal renderer build the chart by series /
+   * category / element to match PowerPoint, rather than as one whole element.
+   */
+  oleChartBuild?: string;
   /** Schema-accurate `p:bldGraphic/p:bldAsOne|p:bldSub` representation. */
   graphicBuildProperties?: PptxGraphicBuild;
   /**
@@ -5556,6 +5713,18 @@ interface PptxAppProperties {
   template?: string;
   /** Hyperlink base URL. */
   hyperlinkBase?: string;
+  /** Document security bitmask (`<DocSecurity>`). */
+  docSecurity?: number;
+  /** Number of multimedia clips (`<MMClips>`). */
+  mmClips?: number;
+  /** Whether thumbnail images were scaled to fit (`<ScaleCrop>`). */
+  scaleCrop?: boolean;
+  /** Whether hyperlinks are current (`<LinksUpToDate>`). */
+  linksUpToDate?: boolean;
+  /** Whether the document is shared (`<SharedDoc>`). */
+  sharedDoc?: boolean;
+  /** Whether hyperlinks changed since last save (`<HyperlinksChanged>`). */
+  hyperlinksChanged?: boolean;
 }
 //#endregion
 //#region src/core/types/presentation-print-properties.d.ts
@@ -6060,6 +6229,21 @@ interface PptxActiveXControl {
   name?: string;
   /** Shape ID this control is linked to (from @spid). */
   shapeId?: string;
+  /** X position (px) of the control's fallback picture, if present. */
+  x?: number;
+  /** Y position (px) of the control's fallback picture, if present. */
+  y?: number;
+  /** Width (px) of the control's fallback picture, if present. */
+  width?: number;
+  /** Height (px) of the control's fallback picture, if present. */
+  height?: number;
+  /**
+   * Relationship ID of the control's static fallback picture
+   * (`mc:AlternateContent > mc:Fallback > p:pic > p:blipFill > a:blip@r:embed`).
+   * Renderers resolve this to an image so a control shows its last static
+   * frame instead of a blank area (the live ActiveX cannot run in a viewer).
+   */
+  fallbackImageRelId?: string;
   /** Raw XML for round-trip preservation. */
   rawXml?: XmlObject;
 }
@@ -6186,6 +6370,13 @@ interface PptxSlide {
   customerData?: PptxCustomerData[];
   /** ActiveX control references from `p:controls` on this slide. */
   activeXControls?: PptxActiveXControl[];
+  /**
+   * Shapes parsed from a referenced legacy VML drawing part
+   * (`ppt/drawings/vmlDrawing*.vml`, linked via a `legacyDrawing`
+   * relationship). These are read-only render hints: the VML part itself is
+   * preserved verbatim on save, so this field is not re-serialized.
+   */
+  legacyVmlElements?: PptxElement[];
   /** Per-slide header/footer flags from `<p:hf>` (P-H3). */
   headerFooterFlags?: PptxHeaderFooterFlags;
   /** Server-backed slide synchronization metadata stored in a related OPC part. */
@@ -6294,12 +6485,6 @@ interface PptxPresentationProperties {
   showSubtitles?: boolean;
   /** Typed `p:prnPr` settings. Set to null during save to remove the element. */
   printProperties?: PptxPresentationPrintProperties | null;
-  /** @deprecated Use `printProperties.printWhat`; retained as a handout compatibility alias. */
-  printSlidesPerPage?: number;
-  /** @deprecated Use `printProperties.frameSlides`. */
-  printFrameSlides?: boolean;
-  /** @deprecated Use `printProperties.colorMode`. */
-  printColorMode?: 'clr' | 'gray' | 'bw';
   /** Most-recently-used colours from the presentation palette. */
   mruColors?: string[];
   /** Grid spacing in EMUs (cx, cy). Default is 914400 / 8 = 114300. */
@@ -8142,12 +8327,69 @@ interface CollaborationConfig {
    */
   writeBackDebounceMs?: number;
 }
+/**
+ * Normalized staged-reveal mode for a chart graphic frame, derived from the
+ * OOXML `a:bldChart/@bld` (or `p:bldOleChart/@bld`) token:
+ *  - `asOne`      the whole chart appears at once (`allAtOnce`).
+ *  - `bySeries`   one data series is revealed per stage (`series`).
+ *  - `byCategory` one category is revealed per stage (`category`).
+ *  - `byElement`  one series/category ELEMENT is revealed per stage
+ *                 (`seriesElement` / `categoryElement`).
+ */
+type ChartBuildMode = 'asOne' | 'bySeries' | 'byCategory' | 'byElement';
+/**
+ * Normalized staged-reveal mode for a SmartArt diagram, derived from the OOXML
+ * `a:bldDgm/@bld` or `p:bldDgm/@bld` token:
+ *  - `asOne`        the whole diagram appears at once (`whole` / `allAtOnce`).
+ *  - `byOne`        one node is revealed per stage (`one`, and the assorted
+ *                   `depthBy*` / `breadthBy*` / directional traversals).
+ *  - `byLvl`        levels are revealed one element at a time (`lvlOne`).
+ *  - `byLvlAtOnce`  a whole level is revealed per stage (`lvlAtOnce`).
+ */
+type DiagramBuildMode = 'asOne' | 'byOne' | 'byLvl' | 'byLvlAtOnce';
+/**
+ * Playback-time staged-build state surfaced on {@link ElementAnimationState}.
+ * `progress` is the 0..1 fraction of the build revealed at the current playback
+ * time; a consumer maps it to its own item COUNT (see `revealedStageCount`).
+ */
+type ElementBuildState = {
+  kind: 'chart';
+  mode: ChartBuildMode;
+  progress: number;
+} | {
+  kind: 'diagram';
+  mode: DiagramBuildMode;
+  progress: number;
+};
 /** Snapshot of a single element's animation state at a point in the timeline. */
 interface ElementAnimationState {
   /** Whether the element should be visible. */
   visible: boolean;
   /** CSS animation shorthand to apply (undefined = no active animation). */
   cssAnimation: string | undefined;
+  /**
+   * Staged-build reveal state, present only when the active animation builds a
+   * chart or SmartArt diagram in stages (`p:bldChart` / `p:bldDgm`) rather than
+   * revealing the whole element at once. A staged renderer multiplies
+   * `build.progress` (0..1) by its own series / category / level COUNT to
+   * decide how many stages are revealed at the current playback time; see
+   * {@link import('./animation-build').revealedStageCount}. Absent for ordinary
+   * whole-element entrances, so existing renderers are unaffected.
+   */
+  build?: ElementBuildState;
+  /**
+   * True when an active `p:animClr` color animation targets this shape's fill.
+   * A vector renderer should then paint the fill with `fill: inherit` so the
+   * wrapper-level colour keyframes cascade to the SVG path. Absent/false means
+   * no active fill-colour animation.
+   */
+  animatesFill?: boolean;
+  /**
+   * True when an active `p:animClr` color animation targets this shape's
+   * stroke. A vector renderer should then paint the stroke with
+   * `stroke: inherit`. Absent/false means no active stroke-colour animation.
+   */
+  animatesStroke?: boolean;
 }
 /** The unit system used for ruler display. */
 type RulerUnit = 'inches' | 'centimetres';
@@ -8740,1029 +8982,1040 @@ interface PowerPointViewerHandle extends FileViewerHandle, PowerPointViewerAPI {
   getContent: () => Promise<Uint8Array>;
 }
 
-//#region src/viewer/hooks/presentation-mode/types.d.ts
-/**
- * How a forward/backward slide advance was requested.
- *
- * - `'click'`: a click/tap on the slide surface (PowerPoint's "On Mouse Click"
- *   advance). This is the only trigger governed by `advanceOnClick`.
- * - `'explicit'`: keyboard, navigation buttons, action triggers, and timed
- *   auto-advance. These always navigate regardless of `advanceOnClick`, matching
- *   PowerPoint (arrow keys / Next always work even when click-advance is off).
- */
-type SlideAdvanceTrigger = 'click' | 'explicit';
-/**
- * State describing the transition overlay that plays while advancing into a
- * slide that carries a `p:transition`. The outgoing slide is snapshotted into
- * an animated overlay layer while the incoming slide renders underneath on the
- * main stage; the overlay tears down once `durationMs` elapses.
- */
-interface PresentationTransitionOverlayState {
-  /** Index of the leaving slide, rendered (animated) in the overlay layer. */
-  outgoingSlideIndex: number;
-  /** Index of the arriving slide, already live on the main stage. */
-  incomingSlideIndex: number;
-  /** The incoming slide's transition definition (drives the CSS animation). */
-  transition: PptxSlideTransition;
-  /** Resolved transition duration (ms). */
-  durationMs: number;
-}
-interface UsePresentationModeInput {
+//#region src/viewer/components/toolbar/toolbar-types.d.ts
+interface ToolbarProps {
+  fileName?: string;
   mode: ViewerMode;
-  slides: PptxSlide[];
-  visibleSlideIndexes: number[];
-  activeSlideIndex: number;
-  containerRef: React.RefObject<HTMLElement | null>;
-  /** Raw PPTX bytes: forwarded to audience window for content sharing. */
-  content?: ArrayBuffer | Uint8Array | null;
+  canEdit: boolean;
+  isNarrowViewport: boolean;
+  isSidebarCollapsed: boolean;
+  isInspectorPaneOpen: boolean;
+  isCompactToolbarOpen: boolean;
+  toolbarSection: ToolbarSection;
+  scale: number;
+  canUndo: boolean;
+  canRedo: boolean;
+  undoLabel: string | undefined;
+  redoLabel: string | undefined;
+  findReplaceOpen: boolean;
+  selectedElement: PptxElement | null;
+  tableEditorState?: TableCellEditorState | null;
+  editTemplateMode: boolean;
+  newShapeType: SupportedShapeType;
+  activeTool: DrawingTool;
+  drawingColor: string;
+  drawingWidth: number;
+  clipboardPayload: ElementClipboardPayload | null;
   onSetMode: (mode: ViewerMode) => void;
-  onSetActiveSlideIndex: (index: number) => void;
-  /**
-   * Play a sound file for an action/transition. When `options.loop` is true the
-   * audio repeats until the next animation sound plays or the show exits
-   * (used for transition sounds flagged with `soundLoop`).
-   */
-  onPlayActionSound?: (soundPath: string, options?: {
-    loop?: boolean;
-  }) => void;
-  /** Called when L key is pressed during presentation. */
-  onToggleLaser?: () => void;
-  /** Called when P key is pressed during presentation. */
-  onTogglePen?: () => void;
-  /** Called when E key is pressed during presentation. */
-  onToggleEraser?: () => void;
-  /** Called when Ctrl+M is pressed during presentation. */
-  onToggleToolbar?: () => void;
-  /** Called to persist rehearsal timings into slide transitions. */
-  onSaveRehearsalTimings?: (timings: Record<number, number>) => void;
-  /** Whether to loop continuously (kiosk or explicit loop setting). */
-  loopContinuously?: boolean;
-  /** Whether to play animations during the slide show (false = skip all animations). */
-  showWithAnimation?: boolean;
-  /** Whether to use rehearsed auto-advance timings (false = manual advance only). */
-  useTimings?: boolean;
-  /**
-   * Options > Advanced > "End with black slide". When true (PowerPoint's
-   * default), advancing past the last slide shows a black end-of-show
-   * screen; the next advance (or a click on it) exits. When false,
-   * advancing past the last slide exits the show directly.
-   */
-  endWithBlackSlide?: boolean;
-}
-interface UsePresentationModeResult {
-  presentationSlideIndex: number;
-  setPresentationSlideIndex: (index: number) => void;
-  presentationSlideVisible: boolean;
-  /** Active slide-transition overlay, or `null` when no transition is playing. */
-  transitionOverlay: PresentationTransitionOverlayState | null;
-  /** Tear down the transition overlay once its animation completes. */
-  handleTransitionOverlayComplete: () => void;
-  presentationAnimations: PresentationAnimationRuntime[];
-  presentationElementStates: Map<string, ElementAnimationState>;
-  presentationKeyframesCss: string;
-  clearPresentationTimers: () => void;
-  runPresentationEntranceAnimations: (slideIndex: number) => void;
-  /** True while the black "End of slide show" screen is displayed. */
-  endOfShowVisible: boolean;
-  movePresentationSlide: (direction: 1 | -1, trigger?: SlideAdvanceTrigger) => void;
-  navigateToSlide: (slideIndex: number) => void;
-  handlePresentationAction: (action: PptxAction) => void;
-  /**
-   * Handle a shape click in presentation mode. If the shape is an interactive
-   * trigger, play its animation sequence. Returns `true` if handled.
-   */
-  handleInteractiveShapeClick: (shapeId: string) => boolean;
-  /** Set of shape IDs that are interactive sequence triggers on the current slide. */
-  interactiveTriggerShapeIds: ReadonlySet<string>;
-  /** Set of shape IDs that are hover animation triggers on the current slide. */
-  hoverTriggerShapeIds: ReadonlySet<string>;
-  /** Handle hover start on a shape. If the shape has a hover sequence, play it. Returns `true` if handled. */
-  handleHoverStart: (shapeId: string) => boolean;
-  /** Handle hover end on a shape. Resets the hover sequence for replay. */
-  handleHoverEnd: (shapeId: string) => void;
-  /** Must be called from a user-gesture handler (click) to satisfy browser fullscreen policy. */
-  enterPresentMode: () => void;
-  /** Whether presenter view (split-screen with notes) is active instead of fullscreen. */
-  presenterMode: boolean;
-  /** Enter presenter view mode (no fullscreen, shows notes panel). */
-  enterPresenterView: () => void;
-  /** Toggle between fullscreen and presenter view during presentation. */
-  togglePresenterView: () => void;
-  /** Timestamp (ms) when the presentation started: used for elapsed timer. */
-  presentationStartTime: number | null;
-  /** Whether the current presentation session is in rehearse-timings mode. */
-  rehearsing: boolean;
-  /** Enter rehearse-timings mode (fullscreen presentation + timing HUD). */
-  enterRehearsalMode: () => void;
-  /** Recorded timings in ms, keyed by slide index. Populated during rehearsal. */
-  recordedTimings: Record<number, number>;
-  /** Timestamp when the current slide started (ms since epoch). */
-  slideStartTime: number | null;
-  /** Whether the rehearsal summary dialog should be shown. */
-  showRehearsalSummary: boolean;
-  /** Dismiss the rehearsal summary (discard timings). */
-  dismissRehearsalSummary: () => void;
-  /** Save recorded timings into each slide's transition.advanceAfterMs. */
-  saveRehearsalTimings: () => void;
-  /** Whether rehearsal timer is paused. */
-  rehearsalPaused: boolean;
-  /** Toggle the rehearsal timer pause state. */
-  toggleRehearsalPause: () => void;
-  /** Handle a zoom element click in presentation mode. */
-  handleZoomClick: (targetSlideIndex: number, returnSlideIndex: number) => void;
-  /** Ref holding the slide index to return to after zoom navigation. */
-  zoomReturnSlideIndex: React.RefObject<number | null>;
-  /** Navigate back to the zoom summary slide. Returns true if navigation occurred. */
-  returnToZoomSlide: () => boolean;
-  /** Clear the stored zoom return index. */
-  clearZoomReturn: () => void;
-  /** Open the audience display in a separate browser window. Returns `true` if successful. */
-  openAudienceWindow: () => boolean;
-  /** Close the audience display window. */
-  closeAudienceWindow: () => void;
-  /** Whether the audience window is currently open. */
-  isAudienceWindowOpen: () => boolean;
-  /** Send a slide index to the audience window explicitly. */
-  syncSlideToAudience: (slideIndex: number) => void;
-  syncStateToAudience: (snapshot: PresentationSnapshot) => void;
-  presenterSnapshot: PresentationSnapshot;
-  setPresenterBlackout: (blackout: PresentationSnapshot['blackout']) => void;
-  togglePresenterTimer: () => void;
-  resetPresenterTimer: () => void;
-  stepPresenterZoom: (direction: 1 | -1) => void;
-  resetPresenterZoom: () => void;
-  setPresenterCaption: (caption: string) => void;
-  setPresenterSubtitlesVisible: (visible: boolean) => void;
-  updatePresenterSnapshot: (patch: Partial<PresentationSnapshot>) => void;
-  swapPresenterDisplays: () => Promise<boolean>;
-}
-//#endregion
-//#region src/viewer/hooks/useThemeSwitching.d.ts
-interface UseThemeSwitchingInput {
-  /** Ref to the PptxHandler instance. */
-  handlerRef: RefObject<PptxHandler | null>;
-  /** Current parsed presentation data (null when nothing is loaded). */
-  data: PptxData | null;
-  /** Callback to update the presentation data after theme switch. */
-  onDataChange: (newData: PptxData) => void;
-  /** Optional callback fired when theme switch completes successfully. */
-  onThemeChanged?: (preset: PptxThemePreset) => void;
-}
-interface ThemeSwitchingResult {
-  /** All available built-in theme presets. */
-  presets: readonly PptxThemePreset[];
-  /**
-   * Apply a theme preset to the current presentation.
-   * Updates both the in-memory ZIP and all resolved element colours.
-   */
-  switchToPreset: (preset: PptxThemePreset) => Promise<void>;
-  /**
-   * Apply a custom colour scheme (and optional font scheme) to the
-   * current presentation.
-   */
-  switchToCustom: (colorScheme: PptxThemeColorScheme, fontScheme?: PptxThemeFontScheme, themeName?: string) => Promise<void>;
-  /**
-   * Get the preset matching the current presentation theme (if any).
-   * Returns undefined if the current theme does not match a built-in preset.
-   */
-  currentPreset: PptxThemePreset | undefined;
-}
-/**
- * React hook providing theme switching capabilities for the PowerPoint viewer.
- *
- * @example
- * ```tsx
- * const { presets, switchToPreset, currentPreset } = useThemeSwitching({
- *   handlerRef,
- *   data,
- *   onDataChange: setData,
- * });
- *
- * return (
- *   <div>
- *     {presets.map(preset => (
- *       <button
- *         key={preset.id}
- *         onClick={() => switchToPreset(preset)}
- *         aria-pressed={preset.id === currentPreset?.id}
- *       >
- *         {preset.name}
- *       </button>
- *     ))}
- *   </div>
- * );
- * ```
- */
-declare function useThemeSwitching(input: UseThemeSwitchingInput): ThemeSwitchingResult;
-//#endregion
-//#region ../../node_modules/.bun/lib0@0.2.117/node_modules/lib0/observable.d.ts
-/**
- * Handles named events.
- *
- * @deprecated
- * @template N
- */
-declare class Observable<N> {
-  /**
-   * Some desc.
-   * @type {Map<N, any>}
-   */
-  _observers: Map<N, any>;
-  /**
-   * @param {N} name
-   * @param {function} f
-   */
-  on(name: N, f: Function): void;
-  /**
-   * @param {N} name
-   * @param {function} f
-   */
-  once(name: N, f: Function): void;
-  /**
-   * @param {N} name
-   * @param {function} f
-   */
-  off(name: N, f: Function): void;
-  /**
-   * Emit a named event. All registered event listeners that listen to the
-   * specified name will receive the event.
-   *
-   * @todo This should catch exceptions
-   *
-   * @param {N} name The event name.
-   * @param {Array<any>} args The arguments that are applied to the event listener.
-   */
-  emit(name: N, args: Array<any>): void;
-  destroy(): void;
-}
-//#endregion
-//#region ../../node_modules/.bun/y-protocols@1.0.7+253afa400b9c0a30/node_modules/y-protocols/awareness.d.ts
-/**
- * @typedef {Object} MetaClientState
- * @property {number} MetaClientState.clock
- * @property {number} MetaClientState.lastUpdated unix timestamp
- */
-/**
- * The Awareness class implements a simple shared state protocol that can be used for non-persistent data like awareness information
- * (cursor, username, status, ..). Each client can update its own local state and listen to state changes of
- * remote clients. Every client may set a state of a remote peer to `null` to mark the client as offline.
- *
- * Each client is identified by a unique client id (something we borrow from `doc.clientID`). A client can override
- * its own state by propagating a message with an increasing timestamp (`clock`). If such a message is received, it is
- * applied if the known state of that client is older than the new state (`clock < newClock`). If a client thinks that
- * a remote client is offline, it may propagate a message with
- * `{ clock: currentClientClock, state: null, client: remoteClient }`. If such a
- * message is received, and the known clock of that client equals the received clock, it will override the state with `null`.
- *
- * Before a client disconnects, it should propagate a `null` state with an updated clock.
- *
- * Awareness states must be updated every 30 seconds. Otherwise the Awareness instance will delete the client state.
- *
- * @extends {Observable<string>}
- */
-declare class Awareness extends Observable<string> {
-  /**
-   * @param {Y.Doc} doc
-   */
-  constructor(doc: Y.Doc);
-  doc: Y.Doc;
-  /**
-   * @type {number}
-   */
-  clientID: number;
-  /**
-   * Maps from client id to client state
-   * @type {Map<number, Object<string, any>>}
-   */
-  states: Map<number, {
-    [x: string]: any;
-  }>;
-  /**
-   * @type {Map<number, MetaClientState>}
-   */
-  meta: Map<number, MetaClientState>;
-  _checkInterval: any;
-  /**
-   * @return {Object<string,any>|null}
-   */
-  getLocalState(): {
-    [x: string]: any;
-  } | null;
-  /**
-   * @param {Object<string,any>|null} state
-   */
-  setLocalState(state: {
-    [x: string]: any;
-  } | null): void;
-  /**
-   * @param {string} field
-   * @param {any} value
-   */
-  setLocalStateField(field: string, value: any): void;
-  /**
-   * @return {Map<number,Object<string,any>>}
-   */
-  getStates(): Map<number, {
-    [x: string]: any;
+  onToggleSidebar: () => void;
+  onToggleInspector: () => void;
+  /** Opens the inspector pane and switches to the properties tab (for animation panel). */
+  onOpenAnimationPanel: () => void;
+  /** Adds an animation preset to the selected element. */
+  onAddAnimation?: (preset: string, group: 'entrance' | 'emphasis' | 'exit') => void;
+  /** Removes all animations from the selected element. */
+  onRemoveAnimation?: () => void;
+  onToggleCompactToolbar: () => void;
+  onSetToolbarSection: (section: ToolbarSection) => void;
+  onZoomIn: () => void;
+  onZoomOut: () => void;
+  onZoomToFit: () => void;
+  onUndo: () => void;
+  onRedo: () => void;
+  onToggleFindReplace: () => void;
+  onSetNewShapeType: (type: SupportedShapeType) => void;
+  onAddTextBox: () => void;
+  onAddShape: () => void;
+  onAddTable: () => void;
+  onAddChart?: (chartType: PptxChartType) => void;
+  onAddSmartArt: () => void;
+  onAddEquation: () => void;
+  onAddActionButton: (shapeType: string) => void;
+  onInsertField?: (fieldType: string, value?: string) => void;
+  onOpenHeaderFooter?: () => void;
+  onOpenImagePicker: () => void;
+  onOpenMediaPicker: () => void;
+  onSetActiveTool: (tool: DrawingTool) => void;
+  onSetDrawingColor: (color: string) => void;
+  onSetDrawingWidth: (width: number) => void;
+  onSetEditTemplateMode: (mode: boolean) => void;
+  spellCheckEnabled: boolean;
+  showGrid: boolean;
+  showRulers: boolean;
+  snapToGrid: boolean;
+  snapToShape: boolean;
+  onSetSpellCheckEnabled: (enabled: boolean) => void;
+  onSetShowGrid: (enabled: boolean) => void;
+  onSetShowRulers: (enabled: boolean) => void;
+  onSetSnapToGrid: (enabled: boolean) => void;
+  onSetSnapToShape: (enabled: boolean) => void;
+  onAddGuide: (axis: 'h' | 'v') => void;
+  onAlignElements: (align: string) => void;
+  onDistributeElements: (axis: string) => void;
+  canDistribute: boolean;
+  onCopy: () => void;
+  onCut: () => void;
+  onPaste: () => void;
+  onFlip: (direction: 'horizontal' | 'vertical') => void;
+  onMoveLayer: (direction: string) => void;
+  onMoveLayerToEdge: (direction: string) => void;
+  onDuplicate: () => void;
+  onDelete: () => void;
+  /** Open another presentation (File ▸ Open). Hidden when not provided. */
+  onOpenFile?: () => void;
+  onOpenRecentFile?: (key: string) => void;
+  onCreatePresentation: (templateId: string) => void;
+  onExportPng: () => void;
+  onExportPdf: () => void;
+  onExportVideo: () => void;
+  onExportGif: () => void;
+  onPackageForSharing: () => void;
+  onOpenShareDialog?: () => void;
+  onSaveAsPptx: () => void;
+  onSaveAsPpsx: () => void;
+  onSaveAsPptm: () => void;
+  hasMacros: boolean;
+  onCopySlideAsImage: () => void;
+  onPrint: () => void;
+  onToggleShortcuts: () => void;
+  onOpenSettings?: () => void;
+  onRunAccessibilityCheck: () => void;
+  onToggleSlideSorter: () => void;
+  onUpdateTextStyle: (updates: Partial<TextStyle>) => void;
+  /** Rewrite the selected text's characters (PowerPoint's Aa "Change Case" dropdown). */
+  onTransformTextCase: (mode: ChangeCaseMode) => void;
+  isOverflowMenuOpen: boolean;
+  onSetOverflowMenuOpen: (open: boolean) => void;
+  layoutOptions: Array<{
+    path: string;
+    name: string;
   }>;
+  onInsertSlideFromLayout: (path: string, name?: string) => void;
+  customShows: PptxCustomShow[];
+  activeCustomShowId: string | null;
+  onSetActiveCustomShowId: (id: string | null) => void;
+  onCreateCustomShow: () => void;
+  onRenameActiveCustomShow: () => void;
+  onDeleteActiveCustomShow: () => void;
+  onToggleCurrentSlideInActiveShow: () => void;
+  isCurrentSlideInActiveShow: boolean;
+  onToggleVersionHistory?: () => void;
+  onOpenPasswordProtection?: () => void;
+  onOpenDocumentProperties?: () => void;
+  onOpenFontEmbedding?: () => void;
+  onOpenDigitalSignatures?: () => void;
+  onEnterMasterView: () => void;
+  onCloseMasterView: () => void;
+  onEnterPresenterView?: () => void;
+  onEnterRehearsalMode?: () => void;
+  onToggleThemeEditor: () => void;
+  isThemeEditorOpen: boolean;
+  onToggleThemeGallery: () => void;
+  isThemeGalleryOpen: boolean;
+  onCompare?: () => void;
+  onToggleComments?: () => void;
+  isCommentsPanelOpen?: boolean;
+  spellCheckActive?: boolean;
+  slideCommentCount?: number;
+  formatPainterActive?: boolean;
+  onToggleFormatPainter?: () => void;
+  canActivateFormatPainter?: boolean;
+  isSelectionPaneOpen?: boolean;
+  onToggleSelectionPane?: () => void;
+  eyedropperActive?: boolean;
+  onToggleEyedropper?: () => void;
+  onOpenSetUpSlideShow?: () => void;
+  onOpenBroadcastDialog?: () => void;
+  onToggleSubtitles?: () => void;
+  showSubtitles?: boolean;
+  activeSlide?: PptxSlide;
+  onTransitionChange: (updates: Partial<PptxSlideTransition>) => void;
+  onApplyTransitionToAll: () => void;
+  /** Host-supplied list of toolbar buttons/ribbon tabs to hide. See `PowerPointViewerProps.hiddenActions`. */
+  hiddenActions?: readonly ToolbarActionId[];
+  /** Whether the AI assistant is available (the host passed the `ai` prop). */
+  aiEnabled?: boolean;
+  /** Whether the AI assistant panel is currently open. */
+  isAiPanelOpen?: boolean;
+  /** Toggle the AI assistant panel. */
+  onToggleAiPanel?: () => void;
 }
-type MetaClientState = {
-  clock: number;
-  /**
-   * unix timestamp
-   */
-  lastUpdated: number;
-};
-//#endregion
-//#region src/viewer/hooks/collaboration/useYjsProvider.d.ts
-interface UseYjsProviderInput {
-  /**
-   * Collaboration config, or `undefined` when collaboration is inactive. The
-   * hook is always called (React hook rules) but stays fully dormant, never
-   * opening a transport, while config is absent.
-   */
-  config?: CollaborationConfig;
-}
-interface UseYjsProviderResult {
-  /** Current WebSocket connection status. */
-  status: ConnectionStatus;
-  /** The Yjs awareness instance (null until connected). */
-  awareness: Awareness | null;
-  /** The Yjs document (null until initialised). */
-  doc: Doc | null;
-  /** Local awareness client ID. */
-  clientId: number | null;
-  /**
-   * Whether the provider completed its initial document sync. Local doc
-   * writes should be gated on this so a late joiner never seeds its
-   * bootstrap deck into a room whose content has not arrived yet. Websocket
-   * flips it on the provider's 'synced' event; webrtc flips it on peer sync
-   * or after {@link INITIAL_SYNC_GRACE_MS} (a lone fresh-room peer never
-   * receives a sync event).
-   */
-  synced: boolean;
-  /** Manually retry the connection after a timeout or error. */
-  retry: () => void;
-}
-/**
- * Lazily loads `yjs` and `y-websocket`, creates a Y.Doc and
- * WebSocketProvider, and tracks the connection lifecycle.
- *
- * If the connection does not succeed within {@link CONNECTION_TIMEOUT_MS},
- * the provider is torn down and status moves to `'error'`. The consumer
- * can call `retry()` to attempt a fresh connection.
- *
- * The Yjs packages are dynamically imported so they are fully
- * tree-shaken when collaboration is not enabled.
- */
-declare function useYjsProvider({ config }: UseYjsProviderInput): UseYjsProviderResult;
-//#endregion
-//#region src/viewer/hooks/collaboration/usePresenceTracking.d.ts
-interface UsePresenceTrackingInput {
-  awareness: Awareness | null;
-  localClientId: number | null;
-  userName: string;
-  userColor: string;
-  userAvatar?: string;
-  /** Role in the session (broadcaster, viewer, or collaborator). */
-  role?: string;
-  canvasWidth: number;
-  canvasHeight: number;
-}
-interface UsePresenceTrackingResult {
-  /** Presence data for all remote users (excludes local). */
-  remoteUsers: UserPresence[];
-  /** Broadcast a partial presence update for the local user. */
-  broadcastPresence: (update: Partial<Omit<UserPresence, 'clientId'>>) => void;
-}
-declare function usePresenceTracking({ awareness, localClientId, userName, userColor, userAvatar, role, canvasWidth, canvasHeight }: UsePresenceTrackingInput): UsePresenceTrackingResult;
 //#endregion
-//#region src/viewer/hooks/collaboration/useCollaborativeState.d.ts
-interface UseCollaborativeStateInput {
-  /**
-   * Collaboration config, or `undefined` when collaboration is inactive. The
-   * hook is always called so the surrounding provider keeps a stable React
-   * tree shape; it produces a dormant value (no transport, empty presence)
-   * while config is absent.
-   */
-  config?: CollaborationConfig;
-  canvasWidth: number;
-  canvasHeight: number;
+//#region src/viewer/utils/table-band-style.d.ts
+/** Context for resolving table style colours from the theme. */
+interface TableStyleContext {
+  tableStyleMap?: ParsedTableStyleMap;
+  theme?: PptxTheme;
 }
-declare function useCollaborativeState({ config, canvasWidth, canvasHeight }: UseCollaborativeStateInput): CollaborationContextValue | null;
 //#endregion
-//#region src/viewer/hooks/collaboration/useCollaborativeHistory.d.ts
-interface UseCollaborativeHistoryInput {
-  /** The local user's client ID (from Yjs awareness). */
-  localClientId: number | null;
-  /** Standard history undo function. */
-  handleUndo: () => void;
-  /** Standard history redo function. */
-  handleRedo: () => void;
-  /** Whether undo is available. */
-  canUndo: boolean;
-  /** Whether redo is available. */
-  canRedo: boolean;
-}
-interface UseCollaborativeHistoryResult {
-  /** Undo the last local change. */
-  handleUndo: () => void;
-  /** Redo the last undone local change. */
-  handleRedo: () => void;
-  /** Whether undo is available. */
-  canUndo: boolean;
-  /** Whether redo is available. */
-  canRedo: boolean;
+//#region src/viewer/components/canvas/canvas-types.d.ts
+interface ZoomViewport {
+  canvasViewportRef: React$1.RefObject<HTMLDivElement | null>;
+  editWrapperRef: React$1.RefObject<HTMLDivElement | null>;
+  canvasStageRef: React$1.RefObject<HTMLDivElement | null>;
+  editorScale: number;
 }
-declare function useCollaborativeHistory({ localClientId: _localClientId, handleUndo, handleRedo, canUndo, canRedo }: UseCollaborativeHistoryInput): UseCollaborativeHistoryResult;
-//#endregion
-//#region src/viewer/hooks/collaboration/useYjsDocumentSync.d.ts
-interface UseYjsDocumentSyncInput {
-  /** The Yjs document (from useYjsProvider). null when not collaborating. */
-  doc: Doc | null;
-  /** Current slides state. */
-  slides: PptxSlide[];
-  /** Separated master/layout (template) elements, merged back on write-back. */
-  templateElementsBySlideId: Record<string, PptxElement[]>;
-  /** React state setter for slides. */
-  setSlides: React.Dispatch<React.SetStateAction<PptxSlide[]>>;
-  /** Whether collaboration is active (status === 'connected'). */
-  isConnected: boolean;
-  /**
-   * Whether the provider completed its initial document sync. Local -> doc
-   * writes are gated on this so a late joiner never seeds its bootstrap deck
-   * into a room whose real content has not arrived yet. Defaults to true for
-   * callers that manage sync readiness themselves.
-   */
-  isSynced?: boolean;
-  /** Collaboration config (for role and write-back). */
-  config?: Pick<CollaborationConfig, 'role' | 'onWriteBack' | 'writeBackDebounceMs'>;
+interface SlideCanvasProps {
+  activeSlide: PptxSlide | undefined;
+  templateElements: PptxElement[];
+  canvasSize: CanvasSize;
+  zoom: ZoomViewport;
+  mode: ViewerMode;
+  canEdit: boolean;
+  editTemplateMode: boolean;
+  selectedElementIdSet: Set<string>;
+  selectedElement: PptxElement | null;
+  inlineEditingElementId: string | null;
+  inlineEditingText: string;
+  spellCheckEnabled: boolean;
+  mediaDataUrls: Map<string, string>;
+  tableEditorState: TableCellEditorState | null;
+  marqueeSelectionState: MarqueeSelectionState | null;
+  snapLines: Array<{
+    axis: string;
+    position: number;
+  }>;
+  showGrid: boolean;
+  /** Grid spacing in CSS px (derived from PPTX gridSpacing EMUs). */
+  gridSpacingPx?: number;
+  showRulers: boolean;
+  /** Unit system for rulers (default: inches). */
+  rulerUnit?: RulerUnit;
+  guides: Array<{
+    id: string;
+    axis: 'h' | 'v';
+    position: number;
+  }>;
+  presentationElementStates?: Map<string, ElementAnimationState>;
+  presentationKeyframesCss?: string;
+  onClick: (elementId: string, e: React$1.MouseEvent) => void;
+  onDoubleClick: (elementId: string, e: React$1.MouseEvent) => void;
+  onMouseDown: (elementId: string, e: React$1.MouseEvent) => void;
+  onContextMenu: (elementId: string, e: React$1.MouseEvent) => void;
+  /** Called when the user presses mouse down on empty canvas space. */
+  onCanvasMouseDown?: (e: React$1.MouseEvent) => void;
+  onResizePointerDown: (elementId: string, e: React$1.MouseEvent, handle: string) => void;
+  onAdjustmentPointerDown: (elementId: string, e: React$1.MouseEvent) => void;
+  /** Commit a new rotation (degrees) when the on-canvas rotate handle is dragged. */
+  onRotate?: (elementId: string, rotationDeg: number) => void;
+  onInlineEditChange: (text: string) => void;
+  onInlineEditCommit: () => void;
+  onInlineEditCancel: () => void;
+  onTableCellSelect: (cell: Omit<TableCellEditorState, 'elementId'> | null, elementId: string) => void;
+  /** Called when an edited table cell should be committed. */
+  onCommitCellEdit?: (elementId: string, rowIndex: number, colIndex: number, text: string) => void;
   /**
-   * Return the source PPTX bytes for write-back serialization. Only called
-   * when role === 'owner' and onWriteBack is set.
+   * Commit a partial update to a SmartArt element from inline (on-canvas) node
+   * editing. Routed to the same element-update path the inspector uses (undo/redo
+   * + dirty marking). When absent, inline SmartArt editing is disabled.
    */
-  getSourceBytes?: () => Uint8Array | null;
+  onUpdateSmartArtElement?: (elementId: string, updates: Partial<PptxElement>) => void;
   /**
-   * Monotonic counter bumped each time the content-load pipeline finishes
-   * applying a parsed deck to viewer state. A local load that lands while the
-   * shared doc already holds slides (a late joiner's bootstrap deck parsing
-   * after the room state arrived) would silently clobber the synced slides;
-   * each bump re-adopts the doc's slides when the room has content.
+   * Apply a text-style toggle (Ctrl/Cmd+B/I/U) to the element being
+   * inline-edited. Routed to the same updateSelectedTextStyle path as the
+   * toolbar. When absent, the inline formatting shortcuts are inert.
    */
-  loadVersion?: number;
-}
-declare function useYjsDocumentSync({ doc, slides, templateElementsBySlideId, setSlides, isConnected, isSynced, config, getSourceBytes, loadVersion }: UseYjsDocumentSyncInput): void;
-//#endregion
-//#region src/viewer/hooks/collaboration/useBroadcastFollower.d.ts
-interface UseBroadcastFollowerInput {
-  /** The collaboration context (null when collaboration is disabled). */
-  collab: CollaborationContextValue | null;
-  /** Current local active slide index. */
-  activeSlideIndex: number;
-  /** Setter for the active slide index. */
-  setActiveSlideIndex: (index: number) => void;
-  /** Total number of slides (for bounds checking). */
-  slideCount: number;
+  onFormatText?: (updates: Partial<TextStyle>) => void;
+  /** Called when table column widths are resized. */
+  onResizeTableColumns?: (elementId: string, newWidths: number[]) => void;
+  /** Called when a table row is resized. */
+  onResizeTableRow?: (elementId: string, rowIndex: number, newHeight: number) => void;
+  /** Find & Replace results (all matches across all slides). */
+  findResults?: Array<{
+    slideIndex: number;
+    elementId: string;
+    segmentIndex: number;
+    startOffset: number;
+    length: number;
+  }>;
+  /** Index of the currently focused find result (-1 for none). */
+  findResultIndex?: number;
+  /** Index of the currently visible slide (needed to filter find results). */
+  activeSlideIndex?: number;
+  /** Currently active drawing tool ("select" means no drawing overlay). */
+  activeTool?: DrawingTool;
+  /** Stroke colour for pen / highlighter. */
+  drawingColor?: string;
+  /** Stroke width for pen / highlighter. */
+  drawingWidth?: number;
+  /** Ref that is true while a pointer stroke is in progress. */
+  isDrawingRef?: React$1.RefObject<boolean>;
+  /** Called when a completed ink stroke should be added to the slide. */
+  onAddInkElement?: (ink: InkPptxElement) => void;
+  /** Called when a freeform drawing stroke should be added as a shape element. */
+  onAddFreeformShape?: (shape: ShapePptxElement) => void;
+  /** Called when the eraser tool removes an ink element. */
+  onEraseInkElement?: (elementId: string) => void;
+  /** Called when a shape-level action is clicked (e.g. slide jump, URL). */
+  onActionClick?: (elementId: string, action: PptxAction) => void;
+  /** Called when a text-level hyperlink is clicked. */
+  onHyperlinkClick?: (url: string) => void;
+  /** Comments for the current slide (used for on-canvas markers). */
+  comments?: PptxComment[];
+  /** Whether to show comment markers on the slide canvas. */
+  showCommentMarkers?: boolean;
+  /** Called when a comment marker is clicked. */
+  onCommentMarkerClick?: (commentId: string) => void;
+  onMoveGuide?: (guideId: string, position: number) => void;
+  onDeleteGuide?: (guideId: string) => void;
+  onCreateGuideFromRuler?: (axis: 'h' | 'v', positionPx: number) => void;
+  /** When true, shows connection sites on shapes and enables connector drawing. */
+  connectorCreationMode?: boolean;
+  /** Called when a new connector is created between two shapes. */
+  onCreateConnector?: (connector: ConnectorPptxElement) => void;
+  /** All slides in the presentation (for zoom element thumbnails). */
+  allSlides?: readonly PptxSlide[];
+  /** Callback fired when a zoom element is clicked in presentation mode. */
+  onZoomClick?: (targetSlideIndex: number, returnSlideIndex: number) => void;
+  /** Index of the current slide (for zoom return navigation). */
+  sourceSlideIndex?: number;
+  /** Context for text field placeholder substitution (slide number, header/footer, etc.). */
+  fieldContext?: FieldSubstitutionContext;
+  /** Theme + table style map for resolving table band/header colours. */
+  tableStyleContext?: TableStyleContext;
+  /** Optional collaboration cursor overlay rendered on top of the canvas. */
+  collaborationOverlay?: React$1.ReactNode;
   /**
-   * When true, auto-follow stands down (e.g. the local user is manually
-   * following a specific peer via the follow bar). Defaults to false.
+   * When true, the stage marks itself `data-pptx-ai-active` so element colour
+   * changes tween while the AI assistant is working (see AiFocusHighlightOverlay).
    */
-  paused?: boolean;
+  aiActive?: boolean;
 }
-declare function useBroadcastFollower({ collab, activeSlideIndex, setActiveSlideIndex, slideCount, paused }: UseBroadcastFollowerInput): void;
 //#endregion
-//#region src/viewer/hooks/collaboration/useFollowMode.d.ts
-interface UseFollowModeInput {
-  /** The collaboration context (null when collaboration is disabled). */
-  collab: CollaborationContextValue | null;
-  /** Current local active slide index. */
-  activeSlideIndex: number;
-  /** Setter for the active slide index. */
-  setActiveSlideIndex: (index: number) => void;
-  /** Total number of slides (for bounds checking). */
-  slideCount: number;
+//#region src/viewer/hooks/useAutosave.d.ts
+type AutosaveStatus = {
+  state: 'idle';
+} | {
+  state: 'disabled';
+  reason: string;
+} | {
+  state: 'saving';
+} | {
+  state: 'saved';
+  timestamp: number;
+} | {
+  state: 'error';
+  message: string;
+};
+interface UseAutosaveInput {
+  /** Whether the document has unsaved changes. */
+  isDirty: boolean;
+  /** File path or name of the currently-open PPTX. Required for autosave to work. */
+  filePath: string | undefined;
+  /** Serialise current editor state to a Uint8Array. */
+  serializeSlides: () => Promise<Uint8Array | null>;
+  /** Autosave interval in seconds (default 120). */
+  intervalSeconds?: number;
+  /** Whether autosave is enabled. */
+  enabled?: boolean;
 }
-interface UseFollowModeResult {
-  /** The clientId currently being followed, or null. */
-  followedClientId: number | null;
-  /** Follow the given peer, or `null` to stop following. */
-  followUser: (clientId: number | null) => void;
+interface UseAutosaveResult {
+  /** Current autosave status for display in the StatusBar. */
+  autosaveStatus: AutosaveStatus;
+  /** Manually trigger an autosave right now. */
+  triggerAutosave: () => Promise<void>;
 }
-declare function useFollowMode({ collab, activeSlideIndex, setActiveSlideIndex, slideCount }: UseFollowModeInput): UseFollowModeResult;
+declare function useAutosave(input: UseAutosaveInput): UseAutosaveResult;
 //#endregion
-//#region src/viewer/hooks/presentation-mode/useAnimationPlayback.d.ts
-interface UseAnimationPlaybackInput {
+//#region src/viewer/hooks/useViewerBuildingBlocks.d.ts
+interface UseViewerBuildingBlocksInput {
+  /** PPTX content as ArrayBuffer/Uint8Array, or null/undefined while no file is loaded. */
+  content: ArrayBuffer | Uint8Array | null | undefined;
+  /** Whether editing actions are enabled. Defaults to false (view-only). */
+  canEdit?: boolean;
+  /** Original file path, used for autosave recovery. */
+  filePath?: string;
+  /** Display name for the toolbar's file-name-aware controls (e.g. title bar hosts build themselves). */
+  fileName?: string;
+  /** Whether the built-in autosave-to-localStorage recovery timer is active. Defaults to true. */
+  autosaveEnabled?: boolean;
+  /** Display name used as the author for comments. */
+  userName?: string;
+  /** Host-supplied list of toolbar buttons/ribbon tabs to hide. */
+  hiddenActions?: readonly ToolbarActionId[];
+  /** Imperative handle ref, exposing the same `PowerPointViewerHandle` API `PowerPointViewer` does. */
+  handle?: React.ForwardedRef<PowerPointViewerHandle>;
+  onContentChange?: (content: Uint8Array) => void;
+  onDirtyChange?: (dirty: boolean) => void;
+  onActiveSlideChange?: (index: number) => void;
+  onModeChange?: (mode: ViewerMode) => void;
+  onZoomChange?: (zoom: number) => void;
+  onSelectionChange?: (ids: string[]) => void;
+  onSlideCountChange?: (count: number) => void;
+  /** Fired by the toolbar's "Settings" button; the host owns rendering that dialog. */
+  onOpenSettings?: () => void;
+  /** Fired by the toolbar's "Header & Footer" button; the host owns rendering that panel. */
+  onOpenHeaderFooter?: () => void;
+  /** Fired by the toolbar's "Share" button; the host owns rendering that dialog. */
+  onOpenShareDialog?: () => void;
+}
+interface ViewerBuildingBlocksResult {
+  /** Flat, self-contained props for the standalone `<Toolbar>` component. */
+  toolbarProps: ToolbarProps;
+  /** Flat, self-contained props for the standalone `<SlideCanvas>` component. */
+  canvasProps: SlideCanvasProps;
+  /** Current viewer mode (edit, view, present, master). */
+  mode: ViewerMode;
+  /** True while the initial parse of `content` is in progress. */
+  loading: boolean;
+  /** Parse error message, or null. */
+  error: string | null;
+  /** Current autosave-to-localStorage recovery status. */
+  autosaveStatus: AutosaveStatus;
+}
+declare function useViewerBuildingBlocks(input: UseViewerBuildingBlocksInput): ViewerBuildingBlocksResult;
+
+//#region src/viewer/hooks/presentation-mode/types.d.ts
+/**
+ * How a forward/backward slide advance was requested.
+ *
+ * - `'click'`: a click/tap on the slide surface (PowerPoint's "On Mouse Click"
+ *   advance). This is the only trigger governed by `advanceOnClick`.
+ * - `'explicit'`: keyboard, navigation buttons, action triggers, and timed
+ *   auto-advance. These always navigate regardless of `advanceOnClick`, matching
+ *   PowerPoint (arrow keys / Next always work even when click-advance is off).
+ */
+type SlideAdvanceTrigger = 'click' | 'explicit';
+/**
+ * State describing the transition overlay that plays while advancing into a
+ * slide that carries a `p:transition`. The outgoing slide is snapshotted into
+ * an animated overlay layer while the incoming slide renders underneath on the
+ * main stage; the overlay tears down once `durationMs` elapses.
+ */
+interface PresentationTransitionOverlayState {
+  /** Index of the leaving slide, rendered (animated) in the overlay layer. */
+  outgoingSlideIndex: number;
+  /** Index of the arriving slide, already live on the main stage. */
+  incomingSlideIndex: number;
+  /** The incoming slide's transition definition (drives the CSS animation). */
+  transition: PptxSlideTransition;
+  /** Resolved transition duration (ms). */
+  durationMs: number;
+}
+interface UsePresentationModeInput {
+  mode: ViewerMode;
   slides: PptxSlide[];
-  onPlayActionSound?: (soundPath: string) => void;
-  /** When false, all animations are skipped (elements shown immediately). */
+  visibleSlideIndexes: number[];
+  activeSlideIndex: number;
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Raw PPTX bytes: forwarded to audience window for content sharing. */
+  content?: ArrayBuffer | Uint8Array | null;
+  onSetMode: (mode: ViewerMode) => void;
+  onSetActiveSlideIndex: (index: number) => void;
+  /**
+   * Play a sound file for an action/transition. When `options.loop` is true the
+   * audio repeats until the next animation sound plays or the show exits
+   * (used for transition sounds flagged with `soundLoop`).
+   */
+  onPlayActionSound?: (soundPath: string, options?: {
+    loop?: boolean;
+  }) => void;
+  /** Called when L key is pressed during presentation. */
+  onToggleLaser?: () => void;
+  /** Called when P key is pressed during presentation. */
+  onTogglePen?: () => void;
+  /** Called when E key is pressed during presentation. */
+  onToggleEraser?: () => void;
+  /** Called when Ctrl+M is pressed during presentation. */
+  onToggleToolbar?: () => void;
+  /** Called to persist rehearsal timings into slide transitions. */
+  onSaveRehearsalTimings?: (timings: Record<number, number>) => void;
+  /** Whether to loop continuously (kiosk or explicit loop setting). */
+  loopContinuously?: boolean;
+  /** Whether to play animations during the slide show (false = skip all animations). */
   showWithAnimation?: boolean;
+  /** Whether to use rehearsed auto-advance timings (false = manual advance only). */
+  useTimings?: boolean;
+  /**
+   * Options > Advanced > "End with black slide". When true (PowerPoint's
+   * default), advancing past the last slide shows a black end-of-show
+   * screen; the next advance (or a click on it) exits. When false,
+   * advancing past the last slide exits the show directly.
+   */
+  endWithBlackSlide?: boolean;
 }
-interface UseAnimationPlaybackResult {
+interface UsePresentationModeResult {
+  presentationSlideIndex: number;
+  setPresentationSlideIndex: (index: number) => void;
+  presentationSlideVisible: boolean;
+  /** Active slide-transition overlay, or `null` when no transition is playing. */
+  transitionOverlay: PresentationTransitionOverlayState | null;
+  /** Tear down the transition overlay once its animation completes. */
+  handleTransitionOverlayComplete: () => void;
   presentationAnimations: PresentationAnimationRuntime[];
   presentationElementStates: Map<string, ElementAnimationState>;
   presentationKeyframesCss: string;
-  interactiveTriggerShapeIds: ReadonlySet<string>;
-  hoverTriggerShapeIds: ReadonlySet<string>;
   clearPresentationTimers: () => void;
-  playNextAnimationGroup: () => boolean;
+  runPresentationEntranceAnimations: (slideIndex: number) => void;
+  /** True while the black "End of slide show" screen is displayed. */
+  endOfShowVisible: boolean;
+  movePresentationSlide: (direction: 1 | -1, trigger?: SlideAdvanceTrigger) => void;
+  navigateToSlide: (slideIndex: number) => void;
+  handlePresentationAction: (action: PptxAction) => void;
+  /**
+   * Handle a shape click in presentation mode. If the shape is an interactive
+   * trigger, play its animation sequence. Returns `true` if handled.
+   */
   handleInteractiveShapeClick: (shapeId: string) => boolean;
+  /** Set of shape IDs that are interactive sequence triggers on the current slide. */
+  interactiveTriggerShapeIds: ReadonlySet<string>;
+  /** Set of shape IDs that are hover animation triggers on the current slide. */
+  hoverTriggerShapeIds: ReadonlySet<string>;
+  /** Handle hover start on a shape. If the shape has a hover sequence, play it. Returns `true` if handled. */
   handleHoverStart: (shapeId: string) => boolean;
+  /** Handle hover end on a shape. Resets the hover sequence for replay. */
   handleHoverEnd: (shapeId: string) => void;
-  runPresentationEntranceAnimations: (slideIndex: number) => void;
-  /** Exposed so the orchestrator can schedule additional timers (e.g. auto-advance). */
-  presentationTimersRef: React.RefObject<number[]>;
-}
-declare function useAnimationPlayback(input: UseAnimationPlaybackInput): UseAnimationPlaybackResult;
-//#endregion
-//#region src/viewer/hooks/presentation-mode/useRehearsalTimings.d.ts
-interface UseRehearsalTimingsInput {
-  containerRef: React.RefObject<HTMLElement | null>;
-  onSetMode: (mode: ViewerMode) => void;
-  onSaveRehearsalTimings?: (timings: Record<number, number>) => void;
-  setPresentationStartTime: (time: number | null) => void;
-  setPresenterMode: (mode: boolean) => void;
-}
-interface UseRehearsalTimingsResult {
+  /** Must be called from a user-gesture handler (click) to satisfy browser fullscreen policy. */
+  enterPresentMode: () => void;
+  /** Whether presenter view (split-screen with notes) is active instead of fullscreen. */
+  presenterMode: boolean;
+  /** Enter presenter view mode (no fullscreen, shows notes panel). */
+  enterPresenterView: () => void;
+  /** Toggle between fullscreen and presenter view during presentation. */
+  togglePresenterView: () => void;
+  /** Timestamp (ms) when the presentation started: used for elapsed timer. */
+  presentationStartTime: number | null;
+  /** Whether the current presentation session is in rehearse-timings mode. */
   rehearsing: boolean;
-  setRehearsing: React.Dispatch<React.SetStateAction<boolean>>;
+  /** Enter rehearse-timings mode (fullscreen presentation + timing HUD). */
+  enterRehearsalMode: () => void;
+  /** Recorded timings in ms, keyed by slide index. Populated during rehearsal. */
   recordedTimings: Record<number, number>;
+  /** Timestamp when the current slide started (ms since epoch). */
   slideStartTime: number | null;
+  /** Whether the rehearsal summary dialog should be shown. */
   showRehearsalSummary: boolean;
-  setShowRehearsalSummary: React.Dispatch<React.SetStateAction<boolean>>;
-  rehearsalPaused: boolean;
-  recordCurrentSlideTime: (slideIndex: number) => void;
+  /** Dismiss the rehearsal summary (discard timings). */
   dismissRehearsalSummary: () => void;
+  /** Save recorded timings into each slide's transition.advanceAfterMs. */
   saveRehearsalTimings: () => void;
-  enterRehearsalMode: () => void;
+  /** Whether rehearsal timer is paused. */
+  rehearsalPaused: boolean;
+  /** Toggle the rehearsal timer pause state. */
   toggleRehearsalPause: () => void;
+  /** Handle a zoom element click in presentation mode. */
+  handleZoomClick: (targetSlideIndex: number, returnSlideIndex: number) => void;
+  /** Ref holding the slide index to return to after zoom navigation. */
+  zoomReturnSlideIndex: React.RefObject<number | null>;
+  /** Navigate back to the zoom summary slide. Returns true if navigation occurred. */
+  returnToZoomSlide: () => boolean;
+  /** Clear the stored zoom return index. */
+  clearZoomReturn: () => void;
+  /** Open the audience display in a separate browser window. Returns `true` if successful. */
+  openAudienceWindow: () => boolean;
+  /** Close the audience display window. */
+  closeAudienceWindow: () => void;
+  /** Whether the audience window is currently open. */
+  isAudienceWindowOpen: () => boolean;
+  /** Send a slide index to the audience window explicitly. */
+  syncSlideToAudience: (slideIndex: number) => void;
+  syncStateToAudience: (snapshot: PresentationSnapshot) => void;
+  presenterSnapshot: PresentationSnapshot;
+  setPresenterBlackout: (blackout: PresentationSnapshot['blackout']) => void;
+  togglePresenterTimer: () => void;
+  resetPresenterTimer: () => void;
+  stepPresenterZoom: (direction: 1 | -1) => void;
+  resetPresenterZoom: () => void;
+  setPresenterCaption: (caption: string) => void;
+  setPresenterSubtitlesVisible: (visible: boolean) => void;
+  updatePresenterSnapshot: (patch: Partial<PresentationSnapshot>) => void;
+  swapPresenterDisplays: () => Promise<boolean>;
 }
-declare function useRehearsalTimings(input: UseRehearsalTimingsInput): UseRehearsalTimingsResult;
 //#endregion
-//#region src/viewer/hooks/presentation-mode/usePresentationKeyboard.d.ts
-interface UsePresentationKeyboardInput {
-  mode: ViewerMode;
-  movePresentationSlide: (direction: 1 | -1) => void;
-  onSetMode: (mode: ViewerMode) => void;
-  onToggleLaser?: () => void;
-  onTogglePen?: () => void;
-  onToggleEraser?: () => void;
-  onToggleToolbar?: () => void;
-  /** Toggle between presenter view (split-screen with notes) and fullscreen. */
-  onTogglePresenterView?: () => void;
-  onToggleBlackScreen?: () => void;
-  onToggleWhiteScreen?: () => void;
-  rehearsing: boolean;
-  recordCurrentSlideTime: (slideIndex: number) => void;
-  presentationSlideIndex: number;
-  setShowRehearsalSummary: (value: boolean) => void;
+//#region src/viewer/hooks/useThemeSwitching.d.ts
+interface UseThemeSwitchingInput {
+  /** Ref to the PptxHandler instance. */
+  handlerRef: RefObject<PptxHandler | null>;
+  /** Current parsed presentation data (null when nothing is loaded). */
+  data: PptxData | null;
+  /** Callback to update the presentation data after theme switch. */
+  onDataChange: (newData: PptxData) => void;
+  /** Optional callback fired when theme switch completes successfully. */
+  onThemeChanged?: (preset: PptxThemePreset) => void;
+}
+interface ThemeSwitchingResult {
+  /** All available built-in theme presets. */
+  presets: readonly PptxThemePreset[];
+  /**
+   * Apply a theme preset to the current presentation.
+   * Updates both the in-memory ZIP and all resolved element colours.
+   */
+  switchToPreset: (preset: PptxThemePreset) => Promise<void>;
+  /**
+   * Apply a custom colour scheme (and optional font scheme) to the
+   * current presentation.
+   */
+  switchToCustom: (colorScheme: PptxThemeColorScheme, fontScheme?: PptxThemeFontScheme, themeName?: string) => Promise<void>;
+  /**
+   * Get the preset matching the current presentation theme (if any).
+   * Returns undefined if the current theme does not match a built-in preset.
+   */
+  currentPreset: PptxThemePreset | undefined;
+}
+/**
+ * React hook providing theme switching capabilities for the PowerPoint viewer.
+ *
+ * @example
+ * ```tsx
+ * const { presets, switchToPreset, currentPreset } = useThemeSwitching({
+ *   handlerRef,
+ *   data,
+ *   onDataChange: setData,
+ * });
+ *
+ * return (
+ *   <div>
+ *     {presets.map(preset => (
+ *       <button
+ *         key={preset.id}
+ *         onClick={() => switchToPreset(preset)}
+ *         aria-pressed={preset.id === currentPreset?.id}
+ *       >
+ *         {preset.name}
+ *       </button>
+ *     ))}
+ *   </div>
+ * );
+ * ```
+ */
+declare function useThemeSwitching(input: UseThemeSwitchingInput): ThemeSwitchingResult;
+//#endregion
+//#region ../../node_modules/.bun/lib0@0.2.117/node_modules/lib0/observable.d.ts
+/**
+ * Handles named events.
+ *
+ * @deprecated
+ * @template N
+ */
+declare class Observable<N> {
+  /**
+   * Some desc.
+   * @type {Map<N, any>}
+   */
+  _observers: Map<N, any>;
+  /**
+   * @param {N} name
+   * @param {function} f
+   */
+  on(name: N, f: Function): void;
+  /**
+   * @param {N} name
+   * @param {function} f
+   */
+  once(name: N, f: Function): void;
+  /**
+   * @param {N} name
+   * @param {function} f
+   */
+  off(name: N, f: Function): void;
+  /**
+   * Emit a named event. All registered event listeners that listen to the
+   * specified name will receive the event.
+   *
+   * @todo This should catch exceptions
+   *
+   * @param {N} name The event name.
+   * @param {Array<any>} args The arguments that are applied to the event listener.
+   */
+  emit(name: N, args: Array<any>): void;
+  destroy(): void;
+}
+//#endregion
+//#region ../../node_modules/.bun/y-protocols@1.0.7+253afa400b9c0a30/node_modules/y-protocols/awareness.d.ts
+/**
+ * @typedef {Object} MetaClientState
+ * @property {number} MetaClientState.clock
+ * @property {number} MetaClientState.lastUpdated unix timestamp
+ */
+/**
+ * The Awareness class implements a simple shared state protocol that can be used for non-persistent data like awareness information
+ * (cursor, username, status, ..). Each client can update its own local state and listen to state changes of
+ * remote clients. Every client may set a state of a remote peer to `null` to mark the client as offline.
+ *
+ * Each client is identified by a unique client id (something we borrow from `doc.clientID`). A client can override
+ * its own state by propagating a message with an increasing timestamp (`clock`). If such a message is received, it is
+ * applied if the known state of that client is older than the new state (`clock < newClock`). If a client thinks that
+ * a remote client is offline, it may propagate a message with
+ * `{ clock: currentClientClock, state: null, client: remoteClient }`. If such a
+ * message is received, and the known clock of that client equals the received clock, it will override the state with `null`.
+ *
+ * Before a client disconnects, it should propagate a `null` state with an updated clock.
+ *
+ * Awareness states must be updated every 30 seconds. Otherwise the Awareness instance will delete the client state.
+ *
+ * @extends {Observable<string>}
+ */
+declare class Awareness extends Observable<string> {
+  /**
+   * @param {Y.Doc} doc
+   */
+  constructor(doc: Y.Doc);
+  doc: Y.Doc;
+  /**
+   * @type {number}
+   */
+  clientID: number;
+  /**
+   * Maps from client id to client state
+   * @type {Map<number, Object<string, any>>}
+   */
+  states: Map<number, {
+    [x: string]: any;
+  }>;
+  /**
+   * @type {Map<number, MetaClientState>}
+   */
+  meta: Map<number, MetaClientState>;
+  _checkInterval: any;
+  /**
+   * @return {Object<string,any>|null}
+   */
+  getLocalState(): {
+    [x: string]: any;
+  } | null;
+  /**
+   * @param {Object<string,any>|null} state
+   */
+  setLocalState(state: {
+    [x: string]: any;
+  } | null): void;
+  /**
+   * @param {string} field
+   * @param {any} value
+   */
+  setLocalStateField(field: string, value: any): void;
+  /**
+   * @return {Map<number,Object<string,any>>}
+   */
+  getStates(): Map<number, {
+    [x: string]: any;
+  }>;
 }
-/**
- * Registers keyboard shortcuts for presentation mode: arrow/space
- * for slide navigation, Escape to exit, and annotation tool toggles.
- */
-declare function usePresentationKeyboard(input: UsePresentationKeyboardInput): void;
+type MetaClientState = {
+  clock: number;
+  /**
+   * unix timestamp
+   */
+  lastUpdated: number;
+};
 //#endregion
-//#region src/viewer/hooks/presentation-mode/useSlideNavigation.d.ts
-interface UseSlideNavigationInput {
-  slides: PptxSlide[];
-  visibleSlideIndexes: number[];
-  presentationSlideIndex: number;
-  setPresentationSlideIndex: (index: number) => void;
-  setPresentationSlideVisible: (visible: boolean) => void;
-  setTransitionOverlay: (state: PresentationTransitionOverlayState | null) => void;
-  onSetMode: (mode: ViewerMode) => void;
-  onSetActiveSlideIndex: (index: number) => void;
-  onPlayActionSound?: (soundPath: string) => void;
-  loopContinuously?: boolean;
-  /** Whether to use rehearsed auto-advance timings. When false, slides advance only on click. */
-  useTimings?: boolean;
+//#region src/viewer/hooks/collaboration/useYjsProvider.d.ts
+interface UseYjsProviderInput {
   /**
-   * Fired when the user advances past the last slide (no loop, no rehearsal).
-   * The presentation-mode hook uses it for PowerPoint's "End with black
-   * slide" behavior. When absent, advancing past the end clamps as before.
+   * Collaboration config, or `undefined` when collaboration is inactive. The
+   * hook is always called (React hook rules) but stays fully dormant, never
+   * opening a transport, while config is absent.
    */
-  onAdvancePastLastSlide?: () => void;
-  playNextAnimationGroup: () => boolean;
-  clearPresentationTimers: () => void;
-  runPresentationEntranceAnimations: (slideIndex: number) => void;
-  presentationTimersRef: {
-    current: number[];
-  };
-  rehearsing: boolean;
-  recordCurrentSlideTime: (slideIndex: number) => void;
-  setShowRehearsalSummary: (value: boolean) => void;
-}
-interface UseSlideNavigationResult {
-  movePresentationSlide: (direction: 1 | -1, trigger?: SlideAdvanceTrigger) => void;
-  navigateToSlide: (slideIndex: number) => void;
-  handlePresentationAction: (action: PptxAction) => void;
-  scheduleAutoAdvanceForSlide: (slideIndex: number) => void;
-}
-declare function useSlideNavigation(input: UseSlideNavigationInput): UseSlideNavigationResult;
-interface UsePresenterWindowInput {
-  currentSlideIndex: number;
-  isPresenterMode: boolean;
-  /** Raw PPTX bytes to share with the audience tab via IndexedDB. */
-  content?: ArrayBuffer | Uint8Array | null;
-  snapshot: PresentationSnapshot;
-}
-interface UsePresenterWindowResult {
-  openAudienceWindow: () => boolean;
-  closeAudienceWindow: () => void;
-  isAudienceWindowOpen: () => boolean;
-  syncSlideToAudience: (slideIndex: number) => void;
-  syncStateToAudience: (snapshot: PresentationSnapshot) => void;
-  swapDisplays: () => Promise<boolean>;
+  config?: CollaborationConfig;
 }
-declare function usePresenterWindow(input: UsePresenterWindowInput): UsePresenterWindowResult;
-//#endregion
-//#region src/viewer/hooks/presentation-mode/useAudienceMode.d.ts
-interface UseAudienceModeInput {
-  mode: ViewerMode;
-  onSetMode: (mode: ViewerMode) => void;
-  onSetActiveSlideIndex: (index: number) => void;
-  containerRef: React.RefObject<HTMLElement | null>;
-  onSnapshot?: (snapshot: PresentationSnapshot) => void;
+interface UseYjsProviderResult {
+  /** Current WebSocket connection status. */
+  status: ConnectionStatus;
+  /** The Yjs awareness instance (null until connected). */
+  awareness: Awareness | null;
+  /** The Yjs document (null until initialised). */
+  doc: Doc | null;
+  /** Local awareness client ID. */
+  clientId: number | null;
+  /**
+   * Whether the provider completed its initial document sync. Local doc
+   * writes should be gated on this so a late joiner never seeds its
+   * bootstrap deck into a room whose content has not arrived yet. Websocket
+   * flips it on the provider's 'synced' event; webrtc flips it on peer sync
+   * or after {@link INITIAL_SYNC_GRACE_MS} (a lone fresh-room peer never
+   * receives a sync event).
+   */
+  synced: boolean;
+  /** Manually retry the connection after a timeout or error. */
+  retry: () => void;
 }
 /**
- * When the page was opened with the `#pptx-audience` hash, this hook:
- * 1. Auto-enters fullscreen presentation mode after content loads
- * 2. Listens on BroadcastChannel for slide-change messages from the presenter
- * 3. Exits presentation mode when the presenter sends an exit signal
+ * Lazily loads `yjs` and `y-websocket`, creates a Y.Doc and
+ * WebSocketProvider, and tracks the connection lifecycle.
+ *
+ * If the connection does not succeed within {@link CONNECTION_TIMEOUT_MS},
+ * the provider is torn down and status moves to `'error'`. The consumer
+ * can call `retry()` to attempt a fresh connection.
+ *
+ * The Yjs packages are dynamically imported so they are fully
+ * tree-shaken when collaboration is not enabled.
  */
-declare function useAudienceMode(input: UseAudienceModeInput): void;
-
-//#region src/viewer/hooks/useAutosave.d.ts
-type AutosaveStatus = {
-  state: 'idle';
-} | {
-  state: 'disabled';
-  reason: string;
-} | {
-  state: 'saving';
-} | {
-  state: 'saved';
-  timestamp: number;
-} | {
-  state: 'error';
-  message: string;
-};
-interface UseAutosaveInput {
-  /** Whether the document has unsaved changes. */
-  isDirty: boolean;
-  /** File path or name of the currently-open PPTX. Required for autosave to work. */
-  filePath: string | undefined;
-  /** Serialise current editor state to a Uint8Array. */
-  serializeSlides: () => Promise<Uint8Array | null>;
-  /** Autosave interval in seconds (default 120). */
-  intervalSeconds?: number;
-  /** Whether autosave is enabled. */
-  enabled?: boolean;
-}
-interface UseAutosaveResult {
-  /** Current autosave status for display in the StatusBar. */
-  autosaveStatus: AutosaveStatus;
-  /** Manually trigger an autosave right now. */
-  triggerAutosave: () => Promise<void>;
-}
-declare function useAutosave(input: UseAutosaveInput): UseAutosaveResult;
-//#endregion
-//#region src/viewer/utils/table-band-style.d.ts
-/** Context for resolving table style colours from the theme. */
-interface TableStyleContext {
-  tableStyleMap?: ParsedTableStyleMap;
-  theme?: PptxTheme;
-}
+declare function useYjsProvider({ config }: UseYjsProviderInput): UseYjsProviderResult;
 //#endregion
-//#region src/viewer/components/canvas/canvas-types.d.ts
-interface ZoomViewport {
-  canvasViewportRef: React$1.RefObject<HTMLDivElement | null>;
-  editWrapperRef: React$1.RefObject<HTMLDivElement | null>;
-  canvasStageRef: React$1.RefObject<HTMLDivElement | null>;
-  editorScale: number;
+//#region src/viewer/hooks/collaboration/usePresenceTracking.d.ts
+interface UsePresenceTrackingInput {
+  awareness: Awareness | null;
+  localClientId: number | null;
+  userName: string;
+  userColor: string;
+  userAvatar?: string;
+  /** Role in the session (broadcaster, viewer, or collaborator). */
+  role?: string;
+  canvasWidth: number;
+  canvasHeight: number;
 }
-interface SlideCanvasProps {
-  activeSlide: PptxSlide | undefined;
-  templateElements: PptxElement[];
-  canvasSize: CanvasSize;
-  zoom: ZoomViewport;
-  mode: ViewerMode;
-  canEdit: boolean;
-  editTemplateMode: boolean;
-  selectedElementIdSet: Set<string>;
-  selectedElement: PptxElement | null;
-  inlineEditingElementId: string | null;
-  inlineEditingText: string;
-  spellCheckEnabled: boolean;
-  mediaDataUrls: Map<string, string>;
-  tableEditorState: TableCellEditorState | null;
-  marqueeSelectionState: MarqueeSelectionState | null;
-  snapLines: Array<{
-    axis: string;
-    position: number;
-  }>;
-  showGrid: boolean;
-  /** Grid spacing in CSS px (derived from PPTX gridSpacing EMUs). */
-  gridSpacingPx?: number;
-  showRulers: boolean;
-  /** Unit system for rulers (default: inches). */
-  rulerUnit?: RulerUnit;
-  guides: Array<{
-    id: string;
-    axis: 'h' | 'v';
-    position: number;
-  }>;
-  presentationElementStates?: Map<string, ElementAnimationState>;
-  presentationKeyframesCss?: string;
-  onClick: (elementId: string, e: React$1.MouseEvent) => void;
-  onDoubleClick: (elementId: string, e: React$1.MouseEvent) => void;
-  onMouseDown: (elementId: string, e: React$1.MouseEvent) => void;
-  onContextMenu: (elementId: string, e: React$1.MouseEvent) => void;
-  /** Called when the user presses mouse down on empty canvas space. */
-  onCanvasMouseDown?: (e: React$1.MouseEvent) => void;
-  onResizePointerDown: (elementId: string, e: React$1.MouseEvent, handle: string) => void;
-  onAdjustmentPointerDown: (elementId: string, e: React$1.MouseEvent) => void;
-  /** Commit a new rotation (degrees) when the on-canvas rotate handle is dragged. */
-  onRotate?: (elementId: string, rotationDeg: number) => void;
-  onInlineEditChange: (text: string) => void;
-  onInlineEditCommit: () => void;
-  onInlineEditCancel: () => void;
-  onTableCellSelect: (cell: Omit<TableCellEditorState, 'elementId'> | null, elementId: string) => void;
-  /** Called when an edited table cell should be committed. */
-  onCommitCellEdit?: (elementId: string, rowIndex: number, colIndex: number, text: string) => void;
-  /**
-   * Commit a partial update to a SmartArt element from inline (on-canvas) node
-   * editing. Routed to the same element-update path the inspector uses (undo/redo
-   * + dirty marking). When absent, inline SmartArt editing is disabled.
-   */
-  onUpdateSmartArtElement?: (elementId: string, updates: Partial<PptxElement>) => void;
+interface UsePresenceTrackingResult {
+  /** Presence data for all remote users (excludes local). */
+  remoteUsers: UserPresence[];
+  /** Broadcast a partial presence update for the local user. */
+  broadcastPresence: (update: Partial<Omit<UserPresence, 'clientId'>>) => void;
+}
+declare function usePresenceTracking({ awareness, localClientId, userName, userColor, userAvatar, role, canvasWidth, canvasHeight }: UsePresenceTrackingInput): UsePresenceTrackingResult;
+//#endregion
+//#region src/viewer/hooks/collaboration/useCollaborativeState.d.ts
+interface UseCollaborativeStateInput {
   /**
-   * Apply a text-style toggle (Ctrl/Cmd+B/I/U) to the element being
-   * inline-edited. Routed to the same updateSelectedTextStyle path as the
-   * toolbar. When absent, the inline formatting shortcuts are inert.
+   * Collaboration config, or `undefined` when collaboration is inactive. The
+   * hook is always called so the surrounding provider keeps a stable React
+   * tree shape; it produces a dormant value (no transport, empty presence)
+   * while config is absent.
    */
-  onFormatText?: (updates: Partial<TextStyle>) => void;
-  /** Called when table column widths are resized. */
-  onResizeTableColumns?: (elementId: string, newWidths: number[]) => void;
-  /** Called when a table row is resized. */
-  onResizeTableRow?: (elementId: string, rowIndex: number, newHeight: number) => void;
-  /** Find & Replace results (all matches across all slides). */
-  findResults?: Array<{
-    slideIndex: number;
-    elementId: string;
-    segmentIndex: number;
-    startOffset: number;
-    length: number;
-  }>;
-  /** Index of the currently focused find result (-1 for none). */
-  findResultIndex?: number;
-  /** Index of the currently visible slide (needed to filter find results). */
-  activeSlideIndex?: number;
-  /** Currently active drawing tool ("select" means no drawing overlay). */
-  activeTool?: DrawingTool;
-  /** Stroke colour for pen / highlighter. */
-  drawingColor?: string;
-  /** Stroke width for pen / highlighter. */
-  drawingWidth?: number;
-  /** Ref that is true while a pointer stroke is in progress. */
-  isDrawingRef?: React$1.RefObject<boolean>;
-  /** Called when a completed ink stroke should be added to the slide. */
-  onAddInkElement?: (ink: InkPptxElement) => void;
-  /** Called when a freeform drawing stroke should be added as a shape element. */
-  onAddFreeformShape?: (shape: ShapePptxElement) => void;
-  /** Called when the eraser tool removes an ink element. */
-  onEraseInkElement?: (elementId: string) => void;
-  /** Called when a shape-level action is clicked (e.g. slide jump, URL). */
-  onActionClick?: (elementId: string, action: PptxAction) => void;
-  /** Called when a text-level hyperlink is clicked. */
-  onHyperlinkClick?: (url: string) => void;
-  /** Comments for the current slide (used for on-canvas markers). */
-  comments?: PptxComment[];
-  /** Whether to show comment markers on the slide canvas. */
-  showCommentMarkers?: boolean;
-  /** Called when a comment marker is clicked. */
-  onCommentMarkerClick?: (commentId: string) => void;
-  onMoveGuide?: (guideId: string, position: number) => void;
-  onDeleteGuide?: (guideId: string) => void;
-  onCreateGuideFromRuler?: (axis: 'h' | 'v', positionPx: number) => void;
-  /** When true, shows connection sites on shapes and enables connector drawing. */
-  connectorCreationMode?: boolean;
-  /** Called when a new connector is created between two shapes. */
-  onCreateConnector?: (connector: ConnectorPptxElement) => void;
-  /** All slides in the presentation (for zoom element thumbnails). */
-  allSlides?: readonly PptxSlide[];
-  /** Callback fired when a zoom element is clicked in presentation mode. */
-  onZoomClick?: (targetSlideIndex: number, returnSlideIndex: number) => void;
-  /** Index of the current slide (for zoom return navigation). */
-  sourceSlideIndex?: number;
-  /** Context for text field placeholder substitution (slide number, header/footer, etc.). */
-  fieldContext?: FieldSubstitutionContext;
-  /** Theme + table style map for resolving table band/header colours. */
-  tableStyleContext?: TableStyleContext;
-  /** Optional collaboration cursor overlay rendered on top of the canvas. */
-  collaborationOverlay?: React$1.ReactNode;
+  config?: CollaborationConfig;
+  canvasWidth: number;
+  canvasHeight: number;
 }
+declare function useCollaborativeState({ config, canvasWidth, canvasHeight }: UseCollaborativeStateInput): CollaborationContextValue | null;
 //#endregion
-//#region src/viewer/components/toolbar/toolbar-types.d.ts
-interface ToolbarProps {
-  fileName?: string;
-  mode: ViewerMode;
-  canEdit: boolean;
-  isNarrowViewport: boolean;
-  isSidebarCollapsed: boolean;
-  isInspectorPaneOpen: boolean;
-  isCompactToolbarOpen: boolean;
-  toolbarSection: ToolbarSection;
-  scale: number;
+//#region src/viewer/hooks/collaboration/useCollaborativeHistory.d.ts
+interface UseCollaborativeHistoryInput {
+  /** The local user's client ID (from Yjs awareness). */
+  localClientId: number | null;
+  /** Standard history undo function. */
+  handleUndo: () => void;
+  /** Standard history redo function. */
+  handleRedo: () => void;
+  /** Whether undo is available. */
   canUndo: boolean;
+  /** Whether redo is available. */
   canRedo: boolean;
-  undoLabel: string | undefined;
-  redoLabel: string | undefined;
-  findReplaceOpen: boolean;
-  selectedElement: PptxElement | null;
-  tableEditorState?: TableCellEditorState | null;
-  editTemplateMode: boolean;
-  newShapeType: SupportedShapeType;
-  activeTool: DrawingTool;
-  drawingColor: string;
-  drawingWidth: number;
-  clipboardPayload: ElementClipboardPayload | null;
-  onSetMode: (mode: ViewerMode) => void;
-  onToggleSidebar: () => void;
-  onToggleInspector: () => void;
-  /** Opens the inspector pane and switches to the properties tab (for animation panel). */
-  onOpenAnimationPanel: () => void;
-  /** Adds an animation preset to the selected element. */
-  onAddAnimation?: (preset: string, group: 'entrance' | 'emphasis' | 'exit') => void;
-  /** Removes all animations from the selected element. */
-  onRemoveAnimation?: () => void;
-  onToggleCompactToolbar: () => void;
-  onSetToolbarSection: (section: ToolbarSection) => void;
-  onZoomIn: () => void;
-  onZoomOut: () => void;
-  onZoomToFit: () => void;
-  onUndo: () => void;
-  onRedo: () => void;
-  onToggleFindReplace: () => void;
-  onSetNewShapeType: (type: SupportedShapeType) => void;
-  onAddTextBox: () => void;
-  onAddShape: () => void;
-  onAddTable: () => void;
-  onAddChart?: (chartType: PptxChartType) => void;
-  onAddSmartArt: () => void;
-  onAddEquation: () => void;
-  onAddActionButton: (shapeType: string) => void;
-  onInsertField?: (fieldType: string, value?: string) => void;
-  onOpenHeaderFooter?: () => void;
-  onOpenImagePicker: () => void;
-  onOpenMediaPicker: () => void;
-  onSetActiveTool: (tool: DrawingTool) => void;
-  onSetDrawingColor: (color: string) => void;
-  onSetDrawingWidth: (width: number) => void;
-  onSetEditTemplateMode: (mode: boolean) => void;
-  spellCheckEnabled: boolean;
-  showGrid: boolean;
-  showRulers: boolean;
-  snapToGrid: boolean;
-  snapToShape: boolean;
-  onSetSpellCheckEnabled: (enabled: boolean) => void;
-  onSetShowGrid: (enabled: boolean) => void;
-  onSetShowRulers: (enabled: boolean) => void;
-  onSetSnapToGrid: (enabled: boolean) => void;
-  onSetSnapToShape: (enabled: boolean) => void;
-  onAddGuide: (axis: 'h' | 'v') => void;
-  onAlignElements: (align: string) => void;
-  onDistributeElements: (axis: string) => void;
-  canDistribute: boolean;
-  onCopy: () => void;
-  onCut: () => void;
-  onPaste: () => void;
-  onFlip: (direction: 'horizontal' | 'vertical') => void;
-  onMoveLayer: (direction: string) => void;
-  onMoveLayerToEdge: (direction: string) => void;
-  onDuplicate: () => void;
-  onDelete: () => void;
-  /** Open another presentation (File ▸ Open). Hidden when not provided. */
-  onOpenFile?: () => void;
-  onOpenRecentFile?: (key: string) => void;
-  onCreatePresentation: (templateId: string) => void;
-  onExportPng: () => void;
-  onExportPdf: () => void;
-  onExportVideo: () => void;
-  onExportGif: () => void;
-  onPackageForSharing: () => void;
-  onOpenShareDialog?: () => void;
-  onSaveAsPptx: () => void;
-  onSaveAsPpsx: () => void;
-  onSaveAsPptm: () => void;
-  hasMacros: boolean;
-  onCopySlideAsImage: () => void;
-  onPrint: () => void;
-  onToggleShortcuts: () => void;
-  onOpenSettings?: () => void;
-  onRunAccessibilityCheck: () => void;
-  onToggleSlideSorter: () => void;
-  onUpdateTextStyle: (updates: Partial<TextStyle>) => void;
-  /** Rewrite the selected text's characters (PowerPoint's Aa "Change Case" dropdown). */
-  onTransformTextCase: (mode: ChangeCaseMode) => void;
-  isOverflowMenuOpen: boolean;
-  onSetOverflowMenuOpen: (open: boolean) => void;
-  layoutOptions: Array<{
-    path: string;
-    name: string;
-  }>;
-  onInsertSlideFromLayout: (path: string, name?: string) => void;
-  customShows: PptxCustomShow[];
-  activeCustomShowId: string | null;
-  onSetActiveCustomShowId: (id: string | null) => void;
-  onCreateCustomShow: () => void;
-  onRenameActiveCustomShow: () => void;
-  onDeleteActiveCustomShow: () => void;
-  onToggleCurrentSlideInActiveShow: () => void;
-  isCurrentSlideInActiveShow: boolean;
-  onToggleVersionHistory?: () => void;
-  onOpenPasswordProtection?: () => void;
-  onOpenDocumentProperties?: () => void;
-  onOpenFontEmbedding?: () => void;
-  onOpenDigitalSignatures?: () => void;
-  onEnterMasterView: () => void;
-  onCloseMasterView: () => void;
-  onEnterPresenterView?: () => void;
-  onEnterRehearsalMode?: () => void;
-  onToggleThemeEditor: () => void;
-  isThemeEditorOpen: boolean;
-  onToggleThemeGallery: () => void;
-  isThemeGalleryOpen: boolean;
-  onCompare?: () => void;
-  onToggleComments?: () => void;
-  isCommentsPanelOpen?: boolean;
-  spellCheckActive?: boolean;
-  slideCommentCount?: number;
-  formatPainterActive?: boolean;
-  onToggleFormatPainter?: () => void;
-  canActivateFormatPainter?: boolean;
-  isSelectionPaneOpen?: boolean;
-  onToggleSelectionPane?: () => void;
-  eyedropperActive?: boolean;
-  onToggleEyedropper?: () => void;
-  onOpenSetUpSlideShow?: () => void;
-  onOpenBroadcastDialog?: () => void;
-  onToggleSubtitles?: () => void;
-  showSubtitles?: boolean;
-  activeSlide?: PptxSlide;
-  onTransitionChange: (updates: Partial<PptxSlideTransition>) => void;
-  onApplyTransitionToAll: () => void;
-  /** Host-supplied list of toolbar buttons/ribbon tabs to hide. See `PowerPointViewerProps.hiddenActions`. */
-  hiddenActions?: readonly ToolbarActionId[];
 }
+interface UseCollaborativeHistoryResult {
+  /** Undo the last local change. */
+  handleUndo: () => void;
+  /** Redo the last undone local change. */
+  handleRedo: () => void;
+  /** Whether undo is available. */
+  canUndo: boolean;
+  /** Whether redo is available. */
+  canRedo: boolean;
+}
+declare function useCollaborativeHistory({ localClientId: _localClientId, handleUndo, handleRedo, canUndo, canRedo }: UseCollaborativeHistoryInput): UseCollaborativeHistoryResult;
+//#endregion
+//#region src/viewer/hooks/collaboration/useYjsDocumentSync.d.ts
+interface UseYjsDocumentSyncInput {
+  /** The Yjs document (from useYjsProvider). null when not collaborating. */
+  doc: Doc | null;
+  /** Current slides state. */
+  slides: PptxSlide[];
+  /** Separated master/layout (template) elements, merged back on write-back. */
+  templateElementsBySlideId: Record<string, PptxElement[]>;
+  /** React state setter for slides. */
+  setSlides: React.Dispatch<React.SetStateAction<PptxSlide[]>>;
+  /** Whether collaboration is active (status === 'connected'). */
+  isConnected: boolean;
+  /**
+   * Whether the provider completed its initial document sync. Local -> doc
+   * writes are gated on this so a late joiner never seeds its bootstrap deck
+   * into a room whose real content has not arrived yet. Defaults to true for
+   * callers that manage sync readiness themselves.
+   */
+  isSynced?: boolean;
+  /** Collaboration config (for role and write-back). */
+  config?: Pick<CollaborationConfig, 'role' | 'onWriteBack' | 'writeBackDebounceMs'>;
+  /**
+   * Return the source PPTX bytes for write-back serialization. Only called
+   * when role === 'owner' and onWriteBack is set.
+   */
+  getSourceBytes?: () => Uint8Array | null;
+  /**
+   * Monotonic counter bumped each time the content-load pipeline finishes
+   * applying a parsed deck to viewer state. A local load that lands while the
+   * shared doc already holds slides (a late joiner's bootstrap deck parsing
+   * after the room state arrived) would silently clobber the synced slides;
+   * each bump re-adopts the doc's slides when the room has content.
+   */
+  loadVersion?: number;
+}
+declare function useYjsDocumentSync({ doc, slides, templateElementsBySlideId, setSlides, isConnected, isSynced, config, getSourceBytes, loadVersion }: UseYjsDocumentSyncInput): void;
 //#endregion
-//#region src/viewer/hooks/useViewerBuildingBlocks.d.ts
-interface UseViewerBuildingBlocksInput {
-  /** PPTX content as ArrayBuffer/Uint8Array, or null/undefined while no file is loaded. */
-  content: ArrayBuffer | Uint8Array | null | undefined;
-  /** Whether editing actions are enabled. Defaults to false (view-only). */
-  canEdit?: boolean;
-  /** Original file path, used for autosave recovery. */
-  filePath?: string;
-  /** Display name for the toolbar's file-name-aware controls (e.g. title bar hosts build themselves). */
-  fileName?: string;
-  /** Whether the built-in autosave-to-localStorage recovery timer is active. Defaults to true. */
-  autosaveEnabled?: boolean;
-  /** Display name used as the author for comments. */
-  userName?: string;
-  /** Host-supplied list of toolbar buttons/ribbon tabs to hide. */
-  hiddenActions?: readonly ToolbarActionId[];
-  /** Imperative handle ref, exposing the same `PowerPointViewerHandle` API `PowerPointViewer` does. */
-  handle?: React.ForwardedRef<PowerPointViewerHandle>;
-  onContentChange?: (content: Uint8Array) => void;
-  onDirtyChange?: (dirty: boolean) => void;
-  onActiveSlideChange?: (index: number) => void;
-  onModeChange?: (mode: ViewerMode) => void;
-  onZoomChange?: (zoom: number) => void;
-  onSelectionChange?: (ids: string[]) => void;
-  onSlideCountChange?: (count: number) => void;
-  /** Fired by the toolbar's "Settings" button; the host owns rendering that dialog. */
-  onOpenSettings?: () => void;
-  /** Fired by the toolbar's "Header & Footer" button; the host owns rendering that panel. */
-  onOpenHeaderFooter?: () => void;
-  /** Fired by the toolbar's "Share" button; the host owns rendering that dialog. */
-  onOpenShareDialog?: () => void;
+//#region src/viewer/hooks/collaboration/useBroadcastFollower.d.ts
+interface UseBroadcastFollowerInput {
+  /** The collaboration context (null when collaboration is disabled). */
+  collab: CollaborationContextValue | null;
+  /** Current local active slide index. */
+  activeSlideIndex: number;
+  /** Setter for the active slide index. */
+  setActiveSlideIndex: (index: number) => void;
+  /** Total number of slides (for bounds checking). */
+  slideCount: number;
+  /**
+   * When true, auto-follow stands down (e.g. the local user is manually
+   * following a specific peer via the follow bar). Defaults to false.
+   */
+  paused?: boolean;
 }
-interface ViewerBuildingBlocksResult {
-  /** Flat, self-contained props for the standalone `<Toolbar>` component. */
-  toolbarProps: ToolbarProps;
-  /** Flat, self-contained props for the standalone `<SlideCanvas>` component. */
-  canvasProps: SlideCanvasProps;
-  /** Current viewer mode (edit, view, present, master). */
+declare function useBroadcastFollower({ collab, activeSlideIndex, setActiveSlideIndex, slideCount, paused }: UseBroadcastFollowerInput): void;
+//#endregion
+//#region src/viewer/hooks/collaboration/useFollowMode.d.ts
+interface UseFollowModeInput {
+  /** The collaboration context (null when collaboration is disabled). */
+  collab: CollaborationContextValue | null;
+  /** Current local active slide index. */
+  activeSlideIndex: number;
+  /** Setter for the active slide index. */
+  setActiveSlideIndex: (index: number) => void;
+  /** Total number of slides (for bounds checking). */
+  slideCount: number;
+}
+interface UseFollowModeResult {
+  /** The clientId currently being followed, or null. */
+  followedClientId: number | null;
+  /** Follow the given peer, or `null` to stop following. */
+  followUser: (clientId: number | null) => void;
+}
+declare function useFollowMode({ collab, activeSlideIndex, setActiveSlideIndex, slideCount }: UseFollowModeInput): UseFollowModeResult;
+//#endregion
+//#region src/viewer/hooks/presentation-mode/useAnimationPlayback.d.ts
+interface UseAnimationPlaybackInput {
+  slides: PptxSlide[];
+  onPlayActionSound?: (soundPath: string) => void;
+  /** When false, all animations are skipped (elements shown immediately). */
+  showWithAnimation?: boolean;
+}
+interface UseAnimationPlaybackResult {
+  presentationAnimations: PresentationAnimationRuntime[];
+  presentationElementStates: Map<string, ElementAnimationState>;
+  presentationKeyframesCss: string;
+  interactiveTriggerShapeIds: ReadonlySet<string>;
+  hoverTriggerShapeIds: ReadonlySet<string>;
+  clearPresentationTimers: () => void;
+  playNextAnimationGroup: () => boolean;
+  handleInteractiveShapeClick: (shapeId: string) => boolean;
+  handleHoverStart: (shapeId: string) => boolean;
+  handleHoverEnd: (shapeId: string) => void;
+  runPresentationEntranceAnimations: (slideIndex: number) => void;
+  /** Exposed so the orchestrator can schedule additional timers (e.g. auto-advance). */
+  presentationTimersRef: React.RefObject<number[]>;
+}
+declare function useAnimationPlayback(input: UseAnimationPlaybackInput): UseAnimationPlaybackResult;
+//#endregion
+//#region src/viewer/hooks/presentation-mode/useRehearsalTimings.d.ts
+interface UseRehearsalTimingsInput {
+  containerRef: React.RefObject<HTMLElement | null>;
+  onSetMode: (mode: ViewerMode) => void;
+  onSaveRehearsalTimings?: (timings: Record<number, number>) => void;
+  setPresentationStartTime: (time: number | null) => void;
+  setPresenterMode: (mode: boolean) => void;
+}
+interface UseRehearsalTimingsResult {
+  rehearsing: boolean;
+  setRehearsing: React.Dispatch<React.SetStateAction<boolean>>;
+  recordedTimings: Record<number, number>;
+  slideStartTime: number | null;
+  showRehearsalSummary: boolean;
+  setShowRehearsalSummary: React.Dispatch<React.SetStateAction<boolean>>;
+  rehearsalPaused: boolean;
+  recordCurrentSlideTime: (slideIndex: number) => void;
+  dismissRehearsalSummary: () => void;
+  saveRehearsalTimings: () => void;
+  enterRehearsalMode: () => void;
+  toggleRehearsalPause: () => void;
+}
+declare function useRehearsalTimings(input: UseRehearsalTimingsInput): UseRehearsalTimingsResult;
+//#endregion
+//#region src/viewer/hooks/presentation-mode/usePresentationKeyboard.d.ts
+interface UsePresentationKeyboardInput {
   mode: ViewerMode;
-  /** True while the initial parse of `content` is in progress. */
-  loading: boolean;
-  /** Parse error message, or null. */
-  error: string | null;
-  /** Current autosave-to-localStorage recovery status. */
-  autosaveStatus: AutosaveStatus;
+  movePresentationSlide: (direction: 1 | -1) => void;
+  onSetMode: (mode: ViewerMode) => void;
+  onToggleLaser?: () => void;
+  onTogglePen?: () => void;
+  onToggleEraser?: () => void;
+  onToggleToolbar?: () => void;
+  /** Toggle between presenter view (split-screen with notes) and fullscreen. */
+  onTogglePresenterView?: () => void;
+  onToggleBlackScreen?: () => void;
+  onToggleWhiteScreen?: () => void;
+  rehearsing: boolean;
+  recordCurrentSlideTime: (slideIndex: number) => void;
+  presentationSlideIndex: number;
+  setShowRehearsalSummary: (value: boolean) => void;
 }
-declare function useViewerBuildingBlocks(input: UseViewerBuildingBlocksInput): ViewerBuildingBlocksResult;
+/**
+ * Registers keyboard shortcuts for presentation mode: arrow/space
+ * for slide navigation, Escape to exit, and annotation tool toggles.
+ */
+declare function usePresentationKeyboard(input: UsePresentationKeyboardInput): void;
+//#endregion
+//#region src/viewer/hooks/presentation-mode/useSlideNavigation.d.ts
+interface UseSlideNavigationInput {
+  slides: PptxSlide[];
+  visibleSlideIndexes: number[];
+  presentationSlideIndex: number;
+  setPresentationSlideIndex: (index: number) => void;
+  setPresentationSlideVisible: (visible: boolean) => void;
+  setTransitionOverlay: (state: PresentationTransitionOverlayState | null) => void;
+  onSetMode: (mode: ViewerMode) => void;
+  onSetActiveSlideIndex: (index: number) => void;
+  onPlayActionSound?: (soundPath: string) => void;
+  loopContinuously?: boolean;
+  /** Whether to use rehearsed auto-advance timings. When false, slides advance only on click. */
+  useTimings?: boolean;
+  /**
+   * Fired when the user advances past the last slide (no loop, no rehearsal).
+   * The presentation-mode hook uses it for PowerPoint's "End with black
+   * slide" behavior. When absent, advancing past the end clamps as before.
+   */
+  onAdvancePastLastSlide?: () => void;
+  playNextAnimationGroup: () => boolean;
+  clearPresentationTimers: () => void;
+  runPresentationEntranceAnimations: (slideIndex: number) => void;
+  presentationTimersRef: {
+    current: number[];
+  };
+  rehearsing: boolean;
+  recordCurrentSlideTime: (slideIndex: number) => void;
+  setShowRehearsalSummary: (value: boolean) => void;
+}
+interface UseSlideNavigationResult {
+  movePresentationSlide: (direction: 1 | -1, trigger?: SlideAdvanceTrigger) => void;
+  navigateToSlide: (slideIndex: number) => void;
+  handlePresentationAction: (action: PptxAction) => void;
+  scheduleAutoAdvanceForSlide: (slideIndex: number) => void;
+}
+declare function useSlideNavigation(input: UseSlideNavigationInput): UseSlideNavigationResult;
+interface UsePresenterWindowInput {
+  currentSlideIndex: number;
+  isPresenterMode: boolean;
+  /** Raw PPTX bytes to share with the audience tab via IndexedDB. */
+  content?: ArrayBuffer | Uint8Array | null;
+  snapshot: PresentationSnapshot;
+}
+interface UsePresenterWindowResult {
+  openAudienceWindow: () => boolean;
+  closeAudienceWindow: () => void;
+  isAudienceWindowOpen: () => boolean;
+  syncSlideToAudience: (slideIndex: number) => void;
+  syncStateToAudience: (snapshot: PresentationSnapshot) => void;
+  swapDisplays: () => Promise<boolean>;
+}
+declare function usePresenterWindow(input: UsePresenterWindowInput): UsePresenterWindowResult;
+//#endregion
+//#region src/viewer/hooks/presentation-mode/useAudienceMode.d.ts
+interface UseAudienceModeInput {
+  mode: ViewerMode;
+  onSetMode: (mode: ViewerMode) => void;
+  onSetActiveSlideIndex: (index: number) => void;
+  containerRef: React.RefObject<HTMLElement | null>;
+  onSnapshot?: (snapshot: PresentationSnapshot) => void;
+}
+/**
+ * When the page was opened with the `#pptx-audience` hash, this hook:
+ * 1. Auto-enters fullscreen presentation mode after content loads
+ * 2. Listens on BroadcastChannel for slide-change messages from the presenter
+ * 3. Exits presentation mode when the presenter sends an exit signal
+ */
+declare function useAudienceMode(input: UseAudienceModeInput): void;
 
 //#region src/viewer/hooks/useEditorHistory.d.ts
 interface EditorHistoryInput {
@@ -10829,6 +11082,15 @@ interface UseThemeHandlersInput {
   setSlideMasters: React.Dispatch<React.SetStateAction<Array<Record<string, unknown>>>>;
   slideMasters: Array<Record<string, unknown>>;
   history: EditorHistoryResult;
+  /** Current live slides, re-coloured in place on a scheme-colour change. */
+  setSlides: React.Dispatch<React.SetStateAction<PptxSlide[]>>;
+  /** Current theme, used to derive the previous colour map for re-resolution. */
+  theme: PptxTheme | undefined;
+  /**
+   * Force the history stack to capture the next slides change so an in-place
+   * theme re-colour lands as a single undoable entry (mirrors the AI path).
+   */
+  bumpHistory: () => void;
 }
 interface ThemeHandlersResult {
   handleApplyTheme: (themePath: string, applyToAllMasters: boolean) => Promise<void>;
@@ -11343,6 +11605,8 @@ interface ViewerIntegrationResult {
   autosaveStatus: AutosaveStatus;
   isEncryptedDialogOpen: boolean;
   setIsEncryptedDialogOpen: Dispatch<SetStateAction<boolean>>;
+  /** The loaded core handler, exposed for the AI bridge (`getHandler`). */
+  handlerRef: RefObject<PptxHandler | null>;
   /**
    * Bumped each time the load pipeline finishes applying parsed content to
    * viewer state. Collaboration watches it to re-adopt the shared doc's