@docx-editor.dev/pro 2.10.0 → 2.11.0

package/dist/react/webrtc.d.cts

@@ -0,0 +1,98 @@
+import * as Y from 'yjs';
+import { WebrtcProvider } from 'y-webrtc';
+import { CollaborationIdentity, CollaborationFailure } from '@docx-editor.dev/core/collaboration';
+import { EditorModule } from '@docx-editor.dev/core/editor';
+import { a as CollaborationBootstrap, C as CollaborationSession } from '../session-BH7Qgyp6.cjs';
+export { b as CollaborationIdentityUpdate } from '../session-BH7Qgyp6.cjs';
+import 'y-protocols/awareness';
+
+/** Bootstrap for one WebRTC room. @public */
+type UseWebrtcCollaborationBootstrap = CollaborationBootstrap;
+/** Arguments for {@link UseWebrtcCollaborationReturn.connect}. @public */
+interface UseWebrtcCollaborationConnectOptions {
+    readonly roomId: string;
+    readonly identity: CollaborationIdentity;
+    readonly bootstrap: UseWebrtcCollaborationBootstrap;
+    /**
+     * Admit local edits while the transport is `disconnected`. Buffered updates merge on
+     * reconnect. See {@link CreateDocumentCollaborationOptions.offlineEditing}.
+     */
+    readonly offlineEditing?: boolean;
+    readonly signaling?: readonly string[];
+    readonly iceServers?: readonly RTCIceServer[];
+    readonly password?: string;
+}
+/** Input for {@link useWebrtcCollaboration}. @public */
+interface UseWebrtcCollaborationOptions {
+    /**
+     * Host modules. The hook adds `collaborationModule` when a room is ready.
+     * A host collaboration contribution is a configuration error and throws.
+     */
+    readonly modules?: readonly EditorModule[];
+    /**
+     * Connect this room on mount. Omit it and call
+     * {@link UseWebrtcCollaborationReturn.connect} after the user chooses a room.
+     */
+    readonly room?: UseWebrtcCollaborationConnectOptions | null;
+}
+/** Values {@link useWebrtcCollaboration} returns. @public */
+interface UseWebrtcCollaborationReturn {
+    readonly document: Uint8Array | null;
+    readonly modules: readonly EditorModule[];
+    readonly session: CollaborationSession | null;
+    /**
+     * The room's shared Yjs document, owned by the hook. Null while no room is connected.
+     *
+     * Read-only escape hatch: observe it or wire additional providers, but leave teardown to
+     * the hook.
+     */
+    readonly ydoc: Y.Doc | null;
+    /**
+     * The owned `y-webrtc` provider. Null while no room is connected.
+     *
+     * Read-only escape hatch for transport-level access (`disconnect()`/`connect()`, peer
+     * introspection). The hook destroys it on leave and unmount.
+     */
+    readonly provider: WebrtcProvider | null;
+    readonly pending: boolean;
+    readonly error: CollaborationFailure | null;
+    /**
+     * Connect a room. RESOLVES with the failure, or null on success — it does not reject.
+     *
+     * A rejection carried nothing the resolved value does not, and it made the ordinary call
+     * site wrong by default: `onClick={() => connect(options)}` produced an unhandled rejection
+     * on every failed connect. `error` reports the same failure for renderers.
+     */
+    readonly connect: (options: UseWebrtcCollaborationConnectOptions) => Promise<CollaborationFailure | null>;
+    /**
+     * Destroy the room and carry on editing locally.
+     *
+     * The current bytes live in the editor, not in this hook, so the argument is required:
+     * pass `await editor.save()` to keep what the room typed. The hook remounts the editor
+     * from exactly these bytes.
+     */
+    readonly leave: (nextDocument: Uint8Array) => void;
+    /**
+     * Recover a session that reached status `error`: leave with `nextDocument`, then connect
+     * again to the same room with the same identity, signaling, and password.
+     *
+     * The reconnect always uses bootstrap `{ kind: 'join' }`, because an active room still
+     * exists on the other peers. When no peer holds the room any more, the join rejects with
+     * `initialization-timeout` — nothing is lost, because `nextDocument` (your saved bytes)
+     * stays mounted locally. A connect that failed also counts as the prior attempt, so
+     * rejoin retries it as a joiner.
+     */
+    readonly rejoin: (nextDocument: Uint8Array) => Promise<CollaborationFailure | null>;
+}
+/**
+ * Own a WebRTC collaboration room for a React host.
+ *
+ * The default Pro React entry does not import this hook. Import it from
+ * `@docx-editor.dev/pro/react/webrtc` so a review-only bundle does not load
+ * a network provider.
+ *
+ * @public
+ */
+declare function useWebrtcCollaboration(options?: UseWebrtcCollaborationOptions): UseWebrtcCollaborationReturn;
+
+export { CollaborationSession, type UseWebrtcCollaborationBootstrap, type UseWebrtcCollaborationConnectOptions, type UseWebrtcCollaborationOptions, type UseWebrtcCollaborationReturn, useWebrtcCollaboration };

package/dist/react/webrtc.d.ts

@@ -0,0 +1,98 @@
+import * as Y from 'yjs';
+import { WebrtcProvider } from 'y-webrtc';
+import { CollaborationIdentity, CollaborationFailure } from '@docx-editor.dev/core/collaboration';
+import { EditorModule } from '@docx-editor.dev/core/editor';
+import { a as CollaborationBootstrap, C as CollaborationSession } from '../session-BH7Qgyp6.js';
+export { b as CollaborationIdentityUpdate } from '../session-BH7Qgyp6.js';
+import 'y-protocols/awareness';
+
+/** Bootstrap for one WebRTC room. @public */
+type UseWebrtcCollaborationBootstrap = CollaborationBootstrap;
+/** Arguments for {@link UseWebrtcCollaborationReturn.connect}. @public */
+interface UseWebrtcCollaborationConnectOptions {
+    readonly roomId: string;
+    readonly identity: CollaborationIdentity;
+    readonly bootstrap: UseWebrtcCollaborationBootstrap;
+    /**
+     * Admit local edits while the transport is `disconnected`. Buffered updates merge on
+     * reconnect. See {@link CreateDocumentCollaborationOptions.offlineEditing}.
+     */
+    readonly offlineEditing?: boolean;
+    readonly signaling?: readonly string[];
+    readonly iceServers?: readonly RTCIceServer[];
+    readonly password?: string;
+}
+/** Input for {@link useWebrtcCollaboration}. @public */
+interface UseWebrtcCollaborationOptions {
+    /**
+     * Host modules. The hook adds `collaborationModule` when a room is ready.
+     * A host collaboration contribution is a configuration error and throws.
+     */
+    readonly modules?: readonly EditorModule[];
+    /**
+     * Connect this room on mount. Omit it and call
+     * {@link UseWebrtcCollaborationReturn.connect} after the user chooses a room.
+     */
+    readonly room?: UseWebrtcCollaborationConnectOptions | null;
+}
+/** Values {@link useWebrtcCollaboration} returns. @public */
+interface UseWebrtcCollaborationReturn {
+    readonly document: Uint8Array | null;
+    readonly modules: readonly EditorModule[];
+    readonly session: CollaborationSession | null;
+    /**
+     * The room's shared Yjs document, owned by the hook. Null while no room is connected.
+     *
+     * Read-only escape hatch: observe it or wire additional providers, but leave teardown to
+     * the hook.
+     */
+    readonly ydoc: Y.Doc | null;
+    /**
+     * The owned `y-webrtc` provider. Null while no room is connected.
+     *
+     * Read-only escape hatch for transport-level access (`disconnect()`/`connect()`, peer
+     * introspection). The hook destroys it on leave and unmount.
+     */
+    readonly provider: WebrtcProvider | null;
+    readonly pending: boolean;
+    readonly error: CollaborationFailure | null;
+    /**
+     * Connect a room. RESOLVES with the failure, or null on success — it does not reject.
+     *
+     * A rejection carried nothing the resolved value does not, and it made the ordinary call
+     * site wrong by default: `onClick={() => connect(options)}` produced an unhandled rejection
+     * on every failed connect. `error` reports the same failure for renderers.
+     */
+    readonly connect: (options: UseWebrtcCollaborationConnectOptions) => Promise<CollaborationFailure | null>;
+    /**
+     * Destroy the room and carry on editing locally.
+     *
+     * The current bytes live in the editor, not in this hook, so the argument is required:
+     * pass `await editor.save()` to keep what the room typed. The hook remounts the editor
+     * from exactly these bytes.
+     */
+    readonly leave: (nextDocument: Uint8Array) => void;
+    /**
+     * Recover a session that reached status `error`: leave with `nextDocument`, then connect
+     * again to the same room with the same identity, signaling, and password.
+     *
+     * The reconnect always uses bootstrap `{ kind: 'join' }`, because an active room still
+     * exists on the other peers. When no peer holds the room any more, the join rejects with
+     * `initialization-timeout` — nothing is lost, because `nextDocument` (your saved bytes)
+     * stays mounted locally. A connect that failed also counts as the prior attempt, so
+     * rejoin retries it as a joiner.
+     */
+    readonly rejoin: (nextDocument: Uint8Array) => Promise<CollaborationFailure | null>;
+}
+/**
+ * Own a WebRTC collaboration room for a React host.
+ *
+ * The default Pro React entry does not import this hook. Import it from
+ * `@docx-editor.dev/pro/react/webrtc` so a review-only bundle does not load
+ * a network provider.
+ *
+ * @public
+ */
+declare function useWebrtcCollaboration(options?: UseWebrtcCollaborationOptions): UseWebrtcCollaborationReturn;
+
+export { CollaborationSession, type UseWebrtcCollaborationBootstrap, type UseWebrtcCollaborationConnectOptions, type UseWebrtcCollaborationOptions, type UseWebrtcCollaborationReturn, useWebrtcCollaboration };

package/dist/react/webrtc.js

@@ -0,0 +1 @@
+import {b as b$1,a}from'../chunk-HJB77VBO.js';import'../chunk-Q2VBO66F.js';import {useId,useMemo}from'react';var s=Symbol("useWebrtcCollaboration.createRoom");function c(o){return o?`${o.signaling?o.signaling.join(","):""}:${o.roomId}:${o.bootstrap.kind}:${o.identity.actorId}`:""}async function d(o){let{createWebrtcCollaboration:t}=await import('../collaboration/webrtc.js');return t(o)}function b(o){return o[s]??d}function p(o={}){let t=useId(),e=b$1({ownerKey:`react-webrtc:${t}`,hookName:"useWebrtcCollaboration",createRoom:b(o),hostModules:o.modules??a,autoRoom:o.room??null,autoKey:c(o.room??null),rejoinOptionsOf:r=>({...r,bootstrap:{kind:"join"}}),identityOf:r=>r.identity});return useMemo(()=>({document:e.document,modules:e.modules,session:e.session,ydoc:e.room?.ydoc??null,provider:e.room?.provider??null,pending:e.pending,error:e.error,connect:e.connect,leave:e.leave,rejoin:e.rejoin}),[e])}export{p as useWebrtcCollaboration};

package/dist/room-id-BfudXOZz.d.cts

@@ -0,0 +1,13 @@
+/**
+ * Room identifier helpers shared by the provider convenience wrappers.
+ *
+ * The WebRTC and Hocuspocus factories validate the same room-id shape. This module holds
+ * the rule once, with no provider import, so each provider subpath re-exports it without
+ * dragging in the other provider's package.
+ */
+/** Create a cryptographically strong room identifier. It is not an authorization token. @public */
+declare function createCollaborationRoomId(): string;
+/** Validate and normalize a room identifier from a host interface. @public */
+declare function validateRoomId(value: string): string;
+
+export { createCollaborationRoomId as c, validateRoomId as v };

package/dist/room-id-BfudXOZz.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Room identifier helpers shared by the provider convenience wrappers.
+ *
+ * The WebRTC and Hocuspocus factories validate the same room-id shape. This module holds
+ * the rule once, with no provider import, so each provider subpath re-exports it without
+ * dragging in the other provider's package.
+ */
+/** Create a cryptographically strong room identifier. It is not an authorization token. @public */
+declare function createCollaborationRoomId(): string;
+/** Validate and normalize a room identifier from a host interface. @public */
+declare function validateRoomId(value: string): string;
+
+export { createCollaborationRoomId as c, validateRoomId as v };

package/dist/session-BH7Qgyp6.d.cts

@@ -0,0 +1,140 @@
+import * as Y from 'yjs';
+import { Awareness } from 'y-protocols/awareness';
+import { CollaborationIdentity, CollaborationStatus, CollaborationStatusSnapshot, CollaborationFailureCode, CollaborationParticipant, CollaborationRemoteSelection, EditorCollaborationSession } from '@docx-editor.dev/core/collaboration';
+
+/**
+ * Create or join bootstrap for one collaboration replica.
+ *
+ * Text, document, and WebRTC factories share this union.
+ *
+ * `create-or-join` removes the out-of-band decision about which peer creates a room.
+ * The replica probes for an initialized room and joins it when one appears. Otherwise it
+ * runs a short awareness election and only the winning candidate seeds from `document`.
+ * A room that two peers seeded concurrently reports the terminal failure code
+ * `concurrent-seed` on every replica. The document and WebRTC factories accept this kind;
+ * the experimental text factory refuses it.
+ * @public
+ */
+type CollaborationBootstrap = {
+    readonly kind: 'create';
+    readonly document: Uint8Array;
+} | {
+    readonly kind: 'join';
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+} | {
+    readonly kind: 'create-or-join';
+    readonly document: Uint8Array;
+    /** Wait for an existing initialized room before the seed election. Default 4000 ms. */
+    readonly probeTimeoutMs?: number;
+    /** Seed election window after an empty probe. Default 1500 ms. */
+    readonly electionWindowMs?: number;
+    /** Join wait after this replica loses the seed election. Default 30000 ms. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+};
+/**
+ * Display-identity fields a live session can update.
+ *
+ * `actorId` and `role` are attribution and stay immutable for the session lifetime, so this
+ * type cannot name them.
+ * @public
+ */
+interface CollaborationIdentityUpdate {
+    readonly name?: string;
+    readonly color?: string;
+}
+/**
+ * Host-facing collaboration session.
+ *
+ * A host reads identity, status, presence, and undo. The editor attaches
+ * {@link EditorCollaborationSession} internally and never through this type.
+ * @public
+ */
+interface CollaborationSession {
+    readonly documentId: string;
+    /** Unique identity for this attachment lifetime. */
+    readonly sessionId: string;
+    readonly identity: CollaborationIdentity;
+    /**
+     * Update the display name and color mid-session, when the replica supports it.
+     *
+     * Full-document sessions implement this and republish presence at once. A replica that
+     * freezes identity for its lifetime omits it.
+     */
+    setIdentity?(update: CollaborationIdentityUpdate): void;
+    status(): CollaborationStatus;
+    /**
+     * Cached status, current reason, and last failure.
+     *
+     * Same reference until any of those values change.
+     */
+    statusSnapshot(): CollaborationStatusSnapshot;
+    subscribeStatus(listener: (status: CollaborationStatus, reason?: CollaborationFailureCode, detail?: string) => void): () => void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    undo(): boolean;
+    redo(): boolean;
+    participants(): readonly CollaborationParticipant[];
+    subscribeParticipants(listener: (participants: readonly CollaborationParticipant[]) => void): () => void;
+    remoteSelections(): readonly CollaborationRemoteSelection[];
+    subscribeRemoteSelections(listener: (selections: readonly CollaborationRemoteSelection[]) => void): () => void;
+}
+/**
+ * Options for the experimental paragraph-text replica of {@link createTextCollaboration}.
+ *
+ * The caller owns `ydoc`.
+ * @beta
+ */
+interface CreateTextCollaborationOptions {
+    readonly ydoc: Y.Doc;
+    readonly awareness: Awareness;
+    readonly documentId: string;
+    /** Unique attachment identity. Omit it to generate a new identity for this session. */
+    readonly sessionId?: string;
+    readonly identity: CollaborationIdentity;
+    readonly bootstrap: CollaborationBootstrap;
+}
+/**
+ * Engine-facing paragraph-text session, including attach and operation gating.
+ *
+ * Hosts consume {@link CollaborationSession}. Providers call `setTransportStatus`.
+ * @public
+ */
+interface TextCollaborationSession extends EditorCollaborationSession {
+    /**
+     * Provider convenience seam. Low-level consumers normally leave the session ready.
+     *
+     * `reason` is a typed code so a host can branch on it: pass `'transport-disconnected'` for
+     * a socket that will retry itself and `'authentication-failed'` for a credential the server
+     * rejected, because those need opposite responses. The provider's own phrasing goes in
+     * `detail`.
+     */
+    setTransportStatus(status: 'ready' | 'disconnected' | 'error', reason?: CollaborationFailureCode, detail?: string): void;
+}
+/**
+ * Owned collaboration replica: document bytes, session, and teardown.
+ *
+ * Text and document factories share this shape. A host reads
+ * {@link CollaborationSession}; the engine session remains assignable.
+ * @public
+ */
+interface CollaborationHandle<TSession extends CollaborationSession> {
+    readonly document: Uint8Array;
+    readonly session: TSession;
+    destroy(): void;
+}
+/** Owned replica of the experimental {@link createTextCollaboration} factory. @beta */
+type TextCollaborationHandle = CollaborationHandle<TextCollaborationSession>;
+/**
+ * Create or join one experimental paragraph-text collaboration replica.
+ *
+ * This replica shares only the body paragraph text of an unchanging paragraph set: no
+ * formatting, no structure, no images. Use {@link createDocumentCollaboration} for
+ * full-document collaboration; this factory remains for hosts that want to replicate plain
+ * paragraph text and nothing else. The caller owns `ydoc`.
+ * @beta
+ */
+declare function createTextCollaboration(options: CreateTextCollaborationOptions): Promise<TextCollaborationHandle>;
+
+export { type CollaborationSession as C, type TextCollaborationHandle as T, type CollaborationBootstrap as a, type CollaborationIdentityUpdate as b, type CollaborationHandle as c, type CreateTextCollaborationOptions as d, type TextCollaborationSession as e, createTextCollaboration as f };

package/dist/session-BH7Qgyp6.d.ts

@@ -0,0 +1,140 @@
+import * as Y from 'yjs';
+import { Awareness } from 'y-protocols/awareness';
+import { CollaborationIdentity, CollaborationStatus, CollaborationStatusSnapshot, CollaborationFailureCode, CollaborationParticipant, CollaborationRemoteSelection, EditorCollaborationSession } from '@docx-editor.dev/core/collaboration';
+
+/**
+ * Create or join bootstrap for one collaboration replica.
+ *
+ * Text, document, and WebRTC factories share this union.
+ *
+ * `create-or-join` removes the out-of-band decision about which peer creates a room.
+ * The replica probes for an initialized room and joins it when one appears. Otherwise it
+ * runs a short awareness election and only the winning candidate seeds from `document`.
+ * A room that two peers seeded concurrently reports the terminal failure code
+ * `concurrent-seed` on every replica. The document and WebRTC factories accept this kind;
+ * the experimental text factory refuses it.
+ * @public
+ */
+type CollaborationBootstrap = {
+    readonly kind: 'create';
+    readonly document: Uint8Array;
+} | {
+    readonly kind: 'join';
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+} | {
+    readonly kind: 'create-or-join';
+    readonly document: Uint8Array;
+    /** Wait for an existing initialized room before the seed election. Default 4000 ms. */
+    readonly probeTimeoutMs?: number;
+    /** Seed election window after an empty probe. Default 1500 ms. */
+    readonly electionWindowMs?: number;
+    /** Join wait after this replica loses the seed election. Default 30000 ms. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+};
+/**
+ * Display-identity fields a live session can update.
+ *
+ * `actorId` and `role` are attribution and stay immutable for the session lifetime, so this
+ * type cannot name them.
+ * @public
+ */
+interface CollaborationIdentityUpdate {
+    readonly name?: string;
+    readonly color?: string;
+}
+/**
+ * Host-facing collaboration session.
+ *
+ * A host reads identity, status, presence, and undo. The editor attaches
+ * {@link EditorCollaborationSession} internally and never through this type.
+ * @public
+ */
+interface CollaborationSession {
+    readonly documentId: string;
+    /** Unique identity for this attachment lifetime. */
+    readonly sessionId: string;
+    readonly identity: CollaborationIdentity;
+    /**
+     * Update the display name and color mid-session, when the replica supports it.
+     *
+     * Full-document sessions implement this and republish presence at once. A replica that
+     * freezes identity for its lifetime omits it.
+     */
+    setIdentity?(update: CollaborationIdentityUpdate): void;
+    status(): CollaborationStatus;
+    /**
+     * Cached status, current reason, and last failure.
+     *
+     * Same reference until any of those values change.
+     */
+    statusSnapshot(): CollaborationStatusSnapshot;
+    subscribeStatus(listener: (status: CollaborationStatus, reason?: CollaborationFailureCode, detail?: string) => void): () => void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    undo(): boolean;
+    redo(): boolean;
+    participants(): readonly CollaborationParticipant[];
+    subscribeParticipants(listener: (participants: readonly CollaborationParticipant[]) => void): () => void;
+    remoteSelections(): readonly CollaborationRemoteSelection[];
+    subscribeRemoteSelections(listener: (selections: readonly CollaborationRemoteSelection[]) => void): () => void;
+}
+/**
+ * Options for the experimental paragraph-text replica of {@link createTextCollaboration}.
+ *
+ * The caller owns `ydoc`.
+ * @beta
+ */
+interface CreateTextCollaborationOptions {
+    readonly ydoc: Y.Doc;
+    readonly awareness: Awareness;
+    readonly documentId: string;
+    /** Unique attachment identity. Omit it to generate a new identity for this session. */
+    readonly sessionId?: string;
+    readonly identity: CollaborationIdentity;
+    readonly bootstrap: CollaborationBootstrap;
+}
+/**
+ * Engine-facing paragraph-text session, including attach and operation gating.
+ *
+ * Hosts consume {@link CollaborationSession}. Providers call `setTransportStatus`.
+ * @public
+ */
+interface TextCollaborationSession extends EditorCollaborationSession {
+    /**
+     * Provider convenience seam. Low-level consumers normally leave the session ready.
+     *
+     * `reason` is a typed code so a host can branch on it: pass `'transport-disconnected'` for
+     * a socket that will retry itself and `'authentication-failed'` for a credential the server
+     * rejected, because those need opposite responses. The provider's own phrasing goes in
+     * `detail`.
+     */
+    setTransportStatus(status: 'ready' | 'disconnected' | 'error', reason?: CollaborationFailureCode, detail?: string): void;
+}
+/**
+ * Owned collaboration replica: document bytes, session, and teardown.
+ *
+ * Text and document factories share this shape. A host reads
+ * {@link CollaborationSession}; the engine session remains assignable.
+ * @public
+ */
+interface CollaborationHandle<TSession extends CollaborationSession> {
+    readonly document: Uint8Array;
+    readonly session: TSession;
+    destroy(): void;
+}
+/** Owned replica of the experimental {@link createTextCollaboration} factory. @beta */
+type TextCollaborationHandle = CollaborationHandle<TextCollaborationSession>;
+/**
+ * Create or join one experimental paragraph-text collaboration replica.
+ *
+ * This replica shares only the body paragraph text of an unchanging paragraph set: no
+ * formatting, no structure, no images. Use {@link createDocumentCollaboration} for
+ * full-document collaboration; this factory remains for hosts that want to replicate plain
+ * paragraph text and nothing else. The caller owns `ydoc`.
+ * @beta
+ */
+declare function createTextCollaboration(options: CreateTextCollaborationOptions): Promise<TextCollaborationHandle>;
+
+export { type CollaborationSession as C, type TextCollaborationHandle as T, type CollaborationBootstrap as a, type CollaborationIdentityUpdate as b, type CollaborationHandle as c, type CreateTextCollaborationOptions as d, type TextCollaborationSession as e, createTextCollaboration as f };

package/dist/session-okdqygLg.d.cts

@@ -0,0 +1,82 @@
+import { CollaborationIdentity, CollaborationStatus, CollaborationStatusSnapshot, CollaborationFailureCode, CollaborationParticipant, CollaborationRemoteSelection } from '@docx-editor.dev/core/collaboration';
+
+/**
+ * Create or join bootstrap for one collaboration replica.
+ *
+ * Text, document, and WebRTC factories share this union.
+ *
+ * `create-or-join` removes the out-of-band decision about which peer creates a room.
+ * The replica probes for an initialized room and joins it when one appears. Otherwise it
+ * runs a short awareness election and only the winning candidate seeds from `document`.
+ * A room that two peers seeded concurrently reports the terminal failure code
+ * `concurrent-seed` on every replica. The document and WebRTC factories accept this kind;
+ * the experimental text factory refuses it.
+ * @public
+ */
+type CollaborationBootstrap = {
+    readonly kind: 'create';
+    readonly document: Uint8Array;
+} | {
+    readonly kind: 'join';
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+} | {
+    readonly kind: 'create-or-join';
+    readonly document: Uint8Array;
+    /** Wait for an existing initialized room before the seed election. Default 4000 ms. */
+    readonly probeTimeoutMs?: number;
+    /** Seed election window after an empty probe. Default 1500 ms. */
+    readonly electionWindowMs?: number;
+    /** Join wait after this replica loses the seed election. Default 30000 ms. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+};
+/**
+ * Display-identity fields a live session can update.
+ *
+ * `actorId` and `role` are attribution and stay immutable for the session lifetime, so this
+ * type cannot name them.
+ * @public
+ */
+interface CollaborationIdentityUpdate {
+    readonly name?: string;
+    readonly color?: string;
+}
+/**
+ * Host-facing collaboration session.
+ *
+ * A host reads identity, status, presence, and undo. The editor attaches
+ * {@link EditorCollaborationSession} internally and never through this type.
+ * @public
+ */
+interface CollaborationSession {
+    readonly documentId: string;
+    /** Unique identity for this attachment lifetime. */
+    readonly sessionId: string;
+    readonly identity: CollaborationIdentity;
+    /**
+     * Update the display name and color mid-session, when the replica supports it.
+     *
+     * Full-document sessions implement this and republish presence at once. A replica that
+     * freezes identity for its lifetime omits it.
+     */
+    setIdentity?(update: CollaborationIdentityUpdate): void;
+    status(): CollaborationStatus;
+    /**
+     * Cached status, current reason, and last failure.
+     *
+     * Same reference until any of those values change.
+     */
+    statusSnapshot(): CollaborationStatusSnapshot;
+    subscribeStatus(listener: (status: CollaborationStatus, reason?: CollaborationFailureCode, detail?: string) => void): () => void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    undo(): boolean;
+    redo(): boolean;
+    participants(): readonly CollaborationParticipant[];
+    subscribeParticipants(listener: (participants: readonly CollaborationParticipant[]) => void): () => void;
+    remoteSelections(): readonly CollaborationRemoteSelection[];
+    subscribeRemoteSelections(listener: (selections: readonly CollaborationRemoteSelection[]) => void): () => void;
+}
+
+export type { CollaborationSession as C, CollaborationBootstrap as a, CollaborationIdentityUpdate as b };

package/dist/session-okdqygLg.d.ts

@@ -0,0 +1,82 @@
+import { CollaborationIdentity, CollaborationStatus, CollaborationStatusSnapshot, CollaborationFailureCode, CollaborationParticipant, CollaborationRemoteSelection } from '@docx-editor.dev/core/collaboration';
+
+/**
+ * Create or join bootstrap for one collaboration replica.
+ *
+ * Text, document, and WebRTC factories share this union.
+ *
+ * `create-or-join` removes the out-of-band decision about which peer creates a room.
+ * The replica probes for an initialized room and joins it when one appears. Otherwise it
+ * runs a short awareness election and only the winning candidate seeds from `document`.
+ * A room that two peers seeded concurrently reports the terminal failure code
+ * `concurrent-seed` on every replica. The document and WebRTC factories accept this kind;
+ * the experimental text factory refuses it.
+ * @public
+ */
+type CollaborationBootstrap = {
+    readonly kind: 'create';
+    readonly document: Uint8Array;
+} | {
+    readonly kind: 'join';
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+} | {
+    readonly kind: 'create-or-join';
+    readonly document: Uint8Array;
+    /** Wait for an existing initialized room before the seed election. Default 4000 ms. */
+    readonly probeTimeoutMs?: number;
+    /** Seed election window after an empty probe. Default 1500 ms. */
+    readonly electionWindowMs?: number;
+    /** Join wait after this replica loses the seed election. Default 30000 ms. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+};
+/**
+ * Display-identity fields a live session can update.
+ *
+ * `actorId` and `role` are attribution and stay immutable for the session lifetime, so this
+ * type cannot name them.
+ * @public
+ */
+interface CollaborationIdentityUpdate {
+    readonly name?: string;
+    readonly color?: string;
+}
+/**
+ * Host-facing collaboration session.
+ *
+ * A host reads identity, status, presence, and undo. The editor attaches
+ * {@link EditorCollaborationSession} internally and never through this type.
+ * @public
+ */
+interface CollaborationSession {
+    readonly documentId: string;
+    /** Unique identity for this attachment lifetime. */
+    readonly sessionId: string;
+    readonly identity: CollaborationIdentity;
+    /**
+     * Update the display name and color mid-session, when the replica supports it.
+     *
+     * Full-document sessions implement this and republish presence at once. A replica that
+     * freezes identity for its lifetime omits it.
+     */
+    setIdentity?(update: CollaborationIdentityUpdate): void;
+    status(): CollaborationStatus;
+    /**
+     * Cached status, current reason, and last failure.
+     *
+     * Same reference until any of those values change.
+     */
+    statusSnapshot(): CollaborationStatusSnapshot;
+    subscribeStatus(listener: (status: CollaborationStatus, reason?: CollaborationFailureCode, detail?: string) => void): () => void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    undo(): boolean;
+    redo(): boolean;
+    participants(): readonly CollaborationParticipant[];
+    subscribeParticipants(listener: (participants: readonly CollaborationParticipant[]) => void): () => void;
+    remoteSelections(): readonly CollaborationRemoteSelection[];
+    subscribeRemoteSelections(listener: (selections: readonly CollaborationRemoteSelection[]) => void): () => void;
+}
+
+export type { CollaborationSession as C, CollaborationBootstrap as a, CollaborationIdentityUpdate as b };