@kritzel/engine 0.4.31

package/dist/types/classes/registries/tool.registry.d.ts

@@ -0,0 +1,53 @@
+import { KritzelCore } from "../core/core.class";
+import { KritzelBaseTool } from "../tools/base-tool.class";
+/**
+ * A per-engine registry for managing drawing tools in the Kritzel library.
+ * Each `KritzelCore` owns its own `KritzelToolRegistry` instance so that
+ * multiple editors on the same page do not share tool instances or configs.
+ *
+ * Tools are instantiated and stored by name, allowing retrieval by name or index.
+ */
+export declare class KritzelToolRegistry {
+    private readonly core;
+    /** Internal storage for registered tools, mapping tool names to their instances. */
+    private registry;
+    /**
+     * Creates a new tool registry bound to a specific `KritzelCore` instance.
+     * The bound core is used as the constructor argument when registering new tools.
+     *
+     * @param core - The `KritzelCore` instance this registry is bound to.
+     */
+    constructor(core: KritzelCore);
+    /**
+     * Registers a new tool by instantiating it with the registry's bound core.
+     * The tool is stored in the registry under the specified name.
+     *
+     * @param toolName - The unique identifier for the tool.
+     * @param constructor - The tool class constructor that extends `KritzelBaseTool`.
+     * @returns The newly created and registered tool instance.
+     */
+    registerTool(toolName: string, constructor: new (core: KritzelCore) => KritzelBaseTool): KritzelBaseTool;
+    /**
+     * Checks if a tool with the given name is registered.
+     *
+     * @param toolName - The unique identifier of the tool to check.
+     * @returns `true` if the tool is registered, `false` otherwise.
+     */
+    hasTool(toolName: string): boolean;
+    /**
+     * Retrieves a registered tool by its name.
+     * Logs a warning if the tool is not found.
+     *
+     * @param toolName - The unique identifier of the tool to retrieve.
+     * @returns The tool instance if found, or `null` if not registered.
+     */
+    getTool(toolName: string): KritzelBaseTool | null;
+    /**
+     * Retrieves a registered tool by its index in the registry.
+     * The index is based on the order tools were registered.
+     *
+     * @param index - The zero-based index of the tool in the registry.
+     * @returns The tool instance at the specified index, or `null` if the index is out of bounds.
+     */
+    getToolByIndex(index: number): KritzelBaseTool | null;
+}

package/dist/types/classes/structures/app-state-map.structure.d.ts

@@ -0,0 +1,171 @@
+import { KritzelWorkspace } from '../core/workspace.class';
+import type { KritzelCore } from '../core/core.class';
+import { KritzelSyncConfig } from '../../interfaces/sync-config.interface';
+import { KritzelDocumentType } from '../../interfaces/document-metadata.interface';
+/**
+ * Manages the application state for workspaces with Yjs-based synchronization support.
+ * This class provides a synchronized map of workspaces that can be shared across
+ * multiple clients using configurable sync providers (e.g., WebSocket, WebRTC).
+ */
+export declare class KritzelAppStateMap {
+    private map;
+    private _ydoc;
+    private _workspacesMap;
+    private _metadataMap;
+    private _providers;
+    private _core;
+    private _isReady;
+    private _onRemoteChangeCallback;
+    private _workspacesObserver;
+    private _networkSyncPromise;
+    /**
+     * Indicates whether the app state map has been initialized and is ready for use.
+     * @returns True if initialized and all providers are connected, false otherwise.
+     */
+    get isReady(): boolean;
+    /**
+     * Settles when network providers finish their initial sync (or fail/time out).
+     * Resolves immediately when no network providers are configured.
+     */
+    whenNetworkSynced(): Promise<void>;
+    /**
+     * Indicates whether any configured sync provider replicates over the network.
+     * Used by the engine to warn when a matching remote asset storage
+     * provider is missing (images would otherwise only exist locally).
+     */
+    get hasNetworkSyncProvider(): boolean;
+    /**
+     * Creates a new KritzelAppStateMap instance with an empty workspace map.
+     */
+    constructor();
+    /**
+     * Registers a callback function to be invoked when remote changes are received.
+     * This allows external code to react to workspace changes from other clients.
+     * @param callback - The function to call when remote changes occur.
+     */
+    onRemoteChange(callback: () => void): void;
+    /**
+     * Initializes the app state map with Yjs synchronization.
+     * Creates a dedicated Y.Doc for app state, sets up workspace observation,
+     * instantiates and connects all configured sync providers, and loads existing workspaces.
+     * @param core - The KritzelCore instance for triggering re-renders and accessing the store.
+     * @param config - Optional sync configuration specifying providers. Defaults to DEFAULT_SYNC_CONFIG.
+     * @returns A promise that resolves when all providers are connected and the state is loaded.
+     */
+    initialize(core: KritzelCore, config?: KritzelSyncConfig): Promise<void>;
+    /**
+     * Resolves a stable instance identifier for the app-state document.
+     * The id is persisted in localStorage and reused across remounts/reloads.
+     * @param core - The core instance used to namespace the storage key by editorId.
+     * @returns A stable instance identifier.
+     * @throws Error when localStorage is unavailable or inaccessible.
+     */
+    private getOrCreateAppStateInstanceId;
+    /**
+     * Handles changes to the Yjs workspaces map.
+     * For local changes, only triggers a re-render. For remote changes, synchronizes
+     * the local map with the Yjs state by adding, updating, or deleting workspaces.
+     * @param event - The Yjs map event containing information about changed keys.
+     */
+    private handleWorkspacesChange;
+    /**
+     * Reconstructs a KritzelWorkspace instance from its serialized form.
+     * Restores all properties including id, name, viewport, and timestamps.
+     * Handles both legacy { translateX, translateY } and new { centerWorldX, centerWorldY } viewport formats.
+     * @param serialized - The serialized workspace data object.
+     * @returns A fully reconstructed KritzelWorkspace instance.
+     */
+    private reviveWorkspace;
+    /**
+     * Initializes document metadata if not already set.
+     * Uses 'metadata' transaction origin to avoid triggering remote sync callbacks for local state.
+     */
+    private initializeMetadata;
+    /**
+     * Returns whether the document is publicly accessible.
+     */
+    getIsPublic(): boolean;
+    /**
+     * Sets whether the document is publicly accessible.
+     * This change is synced to all connected clients and the server.
+     */
+    setIsPublic(isPublic: boolean): void;
+    /**
+     * Returns the document type stored in metadata.
+     */
+    getDocumentType(): KritzelDocumentType;
+    /**
+     * Executes a callback within a Yjs transaction marked as 'local'.
+     * This allows batching multiple Yjs operations and identifying them as local changes.
+     * @param callback - The function containing Yjs operations to execute within the transaction.
+     */
+    transaction(callback: () => void): void;
+    /**
+     * Loads all workspaces from the Yjs map into the local map.
+     * Clears the existing local map and repopulates it by reviving each serialized workspace.
+     * This is typically called during initialization or when a full sync is needed.
+     */
+    loadFromYjs(): void;
+    /**
+     * Resets the app state by clearing both the local map and the Yjs workspaces map.
+     * This operation is performed within a local transaction to avoid triggering remote sync callbacks.
+     */
+    reset(): void;
+    /**
+     * Inserts a new workspace into both the local map and the Yjs map.
+     * The workspace is serialized before being stored in Yjs for synchronization.
+     * @param workspace - The workspace to insert.
+     * @returns True if the workspace was successfully inserted, false if it has no id.
+     */
+    insert(workspace: KritzelWorkspace): boolean;
+    /**
+     * Updates an existing workspace in both the local map and the Yjs map.
+     * The workspace must already exist in the map to be updated.
+     * @param workspace - The workspace with updated data.
+     * @returns True if the workspace was successfully updated, false if it doesn't exist or has no id.
+     */
+    update(workspace: KritzelWorkspace): boolean;
+    /**
+     * Removes a workspace matching the given predicate from both the local map and the Yjs map.
+     * Only the first matching workspace will be removed.
+     * @param predicate - A function that returns true for the workspace to remove.
+     * @returns True if a matching workspace was found and removed, false otherwise.
+     */
+    remove(predicate: (workspace: KritzelWorkspace) => boolean): boolean;
+    /**
+     * Retrieves a workspace by its unique identifier.
+     * @param id - The unique identifier of the workspace to retrieve.
+     * @returns The workspace if found, undefined otherwise.
+     */
+    get(id: string): KritzelWorkspace | undefined;
+    /**
+     * Returns all workspaces currently stored in the map.
+     * @returns An array containing all workspaces.
+     */
+    allWorkspaces(): KritzelWorkspace[];
+    /**
+     * Filters workspaces based on a predicate function.
+     * @param predicate - A function that returns true for workspaces to include.
+     * @returns An array of workspaces that match the predicate.
+     */
+    filter(predicate: (workspace: KritzelWorkspace) => boolean): KritzelWorkspace[];
+    /**
+     * Finds the first workspace matching the given predicate.
+     * @param predicate - A function that returns true for the workspace to find.
+     * @returns The first matching workspace, or undefined if no match is found.
+     */
+    find(predicate: (workspace: KritzelWorkspace) => boolean): KritzelWorkspace | undefined;
+    /**
+     * Checks if a workspace with the given id exists in the map.
+     * @param id - The unique identifier of the workspace to check.
+     * @returns True if a workspace with the given id exists, false otherwise.
+     */
+    has(id: string): boolean;
+    /**
+     * Destroys the app state map and releases all resources.
+     * Unobserves the Yjs workspaces map, disconnects and destroys all sync providers,
+     * clears all maps, destroys the Y.Doc, and resets all internal references.
+     * This should be called when the app state map is no longer needed.
+     */
+    destroy(): void;
+}

package/dist/types/classes/structures/object-map.structure.d.ts

@@ -0,0 +1,403 @@
+import * as Y from 'yjs';
+import { Awareness } from 'y-protocols/awareness';
+import { KritzelBaseObject } from '../objects/base-object.class';
+import type { KritzelCore } from '../core/core.class';
+import { KritzelSyncConfig } from '../../interfaces/sync-config.interface';
+import { KritzelUndoState } from '../../interfaces/undo-state.interface';
+import { KritzelDocumentType } from '../../interfaces/document-metadata.interface';
+import { IKritzelUser } from '../../interfaces/user.interface';
+/**
+ * A synchronized object map that stores and manages drawable objects on the canvas.
+ * This structure integrates with Yjs for real-time collaboration and persistence,
+ * uses a quadtree for efficient spatial queries, and provides undo/redo functionality.
+ *
+ * @template T - The type of objects stored, must extend KritzelBaseObject
+ */
+export declare class KritzelObjectMap<T extends KritzelBaseObject<any>> {
+    private quadtree;
+    private _ydoc;
+    private _objectsMap;
+    private _metadataMap;
+    private _providers;
+    private _undoManager;
+    private _reviver;
+    private _core;
+    private _workspaceId;
+    private _isReady;
+    private _temporaryItemsCount;
+    private _idMap;
+    private _awareness;
+    private _networkSyncPromise;
+    /** When true this map is a background worker: it never renders, emits, or wires awareness. */
+    private _headless;
+    private _objectsObserver;
+    private _stackItemAddedHandler;
+    private _stackItemPoppedHandler;
+    private _awarenessChangeHandler;
+    private _awarenessChangeCallbacks;
+    private _objectsChangeCallbacks;
+    private _lastAwarenessEmitTime;
+    private _awarenessEmitTimeout;
+    private readonly AWARENESS_THROTTLE_INTERVAL;
+    /**
+     * When true, update() only modifies local state (quadtree + idMap)
+     * without writing to Yjs. Used during drag operations to avoid
+     * redundant full serializations of every child object per frame.
+     */
+    private _localOnlyMode;
+    /**
+     * Tracks whether we're currently executing inside a `transaction()`
+     * callback. While true, `markUndoBoundary()` is a no-op so nested
+     * insert/remove calls don't split the in-progress undo step.
+     */
+    private _inTransaction;
+    /**
+     * Indicates whether the object map has been initialized and is ready for use.
+     * @returns `true` if providers are connected and the map is operational
+     */
+    get isReady(): boolean;
+    /**
+     * Promise that settles when network providers finish connecting.
+     * Resolves immediately if no network providers. Awaited by the loading overlay.
+     */
+    whenNetworkSynced(): Promise<void>;
+    /**
+     * Whether this map runs detached from the rendered canvas.
+     */
+    get isHeadless(): boolean;
+    /**
+     * Returns the Yjs Awareness instance, if a network provider is available.
+     */
+    get awareness(): Awareness | null;
+    /**
+     * Whether a network awareness instance is available.
+     */
+    get hasAwareness(): boolean;
+    /**
+     * Returns the local client ID from the awareness instance.
+     * Used to filter out the local user when rendering remote cursors.
+     */
+    get localClientId(): number | null;
+    /**
+     * Sets the local user identity in the awareness state.
+     * This broadcasts the user's identity to all connected peers.
+     */
+    setLocalUser(user?: IKritzelUser): void;
+    private generateColorFromName;
+    /**
+     * Updates the local cursor position in the awareness state.
+     * This broadcasts the cursor position to all connected peers.
+     */
+    updateCursorPosition(x: number, y: number): void;
+    /**
+     * Clears the local cursor position (e.g., when the pointer leaves the canvas).
+     */
+    clearCursorPosition(): void;
+    /**
+     * Sets the ID of the object currently being drawn by the local user.
+     * Remote clients use this to derive cursor position from the object's latest
+     * coordinates instead of the throttled awareness cursor, reducing desync.
+     * Pass `null` when drawing ends.
+     */
+    setActiveDrawingObject(objectId: string | null): void;
+    /**
+     * Broadcasts the local user's selection box bounds via awareness.
+     * Remote clients use this to render the selection rectangle in the user's color.
+     */
+    setLocalSelectionBox(box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): void;
+    /**
+     * Clears the local selection box from awareness (e.g., when selection completes or is cancelled).
+     */
+    clearLocalSelectionBox(): void;
+    /**
+     * Removes selection groups whose owner is no longer present in awareness.
+     * Called when remote clients disconnect to prevent orphaned selection groups
+     * from persisting in the workspace state.
+     */
+    removeOrphanedSelectionGroups(): void;
+    /** Rerenders the canvas unless this map is running headless. */
+    private requestRerender;
+    /**
+     * Registers a callback to be invoked when the awareness state changes.
+     * The callback receives the full awareness states map.
+     */
+    onAwarenessChange(callback: (states: Map<number, Record<string, any>>) => void): () => void;
+    /**
+     * Registers a callback to be invoked when remote object changes are received.
+     * Used by the awareness cursors component to re-derive cursor positions
+     * from the latest object data when a remote user is actively drawing.
+     */
+    onObjectsChange(callback: () => void): () => void;
+    /**
+     * Returns the Yjs UndoManager instance for managing undo/redo operations.
+     * @returns The UndoManager instance, or `null` if not initialized
+     */
+    get undoManager(): Y.UndoManager | null;
+    /**
+     * Returns the unique identifier of the workspace this object map belongs to.
+     * @returns The workspace ID, or `null` if not initialized
+     */
+    get workspaceId(): string | null;
+    /**
+     * Returns the current state of the undo/redo system.
+     * @returns An object containing undo/redo availability and stack sizes
+     */
+    get undoState(): KritzelUndoState;
+    /**
+     * Returns the total number of objects stored in the map.
+     * @returns The count of all objects in the quadtree
+     */
+    get totalCount(): number;
+    /**
+     * Retrieves an object from the map by its ID in O(1) time.
+     * @param id - The ID of the object to find
+     * @returns The object if found, or undefined
+     */
+    findById(id: string): T | undefined;
+    /**
+     * Creates a new KritzelObjectMap instance with an empty quadtree.
+     * The map must be initialized with `initialize()` before use.
+     */
+    constructor();
+    /**
+     * Initializes the object map with Yjs document, sync providers, and undo manager.
+     * This must be called before using any other methods on the object map.
+     *
+     * @param core - The KritzelCore instance that owns this object map
+     * @param workspaceId - A unique identifier for the workspace, used to namespace the Yjs document
+     * @param config - Optional sync configuration; defaults to DEFAULT_SYNC_CONFIG if not provided
+     * @param options - Optional behavior flags
+     * @param options.headless - Run detached from the rendered canvas (no rerenders, events, or awareness)
+     * @param options.workspaceName - Workspace name to write into document metadata; defaults to the active workspace's name
+     * @returns A promise that resolves when all providers are connected and the map is ready
+     */
+    initialize(core: KritzelCore, workspaceId: string, config?: KritzelSyncConfig, options?: {
+        headless?: boolean;
+        workspaceName?: string;
+    }): Promise<void>;
+    /**
+     * Handles changes to the Yjs objects map, synchronizing remote changes with local state.
+     * For local changes, only triggers a re-render. For remote changes, deserializes objects
+     * and updates the quadtree, handling SelectionGroups specially to maintain correct dimensions.
+     *
+     * @param event - The Yjs map event containing information about changed keys and their actions
+     */
+    private handleObjectsChange;
+    /**
+     * Initializes document metadata if not already set.
+     * Uses 'metadata' transaction origin which is NOT tracked by the UndoManager.
+     */
+    private initializeMetadata;
+    /**
+     * Returns whether the document is publicly accessible.
+     */
+    getIsPublic(): boolean;
+    /**
+     * Sets whether the document is publicly accessible.
+     * This change is synced to all connected clients and the server,
+     * but is NOT tracked by the UndoManager.
+     */
+    setIsPublic(isPublic: boolean): void;
+    /**
+     * Returns the document type stored in metadata.
+     */
+    getDocumentType(): KritzelDocumentType;
+    /**
+     * Returns the workspace name stored in metadata.
+     */
+    getWorkspaceName(): string;
+    /**
+     * Sets the workspace name in metadata.
+     * This change is synced to all connected clients and the server,
+     * but is NOT tracked by the UndoManager.
+     */
+    setWorkspaceName(name: string): void;
+    /**
+     * Returns the workspace ID stored in metadata.
+     */
+    getMetadataWorkspaceId(): string;
+    /**
+       * Executes a callback within a Yjs transaction, grouping multiple operations
+       * into a single undo step. All changes made within the callback will be
+       * tracked as a single 'local' origin transaction.
+       *
+       * @param callback - The function containing operations to execute within the transaction
+       */
+    transaction(callback: () => void): void;
+    /**
+     * Closes the current undo stack item so the next tracked change starts
+     * a new one. Call at gesture/stroke boundaries (e.g. drag/resize/rotate
+     * end, brush/line/shape stroke end).
+     *
+     * No-op while a transaction() is open.
+     */
+    stopUndoCapturing(): void;
+    /**
+     * Internal: closes the current undo stack item. No-op while inside a
+     * transaction() so wrapped multi-op work stays a single undo step.
+     */
+    private markUndoBoundary;
+    /**
+     * Executes a callback where all update() calls only modify local state
+     * (quadtree + idMap) without writing to Yjs. This avoids expensive full
+     * serializations during continuous operations like dragging many objects.
+     *
+     * Objects updated inside this callback must be persisted later
+     * (e.g., via a normal update() call at drag end).
+     *
+     * @param callback - The function containing operations to execute locally
+     */
+    withLocalUpdatesOnly(callback: () => void): void;
+    /**
+     * Loads all objects from the Yjs objects map into the local quadtree.
+     * Clears the existing quadtree and repopulates it by deserializing each
+     * object stored in the Yjs map.
+     */
+    loadFromYjs(): void;
+    /**
+     * Resets the object map by clearing both the local quadtree and the Yjs objects map.
+     * This removes all objects from the workspace. The operation is tracked as a 'local'
+     * transaction for undo/redo purposes.
+     */
+    reset(): void;
+    /**
+     * Inserts a new object into both the local quadtree and the Yjs objects map.
+     * The object must have a valid ID. Non-persistable objects (like SelectionBox)
+     * are only added to the quadtree, not to Yjs.
+     *
+     * @param object - The object to insert; must have a valid `id` property
+     * @returns `true` if the object was successfully inserted, `false` if the object has no ID
+     */
+    insert(object: T): boolean;
+    /**
+     * Updates an existing object in both the local quadtree and the Yjs objects map.
+     * The object must already exist in the map. Supports temporary updates that can
+     * be consolidated later (e.g., for incremental text input).
+     *
+     * @param object - The object with updated properties; must have a valid `id` that exists in the map
+     * @param options - Optional settings for the update operation
+     * @param options.temporary - If `true`, marks this as a temporary change that can be consolidated
+     *                            with other temporary changes into a single undo step
+     * @returns `true` if the object was successfully updated, `false` if the object doesn't exist or has no ID
+     */
+    update(object: T, options?: {
+        temporary?: boolean;
+        skipReindex?: boolean;
+    }): boolean;
+    /**
+     * Removes objects matching the given predicate from both the quadtree and Yjs map.
+     * Each removal is tracked as a separate 'local' transaction for undo/redo.
+     *
+     * @param predicate - A function that returns `true` for objects that should be removed
+     */
+    remove(predicate: (object: T) => boolean): void;
+    /**
+     * Filters objects in the quadtree based on a predicate function.
+     *
+     * @param predicate - A function that returns `true` for objects to include in the result
+     * @returns An array of objects that match the predicate
+     */
+    filter(predicate: (object: T) => boolean): T[];
+    /**
+     * Returns all objects stored in the quadtree.
+     *
+     * @returns An array containing all objects in the map
+     */
+    allObjects(): T[];
+    /**
+     * Queries the quadtree for objects within or intersecting a given 3D range.
+     * This is an efficient spatial query that avoids iterating over all objects.
+     *
+     * @param range - The bounding box to query
+     * @param range.x - The x-coordinate of the range's origin
+     * @param range.y - The y-coordinate of the range's origin
+     * @param range.z - The z-coordinate (layer) of the range's origin
+     * @param range.width - The width of the range
+     * @param range.height - The height of the range
+     * @param range.depth - Optional depth for 3D queries
+     * @returns An array of objects within or intersecting the specified range
+     */
+    query(range: {
+        x: number;
+        y: number;
+        z: number;
+        width: number;
+        height: number;
+        depth?: number;
+    }): T[];
+    /**
+     * Determines whether an object should be persisted to the Yjs document.
+     * Certain objects like SelectionBox are transient and should not be synced.
+     *
+     * @param object - The object to check for persistability
+     * @returns `true` if the object should be persisted, `false` otherwise
+     */
+    private isPersistable;
+    /**
+     * Undoes the last operation if possible.
+     * Reverts the most recent change in the undo stack and emits an objects change event.
+     */
+    undo(): void;
+    /**
+     * Redoes the last undone operation if possible.
+     * Reapplies the most recent change from the redo stack and emits an objects change event.
+     */
+    redo(): void;
+    /**
+     * Checks whether an undo operation is available.
+     *
+     * @returns `true` if there are operations in the undo stack, `false` otherwise
+     */
+    canUndo(): boolean;
+    /**
+     * Checks whether a redo operation is available.
+     *
+     * @returns `true` if there are operations in the redo stack, `false` otherwise
+     */
+    canRedo(): boolean;
+    /**
+     * Clears all undo and redo history.
+     * After calling this, no undo or redo operations will be available.
+     * Also resets the temporary items counter.
+     */
+    clearHistory(): void;
+    /**
+     * Consolidates all temporary items in the undo stack into a single undo item.
+     * This is useful when you want to merge multiple incremental changes (e.g., individual
+     * keystrokes during text editing) into a single undoable action.
+     *
+     * The method works by undoing all temporary items and then redoing them within
+     * a single 'local' transaction, effectively merging them into one undo step.
+     * After consolidation, the temporary items counter is reset to zero.
+     *
+     * @example
+     * // After multiple temporary text updates
+     * objectMap.update(textObject, { temporary: true }); // keystroke 1
+     * objectMap.update(textObject, { temporary: true }); // keystroke 2
+     * objectMap.consolidateTemporaryItems(); // merge into single undo step
+     */
+    consolidateTemporaryItems(): void;
+    /**
+     * Removes all temporary items from the undo stack without consolidating them.
+     * Use this to discard temporary changes completely when they should not be
+     * preserved in the undo history (e.g., when cancelling an operation).
+     *
+     * Unlike `consolidateTemporaryItems`, this method does not preserve the changes
+     * as a single undo step - it simply removes them from history entirely.
+     */
+    clearTemporaryItems(): void;
+    /**
+     * Hot-swaps sync providers on the existing Y.Doc without destroying the document,
+     * objects, undo manager, or quadtree. Tears down old awareness subscriptions,
+    /**
+     * Destroys the object map and releases all resources.
+     * This removes all observers, destroys the undo manager, disconnects all providers,
+     * and destroys the Yjs document. After calling this, the object map cannot be used.
+     */
+    destroy(): void;
+}