@snowcone-app/canvas 0.1.0

package/dist/core/ImageElement.d.ts

@@ -0,0 +1,226 @@
+import { BaseElement } from './BaseElement.js';
+import { ImageTransformData, ImageElementConfig, ResizeAnchor, BoundingBox, Point, TransformStartData } from '../types/index.js';
+/** Image loading state for retry logic and UI feedback */
+export type ImageLoadState = 'loading' | 'loaded' | 'error' | 'retrying';
+export declare class ImageElement extends BaseElement {
+    transformType: 'image';
+    transformData: ImageTransformData;
+    imageUrl: string;
+    imageLoaded: boolean;
+    imageElement: HTMLImageElement | null;
+    imageAspectRatio: number;
+    isCropping: boolean;
+    onLoadCallback: ((element: ImageElement) => void) | null;
+    isSvg: boolean;
+    preserveDimensions: boolean;
+    imageLoadState: ImageLoadState;
+    imageLoadError: Error | null;
+    private svgBlobUrl;
+    private loadTimeoutId;
+    private retryAttempt;
+    private cachedImageUrl;
+    constructor(config?: Partial<ImageElementConfig>);
+    /**
+     * Load image from URL
+     * For SVG files, we render to a high-DPI canvas to maintain quality
+     */
+    loadImage(url: string): void;
+    /**
+     * Load regular raster image (PNG, JPG, etc.) with timeout and retry logic.
+     * Uses exponential backoff: 1s, 2s, 4s between retries.
+     */
+    private loadRegularImage;
+    /**
+     * Single attempt to load a regular image with timeout.
+     * Called by loadRegularImage and retry logic.
+     *
+     * Uses the shared ImageCache to avoid duplicate loading of the same URL
+     * across multiple ImageElement instances.
+     */
+    private attemptLoadRegularImage;
+    /**
+     * Handle a load failure - either retry with backoff or set error state.
+     */
+    private handleLoadFailure;
+    /**
+     * Clear any pending load timeout
+     */
+    private clearLoadTimeout;
+    /**
+     * Release the current image from the shared cache.
+     * Called when switching URLs or destroying the element.
+     */
+    private releaseImageCache;
+    /**
+     * Manually retry loading the image after a failure.
+     * Resets retry count and starts fresh.
+     */
+    retryImageLoad(): void;
+    /**
+     * Revoke any existing SVG blob URL to prevent memory leaks
+     * iOS Safari has strict blob URL limits; this prevents accumulation
+     */
+    private revokeSvgBlobUrl;
+    /**
+     * Load SVG and convert to high-DPI canvas for crisp rendering
+     * SVG is rendered at 4x resolution to maintain quality when scaled
+     */
+    private loadSvgAsHighDpi;
+    /**
+     * Get bounding box in world coordinates
+     * Returns the unrotated dimensions - rotation is handled by the renderer
+     * When not in crop mode, returns only the cropped area dimensions
+     */
+    getBoundingBox(): BoundingBox;
+    /**
+     * Get visual bounding box - returns the cropped area bounds
+     * This is used for group bounds calculation and should represent the visible area
+     */
+    getVisualBoundingBox(): BoundingBox;
+    /**
+     * Get rotation anchor (center of the visible image area)
+     * In crop mode: returns the center of the full frame
+     * Not in crop mode: returns this.x, this.y (center of cropped area)
+     */
+    getRotationAnchor(): Point;
+    /**
+     * Hit test for image - checks if point is inside the visible (cropped) area
+     */
+    hitTest(worldX: number, worldY: number): boolean;
+    /**
+     * Render the image
+     */
+    render(ctx: CanvasRenderingContext2D, _isSelected?: boolean, _isHovered?: boolean): void;
+    /**
+     * Render placeholder based on current image load state.
+     * Shows different visuals for loading, retrying, error, and no-image states.
+     */
+    renderPlaceholder(ctx: CanvasRenderingContext2D): void;
+    /**
+     * Handle resize - maintain aspect ratio
+     * @returns {boolean} true if resize was applied
+     */
+    resize(anchor: ResizeAnchor, newWidth: number, newHeight: number, startData: TransformStartData): boolean;
+    /**
+     * Get enabled anchors - only corner handles for images
+     */
+    getEnabledAnchors(): ResizeAnchor[];
+    /**
+     * Enter crop mode
+     * Just sets the flag - position stays at the cropped area center
+     */
+    enterCropMode(): void;
+    /**
+     * Exit crop mode
+     * Just clears the flag - position stays the same
+     */
+    exitCropMode(): void;
+    /**
+     * Get crop box bounds in local coordinates (before rotation)
+     * Returns the rectangle where the crop box should be rendered
+     * Local coordinates are relative to this.x, this.y (the center of the cropped area)
+     */
+    getCropBoxBounds(): BoundingBox | null;
+    /**
+     * Get crop box corners in world coordinates (accounting for rotation)
+     * Returns array of {x, y} points for each corner
+     */
+    getCropBoxWorldCorners(): Point[] | null;
+    /**
+     * Convert world coordinates to local coordinates (accounting for rotation and flips)
+     * Local coordinates are relative to this.x, this.y (the center of the visible area)
+     */
+    worldToLocal(worldX: number, worldY: number): Point;
+    /**
+     * Convert local coordinates to world coordinates (accounting for rotation and flips)
+     * Inverse of worldToLocal
+     * Canvas transformations are applied in reverse: scale -> rotate -> translate
+     */
+    localToWorld(localX: number, localY: number): Point;
+    /**
+     * Hit test for crop box handles in world coordinates
+     * Returns {type: 'corner'|'edge', anchor: string} if hit, null otherwise
+     * @param worldX - X coordinate in world space
+     * @param worldY - Y coordinate in world space
+     * @param zoom - Current zoom level (used to scale hit areas for consistent interaction)
+     */
+    hitTestCropHandle(worldX: number, worldY: number, zoom?: number): {
+        type: 'corner' | 'edge';
+        anchor: string;
+        worldX: number;
+        worldY: number;
+    } | null;
+    /**
+     * Hit test for inside crop box in world coordinates
+     * Used for dragging the image within the crop area
+     */
+    hitTestCropBox(worldX: number, worldY: number): boolean;
+    /**
+     * Update crop box (normalized 0-1 coordinates)
+     * @param {number} cropX - Normalized X position (0-1)
+     * @param {number} cropY - Normalized Y position (0-1)
+     * @param {number} cropWidth - Normalized width (0-1)
+     * @param {number} cropHeight - Normalized height (0-1)
+     * @param {boolean} adjustPosition - Whether to adjust this.x, this.y to keep visual position stable (default: false)
+     */
+    updateCrop(cropX: number, cropY: number, cropWidth: number, cropHeight: number, adjustPosition?: boolean): void;
+    /**
+     * Get the local position of the corner opposite to the given anchor
+     * Corners are relative to frame center
+     */
+    private getOppositeCornerLocalPosition;
+    /**
+     * Calculate frame center position from crop center position
+     * In crop mode, this.x/y is the crop center, not the frame center
+     */
+    private calculateFrameCenterFromCropCenter;
+    /**
+     * Get the position of the fixed corner (opposite of anchor) in world coordinates
+     */
+    private getFixedCornerWorldPosition;
+    /**
+     * Calculate where the frame center would be after resize
+     * The opposite corner from the anchor stays fixed in world space
+     */
+    private calculateFrameCenterAfterResize;
+    /**
+     * Calculate crop state (position and size in normalized coords) at a given scale
+     * This is the core geometric calculation that determines where the crop zone
+     * would be positioned within the frame after resize.
+     */
+    private calculateCropStateAtScale;
+    /**
+     * Check if a given scale keeps crop within frame bounds
+     */
+    private isScaleValidForCropBounds;
+    /**
+     * Calculate minimum scale that keeps crop within frame bounds
+     * Uses binary search to find the largest scale >= proposedScale that satisfies constraints
+     */
+    private calculateMinScaleForCropBounds;
+    /**
+     * Remap anchor to account for flips
+     */
+    private remapAnchorForFlips;
+    /**
+     * Clone this element
+     */
+    clone(): ImageElement;
+    /**
+     * Serialize to JSON
+     */
+    toJSON(): ImageElementConfig & {
+        id: string;
+        type: 'image';
+        x: number;
+        y: number;
+        rotation: number;
+    };
+    /**
+     * Clean up resources held by this element
+     * Call this when the element is being removed from the canvas to prevent memory leaks
+     * Particularly important for iOS Safari which has strict memory limits
+     */
+    destroy(): void;
+}
+export default ImageElement;

package/dist/core/ImageLoadEvents.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ImageLoadEvents - Simple event system for notifying when images finish loading
+ *
+ * This solves the issue where the canvas shows "Loading..." even after an image
+ * has loaded, because React doesn't know the element's internal state changed.
+ *
+ * When ImageElement finishes loading an image, it emits an event.
+ * CanvasEditor subscribes to this event and triggers a re-render.
+ */
+type ImageLoadListener = (elementId: string) => void;
+/**
+ * Subscribe to image load events
+ * @param listener - Callback called when any ImageElement finishes loading
+ * @returns Unsubscribe function
+ */
+export declare function subscribeToImageLoads(listener: ImageLoadListener): () => void;
+/**
+ * Emit an image load event
+ * Called by ImageElement when an image finishes loading
+ * @param elementId - The ID of the element that finished loading
+ */
+export declare function emitImageLoaded(elementId: string): void;
+export {};

package/dist/core/InteractionFeedbackRenderer.d.ts

@@ -0,0 +1,15 @@
+import { SnapGuide, SpacingIndicator } from '../types/index.js';
+export declare class InteractionFeedbackRenderer {
+    /**
+     * Render snap guides layer
+     */
+    static renderSnapGuidesLayer(ctx: CanvasRenderingContext2D, snapGuides?: SnapGuide[]): void;
+    /**
+     * Render spacing indicators layer
+     */
+    static renderSpacingIndicatorsLayer(ctx: CanvasRenderingContext2D, spacingIndicators?: SpacingIndicator[]): void;
+    /**
+     * Render a distance label with background
+     */
+    static renderDistanceLabel(ctx: CanvasRenderingContext2D, x: number, y: number, distance: number): void;
+}

package/dist/core/InteractionStateMachine.d.ts

@@ -0,0 +1,199 @@
+import { BaseElement } from './BaseElement.js';
+import { GroupElement } from './GroupElement.js';
+import { ResizePipeline } from './ResizePipeline.js';
+import { ResizeAnchor, BoundingBox, Point, InteractionMode, TransformStartData } from '../types/index.js';
+type State = 'IDLE' | 'DRAGGING' | 'RESIZING' | 'ROTATING' | 'PINCHING';
+interface HandleInfo {
+    anchor: ResizeAnchor;
+    type?: string;
+    cursor?: string;
+    x?: number;
+    y?: number;
+}
+interface RotationStartData {
+    startAngle: number;
+    currentRotation: number;
+    elementData: TransformStartData;
+}
+/**
+ * Output of `updatePinch` — the raw gesture state. PinchHandler
+ * consumes this together with the element snapshot in
+ * `getPinchContext()` to produce the next element.
+ */
+export interface PinchGesture {
+    /** Distance ratio (current / start). 1.0 = no scale change. */
+    scale: number;
+    /** Angle delta in radians (current - start). 0 = no rotate change. */
+    rotationDelta: number;
+    /** Gesture centroid at start (world coords). */
+    startCentroid: Point;
+    /** Gesture centroid right now (world coords). */
+    currentCentroid: Point;
+}
+interface InteractionContextData {
+    mode: InteractionMode | null;
+    dragMode?: string | null;
+    startX: number;
+    startY: number;
+    startData: TransformStartData | RotationStartData | null;
+    activeHandle: HandleInfo | null;
+    element: BaseElement | null;
+}
+interface SnapHandler {
+    snapPosition?: (position: Point, element: BaseElement, allElements: BaseElement[] | null) => Point;
+    snapRotation?: (rotation: number, element: BaseElement) => number;
+}
+export interface ActiveChildContext {
+    group: GroupElement;
+    childId: string;
+}
+export interface CropGroupContext {
+    group: BaseElement;
+    childIndex: number;
+}
+export declare class InteractionStateMachine {
+    state: State;
+    context: InteractionContextData;
+    snapHandler: SnapHandler | null;
+    resizePipeline: ResizePipeline | null;
+    /** Context for interactions targeting a child within a group */
+    _activeChildContext?: ActiveChildContext;
+    /** Context for crop mode interactions on group children */
+    _cropGroupContext?: CropGroupContext;
+    constructor(resizePipeline?: ResizePipeline | null);
+    /**
+     * Set snap handler for position/dimension snapping
+     */
+    setSnapHandler(handler: SnapHandler | null): void;
+    /**
+     * Set resize pipeline for hooking into resize operations
+     */
+    setResizePipeline(pipeline: ResizePipeline | null): void;
+    /**
+     * Get current state
+     */
+    getState(): State;
+    /**
+     * Get current context
+     */
+    getContext(): InteractionContextData;
+    /**
+     * Check if currently interacting
+     */
+    isInteracting(): boolean;
+    /**
+     * Start drag operation
+     */
+    startDrag(element: BaseElement, mouseX: number, mouseY: number, dragMode?: string | null): void;
+    /**
+     * Get drag mode
+     */
+    getDragMode(): string | null | undefined;
+    /**
+     * Reset drag start position (for incremental dragging)
+     */
+    resetDragStart(mouseX: number, mouseY: number): void;
+    /**
+     * Update drag operation
+     * Returns updated position { x, y }
+     */
+    updateDrag(mouseX: number, mouseY: number, allElements?: BaseElement[] | null): Point;
+    /**
+     * Start resize operation
+     */
+    startResize(element: BaseElement, handle: HandleInfo, mouseX: number, mouseY: number, bbox: BoundingBox, visualBbox: BoundingBox): void;
+    /**
+     * Update resize operation
+     * Returns { dx, dy } deltas
+     */
+    updateResize(mouseX: number, mouseY: number): {
+        dx: number;
+        dy: number;
+    };
+    /**
+     * Adjust the resize start position to account for snap corrections
+     * This prevents dx/dy from accumulating when a snap is locked
+     */
+    adjustResizeStart(deltaX: number, deltaY: number): void;
+    /**
+     * Get resize context for ResizeHandler
+     */
+    getResizeContext(): {
+        element: BaseElement;
+        handle: HandleInfo;
+        startData: TransformStartData;
+    };
+    /**
+     * Update the element in resize context (to preserve state between frames)
+     * This is critical for ImageElement crop mode where _lastValidCropState needs to persist
+     */
+    updateResizeElement(element: BaseElement): void;
+    /**
+     * Reset resize start data to current element state (for unfreezing)
+     * This updates startData to use the current element dimensions, preventing jumps
+     */
+    resetResizeStartData(element: BaseElement, mouseX: number, mouseY: number): void;
+    /**
+     * Start rotation operation
+     */
+    startRotate(element: BaseElement, mouseX: number, mouseY: number, startAngle: number, currentRotation: number): void;
+    /**
+     * Update rotation operation
+     * Returns updated rotation angle in degrees
+     */
+    updateRotate(mouseX: number, mouseY: number, centerX: number, centerY: number): number;
+    /**
+     * Get rotation context
+     */
+    getRotationContext(): {
+        startAngle: number;
+        currentRotation: number;
+    };
+    /**
+     * Start a two-finger pinch gesture on `element`. Captures the
+     * gesture's start centroid / distance / angle and the element's
+     * full transform snapshot — `updatePinch` then derives the
+     * gesture's scale + rotation delta against this snapshot every
+     * frame. PinchHandler consumes both via `getPinchContext()` to
+     * produce the next element.
+     */
+    startPinch(element: BaseElement, p1: Point, p2: Point): void;
+    /**
+     * Update pinch gesture for the latest two-pointer positions.
+     * Returns the raw gesture state (scale ratio, rotation delta,
+     * centroid positions). The caller (PinchHandler) is responsible
+     * for applying this to the element — keeping the math out of the
+     * state machine mirrors how `updateResize` returns `{dx, dy}` and
+     * lets `ResizeHandler` do the geometry.
+     *
+     * Scale is clamped to a small floor so degenerate single-finger
+     * coalesces (e.g. fingers landing on the same pixel for one
+     * frame) don't produce zero / NaN dimensions.
+     */
+    updatePinch(p1: Point, p2: Point): PinchGesture;
+    /**
+     * Get the element snapshot + pinch start data (used by
+     * PinchHandler.calculatePinch). Mirrors `getResizeContext`.
+     */
+    getPinchContext(): {
+        element: BaseElement;
+        startData: TransformStartData;
+    };
+    /**
+     * End current interaction
+     */
+    end(): void;
+    /**
+     * Cancel current interaction (no commit)
+     */
+    cancel(): void;
+    /**
+     * Get active handle (for resize mode)
+     */
+    getActiveHandle(): HandleInfo | null;
+    /**
+     * Get mode ('drag', 'resize', 'rotate', or null)
+     */
+    getMode(): InteractionMode | null;
+}
+export {};

package/dist/core/PathElement.d.ts

@@ -0,0 +1,84 @@
+import { BaseElement } from './BaseElement.js';
+import { PathTransformData, PathElementConfig, ResizeAnchor, BoundingBox, Point, TransformStartData } from '../types/index.js';
+export declare class PathElement extends BaseElement {
+    transformType: 'path';
+    transformData: PathTransformData;
+    constructor(config?: Partial<PathElementConfig>);
+    /**
+     * Get bounding box in world coordinates
+     * Returns the unrotated dimensions - rotation is handled by the renderer
+     * For paths, calculates actual bounds from path points
+     * The bounding box is centered around the element position (this.x, this.y)
+     */
+    getBoundingBox(): BoundingBox;
+    /**
+     * Get visual bounding box (same as regular bounding box for paths)
+     * Used for selection display - wraps tightly around actual path
+     */
+    getVisualBoundingBox(): BoundingBox;
+    /**
+     * Get rotation anchor point (center of the path's bounding box)
+     */
+    getRotationAnchor(): Point;
+    /**
+     * Calculate a point on a cubic Bezier curve
+     * @param p0 Start point
+     * @param p1 First control point
+     * @param p2 Second control point
+     * @param p3 End point
+     * @param t Parameter from 0 to 1
+     */
+    private bezierPoint;
+    /**
+     * Calculate bounding box from path points
+     * Returns bbox in local coordinates (relative to element position)
+     */
+    private calculatePathBounds;
+    /**
+     * Update cached bounding box dimensions
+     */
+    updateBounds(): void;
+    /**
+     * Render the path
+     */
+    render(ctx: CanvasRenderingContext2D, _isSelected?: boolean, _isHovered?: boolean): void;
+    /**
+     * Render the path using Canvas API bezier curves
+     */
+    private renderPath;
+    /**
+     * Handle resize - scale all points relative to center
+     */
+    resize(anchor: ResizeAnchor, newWidth: number, newHeight: number, startData: TransformStartData): boolean;
+    /**
+     * Get the opposite anchor (the one that should stay fixed during resize)
+     */
+    private getOppositeAnchor;
+    /**
+     * Get the position of the fixed corner (opposite of dragged anchor)
+     */
+    private getFixedCorner;
+    /**
+     * Get the offset of a corner from the center
+     */
+    private getCornerOffset;
+    /**
+     * Get enabled anchors - all 8 anchors for free resize
+     */
+    getEnabledAnchors(): ResizeAnchor[];
+    /**
+     * Clone this element
+     */
+    clone(): PathElement;
+    /**
+     * Serialize to JSON
+     */
+    toJSON(): PathElementConfig & {
+        id: string;
+        type: 'path';
+        x: number;
+        y: number;
+        rotation: number;
+    };
+}
+export default PathElement;

package/dist/core/PenToolManager.d.ts

@@ -0,0 +1,112 @@
+import { PathPoint, Point } from '../types/index.js';
+import { PathElement } from './PathElement.js';
+export interface PenToolState {
+    active: boolean;
+    pathElement: PathElement | null;
+    points: PathPoint[];
+    currentPoint: PathPoint | null;
+    isDraggingHandle: boolean;
+    previewPoint: Point | null;
+    isClosing: boolean;
+    closingClickPos: Point | null;
+}
+export declare class PenToolManager {
+    private state;
+    /**
+     * Start pen tool mode with a new path element
+     */
+    startPath(pathElement: PathElement): void;
+    /**
+     * Edit an existing path element
+     * Loads the existing points and enters edit mode
+     */
+    editPath(pathElement: PathElement): void;
+    /**
+     * Check if pen tool is active
+     */
+    isActive(): boolean;
+    /**
+     * Get current state
+     */
+    getState(): PenToolState;
+    /**
+     * Update preview point (for cursor following)
+     */
+    setPreviewPoint(x: number, y: number): void;
+    /**
+     * Clear preview point
+     */
+    clearPreviewPoint(): void;
+    /**
+     * Add a new anchor point at the given position (relative to path element)
+     * Returns the created point
+     */
+    addPoint(x: number, y: number): PathPoint;
+    /**
+     * Start dragging handle for the current point
+     */
+    startDraggingHandle(): void;
+    /**
+     * Update handle position for current point (relative to point position)
+     */
+    updateHandle(handleX: number, handleY: number): void;
+    /**
+     * Finish dragging handle
+     * If closing the path, this will complete the closing operation
+     */
+    finishDraggingHandle(): void;
+    /**
+     * Check if we can close the path (clicking near first point)
+     */
+    canClosePath(x: number, y: number, threshold?: number): boolean;
+    /**
+     * Start closing the path (allows handle dragging for the closing point)
+     * Records where the user clicked so we can calculate handle offsets correctly
+     */
+    startClosing(clickX: number, clickY: number): void;
+    /**
+     * Check if currently in closing mode
+     */
+    isClosingPath(): boolean;
+    /**
+     * Recenter the path element to match where the path was actually drawn
+     * Adjusts element position and converts points to be relative to the actual center
+     */
+    private recenterPath;
+    /**
+     * Close the path (connect last point to first)
+     */
+    closePath(): void;
+    /**
+     * Finish the path without closing (leave open)
+     */
+    finishPath(): void;
+    /**
+     * Delete the last added point (undo last point)
+     */
+    deleteLastPoint(): void;
+    /**
+     * Cancel path creation entirely
+     */
+    cancelPath(): PathElement | null;
+    /**
+     * End path creation mode
+     */
+    private endPath;
+    /**
+     * Get points for rendering preview
+     */
+    getPoints(): PathPoint[];
+    /**
+     * Get current point being edited
+     */
+    getCurrentPoint(): PathPoint | null;
+    /**
+     * Check if currently dragging a handle
+     */
+    isDraggingHandle(): boolean;
+    /**
+     * Render pen tool preview on canvas
+     */
+    renderPreview(ctx: CanvasRenderingContext2D, pathElement: PathElement): void;
+}

package/dist/core/PinchHandler.d.ts

@@ -0,0 +1,32 @@
+import { BaseElement } from './BaseElement.js';
+import { Point, TransformStartData } from '../types/index.js';
+export interface PinchInputs {
+    /** Cloned element to mutate — typically `stateMachine.context.element`. */
+    element: BaseElement;
+    /** Start snapshot of the element's transform (from
+     * `BaseElement.getTransformStartData`). Carries the start position,
+     * rotation, dimensions, and stroke width that the math reads. */
+    startData: TransformStartData;
+    /** Distance ratio (current / start). 1 = no scale change. */
+    scale: number;
+    /** Angle delta in radians (current - start). 0 = no rotate change. */
+    rotationDelta: number;
+    /** Gesture centroid at gesture start, in world coords. */
+    startCentroid: Point;
+    /** Gesture centroid right now, in world coords. */
+    currentCentroid: Point;
+    /**
+     * Optional snap hook for cardinal-angle rotation snapping. Same
+     * shape as `InteractionStateMachine`'s rotation snap callback —
+     * returns possibly-adjusted rotation in degrees.
+     */
+    snapRotation?: (rotation: number, element: BaseElement) => number;
+}
+export declare class PinchHandler {
+    /**
+     * Apply the pinch gesture to `element` in place and return it. The
+     * element is expected to already be a clone (the state machine
+     * clones on `startPinch`) — this method does not clone again.
+     */
+    static calculatePinch({ element, startData, scale, rotationDelta, startCentroid, currentCentroid, snapRotation, }: PinchInputs): BaseElement;
+}