Skip to content

Explain which foreground check refused a drag - #1385

Open
Alexandre Zollinger Chohfi (azchohfi) wants to merge 3 commits into
mainfrom
azchohfi-guarded-input-diagnostics
Open

Alexandre Zollinger Chohfi (azchohfi) wants to merge 3 commits into
mainfrom
azchohfi-guarded-input-diagnostics

Conversation

@azchohfi

@azchohfi Alexandre Zollinger Chohfi (azchohfi) commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

What and why

When winapp ui drag refuses input because another window is in front, its error now identifies which of the two safety checks rejected the drag. The existing error.details string includes the window handles (Windows window IDs), process IDs, observation times, and the result of the existing foreground request. This lets a captured failure distinguish a failed foreground request from a later foreground change.

The error code, message and JSON schema stay unchanged. Both safety checks remain, and a rejected drag sends no mouse-button input. This adds diagnostics, not a fix for the previously reported foreground loss.

Related to microsoft/microsoft-ui-reactor#1601.

Before / after

winapp ui drag <selector> <x,y> -w <hwnd> --json

Before — the recorded v0.8.0 failure, whose error path is unchanged on the base branch, reported foreground_not_target without identifying the failing check.

After — passing headless tests capture either gate=before-cursor or gate=before-button-down inside the existing error.details string.

Observed headless output excerpts

These excerpts use synthetic window and process IDs from the tests, not a live desktop capture.

gate=before-cursor
requestSucceeded=False
requestForegroundHwnd=9000

gate=before-button-down
requestSucceeded=True
requestForegroundHwnd=7777

Both cases also retain the comparison's foregroundHwnd=8800 and the separate classification read's classificationForegroundHwnd=9900. Later process-ID lookups are explicitly labeled ownershipMetadata=queried-after-decision rather than presented as one atomic observation.

Not tested / risks

No new live-desktop refusal or terminal screenshot was captured because this work has no authorized desktop-input slot. A separately authorized consumer run of the original diagnostic build passed both foreground checks but still resized from 140 to 196 instead of 200. It did not establish the cause of the earlier foreground failures or fix the sizing discrepancy.

Current-head CI passed, including packaging, UI E2E and samples. Local validation was headless. Window ownership can change between reads, so the diagnostics retain and label separate observations rather than claiming an atomic snapshot.

Checklist

  • Tests added or updated
  • Tested locally on Windows
  • Docs, samples, and plugins/winapp/skills/ updated if user-facing behavior changed — not needed, command syntax and recovery instructions are unchanged
Notes for reviewers

The existing CheckForeground(long) API remains. The additive snapshot overload preserves both foreground reads and their order. Existing custom guards can continue implementing the original interface methods and explicitly report unavailable diagnostic snapshots.

Validation for head 37a79f8291c8e6a8dbdde79450f25fd0111318a8

dotnet run --no-build --no-restore --project src\winapp-CLI\WinApp.UIAutomation.Tests\WinApp.UIAutomation.Tests.csproj -c Release -- --filter "FullyQualifiedName~ForegroundGuardTests|FullyQualifiedName~CaptureForegroundOwnerChainTests" --report-trx --report-trx-filename final-foreground.trx --results-directory artifacts\TestResults\guarded-input
# Passed 26, failed 0, skipped 0.

dotnet run --no-restore --project src\winapp-CLI\WinApp.Cli.Tests\WinApp.Cli.Tests.csproj -c Release -- --filter "FullyQualifiedName~PublicApiSurfaceTests|FullyQualifiedName~UiCommandTests.Drag_|FullyQualifiedName~UiInjectionReportingTests|FullyQualifiedName~DesktopTargetValidationTests|FullyQualifiedName~DesktopPrimitiveGuardTests" --report-trx --report-trx-filename reviewed-drag-api.trx --results-directory artifacts\TestResults\guarded-input
# Passed 54, failed 0, skipped 0.

Earlier full local build at diagnostic commit d1b2dbe2d03ffdaf104c37c5348115e0e92789a0

.\scripts\build-cli.ps1 -SkipAll
# Passed. Published self-contained NativeAOT x64 and arm64 binaries.
# Headless engine checks passed 27, failed 0. Non-host arm64 execution skipped.

The consumer used that original x64 executable with SHA256 3A3294E4BA9F3E5BF145D2208C41DB03FAD7A739CD7E639BE85B449EB9961F20, version 0.8.1-azchohfi-guarded-input-diagnostics.42. No installed binary was replaced.

Report the rejecting gate and retained request/check observations in the existing error.details string without changing foreground acceptance or input dispatch.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 21, 2026 00:18
@azchohfi Alexandre Zollinger Chohfi (azchohfi) added agent-preparing Agent is addressing feedback or completing required validation and CI docs-not-needed labels Nov 21, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The new public ForegroundCheckSnapshot record is missing from ExpectedUiAutomationTypes, causing the public API surface test to fail until the expected exports are updated.

1 open issue
What changed in this PR

This PR adds diagnostics to winapp ui drag refusals so users can identify which foreground safety check rejected the drag. It preserves both checks and the existing error code, message, and JSON structure.

Changes:

  • Records the rejecting check, window handles, process IDs, and observation times in error.details.
  • Captures the foreground request’s result while keeping separate observations clearly labeled.
  • Adds headless tests for both refusal points, retained observations, and guards without snapshot support.
File Description
src/​winapp-CLI/​WinApp.UIAutomation/​Input/​RealForegroundGuard.cs Delegates checks that return diagnostic snapshots.
src/​winapp-CLI/​WinApp.UIAutomation/​Input/​IForegroundGuard.cs Adds an optional snapshot overload for existing implementations.
src/​winapp-CLI/​WinApp.UIAutomation/​Input/​ForegroundGuard.cs Retains rejection observations without changing decisions.
src/​winapp-CLI/​WinApp.UIAutomation/​Input/​ForegroundCheckSnapshot.cs Defines the diagnostic snapshot and observation semantics.
src/​winapp-CLI/​WinApp.UIAutomation.TestSupport/​FakeUiServices.cs Supports snapshots in the fake foreground guard.
src/​winapp-CLI/​WinApp.UIAutomation.Tests/​ForegroundGuardTests.cs Tests preserved decisions and foreground-read order.
src/​winapp-CLI/​WinApp.Cli/​Helpers/​UiInjectionReporting.cs Formats diagnostic details for foreground refusals.
src/​winapp-CLI/​WinApp.Cli/​Helpers/​IDesktopForegroundService.cs Returns the native foreground request’s Boolean result.
src/​winapp-CLI/​WinApp.Cli/​Commands/​UiDragCommand.cs Captures request observations and labels both safety checks.
src/​winapp-CLI/​WinApp.Cli.Tests/​UiInjectionReportingTests.cs Tests reporting when snapshots are unavailable.
src/​winapp-CLI/​WinApp.Cli.Tests/​UiCommandTests.Mouse.cs Tests both refusal points and verifies no drag is sent.
src/​winapp-CLI/​WinApp.Cli.Tests/​FakeDesktopForegroundService.cs Returns a configurable foreground request result.

Review effort: Balanced

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the foreground-safety diagnostic changes.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@github-actions

Copy link
Copy Markdown
Contributor

Build Metrics Report

Validation passed. All required build and validation jobs succeeded.

Binary Sizes

Artifact Baseline Current Delta
CLI (ARM64) 67.56 MB 67.57 MB 📈 +10.5 KB (+0.02%)
CLI (x64) 67.41 MB 67.42 MB 📈 +10.5 KB (+0.02%)
MSIX (ARM64) 27.88 MB 27.88 MB 📈 +1.1 KB (+0.00%)
MSIX (x64) 29.56 MB 29.57 MB 📈 +13.9 KB (+0.05%)
NPM Package 58.06 MB 58.07 MB 📈 +9.3 KB (+0.02%)
NuGet Package 58.23 MB 58.24 MB 📈 +8.5 KB (+0.01%)

.NET Test Results (TRX reports)

Other suites are reflected in the overall validation status above.

✅ 11435 passed, 44 skipped out of 11479 tests in 2026.9s (+10 tests, +319.7s vs. baseline)

Test Coverage

✅ 87.4% line coverage, 81.6% branch coverage · ✅ no change vs. baseline

CLI Startup Time

57ms median (x64, winapp --version) · ✅ no change vs. baseline


Updated 2026-11-21 01:08:58 UTC · commit 37a79f8 · workflow run

@azchohfi Alexandre Zollinger Chohfi (azchohfi) added ready-for-review Agent work and technical checks complete; awaiting review or re-review, not approval or merge and removed agent-preparing Agent is addressing feedback or completing required validation and CI labels Nov 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs-not-needed ready-for-review Agent work and technical checks complete; awaiting review or re-review, not approval or merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants