fix(input): target configured mouse viewport

[ReenigneArcher]

Description

Replace macOS main-display hardcoding with caller-provided virtual desktop and target viewport geometry. Apply the same mapping contract to Windows and Linux/FreeBSD, including negative origins and the XTest fallback.

Expose exception-safe runtime diagnostics for host log integration, document consumer setup, and add runtime and backend tests.

Screenshot

Issues Fixed or Closed

• Fixes macOS: cached CGMainDisplayID goes stale after display re-enumeration; all mouse input collapses to (0,0) #150
• Fixes macOS: Mouse confined to main display when streaming a secondary monitor #134

Roadmap Issues

Type of Change

• feat: New feature (non-breaking change which adds functionality)
• fix: Bug fix (non-breaking change which fixes an issue)
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semicolons, etc.)
• refactor: Code change that neither fixes a bug nor adds a feature
• perf: Code change that improves performance
• test: Adding missing tests or correcting existing tests
• build: Changes that affect the build system or external dependencies
• ci: Changes to CI configuration files and scripts
• chore: Other changes that don't modify src or test files
• revert: Reverts a previous commit
• BREAKING CHANGE: Introduces a breaking change (can be combined with any type above)

Checklist

• Code follows the style guidelines of this project
• Code has been self-reviewed
• Code has been commented, particularly in hard-to-understand areas
• Code docstring/documentation-blocks for new or existing methods/components have been added or updated
• Unit tests have been added or updated for any new or modified functionality

AI Usage

See our AI usage policy.

• None: No AI tools were used in creating this PR
• Light: AI provided minor assistance (formatting, simple suggestions)
• Moderate: AI helped with code generation or debugging specific parts
• Heavy: AI generated most or all of the code changes

[codecov]

Codecov Report

❌ Patch coverage is 86.97674% with 28 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.25%. Comparing base (5ef6b9e) to head (6db298c).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/platform/linux/uhid_backend.cpp	83.87%	3 Missing and 7 partials ⚠️
src/platform/windows/windows_backend.cpp	73.52%	7 Missing and 2 partials ⚠️
src/platform/macos/macos_backend.cpp	73.91%	1 Missing and 5 partials ⚠️
src/core/runtime.cpp	96.70%	0 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #145      +/-   ##
==========================================
+ Coverage   70.80%   71.25%   +0.44%     
==========================================
  Files          47       47              
  Lines       10818    10974     +156     
  Branches     3797     3872      +75     
==========================================
+ Hits         7660     7819     +159     
+ Misses       2733     2464     -269     
- Partials      425      691     +266     

Flag	Coverage Δ
FreeBSD	52.30% <36.87%> (-0.38%)	⬇️
Linux-Clang	55.66% <64.53%> (+0.13%)	⬆️
Linux-GCC	66.53% <84.00%> (+0.29%)	⬆️
PowerShell	75.60% <ø> (ø)
Windows-MSVC	88.91% <94.73%> (+0.09%)	⬆️
Windows-MinGW-UCRT64	64.09% <83.17%> (+0.21%)	⬆️
macOS	45.30% <62.13%> (+0.60%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/include/libvirtualhid/types.hpp	97.43% <100.00%> (ø)
src/core/runtime.cpp	84.80% <96.70%> (+1.25%)	⬆️
src/platform/macos/macos_backend.cpp	62.82% <73.91%> (+14.10%)	⬆️
src/platform/windows/windows_backend.cpp	83.83% <73.52%> (-0.17%)	⬇️
src/platform/linux/uhid_backend.cpp	81.38% <83.87%> (-0.03%)	⬇️

... and 6 files with indirect coverage changes

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 5ef6b9e...6db298c. Read the comment docs.

[ReenigneArcher]

Two P2 correctness findings remain in the macOS mouse mapping.

Merge status: the current head 36a1976a300bdf283c51755f856d06e215cc1792 conflicts with current master at 5ef6b9efa0634bb1fac404c2e9f10e13617ec830. Please rebase and resolve src/platform/macos/macos_backend.cpp, docs/usage.md, and docs/streaming-host-integration.md.

Validation: the isolated MSYS2/UCRT64 library, test binary, and both adapter examples build; git diff --check passes. Of 32 focused runtime, Windows backend, gamepad adapter, and lifecycle tests, 31 pass. The installed-device smoke test fails during unchanged keyboard creation with "Invalid broker create request." Hosted checks for this head pass, including Windows MSVC/MinGW, Linux, FreeBSD, macOS, and quality checks. Hosted macOS logs show 125 passing tests and 2 skips. Native macOS display reconfiguration and Retina pointer delivery were not reproduced locally.

Submitted as a comment review because the authenticated account is this PR's author.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud