docs(dpi): document non-guaranteed per-monitor DPI awareness - #28
Merged
Conversation
SetProcessDpiAwarenessContext(PER_MONITOR_AWARE_V2) at startup discards its return value and fails with ERROR_ACCESS_DENIED (Win32 error 5) when process DPI awareness was already set before script code ran — verified 2026-08-13 under a host where injected software (Citrix App Protection) pre-loads WinForms/WPF into every pwsh, leaving it SYSTEM aware. In that state GetDpiForMonitor reports the system DPI for every monitor and mixed-DPI captures are DWM-virtualized. Correct AGENTS.md, README.md, and .planning docs to state the request- not-guarantee reality. Note pwsh.exe's manifest declares no dpiAware entry, and SetThreadDpiAwarenessContext(PMv2) still succeeds per-thread as the candidate escape hatch. Docs only; no behavior change, generated SnipIT.ps1 untouched. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
aksOps
enabled auto-merge (squash)
August 13, 2026 06:26
aksOps
added a commit
that referenced
this pull request
Aug 14, 2026
* refactor(preview): use native WPF layout * test(preview): align checks with native WPF * fix(preview): prevent More label clipping * docs(dpi): document non-guaranteed per-monitor DPI awareness SetProcessDpiAwarenessContext(PER_MONITOR_AWARE_V2) at startup discards its return value and fails with ERROR_ACCESS_DENIED (Win32 error 5) when process DPI awareness was already set before script code ran — verified 2026-08-13 under a host where injected software (Citrix App Protection) pre-loads WinForms/WPF into every pwsh, leaving it SYSTEM aware. In that state GetDpiForMonitor reports the system DPI for every monitor and mixed-DPI captures are DWM-virtualized. Correct AGENTS.md, README.md, and .planning docs to state the request- not-guarantee reality. Note pwsh.exe's manifest declares no dpiAware entry, and SetThreadDpiAwarenessContext(PMv2) still succeeds per-thread as the candidate escape hatch. Docs only; no behavior change, generated SnipIT.ps1 untouched. ---------
aksOps
added a commit
that referenced
this pull request
Aug 14, 2026
* refactor(preview): use native WPF layout * test(preview): align checks with native WPF * fix(preview): prevent More label clipping * docs(dpi): document non-guaranteed per-monitor DPI awareness SetProcessDpiAwarenessContext(PER_MONITOR_AWARE_V2) at startup discards its return value and fails with ERROR_ACCESS_DENIED (Win32 error 5) when process DPI awareness was already set before script code ran — verified 2026-08-13 under a host where injected software (Citrix App Protection) pre-loads WinForms/WPF into every pwsh, leaving it SYSTEM aware. In that state GetDpiForMonitor reports the system DPI for every monitor and mixed-DPI captures are DWM-virtualized. Correct AGENTS.md, README.md, and .planning docs to state the request- not-guarantee reality. Note pwsh.exe's manifest declares no dpiAware entry, and SetThreadDpiAwarenessContext(PMv2) still succeeds per-thread as the candidate escape hatch. Docs only; no behavior change, generated SnipIT.ps1 untouched. ---------
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.
What changed
Documentation-only correction across
AGENTS.md,README.md, and two codebase reference docs (since removed from the repository). No source or behavior change; generatedSnipIT.ps1untouched.Why
The docs claimed SnipIT is per-monitor DPI aware with accurate mixed-DPI capture. Investigation (2026-08-13) proved the startup
SetProcessDpiAwarenessContext(PER_MONITOR_AWARE_V2)call (src/20-Native.ps1, result piped toOut-Null) can silently fail:FalsewithERROR_ACCESS_DENIED(Win32 error 5) and the process stays SYSTEM aware.dpiAwareentry, and a bare unmanifested exe starts DPI-unaware on the same machine. On the affected machine, injected software (Citrix App Protection,ctxapclient64.dll) pre-loads WinForms/WPF into every pwsh at startup; their initialization sets SYSTEM awareness before any script statement, which locks it.GetDpiForMonitorreports the system DPI for every monitor (soGet-SnipMonitorDescriptorsshows uniform DPI on mixed-DPI hardware) and captures on non-system-DPI monitors go through DWM virtualization (rescaled, not native pixels). Uniform-DPI setups are unaffected.Reviewer notes
SetThreadDpiAwarenessContext(PMv2)was verified to still succeed per-thread even when process awareness is locked; it is recorded in CONCERNS.md as the candidate escape hatch for capture paths. Behavior remediation (assert+log the return value, per-thread PMv2 around capture) is deliberately left for a follow-up with mixed-DPI tests, per the no-behavior-change-without-tests rule.git diff --exit-code -- SnipIT.ps1is clean by construction (nosrc//xaml/edits, no rebuild needed).