@veltdev/draftjs-crdt 1.0.0

package/esm/index.js

@@ -0,0 +1,1815 @@
+import { Store } from '@veltdev/crdt';
+import * as Y from 'yjs';
+import { convertToRaw, convertFromRaw, EditorState, ContentState } from 'draft-js';
+import { useState, useRef, useEffect, useCallback } from 'react';
+import { useVeltClient, useVeltInitState } from '@veltdev/react';
+
+// POLICY: Every function/method in this file MUST be wrapped in try/catch.
+// The package must NEVER throw an exception to the consumer's code.
+const LOG_PREFIX = 'DraftjsCRDT';
+/**
+ * Log an error/warning — only visible when debug mode is enabled
+ * via sessionStorage.setItem('forceCrdtDebugMode', 'true').
+ */
+function logError(message, error) {
+    try {
+        if (typeof sessionStorage !== 'undefined' &&
+            sessionStorage.getItem('forceCrdtDebugMode')) {
+            console.warn(`${LOG_PREFIX} ${message}`, error !== undefined ? error : '');
+        }
+    }
+    catch {
+        // sessionStorage may not be available (SSR / iframe restrictions)
+    }
+}
+
+// POLICY: Public package helpers must never throw into consumer code.
+const CONFIG_MAP_KEY$1 = 'veltConfig';
+const INITIALIZED_FLAG = '__docInitialized';
+const LEGACY_FLAG = 'hasContentSet';
+const META_NODE = 'draftjs-meta';
+const BLOCK_NODE = 'draftjs-block';
+const RAW_ATTR = 'raw';
+const SCHEMA_ATTR = 'schema';
+const SCHEMA_VERSION = 'draftjs-raw-v1';
+function applyInitialContent(doc, xmlFragment, rawContent, force, origin) {
+    try {
+        const configMap = doc.getMap(CONFIG_MAP_KEY$1);
+        if (!force && (configMap.get(INITIALIZED_FLAG) || configMap.get(LEGACY_FLAG))) {
+            return false;
+        }
+        if (!force && xmlFragment.length > 0) {
+            return false;
+        }
+        doc.transact(() => {
+            writeRawToXmlFragment(xmlFragment, rawContent);
+            configMap.set(INITIALIZED_FLAG, true);
+        }, origin);
+        return true;
+    }
+    catch (error) {
+        logError('Failed to apply initial content', error);
+        return false;
+    }
+}
+function normalizeInitialContent(initialContent) {
+    try {
+        if (initialContent === undefined || initialContent === null) {
+            return null;
+        }
+        if (typeof initialContent === 'string') {
+            return convertToRaw(ContentState.createFromText(initialContent));
+        }
+        if (isRawDraftContentState(initialContent)) {
+            return initialContent;
+        }
+        return null;
+    }
+    catch (error) {
+        logError('Failed to normalize initial content', error);
+        return null;
+    }
+}
+function rawFromEditorState(editorState) {
+    try {
+        return convertToRaw(editorState.getCurrentContent());
+    }
+    catch (error) {
+        logError('Failed to read Draft.js editor state', error);
+        return null;
+    }
+}
+function editorStateFromRaw(rawContent, previousState) {
+    try {
+        const contentState = convertFromRaw(rawContent);
+        if (!previousState) {
+            return EditorState.createWithContent(contentState);
+        }
+        let nextState = EditorState.push(previousState, contentState, 'insert-fragment');
+        const previousSelection = previousState.getSelection();
+        if (previousSelection.getHasFocus() &&
+            contentState.getBlockMap().has(previousSelection.getAnchorKey()) &&
+            contentState.getBlockMap().has(previousSelection.getFocusKey())) {
+            nextState = EditorState.forceSelection(nextState, previousSelection);
+        }
+        return nextState;
+    }
+    catch (error) {
+        logError('Failed to create Draft.js editor state from CRDT content', error);
+        return null;
+    }
+}
+function writeRawToXmlFragment(xmlFragment, rawContent) {
+    try {
+        if (xmlFragment.length > 0) {
+            xmlFragment.delete(0, xmlFragment.length);
+        }
+        xmlFragment.insert(0, buildXmlNodes(rawContent));
+    }
+    catch (error) {
+        logError('Failed to write Draft.js content to XML fragment', error);
+    }
+}
+function rawFromXmlFragment(xmlFragment) {
+    try {
+        const nodes = xmlFragment.toArray();
+        const meta = nodes.find((node) => isXmlElement(node, META_NODE));
+        const rawJson = meta instanceof Y.XmlElement ? meta.getAttribute(RAW_ATTR) : undefined;
+        let rawFromMeta = null;
+        if (typeof rawJson === 'string') {
+            const parsed = JSON.parse(rawJson);
+            if (isRawDraftContentState(parsed)) {
+                rawFromMeta = parsed;
+            }
+        }
+        const blocks = nodes
+            .filter((node) => isXmlElement(node, BLOCK_NODE))
+            .map(readBlockFromXml)
+            .filter((block) => !!block);
+        const genericBlocks = nodes
+            .filter((node) => !isXmlElement(node, META_NODE) && !isXmlElement(node, BLOCK_NODE))
+            .map((node, index) => rawBlockFromText(readTextFromXmlNode(node).trim(), index))
+            .filter((block) => !!block);
+        if (rawFromMeta) {
+            if (genericBlocks.length === 0)
+                return rawFromMeta;
+            return {
+                blocks: [...rawFromMeta.blocks, ...genericBlocks],
+                entityMap: rawFromMeta.entityMap ?? {},
+            };
+        }
+        if (blocks.length > 0) {
+            return { blocks: [...blocks, ...genericBlocks], entityMap: {} };
+        }
+        const genericText = nodes.map(readTextFromXmlNode).join('\n').trim();
+        if (genericText) {
+            return {
+                blocks: [rawBlockFromText(genericText, 0)],
+                entityMap: {},
+            };
+        }
+        return null;
+    }
+    catch (error) {
+        logError('Failed to read Draft.js content from XML fragment', error);
+        return null;
+    }
+}
+function rawFromXmlLikeString(value) {
+    try {
+        if (!value) {
+            return null;
+        }
+        const rawFromMeta = rawFromDraftMetaString(value);
+        if (rawFromMeta)
+            return rawFromMeta;
+        const text = stripXmlTags(value)
+            .replace(/\s+/g, ' ')
+            .trim();
+        if (!text)
+            return null;
+        return {
+            blocks: [rawBlockFromText(text, 0)],
+            entityMap: {},
+        };
+    }
+    catch (error) {
+        logError('Failed to read Draft.js content from XML-like string', error);
+        return null;
+    }
+}
+function rawContentsEqual(a, b) {
+    try {
+        if (!a || !b)
+            return false;
+        return serializeRawContent(a) === serializeRawContent(b);
+    }
+    catch {
+        return false;
+    }
+}
+function serializeRawContent(rawContent) {
+    try {
+        return JSON.stringify(rawContent);
+    }
+    catch (error) {
+        logError('Failed to serialize Draft.js raw content', error);
+        return '';
+    }
+}
+function isRawDraftContentState(value) {
+    try {
+        if (!value || typeof value !== 'object')
+            return false;
+        const candidate = value;
+        return Array.isArray(candidate.blocks) && !!candidate.entityMap;
+    }
+    catch {
+        return false;
+    }
+}
+function buildXmlNodes(rawContent) {
+    const meta = new Y.XmlElement(META_NODE);
+    meta.setAttribute(SCHEMA_ATTR, SCHEMA_VERSION);
+    meta.setAttribute(RAW_ATTR, serializeRawContent(rawContent));
+    const blocks = rawContent.blocks.map((block) => {
+        const blockElement = new Y.XmlElement(BLOCK_NODE);
+        blockElement.setAttribute('key', block.key);
+        blockElement.setAttribute('type', block.type);
+        blockElement.setAttribute('depth', String(block.depth ?? 0));
+        blockElement.setAttribute('data', JSON.stringify(block.data ?? {}));
+        blockElement.setAttribute('entityRanges', JSON.stringify(block.entityRanges ?? []));
+        const text = new Y.XmlText();
+        insertStyledText(text, block);
+        blockElement.insert(0, [text]);
+        return blockElement;
+    });
+    return [meta, ...blocks];
+}
+function insertStyledText(xmlText, block) {
+    const text = block.text ?? '';
+    let index = 0;
+    let yIndex = 0;
+    while (index < text.length) {
+        const attrs = getTextAttributesAt(block, index);
+        let end = index + 1;
+        while (end < text.length && sameAttrs(attrs, getTextAttributesAt(block, end))) {
+            end += 1;
+        }
+        const segment = text.slice(index, end);
+        xmlText.insert(yIndex, segment, attrs);
+        yIndex += segment.length;
+        index = end;
+    }
+}
+function getTextAttributesAt(block, offset) {
+    const styles = (block.inlineStyleRanges ?? [])
+        .filter((range) => offset >= range.offset && offset < range.offset + range.length)
+        .map((range) => range.style)
+        .sort();
+    const entity = (block.entityRanges ?? []).find((range) => offset >= range.offset && offset < range.offset + range.length);
+    const attrs = {};
+    if (styles.length > 0)
+        attrs.draftStyles = styles.join(',');
+    if (entity)
+        attrs.draftEntity = String(entity.key);
+    return attrs;
+}
+function sameAttrs(a, b) {
+    return a.draftStyles === b.draftStyles && a.draftEntity === b.draftEntity;
+}
+function readBlockFromXml(blockElement) {
+    try {
+        const textNode = blockElement.toArray().find((node) => node instanceof Y.XmlText);
+        const text = textNode?.toString() ?? '';
+        const dataAttr = blockElement.getAttribute('data');
+        const entityAttr = blockElement.getAttribute('entityRanges');
+        return {
+            key: String(blockElement.getAttribute('key') || `b${Math.random().toString(36).slice(2, 7)}`),
+            text,
+            type: String(blockElement.getAttribute('type') || 'unstyled'),
+            depth: Number(blockElement.getAttribute('depth') || 0),
+            inlineStyleRanges: textNode ? readInlineStyleRanges(textNode) : [],
+            entityRanges: typeof entityAttr === 'string' ? JSON.parse(entityAttr) : [],
+            data: typeof dataAttr === 'string' ? JSON.parse(dataAttr) : {},
+        };
+    }
+    catch (error) {
+        logError('Failed to read Draft.js block from XML', error);
+        return null;
+    }
+}
+function readInlineStyleRanges(xmlText) {
+    const ranges = [];
+    let offset = 0;
+    for (const op of xmlText.toDelta()) {
+        const insert = typeof op.insert === 'string' ? op.insert : '';
+        const styles = op.attributes?.draftStyles?.split(',').filter(Boolean) ?? [];
+        for (const style of styles) {
+            ranges.push({ offset, length: insert.length, style: style });
+        }
+        offset += insert.length;
+    }
+    return ranges;
+}
+function rawBlockFromText(text, index) {
+    if (!text)
+        return null;
+    return {
+        key: stableDraftBlockKey(text, index),
+        text,
+        type: 'unstyled',
+        depth: 0,
+        inlineStyleRanges: [],
+        entityRanges: [],
+        data: {},
+    };
+}
+function stableDraftBlockKey(text, index) {
+    let hash = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        hash = ((hash << 5) - hash + text.charCodeAt(i)) | 0;
+    }
+    return `g${index}${Math.abs(hash).toString(36).slice(0, 4)}`.slice(0, 5);
+}
+function isXmlElement(node, nodeName) {
+    return node instanceof Y.XmlElement && node.nodeName === nodeName;
+}
+function readTextFromXmlNode(node) {
+    try {
+        if (node instanceof Y.XmlText) {
+            return node.toString();
+        }
+        if (node instanceof Y.XmlElement || node instanceof Y.XmlFragment) {
+            const childText = node.toArray().map(readTextFromXmlNode).join('');
+            if (childText)
+                return childText;
+            return stripXmlTags(node.toString());
+        }
+        return '';
+    }
+    catch {
+        return '';
+    }
+}
+function stripXmlTags(value) {
+    return value.replace(/<[^>]+>/g, '');
+}
+function rawFromDraftMetaString(value) {
+    try {
+        const rawStart = value.indexOf('raw="');
+        if (rawStart === -1)
+            return null;
+        const contentStart = rawStart + 'raw="'.length;
+        let contentEnd = value.indexOf('" schema=', contentStart);
+        if (contentEnd === -1) {
+            contentEnd = value.indexOf('"></draftjs-meta>', contentStart);
+        }
+        if (contentEnd === -1)
+            return null;
+        const rawJson = value.slice(contentStart, contentEnd).replace(/&quot;/g, '"');
+        const parsed = JSON.parse(rawJson);
+        return isRawDraftContentState(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+
+// POLICY: Public package methods must never throw into consumer code.
+const CONTENT_KEY = 'draftjs';
+const STORE_SOURCE = 'draftjs';
+const DEFAULT_REST_CONTENT_KEY = 'document-store';
+const CONFIG_MAP_KEY = 'veltConfig';
+const FORCE_RESET_REVISION_KEY = '__draftjsForceResetRevision';
+const FORCE_RESET_OPEN_FOR_EDITS_KEY = '__draftjsForceResetOpenForEdits';
+const VERSION_META_MAP_KEY = 'draftjsVersionMetadata';
+const VERSION_META_LAST_CHANGE_KEY = 'lastChange';
+class CollaborationManager {
+    constructor(config) {
+        this.store = null;
+        this.provider = null;
+        this.xmlFragment = null;
+        this.restXmlFragment = null;
+        this.versionMetadata = null;
+        this.undoManager = null;
+        this.userId = 'anonymous';
+        this.initializedState = false;
+        this.syncedState = false;
+        this.statusState = 'connecting';
+        this.initialContentApplied = false;
+        this.applyingRemote = false;
+        this.skipNextSync = false;
+        this.skipNextSyncToken = 0;
+        this.lastRawJson = '';
+        this.forceResetRawContent = null;
+        this.forceResetRawJson = '';
+        this.hasLocalEditAfterForceReset = false;
+        this.forceResetStrict = false;
+        this.localOrigin = { source: STORE_SOURCE, direction: 'local' };
+        this.initialOrigin = { source: STORE_SOURCE, direction: 'initial' };
+        this.restBridgeOrigin = { source: STORE_SOURCE, direction: 'rest-bridge' };
+        this.statusListeners = new Set();
+        this.syncedListeners = new Set();
+        this.awarenessListeners = new Set();
+        this.versionListeners = new Set();
+        this.cleanupFns = [];
+        this.snapshotSaveTimer = null;
+        this.config = config;
+    }
+    async initialize() {
+        try {
+            this.userId = this.resolveUserId();
+            this.store = this.createStore();
+            this.xmlFragment = this.store.getXml();
+            this.restXmlFragment = this.getRestXmlFragment();
+            this.versionMetadata = this.store.getDoc().getMap(VERSION_META_MAP_KEY);
+            this.bindXmlFragment();
+            this.bindRestXmlFragment();
+            this.setupVersionMetadataListener();
+            this.createUndoManager();
+            try {
+                await this.store.initialize();
+            }
+            catch (error) {
+                if (this.isCorruptionError(error)) {
+                    await this.tryRecoverFromCorruption();
+                }
+                else {
+                    this.reportError('Store initialization failed, entering degraded state', error);
+                }
+            }
+            try {
+                this.provider = this.store?.getProvider() ?? null;
+            }
+            catch (error) {
+                this.reportError('Failed to get provider', error);
+            }
+            this.setupRestDataFallbackListener();
+            this.applyRestXmlFragmentToDraft(false);
+            await this.tryHydrateRestDataFallback();
+            this.setupProviderListeners();
+            this.setupAwarenessListeners();
+            this.tryApplyInitialContent();
+            this.applyFragmentToEditor(false);
+            this.sendCursorPosition();
+            this.initializedState = true;
+        }
+        catch (error) {
+            this.reportError('Initialization failed unexpectedly', error);
+        }
+    }
+    destroy() {
+        try {
+            for (const fn of this.cleanupFns.splice(0)) {
+                try {
+                    fn();
+                }
+                catch {
+                    // ignore cleanup errors
+                }
+            }
+            this.statusListeners.clear();
+            this.syncedListeners.clear();
+            this.awarenessListeners.clear();
+            this.versionListeners.clear();
+            if (this.snapshotSaveTimer) {
+                clearTimeout(this.snapshotSaveTimer);
+                this.snapshotSaveTimer = null;
+            }
+            this.undoManager?.destroy();
+            this.undoManager = null;
+            try {
+                this.store?.updateAwareness(null);
+            }
+            catch {
+                // ignore awareness cleanup errors
+            }
+            this.store?.destroy();
+            this.store = null;
+            this.provider = null;
+            this.xmlFragment = null;
+            this.restXmlFragment = null;
+            this.versionMetadata = null;
+            this.initializedState = false;
+            this.syncedState = false;
+            this.statusState = 'disconnected';
+        }
+        catch (error) {
+            logError('Error during destroy', error);
+        }
+    }
+    handleChange(nextState) {
+        try {
+            if (this.skipNextSync) {
+                this.skipNextSync = false;
+                this.skipNextSyncToken += 1;
+                this.updateAwarenessFromEditorState(nextState);
+                return nextState;
+            }
+            if (!this.applyingRemote) {
+                this.syncEditorStateToXml(nextState);
+            }
+            this.updateAwarenessFromEditorState(nextState);
+            return nextState;
+        }
+        catch (error) {
+            this.reportError('Failed to handle Draft.js change', error);
+            return nextState;
+        }
+    }
+    sendCursorPosition(selection) {
+        try {
+            const resolvedSelection = selection ?? this.safeGetEditorState()?.getSelection();
+            this.updateAwarenessSelection(resolvedSelection ?? null);
+        }
+        catch (error) {
+            this.reportError('Failed to publish Draft.js cursor position', error);
+        }
+    }
+    getRemoteCursors() {
+        try {
+            return this.readRemoteCursors();
+        }
+        catch (error) {
+            this.reportError('Failed to read remote cursors', error);
+            return [];
+        }
+    }
+    onRemoteCursorsChange(cb) {
+        try {
+            this.awarenessListeners.add(cb);
+            cb(this.readRemoteCursors());
+        }
+        catch (error) {
+            this.reportError('Failed to add remote cursor listener', error);
+        }
+        return () => {
+            try {
+                this.awarenessListeners.delete(cb);
+            }
+            catch {
+                // ignore listener cleanup errors
+            }
+        };
+    }
+    get initialized() {
+        return this.initializedState;
+    }
+    get synced() {
+        return this.syncedState;
+    }
+    get status() {
+        return this.statusState;
+    }
+    onStatusChange(cb) {
+        try {
+            this.statusListeners.add(cb);
+            cb(this.statusState);
+        }
+        catch (error) {
+            this.reportError('Failed to add status listener', error);
+        }
+        return () => {
+            try {
+                this.statusListeners.delete(cb);
+            }
+            catch {
+                // ignore listener cleanup errors
+            }
+        };
+    }
+    onSynced(cb) {
+        try {
+            this.syncedListeners.add(cb);
+            cb(this.syncedState);
+        }
+        catch (error) {
+            this.reportError('Failed to add synced listener', error);
+        }
+        return () => {
+            try {
+                this.syncedListeners.delete(cb);
+            }
+            catch {
+                // ignore listener cleanup errors
+            }
+        };
+    }
+    getDoc() {
+        try {
+            return this.store?.getDoc() ?? null;
+        }
+        catch (error) {
+            this.reportError('Failed to get Y.Doc', error);
+            return null;
+        }
+    }
+    getXmlFragment() {
+        try {
+            return this.xmlFragment ?? this.store?.getXml() ?? null;
+        }
+        catch (error) {
+            this.reportError('Failed to get XML fragment', error);
+            return null;
+        }
+    }
+    getXmlText() {
+        try {
+            const fragment = this.getXmlFragment();
+            const firstBlock = fragment?.toArray().find((node) => {
+                return node instanceof Y.XmlElement && node.nodeName === 'draftjs-block';
+            });
+            return firstBlock?.toArray().find((node) => node instanceof Y.XmlText) ?? null;
+        }
+        catch (error) {
+            this.reportError('Failed to get XML text', error);
+            return null;
+        }
+    }
+    getProvider() {
+        try {
+            return this.provider ?? this.store?.getProvider() ?? null;
+        }
+        catch (error) {
+            this.reportError('Failed to get SyncProvider', error);
+            return null;
+        }
+    }
+    getAwareness() {
+        try {
+            return this.store?.getAwareness() ?? this.provider?.getAwareness() ?? null;
+        }
+        catch (error) {
+            this.reportError('Failed to get Awareness', error);
+            return null;
+        }
+    }
+    getUndoManager() {
+        try {
+            return this.undoManager;
+        }
+        catch (error) {
+            this.reportError('Failed to get UndoManager', error);
+            return null;
+        }
+    }
+    getStore() {
+        try {
+            return this.store;
+        }
+        catch (error) {
+            this.reportError('Failed to get Store', error);
+            return null;
+        }
+    }
+    async saveVersion(name) {
+        try {
+            this.flushCurrentEditorState();
+            const versionId = (await this.store?.saveVersion(name)) ?? '';
+            if (versionId) {
+                this.publishVersionChange('save', versionId, name);
+            }
+            return versionId;
+        }
+        catch (error) {
+            this.reportError('Failed to save version', error);
+            return '';
+        }
+    }
+    async getVersions() {
+        try {
+            return (await this.store?.getVersions()) ?? [];
+        }
+        catch (error) {
+            this.reportError('Failed to get versions', error);
+            return [];
+        }
+    }
+    async restoreVersion(versionId) {
+        try {
+            const restored = (await this.store?.restoreVersion(versionId)) ?? false;
+            if (restored) {
+                this.mirrorCurrentDraftToRestXml(this.restBridgeOrigin);
+                this.applyFragmentToEditor(false);
+                this.store?.notifySubscribers();
+                await this.saveCurrentSnapshot();
+                this.publishVersionChange('restore', versionId);
+            }
+            return restored;
+        }
+        catch (error) {
+            this.reportError('Failed to restore version', error);
+            return false;
+        }
+    }
+    async setStateFromVersion(version) {
+        try {
+            await this.store?.setStateFromVersion(version);
+            this.mirrorCurrentDraftToRestXml(this.restBridgeOrigin);
+            this.applyFragmentToEditor(false);
+            this.store?.notifySubscribers();
+            await this.saveCurrentSnapshot();
+            this.publishVersionChange('set-state', version.versionId, version.versionName);
+        }
+        catch (error) {
+            this.reportError('Failed to set state from version', error);
+        }
+    }
+    onVersionsChange(cb) {
+        try {
+            this.versionListeners.add(cb);
+        }
+        catch (error) {
+            this.reportError('Failed to add version listener', error);
+        }
+        return () => {
+            try {
+                this.versionListeners.delete(cb);
+            }
+            catch {
+                // ignore listener cleanup errors
+            }
+        };
+    }
+    createStore() {
+        return new Store({
+            id: this.config.editorId,
+            userId: this.userId,
+            type: 'xml',
+            contentKey: CONTENT_KEY,
+            debounceMs: this.config.debounceMs,
+            veltClient: this.config.veltClient,
+            source: STORE_SOURCE,
+            forceResetInitialContent: this.config.forceResetInitialContent,
+        });
+    }
+    bindXmlFragment() {
+        try {
+            if (!this.xmlFragment)
+                return;
+            const observer = (_events, transaction) => {
+                try {
+                    if (transaction.origin === this.localOrigin || transaction.origin === this.initialOrigin) {
+                        return;
+                    }
+                    if (transaction.origin === this.restBridgeOrigin) {
+                        return;
+                    }
+                    if (this.enforceForceResetInitialContent(true)) {
+                        return;
+                    }
+                    this.applyFragmentToEditor(true);
+                }
+                catch (error) {
+                    this.reportError('Failed to apply remote XML update', error);
+                }
+            };
+            this.xmlFragment.observeDeep(observer);
+            this.cleanupFns.push(() => {
+                try {
+                    this.xmlFragment?.unobserveDeep(observer);
+                }
+                catch {
+                    // ignore observer cleanup errors
+                }
+            });
+        }
+        catch (error) {
+            this.reportError('Failed to bind XML fragment observer', error);
+        }
+    }
+    createUndoManager() {
+        try {
+            if (!this.xmlFragment)
+                return;
+            this.undoManager = new Y.UndoManager(this.xmlFragment, {
+                trackedOrigins: new Set([this.localOrigin]),
+            });
+        }
+        catch (error) {
+            this.reportError('Failed to create UndoManager', error);
+        }
+    }
+    bindRestXmlFragment() {
+        try {
+            if (!this.restXmlFragment)
+                return;
+            const observer = (_events, transaction) => {
+                try {
+                    if (transaction.origin === this.localOrigin
+                        || transaction.origin === this.initialOrigin
+                        || transaction.origin === this.restBridgeOrigin) {
+                        return;
+                    }
+                    if (this.enforceForceResetInitialContent(true)) {
+                        return;
+                    }
+                    this.applyRestXmlFragmentToDraft(true, true);
+                }
+                catch (error) {
+                    this.reportError('Failed to apply REST XML update', error);
+                }
+            };
+            this.restXmlFragment.observeDeep(observer);
+            this.cleanupFns.push(() => {
+                try {
+                    this.restXmlFragment?.unobserveDeep(observer);
+                }
+                catch {
+                    // ignore observer cleanup errors
+                }
+            });
+        }
+        catch (error) {
+            this.reportError('Failed to bind REST XML fragment observer', error);
+        }
+    }
+    setupVersionMetadataListener() {
+        try {
+            if (!this.versionMetadata)
+                return;
+            const observer = () => {
+                try {
+                    const event = this.readVersionChangeEvent();
+                    if (!event)
+                        return;
+                    this.versionListeners.forEach((cb) => {
+                        try {
+                            cb(event);
+                        }
+                        catch {
+                            // ignore listener errors
+                        }
+                    });
+                }
+                catch (error) {
+                    this.reportError('Failed to publish version metadata change', error);
+                }
+            };
+            this.versionMetadata.observe(observer);
+            this.cleanupFns.push(() => {
+                try {
+                    this.versionMetadata?.unobserve(observer);
+                }
+                catch {
+                    // ignore observer cleanup errors
+                }
+            });
+        }
+        catch (error) {
+            this.reportError('Failed to setup version metadata listener', error);
+        }
+    }
+    syncEditorStateToXml(editorState) {
+        try {
+            if (!this.xmlFragment)
+                return;
+            const rawContent = rawFromEditorState(editorState);
+            if (!rawContent)
+                return;
+            const nextRawJson = serializeRawContent(rawContent);
+            if (nextRawJson && nextRawJson === this.lastRawJson) {
+                return;
+            }
+            if (this.config.forceResetInitialContent
+                && this.forceResetRawJson
+                && nextRawJson !== this.forceResetRawJson) {
+                this.hasLocalEditAfterForceReset = true;
+            }
+            const shouldOpenForceResetForEdits = this.shouldOpenForceResetForEdits(nextRawJson);
+            const doc = this.store?.getDoc();
+            if (doc) {
+                doc.transact(() => {
+                    writeRawToXmlFragment(this.xmlFragment, rawContent);
+                    if (this.restXmlFragment) {
+                        writeRawToXmlFragment(this.restXmlFragment, rawContent);
+                    }
+                    if (shouldOpenForceResetForEdits) {
+                        this.markForceResetOpenForEdits(doc);
+                    }
+                }, this.localOrigin);
+            }
+            else {
+                writeRawToXmlFragment(this.xmlFragment, rawContent);
+                if (this.restXmlFragment) {
+                    writeRawToXmlFragment(this.restXmlFragment, rawContent);
+                }
+            }
+            this.lastRawJson = nextRawJson;
+            this.store?.notifySubscribers();
+            this.scheduleSnapshotSave();
+        }
+        catch (error) {
+            this.reportError('Failed to sync Draft.js state to XML', error);
+        }
+    }
+    flushCurrentEditorState() {
+        try {
+            const editorState = this.safeGetEditorState();
+            if (editorState) {
+                this.syncEditorStateToXml(editorState);
+            }
+        }
+        catch (error) {
+            this.reportError('Failed to flush Draft.js state', error);
+        }
+    }
+    applyFragmentToEditor(preserveSelection) {
+        try {
+            if (!this.xmlFragment)
+                return;
+            const rawContent = rawFromXmlFragment(this.xmlFragment);
+            if (!rawContent)
+                return;
+            const currentState = this.safeGetEditorState();
+            const currentRaw = currentState ? rawFromEditorState(currentState) : null;
+            if (rawContentsEqual(currentRaw, rawContent)) {
+                this.lastRawJson = serializeRawContent(rawContent);
+                return;
+            }
+            this.applyingRemote = true;
+            this.skipNextSync = true;
+            const skipToken = this.skipNextSyncToken + 1;
+            this.skipNextSyncToken = skipToken;
+            const nextState = editorStateFromRaw(rawContent, preserveSelection ? currentState : null);
+            if (nextState) {
+                this.config.setEditorState(nextState);
+            }
+            this.lastRawJson = serializeRawContent(rawContent);
+            setTimeout(() => {
+                if (this.skipNextSyncToken === skipToken) {
+                    this.skipNextSync = false;
+                }
+            }, 0);
+        }
+        catch (error) {
+            this.reportError('Failed to hydrate Draft.js editor from XML', error);
+        }
+        finally {
+            this.applyingRemote = false;
+        }
+    }
+    tryApplyInitialContent() {
+        try {
+            if (this.initialContentApplied || !this.store || !this.xmlFragment)
+                return;
+            const initial = normalizeInitialContent(this.config.initialContent);
+            if (!initial)
+                return;
+            const preResetRaw = this.config.forceResetInitialContent
+                ? rawFromXmlFragment(this.xmlFragment)
+                : null;
+            this.initialContentApplied = applyInitialContent(this.store.getDoc(), this.xmlFragment, initial, this.config.forceResetInitialContent, this.initialOrigin);
+            if (this.initialContentApplied) {
+                this.lastRawJson = serializeRawContent(initial);
+                if (this.config.forceResetInitialContent) {
+                    this.forceResetRawContent = initial;
+                    this.forceResetRawJson = serializeRawContent(initial);
+                    this.hasLocalEditAfterForceReset = false;
+                    this.forceResetStrict = !!preResetRaw && !rawDraftContentSemanticallyEqual(preResetRaw, initial);
+                    this.markForceResetBaseline(true);
+                    this.mirrorRawToRestXml(initial, this.initialOrigin);
+                    void this.saveCurrentSnapshot();
+                }
+                this.applyFragmentToEditor(false);
+                this.store.notifySubscribers();
+            }
+        }
+        catch (error) {
+            this.reportError('Failed to apply initial content', error);
+        }
+    }
+    setupProviderListeners() {
+        try {
+            if (!this.provider)
+                return;
+            const onSynced = (synced) => {
+                try {
+                    this.syncedState = synced;
+                    this.syncedListeners.forEach((cb) => {
+                        try {
+                            cb(synced);
+                        }
+                        catch {
+                            // ignore listener errors
+                        }
+                    });
+                    if (synced) {
+                        this.applyRestXmlFragmentToDraft(true);
+                        this.tryApplyInitialContent();
+                        if (!this.enforceForceResetInitialContent(true)) {
+                            this.applyFragmentToEditor(true);
+                        }
+                    }
+                }
+                catch (error) {
+                    this.reportError('Error in synced handler', error);
+                }
+            };
+            const onStatus = (payload) => {
+                try {
+                    const status = typeof payload === 'string' ? payload : payload.status;
+                    this.statusState = status;
+                    this.statusListeners.forEach((cb) => {
+                        try {
+                            cb(status);
+                        }
+                        catch {
+                            // ignore listener errors
+                        }
+                    });
+                }
+                catch (error) {
+                    this.reportError('Error in status handler', error);
+                }
+            };
+            this.provider.on('synced', onSynced);
+            this.provider.on('status', onStatus);
+            this.cleanupFns.push(() => {
+                this.provider?.off('synced', onSynced);
+                this.provider?.off('status', onStatus);
+            });
+            this.syncedState = this.provider.synced;
+            this.statusState = this.provider.status;
+        }
+        catch (error) {
+            this.reportError('Failed to setup provider listeners', error);
+        }
+    }
+    setupAwarenessListeners() {
+        try {
+            const awareness = this.getAwareness();
+            if (!awareness)
+                return;
+            const onChange = () => {
+                try {
+                    const cursors = this.readRemoteCursors();
+                    this.awarenessListeners.forEach((cb) => {
+                        try {
+                            cb(cursors);
+                        }
+                        catch {
+                            // ignore listener errors
+                        }
+                    });
+                }
+                catch (error) {
+                    this.reportError('Failed to publish awareness change', error);
+                }
+            };
+            awareness.on('change', onChange);
+            this.cleanupFns.push(() => {
+                try {
+                    awareness.off('change', onChange);
+                }
+                catch {
+                    // ignore listener cleanup errors
+                }
+            });
+        }
+        catch (error) {
+            this.reportError('Failed to setup awareness listeners', error);
+        }
+    }
+    setupRestDataFallbackListener() {
+        try {
+            const crdtElement = this.getCrdtElement();
+            if (!crdtElement?.onDataChange)
+                return;
+            const unsubscribe = crdtElement.onDataChange({
+                id: this.config.editorId,
+                callback: (payload) => {
+                    try {
+                        this.applyRestDataFallback(payload);
+                    }
+                    catch (error) {
+                        this.reportError('Failed to apply REST data update', error);
+                    }
+                },
+            });
+            if (typeof unsubscribe === 'function') {
+                this.cleanupFns.push(unsubscribe);
+            }
+        }
+        catch (error) {
+            this.reportError('Failed to setup REST data fallback listener', error);
+        }
+    }
+    async tryHydrateRestDataFallback() {
+        try {
+            if (!this.xmlFragment)
+                return;
+            this.applyRestXmlFragmentToDraft(false);
+            const crdtElement = this.getCrdtElement();
+            if (!crdtElement?.getData)
+                return;
+            const payload = await crdtElement.getData({ id: this.config.editorId });
+            this.applyRestDataFallback(payload);
+        }
+        catch (error) {
+            this.reportError('Failed to hydrate REST data fallback', error);
+        }
+    }
+    applyRestDataFallback(payload) {
+        try {
+            if (!this.xmlFragment)
+                return;
+            if (this.enforceForceResetInitialContent(false)) {
+                return;
+            }
+            const rawData = extractRestDataString(payload);
+            if (!rawData)
+                return;
+            const rawContent = rawFromXmlLikeString(rawData);
+            if (!rawContent)
+                return;
+            const currentRaw = rawFromXmlFragment(this.xmlFragment);
+            if (rawContentsEqual(currentRaw, rawContent))
+                return;
+            const doc = this.store?.getDoc();
+            if (doc) {
+                doc.transact(() => {
+                    writeRawToXmlFragment(this.xmlFragment, rawContent);
+                }, 'remote-rest-data');
+            }
+            else {
+                writeRawToXmlFragment(this.xmlFragment, rawContent);
+            }
+            this.lastRawJson = serializeRawContent(rawContent);
+            this.applyFragmentToEditor(false);
+            this.store?.notifySubscribers();
+        }
+        catch (error) {
+            this.reportError('Failed to apply REST data fallback', error);
+        }
+    }
+    applyRestXmlFragmentToDraft(preserveSelection, force = false) {
+        try {
+            if (!this.xmlFragment || !this.restXmlFragment || this.restXmlFragment.length === 0) {
+                return false;
+            }
+            if (this.enforceForceResetInitialContent(preserveSelection)) {
+                return true;
+            }
+            if (!force && this.xmlFragment.length > 0) {
+                return false;
+            }
+            const rawContent = rawFromXmlFragment(this.restXmlFragment)
+                ?? rawFromXmlLikeString(this.restXmlFragment.toString());
+            if (!rawContent)
+                return false;
+            const currentRaw = rawFromXmlFragment(this.xmlFragment);
+            if (rawContentsEqual(currentRaw, rawContent))
+                return false;
+            const doc = this.store?.getDoc();
+            if (doc) {
+                doc.transact(() => {
+                    writeRawToXmlFragment(this.xmlFragment, rawContent);
+                }, this.restBridgeOrigin);
+            }
+            else {
+                writeRawToXmlFragment(this.xmlFragment, rawContent);
+            }
+            this.lastRawJson = serializeRawContent(rawContent);
+            this.applyFragmentToEditor(preserveSelection);
+            this.store?.notifySubscribers();
+            return true;
+        }
+        catch (error) {
+            this.reportError('Failed to bridge REST XML content', error);
+            return false;
+        }
+    }
+    updateAwarenessFromEditorState(editorState) {
+        try {
+            this.updateAwarenessSelection(editorState.getSelection());
+        }
+        catch (error) {
+            this.reportError('Failed to update awareness from editor state', error);
+        }
+    }
+    scheduleSnapshotSave() {
+        try {
+            if (this.snapshotSaveTimer) {
+                clearTimeout(this.snapshotSaveTimer);
+            }
+            const delay = Math.max(100, Math.min(this.config.debounceMs ?? 250, 1000));
+            this.snapshotSaveTimer = setTimeout(() => {
+                this.snapshotSaveTimer = null;
+                void this.saveCurrentSnapshot();
+            }, delay);
+        }
+        catch (error) {
+            this.reportError('Failed to schedule CRDT snapshot save', error);
+        }
+    }
+    enforceForceResetInitialContent(preserveSelection) {
+        try {
+            if (!this.config.forceResetInitialContent
+                || this.hasLocalEditAfterForceReset
+                || !this.forceResetStrict
+                || this.isForceResetOpenForEdits()
+                || !this.forceResetRawContent
+                || !this.xmlFragment) {
+                return false;
+            }
+            const currentRaw = rawFromXmlFragment(this.xmlFragment);
+            if (rawContentsEqual(currentRaw, this.forceResetRawContent)) {
+                return false;
+            }
+            const doc = this.store?.getDoc();
+            if (doc) {
+                doc.transact(() => {
+                    writeRawToXmlFragment(this.xmlFragment, this.forceResetRawContent);
+                    if (this.restXmlFragment) {
+                        writeRawToXmlFragment(this.restXmlFragment, this.forceResetRawContent);
+                    }
+                    this.markForceResetBaseline(false, doc);
+                }, this.initialOrigin);
+            }
+            else {
+                writeRawToXmlFragment(this.xmlFragment, this.forceResetRawContent);
+                if (this.restXmlFragment) {
+                    writeRawToXmlFragment(this.restXmlFragment, this.forceResetRawContent);
+                }
+                this.markForceResetBaseline(false);
+            }
+            this.lastRawJson = this.forceResetRawJson;
+            this.applyFragmentToEditor(preserveSelection);
+            this.store?.notifySubscribers();
+            void this.saveCurrentSnapshot();
+            return true;
+        }
+        catch (error) {
+            this.reportError('Failed to enforce forceResetInitialContent', error);
+            return false;
+        }
+    }
+    shouldOpenForceResetForEdits(nextRawJson) {
+        try {
+            if (!nextRawJson)
+                return false;
+            const doc = this.store?.getDoc();
+            if (!doc)
+                return false;
+            const configMap = doc.getMap(CONFIG_MAP_KEY);
+            if (!configMap.has(FORCE_RESET_REVISION_KEY))
+                return false;
+            return !this.forceResetRawJson || nextRawJson !== this.forceResetRawJson;
+        }
+        catch {
+            return false;
+        }
+    }
+    markForceResetBaseline(newRevision, docOverride) {
+        try {
+            const doc = docOverride ?? this.store?.getDoc();
+            if (!doc)
+                return;
+            const configMap = doc.getMap(CONFIG_MAP_KEY);
+            if (newRevision || !configMap.has(FORCE_RESET_REVISION_KEY)) {
+                configMap.set(FORCE_RESET_REVISION_KEY, `${Date.now()}-${Math.random().toString(36).slice(2)}`);
+            }
+            configMap.set(FORCE_RESET_OPEN_FOR_EDITS_KEY, false);
+        }
+        catch (error) {
+            this.reportError('Failed to mark forceReset baseline metadata', error);
+        }
+    }
+    publishVersionChange(reason, versionId, versionName) {
+        try {
+            const metadata = this.versionMetadata ?? this.store?.getDoc().getMap(VERSION_META_MAP_KEY);
+            if (!metadata)
+                return;
+            const doc = this.store?.getDoc();
+            const event = {
+                revision: `${Date.now()}-${Math.random().toString(36).slice(2)}`,
+                reason,
+                versionId,
+                versionName,
+                userId: this.userId,
+                timestamp: Date.now(),
+            };
+            if (doc) {
+                doc.transact(() => {
+                    metadata.set(VERSION_META_LAST_CHANGE_KEY, event);
+                }, { source: STORE_SOURCE, direction: 'version-metadata' });
+            }
+            else {
+                metadata.set(VERSION_META_LAST_CHANGE_KEY, event);
+            }
+        }
+        catch (error) {
+            this.reportError('Failed to publish version metadata change', error);
+        }
+    }
+    readVersionChangeEvent() {
+        try {
+            const value = this.versionMetadata?.get(VERSION_META_LAST_CHANGE_KEY);
+            if (!value || typeof value !== 'object')
+                return null;
+            const event = value;
+            if (typeof event.revision !== 'string')
+                return null;
+            if (event.reason !== 'save' && event.reason !== 'restore' && event.reason !== 'set-state')
+                return null;
+            if (typeof event.timestamp !== 'number')
+                return null;
+            return event;
+        }
+        catch {
+            return null;
+        }
+    }
+    markForceResetOpenForEdits(doc) {
+        try {
+            const configMap = doc.getMap(CONFIG_MAP_KEY);
+            if (configMap.has(FORCE_RESET_REVISION_KEY)) {
+                configMap.set(FORCE_RESET_OPEN_FOR_EDITS_KEY, true);
+            }
+        }
+        catch (error) {
+            this.reportError('Failed to mark forceReset as open for edits', error);
+        }
+    }
+    isForceResetOpenForEdits() {
+        try {
+            const doc = this.store?.getDoc();
+            if (!doc)
+                return false;
+            return doc.getMap(CONFIG_MAP_KEY).get(FORCE_RESET_OPEN_FOR_EDITS_KEY) === true;
+        }
+        catch {
+            return false;
+        }
+    }
+    mirrorCurrentDraftToRestXml(origin) {
+        try {
+            if (!this.xmlFragment)
+                return false;
+            const rawContent = rawFromXmlFragment(this.xmlFragment);
+            if (!rawContent)
+                return false;
+            return this.mirrorRawToRestXml(rawContent, origin);
+        }
+        catch (error) {
+            this.reportError('Failed to mirror Draft.js XML to REST sidecar', error);
+            return false;
+        }
+    }
+    mirrorRawToRestXml(rawContent, origin) {
+        try {
+            if (!this.restXmlFragment)
+                return false;
+            const currentRestRaw = rawFromXmlFragment(this.restXmlFragment);
+            if (rawContentsEqual(currentRestRaw, rawContent))
+                return false;
+            const doc = this.store?.getDoc();
+            if (doc) {
+                doc.transact(() => {
+                    writeRawToXmlFragment(this.restXmlFragment, rawContent);
+                }, origin);
+            }
+            else {
+                writeRawToXmlFragment(this.restXmlFragment, rawContent);
+            }
+            return true;
+        }
+        catch (error) {
+            this.reportError('Failed to mirror Draft.js raw content to REST sidecar', error);
+            return false;
+        }
+    }
+    async saveCurrentSnapshot() {
+        try {
+            const doc = this.store?.getDoc();
+            const crdtElement = this.getCrdtElement();
+            if (!doc || !crdtElement?.saveSnapshot)
+                return;
+            await crdtElement.saveSnapshot({
+                id: this.config.editorId,
+                state: Array.from(Y.encodeStateAsUpdate(doc)),
+                vector: Array.from(Y.encodeStateVector(doc)),
+                type: 'xml',
+                contentKey: CONTENT_KEY,
+                source: STORE_SOURCE,
+            });
+        }
+        catch (error) {
+            this.reportError('Failed to save CRDT snapshot', error);
+        }
+    }
+    updateAwarenessSelection(selection) {
+        try {
+            if (!this.store)
+                return;
+            const cursorSelection = selection ? selectionToCursor(selection) : null;
+            this.store.updateAwareness({
+                source: STORE_SOURCE,
+                editorId: this.config.editorId,
+                cursorData: this.config.cursorData,
+                selection: cursorSelection,
+            });
+        }
+        catch (error) {
+            this.reportError('Failed to update awareness selection', error);
+        }
+    }
+    readRemoteCursors() {
+        try {
+            const awareness = this.getAwareness();
+            if (!awareness)
+                return [];
+            const localClientId = awareness.clientID;
+            const cursors = [];
+            awareness.getStates().forEach((state, clientId) => {
+                if (clientId === localClientId)
+                    return;
+                if (state?.source !== STORE_SOURCE)
+                    return;
+                if (state?.editorId !== this.config.editorId)
+                    return;
+                cursors.push({
+                    clientId,
+                    user: state.user,
+                    cursorData: state.cursorData,
+                    selection: state.selection,
+                });
+            });
+            return cursors;
+        }
+        catch (error) {
+            this.reportError('Failed to read awareness states', error);
+            return [];
+        }
+    }
+    safeGetEditorState() {
+        try {
+            return this.config.getEditorState();
+        }
+        catch (error) {
+            this.reportError('Failed to get Draft.js editor state', error);
+            return null;
+        }
+    }
+    resolveUserId() {
+        try {
+            const user = this.config.veltClient?.getUser?.();
+            return user?.userId || 'anonymous';
+        }
+        catch {
+            return 'anonymous';
+        }
+    }
+    getCrdtElement() {
+        try {
+            return this.config.veltClient?.getCrdtElement?.() ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    getRestXmlFragment() {
+        try {
+            if (!this.store)
+                return null;
+            const restContentKey = this.config.restContentKey ?? DEFAULT_REST_CONTENT_KEY;
+            if (!restContentKey || restContentKey === CONTENT_KEY)
+                return null;
+            return this.store.getDoc().getXmlFragment(restContentKey);
+        }
+        catch (error) {
+            this.reportError('Failed to get REST XML fragment', error);
+            return null;
+        }
+    }
+    isCorruptionError(error) {
+        try {
+            const msg = String(error);
+            return msg.includes('contentRefs') || msg.includes('Unexpected end of array');
+        }
+        catch {
+            return false;
+        }
+    }
+    async tryRecoverFromCorruption() {
+        try {
+            logError('Encountered Yjs corruption error, attempting recovery');
+            this.store?.destroy();
+            this.store = this.createStore();
+            this.xmlFragment = this.store.getXml();
+            this.bindXmlFragment();
+            this.createUndoManager();
+            await this.store.initialize();
+        }
+        catch (error) {
+            this.reportError('Recovery failed, editor will function in degraded state', error);
+        }
+    }
+    reportError(message, error) {
+        try {
+            logError(message, error);
+            this.config.onError?.(error instanceof Error ? error : new Error(String(error)));
+        }
+        catch {
+            // Never throw while reporting errors.
+        }
+    }
+}
+async function createCollaboration(config) {
+    try {
+        const manager = new CollaborationManager(config);
+        await manager.initialize();
+        return manager;
+    }
+    catch (error) {
+        logError('Failed to create collaboration', error);
+        return new CollaborationManager(config);
+    }
+}
+function selectionToCursor(selection) {
+    return {
+        anchorKey: selection.getAnchorKey(),
+        anchorOffset: selection.getAnchorOffset(),
+        focusKey: selection.getFocusKey(),
+        focusOffset: selection.getFocusOffset(),
+        isBackward: selection.getIsBackward(),
+        hasFocus: selection.getHasFocus(),
+    };
+}
+function extractRestDataString(payload) {
+    try {
+        if (!payload || typeof payload !== 'object')
+            return null;
+        const data = payload.data;
+        if (typeof data === 'string')
+            return data;
+        const nested = payload.result?.data;
+        if (Array.isArray(nested) && typeof nested[0]?.data === 'string')
+            return nested[0].data;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function rawDraftContentSemanticallyEqual(a, b) {
+    try {
+        if (!a || !b || a.blocks.length !== b.blocks.length)
+            return false;
+        return a.blocks.every((block, index) => {
+            const other = b.blocks[index];
+            return !!other
+                && block.text === other.text
+                && block.type === other.type
+                && (block.depth ?? 0) === (other.depth ?? 0)
+                && JSON.stringify(block.inlineStyleRanges ?? []) === JSON.stringify(other.inlineStyleRanges ?? [])
+                && JSON.stringify(block.entityRanges ?? []) === JSON.stringify(other.entityRanges ?? [])
+                && JSON.stringify(block.data ?? {}) === JSON.stringify(other.data ?? {});
+        });
+    }
+    catch {
+        return false;
+    }
+}
+
+// POLICY: Every function/method in this file MUST be wrapped in try/catch.
+// The package must NEVER throw an exception to the consumer's code.
+/**
+ * useCollaboration — React hook for Draft.js collaboration.
+ *
+ * Thin React wrapper over CollaborationManager from ./manager (Draft.js is a
+ * React-only editor; this hook matches the useCollaboration convention of
+ * the other Velt CRDT React wrappers).
+ *
+ * Draft.js is a controlled editor: the consumer owns the EditorState and
+ * passes getEditorState/setEditorState accessors. Wire the returned
+ * `handleChange` into the <Editor onChange> pipeline:
+ *
+ *   const [editorState, setEditorState] = useState(EditorState.createEmpty());
+ *   const { handleChange } = useCollaboration({
+ *     editorId, getEditorState: () => editorState, setEditorState,
+ *   });
+ *   <Editor editorState={editorState} onChange={(s) => setEditorState(handleChange(s))} />
+ */
+function useCollaboration(config) {
+    const { client } = useVeltClient();
+    const veltInitState = useVeltInitState();
+    const [manager, setManager] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [synced, setSynced] = useState(false);
+    const [status, setStatus] = useState('connecting');
+    const [error, setError] = useState(null);
+    const [versions, setVersions] = useState([]);
+    const managerRef = useRef(null);
+    // Tracks component mount across the whole lifecycle so the stable version
+    // callbacks below never set state after unmount.
+    const isMountedRef = useRef(true);
+    useEffect(() => {
+        isMountedRef.current = true;
+        return () => {
+            isMountedRef.current = false;
+        };
+    }, []);
+    // Keep the consumer's controlled-state accessors fresh without
+    // recreating the manager on every render.
+    const getEditorStateRef = useRef(config.getEditorState);
+    const setEditorStateRef = useRef(config.setEditorState);
+    getEditorStateRef.current = config.getEditorState;
+    setEditorStateRef.current = config.setEditorState;
+    // Resolve veltClient: explicit config override or context fallback
+    const veltClient = config.veltClient ?? client;
+    useEffect(() => {
+        try {
+            // Gate 1: Velt must be initialized
+            if (!veltClient || !veltInitState)
+                return;
+            // Gate 2: User must exist (avoid creating an anonymous store)
+            let user;
+            try {
+                user = veltClient.getUser?.();
+            }
+            catch {
+                // getUser may throw if Velt isn't ready
+            }
+            if (!user)
+                return;
+            // Gate 3: Controlled-state accessors must exist
+            if (!config.getEditorState || !config.setEditorState)
+                return;
+            let mounted = true;
+            const init = async () => {
+                try {
+                    const created = await createCollaboration({
+                        ...config,
+                        veltClient,
+                        getEditorState: () => getEditorStateRef.current(),
+                        setEditorState: (state) => setEditorStateRef.current(state),
+                        // Bridge non-fatal manager errors into the hook's error state and
+                        // forward to the consumer's own handler.
+                        onError: (err) => {
+                            try {
+                                if (mounted)
+                                    setError(err);
+                                config.onError?.(err);
+                            }
+                            catch { /* ignore */ }
+                        },
+                    });
+                    if (!mounted) {
+                        try {
+                            created.destroy();
+                        }
+                        catch { /* ignore */ }
+                        return;
+                    }
+                    managerRef.current = created;
+                    setManager(created);
+                    created.onStatusChange((s) => {
+                        try {
+                            if (mounted)
+                                setStatus(s);
+                        }
+                        catch { /* ignore */ }
+                    });
+                    created.onSynced((isSyncedNow) => {
+                        try {
+                            if (mounted)
+                                setSynced(isSyncedNow);
+                        }
+                        catch { /* ignore */ }
+                    });
+                    // Draft.js manager exposes an event-driven version-change signal —
+                    // the event carries metadata only (no list), so refetch on each one
+                    // to keep the reactive list live without polling.
+                    try {
+                        created.onVersionsChange(() => {
+                            try {
+                                void created.getVersions().then((list) => {
+                                    try {
+                                        if (mounted && isMountedRef.current)
+                                            setVersions(list);
+                                    }
+                                    catch { /* ignore */ }
+                                }).catch((err) => {
+                                    logError('Failed to refresh versions after change event', err);
+                                });
+                            }
+                            catch { /* ignore */ }
+                        });
+                    }
+                    catch (err) {
+                        logError('Failed to subscribe to version changes', err);
+                    }
+                    // Capture current state (fast-connection race condition)
+                    if (created.synced)
+                        setSynced(true);
+                    if (created.status !== 'connecting')
+                        setStatus(created.status);
+                    try {
+                        const list = await created.getVersions();
+                        if (mounted)
+                            setVersions(list);
+                    }
+                    catch (err) {
+                        logError('Failed to load initial versions', err);
+                    }
+                    if (mounted)
+                        setIsLoading(false);
+                }
+                catch (err) {
+                    logError('Failed to initialize collaboration', err);
+                    if (mounted) {
+                        setError(err instanceof Error ? err : new Error(String(err)));
+                        setIsLoading(false);
+                    }
+                }
+            };
+            init();
+            return () => {
+                try {
+                    mounted = false;
+                    if (managerRef.current) {
+                        managerRef.current.destroy();
+                        managerRef.current = null;
+                    }
+                    setManager(null);
+                    setIsLoading(true);
+                    setSynced(false);
+                    setStatus('connecting');
+                    setError(null);
+                    setVersions([]);
+                }
+                catch { /* ignore cleanup errors */ }
+            };
+        }
+        catch (err) {
+            logError('Error in useCollaboration effect', err);
+        }
+        // Content/debounce changes don't recreate the manager (captured at init).
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [veltClient, veltInitState, config.editorId]);
+    /** Route local Draft.js changes through the CRDT (identity while loading). */
+    const handleChange = useCallback((nextState) => {
+        try {
+            const active = managerRef.current;
+            if (!active)
+                return nextState;
+            return active.handleChange(nextState);
+        }
+        catch (err) {
+            logError('Failed to handle editor change', err);
+            return nextState;
+        }
+    }, []);
+    // --- Version methods (stable callbacks) ---
+    const refreshVersions = useCallback(async () => {
+        try {
+            const list = (await managerRef.current?.getVersions()) ?? [];
+            if (isMountedRef.current)
+                setVersions(list);
+            return list;
+        }
+        catch (err) {
+            logError('Failed to refresh versions', err);
+            return [];
+        }
+    }, []);
+    const saveVersion = useCallback(async (name) => {
+        try {
+            const id = (await managerRef.current?.saveVersion(name)) ?? '';
+            try {
+                const list = (await managerRef.current?.getVersions()) ?? [];
+                if (isMountedRef.current)
+                    setVersions(list);
+            }
+            catch { /* list refresh is best-effort */ }
+            return id;
+        }
+        catch (err) {
+            logError('Failed to save version', err);
+            return '';
+        }
+    }, []);
+    const restoreVersion = useCallback(async (versionId) => {
+        try {
+            return (await managerRef.current?.restoreVersion(versionId)) ?? false;
+        }
+        catch (err) {
+            logError('Failed to restore version', err);
+            return false;
+        }
+    }, []);
+    const destroy = useCallback(() => {
+        try {
+            managerRef.current?.destroy();
+            managerRef.current = null;
+            setManager(null);
+            setSynced(false);
+            setStatus('disconnected');
+        }
+        catch (err) {
+            logError('Failed to destroy manager', err);
+        }
+    }, []);
+    return {
+        handleChange,
+        manager,
+        isLoading,
+        synced,
+        isSynced: synced,
+        status,
+        error,
+        versions,
+        saveVersion,
+        restoreVersion,
+        refreshVersions,
+        destroy,
+    };
+}
+/** Library-specific alias (mirrors useSlateCollaboration / useTinyMceCollaboration). */
+const useDraftJsCollaboration = useCollaboration;
+
+export { CollaborationManager, createCollaboration, useCollaboration, useDraftJsCollaboration };
+//# sourceMappingURL=index.js.map