@snowcone-app/canvas 0.1.0

package/dist/core/ArtboardManager.d.ts

@@ -0,0 +1,130 @@
+import { ArtboardElement } from './ArtboardElement.js';
+import { TextElement } from './TextElement.js';
+import { ImageElement } from './ImageElement.js';
+import { GroupElement } from './GroupElement.js';
+import { ArtboardConfig } from '../types/index.js';
+export declare class ArtboardManager {
+    private artboards;
+    private elementToArtboard;
+    private activeArtboardId;
+    constructor();
+    /**
+     * Create a new artboard
+     *
+     * NOTE: This method sets the newly created artboard as active. When creating
+     * multiple artboards in a loop (e.g., during initialization), the LAST artboard
+     * will end up as active. If you need a specific artboard to be active after
+     * batch creation, call setActiveArtboard() explicitly afterward.
+     *
+     * SnowconeCanvas handles this via hasInitialSyncRef - it suppresses onArtboardChange
+     * callbacks until the controlled activeArtboard prop has been synced.
+     */
+    createArtboard(config?: Partial<ArtboardConfig>): ArtboardElement;
+    /**
+     * Delete an artboard
+     * Returns the IDs of elements that were on the artboard
+     */
+    deleteArtboard(artboardId: string): string[];
+    /**
+     * Get an artboard by ID
+     */
+    getArtboard(artboardId: string): ArtboardElement | undefined;
+    /**
+     * Get all artboards
+     */
+    getAllArtboards(): ArtboardElement[];
+    /**
+     * Get artboard IDs
+     */
+    getArtboardIds(): string[];
+    /**
+     * Set active artboard
+     */
+    setActiveArtboard(artboardId: string | null): void;
+    /**
+     * Get active artboard
+     */
+    getActiveArtboard(): ArtboardElement | null;
+    /**
+     * Get active artboard ID
+     */
+    getActiveArtboardId(): string | null;
+    /**
+     * Add an element to an artboard
+     */
+    addElementToArtboard(elementId: string, artboardId: string): boolean;
+    /**
+     * Remove an element from its artboard
+     */
+    removeElementFromArtboard(elementId: string): void;
+    /**
+     * Get the artboard that contains an element
+     */
+    getArtboardForElement(elementId: string): ArtboardElement | null;
+    /**
+     * Get artboard ID for an element
+     */
+    getArtboardIdForElement(elementId: string): string | null;
+    /**
+     * Get all elements on an artboard
+     * Note: Returns element IDs, not actual element objects
+     */
+    getElementsOnArtboard(artboardId: string): string[];
+    /**
+     * Find artboard at a point (for selection)
+     */
+    findArtboardAtPoint(x: number, y: number): ArtboardElement | null;
+    /**
+     * Find artboard border at point (for resize handles)
+     */
+    findArtboardBorderAtPoint(x: number, y: number, tolerance?: number): ArtboardElement | null;
+    /**
+     * Determine which artboard an element should belong to based on position
+     */
+    findArtboardForPosition(x: number, y: number): ArtboardElement | null;
+    /**
+     * Update artboard properties
+     */
+    updateArtboard(artboardId: string, updates: Partial<ArtboardConfig>): boolean;
+    /**
+     * Rename an artboard
+     */
+    renameArtboard(artboardId: string, name: string): boolean;
+    /**
+     * Check if an artboard exists
+     */
+    hasArtboard(artboardId: string): boolean;
+    /**
+     * Get artboard count
+     */
+    getArtboardCount(): number;
+    /**
+     * Reorder artboards by moving the artboard at fromIndex to toIndex.
+     * Preserves Map insertion order by rebuilding the internal Map.
+     */
+    reorderArtboards(fromIndex: number, toIndex: number): void;
+    /**
+     * Clear all artboards
+     */
+    clear(): void;
+    /**
+     * Serialize to JSON
+     */
+    toJSON(): {
+        artboards: ArtboardConfig[];
+        activeArtboardId: string | null;
+    };
+    /**
+     * Load from JSON
+     */
+    fromJSON(data: {
+        artboards: ArtboardConfig[];
+        activeArtboardId: string | null;
+    }): void;
+    /**
+     * Validate element-to-artboard mappings
+     * Ensures all elements have valid artboard assignments
+     */
+    validateMappings(elements: (TextElement | ImageElement | GroupElement)[]): void;
+}
+export default ArtboardManager;

package/dist/core/ArtboardRenderer.d.ts

@@ -0,0 +1,97 @@
+import { ArtboardElement } from './ArtboardElement.js';
+export interface ArtboardRenderOptions {
+    showLabel?: boolean;
+    showBorder?: boolean;
+    borderColor?: string;
+    borderWidth?: number;
+    labelFontSize?: number;
+    labelColor?: string;
+    labelPadding?: number;
+    selectedBorderColor?: string;
+    selectedBorderWidth?: number;
+    showPreviewBackground?: boolean;
+    borderRadius?: number;
+}
+export declare class ArtboardRenderer {
+    private options;
+    constructor(options?: ArtboardRenderOptions);
+    /**
+     * Render an artboard
+     */
+    render(ctx: CanvasRenderingContext2D, artboard: ArtboardElement, isSelected?: boolean): void;
+    /**
+     * Render artboard background
+     * Optionally renders preview background color for t-shirt design preview
+     * Preview background is NEVER exported - only shown in editor
+     * Background is clipped to the artboard's clipShape
+     */
+    private renderBackground;
+    /**
+     * Render texture background
+     * Renders preset color as base layer, then texture on top
+     */
+    private renderTextureBackground;
+    /**
+     * Render a checkerboard pattern for transparent backgrounds
+     */
+    private renderCheckerboard;
+    /**
+     * Render artboard border (respects clipShape and borderRadius option)
+     */
+    private renderBorder;
+    /**
+     * Render artboard label (name + dimensions)
+     */
+    private renderLabel;
+    /**
+     * Render multiple artboards
+     */
+    renderMultiple(ctx: CanvasRenderingContext2D, artboards: ArtboardElement[], selectedId: string | null): void;
+    /**
+     * Clip rendering to artboard bounds (respects clipShape)
+     * Use this to clip element rendering to stay within artboard
+     */
+    clipToArtboard(ctx: CanvasRenderingContext2D, artboard: ArtboardElement): void;
+    /**
+     * Apply clip path based on artboard's clipShape
+     * This creates the clip region for the given artboard
+     * If borderRadius option is set and no special clipShape, uses rounded rectangle
+     */
+    applyClipPath(ctx: CanvasRenderingContext2D, artboard: ArtboardElement): void;
+    /**
+     * Draw a rounded rectangle path
+     * Helper method for rounded clip shapes
+     */
+    private roundedRect;
+    /**
+     * Restore after clipping
+     */
+    restoreClip(ctx: CanvasRenderingContext2D): void;
+    /**
+     * Render artboard outline (for dragging/resizing preview)
+     */
+    renderOutline(ctx: CanvasRenderingContext2D, x: number, y: number, width: number, height: number, isDragging?: boolean): void;
+    /**
+     * Render resize handles for artboard
+     */
+    renderResizeHandles(ctx: CanvasRenderingContext2D, artboard: ArtboardElement): void;
+    /**
+     * Update options
+     */
+    setOptions(options: Partial<ArtboardRenderOptions>): void;
+    /**
+     * Get current options
+     */
+    getOptions(): ArtboardRenderOptions;
+    /**
+     * Create export-safe renderer
+     * Returns a new renderer instance with preview background disabled
+     * Use this when exporting to ensure preview background is never included
+     */
+    static createForExport(options?: ArtboardRenderOptions): ArtboardRenderer;
+    /**
+     * Check if preview background would be rendered for given artboard
+     */
+    willRenderPreviewBackground(artboard: ArtboardElement): boolean;
+}
+export default ArtboardRenderer;

package/dist/core/BaseElement.d.ts

@@ -0,0 +1,94 @@
+import { TransformType, AnyTransformData, BoundingBox, Point, ResizeAnchor, BlendMode, KnockoutConfig, StrokeConfig, MaskDefinition, DistressEffect, BaseElementConfig, TransformStartData } from '../types/index.js';
+/**
+ * Reset the ID counter (useful for testing)
+ */
+export declare function resetElementIdCounter(): void;
+export declare abstract class BaseElement {
+    id: string;
+    x: number;
+    y: number;
+    rotation: number;
+    opacity: number;
+    transformType: TransformType;
+    transformData: AnyTransformData;
+    blendMode?: BlendMode;
+    knockoutParts?: KnockoutConfig;
+    stroke?: StrokeConfig;
+    masks?: MaskDefinition[];
+    distressEffect?: DistressEffect;
+    name?: string;
+    visible?: boolean;
+    locked?: boolean;
+    /** Whether this element clips content below it (derived from blendMode === 'clip') */
+    get isClipping(): boolean;
+    set isClipping(value: boolean | undefined);
+    constructor(config?: Partial<BaseElementConfig>);
+    /**
+     * Get bounding box in world coordinates
+     * Used for transform math (resize, rotation, handles)
+     * Must be implemented by subclasses
+     */
+    abstract getBoundingBox(): BoundingBox;
+    /**
+     * Get visual bounding box (tight fit around actual rendered content)
+     * Used for selection display - should match what user sees
+     * Default: same as getBoundingBox(), override for tighter fit
+     */
+    getVisualBoundingBox(): BoundingBox;
+    /**
+     * Get rotation anchor point (the point around which element rotates)
+     * Default: returns element's position (x, y)
+     * Override if rotation should be around a different point
+     */
+    getRotationAnchor(): Point;
+    /**
+     * Test if a point hits this element
+     * Uses visual bounding box for better user experience
+     */
+    hitTest(px: number, py: number): boolean;
+    /**
+     * Render the element
+     * Must be implemented by subclasses
+     */
+    abstract render(ctx: CanvasRenderingContext2D, isSelected?: boolean, isHovered?: boolean): void;
+    /**
+     * Apply canvas transform (translate, rotate)
+     * Common implementation for all elements
+     */
+    applyCanvasTransform(ctx: CanvasRenderingContext2D): void;
+    /**
+     * Serialize to JSON
+     * Returns base element properties - subclasses should extend this
+     */
+    toJSON(): BaseElementConfig;
+    /**
+     * Clone this element
+     * Uses toJSON() to serialize and reconstruct
+     */
+    abstract clone(): BaseElement;
+    /**
+     * Update position during drag
+     */
+    move(dx: number, dy: number): void;
+    /**
+     * Update rotation
+     */
+    setRotation(newRotation: number): void;
+    /**
+     * Get enabled resize anchors for this element type
+     * Default: all 8 anchors
+     * Override in subclasses if needed
+     */
+    getEnabledAnchors(): ResizeAnchor[];
+    /**
+     * Handle resize transform
+     * Must be implemented by subclasses
+     */
+    abstract resize(anchor: ResizeAnchor, newWidth: number, newHeight: number, startData: TransformStartData): void | boolean;
+    /**
+     * Called when transform starts
+     * Returns data to be passed to resize()
+     */
+    getTransformStartData(): TransformStartData;
+}
+export default BaseElement;

package/dist/core/CanvasRenderer.d.ts

@@ -0,0 +1,237 @@
+import { BaseElement } from './BaseElement.js';
+import { TransformHandles } from './TransformHandles.js';
+import { InteractionStateMachine } from './InteractionStateMachine.js';
+import { RichText, SnapGuide, SpacingIndicator, ArtboardDistressTexture, CanvasError, ClipShape } from '../types/index.js';
+interface HoverState {
+    type: 'element' | 'resize-handle' | 'rotation-handle' | null;
+    data?: BaseElement | null;
+}
+export declare class CanvasRenderer {
+    /** Pooled offscreen canvas for clipping content rendering */
+    private static _contentCanvas;
+    private static _contentCanvasSize;
+    /** Pooled offscreen canvas for clipping mask rendering */
+    private static _maskCanvas;
+    private static _maskCanvasSize;
+    /**
+     * Get a pooled offscreen canvas for clipping content, only recreating
+     * when dimensions change. Eliminates per-frame canvas allocation.
+     */
+    private static _getContentCanvas;
+    /**
+     * Get a pooled offscreen canvas for clipping masks, only recreating
+     * when dimensions change. Eliminates per-frame canvas allocation.
+     */
+    private static _getMaskCanvas;
+    /**
+     * Cached element JSON configs keyed on the elements array reference.
+     * toJSON() calls are expensive at 60fps with 20+ elements.
+     * Safe to cache because knockout/mask metadata (id, blendMode, knockoutParts, masks)
+     * only changes on React state updates, which always produce a new array reference.
+     * Interactive operations (drag, resize) mutate element position in-place on the
+     * same instances without changing the array reference.
+     */
+    private static _cachedElementsRef;
+    private static _cachedElementConfigs;
+    private static _cachedElementMap;
+    /** Reusable Set for tracking knockout-rendered IDs — avoids per-frame allocation. */
+    private static readonly _knockoutRenderedIds;
+    /**
+     * Optional callback for render errors. Set by SnowconeCanvas to forward
+     * rendering errors to the onError prop. When set, individual element render
+     * failures are caught and reported instead of crashing the entire canvas.
+     */
+    static onRenderError: ((error: CanvasError) => void) | null;
+    /**
+     * Safely render an element, catching errors so one element's failure
+     * doesn't crash the entire canvas render loop.
+     */
+    private static safeRender;
+    /**
+     * Helper function to render an element (using actual element instance, not config)
+     * Used by knockout rendering system
+     */
+    private static renderElement;
+    /**
+     * Apply artboard clip path to the context, respecting clipShape.
+     * After calling this, subsequent drawing will be clipped to the artboard shape.
+     * Caller must call ctx.beginPath() before this if needed.
+     */
+    private static applyArtboardClipPath;
+    /**
+     * Render an element with overflow dimming - parts outside the artboard render at 30% opacity
+     * Uses two-pass rendering: first at 30% opacity (overflow), then clipped to artboard at 100% (inside)
+     */
+    private static renderElementWithOverflowDimming;
+    /**
+     * Render all elements layer
+     * @param showOverflowDimmed When true, element parts outside the artboard render at 30% opacity
+     * @param suppressOverflowDim When true, skip the 30% overflow pass even if `showOverflowDimmed`
+     *   is enabled. Used for piece-guide rendering (ADR-0054) where the boundary's custom path
+     *   clipShape is the visible design edge — overflow beyond the rectangular artboard reads as
+     *   a coloured halo rather than useful UX. Selected/hovered elements fall through to the
+     *   clipped-only branch which respects `clipShape` correctly.
+     */
+    static renderElementsLayer(ctx: CanvasRenderingContext2D, elements: BaseElement[], selectedId: string | null, hoverState?: HoverState, stateMachine?: InteractionStateMachine, artboardBackgroundColor?: string, artboard?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        borderRadius?: number;
+        clipShape?: ClipShape;
+    }, isPreview?: boolean, showOverflowDimmed?: boolean, suppressOverflowDim?: boolean): void;
+    /**
+     * Render elements with clipping mask support at artboard level
+     * Elements with isClipping=true clip all elements below them
+     */
+    private static _renderWithClipping;
+    /**
+     * Render snap guides layer
+     * @see InteractionFeedbackRenderer.renderSnapGuidesLayer
+     */
+    static renderSnapGuidesLayer(ctx: CanvasRenderingContext2D, snapGuides?: SnapGuide[]): void;
+    /**
+     * Render spacing indicators layer
+     * @see InteractionFeedbackRenderer.renderSpacingIndicatorsLayer
+     */
+    static renderSpacingIndicatorsLayer(ctx: CanvasRenderingContext2D, spacingIndicators?: SpacingIndicator[]): void;
+    /**
+     * Render a distance label with background
+     * @see InteractionFeedbackRenderer.renderDistanceLabel
+     */
+    static renderDistanceLabel(ctx: CanvasRenderingContext2D, x: number, y: number, distance: number): void;
+    /**
+     * Render selection box layer
+     * @see SelectionRenderer.renderSelectionLayer
+     */
+    static renderSelectionLayer(ctx: CanvasRenderingContext2D, selectedElement: BaseElement | null, stateMachine: InteractionStateMachine, zoom?: number): void;
+    /**
+     * Render position and size info below the selected element
+     * @see SelectionRenderer.renderPositionSizeInfo
+     */
+    static renderPositionSizeInfo(ctx: CanvasRenderingContext2D, selectedElement: BaseElement | null, transformHandles: TransformHandles | null, stateMachine: InteractionStateMachine | null, zoom?: number): void;
+    /**
+     * Render transform handles layer
+     * @see SelectionRenderer.renderHandlesLayer
+     */
+    static renderHandlesLayer(ctx: CanvasRenderingContext2D, selectedElement: BaseElement | null, transformHandles: TransformHandles, currentRotation: number, isRotating: boolean, hoverState: HoverState, stateMachine: InteractionStateMachine, zoom?: number, showRotationHandle?: boolean): void;
+    /**
+     * Render hover highlights layer with fade-in animation
+     * @see HoverRenderer.renderHoverLayer
+     */
+    static renderHoverLayer(ctx: CanvasRenderingContext2D, hoverState: HoverState, selectedId: string | null, _isAltKeyPressed?: boolean, zoom?: number, artboardBackgroundColor?: string): void;
+    /**
+     * Render crop box layer (for images in crop mode)
+     * @see EditModeRenderer.renderCropBoxLayer
+     */
+    static renderCropBoxLayer(ctx: CanvasRenderingContext2D, selectedElement: BaseElement, transformHandles: TransformHandles, zoom?: number): void;
+    /**
+     * Complete rendering pipeline
+     * Renders all layers in correct z-order
+     */
+    static render({ ctx, elements, selectedId, selectedElement, hoverState, isEditing, stateMachine, snapGuides, spacingIndicators, artboardBackgroundColor, artboard, isPreview, zoom, paddingOffset, showOverflowDimmed, suppressOverflowDim, distressTexture, imageMask, editModeData, }: {
+        ctx: CanvasRenderingContext2D;
+        elements: BaseElement[];
+        selectedId: string | null;
+        selectedElement: BaseElement | null;
+        transformHandles: TransformHandles | null;
+        currentRotation: number;
+        isRotating: boolean;
+        hoverState: HoverState;
+        isEditing: boolean;
+        stateMachine: InteractionStateMachine | null;
+        snapGuides?: SnapGuide[];
+        spacingIndicators?: SpacingIndicator[];
+        hideHandles?: boolean;
+        isAltKeyPressed?: boolean;
+        artboardBackgroundColor?: string;
+        artboard?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+            borderRadius?: number;
+            clipShape?: ClipShape;
+        };
+        isPreview?: boolean;
+        zoom?: number;
+        paddingOffset?: {
+            x: number;
+            y: number;
+        };
+        /** When true, element parts outside the artboard render at 30% opacity */
+        showOverflowDimmed?: boolean;
+        /**
+         * When true, skip the 30% overflow-dim pass even if `showOverflowDimmed` is on.
+         * Used by ADR-0054 piece-guide rendering: the boundary's custom path clipShape is
+         * the visible design edge, so the rectangular-artboard overflow halo reads as
+         * coloured noise rather than useful UX. Selected elements fall through to the
+         * clipped-only branch, which respects `clipShape` correctly.
+         */
+        suppressOverflowDim?: boolean;
+        /** Whether to show the rotation handle (defaults to true, set false for embedded mode) */
+        showRotationHandle?: boolean;
+        /** Artboard-level distress texture (applied after elements, before UI layers) */
+        distressTexture?: ArtboardDistressTexture;
+        /** Artboard-level image mask (applied after distress texture, before UI layers) */
+        imageMask?: import('../types/index.js').ArtboardImageMask;
+        editModeData?: {
+            cursorPosition: number;
+            selectionStart: number;
+            selectionEnd: number;
+            editText: string;
+            editRichText: RichText | null;
+            cursorOpacity: number;
+        };
+    }): void;
+    /**
+     * Single-selection interaction chrome: bbox, handles, position/size
+     * info, hover outline, and the crop-mode alt branch. Hoisted out of
+     * `render()` so the master render loop can call it *after*
+     * `renderPieceGuides`. Otherwise the piece-guide partial die-cut
+     * knockout (`destination-out` at alpha 0.7) erases 70% of the
+     * chrome's alpha along with the artwork it's intentionally dimming.
+     *
+     * Renders at native screen scale: identical transform manipulation
+     * to the original Layer 2 / 3–6 block in `render()` so chrome stays
+     * crisp regardless of canvas zoom.
+     */
+    static renderInteractionChromeLayer({ ctx, selectedElement, transformHandles, stateMachine, currentRotation, isRotating, hoverState, selectedId, hideHandles, isEditing, isAltKeyPressed, artboardBackgroundColor, hoverClipArtboard, showRotationHandle, zoom, paddingOffset, }: {
+        ctx: CanvasRenderingContext2D;
+        selectedElement: BaseElement | null;
+        transformHandles: TransformHandles | null;
+        stateMachine: InteractionStateMachine | null;
+        currentRotation: number;
+        isRotating: boolean;
+        hoverState: HoverState;
+        selectedId: string | null;
+        hideHandles?: boolean;
+        isEditing: boolean;
+        isAltKeyPressed?: boolean;
+        artboardBackgroundColor?: string;
+        /**
+         * Optional clip rect (in world coords) confining the hover outline
+         * to the visible artboard / piece bounds. Selection chrome ignores
+         * this — once the user commits to a selection they want to see the
+         * full extent of the element. The hover outline though was reading
+         * as noisy when the cursor moved over an element that extended past
+         * the piece edge, since the hover ring was drawn into the overflow
+         * region on top of the dimmed surrounding canvas.
+         */
+        hoverClipArtboard?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+            borderRadius?: number;
+            clipShape?: ClipShape;
+        };
+        showRotationHandle?: boolean;
+        zoom?: number;
+        paddingOffset?: {
+            x: number;
+            y: number;
+        };
+    }): void;
+}
+export {};