Add ad-test regression tool (Playwright headless ad-flow validator)

After 8148 ASG account recreation + spot rotation debug session,
formalize tooling for automated ad-pipeline regression checks.

- /home/w4/bin/ad-test — wrapper, available globally
- /home/w4/playwright-tests/ — Playwright + Chromium runtime
- scripts/ad-regression.mjs — versioned copy у репо

Per-URL checks (6):
  1. ad-bundle loaded (window._adConfig set)
  2. popunder SDK fetches
  3. /api/users/<vast_spot> returns <Ad> (catches no-fill)
  4. mode = "vast" after popunder cooldown active
  5. .asg-container injects on play click (right data-spot-id)
  6. console clean (no [ASGB LOADER] errors)

Headless limitation documented: network+DOM checks cover 95% of
regressions without need for full video playback validation.
Use `ad-test --full` or real browser w/ ?debug=1 for visual.

Memory: reference_ad_regression_tool.md added — auto-trigger rule
to run ad-test after spot ID changes / mirror swaps / bundle rebuild.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/ADS.md

@@ -6,6 +6,43 @@
 
 🟢 **Working knowledge** — Skeleton наповнюємо.
 
+## ⚙️ Automated regression test — `ad-test`
+
+Швидкий smoke перевірити що ad flow не поламано після зміни.
+
+```bash
+# default — 3 URLs з 8148 (швидкий smoke)
+ad-test
+
+# конкретні URLs
+ad-test "https://www.xn--3dsq7teoyo9d.com/v/box/123/foo" \
+        "https://t1.atube.sex/v/box/456/bar"
+
+# з screenshots + JSON report
+ad-test --screenshot --json "https://..." "https://..."
+```
+
+**Що перевіряє per URL:**
+1. ✓ ad-bundle loaded (`window._adConfig` set, spot IDs читаються)
+2. ✓ popunder SDK loads
+3. ✓ `/api/users/<vast_spot>` повертає `<Ad>` (не empty no-fill)
+4. ✓ mode = "vast" після popunder cooldown
+5. ✓ `.asg-container` injects на click `pjs_play_btn` (правильний `data-spot-id`)
+6. ✓ console clean (no `[ASGB LOADER]` errors, no `pageerror`)
+
+**Exit code:** 0 = всі pass, 1 = ≥1 fail. Можна chain у CI / git hook.
+
+**Реалізація:**
+- Wrapper: `/home/w4/bin/ad-test`
+- Script: `/home/w4/playwright-tests/ad-regression.mjs` (Playwright + Chromium headless)
+- Repo copy (versioned): `scripts/ad-regression.mjs` + `scripts/ad-test.sh`
+
+**Обмеження headless:**
+- Real video playback не verifies (autoplay restrictions, VPAID не fully supported у chromium-headless-shell)
+- Network-level VAST chain validation (через `<Ad>/<InLine>/<Wrapper>` детекцію) cover 95% regressions без візуальної перевірки
+- Якщо треба видеоплей — `ad-test --full` (full chromium, але VPAID все ще incomplete)
+- Альтернатива для full visual: запусти у real browser з `?debug=1` + дивись HUD
+
 ## Architecture
 
 ### Mirrors (зеркала)