pptx-react-viewer 4.0.0 → 4.1.0

package/dist/index.d.ts

@@ -11648,7 +11648,24 @@ interface TextStyleAnimationDescriptor {
 
 //#region src/render/collaboration-presence.d.ts
 /** Connection lifecycle states for the Yjs WebSocket provider. */
-type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+type ConnectionStatus$1 = 'disconnected' | 'connecting' | 'connected' | 'error';
+/**
+ * Presence data for a remote collaborator, sanitised from the awareness
+ * protocol. Returned by {@link sanitizePresence}; coordinates are in unscaled
+ * slide pixels, clamped to the supplied canvas bounds.
+ */
+interface SanitizedPresence {
+  clientId: number;
+  userName: string;
+  userAvatar?: string;
+  userColor: string;
+  activeSlideIndex: number;
+  cursorX: number;
+  cursorY: number;
+  lastUpdated: string;
+  selectedElementId?: string;
+  role?: CollaborationRole;
+}
 //#endregion
 //#region src/render/collaboration-presence-publisher.d.ts
 /**
@@ -11666,7 +11683,7 @@ interface AwarenessLike {
 //#region src/render/collaboration-external-session.d.ts
 /** Connection state reported by the host, independent of the viewer lifetime. */
 interface ExternalCollaborationSnapshot {
-  status: ConnectionStatus;
+  status: ConnectionStatus$1;
   /**
    * The host has loaded the authoritative document and permits local edits.
    * Keep true while offline to allow ordinary Yjs offline edits, or set false
@@ -11897,6 +11914,47 @@ interface CollaborationConfig {
   writeBackDebounceMs?: number;
 }
 //#endregion
+//#region src/render/text-run-style.d.ts
+/** A plain CSS style map (keys are CSS properties; binding-agnostic). */
+type RunStyle = Record<string, string | number>;
+/** One script-tagged piece of a run's text, ready for a binding's nested span. */
+interface ScriptFontPiece {
+  text: string;
+  /**
+   * CSS for a nested span wrapping `text`, or `undefined` when this piece
+   * needs no span at all (its script's font equals the run's own, so plain
+   * text renders identically). When present it carries the `fontFamily`
+   * override plus the run's own decoration subset, repeated because
+   * `text-decoration-*` does not inherit into a nested span (see
+   * `nestedTextDecorationStyle`).
+   */
+  style?: RunStyle;
+}
+//#endregion
+//#region src/render/reflection.d.ts
+/**
+ * CSS `mask-image`/`-webkit-mask-image` value plus the raw `transform` for a
+ * mirrored reflection sibling. Every value is a ready-to-apply CSS string (or
+ * `'none'` sentinel avoided - fields are omitted when the browser default
+ * already matches), so a binding can spread this directly onto its own style
+ * object with no further per-framework logic.
+ */
+interface ReflectionWrapperStyle {
+  position: 'absolute';
+  left: string;
+  /** `calc(100% + <dist>px)`: sits `@dist` px below the source element's box. */
+  top: string;
+  width: string;
+  height: string;
+  /** Mirror (`scaleY(-1)`) composed with `@sx`/`@sy`/`@kx`/`@ky`/`@rot`. */
+  transform: string;
+  /** Anchor point for the transform above, from `@algn` (default `center top`). */
+  transformOrigin: string;
+  maskImage: string;
+  WebkitMaskImage: string;
+  pointerEvents: 'none';
+}
+//#endregion
 //#region src/render/animation-timeline-build-descriptors.d.ts
 /**
  * `animation-timeline-build-descriptors` - staged-build (`p:bldChart` /
@@ -12134,6 +12192,272 @@ declare function buildSlideTemplateContent(id: SlideTemplateId, options?: SlideT
 declare function buildSlideTemplateSlide(templateId: SlideTemplateId, slideId: string, slideNumber: number, options?: SlideTemplateBuildOptions): PptxSlide;
 /** The unit system used for ruler display. */
 type RulerUnit = 'inches' | 'centimetres';
+/** Framework-neutral picture-bullet source, sizing, and accessible fallback. */
+interface PictureBulletMarker {
+  src?: string;
+  sizePx: number;
+  fallbackMarker: string;
+  accessibleLabel: string;
+  imageRelId?: string;
+}
+//#endregion
+//#region src/render/text-run-meta.d.ts
+/** A run's resolved hyperlink target. */
+interface RunHyperlink {
+  /**
+   * The URL to hand a click handler. For an internal `ppaction://hlinksldjump`
+   * the resolved slide index is appended as a `slideIndex` query parameter, so
+   * the target survives a callback whose only argument is the URL (see
+   * `parsePpactionUrl`, which reads it back off).
+   */
+  url: string;
+  /**
+   * A safe, renderable `href` for a plain `<a>`, or `undefined` when the target
+   * is an internal `ppaction://` action or fails the URL safety check. A
+   * binding with no click handler renders the run as text in that case, which
+   * is what every binding did for every link before this field existed.
+   */
+  href?: string;
+  /** `a:hlinkClick/@tooltip`, for the anchor's `title`. */
+  tooltip?: string;
+  /**
+   * `<a target>` for a real (non-`ppaction://`) hyperlink, from
+   * `a:hlinkClick/@tgtFrame` when authored, else `_blank` (every binding's
+   * pre-existing hardcoded default). Only meaningful alongside {@link href}.
+   */
+  target?: string;
+  /** `<a rel>` paired with {@link target} (see `resolveHyperlinkTargetAttrs`). */
+  rel?: string;
+  /** Resolved target slide for an internal slide jump. */
+  targetSlideIndex?: number;
+  /**
+   * True when the target came from `a:hlinkMouseOver` rather than
+   * `a:hlinkClick`: PowerPoint follows it on hover, not on click, so a binding
+   * that renders a plain anchor should not make it look clickable.
+   */
+  onHover?: boolean;
+}
+/** An inline equation run (`m:oMath`), rendered as MathML rather than text. */
+interface RunEquation {
+  /** The raw OMML node, for `convertOmmlToMathMl`. */
+  xml: Record<string, unknown>;
+  /** Display number for a numbered equation, without its parentheses. */
+  number?: string;
+}
+//#endregion
+//#region src/render/text-run-ruby.d.ts
+/** A run's phonetic guide, ready to render as `<rt>` above the base text. */
+interface RunRuby {
+  /** The annotation itself (`a:ruby/a:rt`), e.g. the furigana reading. */
+  text: string;
+  /** Inline style for the `<rt>` element (size, family, alignment, colour). */
+  style: RunStyle;
+}
+//#endregion
+//#region src/render/text-tab-run-build.d.ts
+/** One tabbed-line piece, ready to spread onto a binding's own span element. */
+interface TabbedRunPiece {
+  text: string;
+  /**
+   * CSS for the span that wraps `text`: inline-block layout, this run's own
+   * decoration repeated, and this piece's own PowerPoint advance-width
+   * correction as `letter-spacing` (see `buildTabbedLine`). The piece is
+   * nested inside the run's own span, and neither property inherits the way a
+   * caller would want: `text-decoration-*` does not inherit into a nested
+   * element at all (an ancestor's underline is drawn *through* its
+   * descendants, but each descendant still computes `none` of its own), so a
+   * caller passes the run's decoration subset (`nestedTextDecorationStyle`) to
+   * have it repeated here; `letter-spacing` DOES inherit, which is exactly why
+   * this piece sets it explicitly rather than only when non-zero - the run's
+   * container span carries its own (wrong, whole-text) correction that would
+   * otherwise leak in.
+   */
+  style: RunStyle;
+  /** CSS for the leader-fill span preceding this piece, or `undefined` when there is no gap to fill. */
+  leaderStyle?: RunStyle;
+  /** Leader glyphs sized to fill `leaderStyle`'s width. Present only alongside `leaderStyle`. */
+  leaderText?: string;
+  /**
+   * `a:rPr/@u="words"` per-word/gap sub-pieces of THIS tab piece's own text
+   * (see `splitWordsForUnderline`), present only when the run's underline is
+   * `words`. A tab-separated piece is otherwise rendered as a single span
+   * (`text` + `style`), which underlines it continuously - correct for a
+   * one-word piece, but wrong for a piece like `"Hello World"` between two tab
+   * stops, which needs a gap under the space. A binding renders one SIBLING
+   * span per entry IN PLACE OF the piece's single `text` span: each entry's
+   * `style` is the piece's own `style` (the same inline-block layout and
+   * advance-width correction, so the line measures exactly as before), with
+   * the underline stripped on a gap entry. They must be siblings, not spans
+   * nested inside the piece span: an ancestor's underline is drawn through
+   * every inline descendant, so a nested gap could not lose it. `text`/`style`
+   * stay the continuous-underline fallback for a binding that does not
+   * render this field.
+   */
+  words?: Array<{
+    text: string;
+    style: RunStyle;
+  }>;
+}
+/** One `\n`-split line of a run's tabbed text. */
+interface TabbedLineRun {
+  pieces: TabbedRunPiece[];
+}
+//#endregion
+//#region src/render/paragraph-types.d.ts
+/** A single rendered run within a paragraph. */
+interface ParagraphRun {
+  text: string;
+  style: RunStyle;
+  /**
+   * The run's hyperlink (`a:hlinkClick` / `a:hlinkMouseOver`), when it has one.
+   * A binding renders the run inside an `<a href>` when {@link RunHyperlink.href}
+   * is set, and routes {@link RunHyperlink.url} to its click handler otherwise
+   * (internal `ppaction://` slide jumps).
+   */
+  hyperlink?: RunHyperlink;
+  /**
+   * An inline equation (`m:oMath`) this run renders INSTEAD of `text`, which is
+   * empty for it. Emitted in the run sequence so the maths lands at its
+   * authored position between the runs around it.
+   */
+  equation?: RunEquation;
+  /**
+   * The run's phonetic guide (`a:ruby`: furigana, pinyin, bopomofo), when it
+   * has one. A binding renders `<ruby>{text}<rt style>{ruby.text}</rt></ruby>`;
+   * a run carrying one is never split per word, so the annotation appears once
+   * over the whole base run.
+   *
+   * Core parsed and saved ruby from the start, but `buildParagraphs` never read
+   * it, so the annotation rendered in React alone.
+   */
+  ruby?: RunRuby;
+  /**
+   * Index of the `textSegments` entry (of the override list when one was
+   * supplied) this run was built from.
+   *
+   * Shared splits one authored run into several per-word runs for PowerPoint's
+   * metric tracking, so this is many-to-one. It is the seam a binding uses to
+   * reach the facts the neutral model does not carry - React's find-match
+   * highlights, per-script font spans, tab stops and ruby all key off the
+   * originating segment - without regrouping the segments itself and drifting
+   * from the grouping here.
+   */
+  segmentIndex?: number;
+  /**
+   * Offset of this run's `text` within its segment's RENDERED text (after field
+   * substitution), so a caller holding per-segment character offsets can map
+   * them onto the split runs.
+   */
+  charStart?: number;
+  /**
+   * Per-script (`a:ea`/`a:cs`/`a:sym`) font-fallback pieces for this run's
+   * text, when a script it contains needs a font distinct from its own. A
+   * binding renders these as nested spans in place of `text` (see
+   * `text-script-fonts.ts`); absent for the common single-font case.
+   */
+  scriptRuns?: ScriptFontPiece[];
+  /**
+   * Measured tab-stop layout for this run's text, present when it contains an
+   * authored `\t` and the paragraph declares explicit tab stops. A binding
+   * renders these lines/pieces in place of `text`, honouring per-stop
+   * alignment and leader glyphs a plain CSS `tab-size` cannot express (see
+   * `text-tab-run-build.ts`). Absent for the common no-tab case.
+   */
+  tabLines?: TabbedLineRun[];
+  /**
+   * `a:rPr/@u="words"` word/gap pieces of a RUBY run's base text, present only
+   * when such a run's underline is `words` (the ordinary per-word split emits
+   * sibling runs instead; a tab piece carries its own `words`). Same shape as
+   * `scriptRuns` and rendered the same way, in place of `text`: a word entry
+   * carries the decoration for its own span, a gap entry is bare text. The
+   * run's own `style` has the underline stripped when this is set (see
+   * `paragraph-run-build.ts`).
+   */
+  underlineWordPieces?: ScriptFontPiece[];
+  /**
+   * `a:reflection` mirrored-sibling wrapper style for this run (the text-run
+   * counterpart of a shape/picture's `ComputedEffectStyle.reflection`), or
+   * `undefined` for the common no-reflection case. A binding renders a sibling
+   * node just below the run's own, painted with the same text, positioned and
+   * masked by this style - see `render/reflection.ts`'s
+   * `getTextReflectionWrapperStyle`.
+   */
+  reflection?: ReflectionWrapperStyle;
+}
+/** A rendered paragraph: runs plus resolved bullet + hanging-indent metadata. */
+interface RenderParagraph {
+  runs: ParagraphRun[];
+  /** Bullet glyph / number to render before the runs (or `undefined`). */
+  bulletMarker?: string;
+  /** Picture marker rendered before runs, or fallback metadata when unresolved. */
+  bulletPicture?: PictureBulletMarker;
+  /** Inline style for the bullet marker (font / size / colour). */
+  bulletStyle: RunStyle;
+  /** `margin-left` in px for the whole paragraph (hanging-indent layout). */
+  marginLeftPx?: number;
+  /** `text-indent` in px (first-line / hanging indent). */
+  textIndentPx?: number;
+  /**
+   * Per-paragraph `line-height` from this paragraph's own `a:pPr > a:lnSpc`.
+   * A unitless multiplier for proportional spacing (`a:spcPct`) or a `"<n>pt"`
+   * string for exact spacing (`a:spcPts`). Undefined when the paragraph does
+   * not override spacing (binding keeps the body-level line-height).
+   */
+  lineHeight?: number | string;
+  /** `margin-top` in px from this paragraph's `a:pPr > a:spcBef` (space before). */
+  spaceBeforePx?: number;
+  /** `margin-bottom` in px from this paragraph's `a:pPr > a:spcAft` (space after). */
+  spaceAfterPx?: number;
+  /**
+   * `font-size` in px to set on the paragraph element so its CSS line boxes
+   * are built from its OWN runs rather than the text body's default size.
+   * Undefined when the paragraph already matches the body default.
+   *
+   * See `resolveParagraphStrutFontSize` for why this is needed: without it a
+   * paragraph of small runs inside a larger-defaulting body is laid out on
+   * too-tall lines and overflows its shape.
+   */
+  strutFontSizePx?: number;
+  /**
+   * True when the paragraph has no runs and no bullet: an authored blank line
+   * (`<a:p><a:endParaRPr/></a:p>`).
+   *
+   * PowerPoint gives such a paragraph a full line box, which is how decks
+   * space a heading away from the bullet list under it. A binding must render
+   * something with height for it (a `<br>`), or the gap disappears and the
+   * block reads as one dense run of text (issue #131, slides 13-14).
+   */
+  isEmpty?: boolean;
+  /**
+   * Indices of this paragraph's segments in the rendered segment list (the
+   * override list when one was supplied), in authored order and INCLUDING the
+   * bullet-marker segment the runs drop.
+   *
+   * The seam a binding uses to reach paragraph facts the neutral model does not
+   * carry, without regrouping the segments itself and drifting from the
+   * grouping here - which is exactly how React ended up splitting on every
+   * `"\n"` and treating a soft `a:br` as a paragraph break.
+   */
+  segmentIndices: number[];
+  /**
+   * True when this paragraph resolves right-to-left (`a:pPr/@rtl`, or the text
+   * body's default). A binding that mirrors its hanging indent for RTL reads
+   * this; the direction itself is already in {@link paragraphStyle}.
+   */
+  rtl?: boolean;
+  /**
+   * Extra CSS for the paragraph box, beyond the margin / indent / spacing
+   * fields above: this paragraph's own `text-align` (`a:pPr/@algn`), its BiDi
+   * `direction`, and the kinsoku line-breaking rules (`@eaLnBrk`,
+   * `@latinLnBrk`, `@hangingPunct`). Absent when the paragraph overrides none
+   * of them, which is the common case.
+   *
+   * All three used to be resolved in React's private paragraph renderer only,
+   * so a deck that centred one paragraph of a left-aligned body, or set CJK
+   * break rules, rendered differently in the other four bindings.
+   */
+  paragraphStyle?: RunStyle;
+}
 //#endregion
 //#region src/render/inline-list-types.d.ts
 /** Current editor payload. Missing segments explicitly denotes plain-text fallback. */
@@ -12142,6 +12466,15 @@ interface InlineTextEditSnapshot {
   text: string;
   textSegments?: TextSegment[];
 }
+type InlineListReadResult = {
+  kind: 'supported';
+  snapshot: InlineTextEditSnapshot;
+  paragraphs: RenderParagraph[];
+} | {
+  kind: 'unsupported';
+  reason: string;
+  text: string;
+};
 //#endregion
 //#region src/render/text-field-substitution.d.ts
 /**
@@ -12238,6 +12571,184 @@ interface ShapeAdjustmentHandleDescriptor {
    */
   solvers?: AdjustmentAxisSolver[];
 }
+interface CollaborationShellState {
+  canEdit: boolean;
+  status: ConnectionStatus$1;
+  remoteUsers: readonly SanitizedPresence[];
+  connectedCount: number;
+}
+type CollaborationShellTranslate = (key: string, params?: Record<string, string | number>) => string;
+/**
+ * One-line, localised status for a custom shell's `role="status"` readout.
+ *
+ * Every binding's custom-shell demo renders this same string under the same
+ * `Collaboration status` label, so the framework-neutral e2e helper that
+ * waits for the shell to become editable (`waitForHostEditing`) reads every
+ * binding the same way. Three of five demos once phrased it differently and
+ * the helper silently skipped them; on vanilla, that let a peer double-click
+ * before its edit gate opened.
+ */
+declare function describeCollaborationShellState(state: Pick<CollaborationShellState, 'canEdit' | 'status' | 'connectedCount'>, translate: CollaborationShellTranslate): string;
+//#endregion
+//#region src/render/collaboration-text-codec.d.ts
+/**
+ * collaboration-text-codec.ts: TextSegment[] <-> Y.Text delta codec used by the
+ * collaboration sync layer. Split out of collaboration-sync.ts to keep both
+ * modules focused.
+ *
+ * Exports:
+ *  - DeltaOp / YTextLike: structural Yjs text interfaces (no yjs import)
+ *  - encodeTextBody: write TextSegment[] into a live YTextLike
+ *  - encodeSegmentsToDelta: pure simulation of the delta Y.Text would produce
+ *  - decodeDelta / decodeTextBody: delta -> TextSegment[]
+ *  - isYTextLike: runtime guard
+ */
+interface DeltaOp {
+  insert?: unknown;
+  attributes?: Record<string, unknown>;
+}
+interface YTextLike {
+  insert: (index: number, text: string, attrs?: Record<string, string>) => void;
+  toDelta: () => DeltaOp[];
+  toString: () => string;
+}
+//#endregion
+//#region src/render/collaboration-text-merge.d.ts
+/** Y.Text surface needed for in-place edits (delete/format on top of insert). */
+interface YTextEditableLike extends YTextLike {
+  delete: (index: number, length: number) => void;
+  format: (index: number, length: number, attributes: Record<string, string | null>) => void;
+}
+//#endregion
+//#region src/render/collaboration-text-positions.d.ts
+interface TextPositionCell {
+  index: number;
+  left?: TextPositionCell;
+  right?: TextPositionCell;
+}
+interface TrackedTextPosition {
+  /** Internal identity, shared by snapshots that observed the same character. */
+  readonly cell: TextPositionCell;
+  readonly association: number;
+}
+//#endregion
+//#region src/render/collaboration-text-session-delta.d.ts
+/** Browser edit range mapped to the editor's pre-input encoded coordinates. */
+interface LocalTextReplacement {
+  from: number;
+  to: number;
+}
+/** Desired UTF-16 units mapped to the editor's previously observed identities. */
+interface TextSessionCorrespondence {
+  readonly retainedIndices: readonly (number | null)[];
+  /** Old carriers for known paragraph attributes, independently of character identity. */
+  readonly paragraphSources?: readonly (number | null)[];
+}
+type LocalTextEdit = LocalTextReplacement | TextSessionCorrespondence;
+//#endregion
+//#region src/render/collaboration-text-session.d.ts
+/** Supplied by the binding's existing Yjs runtime, bound to this exact Y.Text. */
+interface TextSessionPositions<Position> {
+  capture: (index: number, association: number) => Position;
+  resolve: (position: Position) => number | null;
+  /** Synchronize tracked positions once per batch, including in-transaction writes. */
+  refresh?: () => boolean | void;
+  /** Release only resources created for this session. */
+  dispose?: () => void;
+}
+/** Opaque acknowledgement identity for an exact remote snapshot painted by an adapter. */
+interface CollaborationTextSnapshot {
+  readonly delta: readonly DeltaOp[];
+}
+interface CollaborationTextSession {
+  applyLocalDelta: (delta: readonly DeltaOp[], edit?: LocalTextEdit) => boolean;
+  readMerged: () => CollaborationTextSnapshot | undefined;
+  adoptMerged: (snapshot: CollaborationTextSnapshot) => boolean;
+  /** Capture an offset in the last painted/local draft, not the newer remote string. */
+  bookmark: (index: number, association: number) => () => number | null;
+  dispose: () => void;
+}
+//#endregion
+//#region src/render/collaboration-sync.d.ts
+interface YMapLike {
+  get: (key: string) => unknown;
+  set: (key: string, value: unknown) => void;
+  delete: (key: string) => void;
+  forEach: (cb: (value: unknown, key: string) => void) => void;
+}
+/** Shape of the Yjs transaction passed to (deep) observers. */
+interface YTransactionLike {
+  origin?: unknown;
+}
+type YDeepObserver = (events?: unknown, transaction?: YTransactionLike) => void;
+interface YArrayLike {
+  readonly length: number;
+  get: (index: number) => unknown;
+  push: (items: unknown[]) => void;
+  delete: (index: number, length?: number) => void;
+  insert: (index: number, items: unknown[]) => void;
+  toArray: () => unknown[];
+  observe: (handler: () => void) => void;
+  unobserve: (handler: () => void) => void;
+  observeDeep: (handler: YDeepObserver) => void;
+  unobserveDeep: (handler: YDeepObserver) => void;
+}
+interface YDocLike {
+  getMap: (name: string) => YMapLike;
+  getArray: (name: string) => YArrayLike;
+  transact: (fn: () => void, origin?: unknown) => void;
+}
+interface YjsFactories {
+  createMap: () => YMapLike;
+  createArray: () => YArrayLike;
+  createText: () => YTextLike;
+  /** Track character identities using the binding's existing Yjs runtime. */
+  createTextPositions?: (text: YTextEditableLike) => TextSessionPositions<TrackedTextPosition>;
+}
+//#endregion
+//#region src/render/collaboration-live-patch-target.d.ts
+/** Interim geometry for an element mid-gesture. All fields optional. */
+interface LiveGeometryPatch {
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  rotation?: number;
+}
+/** The element's pre-edit rich text, used to remap the interim plain text. */
+interface LiveTextSource {
+  textSegments?: TextSegment[];
+  textStyle?: TextStyle;
+}
+//#endregion
+//#region src/render/collaboration-text-target.d.ts
+interface CollaborationInlineSnapshot extends CollaborationTextSnapshot {
+  readonly inline: InlineTextEditSnapshot;
+}
+/** A mounted editor owns this handle, never the document or its provider. */
+interface CollaborationTextTarget extends CollaborationTextSession {
+  readMerged: () => CollaborationInlineSnapshot | undefined;
+  /** A bookmark follows character identity rather than a mutable numeric offset. */
+  bookmark: (index: number, association: number) => () => number | null;
+}
+interface CollaborationLivePatcher {
+  /** Bind a mounted native editor; its handle must be disposed on unmount. */
+  beginTextEdit?: (slideId: string | undefined, elementId: string, onChange?: () => void, ownsModel?: (element: PptxElement) => boolean) => CollaborationTextTarget | undefined;
+  /** Attach a live doc (or `null` to go dormant). Pending patches are dropped. */
+  configure: (doc: YDocLike | null, factories: YjsFactories | null,
+  /** Publish synchronously when the host may revoke write readiness at any time. */
+  immediate?: boolean) => void;
+  /** True when a doc + factories are attached, i.e. patches will be written. */
+  isActive: () => boolean;
+  /** Queue interim geometry for an element. */
+  patchGeometry: (slideId: string | undefined, elementId: string, geometry: LiveGeometryPatch) => void;
+  /** Queue interim text for an element (remapped over `source`'s segments). */
+  patchText: (slideId: string | undefined, elementId: string, text: string, source?: LiveTextSource) => void;
+  /** Write everything queued right now (call on gesture end / edit commit). */
+  flush: () => void;
+  /** Drop pending work, cancel timers and detach the doc. */
+  dispose: () => void;
+}
 /**
  * A font supplied by the host application. The package never ships fonts:
  * applications provide a licensed URL, data URL, or blob URL for their users.
@@ -12904,6 +13415,58 @@ interface PptxAiBridge {
   notify?(message: string, level?: PptxAiNotifyLevel): void;
 }
 //#endregion
+//#region src/viewer/hooks/collaboration/types.d.ts
+/** Connection lifecycle states for the Yjs WebSocket provider. */
+type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+/**
+ * Presence data broadcast to other participants.
+ * Cursor position is relative to the slide canvas (0..canvasWidth, 0..canvasHeight).
+ */
+interface UserPresence {
+  /** Unique client ID (assigned by Yjs awareness). */
+  clientId: number;
+  /** Sanitised display name. */
+  userName: string;
+  /** Optional avatar URL (validated). */
+  userAvatar?: string;
+  /** Hex colour for the user's cursor ring. */
+  userColor: string;
+  /** Slide index the user is currently viewing. */
+  activeSlideIndex: number;
+  /** Cursor X on the canvas (clamped to slide bounds). */
+  cursorX: number;
+  /** Cursor Y on the canvas (clamped to slide bounds). */
+  cursorY: number;
+  /** ISO timestamp of last update (for stale-presence cleanup). */
+  lastUpdated: string;
+  /** Optional currently selected element ID. */
+  selectedElementId?: string;
+  /** Role in the session (owner, viewer, or collaborator). */
+  role?: CollaborationRole;
+}
+/** Value exposed by `CollaborationContext`. */
+interface CollaborationContextValue {
+  /** Current WebSocket connection status. */
+  status: ConnectionStatus;
+  /** Presence data for all remote users (excludes the local user). */
+  remoteUsers: UserPresence[];
+  /** Broadcast the local user's presence state. */
+  broadcastPresence: (update: Partial<Omit<UserPresence, 'clientId'>>) => void;
+  /** Total number of connected users (including local). */
+  connectedCount: number;
+  /** The collaboration config that was provided. */
+  config: CollaborationConfig;
+  /** The Yjs document (for document sync). */
+  doc: Doc | null;
+  /**
+   * Whether the provider completed its initial document sync (or the
+   * first-write grace period elapsed). Local doc writes are gated on this.
+   */
+  synced: boolean;
+  /** Manually retry the WebSocket connection after a timeout or error. */
+  retry: () => void;
+}
+//#endregion
 //#region src/viewer/types-ui.d.ts
 /**
  * Base handle interface for file viewer components.
@@ -13522,6 +14085,9 @@ interface ZoomViewport {
   editorScale: number;
 }
 interface SlideCanvasProps {
+  /** The viewer-owned live channel; absent for static/custom non-collaborative canvases. */
+  livePatcher?: CollaborationLivePatcher;
+  registerInlineEditReader?: (elementId: string, read: () => InlineListReadResult) => () => void;
   /** Native image paste commands supplied by the stock or headless editor. */
   imagePaste?: CanvasImagePasteHandlers;
   activeSlide: PptxSlide | undefined;
@@ -13672,8 +14238,10 @@ type AutosaveStatus = {
   message: string;
 };
 //#endregion
-//#region src/viewer/hooks/useViewerBuildingBlocks.d.ts
+//#region src/viewer/hooks/useViewerBuildingBlocks-types.d.ts
 interface UseViewerBuildingBlocksInput extends ViewportFitOptions {
+  /** Optional collaboration, including a host-owned document and presence session. */
+  collaboration?: CollaborationConfig;
   /** 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). */
@@ -13689,7 +14257,7 @@ interface UseViewerBuildingBlocksInput extends ViewportFitOptions {
   /** 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>;
+  handle?: React$1__default.ForwardedRef<PowerPointViewerHandle>;
   onContentChange?: (content: Uint8Array) => void;
   onDirtyChange?: (dirty: boolean) => void;
   onActiveSlideChange?: (index: number) => void;
@@ -13705,6 +14273,15 @@ interface UseViewerBuildingBlocksInput extends ViewportFitOptions {
   onOpenShareDialog?: () => void;
 }
 interface ViewerBuildingBlocksResult {
+  /** Connection and presence state for a custom status bar, or null when disabled. */
+  collaboration: CollaborationContextValue | null;
+  /**
+   * Effective edit permission plus connection/presence counts, in the shape
+   * every binding's custom shell receives (Vue/Svelte `shellState`, Angular
+   * `state()`, Vanilla `getState()`); pass it to
+   * `describeCollaborationShellState` for a localised status line.
+   */
+  shellState: CollaborationShellState;
   /** Flat, self-contained props for the standalone `<Toolbar>` component. */
   toolbarProps: ToolbarProps;
   /** Flat, self-contained props for the standalone `<SlideCanvas>` component. */
@@ -13718,13 +14295,15 @@ interface ViewerBuildingBlocksResult {
   /** Current autosave-to-localStorage recovery status. */
   autosaveStatus: AutosaveStatus;
 }
+//#endregion
+//#region src/viewer/hooks/useViewerBuildingBlocks.d.ts
 declare function useViewerBuildingBlocks(input: UseViewerBuildingBlocksInput): ViewerBuildingBlocksResult;
 
 //#region src/viewer/components/Toolbar.d.ts
 declare function Toolbar(p: ToolbarProps): React$1__default.ReactElement;
 //#endregion
 //#region src/viewer/components/SlideCanvas.d.ts
-declare function SlideCanvas({ imagePaste, activeSlide, templateElements, canvasSize, zoom, mode, canEdit, editTemplateMode, selectedElementIdSet, selectedElement, inlineEditingElementId, inlineEditingText, spellCheckEnabled, mediaDataUrls, tableEditorState, marqueeSelectionState, snapLines, showGrid, gridSpacingPx, showRulers, rulerUnit, guides, presentationElementStates, presentationKeyframesCss, onClick, onDoubleClick, onMouseDown, onContextMenu, onCanvasMouseDown, onResizePointerDown, onAdjustmentPointerDown, onRotate, onInlineEditChange, onInlineEditCommit, onInlineEditCancel, onTableCellSelect, onCommitCellEdit, onUpdateSmartArtElement, onFormatText, onResizeTableColumns, onResizeTableRow, findResults, findResultIndex, activeSlideIndex, activeTool, drawingColor, drawingWidth, isDrawingRef, onAddInkElement, onAddFreeformShape, onEraseInkElement, onActionClick, onHyperlinkClick, comments, showCommentMarkers, onCommentMarkerClick, onMoveGuide, onDeleteGuide, onCreateGuideFromRuler, connectorCreationMode, onCreateConnector, onUpdateSlideAnimations, allSlides, onZoomClick, sourceSlideIndex, fieldContext, tableStyleContext, collaborationOverlay, aiActive }: SlideCanvasProps): React$1.JSX.Element;
+declare function SlideCanvas(props: SlideCanvasProps): React$1.JSX.Element;
 //#endregion
 //#region src/viewer/components/SlideTemplateGalleryDialog.d.ts
 interface SlideTemplateGalleryDialogProps {
@@ -13763,5 +14342,5 @@ declare function SlideTemplatePreview({ templateId, scheme }: SlideTemplatePrevi
  */
 declare function renderToCanvas(element: HTMLElement, options?: Partial<Options>): Promise<HTMLCanvasElement>;
 
-export { AVATAR_COLOR_SWATCHES, DEFAULT_VIEWER_PROFILE, LOCALE_CATALOG, PPTX_OPEN_ACCEPT, PRESENTATION_OPEN_EXTENSIONS, PowerPointViewer, SLIDE_TEMPLATES, SlideCanvas, SlideTemplateGalleryDialog, SlideTemplatePreview, THEME_CATALOG, Toolbar, VIEWER_PREFS_STORAGE_KEY, ViewerThemeProvider, buildSlideTemplateContent, buildSlideTemplateSlide, clearAllLocalViewerData, clearStoredViewerPrefs, createImageElementFromFile, defaultCssVars, defaultRadius, defaultThemeColors, getAnimationInitialStyle, getLocalStorageUsageSummary, isLegacyBinaryPresentation, isSupportedPresentationFile, presentationBaseName, readStoredViewerPrefs, renderToCanvas, resolveProfileInitial, resolveThemeCatalogEntry, saveViewerProfile, savedPresentationFileName, themeToCssVars, useViewerBuildingBlocks, useViewerTheme, vermilionDarkColors, vermilionDarkTheme, vermilionLightColors, vermilionLightTheme, vermilionRadius, writeStoredViewerPrefs };
-export type { AccountAuthConfig, CollaborationConfig, ElementUpdate, ElementUpdateOptions, ExternalCollaborationAwareness, ExternalCollaborationSession, ExternalCollaborationSnapshot, LocalStorageUsageSummary, LocaleCatalogEntry, PowerPointViewerAPI, PowerPointViewerHandle, PowerPointViewerProps, PptxAiBridge, PptxAiConfig, PptxAiConnection, PptxAiContextStrategy, PptxAiToolName, PptxAiWritePolicy, SavedPresentationFormat, SlideCanvasProps, SlideTemplateGalleryDialogProps, SlideTemplateId, SlideTemplatePreviewProps, SlideTemplateSpec, StoredViewerPrefs, ThemeCatalogEntry, ToolbarActionId, ToolbarButtonId, ToolbarProps, ToolbarTabId, UseViewerBuildingBlocksInput, ViewerBuildingBlocksResult, ViewerMode, ViewerProfile, ViewerTheme, ViewerThemeColors, ViewportFitOptions, ViewportFitPadding };
+export { AVATAR_COLOR_SWATCHES, DEFAULT_VIEWER_PROFILE, LOCALE_CATALOG, PPTX_OPEN_ACCEPT, PRESENTATION_OPEN_EXTENSIONS, PowerPointViewer, SLIDE_TEMPLATES, SlideCanvas, SlideTemplateGalleryDialog, SlideTemplatePreview, THEME_CATALOG, Toolbar, VIEWER_PREFS_STORAGE_KEY, ViewerThemeProvider, buildSlideTemplateContent, buildSlideTemplateSlide, clearAllLocalViewerData, clearStoredViewerPrefs, createImageElementFromFile, defaultCssVars, defaultRadius, defaultThemeColors, describeCollaborationShellState, getAnimationInitialStyle, getLocalStorageUsageSummary, isLegacyBinaryPresentation, isSupportedPresentationFile, presentationBaseName, readStoredViewerPrefs, renderToCanvas, resolveProfileInitial, resolveThemeCatalogEntry, saveViewerProfile, savedPresentationFileName, themeToCssVars, useViewerBuildingBlocks, useViewerTheme, vermilionDarkColors, vermilionDarkTheme, vermilionLightColors, vermilionLightTheme, vermilionRadius, writeStoredViewerPrefs };
+export type { AccountAuthConfig, CollaborationConfig, CollaborationContextValue, CollaborationShellState, ElementUpdate, ElementUpdateOptions, ExternalCollaborationAwareness, ExternalCollaborationSession, ExternalCollaborationSnapshot, LocalStorageUsageSummary, LocaleCatalogEntry, PowerPointViewerAPI, PowerPointViewerHandle, PowerPointViewerProps, PptxAiBridge, PptxAiConfig, PptxAiConnection, PptxAiContextStrategy, PptxAiToolName, PptxAiWritePolicy, SavedPresentationFormat, SlideCanvasProps, SlideTemplateGalleryDialogProps, SlideTemplateId, SlideTemplatePreviewProps, SlideTemplateSpec, StoredViewerPrefs, ThemeCatalogEntry, ToolbarActionId, ToolbarButtonId, ToolbarProps, ToolbarTabId, UseViewerBuildingBlocksInput, ViewerBuildingBlocksResult, ViewerMode, ViewerProfile, ViewerTheme, ViewerThemeColors, ViewportFitOptions, ViewportFitPadding };