@snowcone-app/canvas 0.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,765 @@
+/**
+ * Comprehensive TypeScript type definitions for custom-canvas
+ * Uses discriminated unions for type-safe transform handling
+ */
+export type TransformType = 'custom' | 'distort' | 'circle' | 'lean' | 'arch' | 'ascend' | 'wave' | 'flag' | 'image' | 'group' | 'artboard' | 'shape' | 'path';
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export type ResizeAnchor = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'top' | 'bottom' | 'left' | 'right' | 'middle-left' | 'middle-right' | 'middle-top' | 'middle-bottom';
+export type TextAlign = 'left' | 'center' | 'right';
+export interface CustomTransformData {
+    type: 'custom';
+    controlPoints: Point[];
+    /** Container width for text wrapping */
+    width: number;
+}
+export interface DistortTransformData {
+    type: 'distort';
+    [key: string]: unknown;
+}
+export interface CircleTransformData {
+    type: 'circle';
+    radius: number;
+    scale: number;
+    reverse: boolean;
+}
+export interface LeanTransformData {
+    type: 'lean';
+    leanAmount: number;
+    /** Container width for text layout */
+    width: number;
+}
+export interface ArchTransformData {
+    type: 'arch';
+    archHeight: number;
+    /** Container width for text layout */
+    width: number;
+}
+export interface AscendTransformData {
+    type: 'ascend';
+    ascendAngle: number;
+    /** Container width for text layout */
+    width: number;
+}
+export interface WaveTransformData {
+    type: 'wave';
+    amplitude: number;
+    frequency: number;
+    /** Container width for text layout */
+    width: number;
+}
+export interface FlagTransformData {
+    type: 'flag';
+    amplitude: number;
+    frequency: number;
+    /** Container width for text layout */
+    width: number;
+}
+export interface ImageTransformData {
+    type: 'image';
+    width: number;
+    height: number;
+    cropX: number;
+    cropY: number;
+    cropWidth: number;
+    cropHeight: number;
+    flipHorizontal: boolean;
+    flipVertical: boolean;
+    borderRadius: number;
+}
+export interface GroupTransformData {
+    type: 'group';
+}
+export interface ArtboardTransformData {
+    type: 'artboard';
+}
+export type ShapeType = 'rectangle' | 'circle' | 'ellipse' | 'triangle' | 'polygon' | 'star' | 'line';
+export interface ShapeTransformData {
+    type: 'shape';
+    shapeType: ShapeType;
+    width: number;
+    height: number;
+    borderRadius?: number;
+    radiusX?: number;
+    radiusY?: number;
+    sides?: number;
+    points?: number;
+    innerRadius?: number;
+    fillColor?: string;
+    fillOpacity?: number;
+}
+/**
+ * Path point types define how curve handles behave
+ */
+export type PathPointType = 'corner' | 'smooth' | 'bezier';
+/**
+ * A single point in a path with optional bezier control handles
+ * All coordinates are relative to the path element's position
+ */
+export interface PathPoint {
+    id: string;
+    x: number;
+    y: number;
+    type: PathPointType;
+    handleIn?: Point;
+    handleOut?: Point;
+}
+/**
+ * Transform data for custom path elements
+ */
+export interface PathTransformData {
+    type: 'path';
+    points: PathPoint[];
+    closed: boolean;
+    width: number;
+    height: number;
+    fillEnabled?: boolean;
+    fillColor?: string;
+    fillOpacity?: number;
+    strokeEnabled?: boolean;
+    strokeColor?: string;
+    strokeWidth?: number;
+}
+export type AnyTransformData = CustomTransformData | DistortTransformData | CircleTransformData | LeanTransformData | ArchTransformData | AscendTransformData | WaveTransformData | FlagTransformData | ImageTransformData | GroupTransformData | ArtboardTransformData | ShapeTransformData | PathTransformData;
+export interface TransformStartData {
+    id: string;
+    x: number;
+    y: number;
+    rotation: number;
+    transformData: Record<string, any>;
+    width?: number;
+    height?: number;
+    fontSize?: number;
+    richText?: unknown;
+    lineCount?: number;
+    visualX?: number;
+    visualY?: number;
+    visualWidth?: number;
+    visualHeight?: number;
+    bboxX?: number;
+    bboxY?: number;
+    cropX?: number;
+    cropY?: number;
+    cropWidth?: number;
+    cropHeight?: number;
+    strokeWidth?: number;
+    childrenStartData?: TransformStartData[];
+    [key: string]: unknown;
+}
+export type BlendMode = 'normal' | 'knockout' | 'clip';
+export type CompositingScope = 'group' | 'artboard';
+export type KnockoutScope = CompositingScope;
+export interface CompositingConfig {
+    fill?: boolean;
+    stroke?: boolean;
+    scope?: CompositingScope;
+}
+export type KnockoutConfig = CompositingConfig;
+export interface StrokeConfig {
+    enabled: boolean;
+    color: string;
+    width: number;
+    dashArray?: number[];
+    lineCap?: 'butt' | 'round' | 'square';
+    lineJoin?: 'miter' | 'round' | 'bevel';
+    miterLimit?: number;
+    opacity?: number;
+    feather?: number;
+}
+/**
+ * Rendering context metadata passed to renderers
+ * Used to customize rendering behavior for specific contexts (e.g., knockout, export, preview)
+ */
+export interface RenderingContext {
+    /** True when rendering for knockout compositing (affects stroke color/opacity) */
+    isKnockout?: boolean;
+    /** True when rendering for export (may skip certain preview-only features) */
+    isExport?: boolean;
+    /** True when rendering for mask application */
+    isMask?: boolean;
+    /** True when the caller has already applied element positioning (translate/rotate) */
+    positionApplied?: boolean;
+}
+export type MaskType = 'clip' | 'alpha' | 'luma' | 'distress';
+export interface MaskDefinition {
+    id: string;
+    type: MaskType;
+    maskElement: AnyElementConfig;
+    inverted?: boolean;
+    feather?: number;
+    opacity?: number;
+    blendMode?: string;
+}
+export type DistressStyle = 'worn' | 'cracked' | 'grunge' | 'retro' | 'custom';
+export interface DistressEffect {
+    enabled: boolean;
+    style: DistressStyle;
+    intensity: number;
+    fadeAmount?: number;
+    grainAmount?: number;
+    scratchAmount?: number;
+    edgeWear?: number;
+    textureUrl?: string;
+    textureOpacity?: number;
+    textureBlendMode?: 'multiply' | 'screen' | 'overlay';
+    seed?: number;
+}
+/**
+ * Per-character glyph override
+ * Allows substituting specific characters with alternate glyphs from the font
+ */
+export interface GlyphOverride {
+    /** Index of the character in the text string */
+    charIndex: number;
+    /** Glyph index in the font file */
+    glyphIndex: number;
+    /** Unicode codepoint of the original character */
+    unicode: string;
+    /** Human-readable name of the alternate (e.g., "Swash A", "Fancy G") */
+    alternateName?: string;
+}
+/**
+ * OpenType feature settings for advanced typography
+ * Features are applied globally to the entire text element
+ */
+export interface OpenTypeFeatures {
+    /** Standard ligatures (fi, fl, etc.) */
+    liga?: boolean;
+    /** Discretionary ligatures (ct, st, etc.) */
+    dlig?: boolean;
+    /** Contextual alternates */
+    calt?: boolean;
+    /** Swash alternates */
+    swsh?: boolean;
+    /** Small capitals */
+    smcp?: boolean;
+    /** All small capitals */
+    c2sc?: boolean;
+    /** Oldstyle figures (0-9) */
+    onum?: boolean;
+    /** Lining figures (0-9) */
+    lnum?: boolean;
+    /** Tabular figures */
+    tnum?: boolean;
+    /** Proportional figures */
+    pnum?: boolean;
+    /** Stylistic sets (ss01-ss20) */
+    ss01?: boolean;
+    ss02?: boolean;
+    ss03?: boolean;
+    ss04?: boolean;
+    ss05?: boolean;
+    ss06?: boolean;
+    ss07?: boolean;
+    ss08?: boolean;
+    ss09?: boolean;
+    ss10?: boolean;
+    ss11?: boolean;
+    ss12?: boolean;
+    ss13?: boolean;
+    ss14?: boolean;
+    ss15?: boolean;
+    ss16?: boolean;
+    ss17?: boolean;
+    ss18?: boolean;
+    ss19?: boolean;
+    ss20?: boolean;
+    /** Character variants (cv01-cv99) - common ones */
+    cv01?: boolean;
+    cv02?: boolean;
+    cv03?: boolean;
+    cv04?: boolean;
+    cv05?: boolean;
+    /** Glyph composition/decomposition */
+    ccmp?: boolean;
+    /** Localized forms */
+    locl?: boolean;
+    /** Kerning */
+    kern?: boolean;
+    /** Mark positioning */
+    mark?: boolean;
+    /** Mark-to-mark positioning */
+    mkmk?: boolean;
+}
+/**
+ * Metadata about available glyphs for a specific character
+ */
+export interface GlyphAlternate {
+    /** Glyph index in the font file */
+    glyphIndex: number;
+    /** Unicode codepoint this glyph represents */
+    unicode: string;
+    /** Human-readable name (e.g., "A.swash", "g.alt01") */
+    name: string;
+    /** Category of alternate (swash, stylistic, etc.) */
+    category?: 'default' | 'swash' | 'stylistic' | 'contextual' | 'ligature';
+    /** Preview data URL (base64-encoded image) */
+    previewDataUrl?: string;
+}
+/**
+ * Character-level styling properties
+ * Each property is optional - undefined means inherit from element defaults
+ */
+export interface CharacterStyle {
+    /** Text color (CSS color string) */
+    color?: string;
+    /** Font family name */
+    fontFamily?: string;
+    /** Font size in pixels */
+    fontSize?: number;
+    /** Bold weight */
+    bold?: boolean;
+    /** Italic style */
+    italic?: boolean;
+    /** Underline decoration */
+    underline?: boolean;
+    /** Strikethrough decoration */
+    strikethrough?: boolean;
+}
+/**
+ * A span of text with uniform styling
+ * Used for efficient storage of rich text (avoids per-character arrays)
+ */
+export interface TextSpan {
+    /** The text content of this span */
+    text: string;
+    /** Style properties for this span (optional properties inherit from element defaults) */
+    style: CharacterStyle;
+}
+/**
+ * Rich text data structure with helper methods
+ * Stores text as an array of styled spans for efficient rendering
+ */
+export declare class RichText {
+    spans: TextSpan[];
+    constructor(spans?: TextSpan[]);
+    /**
+     * Create RichText from plain text string (no special formatting)
+     */
+    static fromPlainText(text: string, style?: CharacterStyle): RichText;
+    /**
+     * Get the full text content (all spans concatenated)
+     */
+    getText(): string;
+    /**
+     * Get the total character count
+     */
+    getLength(): number;
+    /**
+     * Get the style at a specific character index
+     * @param charIndex Character index (0-based)
+     * @returns The style object for the span containing this character
+     */
+    getStyleAt(charIndex: number): CharacterStyle;
+    /**
+     * Apply a style to a character range
+     * @param start Start index (inclusive)
+     * @param end End index (exclusive)
+     * @param style Style to apply (merged with existing styles)
+     */
+    applyStyle(start: number, end: number, style: CharacterStyle): void;
+    /**
+     * Insert text at a specific position with a given style
+     * @param index Character index to insert at
+     * @param text Text to insert
+     * @param style Style for the inserted text
+     */
+    insert(index: number, text: string, style: CharacterStyle): void;
+    /**
+     * Delete text in a character range
+     * @param start Start index (inclusive)
+     * @param end End index (exclusive)
+     */
+    delete(start: number, end: number): void;
+    /**
+     * Normalize spans by:
+     * 1. Removing empty spans
+     * 2. Merging adjacent spans with identical styles
+     * This prevents fragmentation and improves performance
+     */
+    private normalize;
+    /**
+     * Check if two styles are equal
+     */
+    private stylesEqual;
+    /**
+     * Clone this RichText instance
+     */
+    clone(): RichText;
+    /**
+     * Clear a specific style property from all spans.
+     * Used when element-level property changes should override character-level.
+     * After clearing, spans will inherit the property from element defaults.
+     * @param property The style property to clear (e.g., 'fontFamily', 'bold')
+     */
+    clearStyleProperty(property: keyof CharacterStyle): void;
+    /**
+     * Serialize to JSON
+     */
+    toJSON(): {
+        spans: TextSpan[];
+    };
+    /**
+     * Deserialize from JSON
+     */
+    static fromJSON(json: {
+        spans: TextSpan[];
+    }): RichText;
+}
+export interface BaseElementConfig {
+    id?: string;
+    x?: number;
+    y?: number;
+    rotation?: number;
+    opacity?: number;
+    transformType?: TransformType;
+    transformData?: Partial<AnyTransformData>;
+    blendMode?: BlendMode;
+    knockoutParts?: KnockoutConfig;
+    stroke?: StrokeConfig;
+    masks?: MaskDefinition[];
+    distressEffect?: DistressEffect;
+    name?: string;
+    visible?: boolean;
+    locked?: boolean;
+    isClipping?: boolean;
+}
+export interface BaseTextElementConfig extends BaseElementConfig {
+    richText?: RichText | {
+        spans: TextSpan[];
+    };
+    text?: string;
+    fontSize?: number;
+    fontFamily?: string;
+    color?: string;
+    textAlign?: TextAlign;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    glyphOverrides?: GlyphOverride[];
+    openTypeFeatures?: OpenTypeFeatures;
+}
+export interface CustomElementConfig extends BaseTextElementConfig {
+    transformType: 'custom';
+    transformData?: Partial<CustomTransformData>;
+}
+export interface DistortElementConfig extends BaseTextElementConfig {
+    transformType: 'distort';
+    transformData?: Partial<DistortTransformData>;
+}
+export interface CircleElementConfig extends BaseTextElementConfig {
+    transformType: 'circle';
+    transformData?: Partial<CircleTransformData>;
+}
+export interface LeanElementConfig extends BaseTextElementConfig {
+    transformType: 'lean';
+    transformData?: Partial<LeanTransformData>;
+}
+export interface ArchElementConfig extends BaseTextElementConfig {
+    transformType: 'arch';
+    transformData?: Partial<ArchTransformData>;
+}
+export interface AscendElementConfig extends BaseTextElementConfig {
+    transformType: 'ascend';
+    transformData?: Partial<AscendTransformData>;
+}
+export interface WaveElementConfig extends BaseTextElementConfig {
+    transformType: 'wave';
+    transformData?: Partial<WaveTransformData>;
+}
+export interface FlagElementConfig extends BaseTextElementConfig {
+    transformType: 'flag';
+    transformData?: Partial<FlagTransformData>;
+}
+export interface ImageElementConfig extends BaseElementConfig {
+    transformType: 'image';
+    transformData?: Partial<ImageTransformData>;
+    imageUrl?: string;
+    imageAspectRatio?: number;
+    /**
+     * Callback invoked when the image finishes loading.
+     *
+     * The parameter is an `ImageElement` instance (clone of the loaded element).
+     * Import `ImageElement` from `@snowcone-app/canvas/advanced` to narrow the type.
+     *
+     * @example
+     * ```ts
+     * import type { ImageElement } from '@snowcone-app/canvas/advanced';
+     * const config: ImageElementConfig = {
+     *   transformType: 'image',
+     *   onLoadCallback(el) {
+     *     const img = el as ImageElement;
+     *     console.log(img.id, img.transformData.width);
+     *   },
+     * };
+     * ```
+     */
+    onLoadCallback?(element: BaseElementConfig & {
+        readonly id: string;
+        readonly transformType: 'image';
+    }): void;
+    /**
+     * If true, dimensions (width/height) won't be recalculated when the image loads.
+     * Use this when you've explicitly calculated dimensions (e.g., for "cover" sizing).
+     */
+    preserveDimensions?: boolean;
+}
+export interface GroupElementConfig extends BaseElementConfig {
+    transformType: 'group';
+    transformData?: Partial<GroupTransformData>;
+    children?: AnyElementConfig[];
+}
+export interface ShapeElementConfig extends BaseElementConfig {
+    transformType: 'shape';
+    transformData?: Partial<ShapeTransformData>;
+}
+export interface PathElementConfig extends BaseElementConfig {
+    transformType: 'path';
+    transformData?: Partial<PathTransformData>;
+}
+export type ArtboardBackgroundType = 'color' | 'transparent' | 'texture';
+export interface ArtboardDistressTexture {
+    enabled: boolean;
+    textureUrl: string;
+    intensity: number;
+}
+export interface ArtboardImageMask {
+    enabled: boolean;
+    imageUrl: string;
+    maskType: 'clip' | 'alpha' | 'luma';
+    opacity: number;
+    inverted?: boolean;
+}
+export type ClipShape = 'rectangle' | 'circle' | {
+    type: 'rounded';
+    radius: number;
+} | {
+    type: 'path';
+    d: string;
+} | {
+    type: 'composite-path';
+    pieces: Array<{
+        d: string;
+        x: number;
+        y: number;
+        rotation?: 0 | 90 | 180 | 270;
+        baseWidth?: number;
+        baseHeight?: number;
+    }>;
+};
+export interface ArtboardConfig {
+    id?: string;
+    name?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    backgroundColor?: string;
+    backgroundType?: ArtboardBackgroundType;
+    backgroundTexture?: string;
+    exportBackground?: boolean;
+    elementIds?: string[];
+    transformType?: 'artboard';
+    clipShape?: ClipShape;
+    previewBackgroundColor?: string;
+    distressTexture?: ArtboardDistressTexture;
+    imageMask?: ArtboardImageMask;
+}
+export type AnyElementConfig = CustomElementConfig | DistortElementConfig | CircleElementConfig | LeanElementConfig | ArchElementConfig | AscendElementConfig | WaveElementConfig | FlagElementConfig | ImageElementConfig | GroupElementConfig | ShapeElementConfig | PathElementConfig;
+export type TextOnlyElementConfig = Exclude<AnyElementConfig, ImageElementConfig | ShapeElementConfig | PathElementConfig>;
+export type InteractionMode = 'idle' | 'drag' | 'resize' | 'rotate' | 'crop' | 'pen' | 'edit-path' | 'pinch';
+export interface InteractionContext<T = unknown> {
+    mode: InteractionMode;
+    startX: number;
+    startY: number;
+    startData: TransformStartData;
+    activeHandle?: ResizeAnchor;
+    element: T;
+}
+export interface Command {
+    execute(): void;
+    undo(): void;
+}
+export interface ElementUpdate<T = unknown> {
+    oldElement: T;
+    newElement: T;
+}
+export interface MultiElementUpdate<T = unknown> {
+    updates: Map<string, ElementUpdate<T>>;
+}
+export type SelectionState = {
+    type: 'none';
+} | {
+    type: 'single';
+    elementId: string;
+} | {
+    type: 'multiple';
+    elementIds: Set<string>;
+};
+export interface SnapGuide {
+    type: 'vertical' | 'horizontal';
+    sourceId?: string;
+    targetId?: string;
+    x?: number;
+    y1?: number;
+    y2?: number;
+    y?: number;
+    x1?: number;
+    x2?: number;
+}
+export interface SnapResult {
+    x: number;
+    y: number;
+    snappedX: boolean;
+    snappedY: boolean;
+    guides: SnapGuide[];
+}
+export interface SpacingIndicator {
+    type: 'horizontal' | 'vertical';
+    distance: number;
+    isSnapTarget?: boolean;
+    isAltHover?: boolean;
+    x1?: number;
+    x2?: number;
+    y?: number;
+    x?: number;
+    y1?: number;
+    y2?: number;
+    labelX: number;
+    labelY: number;
+}
+export interface ResizeResult {
+    newWidth: number;
+    newHeight: number;
+    newX: number;
+    newY: number;
+    newRotation: number;
+}
+export interface ResizeParams<T = unknown> {
+    element: T;
+    anchor: ResizeAnchor;
+    dx: number;
+    dy: number;
+    startData: TransformStartData;
+    maintainAspectRatio?: boolean;
+}
+export interface RenderContext {
+    ctx: CanvasRenderingContext2D;
+    isSelected: boolean;
+    isHovered?: boolean;
+    scale?: number;
+}
+export interface HandleInfo {
+    anchor: ResizeAnchor;
+    x: number;
+    y: number;
+    cursor: string;
+}
+export interface TransformControl {
+    key: string;
+    label: string;
+    type?: 'checkbox' | 'slider' | 'select';
+    defaultValue?: number | boolean | string;
+    defaultInternalValue?: number;
+    step?: number;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    toSlider?: (internal: number) => number;
+    fromSlider?: (slider: number) => number;
+    toDisplay?: (internal: number) => string;
+    visibleWhen?: (data: Record<string, unknown>) => boolean;
+}
+export interface TransformTypeDefinition {
+    id: TransformType;
+    label: string;
+    Component: new (config?: Partial<BaseTextElementConfig>) => unknown;
+}
+export type ExtractElementByType<T extends TransformType> = Extract<AnyElementConfig, {
+    transformType: T;
+}>;
+export type ExtractTransformData<T extends TransformType> = Extract<AnyTransformData, {
+    type: T;
+}>;
+export declare function isCustomTransform(data: AnyTransformData): data is CustomTransformData;
+export declare function isDistortTransform(data: AnyTransformData): data is DistortTransformData;
+export declare function isCircleTransform(data: AnyTransformData): data is CircleTransformData;
+export declare function isLeanTransform(data: AnyTransformData): data is LeanTransformData;
+export declare function isArchTransform(data: AnyTransformData): data is ArchTransformData;
+export declare function isAscendTransform(data: AnyTransformData): data is AscendTransformData;
+export declare function isWaveTransform(data: AnyTransformData): data is WaveTransformData;
+export declare function isFlagTransform(data: AnyTransformData): data is FlagTransformData;
+export declare function isImageTransform(data: AnyTransformData): data is ImageTransformData;
+export declare function isGroupTransform(data: AnyTransformData): data is GroupTransformData;
+export declare function isArtboardTransform(data: AnyTransformData): data is ArtboardTransformData;
+export declare function isTextElementConfig(config: AnyElementConfig): config is TextOnlyElementConfig;
+export declare function isImageElementConfig(config: AnyElementConfig): config is ImageElementConfig;
+export declare function isCustomElementConfig(config: AnyElementConfig): config is CustomElementConfig;
+export declare function isCircleElementConfig(config: AnyElementConfig): config is CircleElementConfig;
+export declare function isLeanElementConfig(config: AnyElementConfig): config is LeanElementConfig;
+export declare function isArchElementConfig(config: AnyElementConfig): config is ArchElementConfig;
+export declare function isAscendElementConfig(config: AnyElementConfig): config is AscendElementConfig;
+export declare function isWaveElementConfig(config: AnyElementConfig): config is WaveElementConfig;
+export declare function isFlagElementConfig(config: AnyElementConfig): config is FlagElementConfig;
+export declare function isGroupElementConfig(config: AnyElementConfig): config is GroupElementConfig;
+export declare function isShapeElementConfig(config: AnyElementConfig): config is ShapeElementConfig;
+export declare function isPathElementConfig(config: AnyElementConfig): config is PathElementConfig;
+export declare function isShapeTransform(data: AnyTransformData): data is ShapeTransformData;
+export declare function isPathTransform(data: AnyTransformData): data is PathTransformData;
+export declare function hasStroke(config: AnyElementConfig): boolean;
+export declare function hasMasks(config: AnyElementConfig): boolean;
+export declare function isKnockout(config: AnyElementConfig): boolean;
+export declare function hasDistressEffect(config: AnyElementConfig): boolean;
+/**
+ * Categories of errors that can occur within the canvas.
+ *
+ * - 'render': Errors during canvas rendering (element draw, compositing)
+ * - 'export': Errors during artboard export (PNG generation, worker failures)
+ * - 'import': Errors loading or deserializing saved state / initial elements
+ * - 'image': Errors loading images (network failures, CORS, decode errors)
+ * - 'worker': Errors in the export web worker
+ * - 'state': Errors in state management (artboard creation, element updates)
+ * - 'unknown': Uncategorized errors caught by the ErrorBoundary
+ */
+export type CanvasErrorCategory = 'render' | 'export' | 'import' | 'image' | 'worker' | 'state' | 'unknown';
+/**
+ * Structured error type for all canvas errors.
+ * Provides consistent error reporting with category, context, and recoverability info.
+ *
+ * @example
+ * ```tsx
+ * <SnowconeCanvas
+ *   onError={(error) => {
+ *     if (error.category === 'image' && error.recoverable) {
+ *       showToast('Image failed to load, please try another');
+ *     } else if (!error.recoverable) {
+ *       reportCrash(error);
+ *     }
+ *   }}
+ * />
+ * ```
+ */
+export interface CanvasError {
+    /** The category of this error */
+    category: CanvasErrorCategory;
+    /** Human-readable error message */
+    message: string;
+    /** The original Error object, if available */
+    originalError?: Error;
+    /** The element ID involved, if applicable */
+    elementId?: string;
+    /** The artboard ID involved, if applicable */
+    artboardId?: string;
+    /** Whether the canvas can continue operating after this error */
+    recoverable: boolean;
+}