@kritzel/engine 0.4.31

package/dist/collection/classes/structures/quadtree.structure.js

@@ -0,0 +1,251 @@
+/**
+ * A quadtree data structure for efficient spatial indexing of objects.
+ * Quadtrees recursively subdivide 2D space into four quadrants to enable
+ * fast spatial queries like finding all objects within a given region.
+ *
+ * @template T - The type of objects stored in the quadtree, must extend KritzelBaseObject
+ */
+export class KritzelQuadtree {
+    bounds;
+    capacity;
+    objects = [];
+    children = null;
+    _size = 0;
+    /**
+     * Total number of objects in the quadtree (O(1) access).
+     * @returns The count of all objects stored in this quadtree and its children
+     */
+    get size() {
+        return this._size;
+    }
+    /**
+     * Creates a new quadtree with the specified bounds and capacity.
+     *
+     * @param bounds - The bounding box defining the spatial region covered by this quadtree
+     * @param capacity - Maximum number of objects a node can hold before subdividing (default: 16)
+     */
+    constructor(bounds, capacity = 16) {
+        this.bounds = bounds;
+        this.capacity = capacity;
+    }
+    /**
+     * Resets the quadtree to its initial empty state.
+     * Clears all stored objects and removes all child nodes.
+     */
+    reset() {
+        this.objects = [];
+        this.children = null;
+        this._size = 0;
+    }
+    /**
+     * Inserts an object into the quadtree.
+     * If the current node exceeds capacity, it will subdivide and delegate
+     * the insertion to the appropriate child quadrant.
+     *
+     * @param object - The object to insert, must have a rotatedBoundingBox property
+     * @returns `true` if the object was successfully inserted, `false` if it doesn't intersect the quadtree bounds
+     */
+    insert(object) {
+        if (!this.intersects(object.rotatedBoundingBox, this.bounds)) {
+            return false;
+        }
+        if (this.objects.length < this.capacity && this.children === null) {
+            this.objects.push(object);
+            this._size++;
+            return true;
+        }
+        if (this.children === null) {
+            this.subdivide();
+        }
+        for (const child of this.children) {
+            if (child.insert(object)) {
+                this._size++;
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Updates an existing object in the quadtree by matching its ID.
+     * Searches through the tree to find the object and replaces it with the new reference.
+     * Note: This does not reposition the object if its bounding box has changed.
+     *
+     * @param object - The updated object with the same ID as the one to replace
+     * @returns `true` if the object was found and updated, `false` otherwise
+     */
+    update(object) {
+        const index = this.objects.findIndex(o => o.id === object.id);
+        if (index !== -1) {
+            this.objects[index] = object;
+            return true;
+        }
+        if (this.children !== null) {
+            for (const child of this.children) {
+                if (child.update(object)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Reindexes an existing object by removing it from its current node and
+     * reinserting it based on its latest bounding box.
+     *
+     * @param object - The updated object to reindex
+     * @returns `true` if the object was found and reinserted, `false` otherwise
+     */
+    reindex(object) {
+        const removed = this.remove(o => o.id === object.id);
+        if (removed === 0) {
+            return false;
+        }
+        return this.insert(object);
+    }
+    /**
+     * Removes objects from the quadtree that match the given predicate.
+     * Recursively searches through all nodes and removes matching objects.
+     *
+     * @param predicate - A function that returns `true` for objects that should be removed
+     * @returns The total number of objects removed from the quadtree
+     */
+    remove(predicate) {
+        let removed = 0;
+        const index = this.objects.findIndex(o => predicate(o));
+        if (index !== -1) {
+            this.objects.splice(index, 1);
+            removed++;
+        }
+        if (this.children !== null) {
+            for (const child of this.children) {
+                removed += child.remove(predicate);
+            }
+        }
+        this._size -= removed;
+        return removed;
+    }
+    /**
+     * Finds all objects whose bounding boxes intersect with the given range.
+     * This is the primary spatial query method for efficient object retrieval.
+     *
+     * @param range - The bounding box to query against
+     * @returns An array of all objects that intersect with the given range
+     */
+    query(range) {
+        const results = [];
+        this._queryInto(range, results);
+        return results;
+    }
+    /**
+     * Internal method that collects query results into a pre-allocated array.
+     * Avoids creating intermediate arrays from spread operators.
+     *
+     * @param range - The bounding box to query against
+     * @param results - The array to collect matching objects into
+     */
+    _queryInto(range, results) {
+        if (!this.intersects(range, this.bounds)) {
+            return;
+        }
+        for (const object of this.objects) {
+            if (this.intersects(object.rotatedBoundingBox, range)) {
+                results.push(object);
+            }
+        }
+        if (this.children !== null) {
+            for (const child of this.children) {
+                child._queryInto(range, results);
+            }
+        }
+    }
+    /**
+     * Filters all objects in the quadtree using a custom predicate function.
+     * Unlike `query`, this method checks all objects regardless of spatial location.
+     *
+     * @param predicate - A function that returns `true` for objects to include in results
+     * @returns An array of all objects that satisfy the predicate
+     */
+    filter(predicate) {
+        const results = [];
+        this._filterInto(predicate, results);
+        return results;
+    }
+    /**
+     * Internal method that collects filter results into a pre-allocated array.
+     * Avoids creating intermediate arrays from spread operators.
+     *
+     * @param predicate - A function that returns `true` for objects to include
+     * @param results - The array to collect matching objects into
+     */
+    _filterInto(predicate, results) {
+        for (const obj of this.objects) {
+            if (predicate(obj)) {
+                results.push(obj);
+            }
+        }
+        if (this.children !== null) {
+            for (const child of this.children) {
+                child._filterInto(predicate, results);
+            }
+        }
+    }
+    /**
+     * Retrieves all objects stored in the quadtree.
+     * Traverses the entire tree structure to collect every object.
+     *
+     * @returns An array containing all objects in the quadtree
+     */
+    allObjects() {
+        const results = [];
+        this._collectAllInto(results);
+        return results;
+    }
+    /**
+     * Internal method that collects all objects into a pre-allocated array.
+     * Avoids creating intermediate arrays from spread operators.
+     *
+     * @param results - The array to collect all objects into
+     */
+    _collectAllInto(results) {
+        for (const obj of this.objects) {
+            results.push(obj);
+        }
+        if (this.children !== null) {
+            for (const child of this.children) {
+                child._collectAllInto(results);
+            }
+        }
+    }
+    /**
+     * Subdivides this quadtree node into four child quadrants.
+     * Called automatically when the node's capacity is exceeded.
+     * Creates children for: Northwest (NW), Northeast (NE), Southwest (SW), Southeast (SE).
+     */
+    subdivide() {
+        const { x, y, z, width, height } = this.bounds;
+        const halfWidth = width / 2;
+        const halfHeight = height / 2;
+        // Create 4 quadrants: NW, NE, SW, SE
+        this.children = [
+            new KritzelQuadtree({ x, y, z, width: halfWidth, height: halfHeight }, this.capacity), // Northwest
+            new KritzelQuadtree({ x: x + halfWidth, y, z, width: halfWidth, height: halfHeight }, this.capacity), // Northeast
+            new KritzelQuadtree({ x, y: y + halfHeight, z, width: halfWidth, height: halfHeight }, this.capacity), // Southwest
+            new KritzelQuadtree({ x: x + halfWidth, y: y + halfHeight, z, width: halfWidth, height: halfHeight }, this.capacity), // Southeast
+        ];
+    }
+    /**
+     * Checks whether two bounding boxes intersect (overlap) each other.
+     * Uses axis-aligned bounding box (AABB) collision detection.
+     *
+     * @param a - The first bounding box
+     * @param b - The second bounding box
+     * @returns `true` if the bounding boxes overlap, `false` otherwise
+     */
+    intersects(a, b) {
+        return !(a.x >= b.x + b.width || // a is completely to the right of b
+            a.x + a.width <= b.x || // a is completely to the left of b
+            a.y >= b.y + b.height || // a is completely below b
+            a.y + a.height <= b.y // a is completely above b
+        );
+    }
+}

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

@@ -0,0 +1,88 @@
+/**
+ * Abstract base class for all drawing tools in Kritzel.
+ * Provides common functionality and defines the interface that all tools must implement.
+ * Tools handle user interactions (pointer events, wheel events) and can be serialized/deserialized.
+ */
+export class KritzelBaseTool {
+    /** Class name identifier used for serialization/deserialization */
+    __class__ = this.constructor.name;
+    /** Identifies the tool type for config resolution (survives minification and dual-package bundling) */
+    toolType = 'base';
+    /** Human-readable name of the tool */
+    name = 'base-tool';
+    /** Reference to the Kritzel core instance for accessing store, viewport, and other core functionality */
+    _core;
+    /**
+     * Creates a new instance of KritzelBaseTool.
+     * @param core - The KritzelCore instance that provides access to application state and functionality
+     */
+    constructor(core) {
+        this._core = core;
+        void this._core; // Avoid unused variable warning
+    }
+    /**
+     * Called when the tool becomes the active tool.
+     * Override in subclasses to perform initialization when the tool is selected.
+     */
+    onActivate() {
+        // default implementation
+    }
+    /**
+     * Called when the tool is deactivated (another tool becomes active).
+     * Override in subclasses to perform cleanup when the tool is deselected.
+     */
+    onDeactivate() {
+        // default implementation
+    }
+    /**
+     * Handles pointer down events (mouse click, touch start, pen down).
+     * Override in subclasses to implement tool-specific behavior when the user starts an interaction.
+     * @param _event - The PointerEvent containing information about the pointer (position, type, buttons, etc.)
+     */
+    handlePointerDown(_event) {
+        // default implementation
+    }
+    /**
+     * Handles pointer move events (mouse move, touch move, pen move).
+     * Override in subclasses to implement tool-specific behavior during dragging or hovering.
+     * @param _event - The PointerEvent containing information about the pointer (position, type, buttons, etc.)
+     */
+    handlePointerMove(_event) {
+        // default implementation
+    }
+    /**
+     * Handles pointer up events (mouse release, touch end, pen up).
+     * Override in subclasses to implement tool-specific behavior when the user ends an interaction.
+     * @param _event - The PointerEvent containing information about the pointer (position, type, buttons, etc.)
+     */
+    handlePointerUp(_event) {
+        // default implementation
+    }
+    /**
+     * Handles mouse wheel events for zooming or scrolling.
+     * Override in subclasses to implement tool-specific wheel behavior.
+     * @param _event - The WheelEvent containing scroll delta and modifier key information
+     */
+    handleWheel(_event) {
+        // default implementation
+    }
+    /**
+     * Serializes the tool to a plain object for persistence or transfer.
+     * @returns An object containing the tool's class name and name property
+     */
+    serialize() {
+        return {
+            __class__: this.__class__,
+            name: this.name,
+        };
+    }
+    /**
+     * Deserializes a plain object into this tool instance.
+     * @param object - The serialized tool data to restore
+     * @returns This tool instance with restored properties
+     */
+    deserialize(object) {
+        Object.assign(this, object);
+        return this;
+    }
+}

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

@@ -0,0 +1,236 @@
+import { KritzelEventHelper } from "../../helpers/event.helper";
+import { KritzelPath } from "../objects/path.class";
+import { KritzelBaseTool } from "./base-tool.class";
+import { DEFAULT_COLOR_PALETTE } from "../../constants/color-palette.constants";
+import { DEFAULT_STROKE_SIZES } from "../../constants/stroke-size.constants";
+/**
+ * Brush tool for free-hand drawing on the canvas.
+ * Creates smooth paths by tracking pointer movement and rendering stroke paths.
+ * Supports mouse, touch, and pen input with configurable color, size, and opacity.
+ */
+export class KritzelBrushTool extends KritzelBaseTool {
+    toolType = 'brush';
+    /** The color of the brush stroke (supports theme-aware light/dark colors) */
+    color = DEFAULT_COLOR_PALETTE[0];
+    /** The width of the brush stroke in pixels */
+    size = 6;
+    /** The opacity of the brush stroke (0-1) */
+    opacity = 1;
+    /** Available color palette for the brush tool */
+    palette = [...DEFAULT_COLOR_PALETTE];
+    /** Available stroke size presets for the brush tool */
+    sizes = [...DEFAULT_STROKE_SIZES];
+    /**
+     * Minimum distance in screen pixels between two consecutive stored points.
+     * Pointer-move samples closer than this to the previously stored point are
+     * dropped. This shrinks the path's `points` array (which is fully
+     * re-serialized on every Yjs update during a stroke), reducing per-stroke
+     * websocket traffic without visible quality loss — `perfect-freehand`
+     * already smooths the rendered stroke.
+     */
+    static MIN_POINT_DISTANCE_PX = 3;
+    /** Tracks the ID of the path currently being drawn */
+    _currentPathId = null;
+    /**
+     * Returns true if (x, y) is far enough from the last stored point on
+     * `currentPath` to be appended. Distance is measured in the same coordinate
+     * system the points themselves are stored in (world units when
+     * lockDrawingScale is true, screen units otherwise), with the threshold
+     * scaled by `divider` so the filter is always ~1 screen pixel.
+     *
+     * Uses squared distance to avoid a per-move `Math.sqrt`.
+     */
+    shouldAppendPoint(currentPath, x, y, divider) {
+        const points = currentPath.points;
+        if (!points || points.length === 0) {
+            return true;
+        }
+        const last = points[points.length - 1];
+        const dx = x - last[0];
+        const dy = y - last[1];
+        const threshold = KritzelBrushTool.MIN_POINT_DISTANCE_PX / divider;
+        return dx * dx + dy * dy >= threshold * threshold;
+    }
+    /**
+     * Creates a new instance of KritzelBrushTool.
+     * @param core - The KritzelCore instance that provides access to application state and functionality
+     */
+    constructor(core) {
+        super(core);
+    }
+    /**
+     * Handles pointer down events to start drawing a new path.
+     * Creates a new KritzelPath object at the pointer position and adds it to the canvas.
+     * Supports both mouse (left-click) and touch/pen input.
+     * @param event - The PointerEvent containing pointer position and input type information
+     */
+    handlePointerDown(event) {
+        if (event.cancelable) {
+            event.preventDefault();
+        }
+        if (event.pointerType === 'mouse') {
+            if (KritzelEventHelper.isLeftClick(event)) {
+                this._core.store.state.isDrawing = true;
+                const viewportScale = this._core.store.state.scale;
+                const lockScale = this._core.store.state.lockDrawingScale;
+                const divider = lockScale ? viewportScale : 1;
+                const x = (event.clientX - this._core.store.offsetX) / divider;
+                const y = (event.clientY - this._core.store.offsetY) / divider;
+                const path = KritzelPath.create(this._core, {
+                    points: [[x, y]],
+                    translateX: -this._core.store.state.translateX / divider,
+                    translateY: -this._core.store.state.translateY / divider,
+                    scale: lockScale ? 1 : viewportScale,
+                    fill: this.color,
+                    strokeWidth: this.size,
+                    opacity: this.opacity,
+                });
+                path.isCompleted = false;
+                this._currentPathId = path.id;
+                this._core.store.objects.insert(path);
+                this._core.store.objects?.setActiveDrawingObject(path.id);
+            }
+        }
+        if (event.pointerType === 'touch' || event.pointerType === 'pen') {
+            const activePointers = Array.from(this._core.store.state.pointers.values());
+            if (activePointers.length === 1) {
+                const viewportScale = this._core.store.state.scale;
+                const lockScale = this._core.store.state.lockDrawingScale;
+                const divider = lockScale ? viewportScale : 1;
+                const x = Math.round((activePointers[0].clientX - this._core.store.offsetX) / divider);
+                const y = Math.round((activePointers[0].clientY - this._core.store.offsetY) / divider);
+                this._core.store.state.isDrawing = true;
+                const path = KritzelPath.create(this._core, {
+                    points: [[x, y]],
+                    translateX: -this._core.store.state.translateX / divider,
+                    translateY: -this._core.store.state.translateY / divider,
+                    scale: lockScale ? 1 : viewportScale,
+                    fill: this.color,
+                    strokeWidth: this.size,
+                    opacity: this.opacity,
+                });
+                path.isCompleted = false;
+                this._currentPathId = path.id;
+                this._core.store.objects.insert(path);
+                this._core.store.objects?.setActiveDrawingObject(path.id);
+            }
+        }
+    }
+    /**
+     * Handles pointer move events to extend the current path while drawing.
+     * Adds new points to the current path as the pointer moves across the canvas.
+     * Only processes events when actively drawing (isDrawing state is true).
+     * @param event - The PointerEvent containing the current pointer position
+     */
+    handlePointerMove(event) {
+        if (event.cancelable) {
+            event.preventDefault();
+        }
+        if (event.pointerType === 'mouse') {
+            if (this._core.store.state.isDrawing && this._currentPathId) {
+                const currentPath = this._core.store.objects.findById(this._currentPathId);
+                if (currentPath) {
+                    const viewportScale = this._core.store.state.scale;
+                    const lockScale = this._core.store.state.lockDrawingScale;
+                    const divider = lockScale ? viewportScale : 1;
+                    const x = (event.clientX - this._core.store.offsetX) / divider;
+                    const y = (event.clientY - this._core.store.offsetY) / divider;
+                    if (!this.shouldAppendPoint(currentPath, x, y, divider)) {
+                        return;
+                    }
+                    const updatedPath = KritzelPath.create(this._core, {
+                        points: [...currentPath.points, [x, y]],
+                        translateX: -this._core.store.state.translateX / divider,
+                        translateY: -this._core.store.state.translateY / divider,
+                        scale: lockScale ? 1 : viewportScale,
+                        fill: this.color,
+                        strokeWidth: this.size,
+                        opacity: this.opacity,
+                    });
+                    updatedPath.id = currentPath.id;
+                    updatedPath.workspaceId = currentPath.workspaceId;
+                    updatedPath.zIndex = currentPath.zIndex;
+                    updatedPath.isCompleted = false;
+                    this._core.store.objects.update(updatedPath);
+                }
+            }
+        }
+        if (event.pointerType === 'touch' || event.pointerType === 'pen') {
+            const activePointers = Array.from(this._core.store.state.pointers.values());
+            if (activePointers.length === 1) {
+                if (this._currentPathId) {
+                    const currentPath = this._core.store.objects.findById(this._currentPathId);
+                    if (currentPath) {
+                        const viewportScale = this._core.store.state.scale;
+                        const lockScale = this._core.store.state.lockDrawingScale;
+                        const divider = lockScale ? viewportScale : 1;
+                        const x = Math.round((activePointers[0].clientX - this._core.store.offsetX) / divider);
+                        const y = Math.round((activePointers[0].clientY - this._core.store.offsetY) / divider);
+                        if (!this.shouldAppendPoint(currentPath, x, y, divider)) {
+                            return;
+                        }
+                        const updatedPath = KritzelPath.create(this._core, {
+                            points: [...currentPath.points, [x, y]],
+                            translateX: -this._core.store.state.translateX / divider,
+                            translateY: -this._core.store.state.translateY / divider,
+                            scale: lockScale ? 1 : viewportScale,
+                            fill: this.color,
+                            strokeWidth: this.size,
+                            opacity: this.opacity,
+                        });
+                        updatedPath.id = currentPath.id;
+                        updatedPath.workspaceId = currentPath.workspaceId;
+                        updatedPath.zIndex = currentPath.zIndex;
+                        updatedPath.isCompleted = false;
+                        this._core.store.objects.update(updatedPath);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Handles pointer up events to complete the current path.
+     * Marks the path as completed, updates the store, and emits an objects change event.
+     * Resets the drawing state and clears the current path reference.
+     * @param event - The PointerEvent indicating the end of the drawing gesture
+     */
+    handlePointerUp(event) {
+        if (event.cancelable) {
+            event.preventDefault();
+        }
+        if (event.pointerType === 'mouse') {
+            if (this._core.store.state.isDrawing) {
+                this._core.store.state.isDrawing = false;
+                if (this._currentPathId) {
+                    const currentPath = this._core.store.objects.findById(this._currentPathId);
+                    if (currentPath) {
+                        currentPath.isCompleted = true;
+                        this._core.store.objects.update(currentPath);
+                        this._core.engine.emitObjectsChange();
+                        this._core.engine.emitObjectsAdded([currentPath]);
+                    }
+                    this._core.store.objects?.setActiveDrawingObject(null);
+                    this._currentPathId = null;
+                    this._core.store.objects?.stopUndoCapturing();
+                }
+            }
+        }
+        if (event.pointerType === 'touch' || event.pointerType === 'pen') {
+            if (this._core.store.state.isDrawing) {
+                this._core.store.state.isDrawing = false;
+                if (this._currentPathId) {
+                    const currentPath = this._core.store.objects.findById(this._currentPathId);
+                    if (currentPath) {
+                        currentPath.isCompleted = true;
+                        this._core.store.objects.update(currentPath);
+                        this._core.engine.emitObjectsChange();
+                        this._core.engine.emitObjectsAdded([currentPath]);
+                    }
+                    this._core.store.objects?.setActiveDrawingObject(null);
+                    this._currentPathId = null;
+                    this._core.store.objects?.stopUndoCapturing();
+                }
+            }
+        }
+    }
+}