web: deterministic cache busting via commit-based version tag; generate pkg/env.js at build; update index.html and docs; remove dead env.js

Author: rgilks

README.md

@@ -79,6 +79,10 @@ This repo is configured to deploy via Cloudflare Workers; cache-control headers
   - Build populates `dist/` with only production runtime files: `index.html` and `pkg/{app_web.js, app_web_bg.wasm, env.js}`
 - Worker sets cache-control headers for `.wasm`/`.js`/HTML
 
+#### Build cache-busting
+
+- The build generates `pkg/env.js` with a `version` derived from the current git commit (short SHA, with CI env fallbacks). `index.html` appends `?v=<version>` to the dynamic import of `app_web.js` to ensure deterministic cache busting across deploys.
+
 Controls in browser:
 
 - Click Start to initialize audio (canvas click also works)

env.js

@@ -240,7 +240,8 @@ <h3>Modes (1..7)</h3>
       Try Chrome 113+ or Edge 113+ with WebGPU enabled.
     </div>
     <script type="module">
-      const v = Date.now();
+      import { version as versionTag } from "env";
+      const v = versionTag || Date.now();
       console.log("[index] dynamic import cache-bust tag:", v);
       if (!("gpu" in navigator)) {
         const el = document.getElementById("no-webgpu");

index.html

@@ -4,7 +4,7 @@
   "description": "Web (WASM): uses `wasm-pack` to build and a static `index.html` to run",
   "main": "index.js",
   "scripts": {
-    "build": "wasm-pack build --target web --out-dir pkg --out-name app_web --release && cp env.js pkg/env.js && rm -rf dist && mkdir -p dist/pkg && cp pkg/app_web.js dist/pkg/ && cp pkg/app_web_bg.wasm dist/pkg/ && cp env.js dist/pkg/env.js && cp index.html dist/index.html && cp favicon.svg dist/favicon.svg",
+    "build": "wasm-pack build --target web --out-dir pkg --out-name app_web --release && node scripts/gen-env.js && rm -rf dist && mkdir -p dist/pkg && cp pkg/app_web.js dist/pkg/ && cp pkg/app_web_bg.wasm dist/pkg/ && cp pkg/env.js dist/pkg/env.js && cp index.html dist/index.html && cp favicon.svg dist/favicon.svg",
     "serve": "http-server -p 8080 -c-1 .",
     "dev": "npm run build && (http-server -p 8080 -c-1 . & SERVER_PID=$!; npm run open; wait $SERVER_PID)",
     "open": "open http://localhost:8080",

package.json

@@ -0,0 +1,75 @@
+/* eslint-disable no-console */
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+function shortSha(sha) {
+  if (!sha || typeof sha !== "string") return null;
+  const cleaned = sha.trim();
+  if (!cleaned) return null;
+  return cleaned.slice(0, 8);
+}
+
+function getVersionTag() {
+  const envCandidates = [
+    process.env.GIT_COMMIT,
+    process.env.COMMIT,
+    process.env.SOURCE_COMMIT,
+    process.env.VERCEL_GIT_COMMIT_SHA,
+    process.env.GITHUB_SHA,
+    process.env.CF_PAGES_COMMIT_SHA,
+  ];
+  for (const candidate of envCandidates) {
+    const s = shortSha(candidate);
+    if (s) return s;
+  }
+
+  try {
+    const sha = execSync("git rev-parse --short HEAD", {
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .toString()
+      .trim();
+    if (sha) return sha;
+  } catch (_) {
+    // ignore
+  }
+
+  // Final fallback: time-based tag, stable within the build
+  return `dev-${Math.floor(Date.now() / 1000).toString(36)}`;
+}
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function writeEnvJs(targetPath, version) {
+  const contents = `// Auto-generated by scripts/gen-env.js
+export const version = "${version}";
+export function now() {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+}
+export default { version, now };
+`;
+  fs.writeFileSync(targetPath, contents, "utf8");
+}
+
+function main() {
+  const repoRoot = path.resolve(__dirname, "..");
+  const pkgDir = path.join(repoRoot, "pkg");
+  ensureDir(pkgDir);
+
+  const version = getVersionTag();
+  const target = path.join(pkgDir, "env.js");
+  writeEnvJs(target, version);
+  console.log(
+    `[gen-env] wrote ${path.relative(repoRoot, target)} with version: ${version}`
+  );
+}
+
+main();