Standardize UI coordinate terminology: "app" → "screen" coordinates#660
Merged
Conversation
winapp ui drag/touch/pen and the shared coordinate parser accept and report absolute screen coordinates in the same space 'ui inspect' reports, but the help text and docs described them inconsistently as 'app coordinates' / 'app-relative' / 'app x,y'. Standardize on the correct Win32 term 'screen coordinates' across command descriptions, argument/option help, doc comments, and the hand-written UI-automation docs. Regenerated downstream artifacts (docs/cli-schema.json, plugin + .claude skills, npm winapp-commands.ts and npm-usage.md). The npm-usage.md regen also syncs a pre-existing stale 'send-keys --allow-system-keys' row that had drifted from the schema. Wording/docs only - no behavioral change. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7e0e07ab-c48d-4355-aff4-20f7120adb21
Contributor
There was a problem hiding this comment.
Pull request overview
Standardizes UI automation help and documentation to correctly describe absolute screen coordinates, with no behavioral changes.
Changes:
- Updates drag, touch, pen, and shared parser terminology.
- Regenerates CLI schema, npm references, and agent skills.
- Includes the pre-existing
allowSystemKeysnpm documentation sync.
Reviewed changes
Copilot reviewed 17 out of 17 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
src/winapp-npm/src/winapp-commands.ts |
Updates generated npm API descriptions. |
src/winapp-CLI/WinApp.Cli/Helpers/PointerGesturePlanner.cs |
Corrects coordinate documentation. |
src/winapp-CLI/WinApp.Cli/Helpers/CoordinateParser.cs |
Corrects parser documentation. |
src/winapp-CLI/WinApp.Cli/Commands/UiTouchCommand.cs |
Updates touch help text. |
src/winapp-CLI/WinApp.Cli/Commands/UiPenCommand.cs |
Updates pen help text. |
src/winapp-CLI/WinApp.Cli/Commands/UiDragCommand.cs |
Updates drag help and comments. |
src/winapp-CLI/WinApp.Cli.Tests/UiCommandTests.Touch.cs |
Corrects test terminology. |
src/winapp-CLI/WinApp.Cli.Tests/UiCommandTests.Mouse.cs |
Corrects test terminology. |
docs/usage.md |
Updates UI command summaries. |
docs/ui-automation.md |
Updates coordinate guidance and examples. |
docs/npm-usage.md |
Regenerates npm documentation. |
docs/fragments/skills/winapp-cli/ui-automation.md |
Updates the source skill fragment. |
docs/cli-schema.json |
Regenerates command descriptions. |
.github/plugin/skills/winapp-cli/ui-automation/SKILL.md |
Regenerates the plugin skill. |
.github/plugin/agents/winapp.agent.md |
Updates agent command guidance. |
.claude/skills/winapp-ui-automation/SKILL.md |
Synchronizes the Claude skill mirror. |
.claude/agents/winapp.md |
Synchronizes the Claude agent mirror. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
Build Metrics ReportBinary Sizes
Test Results✅ 3338 passed, 4 skipped out of 3342 tests in 620.9s (-116.7s vs. baseline) Test Coverage✅ 86.3% line coverage, 80% branch coverage · ✅ no change vs. baseline CLI Startup Time46ms median (x64, Updated 2026-07-16 19:29:30 UTC · commit |
zateutsch
approved these changes
Jul 16, 2026
nmetulev
added a commit
that referenced
this pull request
Jul 16, 2026
Resolved the ui-automation agent-doc conflict by keeping #660's "app" -> "screen" coordinate terminology on the ui drag line and the send-keys windowless/post-message caveat from this branch. Regenerated all auto-generated docs/skills (cli-schema.json, plugin + .claude skills, npm-usage.md, winapp-commands.ts) from the merged CLI; restored plugin.json version to match main. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
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
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.
What & why
winapp ui drag/touch/pen(and the shared coordinate parser) all accept and report absolute screen coordinates — the exact same spacewinapp ui inspectreports — but the help text and docs described them inconsistently as "app coordinates", "app-relative", and "app x,y". That wording is ambiguous (it reads as window/client-relative) and was the source of real confusion about which coordinate space these verbs use.This PR standardizes on the correct Win32 term "screen coordinates" everywhere. Wording/docs only — no behavioral change.
Changes
Source of truth (C#):
Commands/UiDragCommand.cs,UiTouchCommand.cs,UiPenCommand.cs— command descriptions + argument/option helpHelpers/CoordinateParser.cs,PointerGesturePlanner.cs— doc commentsWinApp.Cli.Tests/UiCommandTests.{Mouse,Touch}.cs— test commentsHand-written docs:
docs/ui-automation.md,docs/usage.md,docs/fragments/skills/winapp-cli/ui-automation.md,.github/plugin/agents/winapp.agent.mdRegenerated artifacts (via
scripts/generate-llm-docs.ps1+ npmgenerate-commands/generate-docs,sync-claude-plugin.ps1):docs/cli-schema.json, plugin +.claudeskills,src/winapp-npm/src/winapp-commands.ts,docs/npm-usage.mdNotes for reviewers
versionis unchanged (built with pinnedAssemblyVersionto avoid churn); the onlycli-schema.jsonchanges are the wording lines.npm-usage.mdregeneration also picks up a pre-existing stale row — thesend-keys --allow-system-keysoption was already inwinapp-commands.tsbut had never been regenerated intonpm-usage.md. Reverting it would failgenerate-docs:check, so it's included as an incidental doc sync.generate-commands:checkandgenerate-docs:checkboth pass.A separate follow-up issue tracks a related but distinct behavioral asymmetry (touch/pen reject out-of-window coordinates while click/drag/hover/scroll do not).