Custom Gesture Chrome Extension

A Chrome extension that allows you to define and execute custom gestures on websites with modifier key support. Works seamlessly with OS and browser gestures by using modifier keys (Alt, Ctrl, Shift) to distinguish custom gestures from default behaviors.

✨ Features

• Custom Gesture Recognition: Define swipe gestures (left, right, up, down) with modifier keys
• Site-Specific Gestures: Configure different gestures for different websites
• Visual Feedback: See your gestures as you perform them with real-time trail visualization
• Pre-configured Presets: Quick setup for popular sites (YouTube, GitHub, Gmail)
• Multiple Action Types: Navigate, scroll, tab management, media control, custom scripts
• Non-Intrusive: Only intercepts gestures with modifier keys, allowing normal browser behavior
• Full UI: Popup shows active gestures, Options page for configuration

🚀 Installation

1. Clone or download this repository
2. Install dependencies:

   npm install

3. Build the extension:

   npm run build

4. Load in Chrome:
   • Open chrome://extensions/
   • Enable "Developer mode" (top right)
   • Click "Load unpacked"
   • Select the dist folder

📖 Usage

Quick Start with Presets

1. Click the extension icon in Chrome toolbar
2. Click "Configure Gestures"
3. Click on a preset card (YouTube, GitHub, or Gmail)
4. Visit the site and try the gestures!

Pre-configured Gestures

YouTube:

• Alt + Swipe Right: Play/Pause video
• Alt + Swipe Up: Volume up
• Alt + Swipe Down: Volume down
• Alt + Swipe Left: Mute/Unmute

GitHub:

• Alt + Swipe Left: Go back
• Alt + Swipe Right: Go forward
• Alt + Swipe Up: Scroll to top
• Alt + Swipe Down: Scroll to bottom

Gmail:

• Alt + Swipe Right: Archive email
• Alt + Swipe Left: Delete email
• Alt + Swipe Down: Mark as read

Creating Custom Gestures

1. Open extension options (right-click icon → Options)
2. Click "+ Add New Gesture"
3. Configure:
   • Site Pattern: Leave empty for all sites, or specify domain (e.g., youtube.com)
   • Gesture Pattern: Choose swipe direction
   • Modifier Keys: Select Alt, Ctrl, and/or Shift
   • Action Type: Choose what the gesture does
   • Action Parameter: Specify the action details
4. Click "Save Gesture"

Action Types

• Navigate: back, forward, reload
• Scroll: up, down, top, bottom
• Tab: new, close, next, prev
• Media: play, pause, playPause, mute, volumeUp, volumeDown
• Script: Custom JavaScript code to execute

🎯 How It Works

The extension follows this flow:

1. User performs a gesture (with modifier keys)
2. Extension detects the gesture
3. If gesture is mapped → Execute custom action
4. If gesture is not mapped → Allow normal browser behavior

This design ensures that:

• Default Chrome gestures still work (e.g., swipe without modifiers)
• Site-specific gestures still work
• Only gestures with modifier keys trigger custom actions

🏗️ Architecture

Project Structure

src/
├── background/
│   ├── configuration-manager.js  # Manages gesture configuration
│   └── service-worker.js         # Background service worker
├── content/
│   ├── content-script.js         # Main coordinator
│   ├── event-interceptor.js      # Captures pointer events
│   ├── gesture-recognizer.js     # Pattern matching
│   ├── gesture-handler.js        # Action execution
│   └── visual-feedback.js        # Visual gesture feedback
├── shared/
│   ├── constants.js              # Shared constants
│   ├── types.js                  # Type definitions
│   └── utils.js                  # Utility functions
└── ui/
    ├── options.html/js           # Options page
    └── popup.html/js             # Extension popup

Components

• EventInterceptor: Captures pointer events with 50ms delay for OS gesture priority
• GestureRecognizer: Analyzes movement patterns and matches against configured gestures
• GestureHandler: Executes the mapped action (6 built-in action types)
• VisualFeedback: Shows real-time gesture trail with SVG overlay
• ConfigurationManager: Manages gesture storage and site-specific presets
• ServiceWorker: Background lifecycle and message handling

Event Flow

1. EventInterceptor: Captures pointer events and tracks modifier keys
2. GestureRecognizer: Analyzes movement (distance, direction, velocity, duration)
3. GestureHandler: Executes action if gesture matches configuration
4. VisualFeedback: Shows blue trail during gesture, green/red flash on completion

🧪 Development

Running Tests

npm test

All 113 tests pass, covering:

• Event interception and modifier key tracking
• Gesture recognition and pattern matching
• Action execution for all handler types
• Configuration management
• Service worker message handling

Building

npm run build        # Production build
npm run build:dev    # Development build with source maps

🔧 Technical Details

Gesture Recognition

• Minimum Distance: 100px
• Maximum Duration: 500ms
• Multi-touch Support: Up to 5 simultaneous touch points
• Modifier Keys: Alt, Ctrl, Shift, Meta
• OS Gesture Delay: 50ms to allow OS gestures priority

Browser Compatibility

• Chrome/Edge (Manifest V3)
• Supports mouse, touchpad, and touchscreen input
• Requires Pointer Events API support

Permissions

• storage: Save gesture configuration
• activeTab: Execute actions on current tab
• <all_urls>: Inject content script on all pages

📝 License

MIT License - feel free to use and modify!

🤝 Contributing

Contributions welcome! Please ensure all tests pass before submitting PRs.

npm test

🐛 Troubleshooting

Gestures not working?

• Make sure you're holding the modifier key (Alt by default)
• Check that gestures are configured for the current site
• Reload the page after installing/updating the extension

Visual feedback not showing?

• Visual feedback is enabled by default
• Check browser console for errors

Conflicts with other extensions?

• Try disabling other gesture extensions
• Use different modifier key combinations