Fix demo pages on subdirectory mounts and add error reporting by lampmaker · Pull Request #22 · lampmaker/tinywebgpu

lampmaker · 2026-08-21T06:53:31Z

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.js now resolves build imports against import.meta.url (the module's own location) instead of using a page-relative base argument. 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 and unhandledrejection events, 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.html to 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), and boot() 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.html to ../docs/tutorial.html.
Added path validation test: Created test/paths.test.mjs that validates all src, 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 to import.meta.url in libselect.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

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

lampmaker · 2026-08-21T06:53:31Z

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.js now resolves build imports against import.meta.url (the module's own location) instead of using a page-relative base argument. 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 and unhandledrejection events, 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.html to 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), and boot() 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.html to ../docs/tutorial.html.
Added path validation test: Created test/paths.test.mjs that validates all src, 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 to import.meta.url in libselect.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

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

lampmaker · 2026-08-21T06:53:31Z

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.js now resolves build imports against import.meta.url (the module's own location) instead of using a page-relative base argument. 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 and unhandledrejection events, 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.html to 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), and boot() 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.html to ../docs/tutorial.html.
Added path validation test: Created test/paths.test.mjs that validates all src, 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 to import.meta.url in libselect.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

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

lampmaker · 2026-08-21T06:53:31Z

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.js now resolves build imports against import.meta.url (the module's own location) instead of using a page-relative base argument. 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 and unhandledrejection events, 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.html to 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), and boot() 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.html to ../docs/tutorial.html.
Added path validation test: Created test/paths.test.mjs that validates all src, 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 to import.meta.url in libselect.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

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

lampmaker · 2026-08-21T06:53:31Z

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.js now resolves build imports against import.meta.url (the module's own location) instead of using a page-relative base argument. 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 and unhandledrejection events, 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.html to 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), and boot() 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.html to ../docs/tutorial.html.
Added path validation test: Created test/paths.test.mjs that validates all src, 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 to import.meta.url in libselect.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

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

lampmaker · 2026-08-21T06:53:31Z

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.js now resolves build imports against import.meta.url (the module's own location) instead of using a page-relative base argument. 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 and unhandledrejection events, 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.html to 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), and boot() 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.html to ../docs/tutorial.html.
Added path validation test: Created test/paths.test.mjs that validates all src, 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 to import.meta.url in libselect.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

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

lampmaker · 2026-08-21T06:53:31Z

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.js now resolves build imports against import.meta.url (the module's own location) instead of using a page-relative base argument. 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 and unhandledrejection events, 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.html to 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), and boot() 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.html to ../docs/tutorial.html.
Added path validation test: Created test/paths.test.mjs that validates all src, 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 to import.meta.url in libselect.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

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

lampmaker · 2026-08-21T06:53:31Z

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.js now resolves build imports against import.meta.url (the module's own location) instead of using a page-relative base argument. 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 and unhandledrejection events, 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.html to 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), and boot() 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.html to ../docs/tutorial.html.
Added path validation test: Created test/paths.test.mjs that validates all src, 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 to import.meta.url in libselect.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

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

claude added 2 commits August 21, 2026 06:39

lampmaker merged commit b85c4b4 into mainAug 21, 2026
1 check passed