@yogiswara/honcho-editor-ui 1.3.7 → 1.3.9

package/dist/hooks/useAdjustmentHistory.d.ts

@@ -0,0 +1,91 @@
+import { AdjustmentState } from './editor/useHonchoEditor';
+/**
+ * Configuration options for the adjustment history hook
+ */
+interface HistoryOptions {
+    /** Maximum number of history entries to keep. Use 'unlimited' for no limit */
+    maxSize?: number | 'unlimited';
+    /** Whether to enable batch mode for grouping multiple changes */
+    enableBatching?: boolean;
+    /** Enable development warnings for performance issues */
+    devWarnings?: boolean;
+}
+/**
+ * Information about the current history state
+ */
+export interface HistoryInfo {
+    /** Whether undo operation is available */
+    canUndo: boolean;
+    /** Whether redo operation is available */
+    canRedo: boolean;
+    /** Current position in history (0-based index) */
+    currentIndex: number;
+    /** Total number of states in history */
+    totalStates: number;
+    /** Current size of history in memory */
+    historySize: number;
+    /** Whether batch mode is currently active */
+    isBatchMode: boolean;
+}
+/**
+ * Actions available for history management
+ */
+export interface HistoryActions {
+    /** Add a new adjustment state to history */
+    pushState: (state: AdjustmentState) => void;
+    /** Undo to previous adjustment state */
+    undo: () => void;
+    /** Redo to next adjustment state */
+    redo: () => void;
+    /** Reset history with new initial adjustment state */
+    reset: (newInitialState: AdjustmentState) => void;
+    /** Jump to specific index in history */
+    jumpToIndex: (index: number) => void;
+    /** Clear all history and start fresh */
+    clearHistory: () => void;
+    /** Get a copy of the entire history array */
+    getHistory: () => AdjustmentState[];
+    /** Trim history to specified size, keeping most recent entries */
+    trimHistory: (keepLast: number) => void;
+}
+/**
+ * Configuration actions for runtime adjustment
+ */
+export interface HistoryConfig {
+    /** Set maximum history size */
+    setMaxSize: (size: number | 'unlimited') => void;
+    /** Enable or disable batch mode */
+    setBatchMode: (enabled: boolean) => void;
+    /** Get current memory usage estimate */
+    getMemoryUsage: () => number;
+}
+/**
+ * Return type for the useAdjustmentHistory hook
+ */
+export interface UseAdjustmentHistoryReturn {
+    /** Current adjustment state value */
+    currentState: AdjustmentState;
+    /** Information about history state */
+    historyInfo: HistoryInfo;
+    /** Available history actions */
+    actions: HistoryActions;
+    /** Configuration options */
+    config: HistoryConfig;
+}
+/**
+ * Advanced hook for managing AdjustmentState history with undo/redo functionality.
+ *
+ * Features:
+ * - Unlimited or configurable history size
+ * - Batch mode for grouping multiple changes into single undo operations
+ * - Memory usage monitoring and optimization
+ * - Internal stabilization to prevent re-render issues
+ * - Jump to any point in history
+ * - Automatic AdjustmentState comparison
+ *
+ * @param initialState - The initial AdjustmentState value
+ * @param options - Configuration options for history behavior
+ * @returns Object with current state, history info, actions, and config
+ */
+export declare function useAdjustmentHistory(initialState: AdjustmentState, options?: HistoryOptions): UseAdjustmentHistoryReturn;
+export {};

package/dist/hooks/useAdjustmentHistory.demo.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Demo component showing batch mode behavior
+ */
+export declare function BatchModeDemo(): import("react/jsx-runtime").JSX.Element;
+/**
+ * Example showing smooth preset application
+ */
+export declare function SmoothPresetDemo(): import("react/jsx-runtime").JSX.Element;

package/dist/hooks/useAdjustmentHistory.demo.js

@@ -0,0 +1,106 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useState } from 'react';
+import { useAdjustmentHistory } from './useAdjustmentHistory';
+const initialAdjustments = {
+    tempScore: 0, tintScore: 0, vibranceScore: 0, saturationScore: 0,
+    exposureScore: 0, highlightsScore: 0, shadowsScore: 0, whitesScore: 0,
+    blacksScore: 0, contrastScore: 0, clarityScore: 0, sharpnessScore: 0,
+};
+/**
+ * Demo component showing batch mode behavior
+ */
+export function BatchModeDemo() {
+    const { currentState, historyInfo, actions, config } = useAdjustmentHistory(initialAdjustments);
+    const [updateCount, setUpdateCount] = useState(0);
+    // Track UI updates
+    React.useEffect(() => {
+        setUpdateCount(prev => prev + 1);
+    }, [currentState]);
+    const handleBatchUpdates = async () => {
+        setUpdateCount(0); // Reset counter
+        console.log('Starting batch mode...');
+        config.setBatchMode(true);
+        // These will update currentState 4 times (UI updates)
+        console.log('Push state 1...');
+        actions.pushState({ ...currentState, tempScore: 25 });
+        console.log('Push state 2...');
+        actions.pushState({ ...currentState, tempScore: 50 });
+        console.log('Push state 3...');
+        actions.pushState({ ...currentState, tempScore: 75 });
+        console.log('Push state 4...');
+        actions.pushState({ ...currentState, tempScore: 100 });
+        console.log('Ending batch mode...');
+        config.setBatchMode(false); // Only now will 1 history entry be created
+        console.log('Batch complete!');
+    };
+    const handleInstantUpdates = () => {
+        setUpdateCount(0); // Reset counter
+        // These will create 4 history entries (normal mode)
+        actions.pushState({ ...currentState, tintScore: 25 });
+        actions.pushState({ ...currentState, tintScore: 50 });
+        actions.pushState({ ...currentState, tintScore: 75 });
+        actions.pushState({ ...currentState, tintScore: 100 });
+    };
+    return (_jsxs("div", { style: { padding: '20px', fontFamily: 'monospace' }, children: [_jsx("h2", { children: "Batch Mode Demo" }), _jsxs("div", { style: { marginBottom: '20px', padding: '10px', backgroundColor: '#f5f5f5' }, children: [_jsx("strong", { children: "Current State:" }), _jsxs("div", { children: ["Temperature: ", currentState.tempScore] }), _jsxs("div", { children: ["Tint: ", currentState.tintScore] }), _jsxs("div", { children: ["UI Updates: ", updateCount] }), _jsxs("div", { children: ["History Size: ", historyInfo.totalStates] }), _jsxs("div", { children: ["Can Undo: ", historyInfo.canUndo ? 'Yes' : 'No'] }), _jsxs("div", { children: ["Batch Mode: ", historyInfo.isBatchMode ? 'Active' : 'Inactive'] })] }), _jsxs("div", { style: { display: 'flex', gap: '10px', marginBottom: '20px' }, children: [_jsx("button", { onClick: handleBatchUpdates, style: { padding: '10px', backgroundColor: '#4CAF50', color: 'white', border: 'none' }, children: "Batch Mode (4 UI updates, 1 history entry)" }), _jsx("button", { onClick: handleInstantUpdates, style: { padding: '10px', backgroundColor: '#2196F3', color: 'white', border: 'none' }, children: "Normal Mode (4 UI updates, 4 history entries)" })] }), _jsxs("div", { style: { display: 'flex', gap: '10px' }, children: [_jsx("button", { onClick: actions.undo, disabled: !historyInfo.canUndo, style: {
+                            padding: '10px',
+                            backgroundColor: historyInfo.canUndo ? '#FF9800' : '#ccc',
+                            color: 'white',
+                            border: 'none'
+                        }, children: "Undo" }), _jsx("button", { onClick: actions.redo, disabled: !historyInfo.canRedo, style: {
+                            padding: '10px',
+                            backgroundColor: historyInfo.canRedo ? '#9C27B0' : '#ccc',
+                            color: 'white',
+                            border: 'none'
+                        }, children: "Redo" }), _jsx("button", { onClick: () => actions.reset(initialAdjustments), style: { padding: '10px', backgroundColor: '#f44336', color: 'white', border: 'none' }, children: "Reset" })] }), _jsxs("div", { style: { marginTop: '20px', fontSize: '12px', color: '#666' }, children: [_jsx("h3", { children: "How it works:" }), _jsxs("ul", { children: [_jsxs("li", { children: [_jsx("strong", { children: "Batch Mode:" }), " UI updates immediately on each pushState, but only final state is saved to history when batch ends"] }), _jsxs("li", { children: [_jsx("strong", { children: "Normal Mode:" }), " Each pushState creates both UI update and history entry"] }), _jsxs("li", { children: [_jsx("strong", { children: "Result:" }), " Smooth UI animations with clean undo/redo history"] })] })] })] }));
+}
+/**
+ * Example showing smooth preset application
+ */
+export function SmoothPresetDemo() {
+    const { currentState, historyInfo, actions, config } = useAdjustmentHistory(initialAdjustments);
+    const dramaticPreset = {
+        tempScore: 50, tintScore: -20, vibranceScore: 80, saturationScore: 60,
+        exposureScore: 30, highlightsScore: -40, shadowsScore: 40, whitesScore: 20,
+        blacksScore: -30, contrastScore: 70, clarityScore: 50, sharpnessScore: 40,
+    };
+    const handleSmoothPreset = async () => {
+        config.setBatchMode(true);
+        // Create smooth transition with multiple steps
+        const steps = 8;
+        for (let i = 1; i <= steps; i++) {
+            const progress = i / steps;
+            const intermediateState = {
+                tempScore: Math.round(currentState.tempScore + (dramaticPreset.tempScore - currentState.tempScore) * progress),
+                tintScore: Math.round(currentState.tintScore + (dramaticPreset.tintScore - currentState.tintScore) * progress),
+                vibranceScore: Math.round(currentState.vibranceScore + (dramaticPreset.vibranceScore - currentState.vibranceScore) * progress),
+                saturationScore: Math.round(currentState.saturationScore + (dramaticPreset.saturationScore - currentState.saturationScore) * progress),
+                exposureScore: Math.round(currentState.exposureScore + (dramaticPreset.exposureScore - currentState.exposureScore) * progress),
+                highlightsScore: Math.round(currentState.highlightsScore + (dramaticPreset.highlightsScore - currentState.highlightsScore) * progress),
+                shadowsScore: Math.round(currentState.shadowsScore + (dramaticPreset.shadowsScore - currentState.shadowsScore) * progress),
+                whitesScore: Math.round(currentState.whitesScore + (dramaticPreset.whitesScore - currentState.whitesScore) * progress),
+                blacksScore: Math.round(currentState.blacksScore + (dramaticPreset.blacksScore - currentState.blacksScore) * progress),
+                contrastScore: Math.round(currentState.contrastScore + (dramaticPreset.contrastScore - currentState.contrastScore) * progress),
+                clarityScore: Math.round(currentState.clarityScore + (dramaticPreset.clarityScore - currentState.clarityScore) * progress),
+                sharpnessScore: Math.round(currentState.sharpnessScore + (dramaticPreset.sharpnessScore - currentState.sharpnessScore) * progress),
+            };
+            actions.pushState(intermediateState);
+            // Small delay for smooth animation
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        config.setBatchMode(false); // Commit final state
+    };
+    return (_jsxs("div", { style: { padding: '20px', fontFamily: 'monospace' }, children: [_jsx("h2", { children: "Smooth Preset Application" }), _jsxs("div", { style: { display: 'grid', gridTemplateColumns: 'repeat(4, 1fr)', gap: '10px', marginBottom: '20px', fontSize: '12px' }, children: [_jsxs("div", { children: ["Temp: ", currentState.tempScore] }), _jsxs("div", { children: ["Tint: ", currentState.tintScore] }), _jsxs("div", { children: ["Vibrance: ", currentState.vibranceScore] }), _jsxs("div", { children: ["Saturation: ", currentState.saturationScore] }), _jsxs("div", { children: ["Exposure: ", currentState.exposureScore] }), _jsxs("div", { children: ["Highlights: ", currentState.highlightsScore] }), _jsxs("div", { children: ["Shadows: ", currentState.shadowsScore] }), _jsxs("div", { children: ["Whites: ", currentState.whitesScore] }), _jsxs("div", { children: ["Blacks: ", currentState.blacksScore] }), _jsxs("div", { children: ["Contrast: ", currentState.contrastScore] }), _jsxs("div", { children: ["Clarity: ", currentState.clarityScore] }), _jsxs("div", { children: ["Sharpness: ", currentState.sharpnessScore] })] }), _jsx("button", { onClick: handleSmoothPreset, style: {
+                    padding: '15px 30px',
+                    backgroundColor: '#4CAF50',
+                    color: 'white',
+                    border: 'none',
+                    fontSize: '16px',
+                    marginRight: '10px'
+                }, children: "Apply Dramatic Preset (Smooth)" }), _jsx("button", { onClick: actions.undo, disabled: !historyInfo.canUndo, style: {
+                    padding: '15px 30px',
+                    backgroundColor: historyInfo.canUndo ? '#FF9800' : '#ccc',
+                    color: 'white',
+                    border: 'none',
+                    fontSize: '16px'
+                }, children: "Undo Preset" }), _jsx("div", { style: { marginTop: '20px', fontSize: '12px', color: '#666' }, children: _jsx("p", { children: "This demo shows smooth preset application with 8 intermediate steps, but only 1 undo operation!" }) })] }));
+}

package/dist/hooks/useAdjustmentHistory.example.d.ts

@@ -0,0 +1,33 @@
+import { type HistoryInfo } from './useAdjustmentHistory';
+import { AdjustmentState } from './editor/useHonchoEditor';
+export declare function useEditorWithHistory(): {
+    adjustments: AdjustmentState;
+    canUndo: boolean;
+    canRedo: boolean;
+    undo: () => void;
+    redo: () => void;
+    updateTemperature: (newTemp: number) => void;
+    applyPresetWithSmoothUI: (presetState: AdjustmentState) => void;
+    updateMultipleAdjustments: (updates: Partial<AdjustmentState>) => void;
+    resetAdjustments: () => void;
+    jumpToIndex: (index: number) => void;
+    getHistory: () => AdjustmentState[];
+    clearHistory: () => void;
+    setBatchMode: (enabled: boolean) => void;
+    setMaxSize: (size: number | "unlimited") => void;
+    getMemoryUsage: () => number;
+    historyInfo: HistoryInfo;
+};
+/**
+ * Example integration with your existing useHonchoEditor pattern
+ */
+export declare function integrateWithHonchoEditor(): {
+    currentAdjustments: AdjustmentState;
+    canUndo: boolean;
+    canRedo: boolean;
+    handleSliderChange: (key: keyof AdjustmentState, value: number) => void;
+    handlePresetWithAnimation: (presetState: AdjustmentState) => Promise<void>;
+    handleUndo: () => void;
+    handleRedo: () => void;
+    handleRevert: () => void;
+};

package/dist/hooks/useAdjustmentHistory.example.js

@@ -0,0 +1,150 @@
+import { useAdjustmentHistory } from './useAdjustmentHistory';
+/**
+ * Example usage of the simplified useAdjustmentHistory hook
+ * This shows how to integrate it with your existing useHonchoEditor
+ */
+// Example initial adjustment state
+const initialAdjustments = {
+    tempScore: 0,
+    tintScore: 0,
+    vibranceScore: 0,
+    saturationScore: 0,
+    exposureScore: 0,
+    highlightsScore: 0,
+    shadowsScore: 0,
+    whitesScore: 0,
+    blacksScore: 0,
+    contrastScore: 0,
+    clarityScore: 0,
+    sharpnessScore: 0,
+};
+export function useEditorWithHistory() {
+    // Initialize the adjustment history hook
+    const { currentState: currentAdjustments, historyInfo, actions, config } = useAdjustmentHistory(initialAdjustments, {
+        maxSize: 100, // Keep last 100 states
+        enableBatching: false, // Start with batching disabled
+        devWarnings: true // Show performance warnings in development
+    });
+    // Example: Update a single adjustment value
+    const updateTemperature = (newTemp) => {
+        const newState = {
+            ...currentAdjustments,
+            tempScore: newTemp
+        };
+        actions.pushState(newState);
+    };
+    // Example: Apply preset with batch mode for smooth UI updates
+    const applyPresetWithSmoothUI = (presetState) => {
+        // Enable batch mode to group all changes into one undo operation
+        config.setBatchMode(true);
+        // These will update the UI immediately but not create history entries
+        actions.pushState({ ...currentAdjustments, tempScore: presetState.tempScore });
+        actions.pushState({ ...currentAdjustments, tempScore: presetState.tempScore, tintScore: presetState.tintScore });
+        actions.pushState({ ...currentAdjustments, tempScore: presetState.tempScore, tintScore: presetState.tintScore, exposureScore: presetState.exposureScore });
+        actions.pushState(presetState); // Final complete state
+        // Disable batch mode to commit only the final state to history
+        config.setBatchMode(false);
+        // Result: UI updated 4 times (smooth animation), but only 1 undo operation
+    };
+    // Example: Bulk update multiple adjustments
+    const updateMultipleAdjustments = (updates) => {
+        config.setBatchMode(true); // Start batching
+        const newState = {
+            ...currentAdjustments,
+            ...updates
+        };
+        actions.pushState(newState);
+        config.setBatchMode(false); // Commit batch
+    };
+    // Example: Reset to initial state
+    const resetAdjustments = () => {
+        actions.reset(initialAdjustments);
+    };
+    return {
+        // Current adjustment values
+        adjustments: currentAdjustments,
+        // History controls
+        canUndo: historyInfo.canUndo,
+        canRedo: historyInfo.canRedo,
+        undo: actions.undo,
+        redo: actions.redo,
+        // Adjustment functions
+        updateTemperature,
+        applyPresetWithSmoothUI,
+        updateMultipleAdjustments,
+        resetAdjustments,
+        // Advanced features
+        jumpToIndex: actions.jumpToIndex,
+        getHistory: actions.getHistory,
+        clearHistory: actions.clearHistory,
+        // Configuration
+        setBatchMode: config.setBatchMode,
+        setMaxSize: config.setMaxSize,
+        getMemoryUsage: config.getMemoryUsage,
+        // History info
+        historyInfo
+    };
+}
+/**
+ * Example integration with your existing useHonchoEditor pattern
+ */
+export function integrateWithHonchoEditor() {
+    const history = useAdjustmentHistory(initialAdjustments);
+    // Replace your current manual history management with this:
+    // Instead of:
+    // const [history, setHistory] = useState<AdjustmentState[]>([initialAdjustments]);
+    // const [historyIndex, setHistoryIndex] = useState(0);
+    // Use:
+    const currentAdjustments = history.currentState;
+    const canUndo = history.historyInfo.canUndo;
+    const canRedo = history.historyInfo.canRedo;
+    // When any adjustment changes (e.g., slider value):
+    const handleSliderChange = (key, value) => {
+        const newState = {
+            ...currentAdjustments,
+            [key]: value
+        };
+        history.actions.pushState(newState);
+    };
+    // Smooth preset application with multiple UI updates
+    const handlePresetWithAnimation = async (presetState) => {
+        history.config.setBatchMode(true);
+        // Animate through intermediate states for smooth UI
+        const steps = 4;
+        for (let i = 1; i <= steps; i++) {
+            const progress = i / steps;
+            const intermediateState = {
+                tempScore: Math.round(currentAdjustments.tempScore + (presetState.tempScore - currentAdjustments.tempScore) * progress),
+                tintScore: Math.round(currentAdjustments.tintScore + (presetState.tintScore - currentAdjustments.tintScore) * progress),
+                vibranceScore: Math.round(currentAdjustments.vibranceScore + (presetState.vibranceScore - currentAdjustments.vibranceScore) * progress),
+                saturationScore: Math.round(currentAdjustments.saturationScore + (presetState.saturationScore - currentAdjustments.saturationScore) * progress),
+                exposureScore: Math.round(currentAdjustments.exposureScore + (presetState.exposureScore - currentAdjustments.exposureScore) * progress),
+                highlightsScore: Math.round(currentAdjustments.highlightsScore + (presetState.highlightsScore - currentAdjustments.highlightsScore) * progress),
+                shadowsScore: Math.round(currentAdjustments.shadowsScore + (presetState.shadowsScore - currentAdjustments.shadowsScore) * progress),
+                whitesScore: Math.round(currentAdjustments.whitesScore + (presetState.whitesScore - currentAdjustments.whitesScore) * progress),
+                blacksScore: Math.round(currentAdjustments.blacksScore + (presetState.blacksScore - currentAdjustments.blacksScore) * progress),
+                contrastScore: Math.round(currentAdjustments.contrastScore + (presetState.contrastScore - currentAdjustments.contrastScore) * progress),
+                clarityScore: Math.round(currentAdjustments.clarityScore + (presetState.clarityScore - currentAdjustments.clarityScore) * progress),
+                sharpnessScore: Math.round(currentAdjustments.sharpnessScore + (presetState.sharpnessScore - currentAdjustments.sharpnessScore) * progress),
+            };
+            history.actions.pushState(intermediateState);
+            // Small delay for smooth animation
+            await new Promise(resolve => setTimeout(resolve, 50));
+        }
+        history.config.setBatchMode(false); // Commit only final state to history
+    };
+    // Your existing undo/redo handlers become:
+    const handleUndo = history.actions.undo;
+    const handleRedo = history.actions.redo;
+    const handleRevert = () => history.actions.reset(initialAdjustments);
+    return {
+        currentAdjustments,
+        canUndo,
+        canRedo,
+        handleSliderChange,
+        handlePresetWithAnimation,
+        handleUndo,
+        handleRedo,
+        handleRevert
+    };
+}

package/dist/hooks/useAdjustmentHistory.js

@@ -0,0 +1,277 @@
+import { useState, useCallback, useMemo, useRef, useEffect } from 'react';
+/**
+ * Compare two AdjustmentState objects for equality
+ * Uses JSON.stringify for deep comparison of all adjustment values
+ */
+const compareAdjustmentStates = (a, b) => {
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch (error) {
+        // Fallback to manual comparison if JSON.stringify fails
+        console.warn('Failed to compare adjustment states with JSON.stringify, falling back to manual comparison:', error);
+        return (a.tempScore === b.tempScore &&
+            a.tintScore === b.tintScore &&
+            a.vibranceScore === b.vibranceScore &&
+            a.saturationScore === b.saturationScore &&
+            a.exposureScore === b.exposureScore &&
+            a.highlightsScore === b.highlightsScore &&
+            a.shadowsScore === b.shadowsScore &&
+            a.whitesScore === b.whitesScore &&
+            a.blacksScore === b.blacksScore &&
+            a.contrastScore === b.contrastScore &&
+            a.clarityScore === b.clarityScore &&
+            a.sharpnessScore === b.sharpnessScore);
+    }
+};
+/**
+ * Advanced hook for managing AdjustmentState history with undo/redo functionality.
+ *
+ * Features:
+ * - Unlimited or configurable history size
+ * - Batch mode for grouping multiple changes into single undo operations
+ * - Memory usage monitoring and optimization
+ * - Internal stabilization to prevent re-render issues
+ * - Jump to any point in history
+ * - Automatic AdjustmentState comparison
+ *
+ * @param initialState - The initial AdjustmentState value
+ * @param options - Configuration options for history behavior
+ * @returns Object with current state, history info, actions, and config
+ */
+export function useAdjustmentHistory(initialState, options = {}) {
+    // Internal stabilization - prevent re-renders from options object recreation
+    const internalOptions = useMemo(() => ({
+        maxSize: options.maxSize ?? 'unlimited',
+        enableBatching: options.enableBatching ?? false,
+        devWarnings: options.devWarnings ?? false
+    }), [
+        options.maxSize,
+        options.enableBatching,
+        options.devWarnings
+    ]);
+    // Core state management
+    const [history, setHistory] = useState([initialState]);
+    const [currentIndex, setCurrentIndex] = useState(0);
+    const [currentState, setCurrentState] = useState(initialState);
+    // Batch mode state - ref to avoid triggering effects
+    const batchModeRef = useRef(internalOptions.enableBatching);
+    const batchStartIndexRef = useRef(null);
+    const batchStartStateRef = useRef(null);
+    // Configuration refs - prevent re-renders when config changes
+    const maxSizeRef = useRef(internalOptions.maxSize);
+    const devWarningsRef = useRef(internalOptions.devWarnings);
+    // Performance monitoring
+    const performanceRef = useRef({
+        lastHistorySize: 1,
+        lastUpdateTime: Date.now(),
+        largeHistoryWarningShown: false
+    });
+    // Sync currentState with history when not in batch mode
+    useEffect(() => {
+        if (!batchModeRef.current) {
+            setCurrentState(history[currentIndex]);
+        }
+    }, [history, currentIndex]);
+    const getMemoryUsage = useCallback(() => {
+        try {
+            const historyString = JSON.stringify(history);
+            return historyString.length * 2; // Rough estimate: 2 bytes per character
+        }
+        catch (error) {
+            console.warn('Failed to estimate memory usage:', error);
+            return history.length * 1000; // Fallback estimate
+        }
+    }, [history]);
+    // Development warnings for performance
+    const checkPerformance = useCallback(() => {
+        if (!devWarningsRef.current)
+            return;
+        const now = Date.now();
+        const perfData = performanceRef.current;
+        // Warn about large history sizes
+        if (history.length > 1000 && !perfData.largeHistoryWarningShown) {
+            console.warn(`useAdjustmentHistory: Large history size detected (${history.length} entries). Consider setting a maxSize limit.`);
+            perfData.largeHistoryWarningShown = true;
+        }
+        // Update performance tracking
+        perfData.lastHistorySize = history.length;
+        perfData.lastUpdateTime = now;
+    }, [history.length]);
+    // Trim history to specified size, keeping most recent entries
+    const trimHistoryToSize = useCallback((size) => {
+        if (size <= 0)
+            return;
+        setHistory(prevHistory => {
+            if (prevHistory.length <= size)
+                return prevHistory;
+            const startIndex = Math.max(0, prevHistory.length - size);
+            const trimmedHistory = prevHistory.slice(startIndex);
+            // Adjust current index to maintain relative position
+            setCurrentIndex(prevIndex => {
+                const adjustedIndex = prevIndex - startIndex;
+                return Math.max(0, Math.min(adjustedIndex, trimmedHistory.length - 1));
+            });
+            return trimmedHistory;
+        });
+    }, []);
+    // Apply max size limit when history grows
+    const enforceMaxSize = useCallback(() => {
+        if (maxSizeRef.current === 'unlimited')
+            return;
+        const maxSize = maxSizeRef.current;
+        if (history.length > maxSize) {
+            trimHistoryToSize(maxSize);
+        }
+    }, [history.length, trimHistoryToSize]);
+    // Push new state to history
+    const pushState = useCallback((newState) => {
+        // Skip if state hasn't changed
+        if (compareAdjustmentStates(newState, currentState)) {
+            return;
+        }
+        // Always update currentState immediately for smooth UI
+        setCurrentState(newState);
+        if (batchModeRef.current) {
+            // In batch mode: Don't update history yet, just update UI state
+            // History will be updated when batch mode ends
+            return;
+        }
+        // Normal mode: Update history immediately
+        setHistory(prevHistory => {
+            const truncatedHistory = prevHistory.slice(0, currentIndex + 1);
+            const newHistory = [...truncatedHistory, newState];
+            setCurrentIndex(newHistory.length - 1);
+            return newHistory;
+        });
+    }, [currentState, currentIndex]);
+    // Undo to previous state
+    const undo = useCallback(() => {
+        if (currentIndex > 0) {
+            const newIndex = currentIndex - 1;
+            setCurrentIndex(newIndex);
+            setCurrentState(history[newIndex]);
+            // Exit batch mode when undoing
+            if (batchModeRef.current) {
+                batchModeRef.current = false;
+                batchStartIndexRef.current = null;
+                batchStartStateRef.current = null;
+            }
+        }
+    }, [currentIndex, history]);
+    // Redo to next state
+    const redo = useCallback(() => {
+        if (currentIndex < history.length - 1) {
+            const newIndex = currentIndex + 1;
+            setCurrentIndex(newIndex);
+            setCurrentState(history[newIndex]);
+        }
+    }, [currentIndex, history]);
+    // Reset history with new initial state
+    const reset = useCallback((newInitialState) => {
+        setHistory([newInitialState]);
+        setCurrentIndex(0);
+        setCurrentState(newInitialState);
+        batchModeRef.current = internalOptions.enableBatching;
+        batchStartIndexRef.current = null;
+        batchStartStateRef.current = null;
+    }, [internalOptions.enableBatching]);
+    // Jump to specific index in history
+    const jumpToIndex = useCallback((index) => {
+        if (index >= 0 && index < history.length) {
+            setCurrentIndex(index);
+            setCurrentState(history[index]);
+            // Exit batch mode when jumping
+            if (batchModeRef.current) {
+                batchModeRef.current = false;
+                batchStartIndexRef.current = null;
+                batchStartStateRef.current = null;
+            }
+        }
+    }, [history]);
+    // Clear all history and start fresh
+    const clearHistory = useCallback(() => {
+        setHistory([currentState]);
+        setCurrentIndex(0);
+        batchModeRef.current = internalOptions.enableBatching;
+        batchStartIndexRef.current = null;
+        batchStartStateRef.current = null;
+    }, [currentState, internalOptions.enableBatching]);
+    // Get copy of entire history
+    const getHistory = useCallback(() => {
+        return [...history];
+    }, [history]);
+    // Manually trim history
+    const trimHistory = useCallback((keepLast) => {
+        trimHistoryToSize(keepLast);
+    }, [trimHistoryToSize]);
+    // Configuration setters
+    const setMaxSize = useCallback((size) => {
+        maxSizeRef.current = size;
+        if (size !== 'unlimited') {
+            enforceMaxSize();
+        }
+    }, [enforceMaxSize]);
+    const setBatchMode = useCallback((enabled) => {
+        const wasInBatch = batchModeRef.current;
+        if (enabled && !wasInBatch) {
+            // Starting batch mode - save current state as batch start
+            batchModeRef.current = true;
+            batchStartIndexRef.current = currentIndex;
+            batchStartStateRef.current = currentState;
+        }
+        else if (!enabled && wasInBatch) {
+            // Ending batch mode - commit final state to history
+            batchModeRef.current = false;
+            // Only add to history if state actually changed from batch start
+            if (batchStartStateRef.current &&
+                !compareAdjustmentStates(currentState, batchStartStateRef.current)) {
+                setHistory(prevHistory => {
+                    const truncatedHistory = prevHistory.slice(0, batchStartIndexRef.current + 1);
+                    const newHistory = [...truncatedHistory, currentState];
+                    setCurrentIndex(newHistory.length - 1);
+                    return newHistory;
+                });
+            }
+            batchStartIndexRef.current = null;
+            batchStartStateRef.current = null;
+        }
+    }, [currentIndex, currentState]);
+    // History info object
+    const historyInfo = useMemo(() => ({
+        canUndo: currentIndex > 0,
+        canRedo: currentIndex < history.length - 1,
+        currentIndex,
+        totalStates: history.length,
+        historySize: getMemoryUsage(),
+        isBatchMode: batchModeRef.current
+    }), [currentIndex, history.length, getMemoryUsage]);
+    // Actions object - stabilized with useMemo
+    const actions = useMemo(() => ({
+        pushState,
+        undo,
+        redo,
+        reset,
+        jumpToIndex,
+        clearHistory,
+        getHistory,
+        trimHistory
+    }), [pushState, undo, redo, reset, jumpToIndex, clearHistory, getHistory, trimHistory]);
+    // Config object - stabilized with useMemo
+    const config = useMemo(() => ({
+        setMaxSize,
+        setBatchMode,
+        getMemoryUsage
+    }), [setMaxSize, setBatchMode, getMemoryUsage]);
+    // Apply max size enforcement when history changes
+    useEffect(() => {
+        enforceMaxSize();
+        checkPerformance();
+    }, [enforceMaxSize, checkPerformance]);
+    return {
+        currentState,
+        historyInfo,
+        actions,
+        config
+    };
+}