feat: WebGL stack at js/webgl, npm regl/twgl, smoke tests and CI

- Rename js/regl to js/webgl; renderer defaults to webgl; URL regl aliases to webgl
- Pin regl and twgl in package.json; postinstall vendors to lib/; drop duplicate lib/regl.js
- Holoplay forces WebGL when renderer=webgpu would be selected
- Playwright: effects, versions, image+local bg, gallery; WebGPU when available
- CI runs npm ci, playwright test; module check without clobbering package.json
- Track package-lock.json; add RENDERING.md and update README/SECURITY/DEV_README

Made-with: Cursor

Author: ap0ught

.github/agents/matrix-rain-operator.md

@@ -85,7 +85,7 @@ This is a **static ES-module web application** - key architectural points:
 
 ### Core Technologies
 
-1. **WebGL Rendering** (`js/regl/`):
+1. **WebGL Rendering** (`js/webgl/`):
    - Uses REGL functional wrapper
    - Shaders in `/shaders` directory (GLSL)
    - Main passes: rain computation, bloom effects, final composite
@@ -194,7 +194,7 @@ matrix/
 │   ├── main.js            # Application bootstrap
 │   ├── config.js          # URL parameter parsing
 │   ├── utils.js           # Shared utilities (formatModeName, etc.)
-│   ├── regl/              # WebGL implementation
+│   ├── webgl/             # WebGL implementation
 │   │   ├── main.js        # REGL renderer entry
 │   │   ├── rainPass.js    # Core rain computation
 │   │   └── bloomPass.js   # Bloom effects

.github/agents/matrix-red-pill-debugger.md

@@ -366,7 +366,7 @@ function refactorAllEffects() { ... }
 // shaders/rain-pass.glsl
 uniform int effectMode; // Added missing uniform
 
-// js/regl/rainPass.js
+// js/webgl/rainPass.js
 effectMode: config.effect === 'rainbow' ? 1 : 0, // Pass to shader
 ```
 

.github/copilot-agents/matrix-rain-operator.md

@@ -85,7 +85,7 @@ This is a **static ES-module web application** - key architectural points:
 
 ### Core Technologies
 
-1. **WebGL Rendering** (`js/regl/`):
+1. **WebGL Rendering** (`js/webgl/`):
    - Uses REGL functional wrapper
    - Shaders in `/shaders` directory (GLSL)
    - Main passes: rain computation, bloom effects, final composite
@@ -194,7 +194,7 @@ matrix/
 │   ├── main.js            # Application bootstrap
 │   ├── config.js          # URL parameter parsing
 │   ├── utils.js           # Shared utilities (formatModeName, etc.)
-│   ├── regl/              # WebGL implementation
+│   ├── webgl/             # WebGL implementation
 │   │   ├── main.js        # REGL renderer entry
 │   │   ├── rainPass.js    # Core rain computation
 │   │   └── bloomPass.js   # Bloom effects

.github/copilot-agents/matrix-red-pill-debugger.md

@@ -366,7 +366,7 @@ function refactorAllEffects() { ... }
 // shaders/rain-pass.glsl
 uniform int effectMode; // Added missing uniform
 
-// js/regl/rainPass.js
+// js/webgl/rainPass.js
 effectMode: config.effect === 'rainbow' ? 1 : 0, // Pass to shader
 ```
 

.github/copilot-instructions.md

@@ -96,15 +96,15 @@ cp msdfgen/build/msdfgen out/
 - `js/config.js` - URL parameter parsing and configuration management
 - `js/utils.js` - Shared utility functions (formatModeName, etc.)
 - `js/music-integration.js` - Spotify music synchronization
-- `js/regl/` - WebGL implementation using REGL library
+- `js/webgl/` - WebGL implementation (regl npm runtime, vendored to `lib/regl.min.js`)
 - `js/webgpu/` - WebGPU implementation (next-generation graphics)
 - `shaders/` - GLSL and WGSL shader source files
 
 ### Key Renderer Files
-- `js/regl/main.js` - REGL WebGL renderer entry point
+- `js/webgl/main.js` - WebGL renderer entry point
 - `js/webgpu/main.js` - WebGPU renderer entry point  
-- `js/regl/rainPass.js` & `js/webgpu/rainPass.js` - Core Matrix rain computation
-- `js/regl/bloomPass.js` & `js/webgpu/bloomPass.js` - Glow/bloom effects
+- `js/webgl/rainPass.js` & `js/webgpu/rainPass.js` - Core Matrix rain computation
+- `js/webgl/bloomPass.js` & `js/webgpu/bloomPass.js` - Glow/bloom effects
 
 ### Asset Files
 - `assets/` - Matrix fonts (TrueType) and MSDF texture atlases
@@ -168,7 +168,7 @@ npx prettier --write --use-tabs --print-width 160 "js/**/*.js"
 
 ### Making Visual Changes
 1. **Modify shader code** in `/shaders` directory for rendering effects
-2. **Update pass configurations** in `js/regl/` or `js/webgpu/` directories
+2. **Update pass configurations** in `js/webgl/` or `js/webgpu/` directories
 3. **Test immediately** by refreshing browser - no build step needed
 4. **Always validate** with multiple Matrix versions and effects
 
@@ -236,7 +236,7 @@ The service worker (`service-worker.js`) implements offline PWA functionality:
 
 ### Changes Requiring Full Validation
 - **Shader files** (`/shaders`): Test all Matrix versions and effects
-- **Renderer files** (`js/regl/`, `js/webgpu/`): Test WebGL and WebGPU modes
+- **Renderer files** (`js/webgl/`, `js/webgpu/`): Test WebGL and WebGPU modes
 - **Config changes** (`js/config.js`): Test URL parameter parsing
 - **Main entry points** (`index.html`, `js/main.js`): Full application test
 - **Service worker** (`service-worker.js`): Test offline functionality and cache updates
@@ -261,7 +261,7 @@ The service worker (`service-worker.js`) implements offline PWA functionality:
 
 ## Browser Compatibility
 
-- **WebGL 2.0**: Widely supported, battle-tested (js/regl/)
+- **WebGL 2.0**: Widely supported, battle-tested (`js/webgl/`)
 - **WebGPU**: Cutting-edge, modern browsers only (js/webgpu/)
 - **Software Fallback**: Works with SwiftShader when hardware acceleration disabled
 - **Mobile Support**: Responsive design, touch interactions for effects

.github/workflows/master-branch-protection.yml

@@ -34,12 +34,18 @@ jobs:
     - name: Validate code formatting with Prettier
       run: |
         echo "Checking code formatting..."
-        npx prettier --check --use-tabs --print-width 160 "index.html" "./js/**/*.js" "./lib/gpu-buffer.js" || {
+        npx prettier --check --use-tabs --print-width 160 "index.html" "./js/**/*.js" "./lib/gpu-buffer.js" "./scripts/**/*.mjs" "./tests/**/*.js" || {
           echo "❌ Code formatting check failed!"
-          echo "Run: npx prettier --write --use-tabs --print-width 160 \"index.html\" \"./js/**/*.js\" \"./lib/gpu-buffer.js\""
+          echo "Run: npx prettier --write --use-tabs --print-width 160 \"index.html\" \"./js/**/*.js\" \"./lib/gpu-buffer.js\" \"./scripts/**/*.mjs\" \"./tests/**/*.js\""
           exit 1
         }
         echo "✅ Code formatting is correct"
+
+    - name: Install dependencies and run automated tests
+      run: |
+        npm ci
+        npx playwright install --with-deps chromium
+        npm test
     
     - name: Start Matrix application server
       run: |
@@ -111,14 +117,11 @@ jobs:
           exit 1
         fi
         
-        # Validate ES6 module syntax by creating a temporary package.json
-        echo '{"type": "module"}' > package.json
         node --check js/main.js
         node --check js/config.js
         node --check js/effects.js
-        node --check js/regl/stripePass.js
+        node --check js/webgl/stripePass.js
         node --check js/webgpu/stripePass.js
-        rm package.json
         
         echo "✅ JavaScript modules are valid"
     

.gitignore

@@ -5,7 +5,6 @@ build/
 
 # Dependencies
 node_modules/
-package-lock.json
 
 # IDE
 .idea/

DEV_README.md

@@ -72,10 +72,11 @@ float alpha = smoothstep(0.5 - fwidth(distance), 0.5 + fwidth(distance), distanc
 - 🔗 [GPU Buffer Management](https://github.com/brendan-duncan/wgsl_reflect) - WGSL shader reflection
 - 💡 **Why it matters**: WebGPU provides compute shaders and better performance - essential for real-time particle systems like our rain
 
-### REGL: Functional WebGL
+### WebGL path (`js/webgl/`) and regl
 
-- 🔗 [REGL Documentation](https://regl.party/) - WebGL made functional
-- 💡 **Philosophy**: Treat graphics as pure functions - given the same inputs, always produce the same output. Very Matrix-like in its deterministic perfection.
+- 🔗 [regl on npm](https://www.npmjs.com/package/regl) / [regl docs](https://regl.party/) — the WebGL renderer loads the package output from `lib/regl.min.js` (refreshed by `npm install`).
+- 🔗 [RENDERING.md](RENDERING.md) — WebGPU vs WebGL, Holoplay constraints, and twgl for future glue code.
+- 💡 **Philosophy**: Treat graphics as pure functions — given the same inputs, always produce the same output. Very Matrix-like in its deterministic perfection.
 
 ### Signed Distance Fields in Graphics
 

README.md

@@ -62,7 +62,7 @@ _Concept_
 
 ## About
 
-This project is a web implementation of the raining green code seen in the _Matrix_ franchise. It's built right on top of the functional WebGL wrapper, [REGL](https://regl.party), with beta support for the upcoming graphics API [WebGPU](https://github.com/gpuweb/gpuweb); its previous Three.js version is maintained in a separate branch.
+This project is a web implementation of the raining green code seen in the _Matrix_ franchise. The WebGL path ([`js/webgl/`](js/webgl/)) uses the [regl](https://www.npmjs.com/package/regl) package (vendored to `lib/regl.min.js` after install); there is also a [WebGPU](https://github.com/gpuweb/gpuweb) implementation under [`js/webgpu/`](js/webgpu/). See [RENDERING.md](RENDERING.md) for how the two stacks relate. Its previous Three.js version is maintained in a separate branch.
 
 This project runs right in the web browser; you can serve it with any HTTP/HTTPS server, with no additional setup. For example, on a Mac you can point a Terminal shell at a local copy of the project and run a simple HTTP server with Python: `cd /path/to/the/project ; python3 -m http.server`
 

RELEASE.md

@@ -114,7 +114,7 @@ matrix-{version}.zip
 ├── js/                  # JavaScript modules
 │   ├── main.js
 │   ├── config.js
-│   ├── regl/           # WebGL renderer
+│   ├── webgl/          # WebGL renderer
 │   └── webgpu/         # WebGPU renderer
 ├── lib/                 # Third-party libraries
 │   ├── regl.min.js