superdoc 2.12.1-next.3 → 2.13.0-next.10

package/dist/style.css

@@ -1818,11 +1818,11 @@ img[data-v-c95b2073] {
   pointer-events: auto;
 }
 
-.superdoc[data-v-770204b4] {
+.superdoc[data-v-ebe9a1fb] {
   display: flex;
   position: relative;
 }
-.sd-visually-hidden[data-v-770204b4] {
+.sd-visually-hidden[data-v-ebe9a1fb] {
   position: absolute;
   width: 1px;
   height: 1px;
@@ -1833,14 +1833,14 @@ img[data-v-c95b2073] {
   white-space: nowrap;
   border: 0;
 }
-.superdoc__mutation-status[data-v-770204b4] {
+.superdoc__mutation-status[data-v-ebe9a1fb] {
   position: sticky;
   z-index: 10;
   top: 12px;
   height: 0;
   pointer-events: none;
 }
-.superdoc__edit-rejected-status[data-v-770204b4] {
+.superdoc__edit-rejected-status[data-v-ebe9a1fb] {
   position: absolute;
   top: 0;
   left: 50%;
@@ -1858,30 +1858,30 @@ img[data-v-c95b2073] {
   line-height: 20px;
   pointer-events: none;
 }
-.right-sidebar[data-v-770204b4] {
+.right-sidebar[data-v-ebe9a1fb] {
   min-width: 320px;
   height: 100%;
 }
-.floating-comments[data-v-770204b4] {
+.floating-comments[data-v-ebe9a1fb] {
   min-width: 300px;
   width: 300px;
   height: 100%;
   overflow: visible;
 }
-.superdoc__layers[data-v-770204b4] {
+.superdoc__layers[data-v-ebe9a1fb] {
   height: 100%;
   position: relative;
   box-sizing: border-box;
 }
-.superdoc__document[data-v-770204b4] {
+.superdoc__document[data-v-ebe9a1fb] {
   width: 100%;
   position: relative;
 }
-.superdoc__sub-document[data-v-770204b4] {
+.superdoc__sub-document[data-v-ebe9a1fb] {
   width: 100%;
   position: relative;
 }
-.superdoc__selection-layer[data-v-770204b4] {
+.superdoc__selection-layer[data-v-ebe9a1fb] {
   position: absolute;
   min-width: 100%;
   min-height: 100%;
@@ -1892,13 +1892,13 @@ img[data-v-c95b2073] {
 /* SD-3497: PDF whiteboard overlay sits above the rendered PDF canvas but below
    the PDF comment anchors (z-index 6 in PdfCommentsLayer) so anchors stay
    clickable, and below the selection layer (z-index 10). */
-.superdoc__whiteboard-layer[data-v-770204b4] {
+.superdoc__whiteboard-layer[data-v-ebe9a1fb] {
   z-index: 4;
 }
-.superdoc__temp-selection[data-v-770204b4] {
+.superdoc__temp-selection[data-v-ebe9a1fb] {
   position: absolute;
 }
-.superdoc__right-sidebar[data-v-770204b4] {
+.superdoc__right-sidebar[data-v-ebe9a1fb] {
   width: 320px;
   min-width: 320px;
   padding: 0 10px;
@@ -1906,7 +1906,7 @@ img[data-v-c95b2073] {
   position: relative;
   z-index: 2;
 }
-.superdoc__compact-comment-popover[data-v-770204b4] {
+.superdoc__compact-comment-popover[data-v-ebe9a1fb] {
   position: absolute;
   top: 12px;
   right: 12px;
@@ -1915,14 +1915,14 @@ img[data-v-c95b2073] {
 }
 
 /* Tools styles */
-.tools[data-v-770204b4] {
+.tools[data-v-ebe9a1fb] {
   position: absolute;
   z-index: 3;
   display: flex;
   flex-direction: column;
   gap: var(--sd-ui-tools-gap, 6px);
 }
-.tools-item[data-v-770204b4] {
+.tools-item[data-v-ebe9a1fb] {
   display: flex;
   align-items: center;
   justify-content: center;
@@ -1933,10 +1933,10 @@ img[data-v-c95b2073] {
   cursor: pointer;
   position: relative;
 }
-.tools-item i[data-v-770204b4] {
+.tools-item i[data-v-ebe9a1fb] {
   cursor: pointer;
 }
-.superdoc__tools-icon[data-v-770204b4] {
+.superdoc__tools-icon[data-v-ebe9a1fb] {
   width: var(--sd-ui-tools-icon-size, 20px);
   height: var(--sd-ui-tools-icon-size, 20px);
   flex-shrink: 0;
@@ -1951,22 +1951,22 @@ img[data-v-c95b2073] {
 
 /* 834px is iPad screen size in portrait orientation */
 @media (max-width: 834px) {
-.superdoc .superdoc__layers[data-v-770204b4] {
+.superdoc .superdoc__layers[data-v-ebe9a1fb] {
     margin: 0;
     border: 0 !important;
     box-shadow: none;
 }
-.superdoc__sub-document[data-v-770204b4] {
+.superdoc__sub-document[data-v-ebe9a1fb] {
     max-width: 100%;
 }
-.superdoc__right-sidebar[data-v-770204b4] {
+.superdoc__right-sidebar[data-v-ebe9a1fb] {
     padding: 10px;
     position: relative;
 }
 }
 
 /* AI Writer styles */
-.ai-writer-container[data-v-770204b4] {
+.ai-writer-container[data-v-ebe9a1fb] {
   position: fixed;
   z-index: 1000;
   background: white;
@@ -1982,10 +1982,10 @@ img[data-v-c95b2073] {
   transform: translateY(-50%);
   z-index: 50;
 } */
-.ai-tool > svg[data-v-770204b4] {
+.ai-tool > svg[data-v-ebe9a1fb] {
   fill: transparent;
 }
-.ai-tool[data-v-770204b4]::before {
+.ai-tool[data-v-ebe9a1fb]::before {
   content: '';
   position: absolute;
   width: 20px;
@@ -2006,7 +2006,7 @@ img[data-v-c95b2073] {
   filter: brightness(1.2);
   transition: filter 0.2s ease;
 }
-.ai-tool[data-v-770204b4]:hover::before {
+.ai-tool[data-v-ebe9a1fb]:hover::before {
   filter: brightness(1.3);
 }
 
@@ -2359,7 +2359,7 @@ img[data-v-c95b2073] {
   transform: scale(1);
 }
 
-.superdoc-toolbar-overflow[data-v-975959f9] {
+.superdoc-toolbar-overflow[data-v-5f8ee279] {
   min-width: auto !important;
   max-width: 200px;
   flex-wrap: wrap;

package/dist/style.layered.css

@@ -1818,11 +1818,11 @@ img[data-v-c95b2073] {
   pointer-events: auto;
 }
 
-.superdoc[data-v-770204b4] {
+.superdoc[data-v-ebe9a1fb] {
   display: flex;
   position: relative;
 }
-.sd-visually-hidden[data-v-770204b4] {
+.sd-visually-hidden[data-v-ebe9a1fb] {
   position: absolute;
   width: 1px;
   height: 1px;
@@ -1833,14 +1833,14 @@ img[data-v-c95b2073] {
   white-space: nowrap;
   border: 0;
 }
-.superdoc__mutation-status[data-v-770204b4] {
+.superdoc__mutation-status[data-v-ebe9a1fb] {
   position: sticky;
   z-index: 10;
   top: 12px;
   height: 0;
   pointer-events: none;
 }
-.superdoc__edit-rejected-status[data-v-770204b4] {
+.superdoc__edit-rejected-status[data-v-ebe9a1fb] {
   position: absolute;
   top: 0;
   left: 50%;
@@ -1858,30 +1858,30 @@ img[data-v-c95b2073] {
   line-height: 20px;
   pointer-events: none;
 }
-.right-sidebar[data-v-770204b4] {
+.right-sidebar[data-v-ebe9a1fb] {
   min-width: 320px;
   height: 100%;
 }
-.floating-comments[data-v-770204b4] {
+.floating-comments[data-v-ebe9a1fb] {
   min-width: 300px;
   width: 300px;
   height: 100%;
   overflow: visible;
 }
-.superdoc__layers[data-v-770204b4] {
+.superdoc__layers[data-v-ebe9a1fb] {
   height: 100%;
   position: relative;
   box-sizing: border-box;
 }
-.superdoc__document[data-v-770204b4] {
+.superdoc__document[data-v-ebe9a1fb] {
   width: 100%;
   position: relative;
 }
-.superdoc__sub-document[data-v-770204b4] {
+.superdoc__sub-document[data-v-ebe9a1fb] {
   width: 100%;
   position: relative;
 }
-.superdoc__selection-layer[data-v-770204b4] {
+.superdoc__selection-layer[data-v-ebe9a1fb] {
   position: absolute;
   min-width: 100%;
   min-height: 100%;
@@ -1892,13 +1892,13 @@ img[data-v-c95b2073] {
 /* SD-3497: PDF whiteboard overlay sits above the rendered PDF canvas but below
    the PDF comment anchors (z-index 6 in PdfCommentsLayer) so anchors stay
    clickable, and below the selection layer (z-index 10). */
-.superdoc__whiteboard-layer[data-v-770204b4] {
+.superdoc__whiteboard-layer[data-v-ebe9a1fb] {
   z-index: 4;
 }
-.superdoc__temp-selection[data-v-770204b4] {
+.superdoc__temp-selection[data-v-ebe9a1fb] {
   position: absolute;
 }
-.superdoc__right-sidebar[data-v-770204b4] {
+.superdoc__right-sidebar[data-v-ebe9a1fb] {
   width: 320px;
   min-width: 320px;
   padding: 0 10px;
@@ -1906,7 +1906,7 @@ img[data-v-c95b2073] {
   position: relative;
   z-index: 2;
 }
-.superdoc__compact-comment-popover[data-v-770204b4] {
+.superdoc__compact-comment-popover[data-v-ebe9a1fb] {
   position: absolute;
   top: 12px;
   right: 12px;
@@ -1915,14 +1915,14 @@ img[data-v-c95b2073] {
 }
 
 /* Tools styles */
-.tools[data-v-770204b4] {
+.tools[data-v-ebe9a1fb] {
   position: absolute;
   z-index: 3;
   display: flex;
   flex-direction: column;
   gap: var(--sd-ui-tools-gap, 6px);
 }
-.tools-item[data-v-770204b4] {
+.tools-item[data-v-ebe9a1fb] {
   display: flex;
   align-items: center;
   justify-content: center;
@@ -1933,10 +1933,10 @@ img[data-v-c95b2073] {
   cursor: pointer;
   position: relative;
 }
-.tools-item i[data-v-770204b4] {
+.tools-item i[data-v-ebe9a1fb] {
   cursor: pointer;
 }
-.superdoc__tools-icon[data-v-770204b4] {
+.superdoc__tools-icon[data-v-ebe9a1fb] {
   width: var(--sd-ui-tools-icon-size, 20px);
   height: var(--sd-ui-tools-icon-size, 20px);
   flex-shrink: 0;
@@ -1951,22 +1951,22 @@ img[data-v-c95b2073] {
 
 /* 834px is iPad screen size in portrait orientation */
 @media (max-width: 834px) {
-.superdoc .superdoc__layers[data-v-770204b4] {
+.superdoc .superdoc__layers[data-v-ebe9a1fb] {
     margin: 0;
     border: 0 !important;
     box-shadow: none;
 }
-.superdoc__sub-document[data-v-770204b4] {
+.superdoc__sub-document[data-v-ebe9a1fb] {
     max-width: 100%;
 }
-.superdoc__right-sidebar[data-v-770204b4] {
+.superdoc__right-sidebar[data-v-ebe9a1fb] {
     padding: 10px;
     position: relative;
 }
 }
 
 /* AI Writer styles */
-.ai-writer-container[data-v-770204b4] {
+.ai-writer-container[data-v-ebe9a1fb] {
   position: fixed;
   z-index: 1000;
   background: white;
@@ -1982,10 +1982,10 @@ img[data-v-c95b2073] {
   transform: translateY(-50%);
   z-index: 50;
 } */
-.ai-tool > svg[data-v-770204b4] {
+.ai-tool > svg[data-v-ebe9a1fb] {
   fill: transparent;
 }
-.ai-tool[data-v-770204b4]::before {
+.ai-tool[data-v-ebe9a1fb]::before {
   content: '';
   position: absolute;
   width: 20px;
@@ -2006,7 +2006,7 @@ img[data-v-c95b2073] {
   filter: brightness(1.2);
   transition: filter 0.2s ease;
 }
-.ai-tool[data-v-770204b4]:hover::before {
+.ai-tool[data-v-ebe9a1fb]:hover::before {
   filter: brightness(1.3);
 }
 
@@ -2359,7 +2359,7 @@ img[data-v-c95b2073] {
   transform: scale(1);
 }
 
-.superdoc-toolbar-overflow[data-v-975959f9] {
+.superdoc-toolbar-overflow[data-v-5f8ee279] {
   min-width: auto !important;
   max-width: 200px;
   flex-wrap: wrap;

package/dist/superdoc/src/core/collaboration/collaboration-exception.d.ts

@@ -0,0 +1,2 @@
+import { SuperDocExceptionCollaborationPayload } from '../types/index.js';
+export declare function createCollaborationException(code: string, documentId: string | null): SuperDocExceptionCollaborationPayload | null;

package/dist/superdoc/src/core/collaboration/resolve-v2-collaboration-target.d.ts

@@ -7,20 +7,20 @@
  * first-class single-doc provider families — y-websocket, Hocuspocus, and
  * Liveblocks — each bound to one `Y.Doc`, one provider session, and one
  * awareness channel (implemented inside the bundled v2 runtime) and surfaced
- * publicly through {@link V2CollaborationConfig} (`Document.v2Collaboration`).
+ * publicly through {@link DocumentCollaborationConfig} (`Document.collaboration`).
  *
  * The resolver never returns a "maybe collaborative" result: it either returns
  * a normalized, supported target or a stable, redacted diagnostic. Tokens, auth
  * keys, auth endpoints, and query strings are never echoed back in diagnostics.
  */
 /** Provider families the shipped v2 single-doc runtime can drive. */
-export type SupportedV2ProviderFamily = 'y-websocket' | 'hocuspocus' | 'liveblocks';
+export type SupportedV2ProviderFamily = 'y-websocket' | 'hocuspocus' | 'liveblocks' | 'extension';
 /**
  * Stable, machine-readable reasons a target cannot be treated as a supported v2
  * collaboration room. These strings are part of the diagnostic contract and are
  * safe to assert against in tests; they never carry caller-provided values.
  */
-export type V2CollaborationUnsupportedReason = 'missing-target' | 'invalid-document-id' | 'invalid-server-url' | 'invalid-room-mode' | 'invalid-auth-endpoint' | 'missing-auth' | 'mixed-auth' | 'unsupported-document-type' | 'unsupported-multi-document' | 'unsupported-legacy-provider' | 'unsupported-provider-family';
+export type V2CollaborationUnsupportedReason = 'missing-target' | 'invalid-document-id' | 'invalid-server-url' | 'invalid-room-mode' | 'invalid-auth-endpoint' | 'invalid-adapter-id' | 'invalid-provider-options' | 'missing-auth' | 'mixed-auth' | 'unsupported-document-type' | 'unsupported-multi-document' | 'unsupported-legacy-provider' | 'unsupported-provider-family';
 /**
  * Normalized, supported v2 collaboration room target.
  *
@@ -38,11 +38,15 @@ export interface NormalizedV2CollaborationTarget {
     /** Optional connection query params (e.g. auth token) forwarded verbatim. */
     params?: Record<string, string>;
     /** Hocuspocus auth-message token. */
-    token?: string;
+    token?: string | (() => string | Promise<string>);
     /** Liveblocks anonymous public key auth mode. */
     publicApiKey?: string;
     /** Liveblocks server-side auth endpoint mode. */
     authEndpoint?: string;
+    /** Adapter registration key for a customer collaboration Worker. */
+    adapterId?: string;
+    /** Structured-clone-safe options interpreted by the registered adapter. */
+    providerOptions?: unknown;
     /** Explicit room operation; join is the default at the untrusted input boundary. */
     roomMode: 'join' | 'create';
 }
@@ -68,7 +72,9 @@ export interface LegacyCollaborationLike {
     [key: string]: unknown;
 }
 export interface ResolveV2CollaborationTargetInput {
-    /** Document-level v2 collaboration config (canonical supported entry point). */
+    /** Preferred connection settings. Explicit null or invalid input never falls back to the alias. */
+    collaboration?: unknown;
+    /** Compatibility spelling for document-level connection settings. */
     v2Collaboration?: unknown;
     /** Legacy provider-agnostic collaboration block (`modules.collaboration` / upgrade opts). */
     legacyCollaboration?: LegacyCollaborationLike | null;
@@ -83,6 +89,11 @@ export interface ResolveV2CollaborationTargetInput {
      */
     authEndpointBaseUrl?: string;
 }
+/** Select the public spelling before validation; do not merge settings from different rooms. */
+export declare function readCollaborationConfig(input: {
+    collaboration?: unknown;
+    v2Collaboration?: unknown;
+}): unknown;
 /**
  * Redact a connection URL for safe inclusion in diagnostics and artifacts.
  *

package/dist/superdoc/src/core/types/index.d.ts

@@ -591,10 +591,12 @@ export interface CollaborationProvider {
     off?: (...args: unknown[]) => unknown;
     disconnect?: () => unknown;
     destroy?: () => unknown;
+    /** Send a provider-specific stateless string payload. */
+    sendStateless?: (message: string) => unknown;
     [key: string]: unknown;
 }
 /**
- * Document-level v2 collaboration handoff.
+ * Connection settings for one shared document, used at startup and during an upgrade.
  *
  * This is the public surface for SuperDoc v2's shipped real-time collaboration
  * model. v2 collaboration is always single-doc: one `Y.Doc`, one provider
@@ -604,18 +606,19 @@ export interface CollaborationProvider {
  * single-doc provider internally. One `documentId` maps to exactly one
  * room/provider/root identity.
  *
- * SuperDoc v2 supports three first-class provider families through this field:
- * y-websocket, Hocuspocus, and Liveblocks. The provider is selected with
- * `providerType`; omitting it preserves the original y-websocket-only shape
- * (`{ documentId, serverUrl, params? }`) for backward compatibility.
+ * SuperDoc v2 includes y-websocket, Hocuspocus, and Liveblocks adapters and can
+ * route a named provider extension through a configured collaboration Worker.
+ * The provider is selected with `providerType`; omitting it preserves the
+ * original y-websocket-only shape (`{ documentId, serverUrl, params? }`).
  *
  * This is intentionally distinct from the legacy provider-agnostic
- * {@link CollaborationConfig} (`Config.modules.collaboration`): v2 owns its
- * provider internally and does **not** accept an external Yjs `provider`/`ydoc`
- * through this field. External `{ ydoc, provider }` remains a v1 /
- * provider-compat concern only and is rejected as a v2 content driver.
+ * {@link CollaborationConfig} (`Config.modules.collaboration`): v2 owns the
+ * Y.Doc. Provider extensions receive that document inside the collaboration
+ * Worker instead of replacing it.
  */
-export type V2CollaborationConfig = V2YWebsocketCollaborationConfig | V2HocuspocusCollaborationConfig | V2LiveblocksCollaborationConfig;
+export type DocumentCollaborationConfig = V2YWebsocketCollaborationConfig | V2HocuspocusCollaborationConfig | V2LiveblocksCollaborationConfig | V2ProviderExtensionCollaborationConfig;
+/** @deprecated replaceWith=`DocumentCollaborationConfig` compat-indefinitely: existing v2 integrations import this type. */
+export type V2CollaborationConfig = DocumentCollaborationConfig;
 /**
  * y-websocket single-doc provider config.
  *
@@ -653,8 +656,8 @@ export interface V2HocuspocusCollaborationConfig {
     url?: string;
     /** Optional connection params forwarded to the backend. */
     params?: Record<string, string> | null;
-    /** Auth-message token forwarded to the Hocuspocus backend. */
-    token?: string;
+    /** Static auth token or resolver invoked for every Hocuspocus connection. */
+    token?: string | (() => string | Promise<string>);
     /** Explicit room operation. Defaults to `'join'`; `'create'` never joins an existing room. */
     roomMode?: 'join' | 'create';
 }
@@ -681,6 +684,20 @@ export interface V2LiveblocksCollaborationConfig {
     /** Explicit room operation. Defaults to `'join'`; `'create'` never joins an existing room. */
     roomMode?: 'join' | 'create';
 }
+/** Named provider adapter implemented by the configured collaboration Worker. */
+export interface V2ProviderExtensionCollaborationConfig {
+    providerType: 'extension';
+    /** Adapter registration key understood by the collaboration Worker. */
+    adapterId: string;
+    /** Stable shared document identity. */
+    documentId: string;
+    /** Structured-clone-safe options passed to the registered adapter factory. */
+    providerOptions?: unknown;
+    /** Optional host-owned credential resolver available to the adapter. */
+    token?: string | (() => string | Promise<string>);
+    /** Explicit room operation. Defaults to `'join'`; `'create'` never joins an existing room. */
+    roomMode?: 'join' | 'create';
+}
 export interface Comment {
     id?: string;
     commentId?: string;
@@ -932,29 +949,21 @@ export interface AwarenessUser extends User {
 }
 /**
  * One entry in the `states` array delivered to
- * {@link Config.onAwarenessUpdate}. SuperDoc emits an entry per remote
- * client, derived from the underlying Yjs awareness states.
+ * {@link Config.onAwarenessUpdate}. In V2, `states` includes the current
+ * user and remote participants. Do not append the current user again.
  *
- * The runtime helper `awarenessStatesToArray` spreads each remote user
- * onto the top of the entry (`{ clientId, ...value.user, color }`), so
- * `User` fields like `name`, `email`, `image` appear at the top level
- * (not nested under a `user` property). Consumers should read `state.id`,
- * `state.name`, and `state.email`, not `state.user.name`.
+ * Display fields such as `name`, `email`, and `color` are at the top
+ * level, not nested under `user`. Fields may be absent; a presence
+ * entry is not an authenticated account record.
  *
  * Application-specific fields attached to the awareness state by the
  * provider surface through the `[key: string]: unknown` index
  * signature; consumers narrow before use.
  */
 export interface AwarenessState extends User {
-    /** Yjs client identifier for the remote peer. */
+    /** Presence identifier. In V2, scoped to this editor instance, not a Yjs transport id. */
     clientId?: number;
-    /**
-     * Color assigned by SuperDoc's presence system. Spread onto the
-     * awareness entry after the user fields, so it takes precedence
-     * over any color the awareness user carried in (see
-     * {@link AwarenessUser.color}). Used when the presence system
-     * computes a stable palette assignment for the remote peer.
-     */
+    /** Resolved cursor color supplied by the presence system. */
     color?: string;
     /** Application-specific fields spread from the awareness provider. */
     [key: string]: unknown;
@@ -998,12 +1007,11 @@ export interface Document {
      */
     provider?: CollaborationProvider;
     /**
-     * Document-level v2 collaboration handoff. When present, the v2 runtime
-     * makes this document collaborative through the shipped single-doc
-     * y-websocket provider (one room / Y.Doc / awareness channel per
-     * `documentId`). See {@link V2CollaborationConfig}. Ignored by the v1
-     * editor, which uses `Config.modules.collaboration` instead.
+     * Connect this document to a shared room. SuperDoc owns the provider and Y.Doc.
+     * Takes precedence over `v2Collaboration`; `null` opens a local document.
      */
+    collaboration?: DocumentCollaborationConfig | null;
+    /** @deprecated replaceWith=`collaboration` compat-indefinitely: existing v2 integrations use this field. */
     v2Collaboration?: V2CollaborationConfig | null;
 }
 type DocumentSourceOptions = Omit<Document, 'data' | 'type' | 'url'>;
@@ -1126,9 +1134,8 @@ export interface CollaborationConfig {
 /**
  * Options for `upgradeToCollaboration()`.
  *
- * v2 promotes a local single-DOCX editor into the shipped single-doc
- * y-websocket room described by {@link V2CollaborationConfig}. Pass a
- * `v2Collaboration` target to promote into a supported v2 room.
+ * Promote a local DOCX into a shared room using `collaboration`.
+ * Supports the same providers as {@link DocumentCollaborationConfig}.
  *
  * The legacy `ydoc` / `provider` fields remain accepted for source
  * compatibility with v1-shaped callers, but v2 does **not** drive document
@@ -1138,14 +1145,15 @@ export interface CollaborationConfig {
  * fields are therefore optional and only honored when they resolve to a
  * supported v2 room.
  *
- * @see {@link V2CollaborationConfig}
+ * @see {@link DocumentCollaborationConfig}
  */
 export interface UpgradeToCollaborationOptions {
     /**
-     * Canonical supported v2 promotion target: the single-doc y-websocket room
-     * ({ documentId, serverUrl, params? }) to create from the current document.
-     * Promotion fails if the v2 room already exists.
+     * Create a shared room from the current document. Fails if the room already exists.
+     * Takes precedence over `v2Collaboration`.
      */
+    collaboration?: DocumentCollaborationConfig;
+    /** @deprecated replaceWith=`collaboration` compat-indefinitely: existing v2 integrations use this field. */
     v2Collaboration?: V2CollaborationConfig;
     /**
      * Legacy external Yjs document. Accepted for v1 source compatibility; not a
@@ -3242,6 +3250,14 @@ export interface SuperDocExceptionEditorPayload {
     /** Structured browser-worker failure detail when editor startup failed in its worker transport. */
     workerFailure?: SuperDocWorkerFailureDetail;
 }
+/** Connection failure while opening a collaboration room, reported through `onException`. */
+export interface SuperDocExceptionCollaborationPayload extends SuperDocExceptionEditorPayload {
+    error: Error;
+    code: 'collaboration-access-denied' | 'collaboration-connection-failed' | 'collaboration-sync-timeout';
+    /** Access denial requires an explicit provider rejection; a timeout is not proof of denied access. */
+    collaborationReason: 'access-denied' | 'connection-failed' | 'sync-timeout';
+    editor: null;
+}
 /**
  * Exception payload raised by the built-in toolbar.
  *
@@ -3311,6 +3327,7 @@ export interface SuperDocExceptionDiagnosticPayload {
  * Consumers can narrow with `'stage' in payload` (store init),
  * `'code' in payload` (editor lifecycle), `'itemName' in payload`
  * (built-in toolbar), `'source' in payload` (hyperlink activation),
+ * `'collaborationReason' in payload` (collaboration connection),
  * or `'diagnosticCode' in payload` (structured diagnostic).
  *
  * The union exists today because multiple independent emit sites pre-date a
@@ -3318,7 +3335,7 @@ export interface SuperDocExceptionDiagnosticPayload {
  * separate follow-up; consumers can narrow with the `in` checks above in the
  * meantime.
  */
-export type SuperDocExceptionPayload = SuperDocExceptionStorePayload | SuperDocExceptionRestorePayload | SuperDocExceptionEditorPayload | SuperDocExceptionToolbarPayload | SuperDocExceptionHyperlinkPayload | SuperDocExceptionDiagnosticPayload;
+export type SuperDocExceptionPayload = SuperDocExceptionStorePayload | SuperDocExceptionRestorePayload | SuperDocExceptionEditorPayload | SuperDocExceptionCollaborationPayload | SuperDocExceptionToolbarPayload | SuperDocExceptionHyperlinkPayload | SuperDocExceptionDiagnosticPayload;
 /**
  * Zoom mode. `manual` holds whatever value was last set; `fit-width`
  * continuously recomputes the zoom that fits the page width into the
@@ -3827,7 +3844,7 @@ export interface Config {
     role?: 'editor' | 'viewer' | 'suggester';
     /**
      * Document to open. Pass a URL, file, byte source, or structured source.
-     * Use a structured document carrying `v2Collaboration` for collaboration,
+     * Use a structured document carrying `collaboration` for collaboration,
      * or a structured source for other metadata. Omit it to open a blank DOCX.
      */
     document?: DocumentSource | null;

package/dist/superdoc/src/public/collaboration-worker.d.cts

@@ -0,0 +1,18 @@
+// Generated by scripts/ensure-types.cjs. Do not edit by hand.
+import type { SuperDocCollaborationProviderAdapter as __Cjs_SuperDocCollaborationProviderAdapter } from './collaboration-worker.js' with { "resolution-mode": "import" };
+import type { SuperDocCollaborationProviderAttachInput as __Cjs_SuperDocCollaborationProviderAttachInput } from './collaboration-worker.js' with { "resolution-mode": "import" };
+import type { SuperDocCollaborationProviderAwareness as __Cjs_SuperDocCollaborationProviderAwareness } from './collaboration-worker.js' with { "resolution-mode": "import" };
+import type { SuperDocCollaborationProviderFactory as __Cjs_SuperDocCollaborationProviderFactory } from './collaboration-worker.js' with { "resolution-mode": "import" };
+import type { SuperDocCollaborationProviderFactoryInput as __Cjs_SuperDocCollaborationProviderFactoryInput } from './collaboration-worker.js' with { "resolution-mode": "import" };
+import type { SuperDocCollaborationProviderFamily as __Cjs_SuperDocCollaborationProviderFamily } from './collaboration-worker.js' with { "resolution-mode": "import" };
+import type { SuperDocCollaborationProviderTransport as __Cjs_SuperDocCollaborationProviderTransport } from './collaboration-worker.js' with { "resolution-mode": "import" };
+import type { SuperDocCollaborationWorkerOptions as __Cjs_SuperDocCollaborationWorkerOptions } from './collaboration-worker.js' with { "resolution-mode": "import" };
+export declare const bootstrapSuperDocCollaborationWorker: typeof import('./collaboration-worker.js', { with: { "resolution-mode": "import" } }).bootstrapSuperDocCollaborationWorker;
+export type { __Cjs_SuperDocCollaborationProviderAdapter as SuperDocCollaborationProviderAdapter };
+export type { __Cjs_SuperDocCollaborationProviderAttachInput as SuperDocCollaborationProviderAttachInput };
+export type { __Cjs_SuperDocCollaborationProviderAwareness as SuperDocCollaborationProviderAwareness };
+export type { __Cjs_SuperDocCollaborationProviderFactory as SuperDocCollaborationProviderFactory };
+export type { __Cjs_SuperDocCollaborationProviderFactoryInput as SuperDocCollaborationProviderFactoryInput };
+export type { __Cjs_SuperDocCollaborationProviderFamily as SuperDocCollaborationProviderFamily };
+export type { __Cjs_SuperDocCollaborationProviderTransport as SuperDocCollaborationProviderTransport };
+export type { __Cjs_SuperDocCollaborationWorkerOptions as SuperDocCollaborationWorkerOptions };