@readium/navigator-html-injectables 2.2.5 → 2.3.1-alpha.1

package/src/modules/snapper/ColumnSnapper.ts

@@ -6,8 +6,17 @@ import { ModuleName } from "../ModuleLibrary";
 import { Locator, LocatorLocations, LocatorText } from "@readium/shared";
 import { rangeFromLocator } from "../../helpers/locator";
 import { ReadiumWindow, deselect, findFirstVisibleLocator } from "../../helpers/dom";
+import { PatternAnalyzer } from "../../protection/PatternAnalyzer";
+import { BaseSuspiciousActivityEvent } from "../Peripherals";
+import { isTypedOMSupported } from "../../helpers/css";
 
 const COLUMN_SNAPPER_STYLE_ID = "readium-column-snapper-style";
+
+export interface SuspiciousSnappingEvent extends BaseSuspiciousActivityEvent {
+    type: "suspicious_snapping";
+    event: null;
+}
+
 const SNAP_DURATION = 200; // Milliseconds
 
 enum ScrollTouchState {
@@ -21,8 +30,11 @@ enum ScrollTouchState {
  */
 export class ColumnSnapper extends Snapper {
     static readonly moduleName: ModuleName = "column_snapper";
+    private isSnapProtectionEnabled = false;
     private resizeObserver!: ResizeObserver;
     private mutationObserver!: MutationObserver;
+    private patternAnalyzer: PatternAnalyzer | null = null;
+    private lastTurnTime: number = 0;
     private wnd!: ReadiumWindow;
     private comms!: Comms;
     private doc() { return this.wnd.document.scrollingElement as HTMLElement; }
@@ -72,6 +84,7 @@ export class ColumnSnapper extends Snapper {
     private alreadyScrollLeft = 0;
     private overscroll = 0;
     private cachedScrollWidth = 0; // We have to cache this because during overscroll (transform, or left) the width is incorrect due to browser
+    
     private takeOverSnap() {
         this.snappingCancelled = true;
         this.clearTouches();
@@ -80,7 +93,7 @@ export class ColumnSnapper extends Snapper {
         // translate3d(XXXpx, 0px, 0px) -> slice 12 -> XXXpx, 0px, 0px) -> split "px" [0] -> XXX
         this.overscroll = doc.style.transform?.length > 12 ? parseFloat(doc.style.transform.slice(12).split("px")[0]) : 0;
     }
-
+    
     // Snaps the current offset to the page width.
     snapCurrentOffset(smooth=false, noprogress=false) {
         const startX = this.wnd.scrollX > 0 ? this.wnd.scrollX : this.alreadyScrollLeft;
@@ -96,6 +109,11 @@ export class ColumnSnapper extends Snapper {
             ((factor * cdo) > 0 ? 2 : 1);
 
         const so = this.snapOffset(currentOffset + hurdle);
+        
+        const direction = so > this.scrollOffset() ? "right" : "left";
+
+        this.checkSuspiciousSnap(direction, Math.abs(so - this.scrollOffset()));
+        
         if(smooth && so !== this.scrollOffset()) { // Smooth snapping
             this.snappingCancelled = false;
             const position = (start: number, end: number, elapsed: number, period: number) => {
@@ -116,7 +134,13 @@ export class ColumnSnapper extends Snapper {
                 const spos = position(startX, so, elapsed, period);
                 doc.scrollLeft = spos;
                 if(this.overscroll !== 0)
-                    doc.style.transform = `translate3d(${-lpos}px, 0px, 0px)`;
+                    if(isTypedOMSupported) {
+                        doc.attributeStyleMap.set("transform", new CSSTransformValue([
+                            new CSSTranslate(CSS.px(-lpos), CSS.px(0), CSS.px(0))
+                        ]));
+                    } else {
+                        doc.style.transform = `translate3d(${-lpos}px, 0px, 0px)`;
+                    }
 
                 if (elapsed < period)
                     this.wnd.requestAnimationFrame(step);
@@ -220,10 +244,22 @@ export class ColumnSnapper extends Snapper {
         const newpos = this.alreadyScrollLeft + dro;
         if(newpos < 0) {
             this.overscroll = newpos;
-            this.doc().style.transform = `translate3d(${-this.overscroll}px, 0px, 0px)`;
+            if(isTypedOMSupported) {
+                this.doc().attributeStyleMap.set("transform", new CSSTransformValue([
+                    new CSSTranslate(CSS.px(-newpos), CSS.px(0), CSS.px(0))
+                ]));
+            } else {
+                this.doc().style.transform = `translate3d(${-newpos}px, 0px, 0px)`;
+            }
         } else if((newpos + this.wnd.innerWidth) > this.cachedScrollWidth) {
             this.overscroll = newpos;
-            this.doc().style.transform = `translate3d(${-newpos}px, 0px, 0px)`;
+            if(isTypedOMSupported) {
+                this.doc().attributeStyleMap.set("transform", new CSSTransformValue([
+                    new CSSTranslate(CSS.px(-newpos), CSS.px(0), CSS.px(0))
+                ]));
+            } else {
+                this.doc().style.transform = `translate3d(${-newpos}px, 0px, 0px)`;
+            }
         } else {
             this.overscroll = 0;
             this.doc().style.removeProperty("transform");
@@ -232,6 +268,37 @@ export class ColumnSnapper extends Snapper {
     }
     private readonly onTouchMover = this.onTouchMove.bind(this);
 
+    private enableSnapProtection() {
+        if (!this.patternAnalyzer) {
+            this.patternAnalyzer = new PatternAnalyzer({
+                maxVelocity: this.wnd.innerWidth,  // page width
+                minVariance: 0.1,   // Allow for some variation in swipe speed
+                historySize: 5,      // Fewer samples needed for swipe detection
+                maxConsistentScrolls: 3,  // Lower threshold for consistent scrolling
+                minDirectionChanges: 0.3  // Require more direction changes
+            });
+            this.isSnapProtectionEnabled = true;
+            this.comms?.log("Snap protection enabled");
+        }
+    }
+
+    private checkSuspiciousSnap(direction: "left" | "right", distance: number) {
+        if (!this.isSnapProtectionEnabled || !this.patternAnalyzer) return;
+
+        const now = Date.now();
+        const timeDelta = now - (this.lastTurnTime || now);
+        this.lastTurnTime = now;
+
+        const isSuspicious = this.patternAnalyzer.analyze(direction, distance, timeDelta);
+        if (isSuspicious) {
+            this.comms?.send("content_protection", {
+                type: "suspicious_snapping",
+                timestamp: Date.now(),
+                event: null
+            } as SuspiciousSnappingEvent);
+        }
+    }
+
     mount(wnd: ReadiumWindow, comms: Comms): boolean {
         this.wnd = wnd;
         this.comms = comms;
@@ -317,6 +384,11 @@ export class ColumnSnapper extends Snapper {
         // For cases the resizeObserver is not able to detect cos body is not resizing despite colCount,
         // we need to check the syle attribute on the documentElement (ReadiumCSS props)
         this.mutationObserver.observe(wnd.document.documentElement, {attributes: true, attributeFilter: ["style"]});
+        
+        comms.register("scroll_protection", ColumnSnapper.moduleName, (_, ack) => {
+            this.enableSnapProtection();
+            ack(true);
+        });
 
         const scrollToOffset = (offset: number): boolean => {
             const oldScrollLeft = this.doc().scrollLeft;
@@ -427,6 +499,7 @@ export class ColumnSnapper extends Snapper {
                 if(change) {
                     this.reportProgress();
                     deselect(this.wnd);
+                    this.checkSuspiciousSnap("left", this.wnd.innerWidth);
                 }
                 ack(change);
             });
@@ -441,6 +514,7 @@ export class ColumnSnapper extends Snapper {
                 if(change) {
                     this.reportProgress();
                     deselect(this.wnd);
+                    this.checkSuspiciousSnap("right", this.wnd.innerWidth);
                 }
                 ack(change);
             });
@@ -478,7 +552,7 @@ export class ColumnSnapper extends Snapper {
         wnd.addEventListener("touchmove", this.onTouchMover, { passive: true });
 
         // Safari hack, otherwise other events won't register
-        wnd.document.addEventListener('touchstart', () => {});
+        wnd.document.addEventListener("touchstart", () => {});
 
         comms.log("ColumnSnapper Mounted");
         return true;
@@ -490,6 +564,12 @@ export class ColumnSnapper extends Snapper {
         this.resizeObserver.disconnect();
         this.mutationObserver.disconnect();
 
+        if (this.patternAnalyzer) {
+            this.patternAnalyzer.clear();
+            this.patternAnalyzer = null;
+            this.isSnapProtectionEnabled = false;
+        }
+
         wnd.removeEventListener("touchstart", this.onTouchStarter);
         wnd.removeEventListener("touchend", this.onTouchEnder);
         wnd.removeEventListener("touchmove", this.onTouchMover);

package/src/modules/snapper/ScrollSnapper.ts

@@ -5,14 +5,27 @@ import { ModuleName } from "../ModuleLibrary";
 import { Snapper } from "./Snapper";
 import { rangeFromLocator } from "../../helpers/locator";
 import { forceWebkitRecalc } from "../../helpers/document";
+import { PatternAnalyzer } from "../../protection/PatternAnalyzer";
+import { SCROLL_PROTECTION_CONFIG } from "../../protection/config";
+import { BaseSuspiciousActivityEvent } from "../Peripherals";
 
 const SCROLL_SNAPPER_STYLE_ID = "readium-scroll-snapper-style";
 
+export interface SuspiciousScrollingEvent extends BaseSuspiciousActivityEvent {
+    type: "suspicious_scrolling";
+    scrollDelta: number;
+    scrollDirection: "up" | "down";
+    targetElement: { tagName: string } | null;
+}
+
 export class ScrollSnapper extends Snapper {
     static readonly moduleName: ModuleName = "scroll_snapper";
     private wnd!: ReadiumWindow;
     private comms!: Comms;
     private resizeObserver!: ResizeObserver;
+    private patternAnalyzer: PatternAnalyzer | null = null;
+    private lastScrollTime: number = 0;
+    private isScrollProtectionEnabled = false;
 
     private initialScrollHandled = false;
     private isScrolling = false;
@@ -41,7 +54,7 @@ export class ScrollSnapper extends Snapper {
         });
     }
 
-    private handleScroll = () => {
+    private handleScroll = (_e: Event) => {
         if (!this.comms.ready) return;
         
         // We have to filter scroll from resize events
@@ -68,6 +81,31 @@ export class ScrollSnapper extends Snapper {
                 const deltaY = currentScrollTop - this.lastScrollTop;
                 this.lastScrollTop = currentScrollTop;
 
+                if (this.isScrollProtectionEnabled && Math.abs(deltaY) > 5) { // Ignore tiny scrolls
+                    const now = Date.now();
+                    const timeDelta = now - (this.lastScrollTime || now);
+                    if (this.patternAnalyzer) {
+                        const isSuspicious = this.patternAnalyzer.analyze(
+                            deltaY > 0 ? "down" : "up",
+                            Math.abs(deltaY),
+                            timeDelta
+                        );
+                        if (isSuspicious) {
+                            const target = _e.target && "tagName" in _e.target ? 
+                                { tagName: (_e.target as Element).tagName } : null;
+                                
+                            this.comms?.send("content_protection", {
+                                type: "suspicious_scrolling",
+                                timestamp: Date.now(),
+                                scrollDelta: deltaY,
+                                scrollDirection: deltaY > 0 ? "down" : "up",
+                                targetElement: target
+                            } as SuspiciousScrollingEvent);
+                        }
+                    }
+                    this.lastScrollTime = now;
+                }
+
                 this.comms.send("scroll", deltaY);
             
                 this.isScrolling = false;
@@ -75,6 +113,14 @@ export class ScrollSnapper extends Snapper {
         }
     };
 
+    private enableScrollProtection() {
+        if (!this.patternAnalyzer) {
+            this.patternAnalyzer = new PatternAnalyzer(SCROLL_PROTECTION_CONFIG);
+            this.isScrollProtectionEnabled = true;
+            this.comms?.log("Scroll protection enabled");
+        }
+    }
+
     mount(wnd: ReadiumWindow, comms: Comms): boolean {
         this.wnd = wnd;
         this.comms = comms;
@@ -222,6 +268,11 @@ export class ScrollSnapper extends Snapper {
             ack(true);
         });
 
+        comms.register("scroll_protection", ScrollSnapper.moduleName, (_, ack) => {
+            this.enableScrollProtection();
+            ack(true);
+        });
+
         comms.register([
             "go_next",
             "go_prev",
@@ -247,6 +298,13 @@ export class ScrollSnapper extends Snapper {
         this.resizeObserver.disconnect();
         if (this.handleScroll) wnd.removeEventListener("scroll", this.handleScroll);
         wnd.document.getElementById(SCROLL_SNAPPER_STYLE_ID)?.remove();
+
+        if (this.patternAnalyzer) {
+            this.patternAnalyzer.clear();
+            this.patternAnalyzer = null;
+            this.isScrollProtectionEnabled = false;
+        }
+
         comms.log("ScrollSnapper Unmounted");
         return true;
     }

package/src/modules/snapper/WebPubSnapper.ts

@@ -5,6 +5,11 @@ import { ModuleName } from "../ModuleLibrary";
 import { Snapper } from "./Snapper";
 import { rangeFromLocator } from "../../helpers/locator";
 import { forceWebkitRecalc } from "../../helpers/document";
+import { PatternAnalyzer } from "../../protection/PatternAnalyzer";
+import { SCROLL_PROTECTION_CONFIG } from "../../protection/config";
+import { SuspiciousScrollingEvent } from "./ScrollSnapper";
+
+export type { SuspiciousScrollingEvent };
 
 export class WebPubSnapper extends Snapper {
     static readonly moduleName: ModuleName = "webpub_snapper";
@@ -12,6 +17,9 @@ export class WebPubSnapper extends Snapper {
     private wnd!: ReadiumWindow;
     private comms!: Comms;
     private resizeObserver!: ResizeObserver;
+    private patternAnalyzer: PatternAnalyzer | null = null;
+    private lastScrollTime: number = 0;
+    private isScrollProtectionEnabled = false;
 
     private initialScrollHandled = false;
     private isScrolling = false;
@@ -38,7 +46,7 @@ export class WebPubSnapper extends Snapper {
         });
     }
 
-    private handleScroll = () => {
+    private handleScroll = (_e: Event) => {
         if (!this.comms.ready) return;
 
         // Filter resize events
@@ -63,6 +71,32 @@ export class WebPubSnapper extends Snapper {
                 const deltaY = currentScrollTop - this.lastScrollTop;
                 this.lastScrollTop = currentScrollTop;
 
+                // Record scroll for pattern analysis if protection is enabled
+                if (this.isScrollProtectionEnabled && Math.abs(deltaY) > 5) { // Ignore tiny scrolls
+                    const now = Date.now();
+                    const timeDelta = now - (this.lastScrollTime || now);
+                    if (this.patternAnalyzer) {
+                        const isSuspicious = this.patternAnalyzer.analyze(
+                            deltaY > 0 ? "down" : "up",
+                            Math.abs(deltaY),
+                            timeDelta
+                        );
+                        if (isSuspicious) {
+                            const target = _e.target && "tagName" in _e.target ? 
+                                { tagName: (_e.target as Element).tagName } : null;
+                                
+                            this.comms?.send("content_protection", {
+                                type: "suspicious_scrolling",
+                                timestamp: Date.now(),
+                                scrollDelta: deltaY,
+                                scrollDirection: deltaY > 0 ? "down" : "up",
+                                targetElement: target
+                            } as SuspiciousScrollingEvent);
+                        }
+                    }
+                    this.lastScrollTime = now;
+                }
+
                 this.comms.send("scroll", deltaY);
 
                 this.isScrolling = false;
@@ -70,6 +104,14 @@ export class WebPubSnapper extends Snapper {
         }
     };
 
+    private enableScrollProtection() {
+        if (!this.patternAnalyzer) {
+            this.patternAnalyzer = new PatternAnalyzer(SCROLL_PROTECTION_CONFIG);
+            this.isScrollProtectionEnabled = true;
+            this.comms?.log("Scroll protection enabled");
+        }
+    }
+
     mount(wnd: ReadiumWindow, comms: Comms): boolean {
         this.wnd = wnd;
         this.comms = comms;
@@ -134,7 +176,7 @@ export class WebPubSnapper extends Snapper {
             });
         });
 
-        this.comms.register("go_id", WebPubSnapper.moduleName, (data, ack) => {
+        comms.register("go_id", WebPubSnapper.moduleName, (data, ack) => {
             const element = wnd.document.getElementById(data as string);
             if(!element) {
                 ack(false);
@@ -197,6 +239,11 @@ export class WebPubSnapper extends Snapper {
             ack(true);
         });
 
+        comms.register("scroll_protection", WebPubSnapper.moduleName, (_, ack) => {
+            this.enableScrollProtection();
+            ack(true);
+        });
+
         comms.register([
             "go_next",
             "go_prev",
@@ -220,7 +267,14 @@ export class WebPubSnapper extends Snapper {
         comms.unregisterAll(WebPubSnapper.moduleName);
         this.resizeObserver.disconnect();
         if (this.handleScroll) wnd.removeEventListener("scroll", this.handleScroll);
+        
+        if (this.patternAnalyzer) {
+            this.patternAnalyzer.clear();
+            this.patternAnalyzer = null;
+            this.isScrollProtectionEnabled = false;
+        }
+
         comms.log("WebPubSnapper Unmounted");
         return true;
     }
-}
+}

package/src/protection/BulkCopyProtector.ts

@@ -0,0 +1,134 @@
+import { ReadiumWindow } from "../helpers/dom";
+
+interface CopyAttempt {
+    timestamp: number;
+    length: number;
+    wasBlocked: boolean;
+}
+
+export interface BulkCopyProtectionOptions {
+    enabled: boolean;
+    maxSelectionPercent: number;
+    absoluteMaxChars: number;
+    minThreshold: number;
+    historySize: number;
+}
+
+export class BulkCopyProtector {
+    private options: BulkCopyProtectionOptions;
+    private copyHistory: CopyAttempt[] = [];
+    private lastSelectionLength = 0;
+    private lastSelectionTime = 0;
+
+    constructor(
+        private readonly window: ReadiumWindow,
+        options: BulkCopyProtectionOptions
+    ) {
+        this.options = options;
+    }
+
+    private cleanupOldHistory(now: number): void {
+        // Keep history for the last 10 seconds
+        const historyWindow = 10000; // 10 seconds
+        this.copyHistory = this.copyHistory.filter(
+            attempt => now - attempt.timestamp < historyWindow
+        );
+        
+        // Trim to max history size
+        if (this.copyHistory.length > this.options.historySize) {
+            this.copyHistory = this.copyHistory.slice(-this.options.historySize);
+        }
+    }
+
+    private isSuspiciousPattern(now: number): boolean {
+        if (this.copyHistory.length < 3) return false;
+        
+        // Check for rapid successive copy attempts
+        const recentAttempts = this.copyHistory.filter(
+            attempt => now - attempt.timestamp < 2000 // Last 2 seconds
+        );
+        
+        if (recentAttempts.length >= 3) {
+            // If multiple rapid copy attempts, it's suspicious
+            return true;
+        }
+        
+        // Check for increasing selection sizes (bulk copy pattern)
+        const increasingSelections = this.copyHistory
+            .slice()
+            .sort((a, b) => a.timestamp - b.timestamp)
+            .every((attempt, i, arr) => {
+                if (i === 0) return true;
+                return attempt.length > arr[i - 1].length * 1.5; // Each selection is significantly larger
+            });
+            
+        return increasingSelections;
+    }
+
+    public shouldAllowCopy(event: ClipboardEvent): boolean {
+        if (!this.options.enabled) return true;
+
+        const selection = this.window.getSelection();
+        if (!selection) return true;
+        
+        const selectedText = selection.toString();
+        const selectedLength = selectedText.length;
+        const docLength = this.window.document.body.innerText.length;
+        const now = Date.now();
+
+        // Clean up old history entries
+        this.cleanupOldHistory(now);
+
+        // Always allow small selections
+        if (selectedLength < this.options.minThreshold) {
+            this.copyHistory.push({
+                timestamp: now,
+                length: selectedLength,
+                wasBlocked: false
+            });
+            return true;
+        }
+
+        const timeSinceLastSelection = now - this.lastSelectionTime;
+        
+        // Check for rapid successive selections
+        const isRapidSelection = 
+            timeSinceLastSelection < 100 && 
+            selectedLength > this.lastSelectionLength * 1.5;
+            
+        const maxAllowedSelection = Math.min(
+            docLength * this.options.maxSelectionPercent,
+            this.options.absoluteMaxChars
+        );
+
+        // Check if this matches a suspicious pattern
+        const isSuspicious = this.isSuspiciousPattern(now);
+        
+        const shouldBlock = selectedLength > maxAllowedSelection || 
+                          isRapidSelection || 
+                          isSuspicious;
+
+        // Record this attempt in history
+        this.copyHistory.push({
+            timestamp: now,
+            length: selectedLength,
+            wasBlocked: shouldBlock
+        });
+
+        if (shouldBlock) {
+            event?.preventDefault();
+            return false;
+        }
+        
+        this.lastSelectionLength = selectedLength;
+        this.lastSelectionTime = now;
+        return true;
+    }
+
+    public destroy(): void {
+        this.lastSelectionLength = 0;
+        this.lastSelectionTime = 0;
+        this.copyHistory = [];
+        this.options.enabled = false;
+    }
+}

package/src/protection/KeyCombinationManager.ts

@@ -0,0 +1,139 @@
+import { KeyCombo, KeyboardPeripheral } from "./KeyboardCombinations";
+import { BaseKeyboardPeripheralEvent, KeyboardEventData, BasicTextSelection } from "../modules/Peripherals";
+import { ReadiumWindow } from "../helpers/dom";
+
+export type KeyHandler = (event: KeyboardEvent) => void;
+export type ActivityEventDispatcher = (event: KeyboardPeripheralEvent) => void;
+
+export interface KeyboardPeripheralEvent extends BaseKeyboardPeripheralEvent, KeyboardEventData {
+    type: string;
+}
+
+export interface KeyComboWithHandler extends KeyCombo {
+    handler?: (event: KeyboardEvent) => void;
+}
+
+export class KeyCombinationManager {
+    /**
+     * Checks if the given keyboard event matches any of the provided key combinations
+     */
+    public match(event: KeyboardEvent, combos: KeyCombo[]): boolean {
+        for (const combo of combos) {
+            const keyMatch = event.keyCode === combo.keyCode;
+            const ctrlMatch = combo.ctrl === undefined || event.ctrlKey === combo.ctrl;
+            const shiftMatch = combo.shift === undefined || event.shiftKey === combo.shift;
+            const altMatch = combo.alt === undefined || event.altKey === combo.alt;
+            const metaMatch = combo.meta === undefined || event.metaKey === combo.meta;
+            
+            if (keyMatch && ctrlMatch && shiftMatch && altMatch && metaMatch) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Creates an event handler that will call the provided handler when any of the key combinations match
+     */
+    public createKeyHandler(combos: KeyCombo[], handler: KeyHandler): (event: KeyboardEvent) => void {
+        return (event: KeyboardEvent) => {
+            if (this.match(event, combos)) {
+                event.preventDefault();
+                event.stopPropagation();
+                handler(event);
+            }
+        };
+    }
+
+    /**
+     * Creates a standardized activity event for keyboard shortcuts
+     */
+    private createActivityEvent(
+        event: KeyboardEvent, 
+        type: string,
+        targetFrameSrc: string,
+        wnd?: ReadiumWindow,
+    ): KeyboardPeripheralEvent {
+        // Capture selected text if window is available
+        let selectedText: Omit<BasicTextSelection, "targetFrameSrc"> | undefined;
+        if (wnd) {
+            const selection = wnd.getSelection();
+            const selectedTextStr = selection?.toString() || '';
+            const domRectList = (selectedTextStr && selection?.rangeCount) ? selection.getRangeAt(0)?.getClientRects() : null;
+            const rect = domRectList?.[0];
+            
+            if (rect && selectedTextStr) {
+                selectedText = {
+                    text: selectedTextStr,
+                    x: rect.x,
+                    y: rect.y,
+                    width: rect.width,
+                    height: rect.height
+                };
+            }
+        }
+
+        return {
+            type: type,
+            timestamp: Date.now(),
+            key: event.key,
+            code: event.code,
+            keyCode: event.keyCode,
+            ctrlKey: event.ctrlKey,
+            altKey: event.altKey,
+            shiftKey: event.shiftKey,
+            metaKey: event.metaKey,
+            targetFrameSrc: targetFrameSrc,
+            selectedText
+        };
+    }
+
+    /**
+     * Creates handlers for keyboard shortcuts with centralized activity event dispatch
+     */
+    public createKeyboardHandlers(
+        targetFrameSrc: string,
+        shortcuts: KeyboardPeripheral[],
+        dispatcher: ActivityEventDispatcher,
+        wnd?: ReadiumWindow,
+    ): KeyComboWithHandler[] {
+        const handlers: KeyComboWithHandler[] = [];
+
+        // Handle KeyboardPeripheral objects only
+        shortcuts.forEach(shortcut => {
+            handlers.push(...shortcut.keyCombos.map(combo => ({
+                ...combo,
+                handler: (event: KeyboardEvent) => {
+                    const eventType = shortcut.type;
+                    const activityEvent = this.createActivityEvent(event, eventType, targetFrameSrc, wnd);
+                    dispatcher(activityEvent);
+                }
+            })));
+        });
+
+        return handlers;
+    }
+
+    /**
+     * Creates a unified keyboard event handler that processes all shortcuts
+     */
+    public createUnifiedHandler(
+        targetFrameSrc: string,
+        shortcuts: KeyboardPeripheral[],
+        dispatcher: ActivityEventDispatcher,
+        wnd?: ReadiumWindow,
+    ): (event: KeyboardEvent) => void {
+        const handlers = this.createKeyboardHandlers(targetFrameSrc, shortcuts, dispatcher, wnd);
+        
+        return (event: KeyboardEvent) => {
+            for (const handlerConfig of handlers) {
+                if (this.match(event, [handlerConfig])) {
+                    event.preventDefault();
+                    event.stopPropagation();
+                    handlerConfig.handler!(event);
+                    return; // Stop after first match
+                }
+            }
+        };
+    }
+}