kritzel-stencil 0.1.73 → 0.1.75

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

@@ -4,6 +4,7 @@ import { HocuspocusProvider, HocuspocusProviderWebsocket } from "@hocuspocus/pro
  * Supports multiplexing - multiple documents can share the same WebSocket connection
  */
 export class HocuspocusSyncProvider {
+    type = 'network';
     provider;
     isConnected = false;
     isSynced = false;
@@ -11,16 +12,87 @@ export class HocuspocusSyncProvider {
     isDestroyed = false;
     connectTimeout = null;
     pendingConnectReject = null;
+    connectionTimeoutMs;
+    _connectionStatus = 'disconnected';
+    visibilityHandler = null;
+    onlineHandler = null;
     get awareness() {
         return this.provider.awareness;
     }
+    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;
@@ -29,48 +101,11 @@ export class HocuspocusSyncProvider {
                 name,
                 document: doc,
                 token: options?.token || null,
-                onStatus: (data) => {
-                    if (options?.onStatus) {
-                        options.onStatus(data);
-                    }
-                },
-                onConnect: () => {
-                    if (this.isConnected || this.isDestroyed) {
-                        return;
-                    }
-                    this.isConnected = true;
-                    if (!options?.quiet) {
-                        console.info(`Hocuspocus connected: ${name}`);
-                    }
-                    if (options?.onConnect) {
-                        options.onConnect();
-                    }
-                },
-                onDisconnect: () => {
-                    if (this.isDestroyed || (!this.isConnected && !this.isSynced)) {
-                        return;
-                    }
-                    this.isConnected = false;
-                    this.isSynced = false;
-                    if (!options?.quiet) {
-                        console.info(`Hocuspocus disconnected: ${name}`);
-                    }
-                    if (options?.onDisconnect) {
-                        options.onDisconnect();
-                    }
-                },
-                onSynced: () => {
-                    if (this.isSynced || this.isDestroyed) {
-                        return;
-                    }
-                    this.isSynced = true;
-                    if (!options?.quiet) {
-                        console.info(`Hocuspocus synced: ${name}`);
-                    }
-                    if (options?.onSynced) {
-                        options.onSynced();
-                    }
-                },
+                onStatus,
+                onConnect,
+                onDisconnect,
+                onSynced,
+                ...reconnectConfig,
             };
             // Add optional settings
             if (options?.forceSyncInterval !== undefined) {
@@ -95,48 +130,11 @@ export class HocuspocusSyncProvider {
                 document: doc,
                 token: options?.token || null,
                 autoConnect: false,
-                onStatus: (data) => {
-                    if (options?.onStatus) {
-                        options.onStatus(data);
-                    }
-                },
-                onConnect: () => {
-                    if (this.isConnected || this.isDestroyed) {
-                        return;
-                    }
-                    this.isConnected = true;
-                    if (!options?.quiet) {
-                        console.info(`Hocuspocus connected: ${name}`);
-                    }
-                    if (options?.onConnect) {
-                        options.onConnect();
-                    }
-                },
-                onDisconnect: () => {
-                    if (this.isDestroyed || (!this.isConnected && !this.isSynced)) {
-                        return;
-                    }
-                    this.isConnected = false;
-                    this.isSynced = false;
-                    if (!options?.quiet) {
-                        console.info(`Hocuspocus disconnected: ${name}`);
-                    }
-                    if (options?.onDisconnect) {
-                        options.onDisconnect();
-                    }
-                },
-                onSynced: () => {
-                    if (this.isSynced || this.isDestroyed) {
-                        return;
-                    }
-                    this.isSynced = true;
-                    if (!options?.quiet) {
-                        console.info(`Hocuspocus synced: ${name}`);
-                    }
-                    if (options?.onSynced) {
-                        options.onSynced();
-                    }
-                },
+                onStatus,
+                onConnect,
+                onDisconnect,
+                onSynced,
+                ...reconnectConfig,
             };
             // Add optional settings
             if (options?.forceSyncInterval !== undefined) {
@@ -153,6 +151,35 @@ export class HocuspocusSyncProvider {
                 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
@@ -215,6 +242,7 @@ export class HocuspocusSyncProvider {
         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;
@@ -222,7 +250,7 @@ export class HocuspocusSyncProvider {
                 this.pendingConnectReject = null;
                 this.connectTimeout = null;
                 reject(new Error('Hocuspocus connection timeout'));
-            }, 10000); // 10 second timeout
+            }, this.connectionTimeoutMs);
             const syncHandler = () => {
                 if (this.connectTimeout) {
                     clearTimeout(this.connectTimeout);
@@ -252,6 +280,10 @@ export class HocuspocusSyncProvider {
             }
         });
     }
+    async reconnect() {
+        this.disconnect();
+        return this.connect();
+    }
     disconnect() {
         // Cancel any pending connection attempt
         if (this.connectTimeout) {
@@ -272,6 +304,7 @@ export class HocuspocusSyncProvider {
         }
         this.isConnected = false;
         this.isSynced = false;
+        this._connectionStatus = 'disconnected';
     }
     destroy() {
         // Mark as destroyed first to prevent any callbacks from doing work
@@ -284,10 +317,12 @@ export class HocuspocusSyncProvider {
         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/indexeddb-sync-provider.class.js

@@ -3,6 +3,7 @@ import { IndexeddbPersistence } from "y-indexeddb";
  * IndexedDB sync provider for local persistence
  */
 export class IndexedDBSyncProvider {
+    type = 'local';
     provider;
     isConnected = false;
     constructor(docName, doc, options) {
@@ -24,6 +25,10 @@ export class IndexedDBSyncProvider {
         // IndexedDB doesn't need explicit disconnect
         this.isConnected = false;
     }
+    async reconnect() {
+        this.disconnect();
+        return this.connect();
+    }
     destroy() {
         if (this.provider) {
             this.provider.destroy();

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

@@ -3,6 +3,7 @@ import { WebsocketProvider } from "y-websocket";
  * WebSocket sync provider for real-time collaboration
  */
 export class WebSocketSyncProvider {
+    type = 'network';
     provider;
     isConnected = false;
     _quiet = false;
@@ -91,6 +92,10 @@ export class WebSocketSyncProvider {
         }
         this.isConnected = false;
     }
+    async reconnect() {
+        this.disconnect();
+        return this.connect();
+    }
     destroy() {
         if (this.provider) {
             this.provider.destroy();

package/dist/collection/classes/structures/app-state-map.structure.js

@@ -79,13 +79,24 @@ export class KritzelAppStateMap {
             this.handleWorkspacesChange(event);
         };
         this._workspacesMap.observe(this._workspacesObserver);
-        // Connect all providers in parallel (settle individually so one failure doesn't block the rest)
-        const results = await Promise.allSettled(this._providers.map(p => p.connect()));
-        results.forEach((result, i) => {
+        // Separate local providers (IndexedDB, BroadcastChannel) from network providers (Hocuspocus, WebSocket)
+        // Local providers are awaited so data is available immediately; network providers sync in the background
+        // via Yjs observers that are already registered above.
+        const localProviders = this._providers.filter(p => p.type === 'local');
+        const networkProviders = this._providers.filter(p => p.type === 'network');
+        // Await local providers for immediate data availability
+        const localResults = await Promise.allSettled(localProviders.map(p => p.connect()));
+        localResults.forEach((result, i) => {
             if (result.status === 'rejected') {
-                console.error(`[Kritzel] Sync provider "${this._providers[i]?.constructor.name}" failed to connect:`, result.reason);
+                console.error(`[Kritzel] Sync provider "${localProviders[i]?.constructor.name}" failed to connect:`, result.reason);
             }
         });
+        // Connect network providers in the background (remote data arrives via Yjs observers)
+        for (const provider of networkProviders) {
+            provider.connect().catch(err => {
+                console.error(`[Kritzel] Network sync provider "${provider.constructor.name}" failed to connect:`, err);
+            });
+        }
         this._isReady = true;
         // Run any pending schema migrations before loading data
         const quietMigrations = !core.store.state.debugInfo.showMigrationInfo;

package/dist/collection/classes/structures/object-map.structure.js

@@ -34,6 +34,7 @@ export class KritzelObjectMap {
     _stackItemPoppedHandler = null;
     _awarenessChangeHandler = null;
     _awarenessChangeCallbacks = [];
+    _objectsChangeCallbacks = [];
     _lastAwarenessEmitTime = 0;
     _awarenessEmitTimeout = null;
     AWARENESS_THROTTLE_INTERVAL = 100; // milliseconds
@@ -50,6 +51,19 @@ export class KritzelObjectMap {
     get awareness() {
         return this._awareness;
     }
+    /**
+     * Whether a network awareness instance is available.
+     */
+    get hasAwareness() {
+        return !!this._awareness;
+    }
+    /**
+     * Returns the local client ID from the awareness instance.
+     * Used to filter out the local user when rendering remote cursors.
+     */
+    get localClientId() {
+        return this._awareness?.clientID ?? null;
+    }
     /**
      * Sets the local user identity in the awareness state.
      * This broadcasts the user's identity to all connected peers.
@@ -58,12 +72,21 @@ export class KritzelObjectMap {
         if (!this._awareness || !user) {
             return;
         }
+        const displayName = user.displayName || user.firstName || 'Anonymous';
         this._awareness.setLocalStateField('user', {
             id: user.id,
-            name: user.displayName || user.firstName || 'Anonymous',
-            color: user.color,
+            displayName,
+            color: user.color || this.generateColorFromName(displayName),
         });
     }
+    generateColorFromName(name) {
+        let hash = 0;
+        for (let i = 0; i < name.length; i++) {
+            hash = name.charCodeAt(i) + ((hash << 5) - hash);
+        }
+        const hue = Math.abs(hash % 360);
+        return `hsl(${hue}, 45%, 55%)`;
+    }
     /**
      * Updates the local cursor position in the awareness state.
      * This broadcasts the cursor position to all connected peers.
@@ -83,6 +106,37 @@ export class KritzelObjectMap {
         }
         this._awareness.setLocalStateField('cursor', null);
     }
+    /**
+     * Sets the ID of the object currently being drawn by the local user.
+     * Remote clients use this to derive cursor position from the object's latest
+     * coordinates instead of the throttled awareness cursor, reducing desync.
+     * Pass `null` when drawing ends.
+     */
+    setActiveDrawingObject(objectId) {
+        if (!this._awareness) {
+            return;
+        }
+        this._awareness.setLocalStateField('activeObjectId', objectId);
+    }
+    /**
+     * Broadcasts the local user's selection box bounds via awareness.
+     * Remote clients use this to render the selection rectangle in the user's color.
+     */
+    setLocalSelectionBox(box) {
+        if (!this._awareness) {
+            return;
+        }
+        this._awareness.setLocalStateField('selectionBox', box);
+    }
+    /**
+     * Clears the local selection box from awareness (e.g., when selection completes or is cancelled).
+     */
+    clearLocalSelectionBox() {
+        if (!this._awareness) {
+            return;
+        }
+        this._awareness.setLocalStateField('selectionBox', null);
+    }
     /**
      * Registers a callback to be invoked when the awareness state changes.
      * The callback receives the full awareness states map.
@@ -90,6 +144,14 @@ export class KritzelObjectMap {
     onAwarenessChange(callback) {
         this._awarenessChangeCallbacks.push(callback);
     }
+    /**
+     * Registers a callback to be invoked when remote object changes are received.
+     * Used by the awareness cursors component to re-derive cursor positions
+     * from the latest object data when a remote user is actively drawing.
+     */
+    onObjectsChange(callback) {
+        this._objectsChangeCallbacks.push(callback);
+    }
     /**
      * Returns the Yjs UndoManager instance for managing undo/redo operations.
      * @returns The UndoManager instance, or `null` if not initialized
@@ -208,16 +270,28 @@ export class KritzelObjectMap {
             this.handleObjectsChange(event);
         };
         this._objectsMap.observe(this._objectsObserver);
-        // Connect all providers in parallel (settle individually so one failure doesn't block the rest)
-        const results = await Promise.allSettled(this._providers.map(p => p.connect()));
-        results.forEach((result, i) => {
+        // Separate local providers (IndexedDB, BroadcastChannel) from network providers (Hocuspocus, WebSocket)
+        // Local providers are awaited so data is available immediately; network providers sync in the background
+        // via Yjs observers that are already registered above.
+        const localProviders = this._providers.filter(p => p.type === 'local');
+        const networkProviders = this._providers.filter(p => p.type === 'network');
+        // Await local providers for immediate data availability
+        const localResults = await Promise.allSettled(localProviders.map(p => p.connect()));
+        localResults.forEach((result, i) => {
             if (result.status === 'rejected') {
-                console.error(`[Kritzel] Sync provider "${this._providers[i]?.constructor.name}" failed to connect:`, result.reason);
+                console.error(`[Kritzel] Sync provider "${localProviders[i]?.constructor.name}" failed to connect:`, result.reason);
             }
         });
+        // Connect network providers in the background (remote data arrives via Yjs observers)
+        for (const provider of networkProviders) {
+            provider.connect().catch(err => {
+                console.error(`[Kritzel] Network sync provider "${provider.constructor.name}" failed to connect:`, err);
+            });
+        }
         this._isReady = true;
         // Find the first provider that exposes awareness (network providers)
-        for (const provider of this._providers) {
+        // Awareness is available immediately after provider construction, before connect() resolves
+        for (const provider of networkProviders) {
             if (provider.awareness) {
                 this._awareness = provider.awareness;
                 break;
@@ -388,6 +462,10 @@ export class KritzelObjectMap {
         if (updatedObjects.length > 0) {
             this._core?.engine.emitObjectsUpdated(updatedObjects.map(obj => ({ object: obj, changedProperties: [] })));
         }
+        // Notify subscribers of remote object changes (e.g., awareness cursors)
+        for (const callback of this._objectsChangeCallbacks) {
+            callback();
+        }
     }
     /**
      * Initializes document metadata if not already set.

package/dist/collection/classes/tools/brush-tool.class.js

@@ -55,6 +55,7 @@ export class KritzelBrushTool extends KritzelBaseTool {
                 path.isCompleted = false;
                 this._currentPathId = path.id;
                 this._core.store.state.objects.insert(path);
+                this._core.store.state.objects?.setActiveDrawingObject(path.id);
             }
         }
         if (event.pointerType === 'touch' || event.pointerType === 'pen') {
@@ -78,6 +79,7 @@ export class KritzelBrushTool extends KritzelBaseTool {
                 path.isCompleted = false;
                 this._currentPathId = path.id;
                 this._core.store.state.objects.insert(path);
+                this._core.store.state.objects?.setActiveDrawingObject(path.id);
             }
         }
     }
@@ -168,6 +170,7 @@ export class KritzelBrushTool extends KritzelBaseTool {
                         this._core.engine.emitObjectsChange();
                         this._core.engine.emitObjectsAdded([currentPath]);
                     }
+                    this._core.store.state.objects?.setActiveDrawingObject(null);
                     this._currentPathId = null;
                 }
             }
@@ -183,6 +186,7 @@ export class KritzelBrushTool extends KritzelBaseTool {
                         this._core.engine.emitObjectsChange();
                         this._core.engine.emitObjectsAdded([currentPath]);
                     }
+                    this._core.store.state.objects?.setActiveDrawingObject(null);
                     this._currentPathId = null;
                 }
             }

package/dist/collection/classes/tools/line-tool.class.js

@@ -70,6 +70,7 @@ export class KritzelLineTool extends KritzelBaseTool {
                 line.isCompleted = false;
                 this._currentLineId = line.id;
                 this._core.store.state.objects.insert(line);
+                this._core.store.state.objects?.setActiveDrawingObject(line.id);
             }
         }
         if (event.pointerType === 'touch' || event.pointerType === 'pen') {
@@ -99,6 +100,7 @@ export class KritzelLineTool extends KritzelBaseTool {
                 line.isCompleted = false;
                 this._currentLineId = line.id;
                 this._core.store.state.objects.insert(line);
+                this._core.store.state.objects?.setActiveDrawingObject(line.id);
             }
         }
     }
@@ -197,6 +199,7 @@ export class KritzelLineTool extends KritzelBaseTool {
                         // Switch to selection tool and select the drawn line
                         this.selectLineAndSwitchTool(currentLine);
                     }
+                    this._core.store.state.objects?.setActiveDrawingObject(null);
                     this._currentLineId = null;
                 }
             }
@@ -214,6 +217,7 @@ export class KritzelLineTool extends KritzelBaseTool {
                         // Switch to selection tool and select the drawn line
                         this.selectLineAndSwitchTool(currentLine);
                     }
+                    this._core.store.state.objects?.setActiveDrawingObject(null);
                     this._currentLineId = null;
                 }
             }

package/dist/collection/classes/tools/shape-tool.class.js

@@ -179,6 +179,7 @@ export class KritzelShapeTool extends KritzelBaseTool {
             scale: lockScale ? 1 : viewportScale,
         });
         this._core.store.state.objects.insert(this.currentShape);
+        this._core.store.state.objects?.setActiveDrawingObject(this.currentShape.id);
         this._core.rerender();
     }
     /**
@@ -239,6 +240,7 @@ export class KritzelShapeTool extends KritzelBaseTool {
             this._core.store.setState('activeTool', KritzelToolRegistry.getTool('selection'));
         }
         this.isDrawing = false;
+        this._core.store.state.objects?.setActiveDrawingObject(null);
         this.currentShape = null;
         this._core.rerender();
     }

package/dist/collection/collection-manifest.json

@@ -1,13 +1,14 @@
 {
   "entries": [
-    "components/shared/kritzel-dropdown/kritzel-dropdown.js",
-    "components/shared/kritzel-brush-style/kritzel-brush-style.js",
     "components/core/kritzel-engine/kritzel-engine.js",
     "components/ui/kritzel-context-menu/kritzel-context-menu.js",
+    "components/shared/kritzel-dropdown/kritzel-dropdown.js",
+    "components/shared/kritzel-brush-style/kritzel-brush-style.js",
     "components/shared/kritzel-font-family/kritzel-font-family.js",
     "components/shared/kritzel-line-endings/kritzel-line-endings.js",
     "components/shared/kritzel-pill-tabs/kritzel-pill-tabs.js",
     "components/shared/kritzel-shape-fill/kritzel-shape-fill.js",
+    "components/core/kritzel-awareness-cursors/kritzel-awareness-cursors.js",
     "components/core/kritzel-cursor-trail/kritzel-cursor-trail.js",
     "components/core/kritzel-editor/kritzel-editor.js",
     "components/shared/kritzel-avatar/kritzel-avatar.js",