fix(cua-driver-rs/windows): hotkey UIA routing for XAML/UWP targets (closes #1607)

[f-trycua]

Summary

The hotkey tool was silently no-op'ing on modern XAML / UWP hosts (modern Notepad, Settings) because PostMessage(WM_KEYDOWN/UP) lands in the window's message queue but the CoreInput dispatcher these apps use only reads from the system input queue. Mirrors the fix in #1597 that routed type_text through UIA ValuePattern.SetValue for the same architectural reason — hotkey now routes through UIA accelerator discovery + pattern activation.

Acid test (Windows 11 VM, modern Notepad)

Combo	Element it targets	Result
ctrl+b	Button "Bold (Ctrl+B)" [actions=[toggle]] (toolbar)	✅ Pressed ctrl+b on pid X via UIA InvokePattern/TogglePattern — Bold actually toggles
ctrl+s	File menu → Save (nested, no exposed accelerator)	❌ honest actionable error pointing at get_window_state for inspection (vs silently no-op'ing before)

How the routing works

When the target HWND is a XAML host (existing is_xaml_host_hwnd helper):

1. AcceleratorKey scan: walk the UIA subtree, read UIA_AcceleratorKeyPropertyId on each element. Conventional UWP / WinUI 3 path.
2. Name-pattern fallback: many shipping XAML apps (modern Notepad) don't set AcceleratorKey at all — they encode shortcuts in element names like "Bold (Ctrl+B)". We scan for that pattern, requiring at least one modifier-like token inside the parens so we don't match "(2)" or "(beta)".
3. Pattern chain: try InvokePattern.Invoke() first, then TogglePattern.Toggle() (Bold/Italic-style buttons live here — calling .Invoke on them returns the misleading (0x00000000) error).
4. Fall back to PostMessage for non-XAML targets — no behavior change for non-UWP apps.

Known limitation (out of scope)

Menu-nested actions (Save, "Save as", Print, etc.) don't expose accelerators outside the closed menu's subtree. Need a richer matcher that walks menus by name + invokes the matching item directly. Tracked separately. The actionable error this PR produces is honest about the limit.

Test plan

• cargo build -p cua-driver -p cua-driver-uia --release clean on the VM
• hotkey ctrl+b on modern Notepad toggles Bold (TogglePattern path)
• hotkey ctrl+s on modern Notepad returns actionable error (no exposed accelerator for menu-nested Save)
• CI green
• Non-UWP app (e.g. classic Notepad) still uses PostMessage path

Closes #1607. Related: #1597 (type_text UIA ValuePattern routing — same architectural fix for the typing path).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Enhanced hotkey support for modern XAML/UWP applications via UI Automation patterns.
  • Improved error messages guiding users to alternative methods when hotkeys aren't applicable.

• Bug Fixes

  • Better handling of hotkey invocation across different Windows application architectures.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Ignored	Preview	May 20, 2026 8:01pm

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d4dbf3d5-6c7c-4f5d-b09f-d051beb164c4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR implements UI Automation-based accelerator key invocation for modern XAML/UWP hosts in Windows, addressing silent failures when PostMessage-delivered hotkeys are ignored by the CoreInput dispatcher. The changes add accelerator lookup and activation helpers in the UIA module, then route HotkeyTool invocation through XAML host detection to attempt UIA accelerator activation before falling back to PostMessage.

Changes

XAML/UWP Hotkey Accelerator Support

Layer / File(s)	Summary
UIA accelerator lookup and invocation infrastructure libs/cua-driver-rs/crates/platform-windows/src/uia/windows_enum.rs	Public function try_invoke_accelerator_in_window validates the target HWND, canonicalizes the accelerator string (normalizing modifier and key token variants), traverses the UIA subtree to find elements matching the combo via AcceleratorKey or name-based shortcut hints, and attempts activation via InvokePattern then TogglePattern. Supporting helpers read UIA BSTR properties, normalize token spellings, rank modifiers, and extract parenthesized shortcuts from element names.
HotkeyTool XAML/UWP routing and accelerator invocation libs/cua-driver-rs/crates/platform-windows/src/tools/impl_.rs	Documentation updated to clarify that legacy Win32 targets use PostMessage while XAML/UWP targets route through UIA. HotkeyTool::invoke now detects XAML hosts, builds an accelerator combo from parsed modifiers and the final key, calls try_invoke_accelerator_in_window on a blocking task, and returns UIA-specific success or error messages; non-XAML hosts continue using the prior PostMessage post_key path.

Sequence Diagram(s)

sequenceDiagram
  HotkeyTool->>HotkeyTool: Check is_xaml_host_hwnd
  alt XAML/UWP Host
    HotkeyTool->>HotkeyTool: Build accelerator combo<br/>(modifiers + final key)
    HotkeyTool->>try_invoke_accelerator_in_window: Call on blocking task
    try_invoke_accelerator_in_window-->>HotkeyTool: (success: bool, scanned: count)
    alt Match found and activated
      HotkeyTool-->>Client: Return "via UIA<br/>InvokePattern/TogglePattern" success
    else No match found
      HotkeyTool-->>Client: Return error: PostMessage ignored,<br/>use get_window_state or UIA actions
    else Match found but no pattern
      HotkeyTool-->>Client: Return activation error
    end
  else Legacy Win32 Host
    HotkeyTool->>post_key: PostMessage WM_KEYDOWN/UP
    post_key-->>HotkeyTool: Success or error
    HotkeyTool-->>Client: Return PostMessage result
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• trycua/cua#1606: Adds desktop-root fallback for CoreWindow-class apps when the initial HWND subtree is empty, complementing the UIA tree-walking logic used by accelerator lookup.
• trycua/cua#1597: Uses the same XAML host routing signal (is_xaml_host_hwnd) to bypass PostMessage for type_text via UIA ValuePattern; this PR applies the same pattern to HotkeyTool::invoke.
• trycua/cua#1542: Introduces the UIA initializer and windows_enum module structure that this PR builds upon.

Poem

🐰 A hotkey once whispered through Windows so old,
But XAML apps left it unheard, dark and cold.
Now AcceleratorKey lights up the UIA tree,
And moderns find focus—hooray, it's set free! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: fixing hotkey handling for XAML/UWP targets by routing through UI Automation instead of PostMessage.
Linked Issues check	✅ Passed	The PR implements the primary fix path from #1607: walking the UIA tree for matching AcceleratorKey elements and invoking via InvokePattern/TogglePattern, with proper error handling for non-exposed accelerators.
Out of Scope Changes check	✅ Passed	All changes are scoped to implementing the UIA-based hotkey routing for XAML/UWP targets as specified in #1607; no unrelated modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-windows-xaml-hotkey-uia

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@libs/cua-driver-rs/crates/platform-windows/src/tools/impl_.rs`:
- Around line 1559-1565: Wrap the tokio::task::spawn_blocking call that runs
crate::uia::windows_enum::try_invoke_accelerator_in_window in a
tokio::time::timeout using the same timeout/duration used by get_window_state so
the hotkey path cannot hang forever; capture the JoinHandle, await it through
tokio::time::timeout(..., handle) and if the timeout elapses return/log an error
(and abort the blocking task if possible) instead of awaiting indefinitely.
Ensure you reference the spawn_blocking invocation and
try_invoke_accelerator_in_window when making the change so callers get a
deterministic timeout result consistent with get_window_state.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4bec1d8e-8a54-4b50-82ad-9d70ea4bba75

📥 Commits

Reviewing files that changed from the base of the PR and between 66ea051 and c0ed104.

📒 Files selected for processing (2)

• libs/cua-driver-rs/crates/platform-windows/src/tools/impl_.rs
• libs/cua-driver-rs/crates/platform-windows/src/uia/windows_enum.rs

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add a timeout around the UIA accelerator scan.

This spawn_blocking is awaited indefinitely, but the new path does a full cross-process UIA subtree walk plus property reads. The same file already guards get_window_state because UIA providers can hang; without the same protection here, one bad provider can wedge hotkey instead of returning an error.

⏱️ Suggested shape

-            let result = tokio::task::spawn_blocking(move || {
+            let blocking = tokio::task::spawn_blocking(move || {
                 crate::uia::windows_enum::try_invoke_accelerator_in_window(
                     hwnd as isize,
                     &accelerator_combo,
                 )
-            })
-            .await;
+            });
+            let result = match tokio::time::timeout(
+                std::time::Duration::from_secs(4),
+                blocking,
+            ).await {
+                Ok(join_result) => join_result,
+                Err(_) => {
+                    return ToolResult::error(format!(
+                        "hotkey timed out after 4s while scanning UIA accelerators for pid {raw_pid}."
+                    ));
+                }
+            };

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	let result = tokio::task::spawn_blocking(move || {
	crate::uia::windows_enum::try_invoke_accelerator_in_window(
	hwnd as isize,
	&accelerator_combo,
	)
	})
	.await;
	let blocking = tokio::task::spawn_blocking(move || {
	crate::uia::windows_enum::try_invoke_accelerator_in_window(
	hwnd as isize,
	&accelerator_combo,
	)
	});
	let result = match tokio::time::timeout(
	std::time::Duration::from_secs(4),
	blocking,
	).await {
	Ok(join_result) => join_result,
	Err(_) => {
	return ToolResult::error(format!(
	"hotkey timed out after 4s while scanning UIA accelerators for pid {raw_pid}."
	));
	}
	};

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@libs/cua-driver-rs/crates/platform-windows/src/tools/impl_.rs` around lines
1559 - 1565, Wrap the tokio::task::spawn_blocking call that runs
crate::uia::windows_enum::try_invoke_accelerator_in_window in a
tokio::time::timeout using the same timeout/duration used by get_window_state so
the hotkey path cannot hang forever; capture the JoinHandle, await it through
tokio::time::timeout(..., handle) and if the timeout elapses return/log an error
(and abort the blocking task if possible) instead of awaiting indefinitely.
Ensure you reference the spawn_blocking invocation and
try_invoke_accelerator_in_window when making the change so callers get a
deterministic timeout result consistent with get_window_state.