
KeyPilot Chrome Extension
------------------------------------

**Keyboard-first navigation for the web with instant visual feedback**

KeyPilot transforms your browsing experience by providing direct keyboard 
for common web interactions, eliminating the need for mouse navigation.


## ✨ Key Features

### ⌨️ Key Mappings

<!-- KP_KEY_MAPPINGS_START -->
> Generated by `extension/build.js` from `extension/src/config/constants.js` and `extension/manifest.json`. Do not edit by hand.

#### Navigation

| Keys | Action |
| --- | --- |
| `I` | Copy image under cursor (clipboard, or Media Library later) |
| `M` | Open the Media Library (coming soon). |
| `R` | Go Forward (History) |
| `U` | Copy URL under cursor (clipboard, or Media Library later) |
| `;` | Open Launcher (Quick Access to Sites) |
| `B` | Open Link in New Tab (Foreground) |
| `D` | Go Back (History) |
| `E` | Open Link Preview in Popover |
| `F` | Click Element |
| `G` | Open Link in New Tab (Background, like middle click) |
| `J` | Open Tab History (Branch-Retaining) |
| `L` | Open Omnibox (Address Bar Overlay) |
| `P` | Open Link in Popover |
| `S` | Go Back (History) |
| `.` | Columnize element under cursor (multi-column layout) |
| `N` | Scroll from a fixed origin: move the mouse away from the dot to scroll faster. Optional middle-click on empty page area (Settings → Scrolling). |
| `'` | Open KeyPilot Settings |
| `1` | Go to Site Root |

#### Tabs

| Keys | Action |
| --- | --- |
| `Q` | Move To Previous Tab |
| `T` | Open New Tab |
| `W` | Move To Next Tab |
| `A` | Close Tab |

#### Page navigation

| Keys | Action |
| --- | --- |
| `O` | Browse images, videos, and documents found on this page |
| `C` | Page Up (Instant) |
| `V` | Page Down (Instant) |
| `X` | Jump to the bottom of the scroll target (Fade hides the jump; Scroll animates) |
| `Z` | Jump to the top of the scroll target (Fade hides the jump; Scroll animates) |

#### Modes & UI

| Keys | Action |
| --- | --- |
| `Y` | Select intersecting HTML elements in a rectangle (or pick cumulative) |
| `Backspace` | Delete Mode |
| `H` | Select text (character level) and copy as rich text by default |
| `K` | Show/Hide the floating KeyPilot keyboard reference |
| `Esc` | Exit Focus |

<!-- KP_KEY_MAPPINGS_END -->




























































































































































































































































































































































































































































































































### Control Strip

Upper-left status strip (dark GUI Pro). **ON/OFF**, **KB** (keyboard reference), **Settings**, collapse, and close. Press **`Alt`+`J`** to restore after close. Options: **Settings → Control Strip**.






































































































































































































































































































































































































































































































































































































































































### 🎯 Smart Modes
- **Normal Mode**: Green crosshair cursor with all shortcuts active
- **Text Focus Mode**: Automatic activation in text fields with orange crosshair
- **Delete Mode**: Red X cursor for element deletion
- **Disabled Mode**: Complete extension disable (no visual elements or shortcuts)


The extension has its own criteria of what is
clickable under the mouse.  On hover, 
clickable link objects are outlined with a green rectangle. 
Clickable text fields (inputs with text, textarea, etc.)
are given an orange outline.

There is one main mode monitored, which is text mode (text entry).
That is when keys will enter text into a text field and
the only key that KeyPilot monitors is the ESC key, which
will move the mode back to hovering over page elements.
A text mode is activated either because the page focused on a text field,
usually on load, or the user clicked a text field (with regular mouse button
clicks or the F key in KeyPilot).  This triggers a 
semi-transparent overlay frame around the page frame as an internal
border of the web page and then the orange outlines
stays in place on the text field. 

The Backspace key activates a selection hovering mode where
the outlines is red and the second press of Backspace deletes
that page element.  The ESC key escapes the delete mode.




## 📦 Installation


### Manual Installation (Development)
1. Download or clone this repository
2. Run `npm run build` to build the extension (builds from `extension/` subdirectory)
3. Open `chrome://extensions/`
4. Enable "Developer mode"
5. Click "Load unpacked" and select the `extension/` subdirectory

### From Chrome Web Store (Future)
1. Visit the Chrome Web Store
2. Search for "KeyPilot"
3. Click "Add to Chrome"
4. Grant necessary permissions


## 🎮 Usage Guide

### Getting Started
1. **Install the extension** and grant permissions
2. **Navigate to any webpage** - the HUD and cursor appear instantly
3. **Move your mouse** to see the green crosshair cursor
4. **Press F** while hovering over links to activate them
5. **Press K** to toggle the keyboard panel.


### Smart Text Field Handling
- **Automatic Detection**: Extension detects when you're in text fields
- **Context Switching**: Only ESC key intercepted in text mode
- **Visual Feedback**: Orange crosshair indicates text focus mode
- **F Key Activation**: Hover over text fields and press F to focus them


## 🔧 Advanced Features

### Cross-Tab Synchronization
- Settings sync instantly across all open tabs
- Extension toggle affects all tabs simultaneously
- State persists across browser sessions


### Browser Compatibility
- ✅ **Chrome**: Full support (recommended)
- ✅ **Edge**: Full support  
- ⚠️ **Firefox**: Limited support
- ❌ **Safari**: Not supported

## 📁 Project Structure

The project is organized with a clear separation between extension code and project management files:

```
KeyPilot/
├── 📄 README.md                  # Project overview and documentation
├── 📄 package.json               # Node.js dependencies and scripts
├── 📄 babel.config.cjs           # Babel configuration
│
├── 📁 extension/                 # Chrome extension code
│   ├── 📄 manifest.json          # Chrome extension configuration
│   ├── 📄 background.js          # Service worker for global commands
│   ├── 📄 content-bundled.js     # Generated content script (do not edit)
│   ├── 📄 build.js               # Build system for bundling modules
│   ├── 📄 popup.html             # Extension popup interface
│   ├── 📄 popup.js               # Popup functionality
│   │
│   ├── 📁 src/                   # Source modules (edit these)
│   │   ├── 📄 content-script.js  # Entry point for content script
│   │   ├── 📄 keypilot.js        # Main orchestrator class
│   │   │
│   │   ├── 📁 config/
│   │   │   └── 📄 constants.js   # Central configuration constants
│   │   │
│   │   ├── 📁 modules/           # Core functionality modules
│   │   │   ├── 📄 state-manager.js           # Global state with subscriber pattern
│   │   │   ├── 📄 event-manager.js           # Base class for event handling
│   │   │   ├── 📄 cursor.js                  # Visual cursor overlays
│   │   │   ├── 📄 element-detector.js        # DOM traversal & classification
│   │   │   ├── 📄 activation-handler.js      # Click/interaction logic
│   │   │   ├── 📄 focus-detector.js          # Text field detection
│   │   │   ├── 📄 overlay-manager.js         # Visual feedback system
│   │   │   ├── 📄 keypilot-toggle-handler.js # Cross-tab state sync
│   │   │   ├── 📄 optimized-scroll-manager.js # Scroll optimization
│   │   │   ├── 📄 intersection-observer-manager.js # Performance monitoring
│   │   │   ├── 📄 shadow-dom-manager.js      # Shadow DOM support
│   │   │   └── 📄 style-manager.js           # CSS injection management
│   │   │
│   │   └── 📁 utils/             # Utility functions
│   │       └── 📄 logger.js      # Logging utilities
│   │
│   ├── 📁 styles/
│   │   └── 📄 popup.css          # Popup styling
│   │
│   ├── 📁 icons/                 # Extension icons
│   │   ├── 📄 icon.svg           # Source icon
│   │   ├── 📄 icon16.png         # 16x16 icon
│   │   ├── 📄 icon48.png         # 48x48 icon
│   │   └── 📄 icon128.png        # 128x128 icon
│   │
│   ├── 📁 tests/                 # Test suites
│   │   ├── 📄 setup.js           # Test configuration
│   │   ├── 📄 *.test.js          # Jest unit and integration tests
│   │   └── 📄 manual-*.md        # Manual testing procedures
│   │
│   └── 📁 test-pages/            # HTML test files for manual testing
│       └── 📄 test-*.html        # Interactive test pages
│
├── 📁 docs/                      # Project documentation
│   ├── 📁 architecture/          # Architecture and design documents
│   ├── 📁 performance/           # Performance analysis and reports
│   └── 📁 compatibility/         # Browser compatibility documentation
│
├── 📁 .kiro/                     # Kiro IDE configuration and specs
├── 📁 .vscode/                   # VS Code settings
├── 📁 .git/                      # Git repository
└── 📁 node_modules/              # Dependencies
```

### Key Files Explained

#### Extension Directory (`extension/`)
All Chrome extension code is contained within the `extension/` subdirectory:

- **`manifest.json`**: Chrome extension configuration and permissions
- **`background.js`**: Service worker managing extension state and communication
- **`content-bundled.js`**: Auto-generated from `src/` modules (never edit directly)
- **`build.js`**: Bundles ES6 modules into browser-compatible code

#### Source Architecture (`extension/src/`)
- **`content-script.js`**: Entry point that instantiates the main KeyPilot class
- **`keypilot.js`**: Main orchestrator that coordinates all modules
- **`config/constants.js`**: Central configuration for keybindings and selectors
- **`modules/`**: Single-responsibility classes following dependency injection pattern

#### Documentation (`docs/`)
- **`architecture/`**: Design documents and architectural decisions
- **`performance/`**: Performance analysis and optimization reports
- **`compatibility/`**: Browser compatibility testing and results

#### Development Workflow
1. **Edit**: Modify files in `extension/src/` directory or `extension/background.js`
2. **Build**: Run `npm run build` to regenerate `extension/content-bundled.js`
3. **Test**: Reload extension in Chrome from the `extension/` directory
4. **Debug**: Use browser console and test files in `extension/test-pages/`

## 📚 Documentation

For detailed technical documentation, see the `docs/` directory:

- **[Architecture Documentation](docs/architecture/)**: Design decisions, implementation details, and architectural patterns
- **[Performance Documentation](docs/performance/)**: Performance analysis, optimization reports, and benchmarking results
- **[Compatibility Documentation](docs/compatibility/)**: Browser compatibility testing results and cross-platform considerations

## 🛠️ Development

### Build System
```bash
# Build the extension (runs from extension/ subdirectory)
npm run build

# Alternative: build directly from extension directory
cd extension && node build.js


### Testing Guidelines
- Write tests for new features
- Test across different page types
- Verify cross-browser compatibility

### Code Style
- Use ES6+ features
- Follow modular architecture
- Add JSDoc comments for public APIs
- Maintain performance optimization

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

