@kritzel/engine 0.4.31 → 0.4.33

package/dist/collection/components/kritzel-engine/kritzel-engine.js

@@ -33,12 +33,26 @@ export class KritzelEngine {
     /** Authoritative workspace catalog for this engine instance. When provided, provider-only workspaces are hidden but not deleted. */
     workspaces;
     async onWorkspacesPropChange() {
-        if (!this._isYjsInitialized) {
+        this._workspacesRevision++;
+        if (!this._isYjsInitialized || this._syncInitPromise) {
             return;
         }
-        await this.reconcileProvidedWorkspaces();
-        await this.ensureActiveWorkspaceIsVisible();
-        this.workspacesChange.emit(this.getVisibleWorkspaces());
+        const previousReconciliation = this._workspacePropReconciliationPromise;
+        const reconciliationPromise = (async () => {
+            await previousReconciliation;
+            await this.reconcileProvidedWorkspaces();
+            await this.ensureActiveWorkspaceIsVisible();
+            this.workspacesChange.emit(this.getVisibleWorkspaces());
+        })();
+        this._workspacePropReconciliationPromise = reconciliationPromise;
+        try {
+            await reconciliationPromise;
+        }
+        finally {
+            if (this._workspacePropReconciliationPromise === reconciliationPromise) {
+                this._workspacePropReconciliationPromise = null;
+            }
+        }
     }
     /** Optional unique identifier for namespacing storage keys across multiple editor instances. */
     editorId;
@@ -92,6 +106,12 @@ export class KritzelEngine {
     onUserChange(newValue) {
         this.core.setUser(newValue);
     }
+    /** Tool definitions to register with this engine instance. */
+    tools = [];
+    onToolsChange() {
+        this._toolsRevision++;
+        void this.registerConfiguredTools();
+    }
     /** Context menu items shown when right-clicking the canvas background. */
     globalContextMenuItems;
     onGlobalContextMenuItemsChange(newValue) {
@@ -282,7 +302,7 @@ export class KritzelEngine {
         }
         const hoveredObject = this.core.getObjectFromPointerEvent(ev);
         if (hoveredObject &&
-            ObjectHelper.isClass(hoveredObject, 'KritzelDynamicObject') &&
+            ObjectHelper.isKritzelEmbeddedObject(hoveredObject) &&
             KritzelWheelHelper.shouldKeepWheelInDynamicObject(ev, hoveredObject)) {
             return;
         }
@@ -384,7 +404,7 @@ export class KritzelEngine {
             return false;
         }
         const object = this.core.store.objects.findById(objectElement.id);
-        if (!object || !KritzelClassHelper.isInstanceOf(object, 'KritzelDynamicObject')) {
+        if (!object || !ObjectHelper.isKritzelEmbeddedObject(object)) {
             return false;
         }
         const isSelected = !!this.core.store.selectionGroup?.objects?.some(selectedObject => selectedObject.id === object.id);
@@ -394,13 +414,7 @@ export class KritzelEngine {
         if (object.isInteractive !== true) {
             return false;
         }
-        const potentialRoots = [];
-        if (object.element instanceof HTMLElement) {
-            potentialRoots.push(object.element);
-        }
-        if (object.elementRef instanceof HTMLElement) {
-            potentialRoots.push(object.elementRef);
-        }
+        const potentialRoots = object.getEmbeddedContentRoots();
         if (potentialRoots.length === 0) {
             return false;
         }
@@ -574,7 +588,7 @@ export class KritzelEngine {
      * Switches the active drawing tool by its registered name.
      * @param toolName - The name the tool was registered with (e.g., 'brush', 'eraser').
      */
-    async changeActiveTool(toolName) {
+    async setActiveTool(toolName) {
         const tool = this.core.toolRegistry.getTool(toolName);
         if (!tool) {
             console.warn(`[KritzelEngine] No tool registered with name: ${toolName}`);
@@ -1880,9 +1894,13 @@ export class KritzelEngine {
     _stateChangeListenersRegistered = false;
     _workspaceInitializationPromise = null;
     _workspaceInitializationTargetKey = null;
+    _workspacePropReconciliationPromise = null;
     _syncInitPromise = null;
+    _toolsInitPromise = null;
+    _toolsRevision = 0;
     _syncConfigRevision = 0;
     _assetStorageConfigRevision = 0;
+    _workspacesRevision = 0;
     _hasLoggedUnlicensedWelcomeBanner = false;
     _previousVisibleDynamicObjects = new Set();
     _revealedImageKeys = new Set();
@@ -1895,6 +1913,37 @@ export class KritzelEngine {
         undoStackSize: 0,
         redoStackSize: 0,
     };
+    /** Returns a tool registered in this engine instance. */
+    async getTool(toolName) {
+        await this.registerConfiguredTools();
+        return this.core.toolRegistry.getTool(toolName);
+    }
+    async registerConfiguredTools() {
+        if (this._toolsInitPromise) {
+            return this._toolsInitPromise;
+        }
+        this._toolsInitPromise = (async () => {
+            do {
+                const revision = this._toolsRevision;
+                for (const definition of this.tools) {
+                    let toolClass = definition.tool;
+                    if (typeof toolClass !== 'function') {
+                        toolClass = toolClass.constructor;
+                    }
+                    await this.registerTool(definition.name, toolClass, definition.config);
+                }
+                if (revision === this._toolsRevision) {
+                    break;
+                }
+            } while (true);
+        })();
+        try {
+            await this._toolsInitPromise;
+        }
+        finally {
+            this._toolsInitPromise = null;
+        }
+    }
     setLoadingState(isLoading) {
         if (this.core.store.state.isLoading === isLoading) {
             return;
@@ -2004,6 +2053,8 @@ export class KritzelEngine {
         this.core.licenseManager.destroy();
     }
     componentWillLoad() {
+        this._toolsRevision++;
+        void this.registerConfiguredTools();
         this.core.setEditorId(this.editorId);
         if (this.themes && this.themes.length > 0) {
             this.core.themeManager.registerThemes(this.themes);
@@ -2043,7 +2094,9 @@ export class KritzelEngine {
             const editorElement = this.host.closest('kritzel-editor');
             this.core.themeManager.setTargetElement(editorElement || this.host);
             // Initialize sync config and Yjs
+            await this.registerConfiguredTools();
             await this.initializeSyncAndWorkspace();
+            await this.waitForWorkspaceAndSceneReady();
             if (this.core.store.state.isReady === false) {
                 this.core.store.state.isReady = true;
                 this.logUnlicensedWelcomeBanner();
@@ -2065,6 +2118,20 @@ export class KritzelEngine {
             this._syncInitPromise = null;
         }
     }
+    async waitForSceneRender() {
+        await new Promise(resolve => {
+            requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+        });
+    }
+    async waitForWorkspaceAndSceneReady() {
+        let observedRevision;
+        do {
+            observedRevision = this._workspacesRevision;
+            await this._workspacePropReconciliationPromise;
+            await this.waitForSceneRender();
+        } while (observedRevision !== this._workspacesRevision ||
+            this._workspacePropReconciliationPromise);
+    }
     /**
      * Initializes the asset storage layer with the latest config. Mirrors
      * the in-flight replay logic of {@link doInitializeSyncAndWorkspace} for
@@ -2447,7 +2514,7 @@ export class KritzelEngine {
             if (!KritzelClassHelper.isInstanceOf(object, 'KritzelSelectionGroup')) {
                 return 'auto';
             }
-            if (object.objects.length === 1 && KritzelClassHelper.isInstanceOf(object.objects[0], 'KritzelDynamicObject')) {
+            if (object.objects.length === 1 && ObjectHelper.isKritzelEmbeddedObject(object.objects[0])) {
                 return 'none';
             }
             return 'auto';
@@ -2455,7 +2522,7 @@ export class KritzelEngine {
         // Track visible dynamic objects and unmount culled ones
         const currentVisibleDynamicObjects = new Set();
         visibleObjects.forEach(object => {
-            if (KritzelClassHelper.isInstanceOf(object, 'KritzelDynamicObject')) {
+            if (ObjectHelper.isKritzelEmbeddedObject(object)) {
                 currentVisibleDynamicObjects.add(object.id);
             }
         });
@@ -2463,7 +2530,7 @@ export class KritzelEngine {
         this._previousVisibleDynamicObjects.forEach(id => {
             if (!currentVisibleDynamicObjects.has(id)) {
                 const object = this.core.store.objects.findById(id);
-                if (object && KritzelClassHelper.isInstanceOf(object, 'KritzelDynamicObject')) {
+                if (object && ObjectHelper.isKritzelEmbeddedObject(object)) {
                     object.unmount();
                 }
             }
@@ -2556,7 +2623,7 @@ export class KritzelEngine {
                     display: 'flex',
                     alignItems: 'center',
                     justifyContent: 'center',
-                } }, h("kritzel-icon", { name: object.loadState === 'error' ? 'image-off' : 'image', size: Math.max(16, Math.min(object.totalWidth, object.totalHeight) * 0.3), style: {
+                } }, h("kritzel-icon", { name: object.loadState === 'error' ? 'imageOff' : 'image', size: Math.max(16, Math.min(object.totalWidth, object.totalHeight) * 0.3), style: {
                     color: KritzelColorHelper.resolveThemeColor({ light: '#9ca3af', dark: '#6b7280' }, currentTheme),
                 } }))), KritzelClassHelper.isInstanceOf(object, 'KritzelDynamicObject') && (h("div", { ref: el => el && object.mount(el), style: {
                     position: 'absolute',
@@ -2575,7 +2642,37 @@ export class KritzelEngine {
                     padding: object.padding + 'px',
                     overflow: 'visible',
                     display: 'block',
-                } })), KritzelClassHelper.isInstanceOf(object, 'KritzelSelectionGroup') && !this.core.displaySelectionLineUI(object) && (h("div", { ref: el => el && object.mount(el), style: {
+                } })), KritzelClassHelper.isInstanceOf(object, 'KritzelIframeObject') && (h("div", { style: {
+                    position: 'absolute',
+                    left: '0',
+                    top: '0',
+                    width: object.totalWidth + 'px',
+                    height: object.totalHeight + 'px',
+                    transform: object.rotationDegrees !== 0 ? `rotate(${object.rotationDegrees}deg)` : undefined,
+                    transformOrigin: object.rotationDegrees !== 0 ? `${object.totalWidth / 2}px ${object.totalHeight / 2}px` : undefined,
+                    opacity: effectiveOpacityString,
+                    backgroundColor: KritzelColorHelper.resolveThemeColor(object.backgroundColor, currentTheme),
+                    borderColor: KritzelColorHelper.resolveThemeColor(object.borderColor, currentTheme),
+                    borderWidth: object.borderWidth + 'px',
+                    borderStyle: 'solid',
+                    borderRadius: object.borderRadius !== undefined ? (typeof object.borderRadius === 'number' ? `${object.borderRadius}px` : object.borderRadius) : undefined,
+                    boxShadow: object.boxShadow,
+                    overflow: 'hidden',
+                    display: 'block',
+                    pointerEvents: object.markedForRemoval ? 'none' : 'auto',
+                } }, h("iframe", { ref: element => element && object.mount(element), title: object.title, sandbox: object.sandboxAttribute, style: {
+                    display: 'block',
+                    width: '100%',
+                    height: '100%',
+                    border: '0',
+                    borderRadius: object.borderRadius !== undefined ? (typeof object.borderRadius === 'number' ? `${object.borderRadius}px` : object.borderRadius) : undefined,
+                    pointerEvents: object.isInteractive ? 'auto' : 'none',
+                } }), h("div", { style: {
+                    position: 'absolute',
+                    inset: '0',
+                    borderRadius: object.borderRadius !== undefined ? (typeof object.borderRadius === 'number' ? `${object.borderRadius}px` : object.borderRadius) : undefined,
+                    pointerEvents: object.isInteractive ? 'none' : 'auto',
+                } }))), KritzelClassHelper.isInstanceOf(object, 'KritzelSelectionGroup') && !this.core.displaySelectionLineUI(object) && (h("div", { ref: el => el && object.mount(el), style: {
                     position: 'absolute',
                     left: '0',
                     top: '0',
@@ -3036,7 +3133,7 @@ export class KritzelEngine {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "Configuration for binary asset storage (e.g., images).\r\n\r\nThe Yjs document only persists asset ids; the actual bytes are stored\r\nby the providers listed here. Defaults to IndexedDB-only storage. To\r\nsupport cross-device image sync alongside a networked sync provider\r\n(Hocuspocus, WebSocket), configure at least one remote asset provider\r\nsuch as `HttpAssetProvider` or `PresignedAssetProvider`."
+                    "text": "Configuration for binary asset storage (e.g., images).\n\nThe Yjs document only persists asset ids; the actual bytes are stored\nby the providers listed here. Defaults to IndexedDB-only storage. To\nsupport cross-device image sync alongside a networked sync provider\n(Hocuspocus, WebSocket), configure at least one remote asset provider\nsuch as `HttpAssetProvider` or `PresignedAssetProvider`."
                 },
                 "getter": false,
                 "setter": false
@@ -3065,6 +3162,31 @@ export class KritzelEngine {
                 "getter": false,
                 "setter": false
             },
+            "tools": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "KritzelToolDefinition[]",
+                    "resolved": "KritzelToolDefinition[]",
+                    "references": {
+                        "KritzelToolDefinition": {
+                            "location": "import",
+                            "path": "../../interfaces/tool.interface",
+                            "id": "src/interfaces/tool.interface.ts::KritzelToolDefinition",
+                            "referenceLocation": "KritzelToolDefinition"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Tool definitions to register with this engine instance."
+                },
+                "getter": false,
+                "setter": false,
+                "defaultValue": "[]"
+            },
             "globalContextMenuItems": {
                 "type": "unknown",
                 "mutable": false,
@@ -3994,7 +4116,7 @@ export class KritzelEngine {
                         }]
                 }
             },
-            "changeActiveTool": {
+            "setActiveTool": {
                 "complexType": {
                     "signature": "(toolName: string) => Promise<void>",
                     "parameters": [{
@@ -4392,7 +4514,7 @@ export class KritzelEngine {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Programmatically opens the context menu at a specified world-coordinate position.\r\nIf `objectId` is provided and found, the object context menu is shown for that object.\r\nIf no `objectId` is provided but a selection group already exists, the object context menu is shown.\r\nOtherwise, the global context menu is shown.",
+                    "text": "Programmatically opens the context menu at a specified world-coordinate position.\nIf `objectId` is provided and found, the object context menu is shown for that object.\nIf no `objectId` is provided but a selection group already exists, the object context menu is shown.\nOtherwise, the global context menu is shown.",
                     "tags": [{
                             "name": "param",
                             "text": "options.x - The X position in world (canvas) coordinates."
@@ -4502,7 +4624,7 @@ export class KritzelEngine {
                     "return": "Promise<T[]>"
                 },
                 "docs": {
-                    "text": "Returns all objects that match the given predicate function.\r\nExcludes internal selection-related objects (selection groups and selection boxes).",
+                    "text": "Returns all objects that match the given predicate function.\nExcludes internal selection-related objects (selection groups and selection boxes).",
                     "tags": [{
                             "name": "param",
                             "text": "predicate - A filter function called for each object. Return `true` to include."
@@ -4511,7 +4633,7 @@ export class KritzelEngine {
                             "text": "An array of matching objects."
                         }, {
                             "name": "example",
-                            "text": "```ts\r\n// Find all text objects\r\nconst texts = await engine.findObjects(obj => obj.__class__ === 'KritzelText');\r\n\r\n// Find objects at a point\r\nconst hits = await engine.findObjects(obj => obj.hitTest(100, 200));\r\n\r\n// Combine criteria\r\nconst filtered = await engine.findObjects(obj => obj.__class__ === 'KritzelPath' && obj.opacity < 0.5);\r\n```"
+                            "text": "```ts\n// Find all text objects\nconst texts = await engine.findObjects(obj => obj.__class__ === 'KritzelText');\n\n// Find objects at a point\nconst hits = await engine.findObjects(obj => obj.hitTest(100, 200));\n\n// Combine criteria\nconst filtered = await engine.findObjects(obj => obj.__class__ === 'KritzelPath' && obj.opacity < 0.5);\n```"
                         }]
                 }
             },
@@ -4644,7 +4766,7 @@ export class KritzelEngine {
                     "return": "Promise<T[]>"
                 },
                 "docs": {
-                    "text": "Adds multiple objects to the canvas in a single batch operation.\r\nAll objects are inserted within one Yjs transaction (single undo step),\r\ntriggering only one rerender cycle. Intended for programmatic streaming\r\nscenarios where per-object overhead would cause stutter.",
+                    "text": "Adds multiple objects to the canvas in a single batch operation.\nAll objects are inserted within one Yjs transaction (single undo step),\ntriggering only one rerender cycle. Intended for programmatic streaming\nscenarios where per-object overhead would cause stutter.",
                     "tags": [{
                             "name": "param",
                             "text": "objects - The object instances to add."
@@ -4766,7 +4888,7 @@ export class KritzelEngine {
                     "return": "Promise<T[]>"
                 },
                 "docs": {
-                    "text": "Removes multiple objects from the canvas in a single batch operation.\r\nAll removals happen within one Yjs transaction (single undo step),\r\ntriggering only one rerender cycle. Intended for programmatic streaming\r\nscenarios where per-object overhead would cause stutter.",
+                    "text": "Removes multiple objects from the canvas in a single batch operation.\nAll removals happen within one Yjs transaction (single undo step),\ntriggering only one rerender cycle. Intended for programmatic streaming\nscenarios where per-object overhead would cause stutter.",
                     "tags": [{
                             "name": "param",
                             "text": "objects - The objects to remove."
@@ -4954,7 +5076,7 @@ export class KritzelEngine {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Pans the viewport to center on the given object without changing the zoom level.\r\nUnlike `centerObjectInViewport`, this moves the camera \u2014 not the object.",
+                    "text": "Pans the viewport to center on the given object without changing the zoom level.\nUnlike `centerObjectInViewport`, this moves the camera \u2014 not the object.",
                     "tags": [{
                             "name": "param",
                             "text": "object - The object whose center the viewport should pan to."
@@ -4974,7 +5096,7 @@ export class KritzelEngine {
                     "return": "Promise<boolean>"
                 },
                 "docs": {
-                    "text": "Pans and zooms the viewport to fit the nearest content, with padding.\r\nUseful when the user has panned away from all objects.",
+                    "text": "Pans and zooms the viewport to fit the nearest content, with padding.\nUseful when the user has panned away from all objects.",
                     "tags": [{
                             "name": "returns",
                             "text": "`true` if content was found and the viewport was adjusted, `false` otherwise."
@@ -4998,7 +5120,7 @@ export class KritzelEngine {
                     "return": "Promise<boolean>"
                 },
                 "docs": {
-                    "text": "Pans and zooms the viewport to fit ALL objects on the canvas, including those not currently rendered.\r\nCalculates the combined bounding box of all objects and centers the viewport to show them.",
+                    "text": "Pans and zooms the viewport to fit ALL objects on the canvas, including those not currently rendered.\nCalculates the combined bounding box of all objects and centers the viewport to show them.",
                     "tags": [{
                             "name": "param",
                             "text": "animate - Whether to animate the viewport transition (default: true)."
@@ -5035,7 +5157,7 @@ export class KritzelEngine {
                     "return": "Promise<boolean>"
                 },
                 "docs": {
-                    "text": "Pans and zooms the viewport to fit the provided objects.\r\nCalculates the combined bounding box of the given objects and centers the viewport to show them.",
+                    "text": "Pans and zooms the viewport to fit the provided objects.\nCalculates the combined bounding box of the given objects and centers the viewport to show them.",
                     "tags": [{
                             "name": "param",
                             "text": "objects - The objects to center and fit in the viewport."
@@ -5142,7 +5264,7 @@ export class KritzelEngine {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Zooms the viewport to the given scale level.\r\nOptionally centers on a world point; if omitted, zooms around the viewport center.",
+                    "text": "Zooms the viewport to the given scale level.\nOptionally centers on a world point; if omitted, zooms around the viewport center.",
                     "tags": [{
                             "name": "param",
                             "text": "scale - Target scale level."
@@ -5430,7 +5552,7 @@ export class KritzelEngine {
                     "return": "Promise<KritzelObjectExportFormat[]>"
                 },
                 "docs": {
-                    "text": "Returns export formats supported by the currently selected object.\r\nOnly returns formats when exactly one object is selected.",
+                    "text": "Returns export formats supported by the currently selected object.\nOnly returns formats when exactly one object is selected.",
                     "tags": []
                 }
             },
@@ -5457,7 +5579,7 @@ export class KritzelEngine {
                     "return": "Promise<boolean>"
                 },
                 "docs": {
-                    "text": "Checks whether the currently selected object supports a specific export format.\r\nReturns false when none or multiple objects are selected.",
+                    "text": "Checks whether the currently selected object supports a specific export format.\nReturns false when none or multiple objects are selected.",
                     "tags": []
                 }
             },
@@ -5484,7 +5606,7 @@ export class KritzelEngine {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Exports the currently selected object in the requested format and triggers a file download.\r\nOnly supports single selection.",
+                    "text": "Exports the currently selected object in the requested format and triggers a file download.\nOnly supports single selection.",
                     "tags": []
                 }
             },
@@ -5505,7 +5627,7 @@ export class KritzelEngine {
                     "return": "Promise<string>"
                 },
                 "docs": {
-                    "text": "Exports the current workspace and all its objects as a JSON string.\r\nThe exported data includes workspace metadata (id, name, viewport) and all canvas objects.",
+                    "text": "Exports the current workspace and all its objects as a JSON string.\nThe exported data includes workspace metadata (id, name, viewport) and all canvas objects.",
                     "tags": [{
                             "name": "returns",
                             "text": "A JSON string representing the complete workspace state."
@@ -5539,7 +5661,7 @@ export class KritzelEngine {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Imports a workspace from a JSON string into a new workspace.\r\nCreates a new workspace with the imported data and automatically switches to it.",
+                    "text": "Imports a workspace from a JSON string into a new workspace.\nCreates a new workspace with the imported data and automatically switches to it.",
                     "tags": [{
                             "name": "param",
                             "text": "json - A JSON string containing workspace data (from exportAsJson)."
@@ -5576,7 +5698,7 @@ export class KritzelEngine {
                     "return": "Promise<number>"
                 },
                 "docs": {
-                    "text": "Loads objects from a workspace JSON string into the current workspace.\r\nUnlike importFromJson, this does not create a new workspace - it adds objects to the existing one.\r\nUseful for initializing a workspace with pre-existing content after the editor is ready.",
+                    "text": "Loads objects from a workspace JSON string into the current workspace.\nUnlike importFromJson, this does not create a new workspace - it adds objects to the existing one.\nUseful for initializing a workspace with pre-existing content after the editor is ready.",
                     "tags": [{
                             "name": "param",
                             "text": "json - A JSON string containing workspace data (from exportAsJson)."
@@ -5636,7 +5758,7 @@ export class KritzelEngine {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Opens a file picker dialog and imports the selected JSON file into the workspace.\r\nThis method creates a hidden file input, triggers the browser's file chooser,\r\nreads the selected JSON file, and imports it using importFromJson.",
+                    "text": "Opens a file picker dialog and imports the selected JSON file into the workspace.\nThis method creates a hidden file input, triggers the browser's file chooser,\nreads the selected JSON file, and imports it using importFromJson.",
                     "tags": [{
                             "name": "returns",
                             "text": "A promise that resolves when the import is complete or rejects on error/cancel."
@@ -5707,7 +5829,7 @@ export class KritzelEngine {
                     "return": "Promise<KritzelWorkspace>"
                 },
                 "docs": {
-                    "text": "Creates a new workspace and emits a `workspacesChange` event.\r\nEmits `activeWorkspaceChange` if the created workspace is activated.",
+                    "text": "Creates a new workspace and emits a `workspacesChange` event.\nEmits `activeWorkspaceChange` if the created workspace is activated.",
                     "tags": [{
                             "name": "param",
                             "text": "workspace - The workspace instance to create."
@@ -5740,7 +5862,7 @@ export class KritzelEngine {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Applies a workspace as declared and emits a `workspacesChange` event.\r\nMetadata and viewport are always applied. When `workspace.objects` is set it is treated as the\r\ncomplete desired object set (`undefined` leaves objects untouched, `[]` removes them all);\r\nupdating objects of a non-active workspace requires a configured sync provider.",
+                    "text": "Applies a workspace as declared and emits a `workspacesChange` event.\nMetadata and viewport are always applied. When `workspace.objects` is set it is treated as the\ncomplete desired object set (`undefined` leaves objects untouched, `[]` removes them all);\nupdating objects of a non-active workspace requires a configured sync provider.",
                     "tags": [{
                             "name": "param",
                             "text": "workspace - The workspace describing the desired state."
@@ -5860,7 +5982,7 @@ export class KritzelEngine {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Loads a shared workspace by token.\r\nIf the workspace exists locally, it switches to it.\r\nIf it doesn't exist, it adds it to the local workspaces list and then switches to it.",
+                    "text": "Loads a shared workspace by token.\nIf the workspace exists locally, it switches to it.\nIf it doesn't exist, it adds it to the local workspaces list and then switches to it.",
                     "tags": [{
                             "name": "param",
                             "text": "token - The connection token identifying the shared workspace"
@@ -5880,7 +6002,7 @@ export class KritzelEngine {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Reinitializes sync by performing a full teardown and re-initialization.\r\nDestroys the current Yjs documents and providers, then rebuilds everything\r\nfrom the current syncConfig. Data reloads from IndexedDB nearly instantly.\r\nCall this after updating the syncConfig prop (e.g. after authentication state changes).",
+                    "text": "Reinitializes sync by performing a full teardown and re-initialization.\nDestroys the current Yjs documents and providers, then rebuilds everything\nfrom the current syncConfig. Data reloads from IndexedDB nearly instantly.\nCall this after updating the syncConfig prop (e.g. after authentication state changes).",
                     "tags": []
                 }
             },
@@ -5997,7 +6119,7 @@ export class KritzelEngine {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "Declaratively configures the full locale catalog, replacing the available\r\nlocale set. Pass `undefined` to restore the built-in locales (en/de/fr).",
+                    "text": "Declaratively configures the full locale catalog, replacing the available\nlocale set. Pass `undefined` to restore the built-in locales (en/de/fr).",
                     "tags": [{
                             "name": "param",
                             "text": "locales - The full locale catalog, or `undefined` for built-ins."
@@ -6173,7 +6295,34 @@ export class KritzelEngine {
                     "return": "Promise<Partial<Record<keyof KritzelTerms, string>>>"
                 },
                 "docs": {
-                    "text": "Resolves every known term key for the active locale into a flat map.\r\nUseful for UI layers that need to localize many strings at once.",
+                    "text": "Resolves every known term key for the active locale into a flat map.\nUseful for UI layers that need to localize many strings at once.",
+                    "tags": []
+                }
+            },
+            "getTool": {
+                "complexType": {
+                    "signature": "(toolName: string) => Promise<KritzelBaseTool | null>",
+                    "parameters": [{
+                            "name": "toolName",
+                            "type": "string",
+                            "docs": ""
+                        }],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        },
+                        "KritzelBaseTool": {
+                            "location": "import",
+                            "path": "../../classes/tools/base-tool.class",
+                            "id": "src/classes/tools/base-tool.class.ts::KritzelBaseTool",
+                            "referenceLocation": "KritzelBaseTool"
+                        }
+                    },
+                    "return": "Promise<KritzelBaseTool>"
+                },
+                "docs": {
+                    "text": "Returns a tool registered in this engine instance.",
                     "tags": []
                 }
             }
@@ -6196,6 +6345,9 @@ export class KritzelEngine {
             }, {
                 "propName": "user",
                 "methodName": "onUserChange"
+            }, {
+                "propName": "tools",
+                "methodName": "onToolsChange"
             }, {
                 "propName": "globalContextMenuItems",
                 "methodName": "onGlobalContextMenuItemsChange"

package/dist/collection/components/kritzel-icon/kritzel-icon.css

@@ -1,18 +1,18 @@
-:host {
-  display: inline-flex; /* Changed from block to inline-flex for better alignment */
-  justify-content: center; /* Center content horizontally */
-  align-items: center; /* Center content vertically */
-  color: var(--kritzel-icon-color, inherited);
-}
-
-span {
-  display: flex;
-  align-items: center;
-  width: 100%; /* Make span fill host width */
-  height: 100%; /* Make span fill host height */
-}
-
-span > svg { /* Ensure SVG scales within the span */
-  width: 100%;
-  height: 100%;
-}
+:host {
+  display: inline-flex; /* Changed from block to inline-flex for better alignment */
+  justify-content: center; /* Center content horizontally */
+  align-items: center; /* Center content vertically */
+  color: var(--kritzel-icon-color, inherited);
+}
+
+span {
+  display: flex;
+  align-items: center;
+  width: 100%; /* Make span fill host width */
+  height: 100%; /* Make span fill host height */
+}
+
+span > svg { /* Ensure SVG scales within the span */
+  width: 100%;
+  height: 100%;
+}

package/dist/collection/components/kritzel-icon/kritzel-icon.js

@@ -1,9 +1,23 @@
-import { h, Host } from "@stencil/core";
+import { h, Host, forceUpdate } from "@stencil/core";
 import { KritzelIconRegistry } from "../../classes/registries/icon-registry.class";
 export class KritzelIcon {
     name;
     label;
     size = 24;
+    unsubscribe;
+    connectedCallback() {
+        this.unsubscribe?.();
+        this.unsubscribe = KritzelIconRegistry.subscribe(name => {
+            if (name === this.name) {
+                forceUpdate(this);
+            }
+        });
+        forceUpdate(this);
+    }
+    disconnectedCallback() {
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+    }
     render() {
         const svgContent = KritzelIconRegistry.get(this.name);
         if (!svgContent) {
@@ -34,9 +48,16 @@ export class KritzelIcon {
                 "type": "string",
                 "mutable": false,
                 "complexType": {
-                    "original": "string",
-                    "resolved": "string",
-                    "references": {}
+                    "original": "KritzelIconName",
+                    "resolved": "\"align\" | \"alignCenterHorizontal\" | \"alignCenterVertical\" | \"alignEndHorizontal\" | \"alignEndVertical\" | \"alignStartHorizontal\" | \"alignStartVertical\" | \"arrow\" | \"arrowDownFromDot\" | \"arrowUpFromDot\" | \"braces\" | \"bringToFront\" | \"check\" | \"chevronDown\" | \"chevronLeft\" | \"chevronRight\" | \"chevronUp\" | \"chevronsLeft\" | \"command\" | \"copy\" | \"cursor\" | \"cut\" | \"delete\" | \"download\" | \"ellipsisVertical\" | \"eraser\" | \"facebook\" | \"github\" | \"google\" | \"group\" | \"hand\" | \"handGrab\" | \"heart\" | \"highlighter\" | \"image\" | \"imageOff\" | \"info\" | \"layoutTemplate\" | \"logOut\" | \"minus\" | \"mousePointer\" | \"moveVertical\" | \"ordering\" | \"palette\" | \"paste\" | \"pen\" | \"plus\" | \"pointer\" | \"redo\" | \"selectAll\" | \"sendToBack\" | \"settings\" | \"shapeEllipse\" | \"shapeRectangle\" | \"shapeTriangle\" | \"shapes\" | \"share\" | \"type\" | \"undo\" | \"ungroup\" | \"upload\" | \"usersRound\" | \"viewport\" | \"x\" | string & {}",
+                    "references": {
+                        "KritzelIconName": {
+                            "location": "import",
+                            "path": "../../classes/registries/icon-registry.class",
+                            "id": "src/classes/registries/icon-registry.class.ts::KritzelIconName",
+                            "referenceLocation": "KritzelIconName"
+                        }
+                    }
                 },
                 "required": false,
                 "optional": false,