test: regression + docs for three-rain and p5-rain

ap0ught · ap0ught · commit e7b10a54322f · 2026-04-10T19:06:30.000-05:00
- tests/README.md: commands, layout, matrix-full vs matrix-experimental-renderers
- tests/regression/matrix-experimental-renderers.spec.js: four URLs (preset + explicit renderer)
- matrix-full.spec.js: exclude mathcode_alphabet_three and mathcode_p5 from WebGL Cartesian product
- matrix-playwright-helpers: rainSurfaceCanvas (first visible canvas); assertMatrixBootsClean uses it
- Smoke specs: matrix-three-rain, matrix-p5-rain use shared helpers; Prettier on tests/*.spec.js
- Docs: CONTRIBUTING, README, DEV_README, DEPENDENCY_POLICY, TESTING_SUMMARY, migration_repl,
  playwright.regression.config, Copilot/agent instructions

Made-with: Cursor
diff --git a/.copilot/instructions.md b/.copilot/instructions.md
@@ -342,7 +342,7 @@ When adding features that span multiple windows/displays:
 These complement `.github/copilot-instructions.md` (treat that file as the detailed source of truth).
 
 - **Renderers**: `js/webgl/` (GLSL + regl **temporarily**, vendored `lib/regl.min.js`) and `js/webgpu/` (WGSL). Experimental: `renderer=three` (`js/three-rain/`), `renderer=p5` (`js/p5-rain/`). URL `renderer=regl` is a legacy alias for WebGL. Holoplay / Looking Glass is **WebGL-only** — see [RENDERING.md](../RENDERING.md), [RENDERING_PIPELINE.md](../RENDERING_PIPELINE.md), [HOLOPLAY.md](../HOLOPLAY.md), and [DEPENDENCY_POLICY.md](../DEPENDENCY_POLICY.md).
-- **Tests**: `npm test` runs Node tests + Playwright smoke tests; `npm run test:regression` is the full mode×effect matrix (slow). Failures on `[Matrix][WebGL]` console lines are intentional.
+- **Tests**: `npm test` runs Node tests + Playwright smoke tests (`tests/README.md`). `npm run test:regression` runs `tests/regression/`: **`matrix-full.spec.js`** (WebGL mode×effect; skips `mathcode_alphabet_three` / `mathcode_p5`) and **`matrix-experimental-renderers.spec.js`** (**three-rain**, **p5-rain**). Slow. Failures on `[Matrix][WebGL]` console lines are intentional.
 - **PWA cache names**: Not just `matrix-v{version}` — the service worker uses `matrix-sw-{scope}-v{VERSION}-{VER}`; `js/main.js` prints the matching string for debugging.
 - **GLSL**: Shared uniforms must match precision across vertex/fragment stages on some GPUs (`uniform mediump float` where shared). Shader sources are loaded as static strings after fetch (avoid undefined `shaderSource`).
 - **GitHub Pages**: Main-site deploy must **sync to `origin/gh-pages`** before rewriting root so `pr-*` previews are not wiped; see [GITHUB_PAGES.md](../.github/GITHUB_PAGES.md).
diff --git a/.github/agents/matrix-rain-operator.md b/.github/agents/matrix-rain-operator.md
@@ -150,7 +150,7 @@ cd ../..
 
 #### Testing and Validation
 
-- **`npm test`**: Node unit tests (`tests/*.test.mjs`) + Playwright smoke tests (`tests/*.spec.js`). Regression matrix: `npm run test:regression`.
+- **`npm test`**: Node unit tests (`tests/*.test.mjs`) + Playwright smoke tests (`tests/*.spec.js`). **`npm run test:regression`**: `tests/regression/` — WebGL mode×effect (`matrix-full.spec.js`) + experimental **three** / **p5** renderers (`matrix-experimental-renderers.spec.js`). See `tests/README.md`.
 - Console hooks in `tests/matrix-playwright-helpers.js` fail CI on `[Matrix][WebGL]` and invalid program errors.
 
 **Essential test URLs** (always append `&suppressWarnings=true`):
diff --git a/.github/copilot-agents/matrix-rain-operator.md b/.github/copilot-agents/matrix-rain-operator.md
@@ -150,7 +150,7 @@ cd ../..
 
 #### Testing and Validation
 
-- **`npm test`**: Node unit tests (`tests/*.test.mjs`) + Playwright smoke tests (`tests/*.spec.js`). Regression matrix: `npm run test:regression`.
+- **`npm test`**: Node unit tests (`tests/*.test.mjs`) + Playwright smoke tests (`tests/*.spec.js`). **`npm run test:regression`**: `tests/regression/` — WebGL mode×effect (`matrix-full.spec.js`) + experimental **three** / **p5** renderers (`matrix-experimental-renderers.spec.js`). See `tests/README.md`.
 - Console hooks in `tests/matrix-playwright-helpers.js` fail CI on `[Matrix][WebGL]` and invalid program errors.
 
 **Essential test URLs** (always append `&suppressWarnings=true`):
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -138,7 +138,7 @@ cp msdfgen/build/msdfgen out/
 - **Install**: `npm ci` (runs `postinstall` → `scripts/vendor-webgl-deps.mjs` to refresh `lib/regl.min.js`).
 - **Default suite**: `npm test` → Node unit tests (`tests/*.test.mjs`) + Playwright smoke tests (`tests/*.spec.js`, **not** `tests/regression/**`).
 - **Helpers**: `tests/matrix-playwright-helpers.js` attaches console/page listeners so **`[Matrix][WebGL]`** lines and invalid-program errors fail CI.
-- **Full matrix** (optional, slow): `npm run test:regression` uses `playwright.regression.config.js` and `tests/regression/` — every `getAvailableModes()` × `getAvailableEffects()` on WebGL.
+- **Full regression** (optional, slow): `npm run test:regression` uses `playwright.regression.config.js` and `tests/regression/` — WebGL **mode×effect** matrix (`matrix-full.spec.js`, experimental renderer presets excluded) plus **three-rain / p5-rain** (`matrix-experimental-renderers.spec.js`). See `tests/README.md`.
 
 **CRITICAL**: After shader or renderer changes, run at least `npm test` before merging.
 
@@ -323,15 +323,15 @@ gallery/                # Screenshot storage directory
 
 ```javascript
 galleryManager.on("itemChange", ({ item, index }) => {
-	// Fired when switching to new shader
+  // Fired when switching to new shader
 });
 
 galleryManager.on("screenshotCapture", ({ item, duration }) => {
-	// Fired when capturing screenshot for missing image
+  // Fired when capturing screenshot for missing image
 });
 
 galleryManager.on("playlistComplete", () => {
-	// Fired when playlist finishes, triggers new playlist generation
+  // Fired when playlist finishes, triggers new playlist generation
 });
 ```
 
@@ -447,16 +447,16 @@ The Matrix Mode panel in the top-right corner provides user controls for customi
 
 ```javascript
 modeDisplay.on("versionChange", (version) => {
-	/* handle version change */
+  /* handle version change */
 });
 modeDisplay.on("effectChange", (effect) => {
-	/* handle effect change */
+  /* handle effect change */
 });
 modeDisplay.on("toggleScreensaver", (enabled) => {
-	/* handle screensaver toggle */
+  /* handle screensaver toggle */
 });
 modeDisplay.on("changeSwitchInterval", (interval) => {
-	/* handle interval change */
+  /* handle interval change */
 });
 ```
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -64,7 +64,7 @@ npm test
 3. **Make your changes** with clear, focused commits
 4. **Test thoroughly** across different Matrix versions and browsers
 5. **Format your code** (match CI): `npx prettier --write --use-tabs --print-width 160 "index.html" "./js/**/*.js" "./lib/gpu-buffer.js" "./scripts/**/*.mjs" "./tests/**/*.js"`
-6. **Run tests**: `npm test` (and `npm run test:regression` if you change shaders or renderers)
+6. **Run tests**: `npm test` (and `npm run test:regression` if you change shaders or renderers). See **[tests/README.md](tests/README.md)** for suite layout; regression includes **`matrix-experimental-renderers.spec.js`** for **`three-rain`** / **`p5-rain`** in addition to the WebGL mode×effect matrix.
 7. **Submit a pull request** with a clear description
 
 ## 📋 Code Style Guidelines
diff --git a/DEPENDENCY_POLICY.md b/DEPENDENCY_POLICY.md
@@ -42,4 +42,4 @@ This repository ships as **static files** (no app bundler). Anything we add must
 
 ## Reviews
 
-When upgrading or adding dependencies, update `**SECURITY.md`** supply-chain table and run `**npm test**` (and `**npm run test:regression**` for renderer/shader changes).
+When upgrading or adding dependencies, update `**SECURITY.md`** supply-chain table and run `**npm test**` (and `**npm run test:regression**` for renderer/shader changes — see `**tests/README.md**`).
diff --git a/DEV_README.md b/DEV_README.md
@@ -46,8 +46,8 @@ The brilliance? **Sawtooth waves** create natural-looking randomness while ensur
 // Converting human-intuitive colors to machine-readable values
 // Like translating between the Matrix's perception layer and reality
 const f = (n) => {
-	const k = (n + hue * 12) % 12;
-	return lightness - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+  const k = (n + hue * 12) % 12;
+  return lightness - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
 };
 ```
 
@@ -149,8 +149,9 @@ npx prettier --write --use-tabs --print-width 160 "index.html" "./js/**/*.js" ".
 npx playwright install   # once per machine
 npm test
 
-# Optional: full WebGL mode × effect regression (slow)
+# Optional: full regression (slow): WebGL mode×effect matrix + three-rain / p5-rain
 npm run test:regression
+# See tests/README.md for what each suite covers.
 
 # Performance testing with URL parameters
 localhost:8000/?fps=30&resolution=0.5&effect=none
diff --git a/README.md b/README.md
@@ -222,4 +222,4 @@ The glyphs are formatted as a multi-channel distance field (or MSDF) via Victor
 
 The raindrops themselves are particles [computed on the GPU and stored in textures](https://threejs.org/examples/webgl_gpgpu_water.html), much smaller than the final render. The data sent from the CPU to the GPU every frame is negligible.
 
-**Contributing / tests:** Install with `npm ci`, run `npm test` (Playwright + unit tests). Full WebGL mode×effect coverage is `npm run test:regression`. See [CONTRIBUTING.md](CONTRIBUTING.md), [DEV_README.md](DEV_README.md), and [RENDERING.md](RENDERING.md).
+**Contributing / tests:** Install with `npm ci`, run `npm test` (Playwright + unit tests). **`npm run test:regression`** runs the WebGL **mode×effect** matrix plus **experimental renderer** checks (**`three-rain`**, **`p5-rain`**). See [tests/README.md](tests/README.md), [CONTRIBUTING.md](CONTRIBUTING.md), [DEV_README.md](DEV_README.md), and [RENDERING.md](RENDERING.md).
diff --git a/TESTING_SUMMARY.md b/TESTING_SUMMARY.md
@@ -1,5 +1,8 @@
 # Multi-Monitor Fullscreen - Testing Summary
 
+> **Automated Playwright layout** (default smoke vs regression, `three-rain` / `p5-rain`): see **[tests/README.md](tests/README.md)**.
+
+
 ## Test Date
 December 16, 2024
 
diff --git a/migration_repl.md b/migration_repl.md
@@ -155,7 +155,8 @@ Every stage that calls `regl({...})` must be rewritten.
 | `package.json`                                                   | Remove `regl` dependency                                                                                                        |
 | `scripts/vendor-webgl-deps.mjs`                                  | Stop copying regl to `lib/`                                                                                                     |
 | `service-worker.js`                                              | Remove `lib/regl.min.js` from `STATIC_ASSETS` when file deleted                                                                 |
-| `tests/regression/matrix-full.spec.js`                           | Still valid; must pass after migration                                                                                          |
+| `tests/regression/matrix-full.spec.js`                           | Still valid; must pass after migration (WebGL-only matrix; skips experimental renderer presets).                                |
+| `tests/regression/matrix-experimental-renderers.spec.js`         | **three-rain** / **p5-rain** URLs; must pass if those paths change.                                                             |
 | `README.md` / `RENDERING.md` / `.github/copilot-instructions.md` | Update wording from “regl” to new stack                                                                                         |
 
 **Optional:** `js/webgl/lkgHelper.js` — may stay JS-only; verify it does not assume regl types.
diff --git a/playwright.regression.config.js b/playwright.regression.config.js
@@ -2,27 +2,31 @@
 import { defineConfig, devices } from "@playwright/test";
 
 /**
- * Full matrix: every `getAvailableModes()` × every `getAvailableEffects()` on WebGL.
+ * Regression browser suite (`tests/regression/`):
+ * - `matrix-full.spec.js` — every `getAvailableModes()` × `getAvailableEffects()` with **forced WebGL**
+ *   (experimental `renderer=three` / `renderer=p5` presets excluded; see file header).
+ * - `matrix-experimental-renderers.spec.js` — **three-rain** and **p5-rain** entry URLs.
+ *
  * Run with: `npm run test:regression`
  * Not part of default `npm test` (see testIgnore in playwright.config.js).
  */
 export default defineConfig({
-	testDir: "./tests/regression",
-	testMatch: "**/*.spec.js",
-	timeout: 120_000,
-	expect: { timeout: 15_000 },
-	fullyParallel: true,
-	forbidOnly: !!process.env.CI,
-	retries: process.env.CI ? 1 : 0,
-	use: {
-		baseURL: "http://127.0.0.1:4173",
-		trace: "on-first-retry",
-	},
-	projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
-	webServer: {
-		command: "npx --yes serve . -l 4173",
-		url: "http://127.0.0.1:4173",
-		reuseExistingServer: !process.env.CI,
-		timeout: 120_000,
-	},
+  testDir: "./tests/regression",
+  testMatch: "**/*.spec.js",
+  timeout: 120_000,
+  expect: { timeout: 15_000 },
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 1 : 0,
+  use: {
+    baseURL: "http://127.0.0.1:4173",
+    trace: "on-first-retry",
+  },
+  projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
+  webServer: {
+    command: "npx --yes serve . -l 4173",
+    url: "http://127.0.0.1:4173",
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
 });
diff --git a/tests/README.md b/tests/README.md
@@ -0,0 +1,23 @@
+# Tests
+
+## Commands
+
+| Command                       | What runs                                                                                                                                                                            |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **`npm run test:unit`**       | Node only: `tests/*.test.mjs` (shader / text invariants, no browser).                                                                                                                |
+| **`npm test`**                | `test:unit` **+** Playwright default config: `tests/**/*.spec.js` **except** `tests/regression/**`. Requires **`npx playwright install`** (e.g. Chromium) once per machine/CI image. |
+| **`npm run test:regression`** | Playwright **`playwright.regression.config.js`**: everything under **`tests/regression/`** (slow). Same Playwright install as above.                                                 |
+
+## Layout
+
+| Path                                                         | Role                                                                                                                                                                                                                                               |
+| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`tests/*.test.mjs`**                                       | Node **`node:test`** modules.                                                                                                                                                                                                                      |
+| **`tests/*.spec.js`**                                        | Playwright smoke tests (default **`npm test`**). Examples: `matrix-mathcode.spec.js`, `matrix-three-rain.spec.js`, `matrix-p5-rain.spec.js`.                                                                                                       |
+| **`tests/matrix-playwright-helpers.js`**                     | Shared **`attachMatrixRenderingWatchers`**, **`assertMatrixBootsClean`**, **`rainSurfaceCanvas`** (first **visible** canvas — important when **`p5-rain`** hides the Matrix canvas).                                                               |
+| **`tests/regression/matrix-full.spec.js`**                   | Full Cartesian product: **`getAvailableModes()` × `getAvailableEffects()`** with **`renderer=webgl`**. Presets that use **`renderer=three`** or **`renderer=p5`** are **skipped** (they would not exercise those renderers while forced to WebGL). |
+| **`tests/regression/matrix-experimental-renderers.spec.js`** | **`three-rain`** and **`p5-rain`** URLs (preset + explicit `renderer=` variants).                                                                                                                                                                  |
+
+## CI
+
+`.github/workflows/master-branch-protection.yml` runs **`npm test`** (not `test:regression` by default). Run **`npm run test:regression`** locally before large renderer or shader refactors.
diff --git a/tests/matrix-mathcode.spec.js b/tests/matrix-mathcode.spec.js
@@ -8,32 +8,43 @@
  * after the compositor runs.
  */
 import { expect, test } from "@playwright/test";
-import { attachMatrixRenderingWatchers, settleAfterPaint } from "./matrix-playwright-helpers.js";
+import {
+  attachMatrixRenderingWatchers,
+  settleAfterPaint,
+} from "./matrix-playwright-helpers.js";
 
 test.describe("Matrix mathcode mode", () => {
-	test("loads WebGL stack, applies mathcode version, and keeps canvas sized", async ({ page }) => {
-		const watchers = attachMatrixRenderingWatchers(page);
+  test("loads WebGL stack, applies mathcode version, and keeps canvas sized", async ({
+    page,
+  }) => {
+    const watchers = attachMatrixRenderingWatchers(page);
 
-		await page.goto("/?version=mathcode&suppressWarnings=true&skipIntro=true&renderer=webgl", {
-			waitUntil: "networkidle",
-		});
+    await page.goto(
+      "/?version=mathcode&suppressWarnings=true&skipIntro=true&renderer=webgl",
+      {
+        waitUntil: "networkidle",
+      },
+    );
 
-		const canvas = page.locator("canvas").first();
-		await expect(canvas).toBeVisible({ timeout: 30_000 });
-		await settleAfterPaint(page);
+    const canvas = page.locator("canvas").first();
+    await expect(canvas).toBeVisible({ timeout: 30_000 });
+    await settleAfterPaint(page);
 
-		const { width, height, webgl } = await canvas.evaluate((el) => {
-			const w = el.width;
-			const h = el.height;
-			const gl = el.getContext("webgl2") || el.getContext("webgl");
-			return { width: w, height: h, webgl: !!gl };
-		});
+    const { width, height, webgl } = await canvas.evaluate((el) => {
+      const w = el.width;
+      const h = el.height;
+      const gl = el.getContext("webgl2") || el.getContext("webgl");
+      return { width: w, height: h, webgl: !!gl };
+    });
 
-		watchers.assertNoIssues("mathcode webgl");
-		expect(width, "canvas should have width").toBeGreaterThan(0);
-		expect(height, "canvas should have height").toBeGreaterThan(0);
-		expect(webgl, "WebGL context should exist (webgl renderer)").toBe(true);
+    watchers.assertNoIssues("mathcode webgl");
+    expect(width, "canvas should have width").toBeGreaterThan(0);
+    expect(height, "canvas should have height").toBeGreaterThan(0);
+    expect(webgl, "WebGL context should exist (webgl renderer)").toBe(true);
 
-		await expect(page.locator("select.version-select")).toHaveValue("mathcode", { timeout: 15_000 });
-	});
+    await expect(page.locator("select.version-select")).toHaveValue(
+      "mathcode",
+      { timeout: 15_000 },
+    );
+  });
 });
diff --git a/tests/matrix-p5-rain.spec.js b/tests/matrix-p5-rain.spec.js
@@ -2,25 +2,34 @@
  * Smoke test: p5.js experimental mathcode mode.
  */
 import { expect, test } from "@playwright/test";
-import { attachMatrixRenderingWatchers, settleAfterPaint } from "./matrix-playwright-helpers.js";
+import {
+  assertMatrixBootsClean,
+  rainSurfaceCanvas,
+} from "./matrix-playwright-helpers.js";
 
 test.describe("Matrix p5.js mathcode mode", () => {
-	test("loads p5-rain preset and exposes a canvas", async ({ page }) => {
-		const watchers = attachMatrixRenderingWatchers(page);
+  test("loads p5-rain preset and exposes a visible 2D canvas", async ({
+    page,
+  }) => {
+    const query = new URLSearchParams({
+      version: "mathcode_p5",
+      suppressWarnings: "true",
+      skipIntro: "true",
+    }).toString();
 
-		await page.goto("/?version=mathcode_p5&suppressWarnings=true&skipIntro=true", {
-			waitUntil: "networkidle",
-		});
+    await assertMatrixBootsClean(page, query);
 
-		const canvases = page.locator("canvas");
-		await expect(canvases.first()).toBeVisible({ timeout: 30_000 });
-		await settleAfterPaint(page);
+    const ctx2d = await rainSurfaceCanvas(page).evaluate(
+      (el) => !!el.getContext("2d"),
+    );
+    expect(
+      ctx2d,
+      "p5 2D mode should expose CanvasRenderingContext2D on the visible surface",
+    ).toBe(true);
 
-		const count = await canvases.count();
-		expect(count, "p5 adds its own canvas while the Matrix canvas may stay hidden").toBeGreaterThanOrEqual(1);
-
-		watchers.assertNoIssues("mathcode_p5 p5.js");
-
-		await expect(page.locator("select.version-select")).toHaveValue("mathcode_p5", { timeout: 15_000 });
-	});
+    await expect(page.locator("select.version-select")).toHaveValue(
+      "mathcode_p5",
+      { timeout: 15_000 },
+    );
+  });
 });
diff --git a/tests/matrix-playwright-helpers.js b/tests/matrix-playwright-helpers.js
diff --git a/tests/matrix-smoke.spec.js b/tests/matrix-smoke.spec.js
diff --git a/tests/matrix-three-rain.spec.js b/tests/matrix-three-rain.spec.js
diff --git a/tests/regression/matrix-experimental-renderers.spec.js b/tests/regression/matrix-experimental-renderers.spec.js
diff --git a/tests/regression/matrix-full.spec.js b/tests/regression/matrix-full.spec.js

Original file line number	Diff line number	Diff line change
`@@ -42,4 +42,4 @@ This repository ships as static files (no app bundler). Anything we add must`
`42`	`42`
`43`	`43`	`## Reviews`
`44`	`44`
`45`		-When upgrading or adding dependencies, update `SECURITY.md` supply-chain table and run `npm test` (and `npm run test:regression` for renderer/shader changes).
	`45`	+When upgrading or adding dependencies, update `SECURITY.md` supply-chain table and run `npm test` (and `npm run test:regression` for renderer/shader changes — see `tests/README.md`).
Original file line number	Diff line number	Diff line change
`@@ -222,4 +222,4 @@ The glyphs are formatted as a multi-channel distance field (or MSDF) via Victor`
`222`	`222`
`223`	`223`	`The raindrops themselves are particles [computed on the GPU and stored in textures](https://threejs.org/examples/webgl_gpgpu_water.html), much smaller than the final render. The data sent from the CPU to the GPU every frame is negligible.`
`224`	`224`
`225`		-Contributing / tests: Install with `npm ci`, run `npm test` (Playwright + unit tests). Full WebGL mode×effect coverage is `npm run test:regression`. See [CONTRIBUTING.md](CONTRIBUTING.md), [DEV_README.md](DEV_README.md), and [RENDERING.md](RENDERING.md).
	`225`	+Contributing / tests: Install with `npm ci`, run `npm test` (Playwright + unit tests). `npm run test:regression` runs the WebGL mode×effect matrix plus experimental renderer checks (`three-rain`, `p5-rain`). See [tests/README.md](tests/README.md), [CONTRIBUTING.md](CONTRIBUTING.md), [DEV_README.md](DEV_README.md), and [RENDERING.md](RENDERING.md).