@kritzel/engine 0.4.31

package/dist/collection/classes/managers/browser-permission.manager.js

@@ -0,0 +1,64 @@
+/**
+ * Manages browser permission checks and prompts for a core instance.
+ *
+ * Permission-specific prompt logic is routed through a handler registry so new
+ * permissions can be added without changing the core control flow.
+ */
+export class KritzelBrowserPermissionManager {
+    _isFirefox = /firefox|fxios/i.test(navigator.userAgent);
+    _isSafari = /safari/i.test(navigator.userAgent) && !/chrome|chromium|crios|android|edg/i.test(navigator.userAgent);
+    _requestHandlers = new Map();
+    /**
+     * Creates a new KritzelBrowserPermissionManager instance.
+     * @param core - The KritzelCore instance this manager belongs to
+     */
+    constructor(_core) {
+        this.registerRequestPermissionHandler('clipboard-read', async () => {
+            // Firefox and Safari open native paste menus when the clipboard is read
+            // proactively, so rely on the permission state instead of an eager read.
+            if (this._isFirefox || this._isSafari) {
+                return 'granted';
+            }
+            try {
+                const status = await navigator.permissions.query({ name: 'clipboard-read' });
+                return status.state === 'denied' ? 'denied' : 'granted';
+            }
+            catch {
+                return 'granted';
+            }
+        });
+    }
+    /**
+     * Registers a custom request handler for a browser permission name.
+     * Existing handlers are replaced, which makes the registry easy to extend.
+     *
+     * @param permissionName - The browser permission name to handle
+     * @param handler - The request implementation for that permission
+     */
+    registerRequestPermissionHandler(permissionName, handler) {
+        this._requestHandlers.set(permissionName, handler);
+    }
+    /**
+     * Checks the current state for a browser permission via the Permissions API.
+     *
+     * @param permissionName - The browser permission name to inspect
+     */
+    async checkPermission(permissionName) {
+        const status = await navigator.permissions.query({ name: permissionName });
+        return status.state;
+    }
+    /**
+     * Requests a browser permission using the registered handler for the given
+     * permission name, then falls back to a permission check when no handler is
+     * registered.
+     *
+     * @param permissionName - The browser permission name to request
+     */
+    async requestPermission(permissionName) {
+        const handler = this._requestHandlers.get(permissionName);
+        if (handler) {
+            return handler();
+        }
+        return this.checkPermission(permissionName);
+    }
+}

package/dist/collection/classes/managers/clipboard.manager.js

@@ -0,0 +1,346 @@
+import { KritzelImage } from "../objects/image.class";
+import { KritzelText } from "../objects/text.class";
+import { KritzelSelectionGroup } from "../objects/selection-group.class";
+import { KritzelClassHelper } from "../../helpers/class.helper";
+import { KritzelReviver } from "../core/reviver.class";
+import { KritzelPasteIntentProviderRegistry } from "../registries/paste-intent-provider.registry";
+import { KritzelEventPasteIntentProvider } from "../providers/paste-intent/event-paste-intent.provider";
+import { KritzelNavigatorPasteIntentProvider } from "../providers/paste-intent/navigator-paste-intent.provider";
+import { KritzelIosPasteIntentProvider } from "../providers/paste-intent/ios-paste-intent.provider";
+import { CLIPBOARD_PAYLOAD_PREFIX } from "./clipboard.types";
+import imageCompression from "browser-image-compression";
+import { KritzelImageFileHelper } from "../../helpers/image-file.helper";
+/**
+ * Manages clipboard operations (copy/cut/paste) for a core instance.
+ *
+ * The system clipboard is the preferred source of truth: copy serializes the current
+ * selection into a Kritzel payload, paste reads + revives it.
+ *
+ * A copy also mirrors the payload into an in-memory session buffer. On platforms where
+ * eventless programmatic clipboard access is unavailable (notably iOS Safari, where the
+ * context menu triggers copy/paste without a native ClipboardEvent), the session buffer
+ * is used as the fallback source so internal object copy/paste keeps working.
+ */
+export class KritzelClipboardManager {
+    _core;
+    _pasteIntentRegistry;
+    /**
+     * In-memory mirror of the most recent copy payload. Acts as the fallback clipboard
+     * source when the system clipboard cannot be read programmatically (e.g. iOS Safari
+     * context-menu paste). Reset is not required; a new copy overwrites it.
+     */
+    _sessionClipboardPayload = null;
+    /**
+     * In-memory cascade offset (world units) applied to successive pastes of the same
+     * clipboard content so they don't stack exactly on top of each other. Reset on copy/cut.
+     */
+    _pasteOffset = 0;
+    constructor(core) {
+        this._core = core;
+        this._pasteIntentRegistry = new KritzelPasteIntentProviderRegistry(this._core);
+        // Provider order is intentional: iOS eventless path should short-circuit,
+        // native paste events remain preferred, and async navigator APIs are fallback.
+        this._pasteIntentRegistry.register(new KritzelIosPasteIntentProvider());
+        this._pasteIntentRegistry.register(new KritzelEventPasteIntentProvider());
+        this._pasteIntentRegistry.register(new KritzelNavigatorPasteIntentProvider());
+    }
+    /**
+     * The most recent copy payload mirrored in memory, used as a fallback clipboard
+     * source when the system clipboard cannot be read programmatically.
+     */
+    get sessionClipboardPayload() {
+        return this._sessionClipboardPayload;
+    }
+    /**
+     * Serializes an object for the clipboard payload. Groups additionally embed their
+     * (recursively serialized) children under `__children__` so the payload is self-contained.
+     */
+    serializeForClipboard(object) {
+        const serialized = (typeof object.serialize === 'function' ? object.serialize() : object);
+        if (KritzelClassHelper.isInstanceOf(object, 'KritzelGroup')) {
+            serialized.__children__ = object.children.map(child => this.serializeForClipboard(child));
+        }
+        return serialized;
+    }
+    serializeClipboardPayload(payload) {
+        return `${CLIPBOARD_PAYLOAD_PREFIX}${JSON.stringify(payload)}`;
+    }
+    async writeBrowserClipboardPayload(payload, event) {
+        const serialized = this.serializeClipboardPayload(payload);
+        if (event?.clipboardData) {
+            event.clipboardData.setData('text/plain', serialized);
+            return;
+        }
+        if (typeof navigator === 'undefined' || !navigator.clipboard?.writeText) {
+            return;
+        }
+        try {
+            await navigator.clipboard.writeText(serialized);
+        }
+        catch {
+            // Ignore clipboard permission failures and keep the local clipboard working.
+        }
+    }
+    /**
+     * Revives a single serialized clipboard object (and its embedded group children).
+     * IDs are NOT regenerated here; see regenerateIdsAndRemapAnchors.
+     */
+    reviveClipboardObject(serialized) {
+        const reviver = new KritzelReviver(this._core);
+        const { __children__, ...objectData } = serialized;
+        const revived = reviver.revive(objectData);
+        if (!revived) {
+            return null;
+        }
+        if (__children__ && KritzelClassHelper.isInstanceOf(revived, 'KritzelGroup')) {
+            const children = __children__.map(child => this.reviveClipboardObject(child)).filter((child) => child != null);
+            revived._pendingChildren = children;
+            revived.childIds = children.map(child => child.id);
+        }
+        return revived;
+    }
+    /**
+     * Assigns fresh unique IDs to every revived object (including nested group children),
+     * keeping group.childIds in sync and remapping line anchors that reference copied
+     * siblings to their new IDs. Anchors pointing at objects outside the pasted set are
+     * left untouched so they stay connected to the existing object.
+     */
+    regenerateIdsAndRemapAnchors(topLevel) {
+        const all = [];
+        const hasOnlyTopLevelLines = topLevel.length > 0 && topLevel.every(object => KritzelClassHelper.isInstanceOf(object, 'KritzelLine'));
+        const collect = (objects) => {
+            for (const object of objects) {
+                all.push(object);
+                if (KritzelClassHelper.isInstanceOf(object, 'KritzelGroup')) {
+                    collect(object._pendingChildren);
+                }
+            }
+        };
+        collect(topLevel);
+        const idMap = new Map();
+        for (const object of all) {
+            const newId = object.generateId();
+            idMap.set(object.id, newId);
+            object.id = newId;
+            object.isMounted = false;
+        }
+        for (const object of all) {
+            if (KritzelClassHelper.isInstanceOf(object, 'KritzelGroup')) {
+                object.childIds = object.childIds.map(id => idMap.get(id) ?? id);
+            }
+            if (KritzelClassHelper.isInstanceOf(object, 'KritzelLine')) {
+                if (object.startAnchor && idMap.has(object.startAnchor.objectId)) {
+                    object.startAnchor = { objectId: idMap.get(object.startAnchor.objectId) };
+                }
+                else if (hasOnlyTopLevelLines) {
+                    object.startAnchor = undefined;
+                }
+                if (object.endAnchor && idMap.has(object.endAnchor.objectId)) {
+                    object.endAnchor = { objectId: idMap.get(object.endAnchor.objectId) };
+                }
+                else if (hasOnlyTopLevelLines) {
+                    object.endAnchor = undefined;
+                }
+            }
+        }
+    }
+    /**
+     * Copies currently selected objects into internal clipboard state.
+     */
+    copy(event) {
+        const selectionGroup = this._core.store.selectionGroup;
+        if (!selectionGroup) {
+            return;
+        }
+        const payload = {
+            version: 1,
+            sourceWorkspaceId: this._core.store.state.activeWorkspace?.id,
+            objects: selectionGroup.objects.sort((a, b) => a.zIndex - b.zIndex).map(obj => this.serializeForClipboard(obj)),
+        };
+        // A fresh copy resets the cascade so the first paste lands at the default offset.
+        this._pasteOffset = 0;
+        // Mirror the payload in memory so eventless paste still works where the system
+        // clipboard is not programmatically accessible (e.g. iOS Safari context menu).
+        this._sessionClipboardPayload = payload;
+        void this.writeBrowserClipboardPayload(payload, event);
+    }
+    /**
+     * Cuts currently selected objects (copy then delete).
+     */
+    cut(event) {
+        const selectionGroup = this._core.store.selectionGroup;
+        if (!selectionGroup) {
+            return;
+        }
+        this.copy(event);
+        this._core.delete();
+    }
+    materializeKritzelObjects(intent) {
+        const objects = intent.payload.objects.map(object => this.reviveClipboardObject(object)).filter((object) => object != null);
+        this.regenerateIdsAndRemapAnchors(objects);
+        return objects;
+    }
+    async materializeImageFiles(intent) {
+        try {
+            const scale = this._core.store.state.scale;
+            const offset = 25 / scale;
+            const preparePromises = intent.files.map(async (file, index) => {
+                const preparedFile = await this.prepareImageFile(file);
+                return KritzelImage.fromBlob(this._core, preparedFile, {
+                    translateX: index * offset,
+                    translateY: index * offset,
+                });
+            });
+            return await Promise.all(preparePromises);
+        }
+        catch (err) {
+            console.error('Failed to import pasted image files:', err);
+            return null;
+        }
+    }
+    async prepareImageFile(file) {
+        if (KritzelImageFileHelper.isGifFile(file)) {
+            return file;
+        }
+        return imageCompression(file, { maxWidthOrHeight: 1200 });
+    }
+    async materializePlainText(intent) {
+        const textObject = KritzelText.create(this._core);
+        const paragraphs = intent.text.split('\n').map(line => {
+            if (line.length === 0) {
+                return { type: 'paragraph' }; // Empty paragraph
+            }
+            return {
+                type: 'paragraph',
+                content: [{ type: 'text', text: line }],
+            };
+        });
+        textObject.setContent({
+            type: 'doc',
+            content: paragraphs,
+        });
+        return [textObject];
+    }
+    /**
+     * Pastes objects from clipboard with optional explicit world coordinates.
+     */
+    async paste(x, y, event) {
+        const pasteIntent = await this._pasteIntentRegistry.resolve(event);
+        let objects = null;
+        if (pasteIntent.type === 'kritzel_objects') {
+            objects = this.materializeKritzelObjects(pasteIntent);
+        }
+        else if (pasteIntent.type === 'image_files') {
+            objects = await this.materializeImageFiles(pasteIntent);
+        }
+        else if (pasteIntent.type === 'plain_text') {
+            objects = await this.materializePlainText(pasteIntent);
+        }
+        if (!objects || objects.length === 0) {
+            return;
+        }
+        await this.insertMaterializedObjects(objects, pasteIntent, x, y);
+    }
+    async insertMaterializedObjects(copiedObjects, pasteIntent, x, y) {
+        const activeWorkspace = this._core.store.state.activeWorkspace;
+        if (!activeWorkspace) {
+            return;
+        }
+        // Determine if we should center the objects in the viewport.
+        // This happens if the user specifically pasted from a different workspace,
+        // OR if we're inserting brand new external items (like images or text).
+        const isDifferentWorkspace = copiedObjects.some(obj => obj.workspaceId !== activeWorkspace.id);
+        const isNewExternalContent = pasteIntent.type !== 'kritzel_objects';
+        const shouldCenterInViewport = isDifferentWorkspace || isNewExternalContent;
+        const hasExplicitPastePosition = x !== undefined && y !== undefined;
+        const minX = Math.min(...copiedObjects.map(obj => obj.translateX));
+        const minY = Math.min(...copiedObjects.map(obj => obj.translateY));
+        let pasteX;
+        let pasteY;
+        const step = 25 / this._core.store.state.scale;
+        if (x !== undefined && y !== undefined) {
+            pasteX = x;
+            pasteY = y;
+        }
+        else if (shouldCenterInViewport) {
+            pasteX = minX;
+            pasteY = minY;
+        }
+        else {
+            pasteX = minX + step + this._pasteOffset;
+            pasteY = minY + step + this._pasteOffset;
+            // Advance the cascade so the next same-content paste is offset further.
+            this._pasteOffset += step;
+        }
+        const offsetX = pasteX - minX;
+        const offsetY = pasteY - minY;
+        this._core.removeSelectionGroup();
+        this._core.removeSelectionBox();
+        const selectionGroup = KritzelSelectionGroup.create(this._core);
+        const baseZIndex = this._core.store.currentZIndex;
+        this._core.store.objects.transaction(() => {
+            const flushPendingChildren = (group, parentZIndex) => {
+                if (group._pendingChildren.length === 0) {
+                    return;
+                }
+                const pendingChildren = group._pendingChildren;
+                group._pendingChildren = [];
+                pendingChildren.forEach((child, childIndex) => {
+                    if (child.workspaceId !== activeWorkspace.id) {
+                        child.workspaceId = activeWorkspace.id;
+                    }
+                    child.updatePosition(child.translateX + offsetX, child.translateY + offsetY);
+                    child.zIndex = parentZIndex + childIndex + 1;
+                    if (KritzelClassHelper.isInstanceOf(child, 'KritzelGroup')) {
+                        flushPendingChildren(child, child.zIndex);
+                    }
+                    this._core.addObject(child);
+                });
+                group.finalize();
+            };
+            const newlyAddedObjects = [];
+            copiedObjects.forEach((obj, i) => {
+                if (obj.workspaceId !== activeWorkspace.id) {
+                    obj.workspaceId = activeWorkspace.id;
+                }
+                obj.updatePosition(obj.translateX + offsetX, obj.translateY + offsetY);
+                obj.zIndex = baseZIndex + i;
+                if (KritzelClassHelper.isInstanceOf(obj, 'KritzelGroup')) {
+                    flushPendingChildren(obj, obj.zIndex);
+                }
+                this._core.addObject(obj);
+                newlyAddedObjects.push(obj);
+                selectionGroup.addOrRemove(obj);
+            });
+            this._core.engine.emitObjectsAdded(newlyAddedObjects);
+        });
+        this._core.anchorManager.rebuildIndex();
+        selectionGroup.isSelected = true;
+        if (copiedObjects.length === 1) {
+            selectionGroup.rotation = copiedObjects[0].rotation;
+        }
+        if (shouldCenterInViewport && !hasExplicitPastePosition) {
+            selectionGroup.centerInViewport();
+        }
+        this._core.addSelectionGroup(selectionGroup);
+        this._core.engine.viewport?.bringIntoViewIfNeeded(selectionGroup);
+        this._core.store.state.isSelecting = false;
+        // Use a double requestAnimationFrame to ensure the browser has fully rendered the DOM,
+        // and objects like KritzelText have executed their own internal size-adjustment rAF calls.
+        await new Promise(resolve => {
+            requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+        });
+        // Re-evaluate bounding box dimensions now that any DOM nodes (like ProseMirror text editors)
+        // have mounted and calculated their actual bounds.
+        selectionGroup.refreshObjectDimensions();
+        // We should update it if the centerInViewport or width adjustments changed it significantly
+        if (shouldCenterInViewport && !hasExplicitPastePosition) {
+            selectionGroup.centerInViewport();
+        }
+        this._core.engine.emitObjectsChange();
+        this._core.rerender();
+        this._core.store.setState('activeTool', this._core.toolRegistry.getTool('selection'));
+        this._core.engine.emitObjectsChange();
+        this._core.rerender();
+    }
+}

package/dist/collection/classes/managers/clipboard.types.js

@@ -0,0 +1 @@
+export const CLIPBOARD_PAYLOAD_PREFIX = 'kritzel-clipboard/v1:';

package/dist/collection/classes/managers/cursor.manager.js

@@ -0,0 +1,139 @@
+import { KritzelCursorHelper } from "../../helpers/cursor.helper";
+/**
+ * Manages cursor state and updates across the application.
+ * Handles cursor changes based on handle hovers, tool states, and interactions.
+ */
+export class KritzelCursorManager {
+    _core;
+    _targetElement = null;
+    _shadowRoot = null;
+    /**
+     * Creates a new KritzelCursorManager instance.
+     * @param core - The KritzelCore instance that provides access to the store and other core functionality.
+     */
+    constructor(core) {
+        this._core = core;
+    }
+    /**
+     * Sets the target element where cursor styles will be applied.
+     * Resets any cursor styles on the previous target element before setting the new one.
+     * Also sets the `--kritzel-global-pointer-cursor` CSS variable for child components to use.
+     * @param element - The HTML element to apply cursor styles to, or null to clear the target.
+     */
+    setTargetElement(element) {
+        // Reset cursor on old target
+        if (this._targetElement) {
+            this._targetElement.style.cursor = '';
+            this._targetElement.style.removeProperty('--kritzel-global-pointer-cursor');
+        }
+        this._targetElement = element;
+        // Set the pointer cursor CSS variable for child components to use
+        if (this._targetElement) {
+            this._targetElement.style.setProperty('--kritzel-global-pointer-cursor', KritzelCursorHelper.getPointerCursor());
+        }
+    }
+    /**
+     * Gets the current cursor target element.
+     * @returns The HTML element where cursor styles are applied, or null if not set.
+     */
+    getTargetElement() {
+        return this._targetElement;
+    }
+    /**
+     * Sets the shadow root used for element detection in hover state calculations.
+     * Required for `elementsFromPoint()` to work within the shadow DOM.
+     * @param shadowRoot - The ShadowRoot instance of the component.
+     */
+    setShadowRoot(shadowRoot) {
+        this._shadowRoot = shadowRoot;
+    }
+    /**
+     * Resets cursor to default state by setting both icon and iconActive to 'default'.
+     * Should be called when all pointers are released to return to the standard cursor.
+     */
+    resetToDefault() {
+        this._core.store.state.cursor = { icon: 'default', iconActive: 'default' };
+    }
+    /**
+     * Detects handle hover states using elementsFromPoint() to work with overlapped elements.
+     * This approach finds all elements at the pointer position instead of relying on pointerenter/pointerleave,
+     * which allows proper detection even when elements overlap.
+     *
+     * Updates the cursor state based on which handle type is being hovered:
+     * - Resize handle overlays: Sets a rotated vertical move cursor based on handle position and selection rotation.
+     * - Rotation handle overlays: Sets a hand cursor that changes to grab when active.
+     * - Line handle overlays: Sets a hand cursor that changes to grab when active.
+     * - No handle: Resets to default cursor.
+     *
+     * @param ev - The PointerEvent containing the cursor position (clientX, clientY).
+     */
+    updateHoverState(ev) {
+        if (this._core.store.isPointerDown)
+            return;
+        if (!this._shadowRoot)
+            return;
+        const elementsAtPoint = this._shadowRoot.elementsFromPoint(ev.clientX, ev.clientY);
+        if (!elementsAtPoint || elementsAtPoint.length === 0)
+            return;
+        // Check for resize handle overlays (selection group)
+        const resizeHandleOverlay = elementsAtPoint.find(el => el.classList.contains('resize-handle-overlay'));
+        if (resizeHandleOverlay) {
+            const selectionGroup = this._core.store.selectionGroup;
+            const rotationDegrees = selectionGroup?.rotationDegrees ?? 0;
+            // Determine rotation offset based on handle position
+            const isTopLeft = resizeHandleOverlay.classList.contains('top-left');
+            const isBottomRight = resizeHandleOverlay.classList.contains('bottom-right');
+            const rotationOffset = (isTopLeft || isBottomRight) ? -45 : 45;
+            this._core.store.state.cursor = { icon: 'move-vertical', rotation: rotationDegrees + rotationOffset };
+            return;
+        }
+        // Check for rotation handle overlay
+        const rotationHandleOverlay = elementsAtPoint.find(el => el.classList.contains('rotation-handle-overlay'));
+        if (rotationHandleOverlay) {
+            this._core.store.state.cursor = { icon: 'hand', iconActive: 'hand-grab' };
+            return;
+        }
+        // Check for line handle overlays (selection line)
+        const lineHandleOverlay = elementsAtPoint.find(el => el.classList.contains('selection-line-handle-overlay'));
+        if (lineHandleOverlay) {
+            this._core.store.state.cursor = { icon: 'hand', iconActive: 'hand-grab' };
+            return;
+        }
+        // Reset cursor if not hovering any handle
+        this._core.store.state.cursor = { icon: 'default', iconActive: 'default' };
+    }
+    /**
+     * Applies the current cursor state to the target element.
+     * Reads the cursor configuration from the store state and uses KritzelCursorHelper
+     * to generate the appropriate cursor value. Uses the active icon when pointer is down,
+     * otherwise uses the default icon.
+     * Should be called in the render loop to keep the cursor in sync with state.
+     */
+    applyCursor() {
+        const state = this._core.store.state;
+        const isPointerDown = this._core.store.isPointerDown;
+        const icon = state.cursor?.icon;
+        const iconActive = state.cursor?.iconActive ?? icon;
+        const rotation = state.cursor?.rotation;
+        const cursor = KritzelCursorHelper.getCursor({
+            iconName: isPointerDown ? iconActive : icon,
+            rotation: rotation,
+        });
+        if (this._targetElement) {
+            this._targetElement.style.cursor = cursor;
+        }
+    }
+    /**
+     * Cleans up cursor state when the component is disconnected.
+     * Removes cursor styles and CSS custom properties from the target element,
+     * then clears all internal references to allow garbage collection.
+     */
+    cleanup() {
+        if (this._targetElement) {
+            this._targetElement.style.cursor = '';
+            this._targetElement.style.removeProperty('--kritzel-pointer-cursor');
+        }
+        this._targetElement = null;
+        this._shadowRoot = null;
+    }
+}