kritzel-stencil 0.3.21 → 0.3.23

package/dist/collection/classes/objects/custom-element.class.js

@@ -1,5 +1,7 @@
 import { KritzelBaseObject } from "./base-object.class";
 import { KritzelMathHelper } from "../../helpers/math.helper";
+import { KritzelCustomElementRendererRegistry } from "../registries/custom-element-renderer.registry";
+import { KritzelHTMLHelper } from "../../helpers/html.helper";
 /**
  * Represents a custom HTML element that can be placed and manipulated on the Kritzel canvas.
  * Extends KritzelBaseObject to inherit common object functionality like positioning,
@@ -9,8 +11,17 @@ export class KritzelCustomElement extends KritzelBaseObject {
     __class__ = 'KritzelCustomElement';
     /** The HTML element to be rendered on the canvas. */
     element;
-    /** Whether the element responds to user interactions. Defaults to true. */
-    isInteractive = true;
+    /**
+     * Optional identifier for a registered renderer (e.g., 'angular-component', 'react-default').
+     * When set, mount() resolves the renderer from a global registry and delegates lifecycle.
+     * If null, falls back to DOM element mounting.
+     */
+    rendererKey = null;
+    /**
+     * Custom data payload for the renderer (e.g., Angular component inputs, React props, Vue data).
+     * Only meaningful when rendererKey is set. Captured on unmount and restored on rehydrate.
+     */
+    rendererData;
     /**
      * Creates a new KritzelCustomElement instance.
      * @param config - Optional configuration object for the custom element.
@@ -28,9 +39,11 @@ export class KritzelCustomElement extends KritzelBaseObject {
             this.translateY = config.translateY || 0;
             this.rotation = KritzelMathHelper.degreesToRadians(config.rotation ?? 0);
             this.scale = config.scale || 1;
-            this.element = config.element;
+            this.element = config.element ?? this.createPlaceholder();
             this.height = config.height || 0;
             this.width = config.width || 0;
+            this.rendererKey = config.rendererKey ?? null;
+            this.rendererData = config.rendererData;
         }
     }
     /**
@@ -52,11 +65,13 @@ export class KritzelCustomElement extends KritzelBaseObject {
         object.id = object.generateId();
         object.workspaceId = core.store.state.activeWorkspace.id;
         object.userId = core.user?.id;
+        object.zIndex = core.store.currentZIndex;
         return object;
     }
     /**
      * Mounts the custom element to a container element in the DOM.
-     * Clears any existing content in the container and appends this element.
+     * If a renderer is registered for this.rendererKey, delegates to the renderer.
+     * Otherwise, uses the standard DOM element mounting fallback.
      * Skips mounting if already mounted to the same container with content attached.
      * @param element - The container HTML element to mount this custom element into.
      */
@@ -64,15 +79,268 @@ export class KritzelCustomElement extends KritzelBaseObject {
         if (element === null) {
             return;
         }
-        // If already mounted to the same element and content is still attached, skip
-        if (this.isMounted && this.elementRef === element && this.element.parentElement === element) {
-            return;
+        this.applyInteractiveState();
+        if (this.isMounted && this.elementRef === element) {
+            // Renderer-based mounts should not be re-invoked on every engine rerender.
+            if (this.rendererKey) {
+                return;
+            }
+            // For direct DOM fallback, remount only if content was detached.
+            if (this.element.parentElement === element) {
+                return;
+            }
         }
         this.elementRef = element;
         this.isMounted = true;
-        // Clear existing content and append the element
+        // Try renderer-based approach if a key is set
+        if (this.rendererKey) {
+            const renderer = KritzelCustomElementRendererRegistry.get(this.rendererKey);
+            if (renderer) {
+                element.innerHTML = ''; // Clear container
+                renderer.onMount({
+                    object: this,
+                    container: element,
+                    data: this.rendererData,
+                });
+                this.applyInteractiveState();
+                return;
+            }
+        }
+        // Fallback to standard DOM mounting
         this.elementRef.innerHTML = '';
         this.elementRef.appendChild(this.element);
+        this.applyInteractiveState();
+    }
+    /**
+     * Updates interactivity state for embedded HTML content.
+     * When disabling interactivity, any focused descendant is blurred so
+     * keyboard input is released immediately.
+     */
+    setIsInteractive(isInteractive) {
+        const hasChanged = this.isInteractive !== isInteractive;
+        this.isInteractive = isInteractive;
+        this.applyInteractiveState();
+        if (hasChanged && !isInteractive) {
+            this.blurFocusedDescendant();
+        }
+    }
+    applyInteractiveState() {
+        const pointerEvents = this.isInteractive ? 'auto' : 'none';
+        const contentCursor = this.isInteractive ? 'auto' : '';
+        if (this.element) {
+            this.element.style.pointerEvents = pointerEvents;
+            this.element.style.cursor = contentCursor;
+        }
+        if (this.elementRef instanceof HTMLElement) {
+            // Keep the mount container clickable so unselected custom elements can still be selected.
+            this.elementRef.style.pointerEvents = 'auto';
+            this.elementRef.style.cursor = '';
+            Array.from(this.elementRef.children).forEach(child => {
+                if (child instanceof HTMLElement) {
+                    child.style.pointerEvents = pointerEvents;
+                    child.style.cursor = contentCursor;
+                }
+            });
+        }
+    }
+    blurFocusedDescendant() {
+        if (!this.element && !(this.elementRef instanceof HTMLElement)) {
+            return;
+        }
+        const activeElement = this.getDeepActiveElement();
+        const isInsideElement = !!this.element && this.isNodeInsideHost(activeElement, this.element);
+        const isInsideMountedContainer = this.elementRef instanceof HTMLElement && this.isNodeInsideHost(activeElement, this.elementRef);
+        if (activeElement && (isInsideElement || isInsideMountedContainer)) {
+            activeElement.blur();
+        }
+    }
+    /**
+     * Returns true when a text-input-like element inside this custom element
+     * currently owns focus.
+     */
+    hasFocusedInputElement() {
+        if (!this.isInteractive) {
+            return false;
+        }
+        const focusHosts = this.getFocusHosts();
+        // Primary path: locate the focused input-like element by walking from each host through
+        // `:focus` (piercing open shadow roots). This works in real browsers even when the engine
+        // and editor are nested web components, because it never relies on the document-level
+        // active element resolving to a descendant of the host.
+        if (focusHosts.some(host => this.hasFocusedInputDescendant(host))) {
+            return true;
+        }
+        // Fallback path: resolve the deep active element and confirm it is input-like and inside a
+        // host. Covers contenteditable content inside nested shadow roots (which `querySelector`
+        // cannot reach) and test environments that mock the active element without real focus.
+        const activeElement = this.getDeepActiveElement();
+        if (activeElement && this.isInputLikeElement(activeElement) && focusHosts.some(host => this.isNodeInsideHost(activeElement, host))) {
+            return true;
+        }
+        return false;
+    }
+    getFocusHosts() {
+        const hosts = [];
+        if (this.element) {
+            hosts.push(this.element);
+        }
+        if (this.elementRef instanceof HTMLElement) {
+            hosts.push(this.elementRef);
+            const firstChild = this.elementRef.firstElementChild;
+            if (firstChild instanceof HTMLElement) {
+                hosts.push(firstChild);
+            }
+        }
+        return hosts;
+    }
+    /**
+     * Returns true when the given host (or, via the flat tree, one of its shadow descendants)
+     * currently contains a focused input-like element.
+     */
+    hasFocusedInputDescendant(host) {
+        if (this.isInputLikeElement(host) && this.matchesFocus(host)) {
+            return true;
+        }
+        // `:focus-within` crosses shadow boundaries for the host, so it is a cheap guard that tells
+        // us whether focus lives anywhere inside this host before doing the deeper traversal.
+        if (typeof host.matches === 'function') {
+            try {
+                if (!host.matches(':focus-within')) {
+                    return false;
+                }
+            }
+            catch {
+                // Selector unsupported in this environment; fall through to the traversal below.
+            }
+        }
+        return this.findFocusedInputLikeElement(host) !== null;
+    }
+    /**
+     * Walks the `:focus` chain from a tree scope, descending into open shadow roots, and returns
+     * the focused element when it is input-like.
+     */
+    findFocusedInputLikeElement(root) {
+        let focused = null;
+        try {
+            focused = root.querySelector(':focus');
+        }
+        catch {
+            focused = null;
+        }
+        if (!(focused instanceof HTMLElement)) {
+            return null;
+        }
+        if (this.isInputLikeElement(focused)) {
+            return focused;
+        }
+        if (focused.shadowRoot) {
+            return this.findFocusedInputLikeElement(focused.shadowRoot);
+        }
+        return null;
+    }
+    matchesFocus(element) {
+        if (typeof element.matches !== 'function') {
+            return false;
+        }
+        try {
+            return element.matches(':focus');
+        }
+        catch {
+            return false;
+        }
+    }
+    isInputLikeElement(element) {
+        const tag = element.tagName;
+        return (tag === 'INPUT' ||
+            tag === 'TEXTAREA' ||
+            tag === 'SELECT' ||
+            element.isContentEditable);
+    }
+    isNodeInsideHost(node, host) {
+        if (!node) {
+            return false;
+        }
+        let current = node;
+        while (current) {
+            if (current === host) {
+                return true;
+            }
+            if (current.parentNode) {
+                current = current.parentNode;
+                continue;
+            }
+            const root = current.getRootNode();
+            if (root instanceof ShadowRoot) {
+                current = root.host;
+                continue;
+            }
+            break;
+        }
+        return false;
+    }
+    getDeepActiveElement(root = document) {
+        const activeElement = root.activeElement;
+        if (!(activeElement instanceof HTMLElement)) {
+            return null;
+        }
+        if (activeElement.shadowRoot) {
+            const nested = this.getDeepActiveElement(activeElement.shadowRoot);
+            return nested ?? activeElement;
+        }
+        return activeElement;
+    }
+    /**
+     * Unmounts the custom element and performs cleanup.
+     * If a renderer is registered, delegates to renderer.onUnmount and captures returned state.
+     * Otherwise, simply removes from DOM.
+     * Called when object is deleted, viewport culled, or editor is unloading.
+     */
+    unmount() {
+        if (!this.isMounted || !this.elementRef) {
+            return;
+        }
+        // Try renderer-based unmount if renderer is registered
+        if (this.rendererKey) {
+            const renderer = KritzelCustomElementRendererRegistry.get(this.rendererKey);
+            if (renderer) {
+                // Capture any updated data returned by renderer
+                const updatedData = renderer.onUnmount({
+                    object: this,
+                    container: this.elementRef,
+                    data: this.rendererData,
+                });
+                if (updatedData !== undefined) {
+                    this.rendererData = updatedData;
+                }
+            }
+        }
+        this.isMounted = false;
+        this.elementRef = null;
+    }
+    /**
+     * Returns whether the rendered content contains a scrollable element.
+     * Traverses light DOM, open shadow roots, and slotted content so nested
+     * framework components are detected as well.
+     */
+    isElementScrollable() {
+        return !!KritzelHTMLHelper.findScrollableElement(this.element);
+    }
+    /**
+     * Creates a placeholder element when HTML deserialization fails.
+     * Used as fallback to ensure element is always defined.
+     * @returns A div element with placeholder styling
+     */
+    createPlaceholder() {
+        const el = document.createElement('div');
+        el.textContent = '[Custom Element]';
+        el.style.border = '1px dashed #ccc';
+        el.style.display = 'flex';
+        el.style.alignItems = 'center';
+        el.style.justifyContent = 'center';
+        el.style.backgroundColor = '#f9f9f9';
+        el.style.color = '#999';
+        el.style.fontSize = '12px';
+        return el;
     }
     /**
      * Resizes and repositions the custom element on the canvas.
@@ -109,7 +377,61 @@ export class KritzelCustomElement extends KritzelBaseObject {
         Object.assign(copiedObject, this);
         copiedObject.id = this.generateId();
         copiedObject.isMounted = false;
+        copiedObject.isSelected = false;
+        copiedObject.isHovered = false;
+        copiedObject.isInteractive = false;
+        copiedObject.resizing = false;
+        copiedObject.markedForRemoval = false;
+        copiedObject.isVisible = true;
         copiedObject.element = this.element.cloneNode(true);
         return copiedObject;
     }
+    /**
+     * Serializes the custom element to a plain JavaScript object for persistence.
+     * Stores HTML as a string (safe for JSON/Yjs) and captures dimension metadata.
+     * @returns A serializable object with htmlString and dimension snapshots
+     */
+    serialize() {
+        const { _core, _elementRef, element, totalWidth, totalHeight, isSelected, isHovered, isMounted, isInteractive, resizing, markedForRemoval, isVisible, ...props } = this;
+        const cloned = structuredClone(props);
+        // Include rendererKey and rendererData for lifecycle-driven rendering
+        cloned.rendererKey = this.rendererKey;
+        cloned.rendererData = this.rendererData;
+        // Store HTML as string for fallback/compatibility when renderer is unavailable
+        cloned.htmlString = element ? element.outerHTML : '';
+        // Capture dimension snapshot at serialization time
+        cloned.serializedWidth = this.width;
+        cloned.serializedHeight = this.height;
+        return cloned;
+    }
+    /**
+     * Deserializes the custom element from a plain object.
+     * Reconstructs the element from stored HTML string with fallback to placeholder.
+     * @template T - The expected return type
+     * @param object - The serialized object data to restore from
+     * @returns This instance cast to type T
+     */
+    deserialize(object) {
+        super.deserialize(object);
+        // Legacy compatibility: this deprecated field should not persist on revived objects.
+        delete this.allowEmbeddedInteraction;
+        // Restore renderer metadata
+        this.rendererKey = object.rendererKey ?? null;
+        this.rendererData = object.rendererData;
+        // Reconstruct element from stored HTML, or create placeholder
+        if (object.htmlString) {
+            try {
+                const temp = document.createElement('div');
+                temp.innerHTML = object.htmlString;
+                this.element = temp.firstElementChild || this.createPlaceholder();
+            }
+            catch {
+                this.element = this.createPlaceholder();
+            }
+        }
+        else {
+            this.element = this.createPlaceholder();
+        }
+        return this;
+    }
 }

package/dist/collection/classes/objects/image.class.js

@@ -39,7 +39,6 @@ export class KritzelImage extends KritzelBaseObject {
     maxWidth = 300;
     maxHeight = 300;
     maxCompressionSize = 1200;
-    isDebugInfoVisible = true;
     // --- Transient (not persisted to Yjs) ---
     /**
      * URL resolved from the asset storage layer (e.g. a `blob:` or https URL).

package/dist/collection/classes/objects/selection-group.class.js

@@ -82,6 +82,12 @@ export class KritzelSelectionGroup extends KritzelBaseObject {
         this._cachedObjectIdsHash = currentHash;
         return this._cachedObjects;
     }
+    syncChildSelectionState(children) {
+        const shouldBeSelected = this.isSelected === true;
+        for (const child of children) {
+            child.isSelected = shouldBeSelected;
+        }
+    }
     /**
      * Gets the number of objects in the selection group.
      * @returns The count of selected objects
@@ -127,6 +133,7 @@ export class KritzelSelectionGroup extends KritzelBaseObject {
         for (const object of objects) {
             if (!this._objectIds.includes(object.id)) {
                 this._objectIds.push(object.id);
+                object.isSelected = true;
                 changed = true;
             }
         }
@@ -154,9 +161,11 @@ export class KritzelSelectionGroup extends KritzelBaseObject {
         const index = this._objectIds.findIndex(id => id === object.id);
         if (index === -1) {
             this._objectIds.push(object.id);
+            object.isSelected = true;
         }
         else {
             this._objectIds.splice(index, 1);
+            object.isSelected = false;
         }
         this._cachedObjects = null; // Invalidate cache
         const children = this.objects; // Get cached objects once
@@ -298,6 +307,8 @@ export class KritzelSelectionGroup extends KritzelBaseObject {
     deserialize(object) {
         // First, deserialize all base properties using parent's deserialize
         super.deserialize(object);
+        // Selection groups intentionally persist their selected state.
+        this.isSelected = object.isSelected === true;
         // Restore objectIds through setter
         if (object.objectIds) {
             this.objectIds = object.objectIds;
@@ -306,6 +317,7 @@ export class KritzelSelectionGroup extends KritzelBaseObject {
         if (object.unchangedObjectSnapshots) {
             this.unchangedObjectSnapshots = new Map(Object.entries(object.unchangedObjectSnapshots));
         }
+        this.syncChildSelectionState(this.objects);
         return this;
     }
     /**

package/dist/collection/classes/providers/assets/asset-resolver.class.js

@@ -60,9 +60,13 @@ export class KritzelAssetResolver {
     _pending = new Map();
     _flushTimer = null;
     _destroyed = false;
-    _quiet = false;
+    _quiet = true;
     /** Dedupes concurrent resolves of the same id. */
     _resolvePromises = new Map();
+    /** Enables or disables resolver diagnostic logging. */
+    setShowInfo(show) {
+        this._quiet = !show;
+    }
     /**
      * Whether any remote provider is configured. Used by the engine to
      * decide whether to warn about a missing remote provider when Yjs is
@@ -88,7 +92,6 @@ export class KritzelAssetResolver {
         // Ensure the deferred ready promise exists before any async work so
         // concurrent callers awaiting `ensureReady()` are unblocked together.
         this.getReadyPromise();
-        this._quiet = config?.quiet ?? false;
         const providers = this.instantiateProviders(config?.providers ?? []);
         // Ensure a local provider always exists so uploads can be optimistic
         // and remote misses can be cached for later offline access.
@@ -121,8 +124,10 @@ export class KritzelAssetResolver {
                 await provider.init();
             }
             catch (err) {
-                console.warn(`[KritzelAssetResolver] Remote provider "${provider.name}" failed to initialize. ` +
-                    `Assets will be served from the local provider until the remote becomes available.`, err);
+                if (this.canLogInfo()) {
+                    console.warn(`[Kritzel] Asset resolver remote provider "${provider.name}" failed to initialize. ` +
+                        `Assets will be served from the local provider until the remote becomes available.`, err);
+                }
             }
         }
         // Re-enqueue any uploads that were interrupted before completing.
@@ -134,7 +139,7 @@ export class KritzelAssetResolver {
             this._resolveReady = null;
             this._rejectReady = null;
         }
-        if (!this._quiet) {
+        if (this.canLogInfo()) {
             this.logProviderConfiguration();
         }
         if (this._pending.size > 0) {
@@ -143,8 +148,8 @@ export class KritzelAssetResolver {
     }
     /** Tears down the resolver and all providers. */
     destroy() {
-        if (!this._quiet) {
-            console.info('Asset resolver destroyed');
+        if (this.canLogInfo()) {
+            console.info('[Kritzel] Asset resolver destroyed');
         }
         this._destroyed = true;
         if (this._flushTimer) {
@@ -340,7 +345,7 @@ export class KritzelAssetResolver {
     // ------------------------------------------------------------------
     logProviderConfiguration() {
         const lines = [
-            `Asset resolver initialized with ${this._providers.length} provider(s):`,
+            `[Kritzel] Asset resolver initialized with ${this._providers.length} provider(s):`,
         ];
         for (const provider of this._providers) {
             const role = provider === this._local ? 'local (primary write target)' : provider.type;
@@ -399,8 +404,8 @@ export class KritzelAssetResolver {
                 recoveredCount++;
             }
         }
-        if (!this._quiet && recoveredCount > 0) {
-            console.info(`Asset resolver: recovered ${recoveredCount} pending upload(s)`);
+        if (this.canLogInfo() && recoveredCount > 0) {
+            console.info(`[Kritzel] Asset resolver recovered ${recoveredCount} pending upload(s)`);
         }
     }
     scheduleFlush(delayMs) {
@@ -455,8 +460,8 @@ export class KritzelAssetResolver {
                 });
                 this._pending.delete(key);
                 await this.clearPendingRemote(job.id, job.providerName);
-                if (!this._quiet) {
-                    console.info(`Asset resolver: uploaded ${job.id} to ${provider.name}`);
+                if (this.canLogInfo()) {
+                    console.info(`[Kritzel] Asset resolver uploaded ${job.id} to ${provider.name}`);
                 }
             }
             catch (err) {
@@ -464,8 +469,10 @@ export class KritzelAssetResolver {
                 const delay = Math.min(MAX_RETRY_DELAY_MS, BASE_RETRY_DELAY_MS * Math.pow(2, job.attempts - 1));
                 job.nextAttemptAt = Date.now() + delay;
                 nextRetryIn = Math.min(nextRetryIn, delay);
-                console.warn(`[KritzelAssetResolver] Upload to ${provider.name} failed for ${job.id} (attempt ${job.attempts}). ` +
-                    `Retrying in ${Math.round(delay / 1000)}s.`, err);
+                if (this.canLogInfo()) {
+                    console.warn(`[Kritzel] Asset resolver upload to ${provider.name} failed for ${job.id} (attempt ${job.attempts}). ` +
+                        `Retrying in ${Math.round(delay / 1000)}s.`, err);
+                }
             }
         }
         if (this._pending.size > 0 && Number.isFinite(nextRetryIn)) {
@@ -523,4 +530,7 @@ export class KritzelAssetResolver {
         const res = await fetch(dataUrl);
         return res.blob();
     }
+    canLogInfo() {
+        return !this._quiet;
+    }
 }

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

@@ -20,7 +20,6 @@ export class IndexedDBAssetProvider {
     type = 'local';
     name = 'IndexedDBAssetProvider';
     _dbName;
-    _quiet;
     _db = null;
     /** In-memory cache of id -> object URL to avoid re-creating blob URLs. */
     _urlCache = new Map();
@@ -28,7 +27,6 @@ export class IndexedDBAssetProvider {
     _knownIds = new Set();
     constructor(options) {
         this._dbName = options?.dbName ?? DEFAULT_DB_NAME;
-        this._quiet = options?.quiet ?? false;
     }
     /**
      * Factory helper enabling use as `IndexedDBAssetProvider.with({ dbName: '...' })`
@@ -43,9 +41,6 @@ export class IndexedDBAssetProvider {
         this._db = await this.openDatabase();
         // Warm up the known-ids cache so canResolve can answer synchronously.
         await this.loadKnownIds();
-        if (!this._quiet) {
-            console.info(`IndexedDBAssetProvider initialized: ${this._dbName}`);
-        }
     }
     destroy() {
         for (const url of this._urlCache.values()) {
@@ -62,9 +57,6 @@ export class IndexedDBAssetProvider {
             this._db.close();
             this._db = null;
         }
-        if (!this._quiet) {
-            console.info(`IndexedDBAssetProvider destroyed: ${this._dbName}`);
-        }
     }
     canResolve(id) {
         return this._knownIds.has(id);

package/dist/collection/classes/registries/custom-element-renderer.registry.js

@@ -0,0 +1,52 @@
+const KRITZEL_RENDERER_REGISTRY_KEY = '__kritzelCustomElementRendererRegistry__';
+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 custom element 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 custom element is deserialized with a rendererKey, the registry is consulted to
+ * resolve the renderer and mount with the persisted rendererData.
+ */
+export class KritzelCustomElementRendererRegistry {
+    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);
+    }
+}