feat(redaction): update to embedPDF v2.4.0 with unified redaction mode support (#5652)

# Description of Changes


Bump to EmbedPDF v2.4.0 plus update to the redaction methods


<!--
Please provide a summary of the changes, including:

- What was changed
- Why the change was made
- Any challenges encountered

Closes #(issue_number)
-->

---

## Checklist

### General

- [X] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [X] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md)
(if applicable)
- [ ] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md)
(if applicable)
- [X] I have performed a self-review of my own code
- [X] My changes generate no new warnings

### Documentation

- [ ] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [ ] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)

### Translations (if applicable)

- [ ] I ran
[`scripts/counter_translation.py`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docs/counter_translation.md)

### UI Changes (if applicable)

- [ ] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)

### Testing (if applicable)

- [X] I have tested my changes locally. Refer to the [Testing
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing)
for more details.

---------

Signed-off-by: Balázs Szücs <[email protected]>

frontend/src/core/components/viewer/AnnotationAPIBridge.tsx

@@ -88,6 +88,7 @@ type AnnotationApiSurface = {
   deselectAnnotation?: () => void;
   updateAnnotation?: (pageIndex: number, annotationId: string, patch: AnnotationPatch) => void;
   onAnnotationEvent?: (listener: (event: AnnotationEvent) => void) => void | (() => void);
+  purgeAnnotation?: (pageIndex: number, annotationId: string) => void;
 };
 
 type ToolDefaultsBuilder = (options?: AnnotationToolOptions) => AnnotationDefaults;
@@ -372,6 +373,11 @@ export const AnnotationAPIBridge = forwardRef<AnnotationAPI>(function Annotation
         const api = annotationApi as AnnotationApiSurface | undefined;
         return api?.getActiveTool?.() ?? null;
       },
+
+      purgeAnnotation: (pageIndex: number, annotationId: string) => {
+        const api = annotationApi as AnnotationApiSurface | undefined;
+        api?.purgeAnnotation?.(pageIndex, annotationId);
+      },
     }),
     [annotationApi, configureAnnotationTool, buildAnnotationDefaults]
   );

frontend/src/core/components/viewer/HistoryAPIBridge.tsx

@@ -146,6 +146,13 @@ export const HistoryAPIBridge = forwardRef<HistoryAPI>(function HistoryAPIBridge
       return historyApi ? historyApi.canRedo() : false;
     },
 
+    purgeByMetadata: <T,>(predicate: (metadata: T | undefined) => boolean, topic?: string) => {
+      if (historyApi?.purgeByMetadata) {
+        return historyApi.purgeByMetadata(predicate, topic);
+      }
+      return 0;
+    },
+
     subscribe: (listener: () => void) => {
       if (!historyApi?.onHistoryChange) {
         return () => {};

frontend/src/core/components/viewer/PanAPIBridge.tsx

@@ -48,7 +48,7 @@ function PanAPIBridgeInner({ documentId }: { documentId: string }) {
             currentPan.togglePan();
           },
           makePanDefault: () => {
-            // v2.3.0: makePanDefault may not exist, enable pan as fallback
+            // v2.5.0: makePanDefault may not exist, enable pan as fallback
             if ('makePanDefault' in currentPan && typeof (currentPan as any).makePanDefault === 'function') {
               (currentPan as any).makePanDefault();
             } else {

frontend/src/core/components/viewer/RedactionAPIBridge.tsx

@@ -3,6 +3,11 @@ import { useRedaction as useEmbedPdfRedaction } from '@embedpdf/plugin-redaction
 import { useRedaction } from '@app/contexts/RedactionContext';
 import { useActiveDocumentId } from '@app/components/viewer/useActiveDocumentId';
 
+/**
+ * RedactionAPIBridge - Uses embedPDF v2.5.0
+ * Bridges between the EmbedPDF redaction plugin and the Stirling-PDF RedactionContext.
+ * Uses the unified redaction mode (toggleRedact/enableRedact/endRedact).
+ */
 export function RedactionAPIBridge() {
   const activeDocumentId = useActiveDocumentId();
   
@@ -43,13 +48,22 @@ function RedactionAPIBridgeInner({ documentId }: { documentId: string }) {
   }, [state?.pendingCount, state?.activeType, state?.isRedacting, setPendingCount, setActiveType, setIsRedacting]);
 
   // Expose the EmbedPDF API through our context's ref
+  // Uses v2.5.0 unified redaction mode
   useImperativeHandle(redactionApiRef, () => ({
-    toggleRedactSelection: () => {
-      provides?.toggleRedactSelection();
+    // Unified redaction methods (v2.5.0)
+    toggleRedact: () => {
+      provides?.toggleRedact();
     },
-    toggleMarqueeRedact: () => {
-      provides?.toggleMarqueeRedact();
+    enableRedact: () => {
+      provides?.enableRedact();
     },
+    isRedactActive: () => {
+      return provides?.isRedactActive() ?? false;
+    },
+    endRedact: () => {
+      provides?.endRedact();
+    },
+    // Common methods
     commitAllPending: () => {
       provides?.commitAllPending();
       // Don't set redactionsApplied here - it should only be set after the file is saved

frontend/src/core/components/viewer/RedactionSelectionMenu.tsx

@@ -8,32 +8,30 @@ import CheckCircleIcon from '@mui/icons-material/CheckCircle';
 import { useRedaction } from '@app/contexts/RedactionContext';
 import { useActiveDocumentId } from '@app/components/viewer/useActiveDocumentId';
 
-// Use the official EmbedPDF v2.3.0 types
 export type { RedactionSelectionMenuProps };
 
 export function RedactionSelectionMenu(props: RedactionSelectionMenuProps) {
   const activeDocumentId = useActiveDocumentId();
-  
+
   // Don't render until we have a valid document ID
   if (!activeDocumentId) {
     return null;
   }
-  
+
   return (
-    <RedactionSelectionMenuInner 
+    <RedactionSelectionMenuInner
       documentId={activeDocumentId}
       {...props}
     />
   );
 }
 
-function RedactionSelectionMenuInner({ 
+function RedactionSelectionMenuInner({
   documentId,
   context,
-  selected, 
+  selected,
   menuWrapperProps,
 }: RedactionSelectionMenuProps & { documentId: string }) {
-  // Extract item and pageIndex from context (EmbedPDF v2.3.0 API)
   const item = context?.item;
   const pageIndex = context?.pageIndex;
   const { t } = useTranslation();
@@ -41,14 +39,14 @@ function RedactionSelectionMenuInner({
   const { setRedactionsApplied } = useRedaction();
   const wrapperRef = useRef<HTMLDivElement>(null);
   const [menuPosition, setMenuPosition] = useState<{ top: number; left: number } | null>(null);
-  
+
   // Merge refs - menuWrapperProps.ref is a callback ref
   const setRef = useCallback((node: HTMLDivElement | null) => {
     wrapperRef.current = node;
     // Call the EmbedPDF ref callback
     menuWrapperProps?.ref?.(node);
   }, [menuWrapperProps]);
-  
+
   const handleRemove = useCallback(() => {
     if (provides?.removePending && item && pageIndex !== undefined) {
       provides.removePending(pageIndex, item.id);
@@ -89,17 +87,17 @@ function RedactionSelectionMenuInner({
     };
 
     updatePosition();
-    
+
     // Update position on scroll/resize
     window.addEventListener('scroll', updatePosition, true);
     window.addEventListener('resize', updatePosition);
-    
+
     return () => {
       window.removeEventListener('scroll', updatePosition, true);
       window.removeEventListener('resize', updatePosition);
     };
   }, [selected, item]);
-  
+
   // Early return AFTER all hooks have been called
   if (!selected || !item) return null;
 
@@ -146,8 +144,8 @@ function RedactionSelectionMenuInner({
               <DeleteIcon style={{ fontSize: 18 }} />
             </ActionIcon>
           </Tooltip>
-          
-          <Tooltip 
+
+          <Tooltip
             label={t('redact.manual.applyWarning', '⚠️ Permanent application, cannot be undone and the data underneath will be deleted')}
             withArrow
             position="top"
@@ -172,15 +170,15 @@ function RedactionSelectionMenuInner({
   return (
     <>
       {/* Invisible wrapper that provides positioning - uses EmbedPDF's menuWrapperProps */}
-      <div 
-        ref={setRef} 
-        style={{ 
+      <div
+        ref={setRef}
+        style={{
           // Use EmbedPDF's positioning styles
           ...menuWrapperProps?.style,
           // Keep the wrapper invisible but still occupying space for positioning
           opacity: 0,
           pointerEvents: 'none',
-        }} 
+        }}
       />
       {typeof document !== 'undefined' && menuContent
         ? createPortal(menuContent, document.body)

frontend/src/core/components/viewer/viewerTypes.ts

@@ -25,6 +25,7 @@ export interface AnnotationAPI {
   deactivateTools: () => void;
   onAnnotationEvent?: (listener: (event: AnnotationEvent) => void) => void | (() => void);
   getActiveTool?: () => { id: AnnotationToolId } | null;
+  purgeAnnotation?: (pageIndex: number, annotationId: string) => void;
 }
 
 export interface HistoryAPI {
@@ -33,6 +34,15 @@ export interface HistoryAPI {
   canUndo: () => boolean;
   canRedo: () => boolean;
   subscribe?: (listener: () => void) => () => void;
+  /**
+   * Purges history entries that match the given predicate based on command metadata.
+   * Useful for removing commands that are no longer valid (e.g., after a permanent redaction commit).
+   * Added in embedPDF v2.4.0+
+   * @param predicate A function that returns true for commands that should be purged
+   * @param topic If provided, only purges entries for that specific topic
+   * @returns The number of entries that were purged
+   */
+  purgeByMetadata?: <T>(predicate: (metadata: T | undefined) => boolean, topic?: string) => number;
 }
 
 export type AnnotationToolId =