Fix demo pages on subdirectory mounts and add error reporting - #22
Merged
Conversation
On a phone a demo that cannot reach a GPU showed nothing at all. Six of the eight examples called init() with no catch, so a missing navigator.gpu or a null adapter threw out of the module script into a console the reader does not have — a loaded page, a blank canvas, and no way to tell that from the JavaScript never having run. - diag.js: a classic, non-module script loaded first by every demo page. It traps window 'error' and 'unhandledrejection' and puts the failure on the screen with an environment report (user agent, secure context, adapter, limits). Being classic and loaded ahead of the modules, it also catches a module that fails to load or parse. - libselect.js: gpuAdvice() names what a failure means on the device in front of the reader, reportFailure() raises the banner, and boot() is the one call the examples now make — picker, build import, init(), failure reported. - Examples 1-5 and 8 moved to boot(); 6 and 7 keep their own error strip but fill it from the shared reporter. The tutorial reports an adapter failure once at page level rather than only inside whichever box asked first. - docs/webgpu-check.html: a library-free page that walks navigator.gpu → adapter → device → one compiled and drawn triangle and says where the chain broke, with a copyable report. Linked from the banner, the index and the tutorial's unsupported notice. - README: the Android specifics — Chrome 121+ on Android 12+, and no WebGPU at all in Samsung Internet, Firefox for Android or in-app browsers. No change to src/ or dist/. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UEu5U9tL6svBahBmuxjrC5
Every example and the tutorial were dead on the deployed site — page renders,
build picker appears, nothing runs, no message. loadLib built its specifier
from a `base` the page passed in ('../src/tinywebgpu.js' from a page one level
down), but a dynamic import() resolves against the importing module's URL, and
libselect.js is at the repo root. Served from the root of an origin the leading
'..' has nowhere to go and is clamped away, so python3 -m http.server resolved
it correctly and hid the bug. Under GitHub Pages the site is at /tinywebgpu/,
so it walked out to the domain root:
Failed to fetch dynamically imported module:
https://lampmaker.github.io/src/tinywebgpu.js
loadLib now resolves against import.meta.url, correct wherever the site is
mounted and wherever the page sits. `base` is gone from loadLib, boot and every
call site.
test/paths.test.mjs resolves every src, href and import specifier on the demo
pages the way a browser will — against a mount at /tinywebgpu/, the case that
fails — and checks each against the files on disk, fragments included. It found
two more dead links: examples 6 and 7 linked ../tutorial.html rather than
../docs/tutorial.html. Wired into `npm test`.
Verified: all ten pages under a subdirectory mount, across ?lib=full|min|tiny,
now fetch the right build with no 404s, and root-served pages still work.
No change to src/ or dist/.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UEu5U9tL6svBahBmuxjrC5
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
2 participants
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
This PR fixes a critical bug where demo pages failed to load their library when the site was mounted at a subdirectory (e.g.,
/tinywebgpu/on GitHub Pages), and adds visible error reporting for WebGPU initialization failures.Key Changes
Fixed library import path resolution:
libselect.jsnow resolves build imports againstimport.meta.url(the module's own location) instead of using a page-relativebaseargument. This ensures the correct library is loaded regardless of where the site is mounted or where the page lives.Added error reporting system: Created
diag.js, a classic (non-module) script that traps uncaught errors andunhandledrejectionevents, displaying them as a banner on the page with environment details. This is critical for mobile users who have no console access.Added WebGPU diagnostic page: Created
docs/webgpu-check.htmlto help users determine whether WebGPU works on their device, with detailed environment reporting and a minimal GPU test.Enhanced error handling in libselect.js: Added
gpuAdvice()function that provides context-specific guidance based on the failure type (no WebGPU support vs. adapter refused), andboot()function that wraps the full initialization pipeline with error reporting.Updated all demo pages: Added
<script src="../diag.js"></script>to every example page and the tutorial to ensure errors are visible.Fixed broken links: Corrected tutorial links in examples 6 and 7 from
../tutorial.htmlto../docs/tutorial.html.Added path validation test: Created
test/paths.test.mjsthat validates allsrc,href, and import specifiers on demo pages resolve correctly when the site is mounted at/tinywebgpu/, catching the exact failure case that occurred on GitHub Pages.Implementation Details
The core issue was that
import()specifiers resolve against the importing module's URL, not the document's. By anchoring the build path toimport.meta.urlinlibselect.js(which sits at the repo root), the library is always found correctly regardless of mount point.The error reporting system is deliberately non-module to catch failures that prevent modules from loading or parsing, and runs early in the page lifecycle to catch all error types.
https://claude.ai/code/session_01UEu5U9tL6svBahBmuxjrC5