Add Playwright visual snapshot tests with CI gate

.github/workflows/visual.yml

@@ -0,0 +1,43 @@
+name: Visual
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  visual:
+    name: Visual snapshot tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright Chromium
+        run: npx playwright install --with-deps chromium
+
+      - name: Build site
+        run: npm run build
+
+      - name: Run visual snapshot tests
+        run: npm run test:visual
+
+      - name: Upload failure artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: visual-test-results
+          path: |
+            test-results/
+            playwright-report/
+          if-no-files-found: ignore

.gitignore

@@ -19,3 +19,7 @@ pnpm-debug.log*
 
 # macOS-specific files
 .DS_Store
+
+# test artifacts
+test-results/
+playwright-report/

README.md

@@ -1,3 +1,56 @@
 ## austinabbott.dev
 
 A minimalist blog built with Astro and hosted on Cloudflare Pages
+
+## Visual tests
+
+Visual snapshot tests catch unintended layout changes from Astro or dependency updates. They compare full-page screenshots of key routes against committed baselines in `tests/visual.spec.ts-snapshots/`.
+
+Baselines are produced and compared on Linux in CI. Screenshots generated on macOS may differ slightly.
+
+### First-time setup
+
+```bash
+npm ci
+npx playwright install chromium
+```
+
+Playwright browsers are downloaded separately from npm packages.
+
+### Run tests
+
+```bash
+npm run test:visual
+```
+
+This builds the site, serves the production build with `astro preview`, and fails if any screenshot differs from the committed baseline.
+
+### When CI fails
+
+1. Open the failed GitHub Actions run for the **Visual snapshot tests** job.
+2. Download the `visual-test-results` artifact. It contains actual, expected, and diff images for failed comparisons.
+3. Decide whether the change is:
+   - **Unintended regression** — fix the CSS or layout and push again.
+   - **Intentional layout change** — update the snapshots (steps below).
+
+### Update snapshots
+
+Prefer refreshing baselines from CI so they match Linux rendering:
+
+1. Download the `visual-test-results` artifact from the failed job.
+2. Copy each `*-actual.png` from `test-results/` over the matching file in `tests/visual.spec.ts-snapshots/`.
+3. Commit the updated PNGs and push.
+
+For a local refresh (may still fail CI if fonts/rendering differ):
+
+```bash
+npm run test:visual:update
+```
+
+Review the changed PNGs, commit them with your layout change, and push. If CI still fails, replace baselines from the CI artifact as above.
+
+Renovate or Astro dependency bumps may fail this check. Updating snapshots is how you approve a new visual baseline.
+
+### Required status check
+
+After this workflow is on `master`, mark **Visual snapshot tests** as a required status check in GitHub branch protection so pull requests cannot merge when screenshots differ.