feat: implement replaceHistory() method to allow replacing history entries in the stack

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 12.4.2
+- **FEAT**(state-manager): Add `replaceHistory()` to replace an existing history entry in the stack (current pointer by default, or a custom index).
+
 ## 12.4.1
 - **FEAT**(main-editor): Add `captureImageOnDone` to `MainEditorConfigs` (default `true`) to make final `captureEditorImage()` on done optional.
 - **FIX**(main-editor): Prevent `_isProcessingFinalImage` from getting stuck by guarding done-flow cleanup with `try/finally`.

lib/features/main_editor/services/state_manager.dart

@@ -285,6 +285,28 @@ class StateManager {
     if (!skipUpdateActiveItems) updateActiveItems();
   }
 
+  /// Replaces a history entry in the stack.
+  ///
+  /// By default, the currently active history entry is replaced. You can
+  /// provide [index] to replace any specific history position.
+  ///
+  /// Throws an [ArgumentError] when [index] is out of range.
+  void replaceHistory(
+    EditorStateHistory history, {
+    int? index,
+    bool skipUpdateActiveItems = false,
+  }) {
+    final targetIndex = index ?? _historyPointer;
+
+    if (targetIndex < 0 || targetIndex >= _stateHistory.length) {
+      throw ArgumentError('History index out of range');
+    }
+
+    _stateHistory[targetIndex] = history;
+
+    if (!skipUpdateActiveItems) updateActiveItems();
+  }
+
   /// Redoes the last undone change, moving the history pointer forward by one
   /// step.
   /// If there is no forward change available, this operation will throw an

pubspec.yaml

@@ -1,6 +1,6 @@
 name: pro_image_editor
 description: "A Flutter image editor: Seamlessly enhance your images with user-friendly editing features."
-version: 12.4.1
+version: 12.4.2
 homepage: https://github.com/hm21/pro_image_editor/
 repository: https://github.com/hm21/pro_image_editor/
 documentation: https://github.com/hm21/pro_image_editor/