docs(cua-driver): Windows behavior notes for the v0.2.9 fix chain + install.ps1 PS 5.1 workaround - #1627
Merged
Merged
Conversation
…nstall.ps1 PS 5.1 workaround Tonight's three cua-driver-rs Windows fixes (#1620 Chromium anti-throttling flag auto-inject in `launch_app`, #1621 control-type whitelist for the `click(x, y)` UIA Invoke pre-check, #1623 SendInput routing for Chromium coord clicks) shipped in v0.2.9 without docs updates. This PR closes that gap and documents the install.ps1 PS 5.1 parse bug as a known issue. ## mcp-tools.mdx - New top-level section `## Windows behavior notes` at the end of the reference, gathering the three cross-cutting changes: - `launch_app` Chromium flag list + the 10 detected browser executables - `click(x, y)` control-type whitelist (Button / MenuItem / Hyperlink / TabItem / ListItem / CheckBox / RadioButton / SplitButton / TreeItem) + why canvases / Panes / Customs fall through - SendInput on Chromium with brief foreground swap + cursor jump, the UIAccess requirement, and the `cua-driver-uia.exe` proxy default - `hotkey`'s SendInput-routed delivery + matching UIAccess constraint - Inline cross-references from `click`, `launch_app`, and `hotkey` pointing to the Windows behavior section so callers reading any of those tool entries see the platform-specific notes. ## installation.mdx - Callout under the Windows install one-liner documenting #1626 (PS 5.1 parse error on `install.ps1`) with the manual-zip workaround verbatim from the issue, scoped to PS 5.1 only (PS 7+ parses fine). Closes the standing /docs update obligation for #1619, #1620, #1621, #1623. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThis PR documents two Windows-specific issues: it adds a PowerShell 5.1 installation workaround to the getting-started guide, and it expands the MCP tool reference with comprehensive Windows behavior notes describing UIA integration, SendInput dispatch mechanics, and Chromium anti-throttling behavior for the ChangesWindows documentation updates
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related issues
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/content/docs/cua-driver/reference/mcp-tools.mdx (1)
1148-1191:⚠️ Potential issue | 🟠 Major | ⚡ Quick winMove this content to the generator source, then regenerate
mcp-tools.mdx.Line 1148 onward is being added directly to a file marked auto-generated, and CI already fails with doc drift for this file. This will keep breaking
Check Documentation Sync(or be overwritten later). Please add these Windows notes in the docs generator/source-of-truth path and re-generate the MDX output before merge.🤖 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 `@docs/content/docs/cua-driver/reference/mcp-tools.mdx` around lines 1148 - 1191, The auto-generated file contains a manually added "## Windows behavior notes" section (starting at "Chromium anti-throttling flags auto-injected" and covering the launch_app/click/hotkey notes) that must be moved into the documentation generator's source-of-truth and the MDX re-generated; remove this manual addition from mcp-tools.mdx, add the same content into the docs generator input (the generator page for the mcp-tools reference / the template that produces the launch_app/click/hotkey docs), then run the docs generation task to regenerate mcp-tools.mdx so CI passes.
🤖 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 `@docs/content/docs/cua-driver/guide/getting-started/installation.mdx`:
- Line 84: The current PowerShell snippet unconditionally prepends $dest to the
User Path using SetEnvironmentVariable and
GetEnvironmentVariable('Path','User'), which causes duplicate entries on
repeated runs; update the snippet to first read the current User Path into a
variable, check whether $dest is already present (e.g., via -notmatch or
splitting on ';' and using -contains), and only call
[Environment]::SetEnvironmentVariable('Path', "$dest;" + $currentPath, 'User')
when $dest is not already in the path to make the operation idempotent.
---
Outside diff comments:
In `@docs/content/docs/cua-driver/reference/mcp-tools.mdx`:
- Around line 1148-1191: The auto-generated file contains a manually added "##
Windows behavior notes" section (starting at "Chromium anti-throttling flags
auto-injected" and covering the launch_app/click/hotkey notes) that must be
moved into the documentation generator's source-of-truth and the MDX
re-generated; remove this manual addition from mcp-tools.mdx, add the same
content into the docs generator input (the generator page for the mcp-tools
reference / the template that produces the launch_app/click/hotkey docs), then
run the docs generation task to regenerate mcp-tools.mdx so CI passes.
🪄 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: ff7be63e-36cf-42d2-8cb1-1f266a4da5db
📒 Files selected for processing (2)
docs/content/docs/cua-driver/guide/getting-started/installation.mdxdocs/content/docs/cua-driver/reference/mcp-tools.mdx
| $dest = "$env:LOCALAPPDATA\Programs\trycua\cua-driver-rs\bin" | ||
| New-Item -ItemType Directory -Force -Path $dest | Out-Null | ||
| Expand-Archive -Force -Path $env:TEMP\cua.zip -DestinationPath $dest | ||
| [Environment]::SetEnvironmentVariable('Path', "$dest;" + [Environment]::GetEnvironmentVariable('Path','User'), 'User') |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file="docs/content/docs/cua-driver/guide/getting-started/installation.mdx"
echo "== File exists? =="
ls -la "$file" || true
echo "== Show lines around 70-100 =="
nl -ba "$file" | sed -n '60,110p'Repository: trycua/cua
Length of output: 283
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file="docs/content/docs/cua-driver/guide/getting-started/installation.mdx"
echo "== File exists? =="
ls -la "$file" || true
echo "== Show lines around 70-100 =="
nl -ba "$file" | sed -n '60,110p'Repository: trycua/cua
Length of output: 283
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file="docs/content/docs/cua-driver/guide/getting-started/installation.mdx"
echo "== Lines 70-100 (with line numbers via awk) =="
awk 'NR>=70 && NR<=100 {printf "%5d %s\n", NR, $0}' "$file"Repository: trycua/cua
Length of output: 2734
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n "SetEnvironmentVariable\('Path'" docs/content/docs/cua-driver/guide/getting-started/installation.mdx || true
rg -n "idempot|NoPathUpdate|PathUpdate|-NoPathUpdate" docs/content/docs/cua-driver/guide/getting-started/installation.mdx || trueRepository: trycua/cua
Length of output: 1219
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n "\[Environment\]::SetEnvironmentVariable\('Path', \"\\$dest;" docs/content/docs/cua-driver/guide/getting-started/installation.mdx || true
rg -n "manual zip install|cua\.zip|cua\.zip -OutFile|$dest = \"" docs/content/docs/cua-driver/guide/getting-started/installation.mdx || trueRepository: trycua/cua
Length of output: 96
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file="docs/content/docs/cua-driver/guide/getting-started/installation.mdx"
rg -n '\$dest;' "$file" || true
rg -n '\[Environment\]::SetEnvironmentVariable\(' "$file" || true
rg -n 'manual zip install|cua\.zip|Expand-Archive' "$file" || trueRepository: trycua/cua
Length of output: 1526
Make the PATH update idempotent in the PS 5.1 workaround.
Line 84 prepends $dest to the User Path unconditionally, so re-running the manual zip workaround can duplicate the entry. Add a guard before SetEnvironmentVariable.
Suggested doc snippet update
- [Environment]::SetEnvironmentVariable('Path', "$dest;" + [Environment]::GetEnvironmentVariable('Path','User'), 'User')
+ $userPath = [Environment]::GetEnvironmentVariable('Path','User')
+ $parts = @($userPath -split ';' | Where-Object { $_ -ne '' })
+ if ($parts -notcontains $dest) {
+ [Environment]::SetEnvironmentVariable('Path', "$dest;$userPath", 'User')
+ }📝 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
| [Environment]::SetEnvironmentVariable('Path', "$dest;" + [Environment]::GetEnvironmentVariable('Path','User'), 'User') | |
| $userPath = [Environment]::GetEnvironmentVariable('Path','User') | |
| $parts = @($userPath -split ';' | Where-Object { $_ -ne '' }) | |
| if ($parts -notcontains $dest) { | |
| [Environment]::SetEnvironmentVariable('Path', "$dest;$userPath", 'User') | |
| } |
🤖 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 `@docs/content/docs/cua-driver/guide/getting-started/installation.mdx` at line
84, The current PowerShell snippet unconditionally prepends $dest to the User
Path using SetEnvironmentVariable and GetEnvironmentVariable('Path','User'),
which causes duplicate entries on repeated runs; update the snippet to first
read the current User Path into a variable, check whether $dest is already
present (e.g., via -notmatch or splitting on ';' and using -contains), and only
call [Environment]::SetEnvironmentVariable('Path', "$dest;" + $currentPath,
'User') when $dest is not already in the path to make the operation idempotent.
Merged
2 tasks
#1627) Re-running the manual-install workaround duplicated `$dest` in the User PATH because the snippet unconditionally prepended. Guards with a `-notcontains` check before `SetEnvironmentVariable` so the entry is added at most once. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Collaborator
Author
|
Addressed in 15d9e19 — added External link-check failure ( |
f-trycua
added a commit
that referenced
this pull request
May 21, 2026
… SendInput dispatch (#1629) The hotkey tool description still claimed "Legacy Win32 targets receive the combo directly via PostMessage(WM_KEYDOWN/UP)" — but #1614/#1618 changed the dispatch to use SendInput (via the cua-driver-uia worker) for combos containing modifiers, because PostMessage doesn't update the OS-wide modifier state and accelerators fail to fire on TranslateAccelerator- based apps (LibreOffice, FAR, classic Notepad, etc.). The actual current dispatch (impl_.rs::HotkeyTool::invoke, lines ~1859-1879): 1. XAML / WinUI / UWP target → UIA accelerator-key invocation 2. Legacy Win32 WITH modifiers → SendInput (brief foreground swap, UIAccess required) 3. Legacy Win32 WITHOUT modifiers → PostMessage WM_KEYDOWN/UP Description now matches reality across all three branches, including the UIAccess requirement and the cua-driver-uia worker proxy auto-preference. Caught during Inkscape stress testing — agents reading the tool docs would expect PostMessage-only behavior and be surprised by the visible cursor / foreground change on modifier+key hotkeys, or by the "SendInput inserted only 0 of 4 events" diagnostic when the daemon lacks UIAccess. The mcp-tools.mdx entry for hotkey is auto-generated from this Rust source (per the AUTO-GENERATED comment at the top of mcp-tools.mdx), so this fix regenerates the public docs on the next docs build. PR #1627 also has an inline cross-reference from the hotkey section to the Windows behavior notes; the two land complementary improvements. Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This was referenced May 27, 2026
This was referenced Jun 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes the missing docs gap for the four cua-driver-rs Windows fixes that shipped in v0.2.9 (#1619 shared fixtures, #1620 Chromium flag auto-inject, #1621 UIA Invoke whitelist, #1623 SendInput on Chromium), and documents the install.ps1 PowerShell 5.1 parse bug (#1626) with a manual-zip workaround.
mcp-tools.mdx
## Windows behavior notesat the end of the reference, gathering the three cross-cutting changes:launch_appChromium flag list + the 10 detected browser executablesclick(x, y)control-type whitelist + why canvases / Panes / Customs fall through to PostMessage / SendInputcua-driver-uia.exeproxy defaulthotkey's SendInput-routed delivery + matching UIAccess constraintclick,launch_app, andhotkeypointing to the Windows behavior section so callers reading any of those tool entries see the platform-specific notes.installation.mdx
install.ps1) with the manual-zip workaround verbatim from the issue, scoped to PS 5.1 only — PS 7+ (pwsh) parsesinstall.ps1correctly.Test plan
[Windows behavior notes](#windows-behavior-notes)anchors land on the new section)🤖 Generated with Claude Code
Summary by CodeRabbit