@kritzel/engine 0.4.31

package/dist/types/classes/core/store.class.d.ts

@@ -0,0 +1,198 @@
+import { KritzelSelectionGroup } from '../objects/selection-group.class';
+import { KritzelEngineState } from '../../interfaces/engine-state.interface';
+import { KritzelSelectionBox } from '../objects/selection-box.class';
+import { KritzelText } from '../objects/text.class';
+import { KritzelShape } from '../objects/shape.class';
+import { KritzelPath } from '../objects/path.class';
+import { KritzelLine } from '../objects/line.class';
+import { KritzelDynamicObject } from '../objects/dynamic-object.class';
+import { StateChangeListener, StatePropertyKey } from '../../types/state.types';
+import { KritzelObjectMap } from '../structures/object-map.structure';
+import { KritzelBaseObject } from '../objects/base-object.class';
+/**
+ * Central state management store for the Kritzel engine.
+ * Provides reactive state management with change listeners, caching for frequently
+ * accessed objects, and computed properties for viewport and selection state.
+ */
+export declare class KritzelStore {
+    /** Internal state object containing all engine state properties */
+    private readonly _state;
+    /** Map of property keys to their registered change listeners */
+    private readonly _listeners;
+    private _cachedSelectionBox;
+    private _cachedSelectionGroup;
+    private _selectionBoxCacheValid;
+    private _selectionGroupCacheValid;
+    private _localUserId;
+    /**
+     * Gets the current engine state.
+     * @returns The mutable engine state object
+     */
+    get state(): KritzelEngineState;
+    /**
+     *  Gets the map of all objects in the workspace.
+     *  Throws an error if the objects map is not initialized, as it is required for all object management.
+     *  @returns The KritzelObjectMap containing all objects
+     *  @throws Error if the objects map is not initialized in the state
+     */
+    get objects(): KritzelObjectMap<KritzelBaseObject<Element>>;
+    /**
+     * Gets the host element for the Kritzel editor.
+     * Throws an error if the host is not set, as it is required for many operations.
+     * @returns The host HTMLElement
+     * @throws Error if the host element is not set in the state
+     */
+    get host(): HTMLElement;
+    /**
+     * Gets the next available z-index for new objects.
+     * Calculates the maximum z-index among all non-selection objects and adds 1.
+     * @returns The next z-index value to use for new objects
+     */
+    get currentZIndex(): number;
+    /**
+     * Returns true if viewport boundaries are set to finite values (not Infinity).
+     */
+    get hasViewportBoundaries(): boolean;
+    /**
+     * Returns the viewport boundary bounds for querying objects.
+     * Uses the configured boundaries, defaulting to Infinity for unset values.
+     */
+    private get viewportBoundaryBounds();
+    /**
+     * Gets the total count of objects in the workspace.
+     * When viewport boundaries are set, returns only objects within those boundaries.
+     * @returns The total number of objects
+     */
+    get totalObjectCount(): number;
+    /**
+     * Gets all objects in the workspace.
+     * When viewport boundaries are set, returns only objects within those boundaries.
+     * @returns Array of all canvas objects
+     */
+    get allObjects(): KritzelBaseObject<Element>[];
+    /**
+     * Gets all objects currently visible in the viewport.
+     * Uses spatial querying for efficient retrieval and sorts by z-index.
+     * @returns Array of objects within the current viewport, sorted by z-index ascending
+     */
+    get objectsInViewport(): KritzelBaseObject<Element>[];
+    /**
+     * Gets all objects excluding selection-related objects (selection group and selection box).
+     * @returns Array of all regular canvas objects
+     */
+    get allNonSelectionObjects(): KritzelBaseObject<Element>[];
+    /**
+     * Gets all currently selected objects (excluding the selection group itself).
+     * @returns Array of selected objects
+     */
+    get selectedObjects(): KritzelBaseObject<Element>[];
+    /**
+     * Gets the current selection box if one exists.
+     * Uses caching for O(1) access after initial lookup.
+     * @returns The selection box or null if none exists
+     */
+    get selectionBox(): KritzelSelectionBox | null;
+    /**
+     * Gets the current local user's selection group if one exists.
+     * When a local user ID is set, returns only the selection group belonging to that user.
+     * Uses caching for O(1) access after initial lookup.
+     * @returns The local user's selection group or null if none exists
+     */
+    get selectionGroup(): KritzelSelectionGroup | null;
+    /**
+     * Invalidate cached selection objects. Call this when selection objects are inserted or removed.
+     */
+    invalidateSelectionCache(): void;
+    /**
+     * Directly set the cached selection box reference for O(1) access.
+     * Use this when creating the selection box to avoid a filter lookup.
+     * @param box - The selection box to cache, or null to clear the cache
+     */
+    setSelectionBox(box: KritzelSelectionBox | null): void;
+    /**
+     * Directly set the cached selection group reference for O(1) access.
+     * Use this when creating the selection group to avoid a filter lookup.
+     * @param group - The selection group to cache, or null to clear the cache
+     */
+    setSelectionGroup(group: KritzelSelectionGroup | null): void;
+    /**
+     * Sets the local user ID for scoping selection group lookups.
+     * When set, the selectionGroup getter returns only the group owned by this user.
+     * @param userId - The local user's ID, or null for non-collaborative mode
+     */
+    setLocalUserId(userId: string | null): void;
+    /**
+     * Gets the currently active text object being edited.
+     * @returns The text object in editing mode, or null if none
+     */
+    get activeText(): KritzelText | null;
+    /**
+     * Gets the currently active shape object being edited.
+     * @returns The shape object in editing mode, or null if none
+     */
+    get activeShape(): KritzelShape | null;
+    /**
+     * Gets the currently selected dynamic object whose focused descendant is an input-like element.
+     * @returns The interactive dynamic object with focused input-like content, or null if none matches
+     */
+    get activeInteractiveDynamicObject(): KritzelDynamicObject | null;
+    /**
+     * Gets the path currently being drawn (not yet completed).
+     * @returns The incomplete path object, or null if no path is being drawn
+     */
+    get currentPath(): KritzelPath | null;
+    /**
+     * Gets the line currently being drawn (not yet completed).
+     * @returns The incomplete line object, or null if no line is being drawn
+     */
+    get currentLine(): KritzelLine | null;
+    /**
+     * Gets the horizontal offset of the host element from the viewport.
+     * @returns The left position of the host element in client coordinates
+     */
+    get offsetX(): number;
+    /**
+     * Gets the vertical offset of the host element from the viewport.
+     * @returns The top position of the host element in client coordinates
+     */
+    get offsetY(): number;
+    /**
+     * Checks if the engine is currently disabled.
+     * The engine is disabled when not enabled, not ready, or no active workspace exists.
+     * @returns True if the engine is disabled and should not process interactions
+     */
+    get isDisabled(): boolean;
+    /**
+     * Checks if any pointer is currently down (active).
+     * @returns True if at least one pointer is currently active
+     */
+    get isPointerDown(): boolean;
+    /**
+     * Creates a new KritzelStore instance.
+     * @param state - The initial engine state configuration
+     */
+    constructor(state: KritzelEngineState);
+    /**
+     * Registers a listener for changes to a specific state property.
+     * The listener will be called whenever the property value changes.
+     * @typeParam K - The state property key type
+     * @param property - The property key to listen for changes on
+     * @param listener - The callback function to invoke on changes
+     */
+    onStateChange<K extends StatePropertyKey>(property: K, listener: StateChangeListener<KritzelEngineState[K]>): void;
+    /**
+     * Gets the current value of a state property as readonly.
+     * @typeParam K - The state property key type
+     * @param property - The property key to retrieve
+     * @returns The current value of the property
+     */
+    getState<K extends StatePropertyKey>(property: K): Readonly<KritzelEngineState[K]>;
+    /**
+     * Sets a state property value and notifies registered listeners.
+     * Only triggers listeners if the value actually changed.
+     * @typeParam K - The state property key type
+     * @param property - The property key to set
+     * @param value - The new value to assign
+     */
+    setState<K extends StatePropertyKey>(property: K, value: KritzelEngineState[K]): void;
+}

package/dist/types/classes/core/viewport.class.d.ts

@@ -0,0 +1,256 @@
+import { KritzelBaseObject } from '../objects/base-object.class';
+import { KritzelCore } from './core.class';
+import { KritzelViewportState } from '../../interfaces/viewport-state.interface';
+/**
+ * Manages viewport transformations including panning, zooming, and centering.
+ * Handles mouse, touch, and wheel events for viewport manipulation.
+ * Supports viewport boundaries and animated transitions.
+ */
+export declare class KritzelViewport {
+    /** Reference to the KritzelCore instance */
+    private readonly _core;
+    /** Debounced function to persist viewport state to workspace */
+    private readonly _debounceUpdate;
+    /** Debounced function to end scaling state after pinch gestures */
+    private readonly _debounceEndScaling;
+    /** Animation frame ID for cancellable viewport animations */
+    private _animationFrameId;
+    /** Initial distance between two touch points for pinch-to-zoom */
+    initialTouchDistance: number;
+    /** Starting X position for pan/zoom gestures */
+    startX: number;
+    /** Starting Y position for pan/zoom gestures */
+    startY: number;
+    /** Minimum movement distance (in screen pixels) before broadcasting touch cursor position */
+    private static readonly TOUCH_CURSOR_BROADCAST_THRESHOLD;
+    /** Screen X position where the current touch interaction started */
+    private _touchStartScreenX;
+    /** Screen Y position where the current touch interaction started */
+    private _touchStartScreenY;
+    /** Whether the touch movement threshold has been exceeded for cursor broadcasting */
+    private _touchCursorBroadcastActive;
+    /**
+     * Creates a new KritzelViewport instance and initializes viewport state.
+     * Sets up debounced handlers for viewport updates and scaling end events.
+     * @param core - The KritzelCore instance to manage viewport for
+     * @param host - The HTML element hosting the canvas
+     */
+    constructor(core: KritzelCore, host: HTMLElement);
+    /**
+     * Cancels any pending debounced viewport updates.
+     * Should be called before switching workspaces to prevent the old workspace's
+     * viewport state from being saved to the new workspace.
+     */
+    cancelPendingUpdates(): void;
+    /**
+     * Clamps translateX and translateY to respect viewport boundaries.
+     * Boundaries are defined in world coordinates and converted to screen-space translate limits.
+     * @param translateX - The proposed translateX value
+     * @param translateY - The proposed translateY value
+     * @returns Clamped translate values
+     */
+    private clampTranslate;
+    /**
+     * Calculates the effective minimum scale considering both the configured scaleMin
+     * and the minimum scale required to keep the viewport within boundaries.
+     * This prevents users from zooming out far enough to see past the boundaries.
+     * @returns The effective minimum scale value
+     */
+    private getEffectiveMinScale;
+    /**
+     * Handles viewport resize events.
+     * Updates the stored viewport dimensions and triggers a rerender.
+     */
+    handleResize(): void;
+    /**
+     * Handles pointer down events for initiating viewport interactions.
+     * For mouse: Right-click starts panning mode.
+     * For touch/pen: Two-finger touch initiates pinch-to-zoom.
+     * Cancels any ongoing viewport animation when user starts interacting.
+     * @param event - The pointer down event
+     */
+    handlePointerDown(event: PointerEvent): void;
+    /**
+     * Handles pointer move events for viewport panning and zooming.
+     * For mouse: Updates pointer position and handles right-click pan dragging.
+     * For touch/pen: Handles two-finger pinch-to-zoom with translation.
+     * @param event - The pointer move event
+     */
+    handlePointerMove(event: PointerEvent): void;
+    /**
+     * Handles pointer up events to end viewport interactions.
+     * For mouse: Ends panning mode on right-click release.
+     * For touch/pen: Triggers debounced end of scaling when all fingers are lifted.
+     * @param event - The pointer up event
+     */
+    handlePointerUp(event: PointerEvent): void;
+    /**
+     * Handles mouse wheel events for panning and zooming.
+     * Ctrl+wheel triggers zoom; regular wheel triggers pan.
+     * Cancels any ongoing viewport animation when user scrolls.
+     * @param event - The wheel event
+     */
+    handleWheel(event: WheelEvent): void;
+    /**
+     * Returns the current viewport state.
+     * @returns The current viewport position, scale, and dimensions.
+     */
+    getViewport(): KritzelViewportState;
+    /**
+     * Converts screen-relative pixel coordinates to world coordinates.
+     * @param x - X position in screen pixels (relative to the host element)
+     * @param y - Y position in screen pixels (relative to the host element)
+     * @returns World coordinates { x, y }
+     */
+    screenToWorld(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Converts world coordinates to screen-relative pixel coordinates.
+     * @param x - X position in world coordinates
+     * @param y - Y position in world coordinates
+     * @returns Screen coordinates { x, y } relative to the host element
+     */
+    worldToScreen(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Animates the viewport to center on the given world coordinates at the specified scale.
+     * Respects scale limits and viewport boundaries.
+     * @param x - X position in world coordinates to center on
+     * @param y - Y position in world coordinates to center on
+     * @param scale - Target scale level
+     */
+    setViewport(x: number, y: number, scale: number): void;
+    /**
+     * Animates the viewport to center on the given world coordinates without changing the scale.
+     * @param x - X position in world coordinates to center on
+     * @param y - Y position in world coordinates to center on
+     */
+    panTo(x: number, y: number): void;
+    /**
+     * Animates the viewport to the given scale level.
+     * Optionally centers on a world point; if omitted, zooms around the viewport center.
+     * @param scale - Target scale level
+     * @param worldX - Optional X position in world coordinates to center on
+     * @param worldY - Optional Y position in world coordinates to center on
+     */
+    zoomTo(scale: number, worldX?: number, worldY?: number): void;
+    /**
+     * Zooms in by a fixed step, centered on the current viewport center,
+     * with a smooth animation. The resulting scale is clamped to the allowed range.
+     * @param factor - Multiplicative zoom-in step
+     * @param duration - Animation duration in milliseconds
+     */
+    zoomIn(factor: number, duration: number): void;
+    /**
+     * Zooms out by a fixed step, centered on the current viewport center,
+     * with a smooth animation. The resulting scale is clamped to the allowed range.
+     * @param factor - Multiplicative zoom-out step
+     * @param duration - Animation duration in milliseconds
+     */
+    zoomOut(factor: number, duration: number): void;
+    /**
+     * Smoothly zooms around the viewport center, keeping the center world point
+     * fixed for the entire animation. The translation is recomputed from the fixed
+     * center point on every frame (rather than interpolated independently), which
+     * guarantees the center never drifts and the viewport does not jump.
+     * The resulting scale is clamped to the allowed range and the translation is
+     * clamped to the viewport boundaries.
+     * @param scaleFactor - Multiplicative scale factor (>1 zooms in, <1 zooms out)
+     * @param duration - Animation duration in milliseconds
+     */
+    private animateZoomAroundViewportCenter;
+    /**
+     * Applies a single zoom step that keeps the given world point anchored to the
+     * given screen point at the specified scale, clamped to the viewport boundaries.
+     */
+    private applyZoomAroundCenter;
+    /**
+     * Centers a given object in the viewport without changing the scale.
+     * The object's center point will be positioned at the viewport center.
+     * Respects viewport boundary constraints.
+     * @param object - The object to center in the viewport
+     */
+    centerInViewport(object: KritzelBaseObject): void;
+    /**
+     * Centers and scales the viewport to fit a given object with 10% padding.
+     * Calculates the optimal scale to show the entire object while respecting
+     * scale limits and viewport boundaries.
+     * @param object - The object to fit in the viewport
+     */
+    centerFitInViewport(object: KritzelBaseObject): void;
+    /**
+     * Centers the viewport on a given object and zooms out only if the object
+     * does not fit at the current scale. Never zooms in — if the object already
+     * fits, the scale is left unchanged.
+     * @param object - The object to fit in the viewport
+     */
+    centerFitInViewportIfNeeded(object: KritzelBaseObject): void;
+    /**
+     * Zooms out and centers the viewport on a given object only if the object
+     * does not fit at the current scale. If the object already fits, the
+     * viewport is left completely unchanged.
+     * @param object - The object to check and fit in the viewport
+     */
+    fitInViewportIfNeeded(object: KritzelBaseObject): void;
+    /**
+     * Smoothly brings a given object into view if it is not fully visible within
+     * the current viewport. Zooms out only if the object is too large to fit at
+     * the current scale; never zooms in. If the object is already fully visible,
+     * the viewport is left unchanged.
+     * @param object - The object to bring into view
+     */
+    bringIntoViewIfNeeded(object: KritzelBaseObject): void;
+    /**
+     * Handles zoom operations triggered by wheel events with Ctrl key.
+     * Zooms around the cursor position, respecting scale limits.
+     * Also handles horizontal pan from trackpad pinch+drag gestures.
+     * @param event - The wheel event with Ctrl modifier
+     */
+    private handleZoom;
+    /**
+     * Handles pan operations triggered by wheel events (without Ctrl).
+     * Applies a pan speed multiplier and clamps to viewport boundaries.
+     * @param event - The wheel event without Ctrl modifier
+     */
+    private handlePan;
+    /**
+     * Cancels any ongoing viewport animation.
+     * Called when user interacts with the canvas during animation.
+     */
+    cancelViewportAnimation(): void;
+    /**
+     * Animates the viewport to the specified position and scale.
+     * @param targetTranslateX - Target X translation
+     * @param targetTranslateY - Target Y translation
+     * @param targetScale - Target scale
+     * @param duration - Animation duration in milliseconds (default 150)
+     */
+    animateViewportTo(targetTranslateX: number, targetTranslateY: number, targetScale: number, duration?: number): void;
+    /**
+     * Centers and fits the nearest content objects in the viewport.
+     * Finds up to maxObjects closest objects to the current viewport center
+     * and animates the viewport to show them.
+     * @param maxObjects - Maximum number of objects to consider (default 20)
+     * @returns true if content was found and viewport is animating, false if no content exists
+     */
+    centerFitNearestContent(maxObjects?: number): boolean;
+    /**
+     * Centers and fits the provided objects in the viewport.
+     * Calculates the combined bounding box of the provided objects and optionally animates the viewport to show them.
+     * @param objects - Objects to include in the fit operation.
+     * @param animate - Whether to animate the viewport transition (default: true)
+     * @returns true if at least one object was provided and viewport was adjusted, false otherwise
+     */
+    centerFitObjects<T extends Element>(objects: KritzelBaseObject<T>[], animate?: boolean): boolean;
+    /**
+     * Centers and fits ALL objects in the viewport, including objects not currently rendered.
+     * Calculates the combined bounding box of all objects and optionally animates the viewport to show them.
+     * @param animate - Whether to animate the viewport transition (default: true)
+     * @returns true if objects were found and viewport was adjusted, false if no objects exist
+     */
+    centerFitAllObjects(animate?: boolean): boolean;
+}

package/dist/types/classes/core/workspace.class.d.ts

@@ -0,0 +1,95 @@
+import { KritzelSerializable } from "../../interfaces/serializable.interface";
+import type { KritzelCore } from "./core.class";
+import type { KritzelBaseObject } from "../objects/base-object.class";
+/** Current version of the workspace export format */
+export declare const WORKSPACE_EXPORT_VERSION = "1.3.0";
+/**
+ * Configuration options for creating a KritzelWorkspace instance.
+ */
+export interface KritzelWorkspaceConfig {
+    /** Unique identifier for the workspace. Auto-generated if omitted. */
+    id?: string;
+    /** Display name of the workspace. Defaults to 'New Workspace' if omitted. */
+    name?: string;
+    /** Initial viewport configuration containing world-space center coordinates and scale */
+    viewport?: {
+        centerWorldX?: number;
+        centerWorldY?: number;
+        scale?: number;
+    };
+    /**
+     * Canvas objects for this workspace. Seeded on first initialization, and treated as the
+     * desired object set by `updateWorkspace()`. Omit to leave existing objects untouched.
+     */
+    objects?: KritzelBaseObject<any>[];
+}
+/**
+ * Represents a workspace in the Kritzel canvas.
+ * A workspace is an isolated canvas area with its own set of objects and viewport state.
+ * It can be serialized and deserialized for persistence and collaborative editing.
+ */
+export declare class KritzelWorkspace implements KritzelSerializable {
+    __class__: string;
+    /** Unique identifier for the workspace */
+    id: string;
+    /** Display name of the workspace */
+    name: string;
+    /** Timestamp when the workspace was created */
+    createdAt: Date;
+    /** Timestamp when the workspace was last updated */
+    updatedAt: Date;
+    /** Viewport state containing the world-space center point and zoom level */
+    viewport: {
+        centerWorldX: number;
+        centerWorldY: number;
+        scale: number;
+    };
+    /**
+     * Desired canvas objects. Seeded when the workspace is first initialized and applied as the
+     * full desired set by `updateWorkspace()`: `undefined` leaves objects untouched, `[]` removes all.
+     */
+    objects?: KritzelBaseObject<any>[];
+    /** Whether the workspace is publicly accessible via a share link */
+    isPublic: boolean;
+    /** Reference to the KritzelCore instance managing this workspace */
+    _core: KritzelCore;
+    /**
+     * Creates a new KritzelWorkspace instance.
+     * @param config - Configuration options object for the workspace
+     */
+    constructor(config?: KritzelWorkspaceConfig);
+    /**
+     * Factory method to create a workspace with a core reference.
+     * @param core - The KritzelCore instance to associate with this workspace
+     * @param obj - Object containing workspace properties (id, name, viewport)
+     * @returns A new KritzelWorkspace instance with the core reference set
+     */
+    static create(core: KritzelCore, obj: any): KritzelWorkspace;
+    /**
+     * Adds an object to this workspace via the core engine.
+     * @param obj - The object to add to the workspace
+     */
+    addObject(obj: any): void;
+    /**
+     * Serializes the workspace to a plain object for storage or transmission.
+     * Converts dates to ISO strings and includes the class identifier.
+     * @param options - Optional settings for serialization
+     * @param options.includeObjects - If true, includes all canvas objects in the serialized output
+     * @returns A plain object representation of the workspace
+     */
+    serialize(options?: {
+        includeObjects?: boolean;
+    }): Record<string, unknown>;
+    /**
+     * Creates a shallow clone of this workspace, preserving the prototype chain.
+     * Useful when Stencil needs a new object reference to detect property changes.
+     */
+    clone(): KritzelWorkspace;
+    /**
+     * Deserializes a plain object into this workspace instance.
+     * Converts ISO string dates back to Date objects.
+     * @param object - The plain object to deserialize from
+     * @returns This workspace instance with updated properties
+     */
+    deserialize(object: any): KritzelSerializable;
+}

package/dist/types/classes/handlers/base.handler.d.ts

@@ -0,0 +1,18 @@
+import { KritzelCore } from '../core/core.class';
+/**
+ * Abstract base class for all Kritzel event handlers.
+ * Provides a common foundation with access to the core instance for derived handler classes
+ * such as key handlers, hover handlers, and context menu handlers.
+ */
+export declare class KritzelBaseHandler {
+    /**
+     * Reference to the KritzelCore instance.
+     * Provides access to canvas state, store, and operations for derived handlers.
+     */
+    protected readonly _core: KritzelCore;
+    /**
+     * Creates a new instance of the base handler.
+     * @param core - The KritzelCore instance that provides access to canvas state and operations.
+     */
+    constructor(core: KritzelCore);
+}

package/dist/types/classes/handlers/context-menu.handler.d.ts

@@ -0,0 +1,67 @@
+import { KritzelBaseHandler } from './base.handler';
+import { KritzelCore } from '../core/core.class';
+/**
+ * Handles context menu interactions on the Kritzel canvas.
+ * Manages the display and positioning of context menus, selecting appropriate menu items
+ * based on whether an object is targeted or the canvas background is right-clicked.
+ */
+export declare class KritzelContextMenuHandler extends KritzelBaseHandler {
+    /**
+     * Menu items to display when the context menu is opened on the canvas background
+     * (i.e., when no object is selected).
+     */
+    globalContextMenuItems: any[];
+    /**
+     * Menu items to display when the context menu is opened on a selected object.
+     */
+    objectContextMenuItems: any[];
+    /**
+     * Creates a new instance of the context menu handler.
+     * @param core - The KritzelCore instance that provides access to canvas state and operations.
+     * @param globalContextMenuItems - Array of menu items to show for canvas-level context menus.
+     * @param objectContextMenuItems - Array of menu items to show when right-clicking on objects.
+     */
+    constructor(core: KritzelCore, globalContextMenuItems: any[], objectContextMenuItems: any[]);
+    /**
+     * Resolves the active context menu items for display, translating each item's
+     * `label` through the current locale. When the label is a known
+     * {@link KritzelTermKey} the translation is used; any other string is passed
+     * through unchanged. Runs at menu-open time so the labels reflect the locale
+     * active at that moment.
+     * @returns A new array of items with resolved labels.
+     */
+    private resolveLabels;
+    /**
+     * Gets the active context menu items (object or global) with localized labels.
+     */
+    private getResolvedContextMenuItems;
+    /**
+     * Handles the context menu event (typically triggered by right-click).
+     * This method performs the following operations:
+     * 1. Validates that the selection tool is active; exits early otherwise.
+     * 2. Checks and resets the `skipContextMenu` flag if set.
+     * 3. Cancels any pending drag operation on the selection tool.
+     * 4. Clears any active selection box if present.
+     * 5. If an object is clicked, creates a new selection group containing that object.
+     * 6. Determines which menu items to display (object or global context menu).
+     * 7. Calculates the menu position, ensuring it stays within viewport bounds.
+     * 8. Updates the store state to show the context menu and disables canvas interactions.
+     * @param event - The pointer event containing the click coordinates and target information.
+     * @returns void - This method does not return a value; it updates state and triggers a rerender.
+     */
+    handleContextMenu(event: PointerEvent): void;
+    /**
+     * Programmatically opens the context menu at a specified world-coordinate position.
+     * If an objectId is provided and found, the object context menu is shown for that object.
+     * If no objectId is provided but a selection group exists, the object context menu is shown.
+     * Otherwise, the global context menu is shown.
+     * @param options.x - The X position in world (canvas) coordinates.
+     * @param options.y - The Y position in world (canvas) coordinates.
+     * @param options.objectId - Optional ID of an object to select and show the object context menu for.
+     */
+    open(options: {
+        x: number;
+        y: number;
+        objectId?: string;
+    }): void;
+}

package/dist/types/classes/handlers/hover.handler.d.ts

@@ -0,0 +1,23 @@
+import { KritzelCore } from '../core/core.class';
+import { KritzelBaseHandler } from './base.handler';
+/**
+ * Handles hover interactions on the Kritzel canvas.
+ * Detects when the pointer moves over canvas objects and updates their hover state accordingly.
+ * Currently only processes mouse input, with placeholder support for touch and pen devices.
+ */
+export declare class KritzelHoverHandler extends KritzelBaseHandler {
+    /**
+     * Creates a new instance of the hover handler.
+     * @param core - The KritzelCore instance that provides access to canvas state and object detection.
+     */
+    constructor(core: KritzelCore);
+    /**
+     * Handles pointer move events to detect and update object hover states.
+     * For mouse input, performs a hit test on the object under the pointer and updates
+     * its `isHovered` property based on whether the pointer coordinates intersect with the object.
+     * Touch and pen input types are recognized but not yet implemented.
+     * @param event - The pointer event containing information about the pointer type and position.
+     * @returns void - This method does not return a value; it updates object state as a side effect.
+     */
+    handlePointerMove(event: PointerEvent): void;
+}