@snowcone-app/canvas 0.1.0

package/dist/components/VisualGuideOverlay.d.ts

@@ -0,0 +1,156 @@
+/**
+ * ADR-0054: SVG-based visual-guide overlay.
+ *
+ * Duplicated intentionally between:
+ *   - snowcone-loom/app/components/VisualGuideOverlay.tsx       (Loom editor)
+ *   - ui-components/packages/canvas/src/components/VisualGuideOverlay.tsx
+ *     (this file — consumed by the Snowcone consumer editor via
+ *      @snowcone-app/canvas)
+ * Loom doesn't depend on @snowcone-app/canvas. Keep these two files
+ * byte-identical below the header; if you change one, mirror the other.
+ *
+ * Renders structured piece guides (boundary, safe area, zones, labels) as
+ * stacked SVG layers on top of an artboard preview. The entire overlay
+ * lives inside a single `<svg viewBox="0 0 artboardWidth artboardHeight">`
+ * so piece-local coordinates compose directly and strokes can opt into
+ * `vector-effect="non-scaling-stroke"` to stay visually crisp at every
+ * viewport scale.
+ *
+ * Falls back cleanly when no guides are authored:
+ *   - `boundary` → the piece's bounding rect (0,0 to pieceWidth, pieceHeight)
+ *   - `safeArea` → an inset rect derived from `safeAreaInsetPx` when present,
+ *     omitted otherwise
+ */
+export type SvgPath = {
+    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;
+};
+export interface ZoneShape {
+    kind: "wrap" | "binding" | "dieCut" | "warning" | "custom";
+    label?: string;
+    path: SvgPath;
+}
+export interface GuideLabel {
+    text: string;
+    x: number;
+    y: number;
+    anchor?: "tl" | "tc" | "tr" | "cl" | "c" | "cr" | "bl" | "bc" | "br";
+}
+export interface PieceGuide {
+    boundary?: SvgPath;
+    safeArea?: SvgPath;
+    zones?: ZoneShape[];
+    labels?: GuideLabel[];
+    /**
+     * Corner radius of the piece's *physical outer shape* (e.g. a phone
+     * case's outer curve) in piece-local pixels. When set, the bleed
+     * ring's outer edge uses a rounded rectangle of `(pieceWidth,
+     * pieceHeight)` with this radius, and the entire piece render is
+     * clipped to that shape — so nothing bleeds into the sharp corners
+     * of the piece's bounding rect. Omit / 0 = sharp corners (current
+     * default behaviour).
+     */
+    outerRadius?: number;
+}
+export interface OverlayPiece {
+    /** Stable piece id (matches `placements[].name`). */
+    id: string;
+    /** Piece's top-left position on the artboard, in artboard pixel coords. */
+    x: number;
+    y: number;
+    /** Piece-local dimensions in px. */
+    width: number;
+    height: number;
+    /**
+     * Fallback safe-area inset when no authored `safeArea` is present. In
+     * piece-local pixels (caller converts from inches). Omit to skip the
+     * fallback safe area entirely.
+     */
+    safeAreaInsetPx?: number;
+    /** Clockwise rotation in degrees about the piece center. Default 0. */
+    rotation?: number;
+}
+export interface VisualGuideOverlayStyle {
+    bleedFill?: string;
+    bleedOpacity?: number;
+    boundaryStroke?: string;
+    boundaryStrokeWidth?: number;
+    /**
+     * Safe-area wash: fills the region outside the safe area (inside the
+     * piece) with a semi-transparent color. Replaces the old dashed
+     * safe-area outline as the default — de-emphasizes the bleed margin so
+     * the safe area reads as the "clean" zone without adding line chrome.
+     */
+    safeAreaWashFill?: string;
+    safeAreaWashOpacity?: number;
+    /**
+     * Corner radius (in viewBox px) for the wash's outer edge so it hugs
+     * rounded products (phone cases, rounded cards, etc.) instead of
+     * boxing sharp corners. Pass `0` for hard corners. Omit to use an
+     * artboard-proportional default (~2% of the shorter axis).
+     */
+    safeAreaWashCornerRadius?: number;
+    /**
+     * Safe-area stroke settings — legacy dashed outline. Disabled by default
+     * (wash does the work). Set `safeAreaStroke` to any color to re-enable.
+     */
+    safeAreaStroke?: string;
+    safeAreaStrokeWidth?: number;
+    safeAreaDashArray?: string;
+    zoneFill?: Partial<Record<ZoneShape["kind"], string>>;
+    zoneStroke?: Partial<Record<ZoneShape["kind"], string>>;
+    labelColor?: string;
+    labelFontSize?: number;
+    labelFontFamily?: string;
+}
+export interface VisualGuideOverlayProps {
+    /** Artboard dimensions in px — defines the SVG viewBox. */
+    artboardWidth: number;
+    artboardHeight: number;
+    /**
+     * @deprecated Do not use — leave at 0 (the default).
+     *
+     * This was intended to mirror SnowconeCanvas's `fixedMargin`, but
+     * `fixedMargin` is in CSS pixels (converted to world units via
+     * `worldMargin = fixedMargin / zoom` in useCanvasLayout.ts) while
+     * this prop treated the value as viewBox/world units. The two only
+     * match at zoom === 1, so passing a non-zero value silently drifted
+     * the overlay content by tens of pixels at typical editor zooms.
+     *
+     * Correct usage: keep the SVG viewBox equal to the artboard, and
+     * position the wrapping div with `inset: ${fixedMargin}px` so the
+     * overlay covers only the artboard region of the padded canvas.
+     */
+    canvasPadding?: number;
+    /** Pieces to render guides for. */
+    pieces: OverlayPiece[];
+    /** Authored guides keyed by piece id. Pieces without a guide fall back. */
+    pieceGuides?: Record<string, PieceGuide>;
+    /** Per-layer visibility toggles. All default to true. */
+    show?: {
+        bleed?: boolean;
+        zones?: boolean;
+        boundary?: boolean;
+        safeArea?: boolean;
+        labels?: boolean;
+    };
+    /** Optional style overrides. */
+    style?: VisualGuideOverlayStyle;
+    /** `className` applied to the wrapping SVG element. */
+    className?: string;
+}
+export declare function VisualGuideOverlay({ artboardWidth, artboardHeight, canvasPadding, pieces, pieceGuides, show, style, className, }: VisualGuideOverlayProps): JSX.Element;

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

@@ -0,0 +1,74 @@
+import { default as React } from 'react';
+export interface ArtboardTabsProps {
+    /**
+     * Tab orientation
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Show "Add Artboard" button
+     */
+    showAddButton?: boolean;
+    /**
+     * Show close buttons on tabs
+     */
+    showCloseButtons?: boolean;
+    /**
+     * Maximum tab width (for horizontal tabs)
+     */
+    maxTabWidth?: number;
+    /**
+     * Custom CSS styles
+     */
+    style?: React.CSSProperties;
+    /**
+     * Custom class name
+     */
+    className?: string;
+    /**
+     * Callback when a new artboard is created
+     */
+    onArtboardCreate?: (artboardId: string) => void;
+    /**
+     * Callback when an artboard is deleted
+     */
+    onArtboardDelete?: (artboardId: string) => void;
+}
+/**
+ * Standalone artboard tabs component
+ *
+ * @example Horizontal tabs
+ * ```tsx
+ * function EditorWithTabs() {
+ *   return (
+ *     <EditorProvider>
+ *       <div style={{ height: '100vh', display: 'flex', flexDirection: 'column' }}>
+ *         <ArtboardTabs
+ *           orientation="horizontal"
+ *           showAddButton={true}
+ *           showCloseButtons={true}
+ *         />
+ *         <Canvas />
+ *       </div>
+ *     </EditorProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Vertical tabs
+ * ```tsx
+ * function EditorWithSideTabs() {
+ *   return (
+ *     <EditorProvider>
+ *       <div style={{ display: 'flex' }}>
+ *         <ArtboardTabs
+ *           orientation="vertical"
+ *           showAddButton={true}
+ *         />
+ *         <Canvas />
+ *       </div>
+ *     </EditorProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare const ArtboardTabs: React.FC<ArtboardTabsProps>;

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

@@ -0,0 +1,72 @@
+import { default as React } from 'react';
+export interface CanvasProps {
+    /** CSS class name */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+    /** Viewport width (container size) */
+    width?: number;
+    /** Viewport height (container size) */
+    height?: number;
+    /** Zoom level - if not provided, automatically fits artboard to container */
+    zoom?: number;
+    /** Padding percentage when auto-fitting (0-1, default 0.95 = 95% of container) */
+    fitPadding?: number;
+    /**
+     * Enable interactive pan/zoom mode (infinite canvas)
+     * - Scroll wheel: zoom in/out
+     * - Space+drag or middle mouse: pan
+     */
+    interactive?: boolean;
+    /** Border radius for artboard corners (in pixels) */
+    artboardBorderRadius?: number;
+    /**
+     * Fixed screen-space margin in pixels (overrides fitPadding for positioning)
+     * When set, the artboard will have this exact margin regardless of zoom level.
+     * The fitPadding still controls the zoom calculation, but positioning uses this fixed margin.
+     */
+    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.
+     */
+    maxHeight?: number;
+    /**
+     * Whether to show the rotation handle on canvas (defaults to true)
+     * Set to false for embedded mode where rotation is handled via toolbar panel
+     */
+    showRotationHandle?: boolean;
+    /**
+     * Whether keyboard shortcuts (copy/paste, delete, undo/redo, etc.) are enabled.
+     * @default true
+     */
+    enableShortcuts?: boolean;
+    /**
+     * ADR-0054 Phase 4: cutout shapes (artboard px) punched through the
+     * `<canvas>` as truly transparent holes. See SnowconeCanvasProps.
+     */
+    canvasCutouts?: import('./SnowconeCanvas').CanvasCutoutShape[];
+    /**
+     * ADR-0054: piece-guide overlays drawn directly into the canvas
+     * render loop (boundary, safe-area wash, zones, die-cut, labels).
+     */
+    pieceGuides?: import('./SnowconeCanvas').PieceGuidesConfig;
+    /**
+     * ADR-0060: viewport focus mode for multi-piece spread layouts. See
+     * `SnowconeCanvasProps.pieceFocus` for the full contract.
+     */
+    pieceFocus?: 'spread' | {
+        pieceId: string;
+    };
+}
+/**
+ * Canvas component - renders CanvasEditor without UI chrome
+ * Exactly like App.tsx but as a reusable component
+ *
+ * Auto-fit behavior: If no zoom is provided, the canvas will automatically
+ * calculate the zoom level to fit the artboard within the container with padding.
+ *
+ * Interactive mode: Enables infinite canvas with pan/zoom controls.
+ */
+export declare const Canvas: React.FC<CanvasProps>;

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

@@ -0,0 +1,76 @@
+import { default as React } from 'react';
+import { TextElement } from '../../core/TextElement.js';
+import { ImageElement } from '../../core/ImageElement.js';
+import { GroupElement } from '../../core/GroupElement.js';
+import { ShapeElement } from '../../core/ShapeElement.js';
+import { PathElement } from '../../core/PathElement.js';
+type EditorElement = TextElement | ImageElement | GroupElement | ShapeElement | PathElement;
+export interface EffectsPanelProps {
+    /**
+     * Whether the panel is open
+     */
+    isOpen: boolean;
+    /**
+     * Callback when panel should close
+     */
+    onClose: () => void;
+    /**
+     * Element to edit effects for
+     * If not provided, uses the selected element from context
+     */
+    element?: EditorElement | null;
+    /**
+     * Callback when element is updated
+     * If not provided, uses the command history from context
+     */
+    onElementUpdate?: (element: EditorElement) => void;
+    /**
+     * Custom CSS styles
+     */
+    style?: React.CSSProperties;
+    /**
+     * Custom class name
+     */
+    className?: string;
+}
+/**
+ * Standalone effects panel component
+ *
+ * @example Using with context (automatic)
+ * ```tsx
+ * function App() {
+ *   const [isOpen, setIsOpen] = useState(false);
+ *
+ *   return (
+ *     <EditorProvider>
+ *       <Canvas />
+ *       <button onClick={() => setIsOpen(true)}>Edit Effects</button>
+ *       <EffectsPanel
+ *         isOpen={isOpen}
+ *         onClose={() => setIsOpen(false)}
+ *       />
+ *     </EditorProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Using with custom element (manual)
+ * ```tsx
+ * function App() {
+ *   const [element, setElement] = useState(myElement);
+ *
+ *   return (
+ *     <EditorProvider>
+ *       <EffectsPanel
+ *         isOpen={true}
+ *         onClose={() => {}}
+ *         element={element}
+ *         onElementUpdate={setElement}
+ *       />
+ *     </EditorProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare const EffectsPanel: React.FC<EffectsPanelProps>;
+export {};

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

@@ -0,0 +1,34 @@
+import { Component, ReactNode, ErrorInfo } from 'react';
+import { CanvasError } from '../../types/index.js';
+export interface ErrorBoundaryProps {
+    children: ReactNode;
+    /** Fallback UI to render when an error is caught. Can be a static ReactNode or a render function. */
+    fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    /**
+     * Render function for custom error UI.
+     * Takes the error and a reset function, returns a ReactNode.
+     * When both `fallback` and `renderError` are provided, `renderError` takes precedence.
+     */
+    renderError?: (error: Error, reset: () => void) => ReactNode;
+    /** Callback fired when an error is caught. Receives the raw Error and React ErrorInfo. */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /** Callback fired when an error is caught, receiving a structured CanvasError. */
+    onCanvasError?: (error: CanvasError) => void;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Error boundary component for graceful error handling.
+ * Catches React rendering errors in the component tree and displays fallback UI.
+ * Supports both plain Error and structured CanvasError callbacks.
+ */
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    resetError: () => void;
+    render(): ReactNode;
+}
+export {};

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

@@ -0,0 +1,51 @@
+import { default as React } from 'react';
+export interface ExportPanelProps {
+    /**
+     * Show continuous export controls
+     */
+    showContinuousExport?: boolean;
+    /**
+     * Default export scale
+     */
+    defaultScale?: number;
+    /**
+     * Default export format
+     */
+    defaultFormat?: 'png' | 'jpg';
+    /**
+     * Callback when export is complete
+     */
+    onExportComplete?: (exports: Record<string, string>) => void;
+    /**
+     * Custom CSS styles
+     */
+    style?: React.CSSProperties;
+    /**
+     * Custom class name
+     */
+    className?: string;
+}
+/**
+ * Standalone export panel component
+ *
+ * @example
+ * ```tsx
+ * function EditorWithExport() {
+ *   return (
+ *     <EditorProvider>
+ *       <div style={{ display: 'flex' }}>
+ *         <Canvas />
+ *         <ExportPanel
+ *           showContinuousExport={true}
+ *           defaultScale={3}
+ *           onExportComplete={(exports) => {
+ *             console.log('Exports:', exports);
+ *           }}
+ *         />
+ *       </div>
+ *     </EditorProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare const ExportPanel: React.FC<ExportPanelProps>;

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

@@ -0,0 +1,70 @@
+import { default as React } from 'react';
+import { TextElement } from '../../core/TextElement.js';
+export interface GlyphPanelProps {
+    /**
+     * Whether the panel is open
+     */
+    isOpen: boolean;
+    /**
+     * Callback when panel should close
+     */
+    onClose: () => void;
+    /**
+     * Font family to browse glyphs for
+     * If not provided, uses the selected text element's font
+     */
+    fontFamily?: string;
+    /**
+     * Font weight to browse glyphs for
+     * If not provided, uses the selected text element's weight
+     */
+    fontWeight?: number;
+    /**
+     * Custom glyph insertion handler
+     * If not provided, uses the default handler that updates the selected element
+     */
+    onInsertGlyph?: (unicode: string) => void;
+    /**
+     * Text element to insert glyphs into
+     * If not provided, uses the selected element from context
+     */
+    element?: TextElement | null;
+}
+/**
+ * Standalone glyph browser panel component
+ *
+ * @example Using with context (automatic)
+ * ```tsx
+ * function App() {
+ *   const [isOpen, setIsOpen] = useState(false);
+ *
+ *   return (
+ *     <EditorProvider>
+ *       <Canvas />
+ *       <button onClick={() => setIsOpen(true)}>Browse Glyphs</button>
+ *       <GlyphPanel
+ *         isOpen={isOpen}
+ *         onClose={() => setIsOpen(false)}
+ *       />
+ *     </EditorProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Using with custom font
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <EditorProvider>
+ *       <GlyphPanel
+ *         isOpen={true}
+ *         onClose={() => {}}
+ *         fontFamily="Playfair Display"
+ *         fontWeight={700}
+ *       />
+ *     </EditorProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare const GlyphPanel: React.FC<GlyphPanelProps>;

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

@@ -0,0 +1,58 @@
+import { default as React } from 'react';
+import { ImageElement } from '../../core/ImageElement.js';
+export interface ImagePanelProps {
+    /**
+     * Whether the panel is open
+     */
+    isOpen: boolean;
+    /**
+     * Callback when panel open state changes
+     */
+    onOpenChange: (open: boolean) => void;
+    /**
+     * Callback after image is selected and element is created/updated
+     */
+    onImageAdded?: (element: ImageElement) => void;
+    /**
+     * Callback after existing image is changed
+     */
+    onImageChanged?: (element: ImageElement) => void;
+    /**
+     * ID of element to change image for (if changing existing image)
+     * If not provided, a new image element will be created
+     */
+    changingElementId?: string | null;
+    /**
+     * Callback when changing element ID changes
+     */
+    onChangingElementIdChange?: (id: string | null) => void;
+}
+/**
+ * Standalone image browser panel component
+ *
+ * @example
+ * ```tsx
+ * function EditorWithImageBrowser() {
+ *   const [isImagePanelOpen, setIsImagePanelOpen] = useState(false);
+ *   const [changingImageId, setChangingImageId] = useState(null);
+ *
+ *   return (
+ *     <EditorProvider>
+ *       <div style={{ display: 'flex' }}>
+ *         <Canvas />
+ *         <button onClick={() => setIsImagePanelOpen(true)}>
+ *           Add Image
+ *         </button>
+ *         <ImagePanel
+ *           isOpen={isImagePanelOpen}
+ *           onOpenChange={setIsImagePanelOpen}
+ *           changingElementId={changingImageId}
+ *           onChangingElementIdChange={setChangingImageId}
+ *         />
+ *       </div>
+ *     </EditorProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare const ImagePanel: React.FC<ImagePanelProps>;

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

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+import { UseLayersOptions } from '../../hooks/useLayers.js';
+export interface LayersPanelProps extends UseLayersOptions {
+    width?: number;
+    height?: number;
+    showPreviewImages?: boolean;
+    enableDragReorder?: boolean;
+    enableGrouping?: boolean;
+    style?: React.CSSProperties;
+    className?: string;
+    showHeader?: boolean;
+}
+export declare const LayersPanel: React.FC<LayersPanelProps>;

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

@@ -0,0 +1,32 @@
+import { CSSProperties } from 'react';
+export interface CanvasSkeletonProps {
+    width?: number | string;
+    height?: number | string;
+    style?: CSSProperties;
+}
+export interface LayersPanelSkeletonProps {
+    itemCount?: number;
+    style?: CSSProperties;
+}
+export interface ToolbarSkeletonProps {
+    style?: CSSProperties;
+}
+/**
+ * Canvas loading skeleton
+ */
+export declare function CanvasSkeleton({ width, height, style }: CanvasSkeletonProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Layers panel loading skeleton
+ */
+export declare function LayersPanelSkeleton({ itemCount, style }: LayersPanelSkeletonProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Toolbar loading skeleton
+ */
+export declare function ToolbarSkeleton({ style }: ToolbarSkeletonProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Generic loading spinner
+ */
+export declare function Spinner({ size, color }: {
+    size?: number;
+    color?: string;
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,47 @@
+import { default as React } from 'react';
+export interface MenuButtonProps {
+    /**
+     * Whether the layers panel is open
+     */
+    isLayersPanelOpen?: boolean;
+    /**
+     * Callback when layers panel toggle is requested
+     */
+    onToggleLayersPanel?: () => void;
+    /**
+     * Callback when image browser should be opened
+     * If provided, this will be called when user selects "Add Image" instead of using the default handler
+     */
+    onOpenImageBrowser?: () => void;
+    /**
+     * Additional menu items to append
+     */
+    additionalItems?: React.ReactNode;
+    /**
+     * Custom button icon
+     */
+    icon?: React.ReactNode;
+    /**
+     * Button tooltip
+     */
+    tooltip?: string;
+    /**
+     * Additional CSS class name
+     */
+    className?: string;
+}
+/**
+ * MenuButton - Unified menu for save/open/export/layers
+ * Must be used within EditorProvider
+ *
+ * @example
+ * ```tsx
+ * <EditorProvider>
+ *   <MenuButton
+ *     isLayersPanelOpen={layersOpen}
+ *     onToggleLayersPanel={() => setLayersOpen(!layersOpen)}
+ *   />
+ * </EditorProvider>
+ * ```
+ */
+export declare const MenuButton: React.FC<MenuButtonProps>;