From 1f5756fd7c6a99aaae23f7b0a22b869d41b5844e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 21 Aug 2026 06:39:11 +0000
Subject: [PATCH 1/2] Make a failed WebGPU start-up visible on the page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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
---
 README.md                        |  18 ++-
 diag.js                          | 180 +++++++++++++++++++++++
 docs/tutorial.html               |  16 ++-
 docs/webgpu-check.html           | 240 +++++++++++++++++++++++++++++++
 examples/1_hello.html            |  12 +-
 examples/2_compute_readback.html |  11 +-
 examples/3_life.html             |  10 +-
 examples/4_indirect.html         |  11 +-
 examples/5_texture.html          |  11 +-
 examples/6_evolution.html        |  13 +-
 examples/7_particles.html        |  13 +-
 examples/8_heightmap.html        |  10 +-
 index.html                       |  10 +-
 libselect.js                     |  48 +++++++
 14 files changed, 566 insertions(+), 37 deletions(-)
 create mode 100644 diag.js
 create mode 100644 docs/webgpu-check.html

diff --git a/README.md b/README.md
index 98519f2..6612018 100644
--- a/README.md
+++ b/README.md
@@ -460,11 +460,12 @@ no TypeScript build needed, and plain-JS users get it too through their editor.
 src/        tinywebgpu.js — the library — and tinywebgpu.d.ts
 dist/       the built artifacts, committed so the demo pages can load them
 tools/      build-min.mjs, its two configs, and find-repeats.mjs
-docs/       the tutorial, API.md, CHANGELOG.md
+docs/       the tutorial, webgpu-check.html, API.md, CHANGELOG.md
 examples/   the eight demo pages
 test/       the test suite
 index.html  the demo index — the site's landing page
 libselect.js  the ?lib=full|min|tiny picker the pages share
+diag.js     puts an uncaught page error on the screen — see "Browser support" below
 ```
 
 To vendor the library, take `src/tinywebgpu.js` (or a file from `dist/`) and drop it next to your
@@ -476,6 +477,21 @@ Pages, which is why `index.html` and `.nojekyll` live there.
 WebGPU requires a current browser (Chrome/Edge 113+, Firefox 141+ on Windows, Safari 26+) and
 a secure context (https or localhost). No WebGL fallback — this is a WebGPU tool.
 
+On **Android**, WebGPU means Chrome 121+ on Android 12 or newer. Samsung Internet, Firefox for
+Android, and the in-app browsers that chat and mail apps open links in have no WebGPU at all, so
+a demo opened from a message will not run — open it in Chrome. Where Chrome has WebGPU but the
+driver is blocklisted, `requestAdapter()` returns null; `chrome://flags/#enable-unsafe-webgpu`
+usually gets past that.
+
+Because a phone has no console, the demo pages do not rely on one. Every page loads `diag.js`
+first — a plain, non-module script that turns an uncaught error into a banner on the page:
+a missing `navigator.gpu`, a null adapter, a module that failed to load or parse. The banner
+carries an environment report (user agent, secure context, adapter, limits) and links to
+**[docs/webgpu-check.html](https://lampmaker.github.io/tinywebgpu/docs/webgpu-check.html)**,
+a library-free page that compiles and draws one triangle and reports exactly where the chain
+broke. That page is the right thing to open — and the right report to paste — when a demo shows
+nothing on a device.
+
 ## License
 
 MIT.
diff --git a/diag.js b/diag.js
new file mode 100644
index 0000000..c1f4b59
--- /dev/null
+++ b/diag.js
@@ -0,0 +1,180 @@
+// Failure reporting for the demo pages. A classic script, deliberately ES5, deliberately not a
+// module: it is loaded from <head> before anything else, so it is already listening when the
+// module scripts are parsed and run.
+//
+// Why it exists: a WebGPU demo that cannot start has nowhere to say so. An uncaught throw in a
+// `<script type="module">` — a missing navigator.gpu, a null adapter, a module that failed to
+// parse — goes to the console and nothing else, and a phone has no console. The page just sits
+// there looking loaded, which reads as "the JavaScript never ran". This turns every one of those
+// into a banner on the page, with the environment details needed to tell the cases apart.
+//
+// The global is TWG_DIAG:
+//   TWG_DIAG.fail(title, detail)   show the banner (first call wins; later ones are ignored)
+//   TWG_DIAG.report()              Promise<string> of the environment report
+//   TWG_DIAG.shown                 whether a banner is up
+
+(function () {
+  'use strict';
+
+  var W = window;
+  if (W.TWG_DIAG) return;
+
+  var CHECK = 'webgpu-check.html';   // resolved against this script's own URL below
+  var checkHref = (function () {
+    var s = document.currentScript;
+    try { return new URL('docs/' + CHECK, s ? s.src : location.href).href; } catch (e) { return ''; }
+  })();
+
+  var api = { shown: false };
+  W.TWG_DIAG = api;
+
+  // ---- the environment report ---------------------------------------------------------------
+  // Everything that decides whether a WebGPU page can run, in the order you would check it by
+  // hand. The adapter probe is async and best-effort: a browser without navigator.gpu never
+  // reaches it, and one that hangs on requestAdapter is cut off rather than left pending.
+  var lines = function (o) {
+    var out = [], k;
+    for (k = 0; k < o.length; k++) out.push(o[k][0] + ': ' + o[k][1]);
+    return out.join('\n');
+  };
+
+  api.report = function () {
+    var base = [
+      ['page', location.href],
+      ['userAgent', navigator.userAgent],
+      ['secure context', String(W.isSecureContext)],
+      ['navigator.gpu', navigator.gpu ? 'present' : 'MISSING'],
+      ['viewport', W.innerWidth + '×' + W.innerHeight + ' @ dpr ' + (W.devicePixelRatio || 1)],
+    ];
+    if (!navigator.gpu) return Promise.resolve(lines(base));
+
+    var timeout = new Promise(function (res) {
+      setTimeout(function () { res(null); }, 4000);
+    });
+    var probe = Promise.resolve()
+      .then(function () { return navigator.gpu.requestAdapter(); })
+      .then(function (a) {
+        if (!a) { base.push(['adapter', 'NULL — the browser has WebGPU but this device/driver gave no adapter']); return; }
+        var info = a.info || {};
+        base.push(['adapter', [info.vendor, info.architecture, info.device, info.description]
+          .filter(Boolean).join(' / ') || '(no info exposed)']);
+        base.push(['features', a.features ? a.features.size + ' available' : '?']);
+        var L = a.limits || {};
+        base.push(['maxBufferSize', String(L.maxBufferSize)]);
+        base.push(['maxStorageBufferBindingSize', String(L.maxStorageBufferBindingSize)]);
+        base.push(['maxComputeInvocationsPerWorkgroup', String(L.maxComputeInvocationsPerWorkgroup)]);
+        base.push(['maxComputeWorkgroupStorageSize', String(L.maxComputeWorkgroupStorageSize)]);
+        base.push(['maxStorageBuffersPerShaderStage', String(L.maxStorageBuffersPerShaderStage)]);
+      })
+      .catch(function (e) { base.push(['adapter', 'requestAdapter threw: ' + (e && e.message || e)]); });
+
+    return Promise.race([probe, timeout]).then(function (r) {
+      if (r === null) base.push(['adapter', 'requestAdapter did not answer within 4s']);
+      return lines(base);
+    });
+  };
+
+  // ---- the banner ---------------------------------------------------------------------------
+  var CSS =
+    '#twg-diag{position:fixed;left:0;right:0;top:0;z-index:2147483647;box-sizing:border-box;' +
+    'max-height:80vh;overflow:auto;padding:.8rem 2.5rem .8rem 1rem;background:#2c2413;color:#f0d79a;' +
+    'border-bottom:1px solid rgba(240,215,154,.4);' +
+    'font:13px/1.55 ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;' +
+    '-webkit-text-size-adjust:100%;text-align:left}' +
+    '#twg-diag b{color:#ffe9b8}' +
+    '#twg-diag a{color:#9fc0ff}' +
+    '#twg-diag pre{white-space:pre-wrap;overflow-wrap:anywhere;margin:.5rem 0 0;' +
+    'font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;color:#d8c79c}' +
+    '#twg-diag summary{cursor:pointer;margin-top:.5rem;color:#e8c983}' +
+    '#twg-diag .x{position:absolute;top:.35rem;right:.5rem;background:none;border:0;' +
+    'color:#f0d79a;font-size:20px;line-height:1;padding:.2rem .45rem;cursor:pointer}';
+
+  var mount = function (node) {
+    var to = document.body || document.documentElement;
+    to.appendChild(node);
+  };
+
+  api.fail = function (title, detail) {
+    if (api.shown) return;                     // the first failure is the interesting one
+    api.shown = true;
+
+    var run = function () {
+      var style = document.createElement('style');
+      style.textContent = CSS;
+      (document.head || document.documentElement).appendChild(style);
+
+      var box = document.createElement('div');
+      box.id = 'twg-diag';
+      box.setAttribute('role', 'alert');
+
+      var close = document.createElement('button');
+      close.className = 'x';
+      close.setAttribute('aria-label', 'dismiss');
+      close.textContent = '×';
+      close.onclick = function () { box.parentNode.removeChild(box); };
+
+      var head = document.createElement('div');
+      var b = document.createElement('b');
+      b.textContent = title;
+      head.appendChild(b);
+      if (detail) {
+        head.appendChild(document.createTextNode(' '));
+        head.appendChild(document.createTextNode(detail));
+      }
+      if (checkHref) {
+        head.appendChild(document.createTextNode(' '));
+        var a = document.createElement('a');
+        a.href = checkHref;
+        a.textContent = 'Run the WebGPU check →';
+        head.appendChild(a);
+      }
+
+      var det = document.createElement('details');
+      var sum = document.createElement('summary');
+      sum.textContent = 'Environment details';
+      var pre = document.createElement('pre');
+      pre.textContent = 'collecting…';
+      det.appendChild(sum);
+      det.appendChild(pre);
+      api.report().then(function (t) { pre.textContent = t; });
+
+      box.appendChild(close);
+      box.appendChild(head);
+      box.appendChild(det);
+      mount(box);
+    };
+
+    if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', run);
+    else run();
+  };
+
+  // ---- the traps ----------------------------------------------------------------------------
+  // A module that fails to parse, a module that throws while evaluating, and a rejected promise
+  // nobody caught all end up here. Without these three, each of them is a silent blank page.
+  var describe = function (e) {
+    if (!e) return 'Unknown error.';
+    if (typeof e === 'string') return e;
+    return (e.name ? e.name + ': ' : '') + (e.message || String(e));
+  };
+
+  W.addEventListener('error', function (ev) {
+    // Resource errors (a 404 on <img>/<script src>) do not bubble as ErrorEvent with .error, but
+    // they do arrive here in the capture phase; only the script-level ones matter for the banner.
+    if (ev.target && ev.target !== W && ev.target.tagName) {
+      var tag = ev.target.tagName;
+      if (tag === 'SCRIPT' || tag === 'LINK') {
+        var url = ev.target.src || ev.target.href;
+        api.fail('This page could not load one of its scripts.', url
+          ? 'The browser failed to fetch ' + url + '.'
+          : 'A module script failed to load or parse — check that the library files under ' +
+            'src/ and dist/ are being served, and as JavaScript.');
+      }
+      return;
+    }
+    api.fail('This page stopped with an error.', describe(ev.error || ev.message));
+  }, true);
+
+  W.addEventListener('unhandledrejection', function (ev) {
+    api.fail('This page stopped with an error.', describe(ev.reason));
+  });
+})();
diff --git a/docs/tutorial.html b/docs/tutorial.html
index 861534e..172fbdd 100644
--- a/docs/tutorial.html
+++ b/docs/tutorial.html
@@ -7,6 +7,10 @@
   <title>TinyWebGPU — tutorial</title>
   <meta name="description" content="A step-by-step tutorial for TinyWebGPU: from one fullscreen
     shader to compute, atomics and a particle system. Every code box on the page really runs.">
+  <!-- Loaded first and on purpose not a module: it turns an uncaught error in the
+       module scripts below — no WebGPU, no adapter, a file that failed to load — into
+       a banner on the page, because a phone has no console to print it to. -->
+  <script src="../diag.js"></script>
   <style>
     :root {
       color-scheme: light dark;
@@ -187,7 +191,9 @@ <h1>TinyWebGPU, step by step</h1>
     <div id="unsupported">
       <strong>WebGPU isn’t available in this browser.</strong> The text still reads fine, but no
       box will run. You need Chrome/Edge 113+, Firefox 141+ (Windows) or Safari 26+, over https
-      or localhost.
+      or localhost. On Android that means Chrome 121+ on Android 12+ — Samsung Internet, Firefox
+      for Android and the in-app browsers inside chat and mail apps have no WebGPU at all.
+      <a href="webgpu-check.html">Run the WebGPU check</a> to see what this device reports.
     </div>
 
     <div class="note">
@@ -1436,7 +1442,7 @@ <h3>Where to go next</h3>
     // The tutorial itself needs nothing beyond the core, but many boxes read results back,
     // resize their canvas or upload textures — features the stock tiny build drops — so under
     // tiny those boxes are skipped with a note instead of failing on a missing function.
-    import { loadLib, explain, missing, TINY_DROPS } from '../libselect.js';
+    import { loadLib, explain, missing, reportFailure, TINY_DROPS } from '../libselect.js';
     const { WEBGPU, lib } = await loadLib(['read', 'resize', 'texio', 'depth'], '..');
 
     // What a box's code can use that the tiny build lacks. Checked against the live editor
@@ -1476,7 +1482,11 @@ <h3>Where to go next</h3>
     const TYPE_NAMES = Object.keys(TYPES);
     const DEFINES = Object.entries({ ...TYPES, ...CONSTS }).map(([t, r]) => `${t} ${r}`).join('\n');
 
-    const getG = () => (initPromise ||= WEBGPU().init().then(g => (g.defines = DEFINES, g)));
+    // A failure here is about the device, not about the box that happened to ask first, so it
+    // is reported once at page level as well as in that box's output panel.
+    const getG = () => (initPromise ||= WEBGPU().init()
+      .then(g => (g.defines = DEFINES, g))
+      .catch(e => { reportFailure(e, lib); throw e; }));
 
     const useCanvas = canvas => {
       if (!canvas) return;
diff --git a/docs/webgpu-check.html b/docs/webgpu-check.html
new file mode 100644
index 0000000..3ec25e2
--- /dev/null
+++ b/docs/webgpu-check.html
@@ -0,0 +1,240 @@
+<!DOCTYPE html>
+<!-- Does WebGPU work on this device? One page, one answer, no library involved.
+     Linked from the failure banner every demo shows when it cannot start, so a reader on a
+     phone can find out whether the problem is the browser, the driver or the page. -->
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+  <title>TinyWebGPU — WebGPU check</title>
+  <style>
+    :root {
+      color-scheme: light dark;
+      --bg: #ffffff; --fg: #1b1b1f; --muted: #5c5c68; --line: #e3e3e8; --card: #fafafb;
+      --accent: #2f6df6; --ok: #1a7f37; --bad: #b3261e;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg: #131317; --fg: #e8e8ec; --muted: #9a9aa6; --line: #2a2a32; --card: #1a1a20;
+        --accent: #7aa2ff; --ok: #4ac26b; --bad: #ff8a80;
+      }
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0; padding: 2rem 1rem 4rem; background: var(--bg); color: var(--fg);
+      font: 16px/1.6 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+      -webkit-text-size-adjust: 100%;
+    }
+    main { max-width: 42rem; margin: 0 auto; }
+    h1 { font-size: 1.5rem; margin: 0 0 1.25rem; letter-spacing: -.02em; }
+    #verdict {
+      padding: 1rem 1.15rem; border: 1px solid var(--line); border-radius: 10px;
+      background: var(--card); margin-bottom: 1.25rem;
+    }
+    #verdict strong { display: block; font-size: 1.1rem; margin-bottom: .35rem; }
+    #verdict.ok strong { color: var(--ok); }
+    #verdict.bad strong { color: var(--bad); }
+    canvas {
+      display: block; width: 100%; max-width: 22rem; height: auto; aspect-ratio: 16 / 9;
+      border: 1px solid var(--line); border-radius: 8px; background: var(--card);
+    }
+    .cap { color: var(--muted); font-size: .9rem; margin: .4rem 0 1.5rem; }
+    table { border-collapse: collapse; width: 100%; font-size: .9rem; }
+    th, td {
+      text-align: left; padding: .4rem .5rem; border-bottom: 1px solid var(--line);
+      vertical-align: top; overflow-wrap: anywhere;
+    }
+    th { color: var(--muted); font-weight: 500; white-space: nowrap; width: 40%; }
+    td { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: .85rem; }
+    /* Two columns do not fit a phone: a user-agent string ends up one character per line.
+       Stack the label above its value instead. */
+    @media (max-width: 34rem) {
+      th, td { display: block; width: auto; }
+      th { border-bottom: 0; padding-bottom: 0; white-space: normal; }
+      td { padding-top: .1rem; }
+    }
+    button {
+      font: inherit; font-size: .9rem; padding: .5rem .9rem; margin: 1.25rem .5rem 0 0;
+      border: 1px solid var(--line); border-radius: 8px; background: var(--card); color: inherit;
+    }
+    a { color: var(--accent); }
+    footer { margin-top: 2rem; padding-top: 1.25rem; border-top: 1px solid var(--line); font-size: .9rem; }
+  </style>
+</head>
+
+<body>
+  <main>
+    <h1>WebGPU check</h1>
+
+    <div id="verdict"><strong>Checking…</strong><span id="advice"></span></div>
+
+    <canvas id="c" width="480" height="270"></canvas>
+    <p class="cap" id="cap">A shader should paint this box. If it stays empty, nothing below ran.</p>
+
+    <h2 style="font-size:1rem;color:var(--muted);margin:0 0 .5rem">Environment</h2>
+    <table id="env"></table>
+
+    <button id="copy">Copy this report</button>
+    <button id="again">Run again</button>
+
+    <footer>
+      Back to the <a href="../index.html">demos</a> and the <a href="tutorial.html">tutorial</a>.
+    </footer>
+  </main>
+
+  <!-- Deliberately a classic script, not a module: if this page cannot run, the reason must
+       still reach the screen, and that rules out anything that could fail to parse first. -->
+  <script>
+    (function () {
+      var $ = function (id) { return document.getElementById(id); };
+      var rows = [];
+      var add = function (k, v) { rows.push([k, v]); };
+
+      var render = function () {
+        var t = $('env');
+        t.textContent = '';
+        for (var i = 0; i < rows.length; i++) {
+          var tr = document.createElement('tr');
+          var th = document.createElement('th');
+          var td = document.createElement('td');
+          th.textContent = rows[i][0];
+          td.textContent = String(rows[i][1]);
+          tr.appendChild(th); tr.appendChild(td); t.appendChild(tr);
+        }
+      };
+
+      var verdict = function (cls, title, advice) {
+        $('verdict').className = cls;
+        $('verdict').querySelector('strong').textContent = title;
+        $('advice').textContent = advice;
+      };
+
+      // A deliberately minimal pipeline: no library, no bind groups, no buffers. If this draws,
+      // WebGPU on this device works and any demo that still fails is the demo's problem.
+      var SHADER =
+        '@vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> {\n' +
+        '  var p = array<vec2<f32>, 3>(vec2(-1.0, -1.0), vec2(3.0, -1.0), vec2(-1.0, 3.0));\n' +
+        '  return vec4<f32>(p[i], 0.0, 1.0);\n' +
+        '}\n' +
+        '@fragment fn fs(@builtin(position) c: vec4<f32>) -> @location(0) vec4<f32> {\n' +
+        '  let uv = c.xy / 480.0;\n' +
+        '  return vec4<f32>(uv.x, uv.y, 0.6, 1.0);\n' +
+        '}\n';
+
+      var run = function () {
+        rows = [];
+        add('page', location.href);
+        add('userAgent', navigator.userAgent);
+        add('secure context (https or localhost)', String(window.isSecureContext));
+        add('viewport', window.innerWidth + '×' + window.innerHeight +
+          ' @ dpr ' + (window.devicePixelRatio || 1));
+        add('navigator.gpu', navigator.gpu ? 'present' : 'MISSING');
+        render();
+
+        if (!navigator.gpu) {
+          verdict('bad', 'No WebGPU in this browser.',
+            'On Android this usually means you are not in Chrome: Samsung Internet, Firefox for ' +
+            'Android, and the in-app browsers inside chat and mail apps have no WebGPU. Open this ' +
+            'page in Chrome 121 or newer on Android 12 or newer. On desktop you need Chrome/Edge ' +
+            '113+, Firefox 141+ (Windows) or Safari 26+, and the page must be on https or localhost.');
+          if (!window.isSecureContext) {
+            add('note', 'navigator.gpu is only exposed in a secure context — this page is not one.');
+            render();
+          }
+          return;
+        }
+
+        verdict('', 'Asking for an adapter…', '');
+
+        navigator.gpu.requestAdapter().then(function (a) {
+          if (!a) {
+            add('adapter', 'NULL');
+            render();
+            verdict('bad', 'WebGPU is present, but this device gave no adapter.',
+              'The GPU or its driver is blocked for WebGPU here. In Chrome, open ' +
+              'chrome://flags/#enable-unsafe-webgpu, switch it on and relaunch. An incognito ' +
+              'window, or hardware acceleration turned off, will also refuse an adapter.');
+            return;
+          }
+          var info = a.info || {};
+          add('adapter', [info.vendor, info.architecture, info.device, info.description]
+            .filter(Boolean).join(' / ') || '(no info exposed)');
+          add('features', a.features ? a.features.size + ' available' : '?');
+          var L = a.limits || {};
+          var keys = ['maxBufferSize', 'maxStorageBufferBindingSize',
+            'maxComputeInvocationsPerWorkgroup', 'maxComputeWorkgroupStorageSize',
+            'maxStorageBuffersPerShaderStage', 'maxTextureDimension2D'];
+          for (var i = 0; i < keys.length; i++) add(keys[i], L[keys[i]]);
+          render();
+
+          return a.requestDevice().then(function (d) {
+            var canvas = $('c');
+            var ctx = canvas.getContext('webgpu');
+            if (!ctx) throw new Error('canvas.getContext("webgpu") returned null');
+            var fmt = navigator.gpu.getPreferredCanvasFormat();
+            add('preferred canvas format', fmt);
+            ctx.configure({ device: d, format: fmt, alphaMode: 'opaque' });
+
+            var mod = d.createShaderModule({ code: SHADER });
+            var pipe = d.createRenderPipeline({
+              layout: 'auto',
+              vertex: { module: mod, entryPoint: 'vs' },
+              fragment: { module: mod, entryPoint: 'fs', targets: [{ format: fmt }] },
+              primitive: { topology: 'triangle-list' },
+            });
+            var enc = d.createCommandEncoder();
+            var pass = enc.beginRenderPass({
+              colorAttachments: [{
+                view: ctx.getCurrentTexture().createView(),
+                loadOp: 'clear', storeOp: 'store', clearValue: { r: 0, g: 0, b: 0, a: 1 },
+              }],
+            });
+            pass.setPipeline(pipe);
+            pass.draw(3);
+            pass.end();
+            d.queue.submit([enc.finish()]);
+
+            return d.queue.onSubmittedWorkDone().then(function () {
+              add('draw', 'submitted and completed');
+              render();
+              verdict('ok', 'WebGPU works on this device.',
+                'A triangle was compiled, drawn and presented. If a demo page still shows nothing, ' +
+                'the problem is in that page rather than in your browser — please report it with ' +
+                'the report below.');
+              $('cap').textContent = 'This gradient is real output from your GPU.';
+            });
+          });
+        }).catch(function (e) {
+          add('error', (e && e.name ? e.name + ': ' : '') + (e && e.message || e));
+          render();
+          verdict('bad', 'WebGPU failed part-way through.',
+            'An adapter was found but the device or the first pipeline did not come up. The error ' +
+            'is in the table below.');
+        });
+      };
+
+      $('again').onclick = run;
+      $('copy').onclick = function () {
+        var text = rows.map(function (r) { return r[0] + ': ' + r[1]; }).join('\n');
+        if (navigator.clipboard) {
+          navigator.clipboard.writeText(text).then(function () {
+            $('copy').textContent = 'Copied';
+            setTimeout(function () { $('copy').textContent = 'Copy this report'; }, 1500);
+          });
+        } else {
+          $('copy').textContent = 'Clipboard unavailable — select the table by hand';
+        }
+      };
+
+      window.addEventListener('error', function (ev) {
+        verdict('bad', 'This page itself hit a JavaScript error.',
+          (ev.error && ev.error.message) || ev.message || 'unknown');
+      });
+
+      run();
+    })();
+  </script>
+</body>
+
+</html>
diff --git a/examples/1_hello.html b/examples/1_hello.html
index 9c6c933..fc588d0 100644
--- a/examples/1_hello.html
+++ b/examples/1_hello.html
@@ -7,6 +7,10 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
   <title>TinyWebGPU — hello shader</title>
+  <!-- Loaded first and on purpose not a module: it turns an uncaught error in the
+       module scripts below — no WebGPU, no adapter, a file that failed to load — into
+       a banner on the page, because a phone has no console to print it to. -->
+  <script src="../diag.js"></script>
   <style>
     body {
       margin: 0; min-height: 100vh; padding: 1rem; display: grid; place-items: center;
@@ -25,10 +29,10 @@
 <body>
   <canvas id="c" width="800" height="450"></canvas>
   <script type="module">
-    import { loadLib } from '../libselect.js';
-    const { WEBGPU } = await loadLib([], '..');   // ?lib=min|tiny switches the build
-
-    const G = await WEBGPU().init(document.getElementById('c').getContext('webgpu'));
+    import { boot } from '../libselect.js';
+    // boot = the ?lib=min|tiny picker, the import of that build, and init() — with any
+    // start-up failure (no WebGPU, no adapter) put on the page instead of only the console.
+    const { G } = await boot([], '..', document.getElementById('c'));
     const quad = G.makeQuad({
       frag: `fn frag(uv: vec2<f32>) -> vec4<f32> {
         return vec4<f32>(0.5 + 0.5 * cos(UB.time + uv.xyx * 4.0 + vec3<f32>(0.0, 2.0, 4.0)), 1.0);
diff --git a/examples/2_compute_readback.html b/examples/2_compute_readback.html
index c27e66c..5b96c3a 100644
--- a/examples/2_compute_readback.html
+++ b/examples/2_compute_readback.html
@@ -7,6 +7,10 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
   <title>TinyWebGPU — compute readback</title>
+  <!-- Loaded first and on purpose not a module: it turns an uncaught error in the
+       module scripts below — no WebGPU, no adapter, a file that failed to load — into
+       a banner on the page, because a phone has no console to print it to. -->
+  <script src="../diag.js"></script>
   <style>
     body {
       margin: 0; padding: 1rem; background: #111; color: #ddd;
@@ -21,10 +25,9 @@
 <body>
   <pre id="out">running…</pre>
   <script type="module">
-    import { loadLib } from '../libselect.js';
-    const { WEBGPU } = await loadLib(['read'], '..');   // ?lib=min|tiny switches the build
-
-    const G = await WEBGPU().init();          // compute-only: no canvas
+    import { boot } from '../libselect.js';
+    // No canvas argument: compute-only. boot also reports a failed start-up on the page.
+    const { G } = await boot(['read'], '..');   // ?lib=min|tiny switches the build
     const N = 16;
 
     const p = G.makeCompute('', `
diff --git a/examples/3_life.html b/examples/3_life.html
index 99847b7..5da73fc 100644
--- a/examples/3_life.html
+++ b/examples/3_life.html
@@ -8,6 +8,10 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
   <title>TinyWebGPU — game of life</title>
+  <!-- Loaded first and on purpose not a module: it turns an uncaught error in the
+       module scripts below — no WebGPU, no adapter, a file that failed to load — into
+       a banner on the page, because a phone has no console to print it to. -->
+  <script src="../diag.js"></script>
   <style>
     body {
       margin: 0; min-height: 100vh; padding: 1rem; display: grid; place-items: center;
@@ -27,11 +31,11 @@
 <body>
   <canvas id="c" width="512" height="512"></canvas>
   <script type="module">
-    import { loadLib } from '../libselect.js';
-    const { WEBGPU } = await loadLib([], '..');   // ?lib=min|tiny switches the build
+    import { boot } from '../libselect.js';
 
     const W = 256, H = 256;
-    const G = await WEBGPU().init(document.getElementById('c').getContext('webgpu'));
+    // boot = picker + build import + init(), with a start-up failure shown on the page.
+    const { G } = await boot([], '..', document.getElementById('c'));   // ?lib=min|tiny switches the build
 
     const step = G.makeCompute(`
         fn idx(x: i32, y: i32) -> u32 {
diff --git a/examples/4_indirect.html b/examples/4_indirect.html
index 1422fa4..75cd6e9 100644
--- a/examples/4_indirect.html
+++ b/examples/4_indirect.html
@@ -10,6 +10,10 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
   <title>TinyWebGPU — indirect dispatch</title>
+  <!-- Loaded first and on purpose not a module: it turns an uncaught error in the
+       module scripts below — no WebGPU, no adapter, a file that failed to load — into
+       a banner on the page, because a phone has no console to print it to. -->
+  <script src="../diag.js"></script>
   <style>
     body {
       margin: 0; padding: 1rem; background: #111; color: #ddd;
@@ -24,10 +28,9 @@
 <body>
   <pre id="out">running…</pre>
   <script type="module">
-    import { loadLib } from '../libselect.js';
-    const { WEBGPU } = await loadLib(['read'], '..');   // ?lib=min|tiny switches the build
-
-    const G = await WEBGPU().init();          // no canvas needed
+    import { boot } from '../libselect.js';
+    // No canvas argument: compute-only. boot also reports a failed start-up on the page.
+    const { G } = await boot(['read'], '..');   // ?lib=min|tiny switches the build
     const N = 1000;
 
     // 1) keep multiples of 7, compact them into `survivors`, count atomically
diff --git a/examples/5_texture.html b/examples/5_texture.html
index accaaac..031aec1 100644
--- a/examples/5_texture.html
+++ b/examples/5_texture.html
@@ -17,6 +17,10 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
   <title>TinyWebGPU — textures and blending</title>
+  <!-- Loaded first and on purpose not a module: it turns an uncaught error in the
+       module scripts below — no WebGPU, no adapter, a file that failed to load — into
+       a banner on the page, because a phone has no console to print it to. -->
+  <script src="../diag.js"></script>
   <style>
     body {
       margin: 0; padding: 1rem; background: #111; color: #ddd;
@@ -38,10 +42,9 @@
     <pre id="out">running…</pre>
   </main>
   <script type="module">
-    import { loadLib } from '../libselect.js';
-    const { WEBGPU } = await loadLib(['texio', 'read', 'blend'], '..');   // ?lib=min|tiny switches the build
-
-    const G = await WEBGPU().init(document.getElementById('c').getContext('webgpu'));
+    import { boot } from '../libselect.js';
+    // boot = picker + build import + init(), with a start-up failure shown on the page.
+    const { G } = await boot(['texio', 'read', 'blend'], '..', document.getElementById('c'));
     const log = [];
     let ok = true;
     const check = (name, pass, detail) => { ok &&= pass; log.push(`${pass ? 'ok  ' : 'FAIL'}  ${name}${detail ? '  — ' + detail : ''}`); };
diff --git a/examples/6_evolution.html b/examples/6_evolution.html
index 6c13026..4934259 100644
--- a/examples/6_evolution.html
+++ b/examples/6_evolution.html
@@ -33,6 +33,10 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
   <title>TinyWebGPU — differential evolution</title>
+  <!-- Loaded first and on purpose not a module: it turns an uncaught error in the
+       module scripts below — no WebGPU, no adapter, a file that failed to load — into
+       a banner on the page, because a phone has no console to print it to. -->
+  <script src="../diag.js"></script>
   <style>
     :root { color-scheme: dark; }
     * { box-sizing: border-box; }
@@ -101,8 +105,8 @@ <h1>Differential evolution</h1>
   </main>
 
   <script type="module">
-    import { loadLib } from '../libselect.js';
-    const { WEBGPU } = await loadLib(['read'], '..');   // ?lib=min|tiny switches the build
+    import { loadLib, reportFailure, explain } from '../libselect.js';
+    const { WEBGPU, lib } = await loadLib(['read'], '..');   // ?lib=min|tiny switches the build
 
     const canvas = document.getElementById('c');
     const el = id => document.getElementById(id);
@@ -149,10 +153,9 @@ <h1>Differential evolution</h1>
       G = await WEBGPU().init(canvas.getContext('webgpu'));
     } catch (e) {
       el('err').style.display = 'block';
-      el('err').textContent = `WebGPU unavailable: ${e.message}. Needs Chrome/Edge 113+, ` +
-        `Firefox 141+ (Windows) or Safari 26+, over https or localhost.`;
+      el('err').textContent = reportFailure(e);   // also raises the shared banner, with details
       el('status').textContent = '';
-      window.__result = { ok: false, msg: 'no webgpu: ' + e.message };
+      window.__result = { ok: false, msg: 'no webgpu: ' + explain(e, lib) };
       throw e;
     }
 
diff --git a/examples/7_particles.html b/examples/7_particles.html
index 01ea9db..984c837 100644
--- a/examples/7_particles.html
+++ b/examples/7_particles.html
@@ -21,6 +21,10 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
   <title>TinyWebGPU — particles</title>
+  <!-- Loaded first and on purpose not a module: it turns an uncaught error in the
+       module scripts below — no WebGPU, no adapter, a file that failed to load — into
+       a banner on the page, because a phone has no console to print it to. -->
+  <script src="../diag.js"></script>
   <style>
     :root { color-scheme: dark; }
     * { box-sizing: border-box; }
@@ -75,8 +79,8 @@ <h1>Particles</h1>
   </main>
 
   <script type="module">
-    import { loadLib } from '../libselect.js';
-    const { WEBGPU } = await loadLib(['read', 'resize'], '..');   // ?lib=min|tiny switches the build
+    import { loadLib, reportFailure, explain } from '../libselect.js';
+    const { WEBGPU, lib } = await loadLib(['read', 'resize'], '..');   // ?lib=min|tiny switches the build
 
     const canvas = document.getElementById('c');
     const el = id => document.getElementById(id);
@@ -93,10 +97,9 @@ <h1>Particles</h1>
       G = await WEBGPU().init(canvas.getContext('webgpu'));
     } catch (e) {
       el('err').style.display = 'block';
-      el('err').textContent = `WebGPU unavailable: ${e.message}. Needs Chrome/Edge 113+, ` +
-        `Firefox 141+ (Windows) or Safari 26+, over https or localhost.`;
+      el('err').textContent = reportFailure(e);   // also raises the shared banner, with details
       el('stats').textContent = '';
-      window.__result = { ok: false, msg: 'no webgpu: ' + e.message };
+      window.__result = { ok: false, msg: 'no webgpu: ' + explain(e, lib) };
       throw e;
     }
 
diff --git a/examples/8_heightmap.html b/examples/8_heightmap.html
index f3862b2..3033c6a 100644
--- a/examples/8_heightmap.html
+++ b/examples/8_heightmap.html
@@ -12,6 +12,10 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
   <title>TinyWebGPU — flat-shaded height map</title>
+  <!-- Loaded first and on purpose not a module: it turns an uncaught error in the
+       module scripts below — no WebGPU, no adapter, a file that failed to load — into
+       a banner on the page, because a phone has no console to print it to. -->
+  <script src="../diag.js"></script>
   <style>
     body {
       margin: 0; min-height: 100vh; padding: 1rem; display: grid; place-items: center;
@@ -32,15 +36,15 @@
   <canvas id="c"></canvas>
   <pre id="out">running…</pre>
   <script type="module">
-    import { loadLib } from '../libselect.js';
-    const { WEBGPU } = await loadLib(['read', 'resize', 'depth'], '..');   // ?lib=min|tiny switches the build
+    import { boot } from '../libselect.js';
 
     const N = 128;                       // cells per side
     const VN = N + 1;                    // grid vertices per side
     const SIZE = 2.0;                    // world extent, centred on the origin
 
     const canvas = document.getElementById('c');
-    const G = await WEBGPU().init(canvas.getContext('webgpu'));
+    // boot = picker + build import + init(), with a start-up failure shown on the page.
+    const { G } = await boot(['read', 'resize', 'depth'], '..', canvas);   // ?lib=min|tiny switches the build
 
     // One f32 per grid vertex. The compute pass writes it read_write; the vertex stage reads it
     // read-only. Same GPUBuffer, two pipelines, two address spaces — see `readOnly` below.
diff --git a/index.html b/index.html
index 66a3ef8..7fade6d 100644
--- a/index.html
+++ b/index.html
@@ -5,6 +5,10 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>TinyWebGPU — demos</title>
+  <!-- Loaded first and on purpose not a module: it turns an uncaught error in the
+       module scripts below — no WebGPU, no adapter, a file that failed to load — into
+       a banner on the page, because a phone has no console to print it to. -->
+  <script src="./diag.js"></script>
   <style>
     :root {
       color-scheme: light dark;
@@ -71,7 +75,10 @@ <h1>TinyWebGPU</h1>
 
     <div id="unsupported">
       <strong>WebGPU isn’t available in this browser.</strong> The demos need Chrome/Edge 113+,
-      Firefox 141+ (Windows), or Safari 26+, over https or localhost.
+      Firefox 141+ (Windows), or Safari 26+, over https or localhost. On Android that means
+      Chrome 121+ on Android 12+ — Samsung Internet, Firefox for Android and the in-app browsers
+      inside chat and mail apps have no WebGPU at all.
+      <a href="docs/webgpu-check.html">Run the WebGPU check</a> to see what this device reports.
     </div>
 
     <h2>Examples</h2>
@@ -109,6 +116,7 @@ <h2>Examples</h2>
     </ul>
 
     <footer>
+      Nothing rendering? <a href="docs/webgpu-check.html">Check WebGPU on this device</a>.<br>
       Source and docs: <a href="https://github.com/lampmaker/tinywebgpu">github.com/lampmaker/tinywebgpu</a>
       · The <a href="docs/tutorial.html">tutorial</a>, the
       <a href="https://github.com/lampmaker/tinywebgpu#readme">README</a> and the
diff --git a/libselect.js b/libselect.js
index bfb3918..8d3609f 100644
--- a/libselect.js
+++ b/libselect.js
@@ -152,3 +152,51 @@ export const loadLib = async (needs = [], base = '.') => {
   const { WEBGPU } = await import(`${base}/${BUILDS[lib].file}`);
   return { WEBGPU, lib, missing: missing(needs, lib) };
 };
+
+// Why a WebGPU start-up failure happened, in the terms a reader can act on. `init()` throws in
+// two distinguishable places — no navigator.gpu at all, and an adapter the browser would not
+// hand over — and on a phone those two mean very different things, so they get different text.
+export const gpuAdvice = e => {
+  const m = (e?.message ?? String(e)).toLowerCase();
+  if (!navigator.gpu || m.includes('not supported') || m === '1')
+    return 'This browser has no WebGPU at all. On Android that usually means the built-in ' +
+      'browser rather than Chrome — Samsung Internet, the in-app browser inside a chat or mail ' +
+      'app, or Firefox for Android. Open the page in Chrome 121+ (Android 12 or newer). ' +
+      'On desktop: Chrome/Edge 113+, Firefox 141+ (Windows), or Safari 26+, over https or localhost.';
+  if (m.includes('adapter') || m === '2')
+    return 'This browser has WebGPU, but the device gave back no adapter — the GPU or its driver ' +
+      'is blocked for WebGPU here. In Chrome, opening chrome://flags/#enable-unsafe-webgpu, ' +
+      'switching it on and relaunching usually gets past it. In a private/incognito window, or ' +
+      'with hardware acceleration switched off, an adapter is often refused outright.';
+  return 'WebGPU started but the demo could not set itself up on this device.';
+};
+
+// Show a start-up failure on the page. Without this a demo that cannot reach a GPU throws into
+// the console and leaves a blank canvas behind, which on a phone is indistinguishable from the
+// JavaScript never having run at all.
+export const reportFailure = (e, lib = current()) => {
+  const detail = `${explain(e, lib)} — ${gpuAdvice(e)}`;
+  if (window.TWG_DIAG) window.TWG_DIAG.fail('This demo could not start.', detail);
+  else {                                   // diag.js missing: still say something visible
+    const p = document.createElement('p');
+    p.style.cssText = 'padding:.8rem 1rem;background:#2c2413;color:#f0d79a;font:13px/1.55 sans-serif';
+    p.textContent = 'This demo could not start. ' + detail;
+    document.body.prepend(p);
+  }
+  return detail;
+};
+
+// What the example pages actually call: picker, build import, and `init()` — with any failure
+// turned into something the reader can see and act on. `ctx` is whatever `init()` accepts
+// (a context, a canvas, a selector) or 0 for the compute-only demos.
+export const boot = async (needs = [], base = '.', ctx = 0, opts = {}) => {
+  const { WEBGPU, lib } = await loadLib(needs, base);
+  try {
+    const G = await WEBGPU().init(ctx, opts);
+    return { G, WEBGPU, lib, missing: missing(needs, lib) };
+  } catch (e) {
+    const detail = reportFailure(e, lib);
+    window.__result = { ok: false, msg: 'no webgpu: ' + explain(e, lib) };
+    throw new Error(detail, { cause: e });
+  }
+};

From e82776083b401b1639ecfd2e070395806df1a6cf Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 21 Aug 2026 06:52:47 +0000
Subject: [PATCH 2/2] Resolve the library import against libselect.js, not the
 page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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
---
 README.md                        |  6 +++
 docs/CHANGELOG.md                | 37 ++++++++++++++
 docs/tutorial.html               |  2 +-
 examples/1_hello.html            |  2 +-
 examples/2_compute_readback.html |  2 +-
 examples/3_life.html             |  2 +-
 examples/4_indirect.html         |  2 +-
 examples/5_texture.html          |  2 +-
 examples/6_evolution.html        |  4 +-
 examples/7_particles.html        |  4 +-
 examples/8_heightmap.html        |  2 +-
 libselect.js                     | 20 ++++++--
 package.json                     |  2 +-
 test/paths.test.mjs              | 88 ++++++++++++++++++++++++++++++++
 14 files changed, 158 insertions(+), 17 deletions(-)
 create mode 100644 test/paths.test.mjs

diff --git a/README.md b/README.md
index 6612018..46d9ca4 100644
--- a/README.md
+++ b/README.md
@@ -468,6 +468,12 @@ libselect.js  the ?lib=full|min|tiny picker the pages share
 diag.js     puts an uncaught page error on the screen — see "Browser support" below
 ```
 
+`libselect.js` resolves the build it imports against its own `import.meta.url`, not against the
+page's — that is what a dynamic `import()` specifier is resolved against, and this file sits at
+the repo root beside `src/` and `dist/`. So the demo pages work whether the site is served from
+the root of an origin or from a subdirectory like `/tinywebgpu/`. `npm test` checks that by
+resolving every path on every demo page against a subdirectory mount.
+
 To vendor the library, take `src/tinywebgpu.js` (or a file from `dist/`) and drop it next to your
 HTML — there is nothing else to fetch. The site is served straight from the repo root by GitHub
 Pages, which is why `index.html` and `.nojekyll` live there.
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 14899c7..1ab7b4b 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -4,6 +4,43 @@ All notable changes to TinyWebGPU. Semver; pre-1.0, minor versions may break API
 
 ## Unreleased
 
+**Fixed — the demo pages load their library again when the site is not at the root of its origin**
+
+Every example and the tutorial were broken on <https://lampmaker.github.io/tinywebgpu/>: the page
+rendered, the build picker appeared, and nothing else ran. `libselect.js` imported the library
+with a specifier built from a `base` argument the page passed in — `'../src/tinywebgpu.js'` from
+a page one level down — but a dynamic `import()` resolves its specifier against the *importing
+module's* URL, not the document's, and `libselect.js` sits at the repo root. Served from the root
+of an origin the leading `..` has nowhere to go and is clamped away, so a local
+`python3 -m http.server` resolved it to the right file and never showed the bug. Under GitHub
+Pages the site lives at `/tinywebgpu/`, so the same `..` walked out to the domain root and each
+page 404'd on `https://lampmaker.github.io/src/tinywebgpu.js`.
+
+`loadLib` now resolves the build against `import.meta.url`, which is correct wherever the site is
+mounted and wherever the page sits, and the `base` argument 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/`, which is the case that
+fails — and checks each one against the files on disk. It found two more dead links while it was
+at it: examples 6 and 7 pointed at `../tutorial.html` rather than `../docs/tutorial.html`.
+
+**Added — a failed start-up says so on the page**
+
+Six of the eight examples called `init()` with no `catch`, so a missing `navigator.gpu`, a null
+adapter or the import failure above threw out of the module script into a console — which a phone
+does not have, and which the reader of a demo has no reason to open. The page just sat there
+looking loaded. `diag.js` is a classic, non-module script every demo page now loads first: it
+traps `error` and `unhandledrejection` and puts the failure on screen with an environment report
+(user agent, secure context, adapter, limits). Being classic and ahead of the modules, it also
+catches a module that fails to load or parse — the case above.
+
+`libselect.js` gained `gpuAdvice()`, which separates "this browser has no WebGPU" from "this
+device gave no adapter" and says what to do about each, `reportFailure()`, and `boot()` — picker,
+build import and `init()` in one call, with failures reported. Examples 1–5 and 8 use it; 6 and 7
+keep their own error strip, filled from the shared reporter. The tutorial reports an adapter
+failure once at page level rather than only inside whichever box scrolled into view first.
+`docs/webgpu-check.html` is a library-free page that walks `navigator.gpu` → adapter → device →
+one compiled and drawn triangle and reports where the chain broke, with a copyable report.
+
 **Added — tutorial step 16, "Your own vertex stage, and a depth buffer"**
 
 The tutorial stopped at compute and fullscreen passes; `makeDraw` lived only in a "where to go
diff --git a/docs/tutorial.html b/docs/tutorial.html
index 172fbdd..14d83f3 100644
--- a/docs/tutorial.html
+++ b/docs/tutorial.html
@@ -1443,7 +1443,7 @@ <h3>Where to go next</h3>
     // resize their canvas or upload textures — features the stock tiny build drops — so under
     // tiny those boxes are skipped with a note instead of failing on a missing function.
     import { loadLib, explain, missing, reportFailure, TINY_DROPS } from '../libselect.js';
-    const { WEBGPU, lib } = await loadLib(['read', 'resize', 'texio', 'depth'], '..');
+    const { WEBGPU, lib } = await loadLib(['read', 'resize', 'texio', 'depth']);
 
     // What a box's code can use that the tiny build lacks. Checked against the live editor
     // content on every run, so deleting the offending line makes the box runnable again.
diff --git a/examples/1_hello.html b/examples/1_hello.html
index fc588d0..fa7e9f1 100644
--- a/examples/1_hello.html
+++ b/examples/1_hello.html
@@ -32,7 +32,7 @@
     import { boot } from '../libselect.js';
     // boot = the ?lib=min|tiny picker, the import of that build, and init() — with any
     // start-up failure (no WebGPU, no adapter) put on the page instead of only the console.
-    const { G } = await boot([], '..', document.getElementById('c'));
+    const { G } = await boot([], document.getElementById('c'));
     const quad = G.makeQuad({
       frag: `fn frag(uv: vec2<f32>) -> vec4<f32> {
         return vec4<f32>(0.5 + 0.5 * cos(UB.time + uv.xyx * 4.0 + vec3<f32>(0.0, 2.0, 4.0)), 1.0);
diff --git a/examples/2_compute_readback.html b/examples/2_compute_readback.html
index 5b96c3a..50f4d35 100644
--- a/examples/2_compute_readback.html
+++ b/examples/2_compute_readback.html
@@ -27,7 +27,7 @@
   <script type="module">
     import { boot } from '../libselect.js';
     // No canvas argument: compute-only. boot also reports a failed start-up on the page.
-    const { G } = await boot(['read'], '..');   // ?lib=min|tiny switches the build
+    const { G } = await boot(['read']);   // ?lib=min|tiny switches the build
     const N = 16;
 
     const p = G.makeCompute('', `
diff --git a/examples/3_life.html b/examples/3_life.html
index 5da73fc..fe351be 100644
--- a/examples/3_life.html
+++ b/examples/3_life.html
@@ -35,7 +35,7 @@
 
     const W = 256, H = 256;
     // boot = picker + build import + init(), with a start-up failure shown on the page.
-    const { G } = await boot([], '..', document.getElementById('c'));   // ?lib=min|tiny switches the build
+    const { G } = await boot([], document.getElementById('c'));   // ?lib=min|tiny switches the build
 
     const step = G.makeCompute(`
         fn idx(x: i32, y: i32) -> u32 {
diff --git a/examples/4_indirect.html b/examples/4_indirect.html
index 75cd6e9..f07b70d 100644
--- a/examples/4_indirect.html
+++ b/examples/4_indirect.html
@@ -30,7 +30,7 @@
   <script type="module">
     import { boot } from '../libselect.js';
     // No canvas argument: compute-only. boot also reports a failed start-up on the page.
-    const { G } = await boot(['read'], '..');   // ?lib=min|tiny switches the build
+    const { G } = await boot(['read']);   // ?lib=min|tiny switches the build
     const N = 1000;
 
     // 1) keep multiples of 7, compact them into `survivors`, count atomically
diff --git a/examples/5_texture.html b/examples/5_texture.html
index 031aec1..ec89bc5 100644
--- a/examples/5_texture.html
+++ b/examples/5_texture.html
@@ -44,7 +44,7 @@
   <script type="module">
     import { boot } from '../libselect.js';
     // boot = picker + build import + init(), with a start-up failure shown on the page.
-    const { G } = await boot(['texio', 'read', 'blend'], '..', document.getElementById('c'));
+    const { G } = await boot(['texio', 'read', 'blend'], document.getElementById('c'));
     const log = [];
     let ok = true;
     const check = (name, pass, detail) => { ok &&= pass; log.push(`${pass ? 'ok  ' : 'FAIL'}  ${name}${detail ? '  — ' + detail : ''}`); };
diff --git a/examples/6_evolution.html b/examples/6_evolution.html
index 4934259..5ae49b4 100644
--- a/examples/6_evolution.html
+++ b/examples/6_evolution.html
@@ -101,12 +101,12 @@ <h1>Differential evolution</h1>
     <p id="status">starting…</p>
     <p>The objective is one WGSL function — replace <code>objStep</code>/<code>objDone</code> with
       your own and the rest of the machinery is unchanged.
-      <a href="../tutorial.html#atomics">The tutorial covers the pieces.</a></p>
+      <a href="../docs/tutorial.html#atomics">The tutorial covers the pieces.</a></p>
   </main>
 
   <script type="module">
     import { loadLib, reportFailure, explain } from '../libselect.js';
-    const { WEBGPU, lib } = await loadLib(['read'], '..');   // ?lib=min|tiny switches the build
+    const { WEBGPU, lib } = await loadLib(['read']);   // ?lib=min|tiny switches the build
 
     const canvas = document.getElementById('c');
     const el = id => document.getElementById(id);
diff --git a/examples/7_particles.html b/examples/7_particles.html
index 984c837..54f2e84 100644
--- a/examples/7_particles.html
+++ b/examples/7_particles.html
@@ -75,12 +75,12 @@ <h1>Particles</h1>
     </div>
     <p class="stats" id="stats">starting…</p>
     <p>Each particle is 16 bytes — position and velocity — and never leaves the GPU.
-      <a href="../tutorial.html#particles">The tutorial builds this one up step by step.</a></p>
+      <a href="../docs/tutorial.html#particles">The tutorial builds this one up step by step.</a></p>
   </main>
 
   <script type="module">
     import { loadLib, reportFailure, explain } from '../libselect.js';
-    const { WEBGPU, lib } = await loadLib(['read', 'resize'], '..');   // ?lib=min|tiny switches the build
+    const { WEBGPU, lib } = await loadLib(['read', 'resize']);   // ?lib=min|tiny switches the build
 
     const canvas = document.getElementById('c');
     const el = id => document.getElementById(id);
diff --git a/examples/8_heightmap.html b/examples/8_heightmap.html
index 3033c6a..6ed7629 100644
--- a/examples/8_heightmap.html
+++ b/examples/8_heightmap.html
@@ -44,7 +44,7 @@
 
     const canvas = document.getElementById('c');
     // boot = picker + build import + init(), with a start-up failure shown on the page.
-    const { G } = await boot(['read', 'resize', 'depth'], '..', canvas);   // ?lib=min|tiny switches the build
+    const { G } = await boot(['read', 'resize', 'depth'], canvas);   // ?lib=min|tiny switches the build
 
     // One f32 per grid vertex. The compute pass writes it read_write; the vertex stage reads it
     // read-only. Same GPUBuffer, two pipelines, two address spaces — see `readOnly` below.
diff --git a/libselect.js b/libselect.js
index 8d3609f..b53a621 100644
--- a/libselect.js
+++ b/libselect.js
@@ -146,10 +146,20 @@ export const initPicker = (needs = []) => {
 };
 
 // One call for the example pages: draw the picker and import the chosen build.
-// `base` is the path from the page to the repo root (pages one level down pass '..').
-export const loadLib = async (needs = [], base = '.') => {
+//
+// The path is resolved against `import.meta.url` — this module's own URL — and not against the
+// page's, because that is what a dynamic import() specifier is resolved against. This file sits
+// at the repo root beside src/ and dist/, so the build files are always one plain step away from
+// it, wherever the page doing the importing happens to live.
+//
+// It used to take a `base` argument and build a page-relative specifier ('../src/tinywebgpu.js'
+// from a page one level down). That was wrong, and only looked right when the site was served
+// from the root of its origin, where a leading '..' has nowhere to go and is clamped away. Under
+// GitHub Pages the site lives at /tinywebgpu/, so the '..' resolved out to the domain root and
+// every demo page 404'd on its own library.
+export const loadLib = async (needs = []) => {
   const lib = initPicker(needs);
-  const { WEBGPU } = await import(`${base}/${BUILDS[lib].file}`);
+  const { WEBGPU } = await import(new URL(BUILDS[lib].file, import.meta.url).href);
   return { WEBGPU, lib, missing: missing(needs, lib) };
 };
 
@@ -189,8 +199,8 @@ export const reportFailure = (e, lib = current()) => {
 // What the example pages actually call: picker, build import, and `init()` — with any failure
 // turned into something the reader can see and act on. `ctx` is whatever `init()` accepts
 // (a context, a canvas, a selector) or 0 for the compute-only demos.
-export const boot = async (needs = [], base = '.', ctx = 0, opts = {}) => {
-  const { WEBGPU, lib } = await loadLib(needs, base);
+export const boot = async (needs = [], ctx = 0, opts = {}) => {
+  const { WEBGPU, lib } = await loadLib(needs);
   try {
     const G = await WEBGPU().init(ctx, opts);
     return { G, WEBGPU, lib, missing: missing(needs, lib) };
diff --git a/package.json b/package.json
index 628bfab..a6a2444 100644
--- a/package.json
+++ b/package.json
@@ -19,7 +19,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node test/layout.test.mjs && node test/frame.test.mjs",
+    "test": "node test/paths.test.mjs && node test/layout.test.mjs && node test/frame.test.mjs",
     "test:min": "TWG_ENTRY=../dist/tinywebgpu.min.js node test/layout.test.mjs && TWG_ENTRY=../dist/tinywebgpu.min.js node test/frame.test.mjs",
     "test:tiny": "node tools/build-min.mjs tiny --with=msg,texio,read,show,pingpong,blend,depth,mips,staging,aliases --out=test/.tiny-full.js && TWG_ENTRY=./.tiny-full.js node test/layout.test.mjs && node tools/build-min.mjs tiny --out=test/.tiny-bare.js && TWG_ENTRY=./.tiny-bare.js node test/tiny.test.mjs",
     "test:rename": "node tools/build-min.mjs tiny --with=msg --rename --out=test/.tiny-renamed.js && TWG_ENTRY=./.tiny-renamed.js node test/rename.test.mjs",
diff --git a/test/paths.test.mjs b/test/paths.test.mjs
new file mode 100644
index 0000000..86dc8aa
--- /dev/null
+++ b/test/paths.test.mjs
@@ -0,0 +1,88 @@
+// Every path the demo pages reference has to resolve to a file that exists, and has to stay
+// inside the repo.
+//
+// This exists because of a bug that a root-served dev server cannot show you. libselect.js used
+// to import the library with a page-relative specifier — '../src/tinywebgpu.js' from a page one
+// level down — but a dynamic import() resolves its specifier against the importing module's URL,
+// which is libselect.js at the repo root, not the page's. Served from the root of an origin the
+// stray '..' has nowhere to go and is clamped away, so `python3 -m http.server` was happy. Served
+// from a subdirectory, as GitHub Pages serves this site at /tinywebgpu/, the same '..' walked out
+// to the domain root and every example and the tutorial 404'd on their own library: the page
+// loaded, nothing ran, and nothing said why.
+//
+// So the rule checked here is "resolve it the way the browser will, then look on disk for it",
+// and the pages are checked as if served from a subdirectory, which is the case that fails.
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import assert from 'node:assert/strict';
+import { BUILDS } from '../libselect.js';
+
+const root = new URL('../', import.meta.url);
+const pages = [
+  'index.html',
+  'docs/tutorial.html',
+  'docs/webgpu-check.html',
+  ...readdirSync(fileURLToPath(new URL('examples/', root))).filter(f => f.endsWith('.html'))
+    .map(f => 'examples/' + f),
+];
+
+// Mounting the site under a subdirectory is what separates a specifier that only looks right from
+// one that is right: at the origin root a leading '..' is silently clamped, and here it is not.
+const MOUNT = 'https://example.test/tinywebgpu/';
+const inside = url => url.href.startsWith(MOUNT);
+
+const MOUNT_PATH = new URL(MOUNT).pathname;               // '/tinywebgpu/'
+const onDisk = url => new URL(decodeURIComponent(url.pathname).slice(MOUNT_PATH.length), root);
+
+let checked = 0, failed = 0;
+const fail = (what, spec, base, url, why) => {
+  failed++;
+  console.log(`  FAIL  ${what}\n        "${spec}" from ${base.href}\n        → ${url.href} (${why})`);
+};
+
+const check = (what, spec, base) => {
+  // Absolute URLs, protocol-relative and bare fragments are somebody else's problem.
+  if (/^[a-z][a-z0-9+.-]*:|^\/\/|^#/i.test(spec)) return;
+  checked++;
+  const url = new URL(spec, base);
+  if (!inside(url)) return fail(what, spec, base, url, 'outside the site');
+  const file = onDisk(url);
+  if (!existsSync(fileURLToPath(file))) return fail(what, spec, base, url, 'no such file');
+  // A link into the tutorial is only as good as the heading it points at.
+  if (url.hash.length > 1 && file.pathname.endsWith('.html')) {
+    const target = readFileSync(fileURLToPath(file), 'utf8');
+    if (!target.includes(`id="${url.hash.slice(1)}"`))
+      return fail(what, spec, base, url, `no id="${url.hash.slice(1)}" in that page`);
+  }
+};
+
+console.log(`resolving demo-page paths as if served from ${MOUNT}\n`);
+
+for (const page of pages) {
+  const src = readFileSync(fileURLToPath(new URL(page, root)), 'utf8');
+  const pageUrl = new URL(page, MOUNT);
+
+  // src=/href= on the page resolve against the page itself.
+  for (const m of src.matchAll(/\s(?:src|href)="([^"]+)"/g)) check(page, m[1], pageUrl);
+
+  // A static import inside an inline module also resolves against the page.
+  for (const mod of src.matchAll(/<script type="module">([\s\S]*?)<\/script>/g))
+    for (const m of mod[1].matchAll(/\bfrom\s+['"]([^'"]+)['"]/g)) check(page, m[1], pageUrl);
+}
+
+// And the builds libselect.js reaches for resolve against libselect.js, wherever a page sits.
+const libselect = new URL('libselect.js', MOUNT);
+for (const b of Object.values(BUILDS)) check('libselect.js BUILDS', b.file, libselect);
+
+// The invariant above only holds while the import is anchored to this module's own URL. Nothing
+// else in the file's behaviour would change if that anchor were dropped, and no root-served page
+// would notice, so say so here rather than finding out on a deployed site again.
+const source = readFileSync(fileURLToPath(new URL('libselect.js', root)), 'utf8');
+assert.match(source, /await import\(new URL\([^)]*import\.meta\.url\)/,
+  'loadLib must resolve the build path against import.meta.url, not against the page');
+console.log('  ok    loadLib anchors its dynamic import to import.meta.url');
+
+console.log(`\n${checked} paths checked`);
+if (failed) { console.error(`${failed} unresolvable`); process.exit(1); }
+console.log('all demo-page paths resolve');