@snowcone-app/canvas 0.1.0

package/dist/hooks/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Hooks - Custom React hooks
+ */
+export { useClickOutside } from './useClickOutside';
+export { useArtboards } from './useArtboards';
+export type { ArtboardInfo, UseArtboardsReturn } from './useArtboards';
+export { useLayers } from './useLayers';
+export type { LayerInfo, UseLayersOptions, UseLayersReturn } from './useLayers';
+export { useExport } from './useExport';
+export type { ExportProgress, ContinuousExportOptions, UseExportReturn } from './useExport';
+export { useProjectLoader } from './useProjectLoader';
+export type { ProjectTemplate, ProjectMetadata, UseProjectLoaderReturn } from './useProjectLoader';
+export { useCommands } from './useCommands';
+export type { UseCommandsReturn } from './useCommands';
+export { useBreakpoint } from './useBreakpoint';
+export type { BreakpointConfig, Breakpoint, UseBreakpointReturn } from './useBreakpoint';
+export { usePerformance } from './usePerformance';
+export type { PerformanceMetrics, UsePerformanceReturn } from './usePerformance';
+export { useSelectedElement } from './useSelectedElement';
+export { useElementById } from './useElementById';
+export { useElementByName } from './useElementByName';
+export { useCanvasReady } from './useCanvasReady';
+export { useTextBinding } from './useTextBinding';
+export type { TextBindingResult } from './useTextBinding';
+export { useImageBinding } from './useImageBinding';
+export type { ImageBindingResult, ImageBindingOptions, ImageFitMode } from './useImageBinding';
+export { useViewport } from './useViewport';
+export type { UseViewportReturn } from './useViewport';
+export { useTextToolbar } from './useTextToolbar';
+export type { UseTextToolbarOptions, UseTextToolbarReturn } from './useTextToolbar';
+export { useAutoExport } from './useAutoExport';
+export type { UseAutoExportOptions, UseAutoExportReturn } from './useAutoExport';
+export { useLayerPreview } from './useLayerPreview';
+export type { UseLayerPreviewOptions, UseLayerPreviewReturn } from './useLayerPreview';
+export { useLayerDragDrop } from './useLayerDragDrop';
+export type { UseLayerDragDropOptions, UseLayerDragDropReturn } from './useLayerDragDrop';
+export { useLayerSelection } from './useLayerSelection';
+export type { UseLayerSelectionOptions, UseLayerSelectionReturn } from './useLayerSelection';
+export { useCanvasEvents } from './useCanvasEvents';
+export { useCommandHistory } from './useCommandHistory';
+export { useKeyboardShortcuts } from './useKeyboardShortcuts';
+export { useElementProperties } from './useElementProperties';

package/dist/hooks/useArtboards.d.ts

@@ -0,0 +1,71 @@
+import { ArtboardElement } from '../core/ArtboardElement.js';
+import { ClipShape, ArtboardDistressTexture } from '../types/index.js';
+export interface ArtboardInfo {
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    backgroundColor: string;
+    clipShape?: ClipShape;
+    isActive: boolean;
+    elementCount: number;
+}
+export interface UseArtboardsReturn {
+    artboards: ArtboardElement[];
+    artboardsInfo: ArtboardInfo[];
+    activeArtboard: ArtboardElement | null;
+    activeArtboardId: string | null;
+    activeArtboardInfo: ArtboardInfo | null;
+    createArtboard: (width?: number, height?: number, config?: Partial<{
+        name: string;
+        x: number;
+        y: number;
+        backgroundColor: string;
+        clipShape: ClipShape;
+    }>) => void;
+    deleteArtboard: (artboardId: string) => void;
+    duplicateArtboard: (artboardId: string) => void;
+    renameArtboard: (artboardId: string, newName: string) => void;
+    updateArtboard: (artboardId: string, updates: Partial<{
+        name: string;
+        width: number;
+        height: number;
+        backgroundColor: string;
+        clipShape: ClipShape;
+        distressTexture: ArtboardDistressTexture | undefined;
+    }>) => void;
+    selectArtboard: (artboardId: string) => void;
+    reorderArtboards: (fromIndex: number, toIndex: number) => void;
+    count: number;
+}
+/**
+ * Hook to access artboard data and operations
+ * Must be used within EditorProvider
+ *
+ * @example
+ * ```tsx
+ * function ArtboardSwitcher() {
+ *   const { artboardsInfo, selectArtboard, createArtboard } = useArtboards();
+ *
+ *   return (
+ *     <div>
+ *       {artboardsInfo.map(ab => (
+ *         <button
+ *           key={ab.id}
+ *           onClick={() => selectArtboard(ab.id)}
+ *           className={ab.isActive ? 'active' : ''}
+ *         >
+ *           {ab.name} ({ab.width}×{ab.height})
+ *         </button>
+ *       ))}
+ *       <button onClick={() => createArtboard(1200, 1200)}>
+ *         + New Artboard
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare const useArtboards: () => UseArtboardsReturn;

package/dist/hooks/useAutoExport.d.ts

@@ -0,0 +1,66 @@
+import { AutoExportConfig, AutoExportStats } from '../services/AutoExportManager.js';
+import { HybridHistoryManager } from '../core/HybridHistoryManager.js';
+import { ArtboardElement } from '../core/ArtboardElement.js';
+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 UseAutoExportOptions {
+    /** Auto-export configuration */
+    config?: Partial<AutoExportConfig>;
+    /** Hybrid history manager to listen to for changes */
+    historyManager?: HybridHistoryManager;
+    /** Current artboards */
+    artboards: ArtboardElement[];
+    /** Current elements */
+    elements: EditorElement[];
+    /** Callback to perform the actual export */
+    onExport: () => void | Promise<void>;
+    /**
+     * Callback fired immediately when an export is scheduled (before debounce).
+     * Use this to show loading indicators right away instead of waiting for export to complete.
+     */
+    onExportScheduled?: () => void;
+    /**
+     * Whether the canvas is mounted and ready for export operations.
+     * When false, exports are deferred until canvas becomes ready.
+     * This prevents "[useExport] Canvas ref not available" errors.
+     */
+    isCanvasReady?: boolean;
+}
+export interface UseAutoExportReturn {
+    /** Current auto-export statistics */
+    stats: AutoExportStats;
+    /** Update configuration on the fly */
+    updateConfig: (config: Partial<AutoExportConfig>) => void;
+    /** Force an immediate export (bypassing debounce) */
+    forceExport: () => Promise<void>;
+    /** Reset statistics */
+    resetStats: () => void;
+    /** Reset change detection (next export will always trigger) */
+    resetChangeDetection: () => void;
+}
+/**
+ * Hook to manage automatic export on state changes
+ *
+ * @example
+ * ```tsx
+ * const { stats, updateConfig } = useAutoExport({
+ *   config: {
+ *     enabled: true,
+ *     debounceMs: 100,
+ *     maxWaitMs: 1000,
+ *   },
+ *   historyManager,
+ *   artboards,
+ *   elements,
+ *   onExport: async () => {
+ *     await exportAllArtboards();
+ *   },
+ * });
+ * ```
+ */
+export declare function useAutoExport(options: UseAutoExportOptions): UseAutoExportReturn;
+export {};

package/dist/hooks/useBreakpoint.d.ts

@@ -0,0 +1,53 @@
+/**
+ * useBreakpoint - Hook for responsive breakpoint detection
+ * Provides responsive utilities for building adaptive UIs
+ *
+ * @example
+ * ```tsx
+ * function ResponsiveLayout() {
+ *   const { isAtLeast, breakpoint } = useBreakpoint();
+ *
+ *   return (
+ *     <div>
+ *       {isAtLeast('md') ? (
+ *         <div className="desktop-layout">
+ *           <LayersPanel />
+ *           <Canvas />
+ *           <ExportPanel />
+ *         </div>
+ *       ) : (
+ *         <div className="mobile-layout">
+ *           <Canvas />
+ *         </div>
+ *       )}
+ *       <p>Current breakpoint: {breakpoint}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export interface BreakpointConfig {
+    xs?: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+    xxl?: number;
+}
+export type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+export interface UseBreakpointReturn {
+    breakpoint: Breakpoint;
+    width: number;
+    isXs: boolean;
+    isSm: boolean;
+    isMd: boolean;
+    isLg: boolean;
+    isXl: boolean;
+    isXxl: boolean;
+    isAtLeast: (bp: Breakpoint) => boolean;
+    isAtMost: (bp: Breakpoint) => boolean;
+}
+/**
+ * Hook for responsive breakpoint detection
+ */
+export declare function useBreakpoint(config?: BreakpointConfig): UseBreakpointReturn;

package/dist/hooks/useCanvasEvents.d.ts

@@ -0,0 +1,8 @@
+import { CanvasEventBus } from '../core/EventBus.js';
+/**
+ * Returns the singleton {@link CanvasEventBus} instance.
+ *
+ * The returned reference is stable across renders -- it always points to
+ * the same singleton, so it is safe to include in dependency arrays.
+ */
+export declare function useCanvasEvents(): CanvasEventBus;

package/dist/hooks/useCanvasReady.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Returns whether the canvas is fully initialized and ready for operations.
+ *
+ * The canvas is not ready until the underlying `<canvas>` element is mounted
+ * and the editor has completed its initial setup. Use this to gate operations
+ * like export or programmatic element manipulation that require a live canvas.
+ *
+ * @returns `true` when the canvas is mounted and ready, `false` otherwise.
+ *
+ * @example
+ * ```tsx
+ * function ExportButton() {
+ *   const ready = useCanvasReady();
+ *   return (
+ *     <button disabled={!ready} onClick={handleExport}>
+ *       Export PNG
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useCanvasReady(): boolean;

package/dist/hooks/useClickOutside.d.ts

@@ -0,0 +1,3 @@
+import { RefObject } from 'react';
+export declare function useClickOutside<T extends HTMLElement>(callback: (event: MouseEvent) => void, enabled?: boolean): RefObject<T | null>;
+export default useClickOutside;

package/dist/hooks/useCommandHistory.d.ts

@@ -0,0 +1,39 @@
+import { HybridHistoryManager } from '../core/HybridHistoryManager.js';
+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';
+import { ArtboardElement } from '../core/ArtboardElement.js';
+import { ArtboardManager } from '../core/ArtboardManager.js';
+/** Union of all element types */
+type AnyElement = TextElement | ImageElement | GroupElement | ShapeElement | PathElement;
+/**
+ * Hook to manage hybrid command history for undo/redo
+ * Supports both global (artboard) and per-artboard (element) operations
+ */
+export declare function useCommandHistory(elements: AnyElement[], setElements: React.Dispatch<React.SetStateAction<AnyElement[]>>, artboardManager: ArtboardManager, onArtboardsChange?: () => void): {
+    executeElementUpdate: (oldElement: AnyElement | undefined | null, newElement: AnyElement) => void;
+    executeAddElement: (element: AnyElement, artboardId?: string, insertAfterElementId?: string, insertBeforeElementId?: string) => void;
+    executeRemoveElement: (element: AnyElement) => void;
+    executeReorderElement: (draggedId: string, targetId: string, position: "before" | "after") => void;
+    executeCommandBatch: (commands: Array<{
+        execute: () => void;
+        undo: () => void;
+    }>) => void;
+    executeCreateArtboard: (artboard: ArtboardElement) => void;
+    executeDeleteArtboard: (artboard: ArtboardElement) => void;
+    executeUpdateArtboard: (artboardId: string, oldProperties: Partial<ArtboardElement>, newProperties: Partial<ArtboardElement>) => void;
+    undo: () => void;
+    redo: () => void;
+    undoActiveArtboard: () => void;
+    redoActiveArtboard: () => void;
+    clearHistory: () => void;
+    clearArtboardHistory: (artboardId: string) => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    canUndoActiveArtboard: boolean;
+    canRedoActiveArtboard: boolean;
+    historyManager: HybridHistoryManager;
+};
+export default useCommandHistory;

package/dist/hooks/useCommands.d.ts

@@ -0,0 +1,47 @@
+import { useEditor } from '../contexts/EditorContext.js';
+export interface UseCommandsReturn {
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    clearHistory: () => void;
+    clearArtboardHistory: (artboardId: string) => void;
+    executeElementUpdate: ReturnType<typeof useEditor>['executeElementUpdate'];
+    executeAddElement: ReturnType<typeof useEditor>['executeAddElement'];
+    executeRemoveElement: ReturnType<typeof useEditor>['executeRemoveElement'];
+    executeReorderElement: ReturnType<typeof useEditor>['executeReorderElement'];
+    executeCreateArtboard: ReturnType<typeof useEditor>['executeCreateArtboard'];
+    executeDeleteArtboard: ReturnType<typeof useEditor>['executeDeleteArtboard'];
+    executeUpdateArtboard: ReturnType<typeof useEditor>['executeUpdateArtboard'];
+    executeCommandBatch: (commands: Array<{
+        execute: () => void;
+        undo: () => void;
+    }>) => void;
+}
+/**
+ * Hook for accessing command history and undo/redo functionality
+ * Must be used within EditorProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { undo, redo, canUndo, canRedo } = useCommands();
+ *   const { selectedElement } = useEditor();
+ *
+ *   const handleDelete = () => {
+ *     if (selectedElement) {
+ *       executeRemoveElement(selectedElement);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={undo} disabled={!canUndo}>Undo</button>
+ *       <button onClick={redo} disabled={!canRedo}>Redo</button>
+ *       <button onClick={handleDelete}>Delete</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useCommands(): UseCommandsReturn;

package/dist/hooks/useContentReady.d.ts

@@ -0,0 +1,18 @@
+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 UseContentReadyOptions {
+    /** DOM mounted and artboards initialized */
+    isCanvasReady: boolean;
+    /** Current elements in the editor */
+    elements: EditorElement[];
+    /** Were initialElements provided to SnowconeCanvas? */
+    hasInitialElements: boolean;
+    /** Have initialElements been deserialized into the editor? */
+    initialElementsLoaded: boolean;
+}
+export declare function useContentReady(options: UseContentReadyOptions): boolean;
+export {};

package/dist/hooks/useElementById.d.ts

@@ -0,0 +1,20 @@
+import { EditorElement } from '../contexts/EditorContext.js';
+/**
+ * Returns a specific element by its ID, or null if not found.
+ *
+ * Useful for components that need to display or react to a particular
+ * element without subscribing to the full editor state.
+ *
+ * @param id - The element ID to look up, or null to skip the lookup.
+ * @returns The matching element, or null if the ID is null or no element matches.
+ *
+ * @example
+ * ```tsx
+ * function ElementInspector({ elementId }: { elementId: string }) {
+ *   const element = useElementById(elementId);
+ *   if (!element) return <p>Element not found</p>;
+ *   return <p>Position: ({element.x}, {element.y})</p>;
+ * }
+ * ```
+ */
+export declare function useElementById(id: string | null): EditorElement | null;

package/dist/hooks/useElementByName.d.ts

@@ -0,0 +1,10 @@
+import { EditorElement } from '../contexts/EditorContext.js';
+/**
+ * Returns the first element matching the given name, or null.
+ *
+ * Must be used within an `EditorProvider`.
+ *
+ * @param name - The element name to look up, or null to skip the lookup.
+ * @returns The matching element, or null if no element matches.
+ */
+export declare function useElementByName(name: string | null): EditorElement | null;

package/dist/hooks/useElementProperties.d.ts

@@ -0,0 +1,29 @@
+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';
+import { TextAlign } from '../types/index.js';
+type EditorElement = TextElement | ImageElement | GroupElement | ShapeElement | PathElement;
+/**
+ * Hook to manage element properties and UI synchronization
+ * @param selectedElement - Currently selected element
+ * @param onElementUpdate - Callback to update element
+ * @returns Property getters and setters
+ */
+export declare function useElementProperties(selectedElement: EditorElement | undefined, onElementUpdate: (element: EditorElement) => void): {
+    fontSize: number;
+    fontColor: string;
+    fontFamily: string;
+    textAlign: TextAlign;
+    setFontSize: import('react').Dispatch<import('react').SetStateAction<number>>;
+    setFontColor: import('react').Dispatch<import('react').SetStateAction<string>>;
+    setFontFamily: import('react').Dispatch<import('react').SetStateAction<string>>;
+    setTextAlign: import('react').Dispatch<import('react').SetStateAction<TextAlign>>;
+    updateFontSize: (delta: number) => void;
+    setFontSizeValue: (newSize: number) => void;
+    updateFontColor: (newColor: string) => void;
+    updateFontFamily: (newFontFamily: string) => void;
+    updateTextAlign: (alignment: TextAlign) => void;
+};
+export default useElementProperties;

package/dist/hooks/useExport.d.ts

@@ -0,0 +1,89 @@
+import { ExportImageOptions } from '../utils/ExportManager.js';
+export interface ExportProgress {
+    artboardId: string;
+    artboardName: string;
+    status: 'pending' | 'rendering' | 'complete' | 'error';
+    progress: number;
+    dataUrl?: string;
+    error?: Error;
+    timestamp: number;
+}
+export interface ContinuousExportOptions {
+    artboardIds?: string[];
+    interval?: number;
+    scale?: number;
+    format?: 'png' | 'jpg';
+    onChange?: (results: Record<string, string>) => void;
+}
+export interface UseExportReturn {
+    exportArtboard: (artboardId: string, options?: ExportImageOptions) => Promise<string>;
+    exportArtboardAsBlob: (artboardId: string, options?: ExportImageOptions) => Promise<Blob>;
+    exportAllArtboards: (options?: ExportImageOptions) => Promise<Record<string, string>>;
+    exportAllArtboardsAsBlobs: (options?: ExportImageOptions) => Promise<Record<string, Blob>>;
+    startContinuousExport: (options: ContinuousExportOptions) => void;
+    stopContinuousExport: () => void;
+    isExporting: boolean;
+    isContinuousExporting: boolean;
+    progress: ExportProgress[];
+    latestExports: Record<string, string>;
+    supportsWorkerExport: boolean;
+    workerStats: {
+        totalExports: number;
+        avgExportTime: number;
+        isWorkerActive: boolean;
+    };
+}
+/**
+ * Hook for exporting artboards to images
+ * Must be used within EditorProvider
+ *
+ * @example Single Export
+ * ```tsx
+ * function ExportButton() {
+ *   const { exportArtboard, isExporting } = useExport();
+ *   const { activeArtboardId } = useArtboards();
+ *
+ *   const handleExport = async () => {
+ *     if (!activeArtboardId) return;
+ *     const dataUrl = await exportArtboard(activeArtboardId, {
+ *       scale: 3,
+ *       format: 'png'
+ *     });
+ *     // Download or display dataUrl
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleExport} disabled={isExporting}>
+ *       {isExporting ? 'Exporting...' : 'Export'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example Continuous Export (Sprint 2)
+ * ```tsx
+ * function LiveMockupPreview() {
+ *   const { startContinuousExport, stopContinuousExport, latestExports } = useExport();
+ *   const { artboardsInfo } = useArtboards();
+ *
+ *   useEffect(() => {
+ *     startContinuousExport({
+ *       interval: 500,
+ *       scale: 3,
+ *       onChange: (exports) => {
+ *         // Send to mockup API
+ *         Object.entries(exports).forEach(([artboardId, dataUrl]) => {
+ *           const artboard = artboardsInfo.find(a => a.id === artboardId);
+ *           sendToMockupAPI(artboard.name, dataUrl);
+ *         });
+ *       }
+ *     });
+ *
+ *     return () => stopContinuousExport();
+ *   }, []);
+ *
+ *   return <div>Mockup preview...</div>;
+ * }
+ * ```
+ */
+export declare function useExport(): UseExportReturn;

package/dist/hooks/useImageBinding.d.ts

@@ -0,0 +1,34 @@
+import { EditorElement } from '../contexts/EditorContext.js';
+/** How the image fits the element bounds. */
+export type ImageFitMode = 'cover' | 'contain';
+/** Options for {@link useImageBinding}. */
+export interface ImageBindingOptions {
+    /** How the image fits the element bounds. Default: "cover". */
+    fit?: ImageFitMode;
+}
+/** Result returned by {@link useImageBinding}. */
+export interface ImageBindingResult {
+    /** Current image URL (from first bound element). Empty string if disconnected. */
+    imageUrl: string;
+    /** Update image URL on all bound elements. No-op if disconnected. */
+    setImageUrl: (url: string) => void;
+    /** The first bound element, or null if no matching image element exists. */
+    element: EditorElement | null;
+    /** All bound image elements (empty array if disconnected). */
+    elements: readonly EditorElement[];
+    /** Whether at least one matching image element exists. */
+    isConnected: boolean;
+}
+/**
+ * Bind an external input to canvas image elements by their `name` property.
+ *
+ * Multiple elements can share the same name — `setImageUrl` updates all of them.
+ * The image URL is read from the first matching element (render order).
+ *
+ * Must be used within an `EditorProvider`.
+ *
+ * @param name - The element name to bind to.
+ * @param options - Optional configuration (fit mode, etc.).
+ * @returns Image URL value, setter, element references, and connection status.
+ */
+export declare function useImageBinding(name: string, options?: ImageBindingOptions): ImageBindingResult;

package/dist/hooks/useKeyboardShortcuts.d.ts

@@ -0,0 +1,13 @@
+/**
+ * useKeyboardShortcuts - Hook for handling keyboard shortcuts in the editor
+ * Provides copy/paste and other keyboard shortcuts
+ */
+/**
+ * Hook that sets up keyboard shortcuts for the editor
+ * Handles copy/paste, delete, undo/redo, and other shortcuts
+ *
+ * @param options.enabled - Whether keyboard shortcuts are active (default: true)
+ */
+export declare function useKeyboardShortcuts(options?: {
+    enabled?: boolean;
+}): void;

package/dist/hooks/useLayerDndKit.d.ts

@@ -0,0 +1,24 @@
+import { useSensors, DragStartEvent, DragMoveEvent, DragOverEvent, DragEndEvent, DragCancelEvent } from '@dnd-kit/core';
+import { GroupElement } from '../core/GroupElement.js';
+import { EditorElement } from '../contexts/EditorContext.js';
+export interface UseLayerDndKitOptions {
+    onReorder: (draggedId: string, targetId: string, position: 'before' | 'after') => void;
+    onGroupReorder?: (draggedId: string, targetId: string, position: 'before' | 'after', groupId: string) => void;
+    onDropIntoGroup?: (draggedId: string, groupId: string) => void;
+    onDropIntoGroupAtPosition?: (draggedId: string, groupId: string, targetChildId: string, position: 'before' | 'after') => void;
+    onRemoveFromGroup?: (draggedId: string) => void;
+    findElement?: (id: string) => EditorElement | null;
+    findParentGroup?: (id: string) => GroupElement | null;
+}
+export interface UseLayerDndKitReturn {
+    activeId: string | null;
+    overId: string | null;
+    dropPosition: 'before' | 'after' | 'into' | null;
+    sensors: ReturnType<typeof useSensors>;
+    onDragStart: (event: DragStartEvent) => void;
+    onDragMove: (event: DragMoveEvent) => void;
+    onDragOver: (event: DragOverEvent) => void;
+    onDragEnd: (event: DragEndEvent) => void;
+    onDragCancel: (event: DragCancelEvent) => void;
+}
+export declare function useLayerDndKit(options: UseLayerDndKitOptions): UseLayerDndKitReturn;

package/dist/hooks/useLayerDragDrop.d.ts

@@ -0,0 +1,58 @@
+import { GroupElement } from '../core/GroupElement.js';
+import { EditorElement } from '../contexts/EditorContext.js';
+export interface UseLayerDragDropOptions {
+    /**
+     * Called when reordering top-level elements or elements in different groups.
+     * Position is already inverted for reversed display order.
+     */
+    onReorder: (draggedId: string, targetId: string, position: 'before' | 'after') => void;
+    /**
+     * Called when reordering elements within the same group.
+     * Position is already inverted for reversed display order.
+     */
+    onGroupReorder?: (draggedId: string, targetId: string, position: 'before' | 'after', groupId: string) => void;
+    /**
+     * Called when dropping an element into a group (center drop zone).
+     */
+    onDropIntoGroup?: (draggedId: string, groupId: string) => void;
+    /**
+     * Called when dropping a top-level element between children of a group.
+     * Position is already inverted for reversed display order.
+     */
+    onDropIntoGroupAtPosition?: (draggedId: string, groupId: string, targetChildId: string, position: 'before' | 'after') => void;
+    /**
+     * Look up an element by ID. Required for determining if a target is a group.
+     */
+    findElement?: (id: string) => EditorElement | null;
+    /**
+     * Find the parent group of an element. Required for intra-group reordering.
+     */
+    findParentGroup?: (id: string) => GroupElement | null;
+}
+export interface UseLayerDragDropReturn {
+    /** ID of the currently dragged element, or null */
+    draggedId: string | null;
+    /** ID of the element being dragged over, or null */
+    dragOverId: string | null;
+    /** Where the dragged element will be dropped relative to the target */
+    dropPosition: 'before' | 'after' | 'into' | null;
+    /** Event handlers to attach to draggable layer items */
+    handlers: {
+        onDragStart: (e: React.DragEvent, elementId: string) => void;
+        onDragOver: (e: React.DragEvent, elementId: string) => void;
+        onDrop: (e: React.DragEvent, targetId: string) => void;
+        onDragEnd: () => void;
+    };
+}
+/**
+ * Hook for managing drag-drop reordering in layer panels.
+ *
+ * Calculates drop position based on mouse position within the target element:
+ * - For groups: top 25% = before, middle 50% = into, bottom 25% = after
+ * - For non-groups: top/bottom split at 40%/60%
+ *
+ * Handles the display-order inversion: layers are displayed in reverse
+ * order (topmost layer first), so visual "before" maps to array "after"
+ * and vice versa. This inversion is applied before calling the callbacks.
+ */
+export declare function useLayerDragDrop(options: UseLayerDragDropOptions): UseLayerDragDropReturn;