fix(desktop): fail fast when WebView2 is unavailable on Windows#3119
fix(desktop): fail fast when WebView2 is unavailable on Windows#3119yyyzl wants to merge 5 commits intoagentscope-ai:mainfrom
Conversation
github-actions
bot
added
the
first-time-contributor
Welcome to CoPaw! 🐾Hi @yyyzl, thank you for your first Pull Request! 🎉 🙌 Join Developer CommunityThanks so much for your contribution! We'd love to invite you to join the official CoPaw developer group! You can find the Discord and DingTalk group links under the "Developer Community" section on our docs page: We truly appreciate your enthusiasm—and look forward to your future contributions! 😊 We'll review your PR soon. Tip ⭐ If you find CoPaw useful, please give us a Star! Staying ahead Star CoPaw on GitHub and be instantly notified of new releases. Your star helps more developers discover this project! 🐾 |
There was a problem hiding this comment.
Pull request overview
This PR improves the Windows CoPaw Desktop launcher experience by detecting missing/damaged Microsoft Edge WebView2 Runtime up-front and failing fast with an actionable, user-visible error instead of silently showing a blank white window.
Changes:
- Add Windows registry detection for WebView2 Runtime and show a native MessageBox + stderr guidance when unavailable.
- Force
pywebviewto usegui="edgechromium"on Windows and wrapwebview.start()failures with WebView2-specific remediation messaging. - Update Desktop troubleshooting docs (EN/ZH) and add unit tests covering registry detection, fail-fast behavior, and forced GUI selection.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
src/copaw/cli/desktop_cmd.py |
Adds WebView2 runtime detection, fail-fast abort helper, and forces EdgeChromium backend on Windows. |
tests/unit/cli/test_cli_desktop.py |
Adds unit tests for WebView2 detection, fail-fast behavior, and gui="edgechromium" enforcement. |
website/public/docs/desktop.en.md |
Updates troubleshooting guidance for missing/damaged WebView2 and points users to Debug launcher output. |
website/public/docs/desktop.zh.md |
Same troubleshooting updates as EN, localized for ZH readers. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces robust checks for the Microsoft Edge WebView2 Runtime on Windows to prevent silent failures or blank windows when launching the desktop application. Key additions include registry-based runtime detection, native error dialogs for missing dependencies, and forcing the edgechromium renderer on Windows. The changes also include comprehensive unit tests for the new utility functions and updated documentation for troubleshooting. I have no feedback to provide as there were no review comments to evaluate.
|
@rayrayraykk Friendly ping 🙏 This PR has been open for a few days and is ready for review — all bot comments have been addressed, and I just verified it still merges cleanly onto the latest |
The generic _abort_desktop_launch call after the Windows-specific if-block was unreachable on Windows because _abort_desktop_launch always raises SystemExit. Restructure as if/else so the control flow is explicit.
yyyzl
force-pushed
the
fix/windows-webview2-white-screen
branch
from
220c185 to
5e51272
Compare
yyyzl
requested a deployment
to
maintainer-approved
GitHub Actions
Waiting
|
Rebased onto latest
Both commits preserved cleanly. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…t code - Re-run _DetectWebView2 after bootstrapper to check actual install state instead of relying solely on process exit code (which may be non-zero for reboot-required or other non-failure cases) - Gate post-install reminder on actual WebView2 absence, not just $R9 flag - Update GUID comment to reference agentscope-ai#3119 explicitly
- Wrap long line in error message to stay under 79 chars (flake8 E501) - Fix black formatting in test assertion - Add pylint disable for protected-access in test file
yyyzl
requested a deployment
to
maintainer-approved
GitHub Actions
Waiting
Previous fix used black defaults (88), but project pre-commit uses --line-length=79.
yyyzl
requested a deployment
to
maintainer-approved
GitHub Actions
Waiting
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Extract the duplicated WebView2 download URL + troubleshooting guidance into _WEBVIEW2_TROUBLESHOOT_SUFFIX constant, reused by both _ensure_desktop_webview_available() and the webview.start() exception handler.
yyyzl
requested a deployment
to
maintainer-approved
GitHub Actions
Waiting
Description
On a small number of Windows machines, launching CoPaw Desktop shows a blank white window with no error feedback. The root cause is a missing or damaged Microsoft Edge WebView2 Runtime — without it, pywebview silently falls back to the legacy MSHTML/IE renderer which cannot render the Vite-built frontend.
This PR turns that silent white-screen into a fail-fast with an actionable error message:
MessageBoxerror dialog + stderr message with a download linkgui="edgechromium"inwebview.start()to prevent silent MSHTML fallbackwebview.start()exceptions with a clear WebView2-specific error on WindowsVerified on Alibaba Cloud Wuying (无影云电脑) where WebView2 was initially missing — after this change the error dialog appeared immediately with the download link, and after installing WebView2 the app launched normally.
Related Issue: N/A (discovered during user testing on cloud desktops)
Security Considerations: N/A
Type of Change
Component(s) Affected
Checklist
pre-commit run --all-fileslocally and it passespytestor as relevant) and they passTesting
Unit tests — 4 new tests in
tests/unit/cli/test_cli_desktop.py:test_detect_windows_webview2_runtime_version_returns_first_valid— skips0.0.0.0, returns first real versiontest_detect_windows_webview2_runtime_version_returns_none— returnsNonewhen no valid version foundtest_ensure_desktop_webview_available_requires_webview2_runtime— exits with code 1 and shows MessageBox when WebView2 missingtest_start_desktop_window_forces_edgechromium_on_windows— verifiesgui="edgechromium"is passed on WindowsManual verification — Tested on Alibaba Cloud Wuying (无影云电脑), a Windows environment without WebView2 pre-installed:
Local Verification Evidence
Additional Notes
{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}is the official Evergreen Runtime identifier from Microsoft0.0.0.0is filtered out as it indicates an uninstalled/placeholder state