@snowcone-app/canvas 0.1.0

package/dist/contexts/ThemeContext.d.ts

@@ -0,0 +1,55 @@
+import { default as React, ReactNode } from 'react';
+export type Theme = 'light' | 'dark' | 'axis' | 'ocean' | 'sunset' | 'auto';
+type ResolvedTheme = 'light' | 'dark' | 'axis-light' | 'axis-dark' | 'ocean-light' | 'ocean-dark' | 'sunset-light' | 'sunset-dark';
+interface ThemeContextValue {
+    theme: Theme;
+    resolvedTheme: ResolvedTheme;
+    setTheme: (theme: Theme) => void;
+    isDark: boolean;
+}
+interface ThemeProviderProps {
+    children: ReactNode;
+    defaultTheme?: Theme;
+    /**
+     * When true, the provider reads theme from the document but doesn't modify it.
+     * Use this when embedding in an app that already manages themes.
+     * This prevents the canvas from overriding the parent app's theme.
+     */
+    passive?: boolean;
+}
+/**
+ * Provides theme state to all descendant components.
+ *
+ * In **active** mode (default), applies theme to `document.documentElement` and
+ * persists the choice to `localStorage`. In **passive** mode, reads the theme
+ * from the document without modifying it -- use this when embedding inside a
+ * host app that already manages themes.
+ *
+ * @example
+ * ```tsx
+ * // Active mode (standalone)
+ * <ThemeProvider defaultTheme="auto">
+ *   <App />
+ * </ThemeProvider>
+ *
+ * // Passive mode (embedded in host app)
+ * <ThemeProvider passive>
+ *   <SnowconeCanvasInner />
+ * </ThemeProvider>
+ * ```
+ */
+export declare const ThemeProvider: React.FC<ThemeProviderProps>;
+/**
+ * Hook to access theme context
+ *
+ * @example
+ * const { theme, setTheme, isDark } = useTheme();
+ *
+ * // Change theme
+ * setTheme('dark');
+ *
+ * // Check current theme
+ * if (isDark) { ... }
+ */
+export declare const useTheme: () => ThemeContextValue;
+export {};

package/dist/contexts/ToolStateContext.d.ts

@@ -0,0 +1,60 @@
+import { default as React, ReactNode } from 'react';
+/** Expanded panel types for contextual toolbars */
+export type ExpandedPanelType = 'cornerRadius' | 'effects' | 'crop' | 'rotation' | null;
+/** Value exposed by ToolStateContext. */
+export interface ToolStateContextValue {
+    /** Which contextual panel is currently expanded, or null */
+    expandedPanelType: ExpandedPanelType;
+    /** Set the expanded panel type */
+    setExpandedPanelType: React.Dispatch<React.SetStateAction<ExpandedPanelType>>;
+    /** Whether any toolbar dropdown/menu/panel is open */
+    isToolbarMenuOpen: boolean;
+    /** Set toolbar menu open state */
+    setIsToolbarMenuOpen: React.Dispatch<React.SetStateAction<boolean>>;
+    /** Version counter for text selection changes (forces re-render on selection) */
+    textSelectionVersion: number;
+    /** Increment text selection version */
+    setTextSelectionVersion: React.Dispatch<React.SetStateAction<number>>;
+    /** Whether the canvas has mounted and is ready for operations */
+    isCanvasReady: boolean;
+    /** Set the canvas ready state */
+    setCanvasReady: (ready: boolean) => void;
+    /** Whether the user is currently rotating an element */
+    isRotating: boolean;
+    /** Set the rotation state */
+    setIsRotating: React.Dispatch<React.SetStateAction<boolean>>;
+}
+/** Props for {@link ToolStateProvider}. */
+export interface ToolStateProviderProps {
+    children: ReactNode;
+}
+/**
+ * Provides UI tool state to all descendants.
+ *
+ * Manages which panel is expanded, whether toolbar menus are open,
+ * text selection tracking, canvas readiness, and rotation state.
+ */
+export declare const ToolStateProvider: React.FC<ToolStateProviderProps>;
+/**
+ * Access UI tool state: expanded panels, toolbar menus, canvas readiness, etc.
+ *
+ * Prefer this over `useEditor()` in components that only need tool UI state
+ * (e.g., contextual toolbars checking which panel is expanded).
+ *
+ * @throws {Error} If called outside of a `ToolStateProvider` (or `EditorProvider`)
+ *
+ * @example
+ * ```tsx
+ * function PanelToggle() {
+ *   const { expandedPanelType, setExpandedPanelType } = useToolStateContext();
+ *   return (
+ *     <button onClick={() => setExpandedPanelType(
+ *       expandedPanelType === 'effects' ? null : 'effects'
+ *     )}>
+ *       {expandedPanelType === 'effects' ? 'Close' : 'Effects'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useToolStateContext(): ToolStateContextValue;

package/dist/contexts/ViewportContext.d.ts

@@ -0,0 +1,87 @@
+import { default as React, ReactNode } from 'react';
+import { ArtboardManager } from '../core/ArtboardManager.js';
+/** Pan offset for infinite canvas viewport */
+export interface PanOffset {
+    x: number;
+    y: number;
+}
+/** Value exposed by ViewportContext. */
+export interface ViewportContextValue {
+    /** Current zoom level (1.0 = 100%) */
+    zoom: number;
+    /** Current pan offset in world coordinates */
+    panOffset: PanOffset;
+    /** Whether the user is currently panning */
+    isPanning: boolean;
+    /** Increment zoom by one step */
+    zoomIn: () => void;
+    /** Decrement zoom by one step */
+    zoomOut: () => void;
+    /** Zoom to fit the active artboard in the viewport */
+    zoomToFit: () => void;
+    /** Reset zoom to 100% and pan offset to origin */
+    resetView: () => void;
+    /** Set zoom to an exact value */
+    setZoom: React.Dispatch<React.SetStateAction<number>>;
+    /** Set pan offset to an exact value */
+    setPanOffset: React.Dispatch<React.SetStateAction<PanOffset>>;
+    /** Set whether the user is currently panning */
+    setIsPanning: React.Dispatch<React.SetStateAction<boolean>>;
+    /**
+     * User-driven zoom multiplier applied on top of the auto-fit zoom
+     * the embedded canvas computes from container size. 1.0 = exactly
+     * fit-zoom (no extra zoom). >1 = zoomed in for fine-detail editing.
+     * Composes with `zoom` (which is the *effective* zoom = fit × user)
+     * so legacy consumers reading `zoom` see one value.
+     */
+    userZoom: number;
+    setUserZoom: React.Dispatch<React.SetStateAction<number>>;
+    /** Reset userZoom to 1.0 and panOffset to origin (returns to fit). */
+    resetUserView: () => void;
+}
+/** Props for {@link ViewportProvider}. */
+export interface ViewportProviderProps {
+    children: ReactNode;
+    /** ArtboardManager instance, used by zoomToFit to read active artboard dimensions. */
+    artboardManager: ArtboardManager;
+    /** Ref to the canvas element, used by zoomToFit to measure the container. */
+    canvasRef: React.RefObject<HTMLCanvasElement | null>;
+    /**
+     * Controls how much of the container the artboard fills when using zoomToFit.
+     * Value between 0 and 1, where 1 means the artboard fills 100% of the container.
+     * Default is 0.9 (90%), leaving 5% padding on each side.
+     */
+    viewPadding?: number;
+}
+/**
+ * Provides viewport state (zoom, pan) and control functions to all descendants.
+ *
+ * Must be composed inside EditorProvider or used standalone for viewport-only
+ * scenarios. Most consumers should use the `useViewport()` hook.
+ */
+export declare const ViewportProvider: React.FC<ViewportProviderProps>;
+/**
+ * Access viewport state: zoom, pan, and control functions.
+ *
+ * Prefer this over `useEditor()` in components that only need viewport information
+ * (e.g., zoom controls, minimap overlays). Changes to non-viewport state won't
+ * trigger re-renders in components using this hook.
+ *
+ * @throws {Error} If called outside of a `ViewportProvider` (or `EditorProvider`)
+ *
+ * @example
+ * ```tsx
+ * function ZoomBar() {
+ *   const { zoom, zoomIn, zoomOut, zoomToFit } = useViewportContext();
+ *   return (
+ *     <div>
+ *       <button onClick={zoomOut}>-</button>
+ *       <span>{Math.round(zoom * 100)}%</span>
+ *       <button onClick={zoomIn}>+</button>
+ *       <button onClick={zoomToFit}>Fit</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useViewportContext(): ViewportContextValue;

package/dist/core/AlignmentSnapSystem.d.ts

@@ -0,0 +1,270 @@
+import { BaseElement } from './BaseElement.js';
+import { Point, SnapGuide, ResizeAnchor, AnyTransformData } from '../types/index.js';
+/**
+ * Represents an element with the properties accessed during snap operations.
+ * Extends BaseElement with optional text/image-specific properties that the
+ * snap system reads via duck-typing.
+ */
+interface SnapElement extends BaseElement {
+    /** Font size (present on TextElement and its subclasses) */
+    fontSize?: number;
+    /** Direct width property (present on some element types) */
+    width?: number;
+    /** Direct height property (present on some element types) */
+    height?: number;
+    /** Image aspect ratio (present on ImageElement) */
+    imageAspectRatio?: number;
+    /** Whether the image is in crop mode (present on ImageElement) */
+    isCropping?: boolean;
+    /** Override clone to return SnapElement */
+    clone(): SnapElement;
+}
+/** Named anchor points returned by RotationAnchorResolver.getSnapAnchors() */
+type SnapAnchors = Record<string, Point>;
+/** Resize handle info passed through the resize pipeline */
+interface SnapHandleInfo {
+    anchor: ResizeAnchor | string;
+    type?: string;
+    cursor?: string;
+    x?: number;
+    y?: number;
+}
+/** Start data captured at the beginning of a resize operation */
+interface ResizeStartData {
+    fontSize?: number;
+    width: number;
+    height: number;
+    visualWidth?: number;
+    visualHeight?: number;
+    x?: number;
+    y?: number;
+    rotation?: number;
+    transformData?: Partial<AnyTransformData>;
+}
+/** Result from the resize pipeline, passed into snapDimensions */
+interface ResizeResult {
+    element: SnapElement;
+    handle: SnapHandleInfo;
+    startData: ResizeStartData | null;
+    isFrozen?: boolean;
+    unfrozenDimensions?: {
+        width: number;
+        height: number;
+    };
+    snapAdjustment?: {
+        dx: number;
+        dy: number;
+    };
+    isInStickySnap?: boolean;
+}
+/** A detected snap on either X or Y axis during resize snap */
+interface ResizeSnap {
+    distance: number;
+    snapTo: number;
+    currentValue: number;
+    guide: SnapGuideExtended;
+}
+/** Extended guide info including movingKey and otherKey for tracking */
+interface SnapGuideExtended {
+    type: string;
+    x?: number;
+    y?: number;
+    y1?: number;
+    y2?: number;
+    x1?: number;
+    x2?: number;
+    movingKey: string;
+    otherKey: string;
+}
+/** Result from _processStickySnap */
+interface StickySnapResult {
+    snapDelta: number;
+    bestSnap: ResizeSnap | null;
+}
+interface SnapState {
+    snapTo: number;
+    anchorKey: string;
+    frozenFontSize: number;
+    frozenWidth: number;
+    frozenHeight: number;
+    frozenPosition: Point;
+    isPositionBasedSnap: boolean;
+}
+interface AlignmentSnapSystemOptions {
+    snapThreshold?: number;
+    enabled?: boolean;
+    showGuides?: boolean;
+    stickyThreshold?: number;
+}
+export declare class AlignmentSnapSystem {
+    snapThreshold: number;
+    enabled: boolean;
+    showGuides: boolean;
+    guides: SnapGuide[];
+    activeSnaps: {
+        x: SnapState | null;
+        y: SnapState | null;
+    };
+    stickyThreshold: number;
+    /** Spatial grid for O(1) amortized snap candidate lookup */
+    private _spatialGrid;
+    /** Map from grid item compound key to anchor metadata */
+    private _anchorMetadata;
+    /**
+     * ADR-0060: extra rectangular regions injected as snap targets in
+     * addition to the canvas elements. Used by spread-mode focused-piece
+     * editing so dragged elements snap to the FOCUSED PIECE'S center /
+     * edges / corners instead of the full artboard. Each rect produces
+     * 9 anchor points (corners, edge midpoints, center) — exactly the
+     * shape `RotationAnchorResolver.getSnapAnchors` produces for an
+     * un-rotated element. The id is used to scope the synthetic
+     * "element id" so grid-item keys stay unique.
+     */
+    private _extraSnapRects;
+    constructor(options?: AlignmentSnapSystemOptions);
+    /**
+     * Enable or disable snapping
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Set snap threshold in pixels
+     */
+    setSnapThreshold(threshold: number): void;
+    /**
+     * Get current snap guides for rendering
+     */
+    getGuides(): SnapGuide[];
+    /**
+     * Clear all snap guides
+     */
+    clearGuides(): void;
+    /**
+     * Clear sticky snap state
+     */
+    clearSnapState(): void;
+    /**
+     * ADR-0060: replace the set of extra snap rects (focused-piece bounds
+     * etc.). Pass `[]` to clear. Effective on the next snap operation.
+     */
+    setExtraSnapRects(rects: Array<{
+        id: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>): void;
+    /**
+     * Populate the spatial grid with anchor points from the given elements.
+     * Each element produces ~9 anchor points (corners, edge midpoints, center).
+     * The grid enables O(1) amortized lookup of nearby anchors by axis.
+     *
+     * Also folds in `_extraSnapRects` (set via `setExtraSnapRects`) so
+     * a focused piece in spread mode contributes its corners / edges /
+     * center as snap targets even though there's no real BaseElement.
+     */
+    private _populateSpatialGrid;
+    /**
+     * Snap a position during drag operation
+     */
+    snapPosition(position: Point, element: BaseElement, allElements: BaseElement[] | null): Point;
+    /**
+     * Calculate what the frozen font size should be at the snap point
+     * This ensures consistent font size regardless of which side of threshold you enter from
+     */
+    _calculateFrozenFontSizeAtSnap(element: SnapElement, snapDeltaX: number, _snapDeltaY: number, handle: SnapHandleInfo | null, startData: ResizeStartData | null): number;
+    /**
+     * Check if this will be a position-based snap (vs dimension-based)
+     * Position-based snaps adjust position to align edges when dimensions can't be modified
+     * Used for text elements where height is derived, not settable
+     */
+    _isPositionBasedSnap(element: SnapElement, axis: 'x' | 'y'): boolean;
+    /**
+     * Determine which snap keys to use based on the resize handle
+     */
+    _getSnapKeysForHandle(handle: SnapHandleInfo | null): string[];
+    /**
+     * Get all possible target snap keys (corners only, no center points)
+     */
+    _getTargetSnapKeys(): string[];
+    /**
+     * Find all X-axis snaps within threshold.
+     * Uses the spatial grid (pre-populated via _populateSpatialGrid) for
+     * O(1) amortized lookup instead of scanning all other elements.
+     */
+    _findXSnaps(movingAnchors: SnapAnchors, _otherElements: BaseElement[], snapKeys: string[], targetSnapKeys: string[]): ResizeSnap[];
+    /**
+     * Find all Y-axis snaps within threshold.
+     * Uses the spatial grid (pre-populated via _populateSpatialGrid) for
+     * O(1) amortized lookup instead of scanning all other elements.
+     */
+    _findYSnaps(movingAnchors: SnapAnchors, _otherElements: BaseElement[], snapKeys: string[], targetSnapKeys: string[]): ResizeSnap[];
+    /**
+     * Sort snaps by distance and prioritize based on handle anchor
+     */
+    _prioritizeSnaps(snaps: ResizeSnap[], handle: SnapHandleInfo | null, axis: 'x' | 'y'): void;
+    /**
+     * Create a guide visualization for an active snap
+     */
+    _createGuideForSnap(snap: SnapState, anchorKey: string, movingAnchors: SnapAnchors, otherElements: BaseElement[], axis: 'x' | 'y'): ResizeSnap | null;
+    /**
+     * Calculate aspect-ratio-aware sticky threshold for a given axis
+     * Wide elements move faster horizontally, tall elements move faster vertically
+     * Adjust threshold to compensate for this velocity difference
+     */
+    _getAdjustedStickyThreshold(axis: 'x' | 'y', element: SnapElement): number;
+    /**
+     * Calculate what dimensions should be when edge reaches snap point
+     * This ensures frozen dimensions match the geometry at the snap position
+     *
+     * The key insight: When a snap is first detected (edge within 5px of guideline),
+     * we need to freeze dimensions at what they WILL BE when the edge reaches the snap point,
+     * not what they ARE at the moment of detection. This prevents visual "jumps" during
+     * corner resize because position compensation expects dimensions to match the snap point.
+     *
+     * @param element - The element being resized
+     * @param axis - 'x' or 'y' axis of the snap
+     * @param snapDelta - Distance to move to reach snap point (can be positive or negative)
+     * @param anchorKey - Which anchor is snapping (e.g., 'topRight', 'bottomLeft', etc.)
+     * @param handle - The resize handle being dragged
+     * @returns {Object} { frozenWidth, frozenHeight } - Dimensions at snap point
+     */
+    _calculateFrozenDimensionsAtSnap(element: SnapElement, axis: 'x' | 'y', snapDelta: number, anchorKey: string, _handle: SnapHandleInfo | null): {
+        frozenWidth: number;
+        frozenHeight: number;
+    };
+    /**
+     * Process sticky snapping for a single axis
+     * @returns {Object} { snapDelta, bestSnap }
+     */
+    _processStickySnap(axis: 'x' | 'y', movingAnchors: SnapAnchors, snaps: ResizeSnap[], element: SnapElement, handle: SnapHandleInfo | null, startData: ResizeStartData | null, otherElements: BaseElement[]): StickySnapResult;
+    /**
+     * Adjust element for right edge resize
+     */
+    _adjustElementForRightResize(element: SnapElement, snapDeltaX: number, handle: SnapHandleInfo): void;
+    /**
+     * Adjust element for left edge resize
+     */
+    _adjustElementForLeftResize(element: SnapElement, snapDeltaX: number, handle: SnapHandleInfo): void;
+    /**
+     * Adjust element for bottom edge resize
+     */
+    _adjustElementForBottomResize(element: SnapElement, snapDeltaY: number, handle: SnapHandleInfo): void;
+    /**
+     * Adjust element for top edge resize
+     */
+    _adjustElementForTopResize(element: SnapElement, snapDeltaY: number, handle: SnapHandleInfo): void;
+    /**
+     * Snap dimensions during resize operation
+     *
+     * @param {object} result - Resize result AFTER ResizeHandler processes it
+     * @param {array} allElements - All elements in the scene
+     * @param {object} startData - Original data from when resize started (for font size preservation)
+     * @returns {object} Modified resize result with adjusted element
+     */
+    snapDimensions(result: ResizeResult, allElements: BaseElement[] | null, startData?: ResizeStartData | null): ResizeResult;
+    /**
+     * Snap rotation (for future implementation)
+     */
+    snapRotation(rotation: number, _element: BaseElement, _allElements?: BaseElement[]): number;
+}
+export {};

package/dist/core/ArtboardElement.d.ts

@@ -0,0 +1,106 @@
+import { TextElement } from './TextElement.js';
+import { ImageElement } from './ImageElement.js';
+import { GroupElement } from './GroupElement.js';
+import { BoundingBox, Point, ArtboardConfig, ArtboardBackgroundType, ArtboardDistressTexture, ArtboardImageMask, ClipShape } from '../types/index.js';
+export declare class ArtboardElement {
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    backgroundColor: string;
+    backgroundType: ArtboardBackgroundType;
+    backgroundTexture?: string;
+    exportBackground: boolean;
+    transformType: 'artboard';
+    clipShape?: ClipShape;
+    previewBackgroundColor?: string;
+    distressTexture?: ArtboardDistressTexture;
+    imageMask?: ArtboardImageMask;
+    private elementIds;
+    constructor(config?: Partial<ArtboardConfig>);
+    /**
+     * Get bounding box of the artboard
+     */
+    getBoundingBox(): BoundingBox;
+    /**
+     * Get center point of the artboard
+     */
+    getCenter(): Point;
+    /**
+     * Check if a point is within artboard bounds
+     */
+    containsPoint(px: number, py: number): boolean;
+    /**
+     * Check if an element's bounding box is within artboard bounds
+     */
+    containsElement(element: TextElement | ImageElement | GroupElement): boolean;
+    /**
+     * Add an element ID to this artboard
+     */
+    addElementId(elementId: string): void;
+    /**
+     * Remove an element ID from this artboard
+     */
+    removeElementId(elementId: string): void;
+    /**
+     * Check if artboard contains an element ID
+     */
+    hasElementId(elementId: string): boolean;
+    /**
+     * Get all element IDs in this artboard
+     */
+    getElementIds(): string[];
+    /**
+     * Get number of elements in artboard
+     */
+    getElementCount(): number;
+    /**
+     * Clear all element IDs
+     */
+    clearElementIds(): void;
+    /**
+     * Test if a point hits the artboard border (for selection)
+     * Returns true if point is near the border (within tolerance)
+     */
+    hitTestBorder(px: number, py: number, tolerance?: number): boolean;
+    /**
+     * Clone the artboard
+     */
+    clone(): ArtboardElement;
+    /**
+     * Serialize to JSON
+     */
+    toJSON(): ArtboardConfig;
+    /**
+     * Create from JSON
+     */
+    static fromJSON(config: ArtboardConfig): ArtboardElement;
+    /**
+     * Update artboard properties
+     */
+    updateProperties(updates: Partial<{
+        name: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        backgroundColor: string;
+        backgroundType: ArtboardBackgroundType;
+        backgroundTexture: string;
+        exportBackground: boolean;
+        clipShape: ClipShape;
+        distressTexture: ArtboardDistressTexture | undefined;
+        imageMask: ArtboardImageMask | undefined;
+    }>): void;
+    /**
+     * Resize artboard (with constraints)
+     */
+    resize(newWidth: number, newHeight: number): void;
+    /**
+     * Move artboard
+     */
+    move(newX: number, newY: number): void;
+}
+export default ArtboardElement;