fix(extension): preserve key identity and prevent VK collisions on printable keydown

[pei711]

why

Closes #3236

Calling page.keyPress("w") inserts text into focused inputs, but the dispatched DOM keydown event lacks key identity (event.key === "" and event.code === "" and event.keyCode === 0). Handlers inspecting event.key or event.code (e.g. shortcut managers and games) ignore the press, even though the subsequent keyup event identifies the key.

Furthermore, punctuation characters in describePrintableKey fell back to vk: ch.toUpperCase().charCodeAt(0). In ASCII, . is charCode 46, which collides with Windows Virtual Key VK_DELETE (46). In Chromium, passing windowsVirtualKeyCode: 46 for . causes the browser's editing command handler to trigger Delete instead of inserting the period.

what changed

• Defined a complete standard US keyboard PRINTABLE_PUNCTUATION lookup covering printable punctuation and shifted symbol keys (e.g. . maps to code: "Period", vk: 190 rather than VK 46 / VK_DELETE).
• Updated Page.describePrintableKey():
  • Resolves punctuation through PRINTABLE_PUNCTUATION.
  • Preserves uppercase key identity when an uppercase character is passed directly (ch === upper).
  • Avoids assigning synthetic charCode virtual key codes in the fallback to prevent command collisions.
• Updated Page.keyDown() for single printable characters (length 1) in the typing path to include key: desc.key, code: desc.code, and windowsVirtualKeyCode: desc.vk.
• Refactored Page.type() to share describePrintableKey() for consistent keyboard event metadata across type() and keyPress().
• Added unit tests in packages/extension/tests/page-key-press.test.ts.
• Added a patch changeset for @browserbasehq/stagehand-extension, @browserbasehq/stagehand, @browserbasehq/stagehand-go, and @browserbasehq/stagehand-python.

test plan

• Run format check: pnpm run fmt:check (passes)
• Run linter: pnpm run lint (passes)
• Run typecheck: pnpm --filter @browserbasehq/stagehand-extension run typecheck (passes)
• Run unit tests: pnpm vitest run packages/extension/tests/page-key-press.test.ts (passes, 4/4 tests)
• Run full extension test suite: pnpm --filter @browserbasehq/stagehand-extension run test:unit (passes, 67/67 files, 1007 tests)

---

Summary by cubic

Fixes page.keyPress() and page.type() dispatching keydown events without key identity (event.key, event.code, and event.keyCode were empty), which caused handlers checking those fields (shortcut managers, games) to ignore the press. Also fixes punctuation collisions where . fell back to VK 46 (VK_DELETE) and triggered Delete in Chromium instead of inserting a period.

• Added a full US keyboard PRINTABLE_PUNCTUATION mapping so characters like . dispatch code: "Period", vk: 190 rather than VK 46.
• Unified describePrintableKey() across keyPress(), keyDown(), and type() so all typing paths share consistent metadata; uppercase characters passed directly keep their uppercase identity.
• The fallback for unknown characters no longer synthesizes a VK code from charCode, preventing command collisions.
• Added unit tests and a patch changeset for all @browserbasehq/stagehand-* packages.

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

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	⚠️ Failed 2026-10-19T15:14:35.330214Z	6d2b419	PR opened

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.

[changeset-bot]

🦋 Changeset detected

Latest commit: 6d2b419

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 24 packages

Name	Type
@browserbasehq/stagehand-extension	Patch
@browserbasehq/stagehand-go	Patch
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-python	Patch
browse	Patch
@browserbasehq/stagehand-examples	Patch
@browserbasehq/stagehand-integrations-claude-cua-sdk	Patch
@browserbasehq/stagehand-integrations	Patch
@browserbasehq/eve	Patch
@browserbasehq/stagehand-integrations-gemini-cua-sdk	Patch
@browserbasehq/stagehand-integrations-example-pi-facade	Patch
@browserbasehq/stagehand-integrations-claude-agent-sdk	Patch
@browserbasehq/stagehand-integrations-example-claude-code-facade	Patch
@browserbasehq/stagehand-integrations-codex-sdk	Patch
@browserbasehq/stagehand-integrations-example-codex-facade	Patch
@browserbasehq/stagehand-integrations-cursor-sdk	Patch
@browserbasehq/stagehand-integrations-example-cursor-facade	Patch
@browserbasehq/stagehand-integrations-deepagents-sdk	Patch
@browserbasehq/stagehand-integrations-eve-sdk	Patch
@browserbasehq/stagehand-integrations-fx-sdk	Patch
@browserbasehq/stagehand-integrations-mastra-sdk	Patch
@browserbasehq/stagehand-integrations-example-mastra-facade	Patch
@browserbasehq/stagehand-integrations-pi-sdk	Patch
@browserbasehq/stagehand-integrations-example-vercel-ai-facade	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR