fix(helpers): press_key supports keyboard shortcuts (suppress char + canonical code/vk)

[sauravpanda]

Summary

Fixes a P1 surfaced by a codex review of the repo. Lifts the workaround that PR #258 made inside fill_input up to the press_key helper itself, so every keyboard shortcut — Cmd+S, Ctrl+Z, Ctrl+L, Cmd+Shift+P, etc. — now works for any caller, not just the select-all that fill_input does.

The bugs

Two distinct problems in helpers.press_key:

1. char event always fired after keyDown. Even with Ctrl/Cmd held, the helper unconditionally emitted an Input.dispatchKeyEvent type=char after the keyDown. Chrome treats char as printable text input, so the shortcut handler fires AND the literal letter gets typed. PR fix(helpers): add fill_input, wait_for_element, wait_for_network_idle #258 worked around this inside fill_input by dispatching select-all via raw CDP calls; every other shortcut remained broken.

2. code and windowsVirtualKeyCode were wrong for letters/digits. The fallback computed code=key (so code="a" for the A key) and vk=ord(key[0]) (97 for "a"). CDP's shortcut handlers compare against canonical physical-key codes — "KeyA" / 65 for the A key, "Digit5" / 53 for the 5 key. Without those, e.code in JS is wrong and shortcut listeners that check e.code === "KeyA" (a common pattern) don't fire.

The fix

• New _key_metadata(key) returns the canonical (vk, code, text) for letters (KeyA/65, KeyZ/90), digits (Digit5/53), and the pre-existing special-key table (Enter/13/\r, Backspace/8, etc.). Punctuation/symbols fall back to ASCII vk + literal code (best-effort; Chrome may still recognise the shortcut from the modifier flags alone).
• press_key now suppresses both text on the keyDown and the entire char event when any of Alt|Ctrl|Meta (modifier bits 0b0111) is set. Shift alone is still text input — Shift+A still types A.
• fill_input's clear-first path simplified back to press_key("a", modifiers=...). The raw-CDP workaround was 5 lines; it's now one call. The helper does the right thing.

Tests

10 new in tests/unit/test_helpers.py:

• test_press_key_letter_uses_canonical_code_and_vk — covers "a" → KeyA/65 and "Z" → KeyZ/90.
• test_press_key_digit_uses_canonical_code_and_vk — "5" → Digit5/53.
• test_press_key_special_key_uses_kkeys_table — Enter still resolves via _KEYS.
• test_press_key_no_modifiers_emits_text_and_char_event — keyDown carries text, char event fires.
• test_press_key_with_ctrl_suppresses_text_and_char — keyDown has no text, no char event.
• test_press_key_with_meta_suppresses_text_and_char — same for Cmd.
• test_press_key_with_alt_suppresses_text_and_char — same for Alt.
• test_press_key_shift_alone_still_emits_text_and_char — Shift alone is text input.
• test_press_key_ctrl_shift_combo_still_suppresses — Ctrl+Shift+P (modifier wins over Shift).
• test_press_key_emits_keyup_with_consistent_metadata — keyUp carries the same code/vk/modifiers.

uv run pytest tests/ → 93 passed (83 → 93).

Test plan

• Unit tests pass locally.
• On a real daemon: an agent calling press_key("z", modifiers=2 if not darwin else 4) in a textarea undoes the last edit (Ctrl/Cmd+Z).
• press_key("l", modifiers=2 if not darwin else 4) focuses the address bar (Ctrl/Cmd+L).
• fill_input(selector, "hello", clear_first=True) still clears on macOS (Cmd+A path goes through the new press_key).

---

Summary by cubic

Fixes keyboard shortcuts by updating press_key to suppress printable char events with Alt/Ctrl/Meta and to emit canonical code/vk for letters and digits. Shortcuts like Cmd+S, Ctrl+Z, and Cmd/Ctrl+A now work reliably, and fill_input uses press_key directly.

• Bug Fixes
  • Suppress text and char events when Alt/Ctrl/Meta are held; Shift alone still types text.
  • Emit canonical CDP metadata for letters/digits (e.g., KeyA/65, Digit5/53); special keys unchanged.
  • Simplify fill_input clear path to use press_key("a", modifiers=Cmd/Ctrl); removed raw CDP workaround.
  • Added 10 unit tests; total suite now 93 passing.

^{Written for commit e0dcdd6. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 2 files

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e0dcdd6905

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Handle multichar uppercase mappings in _key_metadata

The new letter path crashes for some valid single-character inputs because key.upper() can return multiple code points (for example "ß" -> "SS"), and ord(upper) then raises TypeError. This is a regression from the previous implementation and breaks fill_input for international text, since it calls press_key for each character and will now fail at runtime on these inputs.

Useful? React with 👍 / 👎.