@snowcone-app/canvas 0.1.0

package/dist/core/CommandHistory.d.ts

@@ -0,0 +1,173 @@
+import { BaseElement } from './BaseElement.js';
+import { Command as CommandInterface } from '../types/index.js';
+import { ArtboardElement } from './ArtboardElement.js';
+import { ArtboardManager } from './ArtboardManager.js';
+/**
+ * Base Command class
+ * All commands must implement execute() and undo()
+ */
+export declare class Command implements CommandInterface {
+    /**
+     * Execute the command
+     */
+    execute(): void;
+    /**
+     * Undo the command
+     */
+    undo(): void;
+}
+/**
+ * UpdateElementCommand - Command to update an element's properties
+ */
+export declare class UpdateElementCommand extends Command {
+    elementId: string;
+    oldElement: BaseElement | null;
+    newElement: BaseElement | null;
+    onUpdate: (element: BaseElement) => void;
+    constructor(elementId: string, oldElement: BaseElement | null, newElement: BaseElement | null, onUpdate: (element: BaseElement) => void);
+    execute(): void;
+    undo(): void;
+}
+/**
+ * AddElementCommand - Command to add a new element
+ */
+export declare class AddElementCommand extends Command {
+    element: BaseElement;
+    onAdd: (element: BaseElement) => void;
+    onRemove: (id: string) => void;
+    constructor(element: BaseElement, onAdd: (element: BaseElement) => void, onRemove: (id: string) => void);
+    execute(): void;
+    undo(): void;
+}
+/**
+ * RemoveElementCommand - Command to remove an element
+ */
+export declare class RemoveElementCommand extends Command {
+    element: BaseElement;
+    onAdd: (element: BaseElement) => void;
+    onRemove: (id: string) => void;
+    constructor(element: BaseElement, onAdd: (element: BaseElement) => void, onRemove: (id: string) => void);
+    execute(): void;
+    undo(): void;
+}
+/**
+ * BatchCommand - Execute multiple commands as one atomic operation
+ */
+export declare class BatchCommand extends Command {
+    commands: Command[];
+    constructor(commands?: Command[]);
+    execute(): void;
+    undo(): void;
+}
+/**
+ * CompoundCommand - Wraps an array of commands into a single undo entry.
+ * Used by executeBatch() to group multiple operations atomically.
+ *
+ * - execute(): runs all commands in order
+ * - undo(): reverts all commands in reverse order
+ */
+export declare class CompoundCommand extends Command {
+    private commands;
+    constructor(commands: Command[]);
+    execute(): void;
+    undo(): void;
+}
+/**
+ * CommandHistory - Manages undo/redo history
+ */
+export declare class CommandHistory {
+    history: Command[];
+    currentIndex: number;
+    maxSize: number;
+    constructor(maxSize?: number);
+    /**
+     * Execute a command and add it to history
+     */
+    execute(command: Command): void;
+    /**
+     * Execute multiple commands as a single atomic undo entry.
+     * All commands are wrapped in a CompoundCommand so that
+     * undo/redo treats the entire batch as one operation.
+     *
+     * No-op if commands array is empty.
+     */
+    executeBatch(commands: Command[]): void;
+    /**
+     * Undo the last command
+     */
+    undo(): boolean;
+    /**
+     * Redo the next command
+     */
+    redo(): boolean;
+    /**
+     * Check if undo is available
+     */
+    canUndo(): boolean;
+    /**
+     * Check if redo is available
+     */
+    canRedo(): boolean;
+    /**
+     * Clear all history
+     */
+    clear(): void;
+    /**
+     * Get current state info
+     */
+    getState(): {
+        canUndo: boolean;
+        canRedo: boolean;
+        historySize: number;
+        currentIndex: number;
+    };
+}
+/**
+ * CreateArtboardCommand - Command to create a new artboard
+ */
+export declare class CreateArtboardCommand extends Command {
+    artboard: ArtboardElement;
+    artboardManager: ArtboardManager;
+    constructor(artboard: ArtboardElement, artboardManager: ArtboardManager);
+    execute(): void;
+    undo(): void;
+}
+/**
+ * DeleteArtboardCommand - Command to delete an artboard
+ */
+export declare class DeleteArtboardCommand extends Command {
+    artboard: ArtboardElement;
+    artboardManager: ArtboardManager;
+    elementsOnArtboard: string[];
+    constructor(artboard: ArtboardElement, artboardManager: ArtboardManager);
+    execute(): void;
+    undo(): void;
+}
+/**
+ * UpdateArtboardCommand - Command to update artboard properties
+ */
+export declare class UpdateArtboardCommand extends Command {
+    artboardId: string;
+    oldProperties: Partial<ArtboardElement>;
+    newProperties: Partial<ArtboardElement>;
+    artboardManager: ArtboardManager;
+    constructor(artboardId: string, oldProperties: Partial<ArtboardElement>, newProperties: Partial<ArtboardElement>, artboardManager: ArtboardManager);
+    execute(): void;
+    undo(): void;
+}
+/**
+ * ReorderElementCommand - Command to reorder elements in the list
+ */
+export declare class ReorderElementCommand extends Command {
+    draggedId: string;
+    targetId: string;
+    position: 'before' | 'after';
+    oldOrder: string[];
+    newOrder: string[];
+    onReorder: (elementIds: string[]) => void;
+    constructor(draggedId: string, targetId: string, position: 'before' | 'after', currentOrder: string[], onReorder: (elementIds: string[]) => void);
+    private calculateNewOrder;
+    execute(): void;
+    undo(): void;
+}
+export default CommandHistory;

package/dist/core/CoordinateTransform.d.ts

@@ -0,0 +1,69 @@
+/** Minimal interface for objects that can be used with CoordinateTransform */
+interface TransformableElement {
+    x: number;
+    y: number;
+    rotation?: number;
+    flipH?: boolean;
+    flipV?: boolean;
+}
+/**
+ * CoordinateTransform - Handles coordinate transformations between world and local space
+ *
+ * Manages transformations including:
+ * - Translation (x, y position)
+ * - Rotation
+ * - Horizontal and vertical flips
+ */
+export declare class CoordinateTransform {
+    x: number;
+    y: number;
+    rotation: number;
+    flipH: boolean;
+    flipV: boolean;
+    /**
+     * @param x - Center X position in world space
+     * @param y - Center Y position in world space
+     * @param rotation - Rotation in degrees (positive = clockwise)
+     * @param flipH - Horizontal flip
+     * @param flipV - Vertical flip
+     */
+    constructor(x: number, y: number, rotation: number, flipH: boolean, flipV: boolean);
+    /**
+     * Convert world coordinates to local coordinates
+     * @param worldX - X coordinate in world space
+     * @param worldY - Y coordinate in world space
+     * @returns Local coordinates
+     */
+    worldToLocal(worldX: number, worldY: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Convert local coordinates to world coordinates
+     * @param localX - X coordinate in local space
+     * @param localY - Y coordinate in local space
+     * @returns World coordinates
+     */
+    localToWorld(localX: number, localY: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Transform a vector (direction/offset) without translation
+     * @param dx - X component of vector
+     * @param dy - Y component of vector
+     * @param inverse - If true, apply inverse transform
+     * @returns Transformed vector
+     */
+    transformVector(dx: number, dy: number, inverse?: boolean): {
+        dx: number;
+        dy: number;
+    };
+    /**
+     * Create a CoordinateTransform from an element object
+     * @param element - Element with x, y, rotation, flipH, flipV properties
+     * @returns CoordinateTransform
+     */
+    static fromElement(element: TransformableElement): CoordinateTransform;
+}
+export {};

package/dist/core/CropModeController.d.ts

@@ -0,0 +1,90 @@
+import { BaseElement } from './BaseElement.js';
+import { TransformStartData } from '../types/index.js';
+/** Shape of the context object from the interaction state machine */
+interface DragContext {
+    startX: number;
+    startY: number;
+    startData: TransformStartData;
+}
+/** Shape of the resize context from the interaction state machine */
+interface ResizeContext {
+    startData: TransformStartData;
+}
+/** Result of a crop image drag operation */
+interface CropDragResult {
+    cropX: number;
+    cropY: number;
+    cropWidth: number;
+    cropHeight: number;
+    x: number;
+    y: number;
+}
+/** Result of a crop box resize operation */
+interface CropResizeResult {
+    cropX: number;
+    cropY: number;
+    cropWidth: number;
+    cropHeight: number;
+    x: number;
+    y: number;
+    rotation: number;
+    width: number;
+    height: number;
+    cursor: string;
+}
+/** Result of constrained crop values */
+interface CropValues {
+    cropX: number;
+    cropY: number;
+    cropWidth: number;
+    cropHeight: number;
+}
+/**
+ * CropModeController - Handles all crop mode interactions
+ *
+ * Manages:
+ * - Dragging the image behind the crop window
+ * - Resizing the crop box
+ * - Coordinate transformations for crop operations
+ */
+export declare class CropModeController {
+    /**
+     * Handle dragging the image in crop mode
+     */
+    handleCropImageDrag(_element: BaseElement, context: DragContext, currentX: number, currentY: number): CropDragResult;
+    /**
+     * Handle resizing the crop box
+     */
+    handleCropBoxResize(_element: BaseElement, anchor: string, resizeContext: ResizeContext, stateMachineContext: DragContext, currentX: number, currentY: number): CropResizeResult;
+    /**
+     * Get cursor for crop resize handle
+     * @private
+     */
+    _getCropResizeCursor(anchor: string, flipH: boolean, flipV: boolean): string;
+    /**
+     * Calculate new crop values based on anchor and delta
+     * @private
+     */
+    _calculateNewCropValues(anchor: string, startCropX: number, startCropY: number, startCropWidth: number, startCropHeight: number, normalizedDx: number, normalizedDy: number): CropValues;
+    /**
+     * Constrain crop values to valid bounds
+     * @private
+     */
+    _constrainCropValues(anchor: string, cropX: number, cropY: number, cropWidth: number, cropHeight: number, startCropX: number, startCropY: number, startCropWidth: number, startCropHeight: number, minSize: number): CropValues;
+    /**
+     * Calculate offset to keep crop center at same world position
+     * @private
+     */
+    _calculateCropCenterOffset(oldCropX: number, oldCropY: number, oldCropWidth: number, oldCropHeight: number, newCropX: number, newCropY: number, newCropWidth: number, newCropHeight: number, width: number, height: number, rotation: number, flipHMult: number, flipVMult: number): {
+        worldOffsetX: number;
+        worldOffsetY: number;
+    };
+    /**
+     * Get the world position of a crop box handle
+     */
+    getCropBoxHandlePosition(element: BaseElement, anchor: string): {
+        x: number;
+        y: number;
+    };
+}
+export {};

package/dist/core/EditModeRenderer.d.ts

@@ -0,0 +1,51 @@
+import { default as React } from 'react';
+import { BaseElement } from './BaseElement.js';
+import { TransformHandles } from './TransformHandles.js';
+import { RichText } from '../types/index.js';
+export declare class EditModeRenderer {
+    /**
+     * Render edit mode features: cursor and text selection highlight
+     * This renders on the main canvas at world coordinates (same as the element)
+     */
+    static renderEditModeLayer(ctx: CanvasRenderingContext2D, element: BaseElement | null, editModeData: {
+        cursorPosition: number;
+        selectionStart: number;
+        selectionEnd: number;
+        editText: string;
+        editRichText: RichText | null;
+        cursorOpacity: number;
+        isTouchDevice?: boolean;
+        selectionHandlePositionsRef?: React.MutableRefObject<{
+            start: {
+                center: {
+                    x: number;
+                    y: number;
+                };
+                textEdge: {
+                    x: number;
+                    y: number;
+                };
+            } | null;
+            end: {
+                center: {
+                    x: number;
+                    y: number;
+                };
+                textEdge: {
+                    x: number;
+                    y: number;
+                };
+            } | null;
+        }>;
+    }, zoom: number): void;
+    /**
+     * Render edit mode features for transformed text (circle, wave, arch, etc.)
+     * Renders cursor along the transform path
+     */
+    private static renderTransformEditModeLayer;
+    /**
+     * Render crop box layer (for images in crop mode)
+     * Shows both image resize handles and crop handles
+     */
+    static renderCropBoxLayer(ctx: CanvasRenderingContext2D, selectedElement: BaseElement, transformHandles: TransformHandles, zoom?: number): void;
+}

package/dist/core/ElementFactory.d.ts

@@ -0,0 +1,73 @@
+import { AnyElementConfig, TransformType } from '../types';
+import { BaseElement } from './BaseElement';
+import { TextElement } from './TextElement';
+/**
+ * ElementFactory provides type-safe element creation from JSON configurations
+ *
+ * Benefits:
+ * - Type-safe deserialization from database
+ * - Exhaustive compile-time checking (TypeScript ensures all cases are covered)
+ * - Single source of truth for element construction
+ * - Safe undo/redo operations
+ *
+ * Usage:
+ * ```typescript
+ * // From database
+ * const config = JSON.parse(dbRecord);
+ * const element = ElementFactory.createFromJSON(config);
+ *
+ * // For undo/redo
+ * const cloned = ElementFactory.createFromJSON(element.toJSON());
+ * ```
+ */
+export declare class ElementFactory {
+    /**
+     * Create an element instance from a JSON configuration
+     * TypeScript ensures all transform types are handled
+     *
+     * @param config - Element configuration object
+     * @returns BaseElement instance (TextElement, ImageElement, GroupElement, ShapeElement, or PathElement)
+     * @throws Error if transform type is unknown
+     */
+    static createFromJSON(config: AnyElementConfig): BaseElement;
+    /**
+     * Create multiple elements from an array of JSON configurations
+     * Useful for bulk deserialization (e.g., loading a document from DB)
+     *
+     * @param configs - Array of element configurations
+     * @returns Array of BaseElement instances
+     */
+    static createManyFromJSON(configs: AnyElementConfig[]): BaseElement[];
+    /**
+     * Type guard to check if an object is a valid TextElement instance
+     * Useful for runtime validation
+     *
+     * @param obj - Object to check
+     * @returns true if obj is a TextElement
+     */
+    static isTextElement(obj: unknown): obj is TextElement;
+    /**
+     * Validate an element configuration object
+     * Returns true if the config has all required properties
+     *
+     * @param config - Configuration to validate
+     * @returns true if valid
+     */
+    static isValidConfig(config: unknown): config is AnyElementConfig;
+    /**
+     * Create a default element of a given type
+     * Useful for UI "Add Element" buttons
+     *
+     * @param transformType - Type of transform to create
+     * @returns Default element configuration
+     */
+    static createDefaultConfig(transformType: TransformType): AnyElementConfig;
+    /**
+     * Clone an element by serializing and deserializing
+     * Ensures a deep copy with proper class instance
+     *
+     * @param element - Element to clone
+     * @returns Cloned element instance
+     */
+    static clone(element: BaseElement): BaseElement;
+}

package/dist/core/ElementStore.d.ts

@@ -0,0 +1,69 @@
+import { TextElement } from './TextElement.js';
+import { ImageElement } from './ImageElement.js';
+import { GroupElement } from './GroupElement.js';
+import { ShapeElement } from './ShapeElement.js';
+import { PathElement } from './PathElement.js';
+/** Union of all element types that can be stored. */
+export type StoreElement = TextElement | ImageElement | GroupElement | ShapeElement | PathElement;
+export declare class ElementStore {
+    private byId;
+    private order;
+    private _cachedArray;
+    constructor(elements?: StoreElement[]);
+    /** O(1) lookup by ID. */
+    get(id: string): StoreElement | undefined;
+    /** Check whether the store contains an element with the given ID. */
+    has(id: string): boolean;
+    /** Get all elements in render order. */
+    getAll(): StoreElement[];
+    /** Number of elements in the store. */
+    get size(): number;
+    /** Get the ordered ID list (read-only copy). */
+    getOrder(): readonly string[];
+    /** O(n) lookup by name. Returns the first element with the given name, or undefined. */
+    getByName(name: string): StoreElement | undefined;
+    /** O(n) lookup by name. Returns all elements with the given name in render order. */
+    getAllByName(name: string): StoreElement[];
+    /** Replace an element in-place (preserves order). */
+    update(element: StoreElement): ElementStore;
+    /**
+     * Replace an element found by a predicate with a new element.
+     * This mirrors `setElements(prev => prev.map(el => el.id === id ? newEl : el))`.
+     */
+    updateById(id: string, element: StoreElement): ElementStore;
+    /** Add an element at the end of the render order. */
+    add(element: StoreElement): ElementStore;
+    /** Insert an element after a specific element ID. */
+    insertAfter(element: StoreElement, afterId: string): ElementStore;
+    /** Remove an element by ID. */
+    remove(id: string): ElementStore;
+    /** Reorder element to a new index in the render order. */
+    reorder(id: string, newIndex: number): ElementStore;
+    /**
+     * Apply a batch update: replace elements whose IDs match.
+     * Returns a new store. Useful for applying multiple updates at once
+     * (e.g., reordering by an ID array from undo/redo).
+     */
+    replaceAll(elements: StoreElement[]): ElementStore;
+    /**
+     * Filter elements by predicate while preserving order.
+     * Returns a new store containing only elements that match.
+     */
+    filter(predicate: (el: StoreElement) => boolean): ElementStore;
+    /**
+     * Map over elements in render order, returning a new store.
+     * The mapping function receives each element and returns a (possibly modified) element.
+     */
+    map(fn: (el: StoreElement) => StoreElement): ElementStore;
+    /**
+     * Set a completely new ordering for all elements.
+     * IDs not in the new order are dropped; new IDs not in the store are ignored.
+     */
+    setOrder(newOrder: string[]): ElementStore;
+    /** Convert to a plain array (backwards-compatible with `EditorElement[]`). Cached since the store is immutable. */
+    toArray(): StoreElement[];
+    /** Create from a plain array. */
+    static fromArray(elements: StoreElement[]): ElementStore;
+    /** Create a shallow clone (new Map/Array, same element references). */
+    private clone;
+}

package/dist/core/EventBus.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Canvas Event Bus
+ *
+ * A typed publish/subscribe event system for cross-component communication
+ * within the canvas editor. Components can emit and listen for events without
+ * direct coupling, enabling loose coordination between panels, tools, and
+ * the canvas itself.
+ *
+ * All event types are defined in {@link CanvasEventMap} for compile-time
+ * type safety -- subscribers receive correctly-typed payloads and emitters
+ * are checked against the event map at compile time.
+ *
+ * A singleton instance is available via {@link canvasEventBus} for use
+ * across the editor. The {@link useCanvasEvents} hook provides React
+ * integration.
+ *
+ * @example Subscribe to element creation
+ * ```ts
+ * import { canvasEventBus } from '@snowcone-app/canvas/advanced';
+ *
+ * const unsub = canvasEventBus.on('element:created', ({ elementId, type }) => {
+ *   console.log(`Created ${type} element: ${elementId}`);
+ * });
+ *
+ * // Later: clean up
+ * unsub();
+ * ```
+ *
+ * @example One-shot listener
+ * ```ts
+ * canvasEventBus.once('export:completed', ({ durationMs }) => {
+ *   console.log(`Export finished in ${durationMs}ms`);
+ * });
+ * ```
+ */
+/**
+ * Map of all canvas event names to their payload types.
+ *
+ * Extend this interface (via module augmentation) to add custom events:
+ * ```ts
+ * declare module '@snowcone-app/canvas/advanced' {
+ *   interface CanvasEventMap {
+ *     'my-plugin:action': { value: number };
+ *   }
+ * }
+ * ```
+ */
+export interface CanvasEventMap {
+    /** Fired after a new element is added to the canvas */
+    'element:created': {
+        elementId: string;
+        type: string;
+    };
+    /** Fired after one or more properties of an element change */
+    'element:updated': {
+        elementId: string;
+        changes: string[];
+    };
+    /** Fired after an element is removed from the canvas */
+    'element:deleted': {
+        elementId: string;
+    };
+    /** Fired when the selected element changes (null = deselected) */
+    'element:selected': {
+        elementId: string | null;
+    };
+    /** Fired when the active artboard changes */
+    'artboard:changed': {
+        artboardId: string;
+        artboardName: string;
+    };
+    /** Fired when an export operation begins */
+    'export:started': {
+        artboardId: string;
+    };
+    /** Fired when an export operation completes successfully */
+    'export:completed': {
+        artboardId: string;
+        durationMs: number;
+    };
+    /** Fired when an export operation fails */
+    'export:error': {
+        artboardId: string;
+        error: Error;
+    };
+    /** Fired after an undo operation */
+    'undo': {
+        commandDescription?: string;
+    };
+    /** Fired after a redo operation */
+    'redo': {
+        commandDescription?: string;
+    };
+}
+/** Strongly-typed event handler for a specific event name */
+export type CanvasEventHandler<K extends keyof CanvasEventMap> = (event: CanvasEventMap[K]) => void;
+/**
+ * A typed event bus for the canvas editor.
+ *
+ * Provides subscribe ({@link on}, {@link once}), publish ({@link emit}),
+ * and unsubscribe ({@link off}) operations with full type safety.
+ *
+ * Listeners for a given event are called in the order they were registered.
+ * Errors thrown inside a handler are caught and logged to `console.error`
+ * so that one failing handler does not prevent others from executing.
+ */
+export declare class CanvasEventBus {
+    /** Map of event name to the set of registered handler functions */
+    private listeners;
+    /**
+     * Subscribe to an event.
+     *
+     * @param event - The event name to listen for
+     * @param handler - Callback invoked with the event payload
+     * @returns An unsubscribe function -- call it to remove this handler
+     */
+    on<K extends keyof CanvasEventMap>(event: K, handler: CanvasEventHandler<K>): () => void;
+    /**
+     * Subscribe to an event for a single invocation.
+     *
+     * The handler is automatically removed after the first time the event
+     * fires. The returned unsubscribe function can also be used to cancel
+     * before the event fires.
+     *
+     * @param event - The event name to listen for
+     * @param handler - Callback invoked once with the event payload
+     * @returns An unsubscribe function
+     */
+    once<K extends keyof CanvasEventMap>(event: K, handler: CanvasEventHandler<K>): () => void;
+    /**
+     * Emit an event, invoking all registered handlers for that event name.
+     *
+     * Handlers are called synchronously in registration order. If a handler
+     * throws, the error is logged and remaining handlers still execute.
+     *
+     * @param event - The event name to emit
+     * @param data - The payload to pass to each handler
+     */
+    emit<K extends keyof CanvasEventMap>(event: K, data: CanvasEventMap[K]): void;
+    /**
+     * Remove listeners.
+     *
+     * - If called with an event name, removes all handlers for that event.
+     * - If called with no arguments, removes all handlers for all events.
+     *
+     * @param event - Optional event name to clear. Omit to clear everything.
+     */
+    off<K extends keyof CanvasEventMap>(event?: K): void;
+    /**
+     * Get the number of registered listeners for a specific event.
+     *
+     * @param event - The event name to query
+     * @returns The number of handlers currently registered
+     */
+    listenerCount(event: keyof CanvasEventMap): number;
+}
+/**
+ * The singleton CanvasEventBus instance shared across the editor.
+ *
+ * Use this directly or via the {@link useCanvasEvents} hook in React
+ * components.
+ */
+export declare const canvasEventBus: CanvasEventBus;