Keyboard Modifiers and Shortcuts in ego-browser: Complete Guide

ego-browser supports a Playwright-style keyboard API that enables agents to send individual key events and modifier combinations—including Alt, Control, Meta, Shift, and the platform-aware ControlOrMeta—through the page.keyboard.press() method.

The citrolabs/ego-lite repository provides a lightweight browser automation framework with comprehensive keyboard interaction capabilities. Understanding the supported keyboard modifiers and shortcuts is essential for automating form inputs, navigation, and text editing operations. This guide examines the implementation details found in the source code to show exactly which modifier keys and shortcut combinations ego-browser recognizes.

Supported Modifier Keys

The keyboard implementation in src/driver/keyboard.ts defines five distinct modifiers, each mapped to specific CDP (Chrome DevTools Protocol) bitfield values in the MODIFIER_BITS definition (lines 80-85):

• Alt: CDP bit 1
• Control: CDP bit 2
• Meta: CDP bit 4 (maps to ⌘ on macOS and the Windows key on Windows)
• Shift: CDP bit 8
• ControlOrMeta: Automatically resolves to Control on non-macOS platforms or Meta on macOS (handled in parseKeyCombo at lines 17-23)

These modifiers serve as building blocks for complex keyboard shortcuts, allowing agents to simulate platform-specific behaviors like save commands or text selection.

Shortcut Syntax and Parsing

The parseKeyCombo function in src/driver/keyboard.ts processes shortcut strings using Playwright's conventional syntax. Modifiers combine with base keys using the + separator.

Supported patterns include:

• Single modifiers: Control+a, Shift+Tab, Meta+Enter
• Multiple modifiers: Control+Shift+K
• Special keys: Alt+ArrowLeft, Escape, Enter

The parser handles edge cases such as literal "+" characters. When the base key is a plus sign (e.g., "+" or "Shift++"), the logic at lines 107-115 correctly distinguishes between the separator and the key itself, ensuring accurate event generation.

Built-in Editing Shortcuts

Beyond raw key events, ego-browser maps common editing shortcuts to CDP editing commands through the editingCommandsForKey function:

• Ctrl/Meta + a: Triggers selectAll (lines 64-70)
• Backspace (no modifier): Triggers deleteBackward (lines 71-73)
• Delete (no modifier): Triggers deleteForward (lines 74-76)

These mappings provide immediate access to standard text manipulation without requiring manual DOM operations.

Using the Keyboard API

The public interface is exposed through src/format.ts, which documents the page.keyboard.press(key, options?) method. According to the source comments at lines 45-55, the method accepts "Key or shortcut such as Enter or Meta+A."

Practical examples:

// Press a simple key
await page.keyboard.press('Enter');

// Select all text in the focused element
await page.keyboard.press('Control+a');

// Platform-aware save shortcut (Cmd+S on macOS, Ctrl+S elsewhere)
await page.keyboard.press('ControlOrMeta+s');

// Navigate to previous focusable element
await page.keyboard.press('Shift+Tab');

// Complex modifier combination
await page.keyboard.press('Control+Shift+K');

Summary

• ego-browser implements a Playwright-compatible keyboard API in src/driver/keyboard.ts with support for five modifier keys: Alt, Control, Meta, Shift, and ControlOrMeta.
• The parseKeyCombo function handles modifier combinations separated by +, including special cases for literal plus characters at lines 107-115.
• Built-in editing commands map Control/Meta+a to selectAll and handle Backspace/Delete as deletion operations via editingCommandsForKey.
• Agents interact with the keyboard through page.keyboard.press(), accepting both named keys (Enter, Tab) and modifier-plus-key combinations as documented in src/format.ts.

Frequently Asked Questions

What modifier keys does ego-browser support?

ego-browser recognizes Alt, Control, Meta, Shift, and ControlOrMeta. Each maps to a specific CDP bitfield defined in MODIFIER_BITS at lines 80-85 of src/driver/keyboard.ts, with values 1, 2, 4, and 8 respectively. ControlOrMeta automatically resolves to the appropriate platform-specific modifier.

How do I send keyboard shortcuts with multiple modifiers?

Combine modifiers using the + separator in the shortcut string passed to page.keyboard.press(). For example, use Control+Shift+K or Alt+Meta+T. The parseKeyCombo function in src/driver/keyboard.ts parses these combinations and constructs the appropriate bitmask for CDP events.

Does ego-browser handle the Command key differently on macOS?

Yes. The ControlOrMeta modifier automatically resolves to Meta on macOS and Control on other platforms. This logic appears in parseKeyCombo at lines 17-23, allowing shortcuts like ControlOrMeta+s to work correctly as Command+S on macOS and Ctrl+S on Windows/Linux.

Can I press the plus key as a character in ego-browser?

Yes. The parser handles literal "+" characters as base keys when they appear without preceding modifiers or as the final character (e.g., "+" or "Shift++"). This special case is implemented at lines 107-115 of src/driver/keyboard.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}