@snowcone-app/canvas 0.1.0

package/dist/components/embed/SnowconeCanvas.d.ts

@@ -0,0 +1,844 @@
+import { default as React } from 'react';
+import { CanvasError, ClipShape, AnyElementConfig } from '../../types/index.js';
+import { KitPresetId, KitDefinition } from '../../kits/types.js';
+import { PieceGuide, PieceGuideRendererPiece, PieceGuideRendererStyle, PieceGuideVisibility } from '../../rendering/PieceGuideRenderer.js';
+export type { ClipShape } from '../../types/index.js';
+/** 9-point alignment grid values */
+export type AlignmentPoint = 'tl' | 't' | 'tr' | 'l' | 'c' | 'r' | 'bl' | 'b' | 'br' | 'center' | 'top' | 'bottom' | 'left' | 'right';
+/** Events emitted during the export lifecycle */
+export type ExportStatusEvent = {
+    status: 'scheduled';
+    artboardId: string;
+} | {
+    status: 'rendering';
+    artboardId: string;
+} | {
+    status: 'complete';
+    artboardId: string;
+    result: Record<string, string | Blob>;
+} | {
+    status: 'error';
+    artboardId: string;
+    error: Error;
+};
+export interface ArtboardConfig {
+    /** Display name for the artboard (used as key in export results) */
+    name: string;
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+    /** Optional clip shape for content masking */
+    clipShape?: ClipShape;
+    /** Optional background color */
+    backgroundColor?: string;
+    /** Scale mode for initial image: "cover" fills area (may crop), "contain" fits inside (may have space). Default: "cover" */
+    scaleMode?: 'cover' | 'contain';
+    /** Top margin in pixels for contain mode (reduces available area) */
+    fitMarginTop?: number;
+    /** Right margin in pixels for contain mode (reduces available area) */
+    fitMarginRight?: number;
+    /** Bottom margin in pixels for contain mode (reduces available area) */
+    fitMarginBottom?: number;
+    /** Left margin in pixels for contain mode (reduces available area) */
+    fitMarginLeft?: number;
+    /** Alignment override for contain mode (9-point grid: 'tl','t','tr','l','c','r','bl','b','br') */
+    fitAlign?: AlignmentPoint;
+}
+export interface CanvasState {
+    /** Serialized element configurations for persistence */
+    elements: AnyElementConfig[];
+    /** Artboard configurations */
+    artboards: ArtboardConfig[];
+    /** Currently active artboard name */
+    activeArtboard: string;
+}
+/**
+ * Imperative handle for programmatic control of SnowconeCanvas
+ */
+export interface SnowconeCanvasHandle {
+    /**
+     * Trigger an export of artboards programmatically.
+     * Returns a promise that resolves with the exported artboards.
+     *
+     * @param options Export options
+     * @returns Promise resolving to exported artboards keyed by name
+     *
+     * @example
+     * const canvasRef = useRef<SnowconeCanvasHandle>(null);
+     * const handleExport = async () => {
+     *   const exports = await canvasRef.current?.exportArtboards();
+     *   console.log('Exported:', exports);
+     * };
+     */
+    exportArtboards: (options?: {
+        /** Export format */
+        format?: 'dataUrl' | 'blob';
+        /** Resolution multiplier */
+        scale?: number;
+        /** Export all artboards or just active */
+        all?: boolean;
+    }) => Promise<Record<string, string | Blob>>;
+}
+/**
+ * Configuration for export behavior (scale, format, auto-export).
+ *
+ * Group these props together instead of passing them individually:
+ *
+ * @example
+ * ```tsx
+ * <SnowconeCanvas
+ *   exportConfig={{
+ *     autoExportConfig: { enabled: true, debounceMs: 100, maxWaitMs: 1000 },
+ *     format: 'blob',
+ *     exportAll: true,
+ *     scale: 2,
+ *     maxSize: 4000,
+ *     imageFormat: 'webp',
+ *     imageQuality: 0.85,
+ *   }}
+ *   onExportStatus={(event) => { ... }}
+ * />
+ * ```
+ */
+export interface ExportConfig {
+    /**
+     * Smart auto-export configuration with debouncing and change detection.
+     * Replaces the timer-based `autoExportInterval` with an event-driven approach.
+     */
+    autoExportConfig?: {
+        /** Enable/disable auto-export */
+        enabled?: boolean;
+        /** Debounce delay - wait this long after last change before exporting (ms) */
+        debounceMs?: number;
+        /** Maximum wait time - force export after this duration even if changes keep coming (ms) */
+        maxWaitMs?: number;
+    };
+    /**
+     * Export format: 'dataUrl' (base64 string) or 'blob' (binary).
+     * Blob is more efficient for API uploads.
+     */
+    format?: 'dataUrl' | 'blob';
+    /**
+     * If true, exports all artboards on each interval.
+     * If false, only exports the active artboard.
+     */
+    exportAll?: boolean;
+    /**
+     * Resolution multiplier for exports.
+     * Default: 2 (recommended for print quality).
+     *
+     * Note: This scale is applied intelligently - if the resulting image would
+     * exceed `maxSize`, the scale is reduced to cap the largest dimension.
+     */
+    scale?: number;
+    /**
+     * Maximum export dimension (largest side) in pixels.
+     * Default: 4000 (4K).
+     *
+     * When the artboard dimensions multiplied by scale would exceed this,
+     * the effective scale is reduced to cap the output at this size.
+     * Set to 0 or Infinity to disable this capping behavior.
+     */
+    maxSize?: number;
+    /**
+     * Image format for auto-exports.
+     * Default: 'png'.
+     * Use 'webp' for smaller file sizes with transparency support (good for realtime preview).
+     */
+    imageFormat?: 'png' | 'jpg' | 'jpeg' | 'webp';
+    /**
+     * Image quality for auto-exports (0-1).
+     * Only applies to JPEG and WebP formats. PNG ignores this.
+     * Default: 0.92.
+     */
+    imageQuality?: number;
+}
+/**
+ * Configuration for the initial image loaded into the canvas.
+ *
+ * @example
+ * ```tsx
+ * <SnowconeCanvas
+ *   imageConfig={{
+ *     src: 'https://example.com/artwork.png',
+ *     alignment: 'center',
+ *     scale: 1.2,
+ *     scaleMode: 'contain',
+ *   }}
+ * />
+ * ```
+ */
+export interface ImageConfig {
+    /**
+     * URL of initial image to load into the canvas.
+     * Shows loading state while fetching, error state on failure.
+     */
+    src?: string;
+    /**
+     * Alignment for the initial image on the artboard.
+     * Uses a 9-point grid: 'tl', 't', 'tr', 'l', 'c', 'r', 'bl', 'b', 'br'
+     * Or semantic values: 'center', 'top', 'bottom', 'left', 'right'
+     * Default: 'center'
+     */
+    alignment?: AlignmentPoint;
+    /**
+     * Scale multiplier for the initial image.
+     * Default: 1 (image covers artboard exactly)
+     * Values > 1 make the image larger, < 1 make it smaller.
+     */
+    scale?: number;
+    /**
+     * Scale mode for initial image placement.
+     * - "cover" (default): image fills artboard completely, may crop edges
+     * - "contain": image fits entirely inside artboard, may have empty space
+     */
+    scaleMode?: 'cover' | 'contain';
+}
+/**
+ * Configuration for layout and visual appearance of the canvas.
+ *
+ * @example
+ * ```tsx
+ * <SnowconeCanvas
+ *   layoutConfig={{
+ *     width: 1200,
+ *     height: 1200,
+ *     viewPadding: 0.85,
+ *     artboardBorderRadius: 12,
+ *     showToolbar: false,
+ *     showLayers: false,
+ *   }}
+ * />
+ * ```
+ */
+export interface LayoutConfig {
+    /**
+     * Artboard width (shorthand for single artboard).
+     * If `artboards` prop is provided, this is ignored.
+     */
+    width?: number;
+    /**
+     * Artboard height (shorthand for single artboard).
+     * If `artboards` prop is provided, this is ignored.
+     */
+    height?: number;
+    /**
+     * Controls how much of the container the artboard fills.
+     * Value between 0 and 1, where 1 means the artboard fills 100% of the container.
+     * Default is 0.9 (90%).
+     */
+    viewPadding?: number;
+    /**
+     * Border radius for artboard corners in pixels.
+     * This is a visual-only effect - exports will still have the full artboard.
+     * @default 0
+     */
+    artboardBorderRadius?: number;
+    /**
+     * Fixed screen-space margin in pixels.
+     * When set, the artboard will have this exact left/top margin regardless of zoom level.
+     * Overrides viewPadding for positioning.
+     */
+    fixedMargin?: number;
+    /**
+     * Maximum HTML height in pixels.
+     * When the artboard (with vertical fixedMargin padding) would exceed this height,
+     * horizontal padding is increased to shrink the artboard until it fits.
+     */
+    maxHeight?: number;
+    /**
+     * Show toolbar UI.
+     * Default: false (canvas-only mode).
+     */
+    showToolbar?: boolean;
+    /**
+     * Show layers panel.
+     * Default: false (canvas-only mode).
+     */
+    showLayers?: boolean;
+    /**
+     * Whether to show the rotation handle on the canvas.
+     * Set to false for embedded mode where rotation is handled via toolbar panel.
+     * @default true
+     */
+    showRotationHandle?: boolean;
+    /**
+     * When true, hides the internal Canvas component.
+     * Use this when rendering a separate Canvas (e.g., in fullscreen mode)
+     * that shares the same EditorProvider context.
+     */
+    hideCanvas?: boolean;
+    /**
+     * CSS class name for the canvas wrapper element.
+     */
+    canvasWrapperClassName?: string;
+    /**
+     * Inline styles for the canvas wrapper element.
+     */
+    canvasWrapperStyle?: React.CSSProperties;
+    /**
+     * ADR-0054 Phase 4: cutout shapes (in artboard-space px) that get
+     * punched through the `<canvas>` element as truly transparent holes,
+     * revealing whatever sits behind SnowconeCanvas in the DOM. Internally
+     * translated to a CSS `clip-path: path(evenodd, ...)` that accounts
+     * for the canvas's padding margin and zoom. Each shape is a rect,
+     * rounded rect, or SVG path — the same `SvgPath` shape used by the
+     * `VisualGuideOverlay`.
+     */
+    canvasCutouts?: CanvasCutoutShape[];
+}
+/**
+ * ADR-0054: piece-guide config passed to `SnowconeCanvas`. The render
+ * loop calls `renderPieceGuides` with these values after drawing the
+ * artboard and its elements, so boundary/zone/label coordinates are in
+ * the artboard's local pixel frame and compose cleanly with the canvas
+ * viewport transform.
+ */
+export interface PieceGuidesConfig {
+    /** Pieces (artboard-space rects) the guides attach to. */
+    pieces: PieceGuideRendererPiece[];
+    /** Authored guides keyed by piece id. Pieces without a guide fall back to the piece rect. */
+    guides?: Record<string, PieceGuide>;
+    /** Per-layer visibility toggles. All default to true. */
+    show?: PieceGuideVisibility;
+    /** Optional style overrides. */
+    style?: PieceGuideRendererStyle;
+}
+/** ADR-0054 Phase 4: shape union used for `canvasCutouts`. Mirrors the
+ *  `SvgPath` shape in `VisualGuideOverlay`. Coordinates are in artboard
+ *  pixel units (the canvas's intrinsic/native size). */
+export type CanvasCutoutShape = {
+    kind: "rect";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | {
+    kind: "roundedRect";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rx?: number;
+    ry?: number;
+} | {
+    kind: "path";
+    d: string;
+};
+/**
+ * Props for the SnowconeCanvas component.
+ *
+ * Props can be passed individually (flat) or grouped using config objects.
+ * When both are provided, individual props take precedence over config values.
+ *
+ * @example Grouped config pattern (recommended for new code)
+ * ```tsx
+ * <SnowconeCanvas
+ *   artboards={[{ name: 'Front', width: 1200, height: 1200 }]}
+ *   imageConfig={{
+ *     src: 'https://example.com/artwork.png',
+ *     alignment: 'center',
+ *     scaleMode: 'contain',
+ *   }}
+ *   exportConfig={{
+ *     autoExportConfig: { enabled: true, debounceMs: 100 },
+ *     format: 'blob',
+ *     scale: 2,
+ *     imageFormat: 'webp',
+ *   }}
+ *   layoutConfig={{
+ *     viewPadding: 0.85,
+ *     artboardBorderRadius: 12,
+ *     showRotationHandle: false,
+ *   }}
+ *   onExportStatus={(event) => { ... }}
+ * />
+ * ```
+ *
+ * @example Flat props (backwards compatible, still fully supported)
+ * ```tsx
+ * <SnowconeCanvas
+ *   artboards={[{ name: 'Front', width: 1200, height: 1200 }]}
+ *   initialImage="https://example.com/artwork.png"
+ *   autoExportConfig={{ enabled: true, debounceMs: 100 }}
+ *   autoExportFormat="blob"
+ *   exportScale={2}
+ *   viewPadding={0.85}
+ *   onExportStatus={(event) => { ... }}
+ * />
+ * ```
+ */
+export interface SnowconeCanvasProps {
+    /**
+     * Grouped export configuration. See {@link ExportConfig}.
+     * Individual export props (autoExportConfig, autoExportFormat, etc.) take precedence if also provided.
+     */
+    exportConfig?: ExportConfig;
+    /**
+     * Grouped initial image configuration. See {@link ImageConfig}.
+     * Individual image props (initialImage, initialImageAlignment, etc.) take precedence if also provided.
+     */
+    imageConfig?: ImageConfig;
+    /**
+     * Grouped layout/appearance configuration. See {@link LayoutConfig}.
+     * Individual layout props (width, height, viewPadding, etc.) take precedence if also provided.
+     */
+    layoutConfig?: LayoutConfig;
+    /**
+     * Editor kit configuration. Use a preset name ('compact-customizer', 'pro-studio', 'embed-only')
+     * or a custom KitDefinition for full control over layout, capabilities, and behavior.
+     * @default 'pro-studio'
+     */
+    kit?: KitPresetId | KitDefinition;
+    /**
+     * Array of artboard configurations.
+     * Each artboard represents a placement area (e.g., 'Front', 'Back').
+     */
+    artboards?: ArtboardConfig[];
+    /**
+     * Currently active artboard by name.
+     * Used for controlled artboard selection.
+     */
+    activeArtboard?: string;
+    /**
+     * Callback when user switches artboards.
+     * Receives the name of the newly active artboard.
+     */
+    onArtboardChange?: (name: string) => void;
+    /**
+     * Artboard width (shorthand for single artboard).
+     * If `artboards` prop is provided, this is ignored.
+     * @deprecated Use `layoutConfig.width` instead.
+     */
+    width?: number;
+    /**
+     * Artboard height (shorthand for single artboard).
+     * If `artboards` prop is provided, this is ignored.
+     * @deprecated Use `layoutConfig.height` instead.
+     */
+    height?: number;
+    /**
+     * URL of initial image to load into the canvas.
+     * Shows loading state while fetching, error state on failure.
+     *
+     * The image will be sized to "cover" the artboard (like CSS object-fit: cover)
+     * and positioned according to `initialImageAlignment`.
+     * @deprecated Use `imageConfig.src` instead.
+     */
+    initialImage?: string;
+    /**
+     * Alignment for the initial image on the artboard.
+     * Uses a 9-point grid: 'tl', 't', 'tr', 'l', 'c', 'r', 'bl', 'b', 'br'
+     * Or semantic values: 'center', 'top', 'bottom', 'left', 'right'
+     *
+     * Default: 'center' (places image centered on artboard)
+     * @deprecated Use `imageConfig.alignment` instead.
+     */
+    initialImageAlignment?: AlignmentPoint;
+    /**
+     * Scale multiplier for the initial image.
+     * Default: 1 (image covers artboard exactly)
+     * Values > 1 make the image larger, < 1 make it smaller.
+     * @deprecated Use `imageConfig.scale` instead.
+     */
+    initialImageScale?: number;
+    /**
+     * Scale mode for initial image placement.
+     * - "cover" (default): image fills artboard completely, may crop edges
+     * - "contain": image fits entirely inside artboard, may have empty space
+     * @deprecated Use `imageConfig.scaleMode` instead.
+     */
+    initialImageScaleMode?: 'cover' | 'contain';
+    /**
+     * Serialized element configurations for restoring saved state.
+     * Use this to restore a previously saved design.
+     */
+    initialElements?: AnyElementConfig[];
+    /**
+     * Called when canvas content changes (elements added, modified, or removed).
+     * Use this to persist the design state.
+     */
+    onChange?: (state: CanvasState) => void;
+    /**
+     * Called when selection changes.
+     * Receives null when nothing is selected.
+     */
+    onSelectionChange?: (elementId: string | null) => void;
+    /**
+     * Interval in milliseconds for automatic exports.
+     * Set to 0 or undefined to disable auto-export.
+     * Recommended: 500ms for responsive preview updates.
+     *
+     * @deprecated Use `autoExportConfig` or `exportConfig.autoExportConfig` instead, which provides smart debouncing and change detection rather than fixed-interval polling.
+     */
+    autoExportInterval?: number;
+    /**
+     * Smart auto-export configuration with debouncing and change detection.
+     * Replaces the timer-based `autoExportInterval` with an event-driven approach.
+     * @deprecated Use `exportConfig.autoExportConfig` instead.
+     *
+     * @example
+     * ```tsx
+     * <SnowconeCanvas
+     *   autoExportConfig={{
+     *     enabled: true,
+     *     debounceMs: 100,   // Wait 100ms after last change
+     *     maxWaitMs: 1000,   // Force export after 1s of continuous changes
+     *   }}
+     *   onExport={(exports) => console.log('Exported:', exports)}
+     * />
+     * ```
+     */
+    autoExportConfig?: {
+        /** Enable/disable auto-export */
+        enabled?: boolean;
+        /** Debounce delay - wait this long after last change before exporting (ms) */
+        debounceMs?: number;
+        /** Maximum wait time - force export after this duration even if changes keep coming (ms) */
+        maxWaitMs?: number;
+    };
+    /**
+     * Export format: 'dataUrl' (base64 string) or 'blob' (binary).
+     * Blob is more efficient for API uploads.
+     * @deprecated Use `exportConfig.format` instead.
+     */
+    autoExportFormat?: 'dataUrl' | 'blob';
+    /**
+     * If true, exports all artboards on each interval.
+     * If false, only exports the active artboard.
+     * @deprecated Use `exportConfig.exportAll` instead.
+     */
+    autoExportAll?: boolean;
+    /**
+     * Resolution multiplier for exports.
+     * Default: 2 (recommended for print quality).
+     *
+     * Note: This scale is applied intelligently - if the resulting image would
+     * exceed `maxExportSize`, the scale is reduced to cap the largest dimension.
+     * @deprecated Use `exportConfig.scale` instead.
+     */
+    exportScale?: number;
+    /**
+     * Maximum export dimension (largest side) in pixels.
+     * Default: 4000 (4K).
+     *
+     * When the artboard dimensions multiplied by exportScale would exceed this,
+     * the effective scale is reduced to cap the output at this size.
+     *
+     * For example:
+     * - Artboard 3951x4800 with exportScale=2 would normally be 7902x9600
+     * - With maxExportSize=4000, it stays at 3951x4800 (scale effectively 1)
+     * - Artboard 1200x1200 with exportScale=2 becomes 2400x2400 (under limit)
+     *
+     * Set to 0 or Infinity to disable this capping behavior.
+     * @deprecated Use `exportConfig.maxSize` instead.
+     */
+    maxExportSize?: number;
+    /**
+     * Image format for auto-exports.
+     * Default: 'png'.
+     * Use 'webp' for smaller file sizes with transparency support (good for realtime preview).
+     * @deprecated Use `exportConfig.imageFormat` instead.
+     */
+    exportImageFormat?: 'png' | 'jpg' | 'jpeg' | 'webp';
+    /**
+     * Image quality for auto-exports (0-1).
+     * Only applies to JPEG and WebP formats. PNG ignores this.
+     * Default: 0.92.
+     * @deprecated Use `exportConfig.imageQuality` instead.
+     */
+    exportImageQuality?: number;
+    /**
+     * Called with export results.
+     * Results are keyed by artboard name.
+     *
+     * @deprecated Use `onExportStatus` for a unified export lifecycle callback, or `onExportReady` for on-demand export control.
+     */
+    onExport?: (exports: Record<string, string | Blob>) => void;
+    /**
+     * Called immediately when an export is scheduled (before debounce).
+     * Use this to show loading indicators right away instead of waiting for export to complete.
+     * This fires as soon as a change is detected, giving consumers early warning.
+     *
+     * @deprecated Use `onExportStatus` instead, which provides `{ status: 'scheduled' }` events along with the full export lifecycle.
+     *
+     * @example
+     * ```tsx
+     * <SnowconeCanvas
+     *   onExportScheduled={() => {
+     *     // Show shimmer/loading immediately
+     *     setIsExporting(true);
+     *   }}
+     *   onExport={(exports) => {
+     *     // Hide shimmer after export completes
+     *     setIsExporting(false);
+     *   }}
+     * />
+     * ```
+     */
+    onExportScheduled?: () => void;
+    /**
+     * Unified export status callback. Prefer this over individual `onExport`/`onExportScheduled` callbacks.
+     *
+     * Receives events for each phase of the export lifecycle:
+     * - `scheduled` - Export was requested (before debounce completes)
+     * - `rendering` - Export rendering has started
+     * - `complete` - Export finished successfully with results
+     * - `error` - Export failed with an error
+     *
+     * @example
+     * ```tsx
+     * <SnowconeCanvas
+     *   onExportStatus={(event) => {
+     *     switch (event.status) {
+     *       case 'scheduled':
+     *         setIsExporting(true);
+     *         break;
+     *       case 'complete':
+     *         setIsExporting(false);
+     *         uploadResults(event.result);
+     *         break;
+     *       case 'error':
+     *         setIsExporting(false);
+     *         showError(event.error);
+     *         break;
+     *     }
+     *   }}
+     * />
+     * ```
+     */
+    onExportStatus?: (event: ExportStatusEvent) => void;
+    /**
+     * Callback that provides an export function.
+     * Called once when the canvas is ready.
+     * Use this for manual/on-demand exports triggered by UI buttons.
+     *
+     * @example
+     * ```tsx
+     * const [exportFn, setExportFn] = useState<(() => Promise<Record<string, string | Blob>>) | null>(null);
+     *
+     * <SnowconeCanvas
+     *   onExportReady={(fn) => setExportFn(() => fn)}
+     *   ...
+     * />
+     *
+     * <button onClick={() => exportFn?.()}>Export</button>
+     * ```
+     */
+    onExportReady?: (exportFn: () => Promise<Record<string, string | Blob>>) => void;
+    /**
+     * Called when initialImage loads successfully.
+     */
+    onImageLoad?: (src: string) => void;
+    /**
+     * Called when initialImage fails to load.
+     */
+    onImageError?: (src: string, error: Error) => void;
+    /**
+     * General error callback for recoverable and non-recoverable canvas errors.
+     * Receives a structured CanvasError with category, message, and context.
+     *
+     * This fires for:
+     * - Image loading failures (category: 'image')
+     * - Export errors (category: 'export')
+     * - Element import/deserialization errors (category: 'import')
+     * - Unexpected React crashes caught by ErrorBoundary (category: 'unknown')
+     *
+     * Existing `onExportStatus` and `onImageError` callbacks continue to work.
+     * `onError` provides a unified stream of all errors for logging/analytics.
+     *
+     * @example
+     * ```tsx
+     * <SnowconeCanvas
+     *   onError={(error) => {
+     *     console.error(`[${error.category}] ${error.message}`);
+     *     if (!error.recoverable) {
+     *       analytics.track('canvas_crash', { category: error.category });
+     *     }
+     *   }}
+     * />
+     * ```
+     */
+    onError?: (error: CanvasError) => void;
+    /**
+     * Theme name (reserved for future use).
+     */
+    theme?: string;
+    /**
+     * When true, skips the internal ThemeProvider and inherits theme from parent.
+     * Use this when embedding SnowconeCanvas in an app that already manages themes.
+     * This prevents the canvas from overriding the parent app's theme on document.documentElement.
+     *
+     * @default false
+     */
+    inheritTheme?: boolean;
+    /**
+     * When true, assumes EditorProvider already exists in a parent component.
+     * Skips creating the internal EditorProvider so multiple SnowconeCanvas instances
+     * can share the same editor state (e.g., when conditionally rendering mobile/desktop layouts).
+     *
+     * @default false
+     */
+    externalProvider?: boolean;
+    /**
+     * CSS class name for the container.
+     */
+    className?: string;
+    /**
+     * Inline styles for the container.
+     */
+    style?: React.CSSProperties;
+    /**
+     * CSS class name for the canvas wrapper element.
+     * Use this to apply CSS masks, clips, or other effects to just the canvas
+     * without affecting the overlay elements.
+     * @deprecated Use `layoutConfig.canvasWrapperClassName` instead.
+     */
+    canvasWrapperClassName?: string;
+    /**
+     * Inline styles for the canvas wrapper element.
+     * Use this to apply CSS masks, clips, or other effects to just the canvas
+     * without affecting the overlay elements.
+     * @deprecated Use `layoutConfig.canvasWrapperStyle` instead.
+     */
+    canvasWrapperStyle?: React.CSSProperties;
+    /**
+     * ADR-0054 Phase 4: shapes punched through the `<canvas>` as truly
+     * transparent holes. See matching field on LayoutConfig for details.
+     * Takes precedence over `layoutConfig.canvasCutouts`.
+     */
+    canvasCutouts?: CanvasCutoutShape[];
+    /**
+     * ADR-0054: piece boundary / safe-area / zone / label overlays drawn
+     * directly into the canvas render loop (no DOM SVG overlay). Pieces
+     * are in artboard-space coordinates (same frame as placements and
+     * `canvasCutouts`). `guides` is keyed by piece id. Supply `undefined`
+     * or omit to skip piece-guide rendering entirely.
+     *
+     * Replaces the old `VisualGuideOverlay` sibling-overlay pattern —
+     * drawing directly in the ctx means no fixedMargin-unit / aspect-
+     * ratio-letterbox / canvas-wrapper-negative-margin shenanigans.
+     */
+    pieceGuides?: PieceGuidesConfig;
+    /**
+     * ADR-0060: viewport focus mode for multi-piece spread layouts.
+     *
+     * - Omit / `'spread'` — show the entire artboard with all pieces
+     *   visible (historical behaviour). The toggle is a no-op for
+     *   single-piece layouts.
+     * - `{ pieceId: 'front' }` — fit the viewport to that piece's
+     *   rect plus a peek margin so neighbour pieces remain visible
+     *   at the edges (dimmed) for overflow feedback. The piece id
+     *   must match an entry in `pieceGuides.pieces[]`; unrecognised
+     *   ids fall back to spread mode.
+     *
+     * Element data is unaffected — elements always live in spread
+     * (artboard) coordinates regardless of focus. Switching focus is
+     * purely an editor viewport / chrome decision.
+     */
+    pieceFocus?: 'spread' | {
+        pieceId: string;
+    };
+    /**
+     * Show toolbar UI (reserved for future use).
+     * Default: false (canvas-only mode).
+     * @deprecated Use `layoutConfig.showToolbar` instead.
+     */
+    showToolbar?: boolean;
+    /**
+     * Show layers panel (reserved for future use).
+     * Default: false (canvas-only mode).
+     * @deprecated Use `layoutConfig.showLayers` instead.
+     */
+    showLayers?: boolean;
+    /**
+     * Enable keyboard shortcuts.
+     * Default: true.
+     */
+    enableShortcuts?: boolean;
+    /**
+     * Render custom controls on top of the canvas.
+     * Useful for adding menu buttons, toolbars, etc.
+     * The overlay is rendered inside the EditorProvider context.
+     */
+    overlay?: React.ReactNode;
+    /**
+     * When true, hides the internal Canvas component.
+     * Use this when rendering a separate Canvas (e.g., in fullscreen mode)
+     * that shares the same EditorProvider context.
+     * This prevents two Canvas components from fighting over the same refs.
+     * @deprecated Use `layoutConfig.hideCanvas` instead.
+     */
+    hideCanvas?: boolean;
+    /**
+     * Controls how much of the container the artboard fills.
+     * 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.
+     * Use smaller values (e.g., 0.8) to show more canvas area around the artboard,
+     * which is useful for seeing selection handles that extend beyond the artboard.
+     * @deprecated Use `layoutConfig.viewPadding` instead.
+     */
+    viewPadding?: number;
+    /**
+     * Border radius for artboard corners in pixels.
+     * Use this to give the artboard rounded corners in the editor.
+     * This is a visual-only effect - exports will still have the full artboard.
+     * @default 0
+     * @deprecated Use `layoutConfig.artboardBorderRadius` instead.
+     */
+    artboardBorderRadius?: number;
+    /**
+     * Fixed screen-space margin in pixels.
+     * When set, the artboard will have this exact left/top margin regardless of zoom level.
+     * This is useful for aligning the artboard with fixed-position UI elements like headers.
+     * Overrides viewPadding for positioning (viewPadding still affects zoom calculation).
+     * @deprecated Use `layoutConfig.fixedMargin` instead.
+     */
+    fixedMargin?: number;
+    /**
+     * Maximum HTML height in pixels.
+     * When the artboard (with vertical fixedMargin padding) would exceed this height,
+     * horizontal padding is increased to shrink the artboard until it fits within
+     * this constraint while still respecting vertical fixedMargin.
+     * @deprecated Use `layoutConfig.maxHeight` instead.
+     */
+    maxHeight?: number;
+    /**
+     * Whether to show the rotation handle on the canvas.
+     * Set to false for embedded mode where rotation is handled via toolbar panel.
+     * @default true
+     * @deprecated Use `layoutConfig.showRotationHandle` instead.
+     */
+    showRotationHandle?: boolean;
+    /**
+     * Called once when the canvas is fully ready for interaction and export.
+     * Fires after: artboards initialized, initial elements loaded, fonts ready,
+     * and at least one render frame completed.
+     */
+    onReady?: () => void;
+}
+/**
+ * SnowconeCanvas - Self-contained embeddable canvas editor
+ * Wraps with ThemeProvider and EditorProvider for full functionality
+ *
+ * @example With imperative export
+ * ```tsx
+ * const canvasRef = useRef<SnowconeCanvasHandle>(null);
+ *
+ * const handleExport = async () => {
+ *   const exports = await canvasRef.current?.exportArtboards();
+ *   console.log('Exported:', exports);
+ * };
+ *
+ * return <SnowconeCanvas ref={canvasRef} ... />;
+ * ```
+ *
+ * @example Embedded in app with existing theme
+ * ```tsx
+ * // When your app already manages themes, use inheritTheme to prevent conflicts
+ * <SnowconeCanvas inheritTheme ... />
+ * ```
+ */
+export declare const SnowconeCanvas: React.ForwardRefExoticComponent<SnowconeCanvasProps & React.RefAttributes<SnowconeCanvasHandle>>;
+export default SnowconeCanvas;