fix(webgl): static shaders, Playwright guards, PWA cache hints

- Use static GLSL strings and shared fullscreen quad base; mediump rain vert for uniform precision.

- Playwright: matrix-playwright-helpers, fail on [Matrix][WebGL] / invalid program; regression suite (npm run test:regression).

- Bump VERSION + service-worker header for cache bust; console shows real SW cache name (scope + VERSION + VER from SW script).

- Remove stray marker in config comment; Prettier on touched paths.

Made-with: Cursor

Author: ap0ught

VERSION

@@ -1 +1 @@
-1.0.0
+1.0.1

js/config.js

@@ -13,7 +13,6 @@
  */
 
 /*
-=======
  * Random Version Selection Utility
  *
  * Sometimes the best way to experience the Matrix is to let the system

js/main.js

@@ -37,6 +37,33 @@ function enforceHoloplayRenderer(config) {
  */
 let appVersion = "unknown";
 
+/** Matches `const VER` in `service-worker.js` (read at runtime so CI-stamped deploys stay accurate). */
+let serviceWorkerVerStamp = "local";
+
+/**
+ * Same scope key algorithm as `service-worker.js` (BASE_PATH → SCOPE_KEY).
+ * Uses the registered script URL so subpaths (e.g. GitHub Pages project sites) match the SW.
+ * @returns {string}
+ */
+function getPwaCacheScopeKey() {
+	const swPath = new URL("service-worker.js", location.href).pathname;
+	const basePath = swPath.replace(/service-worker\.js$/, "");
+	return basePath.replace(/^\/|\/$/g, "").replace(/\//g, "-") || "root";
+}
+
+/**
+ * Offline cache bucket name the service worker uses after a successful install
+ * (`CACHE_NAME` in `service-worker.js`). If VERSION could not be read, the SW falls back to `v1`.
+ * @param {string} versionTrimmed
+ * @param {string} verStamp
+ * @returns {string}
+ */
+function getExpectedPwaCacheName(versionTrimmed, verStamp) {
+	const prefix = `matrix-sw-${getPwaCacheScopeKey()}-`;
+	const versionSeg = versionTrimmed && versionTrimmed !== "unknown" ? versionTrimmed : "1";
+	return `${prefix}v${versionSeg}-${verStamp}`;
+}
+
 /**
  * Load application version from VERSION file
  * @returns {Promise<string>} The version string (e.g., "1.0.0")
@@ -53,15 +80,33 @@ async function loadVersion() {
 	}
 }
 
+/**
+ * Read `VER` from the deployed service worker script (same source CI rewrites on gh-pages).
+ * @returns {Promise<void>}
+ */
+async function loadServiceWorkerVerStamp() {
+	try {
+		const url = new URL("service-worker.js", location.href).href;
+		const response = await fetch(url, { cache: "no-cache" });
+		const text = await response.text();
+		const match = text.match(/const\s+VER\s*=\s*"([^"]*)"/);
+		if (match) {
+			serviceWorkerVerStamp = match[1];
+		}
+	} catch (error) {
+		console.warn("[Matrix] Could not read service worker VER for cache name hint:", error);
+	}
+}
+
 /**
  * Display version information to console
  * Includes Matrix-themed messaging and helpful cache information
  */
 function displayVersionInfo() {
-	const cacheName = `matrix-v${appVersion}`;
+	const cacheName = getExpectedPwaCacheName(appVersion, serviceWorkerVerStamp);
 	console.log("%c⎡ MATRIX DIGITAL RAIN ⎦", "color: #0F0; font-size: 16px; font-weight: bold; text-shadow: 0 0 10px #0F0");
 	console.log(`%cVersion: ${appVersion}`, "color: #0F0; font-size: 12px");
-	console.log(`%cCache: ${cacheName}`, "color: #0F0; font-size: 12px");
+	console.log(`%cPWA offline cache: ${cacheName}`, "color: #0F0; font-size: 12px");
 	console.log(`%c"Wake up, Neo... The Matrix has you."`, "color: #0F0; font-style: italic; font-size: 10px");
 	console.log("");
 	console.log("%cPWA Cache Debug Commands:", "color: #0F0; font-size: 11px; font-weight: bold");
@@ -216,7 +261,7 @@ document.body.onload = async () => {
 	 * Load and Display Version Information
 	 * Shows version and cache debugging info in console for PWA management
 	 */
-	await loadVersion();
+	await Promise.all([loadVersion(), loadServiceWorkerVerStamp()]);
 	displayVersionInfo();
 
 	/*
@@ -292,7 +337,7 @@ document.body.onload = async () => {
 			urlParams.set("suppressWarnings", true);
 			history.replaceState({}, "", "?" + unescape(urlParams.toString()));
 			currentMatrixRenderer = await solution;
-			startMatrix(currentMatrixRenderer, canvas, matrixConfig);
+			await startMatrix(currentMatrixRenderer, canvas, matrixConfig);
 			canvas.style.display = "unset";
 			document.body.removeChild(notice);
 		});
@@ -303,7 +348,7 @@ document.body.onload = async () => {
 		 * Initialize the chosen rendering solution immediately.
 		 */
 		currentMatrixRenderer = await solution;
-		startMatrix(currentMatrixRenderer, canvas, matrixConfig);
+		await startMatrix(currentMatrixRenderer, canvas, matrixConfig);
 	}
 };
 
@@ -598,11 +643,11 @@ function setupSpotifyEventListeners() {
 /**
  * Start the Matrix renderer
  */
-function startMatrix(matrixRenderer, canvas, config) {
+async function startMatrix(matrixRenderer, canvas, config) {
 	// Start the Matrix renderer
 	// Note: setupFullscreenToggle is called within the renderer implementations
 	// (webgl/main.js and webgpu/main.js) to avoid duplicate event listeners
-	matrixRenderer.default(canvas, config);
+	await matrixRenderer.default(canvas, config);
 }
 
 /**
@@ -632,7 +677,7 @@ async function initializeGalleryMode() {
 			const useWebGPU = (await supportsWebGPU()) && newConfig.renderer?.toLowerCase() === "webgpu";
 			const solution = await import(`./${useWebGPU ? "webgpu" : "webgl"}/main.js`);
 			currentMatrixRenderer = solution;
-			startMatrix(currentMatrixRenderer, canvas, newConfig);
+			await startMatrix(currentMatrixRenderer, canvas, newConfig);
 		} else {
 			await restartMatrixWithNewConfig(newConfig);
 		}

js/webgl/bloomPass.js

@@ -1,4 +1,4 @@
-import { loadText, makePassFBO, makePass } from "./utils.js";
+import { fullscreenQuadReglBase, loadText, makePassFBO, makePass, requireShaderString } from "./utils.js";
 
 // The bloom pass is basically an added high-pass blur.
 // The blur approximation is the sum of a pyramid of downscaled, blurred textures.
@@ -35,49 +35,50 @@ export default ({ regl, config }, inputs) => {
 
 	// The high pass restricts the blur to bright things in our input texture.
 	const highPassFrag = loadText("shaders/glsl/bloomPass.highPass.frag.glsl");
-	const highPass = regl({
-		frag: regl.prop("frag"),
-		uniforms: {
-			highPassThreshold,
-			tex: regl.prop("tex"),
-		},
-		framebuffer: regl.prop("fbo"),
-	});
-
-	// A 2D gaussian blur is just a 1D blur done horizontally, then done vertically.
-	// The FBO pyramid's levels represent separate levels of detail;
-	// by blurring them all, this basic blur approximates a more complex gaussian:
-	// https://web.archive.org/web/20191124072602/https://software.intel.com/en-us/articles/compute-shader-hdr-and-bloom
-
 	const blurFrag = loadText("shaders/glsl/bloomPass.blur.frag.glsl");
-	const blur = regl({
-		frag: regl.prop("frag"),
-		uniforms: {
-			tex: regl.prop("tex"),
-			direction: regl.prop("direction"),
-			height: regl.context("viewportWidth"),
-			width: regl.context("viewportHeight"),
-		},
-		framebuffer: regl.prop("fbo"),
-	});
-
-	// The pyramid of textures gets flattened (summed) into a final blurry "bloom" texture
 	const combineFrag = loadText("shaders/glsl/bloomPass.combine.frag.glsl");
-	const combine = regl({
-		frag: regl.prop("frag"),
-		uniforms: {
-			bloomStrength,
-			...Object.fromEntries(vBlurPyramid.map((fbo, index) => [`pyr_${index}`, fbo])),
-		},
-		framebuffer: output,
+
+	let highPass;
+	let blur;
+	let combine;
+	const programsReady = Promise.all([highPassFrag.loaded, blurFrag.loaded, combineFrag.loaded]).then(() => {
+		highPass = regl({
+			...fullscreenQuadReglBase,
+			frag: requireShaderString("bloomPass.highPass.frag", () => highPassFrag.text()),
+			uniforms: {
+				highPassThreshold,
+				tex: regl.prop("tex"),
+			},
+			framebuffer: regl.prop("fbo"),
+		});
+		blur = regl({
+			...fullscreenQuadReglBase,
+			frag: requireShaderString("bloomPass.blur.frag", () => blurFrag.text()),
+			uniforms: {
+				tex: regl.prop("tex"),
+				direction: regl.prop("direction"),
+				height: regl.context("viewportWidth"),
+				width: regl.context("viewportHeight"),
+			},
+			framebuffer: regl.prop("fbo"),
+		});
+		combine = regl({
+			...fullscreenQuadReglBase,
+			frag: requireShaderString("bloomPass.combine.frag", () => combineFrag.text()),
+			uniforms: {
+				bloomStrength,
+				...Object.fromEntries(vBlurPyramid.map((fbo, index) => [`pyr_${index}`, fbo])),
+			},
+			framebuffer: output,
+		});
 	});
 
 	return makePass(
 		{
 			primary: inputs.primary,
 			bloom: output,
 		},
-		Promise.all([highPassFrag.loaded, blurFrag.loaded]),
+		programsReady,
 		(w, h) => {
 			// The blur pyramids can be lower resolution than the screen.
 			resizePyramid(highPassPyramid, w, h, bloomSize);
@@ -94,12 +95,12 @@ export default ({ regl, config }, inputs) => {
 				const highPassFBO = highPassPyramid[i];
 				const hBlurFBO = hBlurPyramid[i];
 				const vBlurFBO = vBlurPyramid[i];
-				highPass({ fbo: highPassFBO, frag: highPassFrag.text(), tex: i === 0 ? inputs.primary : highPassPyramid[i - 1] });
-				blur({ fbo: hBlurFBO, frag: blurFrag.text(), tex: highPassFBO, direction: [1, 0] });
-				blur({ fbo: vBlurFBO, frag: blurFrag.text(), tex: hBlurFBO, direction: [0, 1] });
+				highPass({ fbo: highPassFBO, tex: i === 0 ? inputs.primary : highPassPyramid[i - 1] });
+				blur({ fbo: hBlurFBO, tex: highPassFBO, direction: [1, 0] });
+				blur({ fbo: vBlurFBO, tex: hBlurFBO, direction: [0, 1] });
 			}
 
-			combine({ frag: combineFrag.text() });
+			combine({});
 		},
 	);
 };

js/webgl/imagePass.js

@@ -1,4 +1,4 @@
-import { loadImage, loadText, makePassFBO, makePass } from "./utils.js";
+import { fullscreenQuadReglBase, loadImage, loadText, makePassFBO, makePass, requireShaderString } from "./utils.js";
 
 // Multiplies the rendered rain and bloom by a loaded in image
 
@@ -9,24 +9,28 @@ export default ({ regl, config }, inputs) => {
 	const bgURL = "bgURL" in config ? config.bgURL : defaultBGURL;
 	const background = loadImage(regl, bgURL);
 	const imagePassFrag = loadText("shaders/glsl/imagePass.frag.glsl");
-	const render = regl({
-		frag: regl.prop("frag"),
-		uniforms: {
-			backgroundTex: background.texture,
-			tex: inputs.primary,
-			bloomTex: inputs.bloom,
-		},
-		framebuffer: output,
+	let render;
+	const programsReady = Promise.all([background.loaded, imagePassFrag.loaded]).then(() => {
+		render = regl({
+			...fullscreenQuadReglBase,
+			frag: requireShaderString("imagePass.frag", () => imagePassFrag.text()),
+			uniforms: {
+				backgroundTex: background.texture,
+				tex: inputs.primary,
+				bloomTex: inputs.bloom,
+			},
+			framebuffer: output,
+		});
 	});
 	return makePass(
 		{
 			primary: output,
 		},
-		Promise.all([background.loaded, imagePassFrag.loaded]),
+		programsReady,
 		(w, h) => output.resize(w, h),
 		(shouldRender) => {
 			if (shouldRender) {
-				render({ frag: imagePassFrag.text() });
+				render({});
 			}
 		},
 	);

js/webgl/main.js

@@ -14,6 +14,35 @@ import { createEffectsMapping, getEffectPass } from "../effects.js";
 
 const dimensions = { width: 1, height: 1 };
 
+/**
+ * Surface the first shader compile / program link failure (otherwise the browser only shows
+ * INVALID_OPERATION: useProgram: program not valid and then suppresses further errors).
+ */
+function installWebGLShaderDebugHooks() {
+	if (typeof WebGLRenderingContext === "undefined") {
+		return;
+	}
+	const proto = WebGLRenderingContext.prototype;
+	if (proto.__matrixShaderDebugHooked) {
+		return;
+	}
+	proto.__matrixShaderDebugHooked = true;
+	const compileShader = proto.compileShader;
+	proto.compileShader = function (shader) {
+		compileShader.call(this, shader);
+		if (!this.getShaderParameter(shader, this.COMPILE_STATUS)) {
+			console.error("[Matrix][WebGL] shader compile failed:\n", this.getShaderInfoLog(shader));
+		}
+	};
+	const linkProgram = proto.linkProgram;
+	proto.linkProgram = function (program) {
+		linkProgram.call(this, program);
+		if (!this.getProgramParameter(program, this.LINK_STATUS)) {
+			console.error("[Matrix][WebGL] program link failed:\n", this.getProgramInfoLog(program));
+		}
+	};
+}
+
 const loadJS = (src) =>
 	new Promise((resolve, reject) => {
 		const tag = document.createElement("script");
@@ -25,6 +54,7 @@ const loadJS = (src) =>
 
 export default async (canvas, config) => {
 	await Promise.all([loadJS("lib/regl.min.js"), loadJS("lib/gl-matrix.js")]);
+	installWebGLShaderDebugHooks();
 
 	const resize = () => {
 		const devicePixelRatio = window.devicePixelRatio ?? 1;
@@ -42,9 +72,16 @@ export default async (canvas, config) => {
 		await setupCamera();
 	}
 
-	const extensions = ["OES_texture_half_float", "OES_texture_half_float_linear"];
-	// These extensions are also needed, but Safari misreports that they are missing
-	const optionalExtensions = ["EXT_color_buffer_half_float", "WEBGL_color_buffer_float", "OES_standard_derivatives"];
+	const extensions = [
+		"OES_texture_half_float",
+		"OES_texture_half_float_linear",
+		"OES_standard_derivatives",
+		// Required to render into half-float FBOs (compute passes + rain); without it, framebuffer attachments can be incomplete.
+		"EXT_color_buffer_half_float",
+	];
+	// rainPass.frag.glsl uses fwidth() for MSDF anti-aliasing (OES_standard_derivatives).
+	// Some older stacks only expose float renderbuffers under a different name — regl may still enable it.
+	const optionalExtensions = ["WEBGL_color_buffer_float"];
 
 	switch (config.testFix) {
 		case "fwidth_10_1_2022_A":
@@ -56,14 +93,16 @@ export default async (canvas, config) => {
 			break;
 	}
 
-	const regl = createREGL({ canvas, pixelRatio: 1, extensions, optionalExtensions });
+	const regl = createREGL({
+		canvas,
+		pixelRatio: 1,
+		extensions,
+		optionalExtensions,
+	});
 
 	const cameraTex = regl.texture(cameraCanvas);
 	const lkg = await getLKG(config.useHoloplay, true);
 
-	// All this takes place in a full screen quad.
-	const fullScreenQuad = makeFullScreenQuad(regl);
-
 	// Create dynamic effects mapping
 	const passModules = {
 		makePalettePass,
@@ -76,7 +115,9 @@ export default async (canvas, config) => {
 	const context = { regl, canvas, config, lkg, cameraTex, cameraAspectRatio };
 	const pipeline = makePipeline(context, [makeRain, makeBloomPass, effectPass, makeQuiltPass]);
 	const screenUniforms = { tex: pipeline[pipeline.length - 1].outputs.primary };
-	const drawToScreen = regl({ uniforms: screenUniforms });
+	// Blit the final texture to the canvas. A nested `regl({ uniforms })` inside another draw can
+	// inherit the last pass's framebuffer binding, so the screen never gets the composed image.
+	const blitToCanvas = makeFullScreenQuad(regl, screenUniforms);
 	await Promise.all(pipeline.map((step) => step.ready));
 
 	const targetFrameTimeMilliseconds = 1000 / config.fps;
@@ -111,11 +152,9 @@ export default async (canvas, config) => {
 				step.setSize(viewportWidth, viewportHeight);
 			}
 		}
-		fullScreenQuad(() => {
-			for (const step of pipeline) {
-				step.execute(shouldRender);
-			}
-			drawToScreen();
-		});
+		for (const step of pipeline) {
+			step.execute(shouldRender);
+		}
+		blitToCanvas();
 	});
 };