From 40a0eaf6d98c61f54f8efcba02ba805e7d77dd14 Mon Sep 17 00:00:00 2001
From: Daniel McCoy Stephenson <dmccoystephenson@gmail.com>
Date: Wed, 28 Oct 2026 01:54:35 -0600
Subject: [PATCH 1/2] Load the browser page behind Strata's loading shell

The page used to show "Loading env-lib-cpp on Strata..." while the engine
downloaded. It now loads behind the Strata web kit's loading shell
(strata-loader.js, vendored at Strata 901e6c9 with its PIN, SHA256SUMS,
LICENSE and update.sh): the /play trailer's first frame as a blurred
backdrop, in the page's colours, and byte-accurate progress with the size.
The loader streams envlib-strata.wasm and hands the bytes to the engine, so
nothing downloads twice.

When the view can't run (no WebGL 2, the renderer fails, the engine stops,
a lost WebGL context does not come back) the shell plays the trailer and
says why; under prefers-reduced-motion it shows the still. A device drawing
under 12 frames a second is offered the clip without losing the live view;
that watch is skipped in automated browsers and ?bench runs.

strata/web/strata-boot.js bridges this classic (non-MODULARIZE) build to
the loader: emcc's script tag is kept inert in a template, the bridge starts
it, and the engine waits in Module.instantiateWasm for the loader's bytes.
After each link strata/web/strata_page.cmake puts the loader and the bridge
inline in the page, so the site is still the same four files, and stamps
the download's size, since the arcade compresses on the fly with no
Content-Length. The smoke test now checks that the shell finishes, and that
without WebGL 2 it says why and downloads nothing of the engine.

drafted by Claude on behalf of Daniel Stephenson

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LYNeuo5Ry76i84tz6WXQSE
---
 docs/STRATA.md                         |  20 ++
 strata/CMakeLists.txt                  |  10 +
 strata/web/shell.html                  |  29 ++-
 strata/web/smoke/smoke.cjs             |  31 +++
 strata/web/strata-boot.js              | 180 +++++++++++++
 strata/web/strata-kit/LICENSE          |  21 ++
 strata/web/strata-kit/PIN              |   1 +
 strata/web/strata-kit/SHA256SUMS       |   2 +
 strata/web/strata-kit/strata-loader.js | 341 +++++++++++++++++++++++++
 strata/web/strata-kit/update.sh        |  19 ++
 strata/web/strata_page.cmake           |  47 ++++
 11 files changed, 699 insertions(+), 2 deletions(-)
 create mode 100644 strata/web/strata-boot.js
 create mode 100644 strata/web/strata-kit/LICENSE
 create mode 100644 strata/web/strata-kit/PIN
 create mode 100644 strata/web/strata-kit/SHA256SUMS
 create mode 100644 strata/web/strata-kit/strata-loader.js
 create mode 100755 strata/web/strata-kit/update.sh
 create mode 100644 strata/web/strata_page.cmake

diff --git a/docs/STRATA.md b/docs/STRATA.md
index ce20091..27b7a29 100644
--- a/docs/STRATA.md
+++ b/docs/STRATA.md
@@ -155,6 +155,26 @@ text. `?bench=30` runs for 30 seconds. Nothing is sent anywhere.
 CI that a run finishes and shows its card on both profiles (it keeps no
 numbers: headless Chromium draws on the CPU).
 
+### The loading shell
+
+The page loads behind the Strata web kit's loading shell
+(`strata/web/strata-kit/strata-loader.js`, vendored from Strata at the commit in
+`strata/web/strata-kit/PIN`; `strata/web/strata-kit/update.sh <sha>` re-vendors it). It shows
+the trailer's first frame (the one on <https://danielstephenson.dev/play>) as a blurred backdrop and real progress with the size ("0.5 of 1.3 MB"). The loader streams
+the `.wasm` and hands its bytes to the engine, so nothing downloads twice. If
+env-lib-cpp can't run (no WebGL 2, the renderer fails, the engine stops, a lost
+WebGL context does not come back), the shell says why, and plays the trailer instead (the still under `prefers-reduced-motion`).
+A device that draws under 12 frames a second is offered the clip without
+losing the game (not in automated browsers or `?bench` runs).
+
+`strata/web/strata-boot.js` bridges this classic (non-`MODULARIZE`) build to the
+loader: emcc's script tag sits inert in `<template id="strata-glue">`, the
+bridge starts it, and the engine waits in `Module.instantiateWasm` for the
+loader's bytes. After each link, `strata/web/strata_page.cmake` puts the loader and
+the bridge inline in the page (so the site is still the same four files) and stamps the download's size on the
+template, because the arcade compresses on the fly and sends no
+`Content-Length`.
+
 ## Tests
 
 - `[view]`: the copy, the no-pointer rule (an entity freed after `sync()`), an
diff --git a/strata/CMakeLists.txt b/strata/CMakeLists.txt
index 98f450c..da99d93 100644
--- a/strata/CMakeLists.txt
+++ b/strata/CMakeLists.txt
@@ -103,6 +103,16 @@ else()
         -sEXPORTED_RUNTIME_METHODS=ccall,cwrap
         "--shell-file=${CMAKE_CURRENT_SOURCE_DIR}/web/shell.html")
     set_property(TARGET envlib_strata_web APPEND PROPERTY LINK_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/web/shell.html")
+    # The loading shell (web/strata-kit, vendored from Strata) and its bridge go
+    # inline into the page, with the download's size (web/strata_page.cmake).
+    set_property(TARGET envlib_strata_web APPEND PROPERTY LINK_DEPENDS
+      "${CMAKE_CURRENT_SOURCE_DIR}/web/strata-kit/strata-loader.js"
+      "${CMAKE_CURRENT_SOURCE_DIR}/web/strata-boot.js")
+    add_custom_command(TARGET envlib_strata_web POST_BUILD
+      COMMAND "${CMAKE_COMMAND}" "-DHTML=$<TARGET_FILE:envlib_strata_web>"
+              "-DWASM=$<TARGET_FILE_DIR:envlib_strata_web>/$<TARGET_FILE_BASE_NAME:envlib_strata_web>.wasm"
+              "-DWEB=${CMAKE_CURRENT_SOURCE_DIR}/web" -P "${CMAKE_CURRENT_SOURCE_DIR}/web/strata_page.cmake"
+      VERBATIM)
     # The page's ?bench mode (web/bench.js) is served next to it.
     configure_file(web/bench.js "${CMAKE_CURRENT_BINARY_DIR}/bench.js" COPYONLY)
 endif()
diff --git a/strata/web/shell.html b/strata/web/shell.html
index 1db3e60..1621895 100644
--- a/strata/web/shell.html
+++ b/strata/web/shell.html
@@ -9,6 +9,8 @@
   :root {
     --bg: #090b12; --panel: rgba(16, 19, 30, 0.94); --line: #2a3046; --text: #e6eaf2; --dim: #9aa3b8;
     --accent: #ffc23a; --btn: #1a1f30; --btn-on: #3a3118;
+    /* The loading shell (web/strata-kit/strata-loader.js) in the page's colours. */
+    --sk-loader-bg: var(--bg); --sk-loader-fg: var(--text); --sk-loader-panel: var(--panel); --sk-loader-accent: var(--accent);
   }
   * { box-sizing: border-box; }
   html, body { margin: 0; height: 100%; background: var(--bg); color: var(--text);
@@ -79,7 +81,7 @@
   <button id="hud" data-key="43" aria-pressed="true" title="Show or hide the text on the view (Tab)">HUD</button>
 </div>
 
-<div id="loading">Loading env-lib-cpp on Strata&hellip;</div>
+<div id="loading" style="display: none"></div>
 
 <!-- ?bench: a scripted frame-rate run (web/bench.js); it must load before the engine. -->
 <script src="bench.js"></script>
@@ -149,6 +151,7 @@
     printErr: (t) => console.warn(t),
     onRendererFailed: (why) => {
       loading.textContent = 'This browser could not start WebGL 2 (' + why + ').';
+      StrataLoader.fallback('engine', 'This browser could not start WebGL 2 (' + why + ').');
     },
     onViewerReady: () => {
       api = {
@@ -163,6 +166,7 @@
       };
       window.envlib = api;
       loading.style.display = 'none';
+      StrataBoot.ready();
       fit();
       let start = 0;
       try { start = Number(localStorage.getItem('envlib.world')) || 0; } catch (e) {}
@@ -213,6 +217,27 @@
   window.addEventListener('resize', fit);
   new ResizeObserver(fit).observe(document.getElementById('stage'));
 </script>
-{{{ SCRIPT }}}
+<!-- emcc's script tag, kept inert: web/strata-boot.js starts it behind the
+     loading shell. data-bytes is the download's size, stamped by the build. -->
+<template id="strata-glue" data-bytes="0">{{{ SCRIPT }}}</template>
+<!-- The loading shell, vendored from Strata, and its bridge to this build; the
+     build puts both inline (web/strata_page.cmake). -->
+<script src="strata-kit/strata-loader.js"></script>
+<script src="strata-boot.js"></script>
+<script>
+  // The loading shell: the trailer's first frame behind real progress, and the
+  // trailer itself, with the reason, if the live view can't run here. The
+  // media are the /play trailer.
+  StrataBoot.start({
+    wasm: 'envlib-strata.wasm',
+    title: 'env-lib-cpp',
+    poster: 'https://danielstephenson.dev/trailers/env-lib-cpp.jpg',
+    posterAlt: 'env-lib-cpp: a grid world and its entities',
+    trailer: { webm: 'https://danielstephenson.dev/trailers/env-lib-cpp.webm', mp4: 'https://danielstephenson.dev/trailers/env-lib-cpp.mp4' },
+    trailerLabel: 'A recorded clip of env-lib-cpp',
+    fallback: { href: 'https://danielstephenson.dev/play', text: 'More games' },
+    canvas: document.getElementById('canvas')
+  }).catch(function () {});  // the loading shell already shows why
+</script>
 </body>
 </html>
diff --git a/strata/web/smoke/smoke.cjs b/strata/web/smoke/smoke.cjs
index 3bf333e..e7452b8 100644
--- a/strata/web/smoke/smoke.cjs
+++ b/strata/web/smoke/smoke.cjs
@@ -167,6 +167,37 @@ const worlds = [
   if (s.pickX < 0 || direct.pickX < 0 || Math.abs(s.pickX - direct.pickX) > 1 || Math.abs(s.pickY - direct.pickY) > 1)
     await fail(`a ${phone ? 'tap' : 'click'} picked (${s.pickX}, ${s.pickY}), but that point is (${direct.pickX}, ${direct.pickY})`);
 
+  // The loading shell finished; and without WebGL 2 it shows the trailer (or
+  // its still) and says why, and the engine never downloads.
+  {
+    await page.waitForFunction(() => { const r = document.querySelector('.sk-loader'); return r && r.hidden; }, null, { timeout: 10000 }).catch(() => {});
+    const shell = await page.evaluate(() => {
+      const r = document.querySelector('.sk-loader');
+      return { hidden: !!(r && r.hidden), state: window.StrataLoader && StrataLoader.state };
+    });
+    if (!shell.hidden || shell.state !== 'done') await fail('the loading shell did not finish: ' + JSON.stringify(shell));
+    console.log('ok: the loading shell showed and is gone');
+    const bare = await browser.newContext({ ...base, userAgent: (base.userAgent || 'Mozilla/5.0') + ' envlib-smoke headless' });
+    await bare.addInitScript(() => {
+      const get = HTMLCanvasElement.prototype.getContext;
+      HTMLCanvasElement.prototype.getContext = function (t, o) { return t === 'webgl2' ? null : get.call(this, t, o); };
+    });
+    const p2 = await bare.newPage();
+    const engine = [];
+    p2.on('request', (r) => { if (/envlib-strata\.(wasm|js)$/.test(r.url())) engine.push(r.url()); });
+    await p2.goto(url, { waitUntil: 'commit' });
+    await p2.waitForFunction(() => window.StrataLoader && StrataLoader.state === 'fallback', null, { timeout: 30000 });
+    const fb = await p2.evaluate(() => {
+      const r = document.querySelector('.sk-loader');
+      return { text: r.innerText, media: !!r.querySelector('video, img'), wide: document.documentElement.scrollWidth > innerWidth };
+    });
+    await p2.screenshot({ path: path.join(outDir, 'no-webgl2.png') });
+    if (!/WebGL 2/.test(fb.text) || fb.wide) await fail('without WebGL 2 the shell did not say why: ' + JSON.stringify(fb));
+    if (engine.length) await fail('without WebGL 2 the engine still downloaded: ' + engine.join(', '));
+    console.log('ok: without WebGL 2 the shell ' + (fb.media ? 'shows the trailer and ' : '') + 'says why, and nothing of the engine downloads');
+    await bare.close();
+  }
+
   if (errors.length) await fail('page errors: ' + errors.join(' | '));
   await page.screenshot({ path: path.join(outDir, 'page.png') });
   await browser.close();
diff --git a/strata/web/strata-boot.js b/strata/web/strata-boot.js
new file mode 100644
index 0000000..66ed372
--- /dev/null
+++ b/strata/web/strata-boot.js
@@ -0,0 +1,180 @@
+/* strata-boot.js: starts this page's Emscripten build behind the Strata web
+   kit's loading shell (strata-kit/strata-loader.js, vendored at a pinned
+   Strata commit).
+
+   The loader expects a MODULARIZE build (a factory it calls with wasmBinary).
+   This build is a classic one: a global Module and the glue script that
+   emcc writes for {{{ SCRIPT }}}, which the shell keeps inside
+   <template id="strata-glue"> so that it does not run by itself. This file
+   bridges the two:
+
+   - the glue starts at once, as before, so a --preload-file data package
+     downloads alongside the engine; it waits in Module.instantiateWasm;
+   - the loader fetches the .wasm as a stream, shows its bytes, and hands
+     them to the factory below, which instantiates them: nothing downloads
+     twice;
+   - an abort, a lost WebGL context that does not come back, and (outside
+     automated browsers and ?bench) a device drawing under 12 frames a
+     second all end in the loader's fallback: the trailer or the poster,
+     with the reason.
+
+     StrataBoot.start({
+       wasm: "index.wasm", title: "...",        // the loader's options, plus:
+       canvas: document.getElementById("canvas"),
+     });
+     // when the first frame is up (the page's own "ready"):
+     StrataBoot.ready();
+
+   `bytes` defaults to data-bytes on the template, which the build stamps
+   (web/strata_page.cmake): the .wasm plus any data package, since the arcade
+   compresses on the fly and sends no Content-Length.
+
+   MIT licensed, as this repository. */
+(function () {
+  "use strict";
+
+  const FACTORY = "__strataBootFactory";
+  let opts = {}, running = false, settled = false, failNow = null;
+  let wasmLen = null, data = null;
+
+  // A data package downloads alongside the .wasm. The loader counts the .wasm;
+  // once it has, the bar goes on with the package's bytes on top, against the
+  // page's stated size (both together). This writes into the loader's own
+  // overlay (.sk-bar, .sk-fill, .sk-size, as strata-loader.js at PIN builds it).
+  function mb(n) { return (n / 1048576).toFixed(n < 10485760 ? 1 : 0); }
+  function showData() {
+    if (wasmLen == null || !data || StrataLoader.state !== "loading") return;
+    const bar = document.querySelector(".sk-loader .sk-bar");
+    if (!bar) return;
+    const stated = opts.bytes || 0;
+    const sane = data.got <= data.total;  // a compressed Content-Length is smaller than the bytes read
+    const total = sane ? Math.max(stated, wasmLen + data.total) : 0;
+    const got = wasmLen + data.got;
+    const size = document.querySelector(".sk-loader .sk-size");
+    if (total) {
+      const pct = Math.min(100, Math.round(got / total * 100));
+      bar.classList.remove("sk-indeterminate");
+      bar.querySelector(".sk-fill").style.width = pct + "%";
+      bar.setAttribute("aria-valuenow", String(pct));
+      if (size) size.textContent = `${mb(Math.min(got, total))} of ${mb(total)} MB`;
+    } else if (size) {
+      size.textContent = `${mb(got)} MB`;
+    }
+  }
+
+  // The glue's src, from the inert copy of emcc's script tag.
+  function glueSrc() {
+    const t = document.getElementById("strata-glue");
+    const s = t && t.content && t.content.querySelector("script[src]");
+    return s ? s.getAttribute("src") : null;
+  }
+
+  function engineFailed(message) {
+    if (settled) return;
+    if (failNow) { failNow(new Error(message)); return; }  // still loading: the loader shows it
+    settled = true;
+    StrataLoader.fallback("engine", message ? `The live view's renderer stopped. (${message})` : undefined);
+  }
+
+  // Links on the fallback leave a framed page (the arcade embeds games) as a whole.
+  function topLinks() {
+    document.querySelectorAll(".sk-loader a[href]").forEach((a) => { a.target = "_top"; a.rel = "noopener"; });
+  }
+
+  function watchContext(canvas) {
+    if (!canvas) return;
+    let timer = null;
+    canvas.addEventListener("webglcontextlost", () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => { if (!settled) { settled = true; StrataLoader.fallback("context-lost"); } }, 3000);
+    });
+    canvas.addEventListener("webglcontextrestored", () => clearTimeout(timer));
+  }
+
+  // Under 12 frames a second over 8 s of visible time, 3 s after the first
+  // frame: offer the clip without taking the live view away. Automated
+  // browsers (software GL) and ?bench runs are left alone.
+  function watchSpeed() {
+    if (navigator.webdriver || /[?&]bench\b/.test(location.search)) return;
+    let frames = 0, visibleMs = 0, last = 0;
+    document.addEventListener("visibilitychange", () => { last = 0; });
+    function step(now) {
+      if (settled) return;
+      if (last && !document.hidden) { const dt = now - last; if (dt < 1000) { visibleMs += dt; frames++; } }
+      last = now;
+      if (visibleMs < 8000) { requestAnimationFrame(step); return; }
+      if (frames * 1000 / visibleMs < 12) StrataLoader.slow();
+    }
+    setTimeout(() => requestAnimationFrame(step), 3000);
+  }
+
+  function start(o) {
+    opts = Object.assign({}, o);
+    const src = glueSrc();
+    if (!src) throw new Error("strata-boot: put <template id=\"strata-glue\"> with emcc's script tag before this call");
+    const M = window.Module = window.Module || {};
+    const userAbort = M.onAbort;
+    M.onAbort = (what) => { if (userAbort) userAbort(what); engineFailed(String(what || "aborted")); };
+    const userFallback = opts.onFallback;
+    opts.onFallback = (code) => { settled = true; topLinks(); if (userFallback) userFallback(code); };
+
+    // The glue asks for its instance here; the factory below answers once
+    // the loader has the bytes. The factory settles with the instantiation.
+    let give;
+    const instance = new Promise((r) => { give = r; });
+    M.instantiateWasm = (imports, ok) => {
+      instance.then((b) => WebAssembly.instantiate(b, imports))
+        .then((r) => { failNow = null; ok(r.instance, r.module); if (resolveFactory) resolveFactory(M); },
+              (e) => engineFailed(String(e && e.message || e)));
+      return {};
+    };
+    // A --preload-file package reports through setStatus("... (got/total)").
+    const userStatus = M.setStatus;
+    M.setStatus = (text) => {
+      if (userStatus) userStatus(text);
+      const m = /\((\d+)\/(\d+)\)/.exec(text || "");
+      if (m) { data = {got: +m[1], total: +m[2]}; showData(); }
+    };
+
+    let resolveFactory = null;
+    window[FACTORY] = (args) => new Promise((resolve, reject) => {
+      failNow = reject;
+      resolveFactory = resolve;
+      wasmLen = args.wasmBinary.byteLength;
+      showData();
+      give(args.wasmBinary);
+    });
+
+    // No WebGL 2: the loader shows the fallback before anything downloads.
+    if (StrataLoader.hasWebGL2()) {
+      const s = document.createElement("script");
+      s.src = src;
+      s.async = true;
+      s.onerror = () => {
+        if (settled) return;
+        settled = true;
+        StrataLoader.fallback("network", `The live view didn't download. (${src})`);
+      };
+      document.body.appendChild(s);
+    }
+    running = true;
+    watchContext(opts.canvas);
+    if (!opts.bytes) {
+      const t = document.getElementById("strata-glue");
+      const n = t ? parseInt(t.getAttribute("data-bytes") || "", 10) : 0;
+      if (n > 0) opts.bytes = n;
+    }
+    const loadOpts = Object.assign({}, opts, {script: src, factory: FACTORY});
+    delete loadOpts.canvas;
+    return StrataLoader.load(loadOpts).then((mod) => mod, (e) => { settled = true; throw e; });
+  }
+
+  // The first frame is up: fade the shell out and start watching the speed.
+  function ready() {
+    if (!running || settled) return;
+    StrataLoader.done();
+    watchSpeed();
+  }
+
+  window.StrataBoot = {start, ready};
+})();
diff --git a/strata/web/strata-kit/LICENSE b/strata/web/strata-kit/LICENSE
new file mode 100644
index 0000000..f8d146f
--- /dev/null
+++ b/strata/web/strata-kit/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel McCoy Stephenson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/strata/web/strata-kit/PIN b/strata/web/strata-kit/PIN
new file mode 100644
index 0000000..28beecb
--- /dev/null
+++ b/strata/web/strata-kit/PIN
@@ -0,0 +1 @@
+901e6c97bc70c86c0e7dfbf857bb87ec405e0164
diff --git a/strata/web/strata-kit/SHA256SUMS b/strata/web/strata-kit/SHA256SUMS
new file mode 100644
index 0000000..a5be9e6
--- /dev/null
+++ b/strata/web/strata-kit/SHA256SUMS
@@ -0,0 +1,2 @@
+7da2a43f932f63e5ae86273a7675b55180dbde4d61dc6e0c5fcd048026879946  strata-loader.js
+8e3fc647b4775773eabc147e564ffbddd0653b252eff96c5432213ee362798df  LICENSE
diff --git a/strata/web/strata-kit/strata-loader.js b/strata/web/strata-kit/strata-loader.js
new file mode 100644
index 0000000..f7d1d46
--- /dev/null
+++ b/strata/web/strata-kit/strata-loader.js
@@ -0,0 +1,341 @@
+/* strata-loader.js: the loading shell for a Strata page.
+
+   Part of the Strata web kit (docs/WEB.md, "The web kit"). A classic script
+   with no dependencies. It defines window.StrataLoader.
+
+     const mod = await StrataLoader.load({
+       script: "/3d/scene.js",          // the Emscripten glue (MODULARIZE)
+       factory: "createScene",          // its EXPORT_NAME
+       wasm: "/3d/scene.wasm",
+       bytes: 1002049,                  // optional: the size, stated before the fetch answers
+       title: "the 3D garden",          // "Loading the 3D garden"
+       poster: "/3d/poster.jpg",        // optional backdrop, blurred while loading
+       trailer: {webm: "...", mp4: "..."},  // optional: played when the page can't run live
+       fallback: {href: "/", text: "Open the 2D dashboard"},  // optional link on every fallback
+       gate: false,                     // true: wait for a tap when the device asks for less
+     });
+     // ... create the scene with StrataKit.create({module: mod, ...}), then:
+     StrataLoader.done();
+
+   What it shows, in an overlay it adds to the page (class sk-loader):
+
+   - the poster (if any) as a blurred backdrop, and the title;
+   - real progress: the .wasm is fetched as a stream and its bytes counted
+     against Content-Length (or `bytes`), shown as "1.2 of 3.4 MB", with
+     role=progressbar. The counted bytes are handed to the module as
+     wasmBinary, so nothing is downloaded twice. The glue script loads at the
+     same time;
+   - the fallback, instead of a blank page: when WebGL 2 is missing, when the
+     engine fails, when a lost context does not come back, or when the device
+     is too slow even at the lowest tier (StrataLoader.slow()): the trailer
+     (muted, looping, with controls; a still poster under reduced motion), or
+     the poster, with the reason in words and the fallback link.
+
+   With gate: true, a device that asks for less (prefers-reduced-motion,
+   Save-Data, or under 4 GB of device memory where the browser says) gets the
+   poster and a "Start" button instead of an automatic download.
+
+   load() resolves with the module, or rejects with an Error whose `code` is
+   "no-webgl2", "network" or "engine" after the fallback is already showing.
+
+   Colours follow the page through CSS custom properties on :root (or any
+   ancestor): --sk-loader-bg, --sk-loader-fg, --sk-loader-panel and
+   --sk-loader-accent.
+
+   MIT licensed, as Strata. */
+(function () {
+  "use strict";
+
+  const CSS = `
+.sk-loader{position:fixed;inset:0;z-index:20;display:grid;place-items:center;padding:16px;
+  background:var(--sk-loader-bg,#101712);color:var(--sk-loader-fg,#e3ece4);
+  font:14px/1.4 system-ui,-apple-system,"Segoe UI",sans-serif;transition:opacity .3s}
+.sk-loader[hidden]{display:none}
+.sk-loader.sk-done{opacity:0;pointer-events:none}
+.sk-loader .sk-backdrop{position:absolute;inset:0;background-size:cover;background-position:center;
+  filter:blur(14px) brightness(.55);transform:scale(1.06)}
+.sk-loader .sk-media{position:absolute;inset:0;width:100%;height:100%;object-fit:cover}
+.sk-loader .sk-box{position:relative;box-sizing:border-box;max-width:min(420px,100%);width:100%;text-align:center;
+  background:var(--sk-loader-panel,rgba(0,0,0,.45));border-radius:12px;padding:16px 18px;
+  -webkit-backdrop-filter:blur(4px);backdrop-filter:blur(4px)}
+.sk-loader.sk-fallback .sk-box{position:absolute;left:16px;right:16px;bottom:max(16px,env(safe-area-inset-bottom));
+  width:auto;max-width:420px;margin:0 auto}
+.sk-loader .sk-title{font-weight:600;margin:0 0 8px}
+.sk-loader .sk-bar{height:8px;border-radius:4px;background:rgba(255,255,255,.18);overflow:hidden}
+.sk-loader .sk-fill{height:100%;width:0;background:var(--sk-loader-accent,#7fd082);transition:width .15s}
+.sk-loader .sk-bar.sk-indeterminate .sk-fill{width:30%;animation:sk-slide 1.2s ease-in-out infinite}
+@keyframes sk-slide{from{margin-left:-30%}to{margin-left:100%}}
+.sk-loader .sk-size{margin-top:6px;font-size:12px;opacity:.85;font-variant-numeric:tabular-nums}
+.sk-loader .sk-msg{margin:0 0 8px}
+.sk-loader a{color:var(--sk-loader-accent,#7fd082)}
+.sk-loader button{font:inherit;min-height:44px;min-width:44px;padding:8px 18px;border-radius:8px;border:0;
+  background:var(--sk-loader-accent,#7fd082);color:#0b130c;font-weight:600;cursor:pointer}
+@media (prefers-reduced-motion: reduce){.sk-loader,.sk-loader .sk-fill{transition:none}
+  .sk-loader .sk-bar.sk-indeterminate .sk-fill{animation:none;width:100%;opacity:.5}}`;
+
+  let root = null, opts = {}, state = "idle";
+
+  function el(tag, cls, text) {
+    const e = document.createElement(tag);
+    if (cls) e.className = cls;
+    if (text != null) e.textContent = text;
+    return e;
+  }
+  function mb(n) { return (n / 1048576).toFixed(n < 10485760 ? 1 : 0); }
+  function sizeText(got, total) {
+    if (!total) return got ? `${mb(got)} MB` : "";
+    return `${mb(Math.min(got, total))} of ${mb(total)} MB`;
+  }
+  const reducedMotion = () => matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+  function mount() {
+    if (root) return root;
+    const style = el("style");
+    style.textContent = CSS;
+    document.head.appendChild(style);
+    root = el("div", "sk-loader");
+    root.setAttribute("role", "status");
+    if (opts.poster) {
+      const b = el("div", "sk-backdrop");
+      b.style.backgroundImage = `url("${String(opts.poster).replace(/"/g, "%22")}")`;
+      root.appendChild(b);
+    }
+    const box = el("div", "sk-box");
+    box.appendChild(el("p", "sk-title", opts.title ? `Loading ${opts.title}` : "Loading"));
+    const bar = el("div", "sk-bar");
+    bar.setAttribute("role", "progressbar");
+    bar.setAttribute("aria-valuemin", "0");
+    bar.setAttribute("aria-valuemax", "100");
+    bar.setAttribute("aria-label", opts.title ? `Loading ${opts.title}` : "Loading");
+    bar.appendChild(el("div", "sk-fill"));
+    box.appendChild(bar);
+    box.appendChild(el("div", "sk-size", opts.bytes ? `${mb(opts.bytes)} MB` : ""));
+    root.appendChild(box);
+    (opts.mount || document.body).appendChild(root);
+    return root;
+  }
+
+  function progress(got, total) {
+    if (!root) return;
+    const bar = root.querySelector(".sk-bar"), fill = root.querySelector(".sk-fill");
+    if (!bar) return;
+    if (total) {
+      const pct = Math.min(100, Math.round(got / total * 100));
+      bar.classList.remove("sk-indeterminate");
+      fill.style.width = pct + "%";
+      bar.setAttribute("aria-valuenow", String(pct));
+    } else {
+      bar.classList.add("sk-indeterminate");
+      bar.removeAttribute("aria-valuenow");
+    }
+    root.querySelector(".sk-size").textContent = sizeText(got, total);
+  }
+
+  function hasWebGL2() {
+    try {
+      const c = document.createElement("canvas");
+      const gl = c.getContext("webgl2");
+      if (!gl) return false;
+      const lose = gl.getExtension("WEBGL_lose_context");
+      if (lose) lose.loseContext();  // give the probe's context back at once
+      return true;
+    } catch (e) { return false; }
+  }
+
+  function asksForLess() {
+    const conn = navigator.connection;
+    if (reducedMotion()) return "reduced-motion";
+    if (conn && conn.saveData) return "save-data";
+    if (navigator.deviceMemory && navigator.deviceMemory < 4) return "low-memory";
+    return null;
+  }
+
+  const REASONS = {
+    "no-webgl2": "This browser can't draw WebGL 2, which the live view needs.",
+    "engine": "The live view's renderer failed to start.",
+    "network": "The live view didn't download.",
+    "context-lost": "The live view lost its graphics context.",
+    "slow": "This device draws the live view too slowly.",
+  };
+
+  // Shows the fallback: the trailer, else the poster, with the reason and the
+  // link. Also usable by a page directly, e.g. StrataLoader.fallback("slow").
+  function fallback(code, message) {
+    state = "fallback";
+    mount();
+    root.hidden = false;
+    root.classList.remove("sk-done");
+    root.classList.add("sk-fallback");
+    root.setAttribute("role", "alert");
+    root.querySelectorAll(".sk-media").forEach((m) => m.remove());
+    const t = opts.trailer;
+    if (t && (t.webm || t.mp4) && !reducedMotion()) {
+      const v = el("video", "sk-media");
+      v.muted = true; v.loop = true; v.autoplay = true; v.playsInline = true; v.controls = true;
+      v.setAttribute("aria-label", opts.trailerLabel || "A recorded clip of the live view");
+      if (opts.poster) v.poster = opts.poster;
+      if (t.webm) v.appendChild(Object.assign(el("source"), {src: t.webm, type: "video/webm"}));
+      if (t.mp4) v.appendChild(Object.assign(el("source"), {src: t.mp4, type: "video/mp4"}));
+      root.insertBefore(v, root.querySelector(".sk-box"));
+    } else if (opts.poster) {
+      const img = el("img", "sk-media");
+      img.src = opts.poster;
+      img.alt = opts.posterAlt || "A still of the live view";
+      root.insertBefore(img, root.querySelector(".sk-box"));
+    }
+    const box = root.querySelector(".sk-box");
+    box.textContent = "";
+    box.appendChild(el("p", "sk-msg", message || REASONS[code] || REASONS.engine));
+    if (t && (t.webm || t.mp4)) box.appendChild(el("p", "sk-size", "Showing a recorded clip instead."));
+    if (opts.fallback && opts.fallback.href) {
+      const p = el("p", "");
+      p.style.margin = "0";
+      const a = el("a", "", opts.fallback.text || "Open the simpler view");
+      a.href = opts.fallback.href;
+      p.appendChild(a);
+      box.appendChild(p);
+    }
+    if (opts.onFallback) opts.onFallback(code);
+  }
+
+  function loadScript(src) {
+    return new Promise((resolve, reject) => {
+      const s = document.createElement("script");
+      s.src = src;
+      s.async = true;
+      s.onload = resolve;
+      s.onerror = () => reject(new Error("script " + src));
+      document.head.appendChild(s);
+    });
+  }
+
+  async function fetchWasm(url, statedBytes) {
+    const res = await fetch(url, {credentials: "same-origin"});
+    if (!res.ok) throw new Error(`${url}: HTTP ${res.status}`);
+    // Content-Length is the size on the wire; when the body is compressed it
+    // is smaller than what the reader yields, so the stated size wins then.
+    const enc = res.headers.get("Content-Encoding");
+    const header = parseInt(res.headers.get("Content-Length") || "", 10);
+    let total = (!enc || enc === "identity") && header > 0 ? header : (statedBytes || 0);
+    if (!res.body || !res.body.getReader) {
+      const buf = await res.arrayBuffer();
+      progress(buf.byteLength, buf.byteLength);
+      return buf;
+    }
+    const reader = res.body.getReader();
+    const chunks = [];
+    let got = 0;
+    progress(0, total);
+    for (;;) {
+      const {done, value} = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      got += value.byteLength;
+      if (total && got > total) total = 0;  // the stated size was wrong: say bytes only
+      progress(got, total);
+    }
+    const out = new Uint8Array(got);
+    let o = 0;
+    for (const c of chunks) { out.set(c, o); o += c.byteLength; }
+    progress(got, got);
+    return out.buffer;
+  }
+
+  function waitForStart(reason) {
+    return new Promise((resolve) => {
+      const box = root.querySelector(".sk-box");
+      const keep = [...box.childNodes];
+      box.textContent = "";
+      const msg = reason === "save-data" ? "Data saver is on."
+        : reason === "low-memory" ? "This device has little memory." : "Motion is reduced on this device.";
+      box.appendChild(el("p", "sk-msg", `${msg} The live view downloads ${opts.bytes ? mb(opts.bytes) + " MB" : "its engine"} and animates.`));
+      const go = el("button", "", "Start the live view");
+      go.type = "button";
+      go.addEventListener("click", () => { box.textContent = ""; keep.forEach((n) => box.appendChild(n)); resolve(); });
+      box.appendChild(go);
+      if (opts.fallback && opts.fallback.href) {
+        const a = el("a", "", opts.fallback.text || "Open the simpler view");
+        a.href = opts.fallback.href;
+        a.style.display = "block";
+        a.style.marginTop = "8px";
+        box.appendChild(a);
+      }
+      go.focus();
+    });
+  }
+
+  async function load(o) {
+    opts = Object.assign({}, o);
+    state = "loading";
+    mount();
+    if (!hasWebGL2()) {
+      fallback("no-webgl2");
+      throw Object.assign(new Error("no-webgl2"), {code: "no-webgl2"});
+    }
+    if (opts.gate) {
+      const why = asksForLess();
+      if (why) await waitForStart(why);
+    }
+    let binary;
+    try {
+      const glue = window[opts.factory] ? Promise.resolve() : loadScript(opts.script);
+      [binary] = await Promise.all([fetchWasm(opts.wasm, opts.bytes), glue]);
+    } catch (e) {
+      fallback("network", `${REASONS.network} (${e.message || e})`);
+      throw Object.assign(new Error("network"), {code: "network", cause: e});
+    }
+    const factory = window[opts.factory];
+    if (typeof factory !== "function") {
+      fallback("network", `${REASONS.network} (${opts.factory} is missing)`);
+      throw Object.assign(new Error("network"), {code: "network"});
+    }
+    try {
+      return await factory(Object.assign({
+        wasmBinary: binary,
+        locateFile: (p) => (opts.base || "") + p,
+        print: (t) => console.log(t),
+        printErr: (t) => console.warn(t),
+      }, opts.moduleArgs || {}));
+    } catch (e) {
+      fallback("engine", `${REASONS.engine} (${e.message || e})`);
+      throw Object.assign(new Error("engine"), {code: "engine", cause: e});
+    }
+  }
+
+  // The live view is up: fade the shell out.
+  function done() {
+    if (!root || state === "fallback") return;
+    state = "done";
+    root.classList.add("sk-done");
+    setTimeout(() => { if (state === "done") root.hidden = true; }, reducedMotion() ? 0 : 320);
+  }
+
+  // The kit could not go any lower and frames are still slow: offer the clip
+  // (or the fallback link) without taking the live view away.
+  function slow() {
+    if (state === "fallback" || (!opts.trailer && !(opts.fallback && opts.fallback.href))) return;
+    const bar = el("div", "sk-slow");
+    bar.setAttribute("role", "status");
+    bar.style.cssText = "position:fixed;left:50%;transform:translateX(-50%);bottom:max(12px,env(safe-area-inset-bottom));" +
+      "z-index:21;background:rgba(0,0,0,.7);color:#fff;padding:8px 12px;border-radius:8px;" +
+      "font:13px system-ui,sans-serif;display:flex;gap:10px;align-items:center;max-width:calc(100vw - 32px)";
+    bar.appendChild(el("span", "", "This device is drawing slowly."));
+    const b = el("button", "", opts.trailer ? "Show the clip" : (opts.fallback.text || "Open the simpler view"));
+    b.type = "button";
+    b.style.cssText = "font:inherit;min-height:36px;padding:4px 10px;border-radius:6px;border:0;cursor:pointer";
+    b.addEventListener("click", () => {
+      bar.remove();
+      if (opts.trailer) fallback("slow"); else location.href = opts.fallback.href;
+    });
+    const x = el("button", "", "×");
+    x.type = "button";
+    x.setAttribute("aria-label", "Dismiss");
+    x.style.cssText = b.style.cssText;
+    x.addEventListener("click", () => bar.remove());
+    bar.appendChild(b);
+    bar.appendChild(x);
+    document.body.appendChild(bar);
+  }
+
+  window.StrataLoader = {load, done, fallback, slow, hasWebGL2, get state() { return state; }};
+})();
diff --git a/strata/web/strata-kit/update.sh b/strata/web/strata-kit/update.sh
new file mode 100755
index 0000000..cbb2f39
--- /dev/null
+++ b/strata/web/strata-kit/update.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Re-vendors the Strata web kit's loading shell (Strata's web/kit/strata-loader.js)
+# at one commit:
+#   web/strata-kit/update.sh <full commit sha>
+# then rebuild, run the browser smoke test, and commit the loader, PIN and SHA256SUMS.
+# Only the loader is vendored: the page is a classic Emscripten build and
+# web/strata-boot.js bridges it to the loader. Once a Strata release carries the
+# kit (its wasm tarball has kit/), the loader can come from the tarball instead.
+set -euo pipefail
+commit="${1:?usage: update.sh <full strata commit sha>}"
+case "$commit" in *[!0-9a-f]* | "") echo "update.sh: give a full hex commit sha" >&2; exit 1 ;; esac
+[ "${#commit}" -eq 40 ] || { echo "update.sh: give the full 40-character sha" >&2; exit 1; }
+here="$(cd "$(dirname "$0")" && pwd)"
+base="https://raw.githubusercontent.com/Preponderous-Software/strata/$commit"
+curl -fsSL -o "$here/strata-loader.js" "$base/web/kit/strata-loader.js"
+curl -fsSL -o "$here/LICENSE" "$base/LICENSE"
+echo "$commit" > "$here/PIN"
+(cd "$here" && sha256sum strata-loader.js LICENSE > SHA256SUMS)
+echo "vendored the Strata loading shell at $commit"
diff --git a/strata/web/strata_page.cmake b/strata/web/strata_page.cmake
new file mode 100644
index 0000000..d42576e
--- /dev/null
+++ b/strata/web/strata_page.cmake
@@ -0,0 +1,47 @@
+# Finishes the page emcc wrote, after each link:
+#   cmake -DHTML=<page> -DWASM=<.wasm> [-DDATA=<.data>] -DWEB=<repo web/ dir> -P web/strata_page.cmake
+#
+# - The loading shell (web/strata-kit/strata-loader.js, vendored from Strata)
+#   and its bridge (web/strata-boot.js) go inline in place of their <script src>
+#   tags, so the site is the same files it always was and the shell costs no
+#   extra request before the engine starts downloading.
+# - The download's size (the .wasm, plus a --preload-file package if any) goes
+#   into data-bytes on <template id="strata-glue">: the arcade compresses on
+#   the fly and sends no Content-Length, so the loader needs the size up front
+#   to show real progress.
+foreach(var HTML WASM WEB)
+  if(NOT DEFINED ${var})
+    message(FATAL_ERROR "strata_page.cmake: -D${var}= is required")
+  endif()
+endforeach()
+
+file(READ "${HTML}" page)
+
+foreach(pair "strata-kit/strata-loader\\.js|strata-kit/strata-loader.js" "strata-boot\\.js|strata-boot.js")
+  string(REPLACE "|" ";" pair "${pair}")
+  list(GET pair 0 pattern)
+  list(GET pair 1 file)
+  string(REGEX MATCH "<script src=\"?${pattern}\"?></script>" tag "${page}")
+  if(tag STREQUAL "")
+    message(FATAL_ERROR "strata_page.cmake: no <script src=\"${file}\"> tag in ${HTML}")
+  endif()
+  file(READ "${WEB}/${file}" body)
+  string(FIND "${body}" "</script" closes)
+  if(NOT closes EQUAL -1)
+    message(FATAL_ERROR "strata_page.cmake: ${file} contains </script and cannot go inline")
+  endif()
+  string(REPLACE "${tag}" "<script>/* ${file} */\n${body}</script>" page "${page}")
+endforeach()
+
+file(SIZE "${WASM}" bytes)
+if(DEFINED DATA AND NOT DATA STREQUAL "")
+  file(SIZE "${DATA}" data_bytes)
+  math(EXPR bytes "${bytes} + ${data_bytes}")
+endif()
+string(REGEX MATCH "data-bytes=\"?0\"?" stamp "${page}")
+if(stamp STREQUAL "")
+  message(FATAL_ERROR "strata_page.cmake: no data-bytes=\"0\" in ${HTML}")
+endif()
+string(REPLACE "${stamp}" "data-bytes=\"${bytes}\"" page "${page}")
+
+file(WRITE "${HTML}" "${page}")

From 2fc16cbad102d90c37f1ca9ed18b6237ffa9be66 Mon Sep 17 00:00:00 2001
From: Daniel McCoy Stephenson <dmccoystephenson@gmail.com>
Date: Wed, 28 Oct 2026 01:57:00 -0600
Subject: [PATCH 2/2] Docs: the slow-device offer keeps the live view

drafted by Claude on behalf of Daniel Stephenson

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LYNeuo5Ry76i84tz6WXQSE
---
 docs/STRATA.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/STRATA.md b/docs/STRATA.md
index 27b7a29..1ca4543 100644
--- a/docs/STRATA.md
+++ b/docs/STRATA.md
@@ -165,7 +165,7 @@ the `.wasm` and hands its bytes to the engine, so nothing downloads twice. If
 env-lib-cpp can't run (no WebGL 2, the renderer fails, the engine stops, a lost
 WebGL context does not come back), the shell says why, and plays the trailer instead (the still under `prefers-reduced-motion`).
 A device that draws under 12 frames a second is offered the clip without
-losing the game (not in automated browsers or `?bench` runs).
+losing the live view (not in automated browsers or `?bench` runs).
 
 `strata/web/strata-boot.js` bridges this classic (non-`MODULARIZE`) build to the
 loader: emcc's script tag sits inert in `<template id="strata-glue">`, the