@yogiswara/honcho-editor-ui 2.8.10 → 2.9.0

package/dist/hooks/useAdjustmentHistory.d.ts

@@ -0,0 +1,95 @@
+import { AdjustmentState, Controller } from './editor/type';
+/**
+ * Configuration options for the adjustment history hook
+ */
+export 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;
+    /** 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;
+    /** Sync history from backend using getEditorHistory */
+    syncFromBackend: () => Promise<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, forceHistory?: boolean) => Promise<void>;
+    /** Get current memory usage estimate */
+    getMemoryUsage: () => number;
+}
+/**
+ * Return type for the useAdjustmentHistory hook
+ */
+export interface UseAdjustmentHistoryReturn {
+    /** Current adjustment state value */
+    currentState: AdjustmentState;
+    /** Current index in history */
+    currentIndex: number;
+    /** 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 controller - Controller for backend operations (optional)
+ * @param firebaseUid - Firebase UID for backend operations (optional)
+ * @param currentImageId - Current image ID for backend operations (optional)
+ * @param options - Configuration options for history behavior
+ * @returns Object with current state, history info, actions, and config
+ */
+export declare function useAdjustmentHistory(initialState: AdjustmentState, controller?: Controller, firebaseUid?: string, currentImageId?: string, options?: HistoryOptions): UseAdjustmentHistoryReturn;

package/dist/hooks/useAdjustmentHistory.js

@@ -0,0 +1,578 @@
+import { useState, useCallback, useMemo, useRef, useEffect } from 'react';
+/**
+ * Convert AdjustmentState to ColorAdjustment format for backend
+ */
+const convertAdjustmentStateToColorAdjustment = (adjustmentState) => {
+    return {
+        temperature: adjustmentState.tempScore,
+        tint: adjustmentState.tintScore,
+        saturation: adjustmentState.saturationScore,
+        vibrance: adjustmentState.vibranceScore,
+        exposure: adjustmentState.exposureScore,
+        contrast: adjustmentState.contrastScore,
+        highlights: adjustmentState.highlightsScore,
+        shadows: adjustmentState.shadowsScore,
+        whites: adjustmentState.whitesScore,
+        blacks: adjustmentState.blacksScore,
+        clarity: adjustmentState.clarityScore,
+        sharpness: adjustmentState.sharpnessScore,
+    };
+};
+/**
+ * Convert ColorAdjustment from backend to AdjustmentState format
+ */
+const convertColorAdjustmentToAdjustmentState = (colorAdjustment) => {
+    return {
+        tempScore: colorAdjustment.temperature,
+        tintScore: colorAdjustment.tint,
+        saturationScore: colorAdjustment.saturation,
+        vibranceScore: colorAdjustment.vibrance,
+        exposureScore: colorAdjustment.exposure,
+        contrastScore: colorAdjustment.contrast,
+        highlightsScore: colorAdjustment.highlights,
+        shadowsScore: colorAdjustment.shadows,
+        whitesScore: colorAdjustment.whites,
+        blacksScore: colorAdjustment.blacks,
+        clarityScore: colorAdjustment.clarity,
+        sharpnessScore: colorAdjustment.sharpness,
+    };
+};
+/**
+ * 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 controller - Controller for backend operations (optional)
+ * @param firebaseUid - Firebase UID for backend operations (optional)
+ * @param currentImageId - Current image ID for backend operations (optional)
+ * @param options - Configuration options for history behavior
+ * @returns Object with current state, history info, actions, and config
+ */
+export function useAdjustmentHistory(initialState, controller, firebaseUid, currentImageId, 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,
+        controller: controller,
+        firebaseUid: firebaseUid,
+        currentImageId: currentImageId
+    }), [
+        options.maxSize,
+        options.enableBatching,
+        options.devWarnings,
+        controller,
+        firebaseUid,
+        currentImageId
+    ]);
+    // Core state management
+    const [history, setHistory] = useState([{ state: initialState, taskId: `initial_${Date.now()}` }]);
+    const [currentState, setCurrentState] = useState(initialState);
+    const currentIndexRef = useRef(0);
+    const currentStateRef = useRef(initialState);
+    // Batch mode state - ref to avoid triggering effects
+    const batchModeRef = useRef(internalOptions.enableBatching);
+    const batchStartIndexRef = useRef(null);
+    const batchStartStateRef = useRef(null);
+    const batchModeProcessingRef = useRef(false); // Guard against double execution
+    // Configuration refs - prevent re-renders when config changes
+    const maxSizeRef = useRef(internalOptions.maxSize);
+    const devWarningsRef = useRef(internalOptions.devWarnings);
+    // Computed current index for return value (defined early for dependencies)
+    const currentIndex = currentIndexRef.current;
+    // 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) {
+    //         console.log(`[useAdjustmentHistory] Syncing currentState with history:`, history[currentIndex]?.state);
+    //         setCurrentState(history[currentIndex]?.state || initialState);
+    //     }
+    // }, [history, currentIndex, initialState]);
+    useEffect(() => {
+        if (internalOptions.currentImageId) {
+            syncFromBackend().catch(console.error);
+        }
+    }, [internalOptions.currentImageId, internalOptions.firebaseUid, internalOptions.controller]);
+    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
+            const prevIndex = currentIndexRef.current;
+            const adjustedIndex = prevIndex - startIndex;
+            currentIndexRef.current = 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) => {
+        // Always update currentState immediately for smooth UI
+        currentStateRef.current = newState;
+        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
+            console.log(`[useAdjustmentHistory] Pushing state in batch mode:`, newState);
+            return;
+        }
+        // Normal mode: Update history immediately
+        console.log(`[useAdjustmentHistory] Pushing new state to history:`, newState);
+        setHistory(prevHistory => {
+            const truncatedHistory = prevHistory.slice(0, currentIndexRef.current + 1);
+            // const taskId = `task_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+            // we put the taskId empty to check this state no need to save it
+            const newHistory = [...truncatedHistory, { state: newState, taskId: "" }];
+            currentIndexRef.current = newHistory.length - 1;
+            return newHistory;
+        });
+    }, []);
+    // Undo to previous state
+    const undo = useCallback(async () => {
+        if (currentIndexRef.current > 0) {
+            const newIndex = currentIndexRef.current - 1;
+            const historyEntry = history[newIndex];
+            const newState = historyEntry.state;
+            currentIndexRef.current = newIndex;
+            currentStateRef.current = newState;
+            setCurrentState(newState);
+            console.log(`[useAdjustmentHistory] Undoing to index ${newIndex}:`, newState);
+            // Call controller to set history index in backend if taskId exists
+            if (historyEntry.taskId && internalOptions.controller && internalOptions.firebaseUid && internalOptions.currentImageId) {
+                try {
+                    console.log(`🔙 Undo: Setting history index to taskId: ${historyEntry.taskId}`);
+                    await internalOptions.controller.setHistoryIndex(internalOptions.firebaseUid, internalOptions.currentImageId, historyEntry.taskId);
+                    console.log('✅ Successfully set history index for undo');
+                }
+                catch (error) {
+                    console.error('❌ Failed to set history index for undo:', error);
+                }
+            }
+            else {
+                console.log("🔙 Undo: No taskId available for setting history index", historyEntry.taskId, internalOptions.firebaseUid, internalOptions.currentImageId);
+            }
+            // Exit batch mode when undoing
+            if (batchModeRef.current) {
+                batchModeRef.current = false;
+                batchStartIndexRef.current = null;
+                batchStartStateRef.current = null;
+            }
+        }
+    }, [history, internalOptions]);
+    // Redo to next state
+    const redo = useCallback(async () => {
+        if (currentIndexRef.current < history.length - 1) {
+            const newIndex = currentIndexRef.current + 1;
+            const historyEntry = history[newIndex];
+            const newState = historyEntry.state;
+            currentIndexRef.current = newIndex;
+            currentStateRef.current = newState;
+            setCurrentState(newState);
+            console.log(`[useAdjustmentHistory] Redoing to index ${newIndex}:`, newState);
+            // Call controller to set history index in backend if taskId exists
+            if (historyEntry.taskId && internalOptions.controller && internalOptions.firebaseUid && internalOptions.currentImageId) {
+                try {
+                    console.log(`🔄 Redo: Setting history index to taskId: ${historyEntry.taskId}`);
+                    await internalOptions.controller.setHistoryIndex(internalOptions.firebaseUid, internalOptions.currentImageId, historyEntry.taskId);
+                    console.log('✅ Successfully set history index for redo');
+                }
+                catch (error) {
+                    console.error('❌ Failed to set history index for redo:', error);
+                }
+            }
+            else {
+                console.warn('🔄 Redo: No taskId available for setting history index', historyEntry.taskId, internalOptions.firebaseUid, internalOptions.currentImageId);
+            }
+        }
+    }, [history, internalOptions]);
+    // Reset history with new initial state
+    // const reset = useCallback((newInitialState: AdjustmentState) => {
+    //     console.log("Reset called setHistory");
+    //     setHistory([{ state: newInitialState, taskId: `reset_${Date.now()}` }]);
+    //     currentIndexRef.current = 0;
+    //     currentStateRef.current = 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) {
+            const historyEntry = history[index];
+            const newState = historyEntry.state;
+            currentIndexRef.current = index;
+            currentStateRef.current = newState;
+            setCurrentState(newState);
+            // 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(() => {
+        console.log("clearHistory called setHistory");
+        setHistory([{ state: currentStateRef.current, taskId: `clear_${Date.now()}` }]);
+        currentIndexRef.current = 0;
+        batchModeRef.current = internalOptions.enableBatching;
+        batchStartIndexRef.current = null;
+        batchStartStateRef.current = null;
+    }, [internalOptions.enableBatching]);
+    // Get copy of entire history
+    const getHistory = useCallback(() => {
+        return history.map(entry => entry.state);
+    }, [history]);
+    // Manually trim history
+    const trimHistory = useCallback((keepLast) => {
+        trimHistoryToSize(keepLast);
+    }, [trimHistoryToSize]);
+    // Sync/replace entire history with new list
+    const syncHistory = useCallback((newHistory, targetIndex) => {
+        throw Error('syncHistory is not implemented yet');
+        // // Validate input
+        // if (!Array.isArray(newHistory) || newHistory.length === 0) {
+        //     console.warn('syncHistory: newHistory must be a non-empty array');
+        //     return;
+        // }
+        // // Validate all items are AdjustmentState objects
+        // const isValidHistory = newHistory.every(state => 
+        //     state && typeof state === 'object' &&
+        //     typeof state.tempScore === 'number' &&
+        //     typeof state.tintScore === 'number' &&
+        //     typeof state.vibranceScore === 'number' &&
+        //     typeof state.saturationScore === 'number' &&
+        //     typeof state.exposureScore === 'number' &&
+        //     typeof state.highlightsScore === 'number' &&
+        //     typeof state.shadowsScore === 'number' &&
+        //     typeof state.whitesScore === 'number' &&
+        //     typeof state.blacksScore === 'number' &&
+        //     typeof state.contrastScore === 'number' &&
+        //     typeof state.clarityScore === 'number' &&
+        //     typeof state.sharpnessScore === 'number'
+        // );
+        // if (!isValidHistory) {
+        //     console.warn('syncHistory: All items in newHistory must be valid AdjustmentState objects');
+        //     return;
+        // }
+        // // Exit batch mode if active
+        // if (batchModeRef.current) {
+        //     batchModeRef.current = false;
+        //     batchStartIndexRef.current = null;
+        //     batchStartStateRef.current = null;
+        // }
+        // // Determine target index
+        // let finalIndex = targetIndex ?? newHistory.length - 1; // Default to last item
+        // finalIndex = Math.max(0, Math.min(finalIndex, newHistory.length - 1)); // Clamp to valid range
+        // // Create a copy of the new history to avoid mutations and convert to HistoryEntry format
+        // const historyToSet = newHistory.map((state, index) => ({ 
+        //     state: { ...state }, 
+        //     taskId: `sync_${Date.now()}_${index}` 
+        // }));
+        // // Apply max size limit if needed
+        // if (maxSizeRef.current !== 'unlimited' && historyToSet.length > maxSizeRef.current) {
+        //     const trimAmount = historyToSet.length - maxSizeRef.current;
+        //     const trimmedHistory = historyToSet.slice(trimAmount);
+        //     // Adjust target index
+        //     finalIndex = Math.max(0, finalIndex - trimAmount);
+        //     setHistory(trimmedHistory);
+        //     setCurrentIndex(finalIndex);
+        //     console.log(`syncHistory: Trimmed ${trimAmount} entries to respect maxSize of ${maxSizeRef.current}`);
+        //     setCurrentState(trimmedHistory[finalIndex].state);
+        //     if (devWarningsRef.current) {
+        //         console.warn(`syncHistory: Trimmed ${trimAmount} entries to respect maxSize of ${maxSizeRef.current}`);
+        //     }
+        // } else {
+        //     // Set history as-is
+        //     setHistory(historyToSet);
+        //     setCurrentIndex(finalIndex);
+        //     console.log(`syncHistory: Synchronized ${historyToSet.length} states, current index: ${finalIndex}`);
+        //     setCurrentState(historyToSet[finalIndex].state);
+        // }
+        // if (devWarningsRef.current) {
+        //     console.log(`syncHistory: Synchronized ${historyToSet.length} states, current index: ${finalIndex}`);
+        // }
+    }, []);
+    // Configuration setters
+    const setMaxSize = useCallback((size) => {
+        maxSizeRef.current = size;
+        if (size !== 'unlimited') {
+            enforceMaxSize();
+        }
+    }, [enforceMaxSize]);
+    const setBatchMode = useCallback(async (enabled, forceHistory = false) => {
+        const wasInBatch = batchModeRef.current;
+        console.log(`🔧 setBatchMode called: enabled=${enabled}, wasInBatch=${wasInBatch}, currentIndex=${currentIndexRef.current}, historyLength=${history.length}`);
+        if (enabled && !wasInBatch) {
+            // Starting batch mode - save current state as batch start
+            batchModeRef.current = true;
+            batchStartIndexRef.current = currentIndexRef.current;
+            batchStartStateRef.current = currentStateRef.current;
+            console.log("🔧 setBatchMode(true): Starting batch mode", {
+                currentState: currentStateRef.current,
+                currentIndex: currentIndexRef.current,
+                batchStartState: currentStateRef.current
+            });
+        }
+        else if (!enabled && wasInBatch) {
+            // Guard against double execution
+            console.log("🔧 setBatchMode: Ending batch mode", batchModeProcessingRef.current);
+            if (batchModeProcessingRef.current) {
+                console.log("⚠️ setBatchMode(false) already processing, skipping duplicate call");
+                return;
+            }
+            console.log("🔧 setBatchMode: Ending batch mode", currentStateRef.current, `batchStartIndex=${batchStartIndexRef.current}`);
+            // Ending batch mode - commit final state to history
+            batchModeProcessingRef.current = true;
+            batchModeRef.current = false;
+            // Only add to history if state actually changed from batch start
+            const statesEqual = batchStartStateRef.current ?
+                compareAdjustmentStates(currentStateRef.current, batchStartStateRef.current) : true;
+            console.log("🔧 setBatchMode(false): Comparing states", {
+                currentState: currentStateRef.current,
+                batchStartState: batchStartStateRef.current,
+                statesEqual,
+                forceHistory,
+                willAddToHistory: batchStartStateRef.current && (!statesEqual || forceHistory)
+            });
+            if (batchStartStateRef.current && (!statesEqual || forceHistory)) {
+                // Generate a unique task ID for this history entry
+                const taskId = `task_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+                console.log('📋 Before SetHistory state for backend:', batchStartIndexRef.current, currentStateRef.current, history.length);
+                // Store variables for backend call BEFORE setHistory
+                let replaceFromTaskId;
+                const batchStartIndex = batchStartIndexRef.current ?? currentIndexRef.current;
+                const wasInMiddleOfHistory = batchStartIndex < history.length - 1;
+                if (wasInMiddleOfHistory) {
+                    // Get the task_id from the original history entry to use as replace_from
+                    const currentHistoryEntry = history[batchStartIndex];
+                    replaceFromTaskId = currentHistoryEntry?.taskId;
+                    console.log(`📍 Was in middle of history (index ${batchStartIndex}), using replace_from: ${replaceFromTaskId}`);
+                }
+                else {
+                    console.log(`📍 At latest history (index ${batchStartIndex}), no replace_from needed`);
+                }
+                setHistory(prevHistory => {
+                    // Check if we were in the middle of history BEFORE any truncation
+                    // Handle case where batchStartIndexRef.current might be null (e.g., after undo)
+                    const batchStartIndex = batchStartIndexRef.current ?? currentIndexRef.current;
+                    const truncatedHistory = prevHistory.slice(0, batchStartIndex + 1);
+                    const newHistoryEntry = {
+                        state: currentStateRef.current,
+                        taskId: taskId
+                    };
+                    const newHistory = [...truncatedHistory, newHistoryEntry];
+                    currentIndexRef.current = newHistory.length - 1;
+                    return newHistory;
+                });
+                // Call controller to create history in backend - OUTSIDE of setHistory callback
+                if (internalOptions.controller && internalOptions.firebaseUid && internalOptions.currentImageId) {
+                    try {
+                        console.log('🔄 Creating editor history in backend for batch mode end');
+                        console.log('📋 Current state for backend:', batchStartIndexRef.current, currentStateRef.current, history.length);
+                        const createEditorConfigPayload = {
+                            gallery_id: internalOptions.currentImageId,
+                            task_id: taskId,
+                            color_adjustment: convertAdjustmentStateToColorAdjustment(currentStateRef.current),
+                            ...(replaceFromTaskId && { replace_from: replaceFromTaskId })
+                        };
+                        // Create editor config with current adjustments
+                        internalOptions.controller.createEditorConfig(internalOptions.firebaseUid, createEditorConfigPayload).then(() => {
+                            console.log('✅ Successfully created editor history in backend');
+                        }).catch((error) => {
+                            console.error('❌ Failed to create editor history in backend:', error);
+                        });
+                    }
+                    catch (error) {
+                        console.error('❌ Error calling controller.createEditorConfig:', error);
+                    }
+                }
+                else {
+                    if (internalOptions.devWarnings) {
+                        console.warn('⚠️ Controller, firebaseUid, or currentImageId not provided - skipping backend history creation');
+                    }
+                }
+            }
+            else {
+                if (forceHistory) {
+                    console.log("🔧 setBatchMode: Force history requested but no batch start state");
+                }
+                else {
+                    console.log("🔧 setBatchMode: No changes since batch start, not adding to history");
+                }
+            }
+            batchStartIndexRef.current = null;
+            batchStartStateRef.current = null;
+            batchModeProcessingRef.current = false; // Reset processing flag
+        }
+    }, [internalOptions, history]);
+    // Sync history from backend using getEditorHistory
+    const syncFromBackend = useCallback(async () => {
+        if (!internalOptions.controller || !internalOptions.firebaseUid || !internalOptions.currentImageId) {
+            console.warn('⚠️ syncFromBackend: Controller, firebaseUid, or currentImageId not provided - cannot sync from backend');
+            return;
+        }
+        try {
+            console.log('🔄 Syncing history from backend using getEditorHistory');
+            const historyResponse = await internalOptions.controller.getEditorHistory(internalOptions.firebaseUid, internalOptions.currentImageId);
+            // Sort history by timestamp (oldest first) before processing
+            const sortedHistory = [...historyResponse.history].sort((a, b) => {
+                const timeA = new Date(a.log.created_at).getTime();
+                const timeB = new Date(b.log.created_at).getTime();
+                return timeA - timeB; // Ascending order (oldest first)
+            });
+            // Convert backend history to AdjustmentState format with taskIds
+            const backendHistoryEntries = sortedHistory.map((entry) => ({
+                state: convertColorAdjustmentToAdjustmentState(entry.editor_config.color_adjustment),
+                taskId: entry.task_id
+            }));
+            // Find the index of the current task
+            let currentTaskIndex = -1;
+            if (historyResponse.current_task_id) {
+                currentTaskIndex = backendHistoryEntries.findIndex(entry => entry.taskId === historyResponse.current_task_id);
+            }
+            // If current_task_id is not found in history, default to the last entry
+            if (currentTaskIndex === -1 && backendHistoryEntries.length > 0) {
+                currentTaskIndex = backendHistoryEntries.length - 1;
+                console.warn(`⚠️ Current task ID "${historyResponse.current_task_id}" not found in history, defaulting to last entry`);
+            }
+            // Handle empty history case
+            if (backendHistoryEntries.length === 0) {
+                console.log('📝 Backend history is empty, keeping current local history');
+                return;
+            }
+            // Exit batch mode if active
+            if (batchModeRef.current) {
+                batchModeRef.current = false;
+                batchStartIndexRef.current = null;
+                batchStartStateRef.current = null;
+            }
+            // Update history state with backend data
+            setHistory(backendHistoryEntries);
+            currentIndexRef.current = Math.max(0, currentTaskIndex);
+            console.log(`📍 Setting current index to: ${Math.max(0, currentTaskIndex)} (task_id: ${historyResponse.current_task_id})`);
+            currentStateRef.current = backendHistoryEntries[Math.max(0, currentTaskIndex)].state;
+            setCurrentState(backendHistoryEntries[Math.max(0, currentTaskIndex)].state);
+            console.log(`✅ Successfully synced ${backendHistoryEntries.length} history entries from backend`);
+            console.log(`📍 Set current index to: ${Math.max(0, currentTaskIndex)} (task_id: ${historyResponse.current_task_id})`);
+        }
+        catch (error) {
+            console.error('❌ Failed to sync history from backend:', error);
+            throw error;
+        }
+    }, [internalOptions]);
+    // History info object
+    const historyInfo = useMemo(() => ({
+        canUndo: currentIndex > 0,
+        canRedo: currentIndex < history.length - 1,
+        currentIndex: currentIndex,
+        totalStates: history.length,
+        historySize: getMemoryUsage(),
+        isBatchMode: batchModeRef.current
+    }), [history.length, getMemoryUsage, currentIndex]);
+    // Actions object - stabilized with useMemo
+    const actions = useMemo(() => ({
+        pushState,
+        undo,
+        redo,
+        jumpToIndex,
+        clearHistory,
+        getHistory,
+        trimHistory,
+        syncFromBackend
+    }), [pushState, undo, redo, jumpToIndex, clearHistory, getHistory, trimHistory, syncFromBackend]);
+    // 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,
+        currentIndex,
+        historyInfo,
+        actions,
+        config
+    };
+}