@snowcone-app/canvas 0.1.0

package/dist/constants.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Central constants file for theme values, colors, and magic numbers
+ * Eliminates duplication across the codebase
+ */
+/**
+ * Get the current theme's accent color from HeroUI CSS variables
+ * Returns oklch() color from --accent variable
+ */
+export declare function getThemeAccentColor(element?: HTMLElement): string;
+/**
+ * Get the current theme's accent foreground color from HeroUI CSS variables
+ * This is the contrasting color for text/icons on accent backgrounds
+ */
+export declare function getThemeAccentForegroundColor(element?: HTMLElement): string;
+/**
+ * Get the current theme name from the data-theme attribute
+ */
+export declare function getCurrentTheme(element?: HTMLElement): string;
+/**
+ * Get the default shape fill color based on the current theme
+ * Returns colors that complement each theme's aesthetic
+ */
+export declare function getThemeShapeFillColor(): string;
+/**
+ * Get the spacing indicator color from the current theme
+ */
+export declare function getThemeSpacingColor(element?: HTMLElement): string;
+/**
+ * Get the current theme's accent color with alpha transparency
+ * Handles both oklch() colors (from HeroUI theme) and hex colors (legacy)
+ */
+export declare function getThemeAccentColorWithAlpha(alpha?: number, element?: HTMLElement): string;
+/**
+ * Get the current theme's text selection color from CSS variables
+ * Returns the theme-specific selection highlight color (already includes opacity)
+ */
+export declare function getThemeTextSelectionColor(element?: HTMLElement): string;
+/**
+ * Get the current theme's hover accent color
+ */
+export declare function getThemeAccentHoverColor(element?: HTMLElement): string;
+/**
+ * Get the current theme's hover accent color with alpha channel
+ */
+export declare function getThemeAccentHoverColorWithAlpha(alpha?: number, element?: HTMLElement): string;
+/**
+ * Get the background color for canvas-rendered tooltips.
+ * Uses --foreground so the tooltip is dark in light mode and light in dark mode,
+ * ensuring contrast against the typically light artboard canvas.
+ */
+export declare function getThemeTooltipBackground(element?: HTMLElement): string;
+/**
+ * Get the text color for canvas-rendered tooltips.
+ * Uses --background so text contrasts with getThemeTooltipBackground().
+ */
+export declare function getThemeTooltipForeground(element?: HTMLElement): string;
+/**
+ * Get the shadow color for canvas-rendered tooltips.
+ * Derives from the tooltip background at 0.2 opacity.
+ */
+export declare function getThemeTooltipShadowColor(element?: HTMLElement): string;
+/**
+ * Get the border color for artboard outlines.
+ * Uses --divider for a theme-appropriate muted border that adapts to light/dark mode.
+ */
+export declare function getThemeArtboardBorderColor(element?: HTMLElement): string;
+/**
+ * Get the label text color for artboard names.
+ * Uses --foreground at 50% opacity for a muted appearance that adapts to light/dark mode.
+ */
+export declare function getThemeArtboardLabelColor(element?: HTMLElement): string;
+/**
+ * Get the current theme's hover border color (uses hover accent color)
+ */
+export declare function getThemeHoverBorderColor(element?: HTMLElement): string;
+/**
+ * Get the pen tool path stroke color.
+ * Uses --foreground so the path line is dark in light mode and light in dark mode,
+ * ensuring visibility against both white and dark artboard backgrounds.
+ */
+export declare function getThemePenPathColor(element?: HTMLElement): string;
+/**
+ * Get the fill color for pen tool anchor points.
+ * Uses --background so anchor circles are visible against the accent-color stroke on both light and dark themes.
+ */
+export declare function getThemePenAnchorFillColor(element?: HTMLElement): string;
+/**
+ * Get the pen tool bezier handle color (control lines and dots).
+ * Uses --foreground at 50% opacity for a muted appearance that adapts to light/dark mode.
+ */
+export declare function getThemePenHandleColor(element?: HTMLElement): string;
+export declare function getSelectionColor(): string;
+export declare function getSelectionFillColor(): string;
+export declare const HOVER_COLOR = "#fbbf24";
+export declare const PREVIEW_ELEMENT_OPACITY = 1;
+export declare const DEFAULT_ARTBOARD_COLOR = "#ffffff";
+export declare const DEFAULT_SHAPE_FILL_COLOR = "#3b82f6";
+export declare const HANDLE_SIZE = 12;
+export declare const HANDLE_RADIUS = 6;
+export declare const ROTATION_HANDLE_DISTANCE = 20;
+export declare const HANDLE_HIT_TOLERANCE = 8;
+export declare const CORNER_HANDLE_VISUAL_RADIUS = 6;
+export declare const EDGE_HANDLE_VISUAL_LENGTH = 24;
+export declare const CORNER_HANDLE_HIT_RADIUS = 16;
+export declare const EDGE_HANDLE_LENGTH = 36;
+export declare const EDGE_HANDLE_HIT_WIDTH = 24;
+export declare const ALIGNMENT_SNAP_THRESHOLD = 2;
+export declare const SPACING_SNAP_THRESHOLD = 4;
+export declare const SPACING_LABEL_TEXT_COLOR = "#FFFFFF";
+export declare const SPACING_LABEL_BORDER_RADIUS = 2;
+export declare const MIN_CROP_SIZE = 0.1;
+export declare const FONT_FAMILIES: string[];
+export declare const FONT_SIZES: number[];
+export declare const HORIZONTAL_PADDING = 0;
+export declare const LINE_HEIGHT_MULTIPLIER = 1.2;
+export declare const MIN_WIDTH = 50;
+export declare const MIN_FONT_SIZE = 8;
+export declare const MAX_FONT_SIZE = 999;
+export declare const SYSTEM_FONTS: Set<string>;
+export declare const WAVE_SKEW_FACTOR = 0.3;
+export declare const WAVE_PATH_STEPS = 100;

package/dist/contexts/CommandContext.d.ts

@@ -0,0 +1,87 @@
+import { default as React, ReactNode } from 'react';
+import { useCommandHistory } from '../hooks/useCommandHistory.js';
+/** Value exposed by CommandContext. */
+export interface CommandContextValue {
+    /** Execute an element update (old -> new) through command history */
+    executeElementUpdate: ReturnType<typeof useCommandHistory>['executeElementUpdate'];
+    /** Execute adding a new element through command history */
+    executeAddElement: ReturnType<typeof useCommandHistory>['executeAddElement'];
+    /** Execute removing an element through command history */
+    executeRemoveElement: ReturnType<typeof useCommandHistory>['executeRemoveElement'];
+    /** Execute reordering an element through command history */
+    executeReorderElement: ReturnType<typeof useCommandHistory>['executeReorderElement'];
+    /** Execute creating an artboard through command history */
+    executeCreateArtboard: ReturnType<typeof useCommandHistory>['executeCreateArtboard'];
+    /** Execute deleting an artboard through command history */
+    executeDeleteArtboard: ReturnType<typeof useCommandHistory>['executeDeleteArtboard'];
+    /** Execute updating an artboard through command history */
+    executeUpdateArtboard: ReturnType<typeof useCommandHistory>['executeUpdateArtboard'];
+    /** Execute a batch of commands as a single undo entry */
+    executeCommandBatch: ReturnType<typeof useCommandHistory>['executeCommandBatch'];
+    /** Undo the last operation (global scope) */
+    undo: () => void;
+    /** Redo the last undone operation (global scope) */
+    redo: () => void;
+    /** Whether there is an operation to undo (global scope) */
+    canUndo: boolean;
+    /** Whether there is an operation to redo (global scope) */
+    canRedo: boolean;
+    /** Undo the last operation on the active artboard */
+    undoActiveArtboard: () => void;
+    /** Redo the last undone operation on the active artboard */
+    redoActiveArtboard: () => void;
+    /** Whether there is an operation to undo on the active artboard */
+    canUndoActiveArtboard: boolean;
+    /** Whether there is an operation to redo on the active artboard */
+    canRedoActiveArtboard: boolean;
+    /** The underlying history manager instance */
+    historyManager: ReturnType<typeof useCommandHistory>['historyManager'];
+}
+/** Props for {@link CommandProvider}. */
+export interface CommandProviderProps {
+    children: ReactNode;
+    /**
+     * The actual command execution functions and undo/redo state.
+     * Provided by InternalEditorProvider which owns the command history.
+     */
+    value: CommandContextValue;
+}
+/**
+ * Provides command execution and undo/redo state to all descendants.
+ *
+ * This is a "pass-through" provider: the actual state is computed by
+ * EditorProvider (via useCommandHistory) and passed in as props. This
+ * allows components to subscribe to command state without subscribing
+ * to all of EditorContext.
+ */
+export declare const CommandProvider: React.FC<CommandProviderProps>;
+/**
+ * Access command execution and undo/redo state.
+ *
+ * Prefer this over `useEditor()` in components that only need to execute
+ * commands or check undo/redo availability (e.g., toolbar buttons that
+ * add/remove elements, undo/redo controls).
+ *
+ * Note: For undo/redo-only access (without execute functions), prefer
+ * `useHistoryContext()` which is even more focused.
+ *
+ * @throws {Error} If called outside of a `CommandProvider` (or `EditorProvider`)
+ *
+ * @example
+ * ```tsx
+ * function DeleteButton() {
+ *   const { executeRemoveElement } = useCommandContext();
+ *   const { selectedElement } = useEditor();
+ *
+ *   return (
+ *     <button
+ *       onClick={() => selectedElement && executeRemoveElement(selectedElement)}
+ *       disabled={!selectedElement}
+ *     >
+ *       Delete
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useCommandContext(): CommandContextValue;

package/dist/contexts/EditorContext.d.ts

@@ -0,0 +1,190 @@
+import { default as React, ReactNode } from 'react';
+import { ArtboardElement } from '../core/ArtboardElement.js';
+import { ArtboardManager } from '../core/ArtboardManager.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 { ElementStore } from '../core/ElementStore.js';
+import { useCommandHistory } from '../hooks/useCommandHistory.js';
+import { CanvasEditorHandle } from '../components/CanvasEditor.jsx';
+import { TextAlign, ShapeType } from '../types/index.js';
+export type { PanOffset } from './ViewportContext.js';
+export type { ExpandedPanelType } from './ToolStateContext.js';
+export type EditorElement = TextElement | ImageElement | GroupElement | ShapeElement | PathElement;
+/**
+ * Full value exposed by EditorContext.
+ *
+ * Contains core state (elements, selection, artboards, zoom), refs to the
+ * canvas DOM and imperative editor handle, setter functions, command history
+ * operations (undo/redo), and element property helpers.
+ */
+export interface EditorContextValue {
+    artboardManager: ArtboardManager;
+    artboards: ArtboardElement[];
+    elements: EditorElement[];
+    /** Normalized element store for O(1) lookups. Use getElementById() for convenience. */
+    elementStore: ElementStore;
+    selectedId: string | null;
+    multiSelection: string[];
+    selectedElement: EditorElement | undefined;
+    activeChildElement: EditorElement | null;
+    hoveredElementId: string | null;
+    hideHandles: boolean;
+    zoom: number;
+    panOffset: import('./ViewportContext.js').PanOffset;
+    isPanning: boolean;
+    isRotating: boolean;
+    /** O(1) element lookup by ID. Returns undefined if not found. */
+    getElementById: (id: string) => EditorElement | undefined;
+    expandedPanelType: import('./ToolStateContext.js').ExpandedPanelType;
+    setExpandedPanelType: React.Dispatch<React.SetStateAction<import('./ToolStateContext.js').ExpandedPanelType>>;
+    clearExpandedPanel: () => void;
+    isToolbarMenuOpen: boolean;
+    setIsToolbarMenuOpen: React.Dispatch<React.SetStateAction<boolean>>;
+    canvasRef: React.RefObject<HTMLCanvasElement | null>;
+    canvasEditorRef: React.RefObject<CanvasEditorHandle | null>;
+    setElements: React.Dispatch<React.SetStateAction<EditorElement[]>>;
+    setSelectedId: React.Dispatch<React.SetStateAction<string | null>>;
+    setZoom: React.Dispatch<React.SetStateAction<number>>;
+    setPanOffset: React.Dispatch<React.SetStateAction<import('./ViewportContext.js').PanOffset>>;
+    setIsPanning: React.Dispatch<React.SetStateAction<boolean>>;
+    setHoveredElementId: React.Dispatch<React.SetStateAction<string | null>>;
+    setHideHandles: React.Dispatch<React.SetStateAction<boolean>>;
+    setMultiSelection: React.Dispatch<React.SetStateAction<string[]>>;
+    setTextSelectionVersion: React.Dispatch<React.SetStateAction<number>>;
+    setIsRotating: React.Dispatch<React.SetStateAction<boolean>>;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    zoomToFit: () => void;
+    resetView: () => void;
+    /**
+     * Version counter that increments on every artboard mutation.
+     * Components can depend on this to re-render when artboard state changes,
+     * even though ArtboardManager is a mutable class instance.
+     */
+    artboardVersion: number;
+    refreshArtboards: () => void;
+    handleSelectionChange: (id: string | null) => void;
+    handleActiveChildChange: (child: EditorElement | null) => void;
+    handleElementUpdate: (updatedElement: EditorElement) => void;
+    handleAddElement: (elementType: string, opts?: {
+        shapeType?: ShapeType;
+    }) => Promise<void>;
+    handleLoadWorkspace: (loadedArtboards: ArtboardElement[], loadedElements: EditorElement[], activeArtboardId: string | null) => void;
+    handleCopyElements: () => void;
+    handlePasteElements: () => void;
+    historyManager: ReturnType<typeof useCommandHistory>['historyManager'];
+    executeElementUpdate: ReturnType<typeof useCommandHistory>['executeElementUpdate'];
+    executeAddElement: ReturnType<typeof useCommandHistory>['executeAddElement'];
+    executeRemoveElement: ReturnType<typeof useCommandHistory>['executeRemoveElement'];
+    executeReorderElement: ReturnType<typeof useCommandHistory>['executeReorderElement'];
+    executeCreateArtboard: ReturnType<typeof useCommandHistory>['executeCreateArtboard'];
+    executeDeleteArtboard: ReturnType<typeof useCommandHistory>['executeDeleteArtboard'];
+    executeUpdateArtboard: ReturnType<typeof useCommandHistory>['executeUpdateArtboard'];
+    executeCommandBatch: ReturnType<typeof useCommandHistory>['executeCommandBatch'];
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    undoActiveArtboard: () => void;
+    redoActiveArtboard: () => void;
+    canUndoActiveArtboard: boolean;
+    canRedoActiveArtboard: boolean;
+    fontSize: number;
+    fontColor: string;
+    fontFamily: string;
+    textAlign: TextAlign;
+    updateFontSize: (delta: number) => void;
+    setFontSizeValue: (size: number) => void;
+    updateFontColor: (color: string) => void;
+    updateFontFamily: (fontFamily: string) => void;
+    updateTextAlign: (textAlign: TextAlign) => void;
+    textSelectionVersion: number;
+    isCanvasReady: boolean;
+    setCanvasReady: (ready: boolean) => void;
+}
+/** Props for {@link EditorProvider}. */
+export interface EditorProviderProps {
+    children: ReactNode;
+    /** Configuration for the default artboard created on mount. */
+    initialArtboardConfig?: {
+        name?: string;
+        x?: number;
+        y?: number;
+        width?: number;
+        height?: number;
+        backgroundColor?: string;
+    };
+    /**
+     * Controls how much of the container the artboard fills when using fitToArtboard.
+     * 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.
+     */
+    viewPadding?: number;
+}
+/**
+ * Provides editor state and operations to all descendant components.
+ *
+ * Composes sub-providers (ViewportProvider, SelectionProvider, ToolStateProvider,
+ * HistoryProvider) around an internal EditorProvider. This gives each sub-context
+ * its own React context, so changes to viewport state (e.g., zoom) won't re-render
+ * components that only subscribe to selection state, and vice versa.
+ *
+ * Must wrap any component that calls `useEditor()` or any of the convenience
+ * hooks (`useArtboards`, `useLayers`, `useViewportContext`, etc.).
+ *
+ * @example
+ * ```tsx
+ * import { EditorProvider, Canvas, useEditor } from '@snowcone-app/canvas';
+ *
+ * function MyEditor() {
+ *   return (
+ *     <EditorProvider initialArtboardConfig={{ width: 1200, height: 1200 }}>
+ *       <Canvas style={{ width: '100%' }} />
+ *       <CustomToolbar />
+ *     </EditorProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare const EditorProvider: React.FC<EditorProviderProps>;
+/**
+ * Access the full editor context: elements, selection, artboards, history, and operations.
+ *
+ * Must be called inside an `EditorProvider`. For focused access, prefer the
+ * sub-context hooks which expose smaller slices of state and cause fewer re-renders:
+ *
+ * - `useViewportContext()` - zoom, pan
+ * - `useSelectionContext()` - selection, hover
+ * - `useHistoryContext()` - undo, redo
+ * - `useToolStateContext()` - panel state, toolbar menus
+ * - `useElementsContext()` - elements, artboards, element operations, font properties
+ * - `useCommandContext()` - command execution (execute*), undo/redo, historyManager
+ *
+ * Or the convenience hooks:
+ * - `useArtboards()`, `useLayers()`, `useExport()`, `useCommands()`
+ * - `useSelectedElement()`, `useElementById()`, `useCanvasReady()`, `useViewport()`
+ *
+ * @returns The complete editor context value
+ * @throws {Error} If called outside of an `EditorProvider`
+ *
+ * @example
+ * ```tsx
+ * function StatusBar() {
+ *   const { elements, selectedId, zoom, canUndo, canRedo, undo, redo } = useEditor();
+ *
+ *   return (
+ *     <div>
+ *       <span>{elements.length} elements</span>
+ *       <span>Zoom: {Math.round(zoom * 100)}%</span>
+ *       <button onClick={undo} disabled={!canUndo}>Undo</button>
+ *       <button onClick={redo} disabled={!canRedo}>Redo</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare const useEditor: () => EditorContextValue;

package/dist/contexts/ElementsContext.d.ts

@@ -0,0 +1,104 @@
+import { default as React, ReactNode } from 'react';
+import { ArtboardElement } from '../core/ArtboardElement.js';
+import { ArtboardManager } from '../core/ArtboardManager.js';
+import { ElementStore } from '../core/ElementStore.js';
+import { CanvasEditorHandle } from '../components/CanvasEditor.jsx';
+import { EditorElement } from './EditorContext.js';
+import { TextAlign } from '../types/index.js';
+/** Value exposed by ElementsContext. */
+export interface ElementsContextValue {
+    /** All elements in the editor */
+    elements: EditorElement[];
+    /** Normalized element store for O(1) lookups */
+    elementStore: ElementStore;
+    /** All artboards */
+    artboards: ArtboardElement[];
+    /** Artboard manager instance */
+    artboardManager: ArtboardManager;
+    /**
+     * Version counter that increments on every artboard mutation.
+     * Components can depend on this to re-render when artboard state changes.
+     */
+    artboardVersion: number;
+    /** Set elements (same SetStateAction signature as before) */
+    setElements: React.Dispatch<React.SetStateAction<EditorElement[]>>;
+    /** Refresh artboards from the artboard manager */
+    refreshArtboards: () => void;
+    /** O(1) element lookup by ID. Returns undefined if not found. */
+    getElementById: (id: string) => EditorElement | undefined;
+    /** Add an element by type (text, image, shape, etc.) */
+    handleAddElement: (elementType: string) => Promise<void>;
+    /** Update an element */
+    handleElementUpdate: (updatedElement: EditorElement) => void;
+    /** Load a workspace (artboards + elements) */
+    handleLoadWorkspace: (loadedArtboards: ArtboardElement[], loadedElements: EditorElement[], activeArtboardId: string | null) => void;
+    /** Copy selected elements to clipboard */
+    handleCopyElements: () => void;
+    /** Paste elements from clipboard */
+    handlePasteElements: () => void;
+    /** Current font size of selected element */
+    fontSize: number;
+    /** Current font color of selected element */
+    fontColor: string;
+    /** Current font family of selected element */
+    fontFamily: string;
+    /** Current text alignment of selected element */
+    textAlign: TextAlign;
+    /** Update font size by delta */
+    updateFontSize: (delta: number) => void;
+    /** Set font size to exact value */
+    setFontSizeValue: (size: number) => void;
+    /** Update font color */
+    updateFontColor: (color: string) => void;
+    /** Update font family */
+    updateFontFamily: (fontFamily: string) => void;
+    /** Update text alignment */
+    updateTextAlign: (textAlign: TextAlign) => void;
+    /** Ref to the canvas HTML element */
+    canvasRef: React.RefObject<HTMLCanvasElement | null>;
+    /** Ref to the imperative canvas editor handle */
+    canvasEditorRef: React.RefObject<CanvasEditorHandle | null>;
+}
+/** Props for {@link ElementsProvider}. */
+export interface ElementsProviderProps {
+    children: ReactNode;
+    /**
+     * The actual element/artboard state from the editor.
+     * Provided by InternalEditorProvider which owns all state.
+     */
+    value: ElementsContextValue;
+}
+/**
+ * Provides element and artboard state to all descendants.
+ *
+ * This is a "pass-through" provider: the actual state is computed by
+ * EditorProvider (via InternalEditorProvider) and passed in as props.
+ * This allows components to subscribe to element changes without
+ * subscribing to all of EditorContext.
+ */
+export declare const ElementsProvider: React.FC<ElementsProviderProps>;
+/**
+ * Access element and artboard state: elements, artboards, element operations,
+ * font properties, and canvas refs.
+ *
+ * Prefer this over `useEditor()` in components that only need element/artboard
+ * information (e.g., layers panel, effects panel, property inspectors).
+ * Changes to non-element state (viewport, selection, tool state) won't
+ * trigger re-renders in components using this hook.
+ *
+ * @throws {Error} If called outside of an `ElementsProvider` (or `EditorProvider`)
+ *
+ * @example
+ * ```tsx
+ * function ElementCount() {
+ *   const { elements, artboards } = useElementsContext();
+ *   return (
+ *     <div>
+ *       <span>{elements.length} elements</span>
+ *       <span>{artboards.length} artboards</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useElementsContext(): ElementsContextValue;

package/dist/contexts/HistoryContext.d.ts

@@ -0,0 +1,60 @@
+import { default as React, ReactNode } from 'react';
+/** Value exposed by HistoryContext. */
+export interface HistoryContextValue {
+    /** Undo the last operation (global scope) */
+    undo: () => void;
+    /** Redo the last undone operation (global scope) */
+    redo: () => void;
+    /** Whether there is an operation to undo (global scope) */
+    canUndo: boolean;
+    /** Whether there is an operation to redo (global scope) */
+    canRedo: boolean;
+    /** Undo the last operation on the active artboard */
+    undoActiveArtboard: () => void;
+    /** Redo the last undone operation on the active artboard */
+    redoActiveArtboard: () => void;
+    /** Whether there is an operation to undo on the active artboard */
+    canUndoActiveArtboard: boolean;
+    /** Whether there is an operation to redo on the active artboard */
+    canRedoActiveArtboard: boolean;
+}
+/** Props for {@link HistoryProvider}. */
+export interface HistoryProviderProps {
+    children: ReactNode;
+    /**
+     * The actual undo/redo functions and state from the command history system.
+     * These are provided by EditorProvider which owns the command history.
+     */
+    value: HistoryContextValue;
+}
+/**
+ * Provides undo/redo state and actions to all descendants.
+ *
+ * This is a "pass-through" provider: the actual history state is computed
+ * by EditorProvider (via useCommandHistory) and passed in as props. This
+ * allows components to subscribe to history changes without subscribing
+ * to all of EditorContext.
+ */
+export declare const HistoryProvider: React.FC<HistoryProviderProps>;
+/**
+ * Access undo/redo state and actions.
+ *
+ * Prefer this over `useEditor()` in components that only need undo/redo
+ * controls (e.g., undo/redo buttons in a toolbar).
+ *
+ * @throws {Error} If called outside of a `HistoryProvider` (or `EditorProvider`)
+ *
+ * @example
+ * ```tsx
+ * function UndoRedoButtons() {
+ *   const { undo, redo, canUndo, canRedo } = useHistoryContext();
+ *   return (
+ *     <>
+ *       <button onClick={undo} disabled={!canUndo}>Undo</button>
+ *       <button onClick={redo} disabled={!canRedo}>Redo</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function useHistoryContext(): HistoryContextValue;

package/dist/contexts/KitContext.d.ts

@@ -0,0 +1,50 @@
+import { KitDefinition, KitPresetId } from '../kits/types.js';
+/**
+ * The value provided by KitContext, including the current kit
+ * and a function to switch kits at runtime.
+ */
+export interface KitContextValue {
+    /** The current resolved KitDefinition */
+    kit: KitDefinition;
+    /** Switch the active kit. Accepts a preset ID string or a full KitDefinition. */
+    setKit: (kit: KitPresetId | KitDefinition) => void;
+}
+/**
+ * Props for the KitProvider component.
+ */
+export interface KitProviderProps {
+    /** The initial kit definition to provide. Updates to this prop will sync the internal state. */
+    kit: KitDefinition;
+    children: React.ReactNode;
+}
+/**
+ * Provides a resolved KitDefinition to all child components via context.
+ * Supports runtime kit switching: children can call `setKit` from `useKit()`
+ * to dynamically change the active kit. If the parent passes a new `kit` prop,
+ * the internal state is synced to match.
+ */
+export declare function KitProvider({ kit: initialKit, children }: KitProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Returns the current kit context value, including the active KitDefinition
+ * and a `setKit` function for runtime kit switching.
+ *
+ * Must be called within a KitProvider.
+ *
+ * @throws {Error} If called outside of a KitProvider
+ *
+ * @example
+ * ```tsx
+ * const { kit, setKit } = useKit();
+ * console.log(kit.name);
+ * setKit('pro-studio'); // switch to a preset
+ * setKit(myCustomKit);  // switch to a custom kit
+ * ```
+ */
+export declare function useKit(): KitContextValue;
+/**
+ * Convenience hook that returns just the capabilities from the current kit.
+ * Equivalent to `useKit().kit.capabilities`.
+ *
+ * @throws {Error} If called outside of a KitProvider
+ */
+export declare function useCapabilities(): import('../types/capabilities.js').EditorCapabilities;

package/dist/contexts/SelectionContext.d.ts

@@ -0,0 +1,51 @@
+import { default as React, ReactNode } from 'react';
+import { EditorElement } from './EditorContext.js';
+/** Value exposed by SelectionContext. */
+export interface SelectionContextValue {
+    /** ID of the currently selected element, or null if nothing is selected */
+    selectedId: string | null;
+    /** IDs of elements in the current multi-selection */
+    multiSelection: string[];
+    /** The child element being directly edited inside a group */
+    activeChildElement: EditorElement | null;
+    /** ID of the element currently being hovered */
+    hoveredElementId: string | null;
+    /** Whether to hide selection handles (e.g., during text editing) */
+    hideHandles: boolean;
+    /** Set the selected element ID */
+    setSelectedId: React.Dispatch<React.SetStateAction<string | null>>;
+    /** Set multi-selection IDs */
+    setMultiSelection: React.Dispatch<React.SetStateAction<string[]>>;
+    /** Set the hovered element ID */
+    setHoveredElementId: React.Dispatch<React.SetStateAction<string | null>>;
+    /** Set whether to hide selection handles */
+    setHideHandles: React.Dispatch<React.SetStateAction<boolean>>;
+    /** Handler for element selection changes */
+    handleSelectionChange: (id: string | null) => void;
+    /** Handler for active child element changes (group editing) */
+    handleActiveChildChange: (child: EditorElement | null) => void;
+}
+/** Props for {@link SelectionProvider}. */
+export interface SelectionProviderProps {
+    children: ReactNode;
+}
+/**
+ * Provides selection state and handlers to all descendants.
+ *
+ * Manages which element is selected, multi-selection, hover state,
+ * and active child element for group editing.
+ */
+export declare const SelectionProvider: React.FC<SelectionProviderProps>;
+/**
+ * Access selection state: selected element ID, multi-selection, hover, and handlers.
+ *
+ * Prefer this over `useEditor()` in components that only need selection information
+ * (e.g., layers panel highlighting, toolbar enable/disable logic).
+ *
+ * Note: This does NOT provide `selectedElement` (the resolved element object).
+ * Use `useEditor()` or `useSelectedElement()` for that, as it requires
+ * cross-referencing with element state.
+ *
+ * @throws {Error} If called outside of a `SelectionProvider` (or `EditorProvider`)
+ */
+export declare function useSelectionContext(): SelectionContextValue;