[Website] Provide better UX for wasm and script download failures#3348
Open
brandonpayton wants to merge 13 commits intotrunkfrom
Open
[Website] Provide better UX for wasm and script download failures#3348brandonpayton wants to merge 13 commits intotrunkfrom
brandonpayton wants to merge 13 commits intotrunkfrom
Conversation
brandonpayton
changed the title
brandonpayton
changed the title
Detect network/download failures by pattern-matching error messages in the cause chain (TypeError "Failed to fetch", module import failures, WebAssembly CompileError/LinkError) and show a dedicated error view with actionable guidance instead of the generic "Playground crashed" message. Also render an inline fallback in index.html when the initial app module fails to load before React is available.
The download error E2E test (`?php=0.0`) was broken for two reasons: 1. Blueprint validation rejects `0.0` before reaching the PHP loader 2. Vite's import-analysis plugin catches `@php-wasm/web-0-0` at transform time, preventing the module from loading at all Fix: Remove the non-existent module import approach. Instead, expose the Redux store on `window.__PLAYGROUND_STORE__` in dev mode and have the E2E test dispatch the error action directly. Error detection logic is already covered by comprehensive unit tests; the E2E test now verifies the modal UI renders correctly. Also includes from the parent commit: - Async/await fix for cache-busted retry in index.html fallback - Expanded unit tests for findFirewallErrorInCauseChain
brandonpayton
force-pushed
the
worktree-fix-download-error-handling
branch
from
4a8aa1a to
aa02b9b
Compare
brandonpayton
changed the title
These screenshots document the two error states tested by the error-handling E2E tests. They can be removed after PR review.
The test 'should prefer instanceof match over name match' had an unused `wrapper` variable and didn't actually test what it claimed — the `namedError` was disconnected from the chain. Rewire the test to build a proper chain (outer → namedError → realFirewall) and assert that the first match encountered while walking the chain is returned.
Member
Author
|
It's strange the E2E tests are failing here because they are passing on my desktop. We'll have to debug those. I'll still mark this as ready for review. |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds robust boot-time download failure detection and user-facing fallbacks so users see actionable guidance when required resources (or the app module itself) can’t be fetched.
Changes:
- Introduce
findDownloadErrorInCauseChain()and unit tests to detect fetch/import/WASM download failures via error cause chains - Surface a dedicated “Could not download required files” modal in both website and personal-wp boot flows
- Add a pre-React inline HTML fallback in
index.htmlwhen the main module import fails; add E2E coverage for both fallback and modal
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/playground/wordpress-builds/src/sqlite-database-integration/get-sqlite-driver-module-details.ts | Removes stray whitespace in switch statement. |
| packages/playground/website/src/lib/state/redux/store.ts | Exposes Redux store on window in dev for E2E-driven state injection. |
| packages/playground/website/src/lib/state/redux/slice-ui.ts | Adds resource-download-failed to site error union. |
| packages/playground/website/src/lib/state/redux/error-utils.ts | Adds download error detection via message/class-name pattern matching across cause chain. |
| packages/playground/website/src/lib/state/redux/error-utils.spec.ts | Adds unit tests for download + firewall error detection helpers. |
| packages/playground/website/src/lib/state/redux/boot-site-client.ts | Dispatches resource-download-failed when download-like errors occur. |
| packages/playground/website/src/components/site-error-modal/get-site-error-view.tsx | Adds a dedicated UI view for download failures and prioritizes it over blueprint step view. |
| packages/playground/website/playwright/e2e/error-handling.spec.ts | Adds E2E coverage for module-load inline fallback and download-error modal rendering. |
| packages/playground/website/index.html | Adds inline HTML fallback template and renders it when ./src/main import fails (including cache-busted retry). |
| packages/playground/remote/remote.html | Updates “report an issue” links to point to the correct repository. |
| packages/playground/personal-wp/src/lib/state/redux/slice-ui.ts | Adds resource-download-failed to site error union. |
| packages/playground/personal-wp/src/lib/state/redux/error-utils.ts | Adds download error detection helper mirroring website implementation. |
| packages/playground/personal-wp/src/lib/state/redux/boot-site-client.ts | Dispatches resource-download-failed when download-like errors occur. |
| packages/playground/personal-wp/src/components/site-error-modal/get-site-error-view.tsx | Adds a dedicated UI view for download failures and prioritizes it over blueprint step view. |
| packages/playground/personal-wp/index.html | Adds inline HTML fallback template and renders it when ./src/main import fails (including cache-busted retry). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
brandonpayton
changed the title
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.
Summary
index.htmlwhen the main app module fails to load entirely (before React is available)findDownloadErrorInCauseChain()utility that walks error cause chains to detect fetch failures, dynamic import errors, and WebAssembly compile/link errors (including Comlink-serialized variants)playground-websiteandplayground-personal-wpDownload error modal
When a resource fails to download during boot (PHP WASM binary, WordPress zip, etc.), users see actionable guidance:
Inline fallback (main module fails to load)
When the app module itself can't load (severe network issue, broken cache), a plain HTML fallback is shown without requiring React:
Matched error patterns
TypeError: Failed to fetchTypeError: Importing a module script failedTypeError: error loading dynamically imported moduleTypeError: NetworkError when attempting to fetchTypeError: Load failedWebAssembly.CompileError/LinkErrorAlso handles Comlink-serialized errors via
originalErrorClassName.E2E test approach
The download error modal E2E test dispatches the
resource-download-failederror directly through the Redux store (exposed onwindow.__PLAYGROUND_STORE__in dev mode). Triggering a real download error in E2E is impractical because the PHP WASM binary and WordPress files are fetched by a Web Worker, whose network requests Playwright cannot intercept. The error detection logic is covered by 28 unit tests inerror-utils.spec.ts; the E2E test verifies the modal UI renders correctly.Test plan
findDownloadErrorInCauseChainandfindFirewallErrorInCauseChain*.wasmrequests in devtools Network tab, load Playground — should show "Could not download required files" modalindex.htmlinline fallback appears