pptx-react-viewer 3.20.0 → 3.21.0

package/dist/internals.d.ts

@@ -11489,6 +11489,61 @@ interface TextStyleAnimationDescriptor {
   color?: string;
 }
 
+//#region src/render/collaboration-presence.d.ts
+/** Connection lifecycle states for the Yjs WebSocket provider. */
+type ConnectionStatus$1 = 'disconnected' | 'connecting' | 'connected' | 'error';
+//#endregion
+//#region src/render/collaboration-presence-publisher.d.ts
+/**
+ * Structural interface for the lazily-imported Yjs awareness surface. Every
+ * binding's live `y-protocols/awareness` `Awareness` instance satisfies this.
+ */
+interface AwarenessLike {
+  clientID?: number;
+  setLocalStateField: (field: string, value: unknown) => void;
+  getStates: () => Map<number, Record<string, unknown>>;
+  on: (event: string, cb: () => void) => void;
+  off?: (event: string, cb: () => void) => void;
+}
+//#endregion
+//#region src/render/collaboration-external-session.d.ts
+/** Connection state reported by the host, independent of the viewer lifetime. */
+interface ExternalCollaborationSnapshot {
+  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
+   * to suspend writes until a fresh sync. The viewer never infers this from
+   * `status` and never opens it after a timeout.
+   */
+  synced: boolean;
+}
+/** The public y-protocols Awareness surface needed by a borrowed session. */
+interface ExternalCollaborationAwareness extends AwarenessLike {
+  clientID: number;
+  getLocalState: () => Record<string, unknown> | null;
+  setLocalState: (state: Record<string, unknown> | null) => void;
+  off: (event: string, callback: () => void) => void;
+}
+/**
+ * Host-owned Yjs resources. The host creates, connects and destroys them.
+ * Keep this object and its resources stable for a session; report connection
+ * changes through subscribe instead of replacing the collaboration config.
+ */
+interface ExternalCollaborationSession {
+  readonly doc: Doc;
+  /** Awareness must belong to doc. One viewer publishes slide presence at a time. */
+  readonly awareness: ExternalCollaborationAwareness;
+  getSnapshot: () => ExternalCollaborationSnapshot;
+  /** Subscribe to status or synced changes; return an unsubscribe function. */
+  subscribe: (listener: () => void) => () => void;
+}
+/** Listener/publisher view, deliberately excluding host lifecycle methods. */
+interface BorrowedCollaborationAwareness extends AwarenessLike {
+  clientID: number;
+  off: (event: string, callback: () => void) => void;
+}
+//#endregion
 //#region src/render/element-update-batch.d.ts
 /** A shallow property patch for a top-level element on an ordinary slide. */
 interface ElementUpdate {
@@ -11637,11 +11692,18 @@ interface CollaborationConfig {
   roomId: string;
   /**
    * WebSocket server URL for the Yjs provider (e.g. "wss://collab.example.com").
-   * Ignored (may be empty) when `transport` is `'webrtc'`.
+   * Ignored (may be empty) for `externalSession` or when `transport` is `'webrtc'`.
    */
   serverUrl: string;
   /** Transport to use. Defaults to `'websocket'`. */
   transport?: CollaborationTransport;
+  /**
+   * Use the host's document, awareness and transport instead of creating a
+   * provider. Transport, serverUrl, signaling and authToken are ignored. The
+   * viewer only detaches its listeners and presence on stop; it never destroys
+   * these resources. Keep this object stable and report readiness via subscribe.
+   */
+  externalSession?: ExternalCollaborationSession;
   /**
    * WebRTC signaling server URLs (only used when `transport` is `'webrtc'`).
    * Defaults to y-webrtc's built-in public signaling list. Same-browser tabs
@@ -12192,7 +12254,9 @@ interface LiveTextSource {
 }
 interface CollaborationLivePatcher {
   /** Attach a live doc (or `null` to go dormant). Pending patches are dropped. */
-  configure: (doc: YDocLike | null, factories: YjsFactories | null) => void;
+  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. */
@@ -15379,12 +15443,14 @@ interface UseYjsProviderResult {
  *
  * The Yjs packages are dynamically imported so they are fully
  * tree-shaken when collaboration is not enabled.
+ * This low-level hook owns built-in transports only. Use useCollaborativeState
+ * (or the full/headless viewer) to attach a host-owned external session.
  */
-declare function useYjsProvider({ config }: UseYjsProviderInput): UseYjsProviderResult;
+declare function useYjsProvider({ config: inputConfig }: UseYjsProviderInput): UseYjsProviderResult;
 //#endregion
 //#region src/viewer/hooks/collaboration/usePresenceTracking.d.ts
 interface UsePresenceTrackingInput {
-  awareness: Awareness | null;
+  awareness: Awareness | BorrowedCollaborationAwareness | null;
   localClientId: number | null;
   userName: string;
   userColor: string;
@@ -15443,56 +15509,22 @@ declare function useCollaborativeHistory({ localClientId: _localClientId, handle
 //#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.
-   */
+  config?: Pick<CollaborationConfig, 'role' | 'onWriteBack' | 'writeBackDebounceMs' | 'externalSession' | 'sessionIntent'>;
   getSourceBytes?: () => Uint8Array | null;
-  /**
-   * Session-level save options (view properties, table styles, tags, deck
-   * properties, ...), built the same way as the Save/Export path
-   * (`buildDeckSaveOptions` in `pptx-viewer-shared`). Without this the
-   * write-back reloaded the source bytes and called `handler.save(slides)`
-   * with NO options, so an owner's write-back file dropped every
-   * session-level edit that lives outside `slides`.
-   */
   getSaveOptions?: () => PptxHandlerSaveOptions;
-  /**
-   * 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;
-  /**
-   * Why the last content load ran. Only a `bootstrap` deck (the host's
-   * `content`) yields to a room that already holds slides; a file the user
-   * opened mid-session is what they asked for and is published instead
-   * (`shouldRoomSlidesReplaceLoad`).
-   */
   loadOrigin?: CollabLoadOrigin;
+  /** External readiness owns this channel together with full-deck writes. */
+  livePatcher?: CollaborationLivePatcher;
+  onReadOnlyChange?: (readOnly: boolean) => void;
 }
-declare function useYjsDocumentSync({ doc, slides, templateElementsBySlideId, setSlides, isConnected, isSynced, config, getSourceBytes, getSaveOptions, loadVersion, loadOrigin }: UseYjsDocumentSyncInput): void;
+declare function useYjsDocumentSync(input: UseYjsDocumentSyncInput): void;
 //#endregion
 //#region src/viewer/hooks/collaboration/useBroadcastFollower.d.ts
 interface UseBroadcastFollowerInput {