@kritzel/engine 0.4.31

package/dist/collection/classes/providers/sync/hocuspocus-sync-provider.class.js

@@ -0,0 +1,333 @@
+import { HocuspocusProvider, HocuspocusProviderWebsocket } from "@hocuspocus/provider";
+/**
+ * Hocuspocus sync provider for real-time collaboration
+ * Supports multiplexing - multiple documents can share the same WebSocket connection
+ */
+export class HocuspocusSyncProvider {
+    static type = 'network';
+    type = 'network';
+    provider;
+    isConnected = false;
+    isSynced = false;
+    usesSharedSocket = false;
+    isDestroyed = false;
+    connectTimeout = null;
+    pendingConnectReject = null;
+    connectionTimeoutMs;
+    _connectionStatus = 'disconnected';
+    visibilityHandler = null;
+    onlineHandler = null;
+    get awareness() {
+        return this.provider.awareness;
+    }
+    get rawProvider() {
+        return this.provider;
+    }
+    get connectionStatus() {
+        return this._connectionStatus;
+    }
+    // Static shared WebSocket instance for multiplexing
+    static sharedWebSocketProvider = null;
+    constructor(docName, doc, options) {
+        const name = options?.name || docName;
+        const url = options?.url || 'ws://localhost:1234';
+        this.connectionTimeoutMs = options?.connectionTimeout ?? 10000;
+        // Use provided websocketProvider or the static shared one
+        const websocketProvider = options?.websocketProvider || HocuspocusSyncProvider.sharedWebSocketProvider;
+        // Build reconnect config from options
+        const reconnectConfig = {};
+        if (options?.delay !== undefined)
+            reconnectConfig.delay = options.delay;
+        if (options?.factor !== undefined)
+            reconnectConfig.factor = options.factor;
+        if (options?.maxAttempts !== undefined)
+            reconnectConfig.maxAttempts = options.maxAttempts;
+        if (options?.minDelay !== undefined)
+            reconnectConfig.minDelay = options.minDelay;
+        if (options?.maxDelay !== undefined)
+            reconnectConfig.maxDelay = options.maxDelay;
+        const onConnect = () => {
+            if (this.isDestroyed) {
+                return;
+            }
+            this.isConnected = true;
+            this._connectionStatus = 'connected';
+            if (!options?.quiet) {
+                console.info(`Hocuspocus connected: ${name}`);
+            }
+            if (options?.onConnect) {
+                options.onConnect();
+            }
+        };
+        const onDisconnect = () => {
+            if (this.isDestroyed) {
+                return;
+            }
+            this.isConnected = false;
+            this.isSynced = false;
+            this._connectionStatus = 'disconnected';
+            if (!options?.quiet) {
+                console.info(`Hocuspocus disconnected: ${name}`);
+            }
+            if (options?.onDisconnect) {
+                options.onDisconnect();
+            }
+        };
+        const onSynced = () => {
+            if (this.isDestroyed) {
+                return;
+            }
+            this.isSynced = true;
+            this._connectionStatus = 'synced';
+            if (!options?.quiet) {
+                console.info(`Hocuspocus synced: ${name}`);
+            }
+            if (options?.onSynced) {
+                options.onSynced();
+            }
+        };
+        const onStatus = (data) => {
+            if (this.isDestroyed) {
+                return;
+            }
+            if (data.status === 'connecting') {
+                this._connectionStatus = 'connecting';
+            }
+            if (options?.onStatus) {
+                options.onStatus(data);
+            }
+        };
+        if (websocketProvider) {
+            // Multiplexing mode - use shared WebSocket connection
+            this.usesSharedSocket = true;
+            const config = {
+                websocketProvider,
+                name,
+                document: doc,
+                token: options?.token || null,
+                onStatus,
+                onConnect,
+                onDisconnect,
+                onSynced,
+                ...reconnectConfig,
+            };
+            // Add optional settings
+            if (options?.forceSyncInterval !== undefined) {
+                config.forceSyncInterval = options.forceSyncInterval;
+            }
+            if (options?.onAuthenticationFailed) {
+                config.onAuthenticationFailed = options.onAuthenticationFailed;
+            }
+            this.provider = new HocuspocusProvider(config);
+            // Must call attach() explicitly when using shared socket
+            this.provider.attach();
+            if (!options?.quiet) {
+                console.info(`Hocuspocus Provider initialized (multiplexed): ${name}`);
+            }
+        }
+        else {
+            // Standalone mode - create own WebSocket connection
+            this.usesSharedSocket = false;
+            const config = {
+                url,
+                name,
+                document: doc,
+                token: options?.token || null,
+                autoConnect: false,
+                onStatus,
+                onConnect,
+                onDisconnect,
+                onSynced,
+                ...reconnectConfig,
+            };
+            // Add optional settings
+            if (options?.forceSyncInterval !== undefined) {
+                config.forceSyncInterval = options.forceSyncInterval;
+            }
+            if (options?.onAuthenticationFailed) {
+                config.onAuthenticationFailed = options.onAuthenticationFailed;
+            }
+            if (options?.WebSocketPolyfill) {
+                config.WebSocketPolyfill = options.WebSocketPolyfill;
+            }
+            this.provider = new HocuspocusProvider(config);
+            if (!options?.quiet) {
+                console.info(`Hocuspocus Provider initialized: ${url}/${name}`);
+            }
+        }
+        this.setupBrowserEventListeners();
+    }
+    setupBrowserEventListeners() {
+        if (typeof document !== 'undefined') {
+            this.visibilityHandler = () => {
+                if (document.visibilityState === 'visible' && !this.isConnected && !this.isDestroyed) {
+                    this.provider.connect();
+                }
+            };
+            document.addEventListener('visibilitychange', this.visibilityHandler);
+        }
+        if (typeof window !== 'undefined') {
+            this.onlineHandler = () => {
+                if (!this.isConnected && !this.isDestroyed) {
+                    this.provider.connect();
+                }
+            };
+            window.addEventListener('online', this.onlineHandler);
+        }
+    }
+    removeBrowserEventListeners() {
+        if (this.visibilityHandler && typeof document !== 'undefined') {
+            document.removeEventListener('visibilitychange', this.visibilityHandler);
+            this.visibilityHandler = null;
+        }
+        if (this.onlineHandler && typeof window !== 'undefined') {
+            window.removeEventListener('online', this.onlineHandler);
+            this.onlineHandler = null;
+        }
+    }
+    /**
+     * Create a shared WebSocket connection for multiplexing
+     * Call this once to create a shared connection that multiple providers can use
+     */
+    static createSharedWebSocket(options) {
+        if (HocuspocusSyncProvider.sharedWebSocketProvider) {
+            console.warn('Shared WebSocket already exists. Returning existing instance.');
+            return HocuspocusSyncProvider.sharedWebSocketProvider;
+        }
+        const config = {
+            url: options.url,
+        };
+        if (options.WebSocketPolyfill) {
+            config.WebSocketPolyfill = options.WebSocketPolyfill;
+        }
+        if (options.onConnect) {
+            config.onConnect = options.onConnect;
+        }
+        if (options.onDisconnect) {
+            config.onDisconnect = options.onDisconnect;
+        }
+        if (options.onStatus) {
+            config.onStatus = options.onStatus;
+        }
+        HocuspocusSyncProvider.sharedWebSocketProvider = new HocuspocusProviderWebsocket(config);
+        console.info(`Shared Hocuspocus WebSocket created: ${options.url}`);
+        return HocuspocusSyncProvider.sharedWebSocketProvider;
+    }
+    /**
+     * Destroy the shared WebSocket connection
+     * Call this when you're done with all multiplexed providers
+     */
+    static destroySharedWebSocket() {
+        if (HocuspocusSyncProvider.sharedWebSocketProvider) {
+            HocuspocusSyncProvider.sharedWebSocketProvider.destroy();
+            HocuspocusSyncProvider.sharedWebSocketProvider = null;
+            console.info('Shared Hocuspocus WebSocket destroyed');
+        }
+    }
+    /**
+     * Get the shared WebSocket provider instance (if it exists)
+     */
+    static getSharedWebSocket() {
+        return HocuspocusSyncProvider.sharedWebSocketProvider;
+    }
+    /**
+     * Static factory method for creating HocuspocusSyncProvider with configuration options
+     * Returns a ProviderFactory that can be used in sync configuration
+     */
+    static with(options) {
+        return {
+            type: 'network',
+            create: (docName, doc, runtimeOptions) => {
+                const mergedOptions = runtimeOptions ? { ...options, ...runtimeOptions } : options;
+                return new HocuspocusSyncProvider(docName, doc, mergedOptions);
+            },
+        };
+    }
+    async connect() {
+        if (this.isSynced || this.isDestroyed) {
+            return;
+        }
+        this._connectionStatus = 'connecting';
+        return new Promise((resolve, reject) => {
+            // Store reject function so we can cancel the connection if destroyed
+            this.pendingConnectReject = reject;
+            this.connectTimeout = setTimeout(() => {
+                this.pendingConnectReject = null;
+                this.connectTimeout = null;
+                reject(new Error('Hocuspocus connection timeout'));
+            }, this.connectionTimeoutMs);
+            const syncHandler = () => {
+                if (this.connectTimeout) {
+                    clearTimeout(this.connectTimeout);
+                    this.connectTimeout = null;
+                }
+                this.pendingConnectReject = null;
+                this.provider.off('synced', syncHandler);
+                if (!this.isDestroyed) {
+                    resolve();
+                }
+            };
+            this.provider.on('synced', syncHandler);
+            // If already synced, resolve immediately
+            if (this.provider.isSynced) {
+                if (this.connectTimeout) {
+                    clearTimeout(this.connectTimeout);
+                    this.connectTimeout = null;
+                }
+                this.pendingConnectReject = null;
+                this.provider.off('synced', syncHandler);
+                resolve();
+                return;
+            }
+            // Connect if not already connected (standalone mode only)
+            if (!this.isConnected && !this.usesSharedSocket) {
+                this.provider.connect();
+            }
+        });
+    }
+    async reconnect() {
+        this.disconnect();
+        return this.connect();
+    }
+    disconnect() {
+        // Cancel any pending connection attempt
+        if (this.connectTimeout) {
+            clearTimeout(this.connectTimeout);
+            this.connectTimeout = null;
+        }
+        if (this.pendingConnectReject) {
+            this.pendingConnectReject = null; // Don't reject, just abandon the promise
+        }
+        if (this.provider) {
+            if (this.usesSharedSocket) {
+                // Detach from shared socket instead of disconnecting
+                this.provider.detach();
+            }
+            else {
+                this.provider.disconnect();
+            }
+        }
+        this.isConnected = false;
+        this.isSynced = false;
+        this._connectionStatus = 'disconnected';
+    }
+    destroy() {
+        // Mark as destroyed first to prevent any callbacks from doing work
+        this.isDestroyed = true;
+        // Cancel any pending connection attempt
+        if (this.connectTimeout) {
+            clearTimeout(this.connectTimeout);
+            this.connectTimeout = null;
+        }
+        if (this.pendingConnectReject) {
+            this.pendingConnectReject = null; // Don't reject, just abandon the promise
+        }
+        this.removeBrowserEventListeners();
+        if (this.provider) {
+            this.provider.destroy();
+        }
+        this.isConnected = false;
+        this.isSynced = false;
+        this._connectionStatus = 'disconnected';
+    }
+}

package/dist/collection/classes/providers/sync/in-memory-sync-provider.class.js

@@ -0,0 +1,69 @@
+import * as Y from "yjs";
+/**
+ * Module-scoped cache that survives component removal and remounting
+ * within the same JS runtime. Cleared on page reload.
+ */
+const sessionCache = new Map();
+/**
+ * In-memory sync provider for session-scoped persistence.
+ *
+ * State survives the component being removed from the DOM and later
+ * re-added within the same page session, but is lost on page reload.
+ * Intended for documentation demos where durable IndexedDB persistence
+ * is not desired.
+ */
+export class InMemorySyncProvider {
+    static type = 'local';
+    type = 'local';
+    doc;
+    cacheKey;
+    isConnected = false;
+    constructor(docName, doc, options) {
+        this.doc = doc;
+        this.cacheKey = options?.name ?? docName;
+    }
+    handleUpdate = (_update, origin) => {
+        // Skip updates that originated from connect() rehydration to avoid a
+        // redundant re-encode of the state we just applied.
+        if (origin === this) {
+            return;
+        }
+        sessionCache.set(this.cacheKey, Y.encodeStateAsUpdate(this.doc));
+    };
+    async connect() {
+        if (this.isConnected) {
+            return;
+        }
+        const cached = sessionCache.get(this.cacheKey);
+        if (cached) {
+            Y.applyUpdate(this.doc, cached, this);
+        }
+        this.doc.on('update', this.handleUpdate);
+        this.isConnected = true;
+    }
+    disconnect() {
+        this.isConnected = false;
+    }
+    async reconnect() {
+        this.disconnect();
+        return this.connect();
+    }
+    destroy() {
+        this.doc.off('update', this.handleUpdate);
+        this.isConnected = false;
+    }
+    /**
+     * Clears the in-memory cache.
+     *
+     * @param name - If provided, only the entry with this cache key is removed.
+     *               If omitted, all entries are cleared.
+     */
+    static clear(name) {
+        if (name !== undefined) {
+            sessionCache.delete(name);
+        }
+        else {
+            sessionCache.clear();
+        }
+    }
+}

package/dist/collection/classes/providers/sync/indexeddb-sync-provider.class.js

@@ -0,0 +1,39 @@
+import { IndexeddbPersistence } from "y-indexeddb";
+/**
+ * IndexedDB sync provider for local persistence
+ */
+export class IndexedDBSyncProvider {
+    static type = 'local';
+    type = 'local';
+    provider;
+    isConnected = false;
+    constructor(docName, doc, options) {
+        const dbName = options?.name || docName;
+        this.provider = new IndexeddbPersistence(dbName, doc);
+    }
+    async connect() {
+        if (this.isConnected) {
+            return;
+        }
+        return new Promise(resolve => {
+            this.provider.on('synced', () => {
+                this.isConnected = true;
+                resolve();
+            });
+        });
+    }
+    disconnect() {
+        // IndexedDB doesn't need explicit disconnect
+        this.isConnected = false;
+    }
+    async reconnect() {
+        this.disconnect();
+        return this.connect();
+    }
+    destroy() {
+        if (this.provider) {
+            this.provider.destroy();
+        }
+        this.isConnected = false;
+    }
+}

package/dist/collection/classes/providers/sync/websocket-sync-provider.class.js

@@ -0,0 +1,110 @@
+import { WebsocketProvider } from "y-websocket";
+/**
+ * WebSocket sync provider for real-time collaboration
+ */
+export class WebSocketSyncProvider {
+    static type = 'network';
+    type = 'network';
+    provider;
+    isConnected = false;
+    _quiet = false;
+    get awareness() {
+        return this.provider.awareness;
+    }
+    get rawProvider() {
+        return this.provider;
+    }
+    constructor(docName, doc, options) {
+        const url = options?.url || 'ws://localhost:1234';
+        const roomName = options?.roomName || docName;
+        this.provider = new WebsocketProvider(url, roomName, doc, {
+            params: options?.params,
+            protocols: options?.protocols,
+            WebSocketPolyfill: options?.WebSocketPolyfill,
+            awareness: options?.awareness,
+            maxBackoffTime: options?.maxBackoffTime,
+            disableBc: true,
+        });
+        this._quiet = options?.quiet ?? false;
+        this.setupEventListeners();
+        if (!this._quiet) {
+            console.info(`WebSocket Provider initialized: ${url}/${roomName}`);
+        }
+    }
+    /**
+     * Static factory method for creating WebSocketSyncProvider with configuration options
+     * Returns a ProviderFactory that can be used in sync configuration
+     */
+    static with(options) {
+        return {
+            type: 'network',
+            create: (docName, doc, runtimeOptions) => {
+                const mergedOptions = runtimeOptions ? { ...options, ...runtimeOptions } : options;
+                return new WebSocketSyncProvider(docName, doc, mergedOptions);
+            },
+        };
+    }
+    setupEventListeners() {
+        this.provider.on('status', ({ status }) => {
+            if (status === 'connected') {
+                this.isConnected = true;
+                if (!this._quiet) {
+                    console.info('WebSocket connected');
+                }
+            }
+            else if (status === 'disconnected') {
+                this.isConnected = false;
+                if (!this._quiet) {
+                    console.info('WebSocket disconnected');
+                }
+            }
+        });
+        this.provider.on('sync', (synced) => {
+            if (synced && !this._quiet) {
+                console.info('WebSocket synced');
+            }
+        });
+    }
+    async connect() {
+        if (this.isConnected) {
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new Error('WebSocket connection timeout'));
+            }, 10000); // 10 second timeout
+            const statusHandler = ({ status }) => {
+                if (status === 'connected') {
+                    clearTimeout(timeout);
+                    this.provider.off('status', statusHandler);
+                    this.isConnected = true;
+                    resolve();
+                }
+            };
+            this.provider.on('status', statusHandler);
+            // If already connected, resolve immediately
+            if (this.provider.wsconnected) {
+                clearTimeout(timeout);
+                this.provider.off('status', statusHandler);
+                this.isConnected = true;
+                resolve();
+            }
+        });
+    }
+    disconnect() {
+        if (this.provider) {
+            this.provider.disconnect();
+        }
+        this.isConnected = false;
+    }
+    async reconnect() {
+        this.disconnect();
+        return this.connect();
+    }
+    destroy() {
+        if (this.provider) {
+            this.provider.destroy();
+        }
+        this.isConnected = false;
+    }
+}

package/dist/collection/classes/registries/dynamic-object-renderer.registry.js

@@ -0,0 +1,52 @@
+const KRITZEL_RENDERER_REGISTRY_KEY = '__kritzelDynamicObjectRendererRegistry__';
+const getGlobalRegistryStore = () => {
+    const globalScope = globalThis;
+    const existing = globalScope[KRITZEL_RENDERER_REGISTRY_KEY];
+    if (existing) {
+        return existing;
+    }
+    const created = {
+        renderers: new Map(),
+    };
+    globalScope[KRITZEL_RENDERER_REGISTRY_KEY] = created;
+    return created;
+};
+/**
+ * Global registry for dynamic object renderers.
+ * Allows wrapper frameworks (Angular, React, Vue) to register renderer implementations
+ * without coupling to core, and enables deterministic rehydration across reloads and
+ * clipboard paste operations.
+ *
+ * Renderer keys are opaque strings that must be stable (e.g., 'angular-todo', 'react-editor').
+ * When a dynamic object is deserialized with a rendererKey, the registry is consulted to
+ * resolve the renderer and mount with the persisted rendererData.
+ */
+export class KritzelDynamicObjectRendererRegistry {
+    static get _renderers() {
+        return getGlobalRegistryStore().renderers;
+    }
+    /**
+     * Registers a renderer implementation for a given key.
+     * @param key - Stable identifier for this renderer (e.g., 'angular-my-component')
+     * @param renderer - Renderer implementation with mount/unmount/update handlers
+     */
+    static register(key, renderer) {
+        this._renderers.set(key, renderer);
+    }
+    /**
+     * Retrieves a registered renderer by key.
+     * @param key - Renderer identifier
+     * @returns The registered renderer, or undefined if not found
+     */
+    static get(key) {
+        return this._renderers.get(key);
+    }
+    /**
+     * Unregisters a renderer by key.
+     * @param key - Renderer identifier to remove
+     * @returns True if the renderer was found and removed; false otherwise
+     */
+    static unregister(key) {
+        return this._renderers.delete(key);
+    }
+}