feat(frontend): add visual diff tooling for UI PR reviews

.github/workflows/visual-diff.yml

@@ -0,0 +1,145 @@
+name: Visual diff
+
+concurrency:
+  group: visual-diff-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+on:
+  pull_request:
+    types:
+      - opened
+      synchronize
+      reopened
+      labeled
+      unlabeled
+      edited
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    outputs:
+      requested: ${{ steps.check.outputs.requested }}
+    steps:
+      - name: Detect visual diff request
+        id: check
+        env:
+          PR_LABELS: ${{ toJson(github.event.pull_request.labels) }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          requested=false
+          if printf '%s' "$PR_LABELS" | grep -q '"name": "visual-change"'; then
+            requested=true
+          elif printf '%s' "$PR_BODY" | grep -q '<!-- visual-diff:required -->'; then
+            requested=true
+          fi
+          echo "requested=${requested}" >> "$GITHUB_OUTPUT"
+
+  visual-diff:
+    needs: check
+    if: needs.check.outputs.requested == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    name: Generate visual diff report
+    steps:
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24.x
+
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup bun
+        run: bash scripts/setup-bun.sh
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Install Playwright browser
+        run: bunx playwright install --with-deps chromium
+
+      - name: Install Supabase CLI
+        uses: supabase/setup-cli@v2
+        with:
+          version: 2.84.2
+
+      - name: Link Supabase templates
+        run: ln -sfn supabase/templates templates
+
+      - name: Run visual diff pipeline
+        run: |
+          bun scripts/visual-diff.ts run \
+            --base "${{ github.event.pull_request.base.sha }}" \
+            --head "${{ github.event.pull_request.head.sha }}"
+
+      - name: Upload visual diff report
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: visual-diff-report-${{ github.event.pull_request.head.sha }}
+          path: .context/visual-diff/report/
+          if-no-files-found: ignore
+          retention-days: 14
+
+      - name: Comment visual diff summary on PR
+        if: always()
+        uses: actions/github-script@v8
+        env:
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          JOB_STATUS: ${{ job.status }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          ARTIFACT_NAME: visual-diff-report-${{ github.event.pull_request.head.sha }}
+        with:
+          script: |
+            const fs = require('node:fs')
+            const path = require('node:path')
+            const marker = '<!-- capgo-visual-diff -->'
+            const issue_number = context.payload.pull_request.number
+            const summaryPath = path.join(process.env.GITHUB_WORKSPACE, '.context/visual-diff/report/summary.md')
+            const ok = process.env.JOB_STATUS === 'success'
+            const summary = fs.existsSync(summaryPath)
+              ? fs.readFileSync(summaryPath, 'utf8').trim()
+              : 'Visual diff did not produce a report. Check the workflow logs and artifacts.'
+
+            const body = [
+              marker,
+              `## Visual diff ${ok ? 'passed' : 'failed'}`,
+              '',
+              summary,
+              '',
+              `Commit: \`${process.env.HEAD_SHA}\``,
+              `[Download the HTML report from workflow artifacts](${process.env.RUN_URL}) (artifact: \`${process.env.ARTIFACT_NAME}\`).`,
+              '',
+              'Open `index.html` from the artifact for side-by-side before/after/diff screenshots.',
+            ].join('\n')
+
+            const { owner, repo } = context.repo
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner,
+              repo,
+              issue_number,
+              per_page: 100,
+            })
+            const existing = comments.find(comment => comment.body?.includes(marker))
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner,
+                repo,
+                comment_id: existing.id,
+                body,
+              })
+            }
+            else {
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number,
+                body,
+              })
+            }

.gitignore

@@ -33,6 +33,7 @@ fastlane/metadata/review_information/phone_number.txt
 
 test-results
 playwright-report
+.context/visual-diff
 playwright/.cache
 playwright/.auth
 CHANGELOG.md

AGENTS.md

@@ -753,6 +753,46 @@ Key points:
   `playwright/e2e` and run them locally with `bun run test:front` before
   shipping UI changes.
 
+### Visual diff for UI changes
+
+When a PR changes customer-facing UI (layout, spacing, colors, components, or
+copy placement), reviewers need a before/after screenshot diff.
+
+**Request the automated PR report** by either:
+
+- adding the `visual-change` label to the PR, or
+- including `<!-- visual-diff:required -->` anywhere in the PR description.
+
+On each push, the `Visual diff` GitHub Action captures screenshots from the PR
+base commit and head commit, generates a diff report, uploads it as a workflow
+artifact, and updates a sticky PR comment (`<!-- capgo-visual-diff -->`).
+
+**Local workflow before opening or updating the PR:**
+
+1. Capture the current UI baseline: `bun run visual:capture:before`
+2. Apply your UI edits and rebuild or refresh the local app as needed.
+3. Capture the updated UI: `bun run visual:capture:after`
+4. Generate the report: `bun run visual:diff`
+5. Paste `.context/visual-diff/report/summary.md` into the PR description under
+   `## Visual changes`.
+6. Add the `visual-change` label (or the HTML marker above) so CI refreshes the
+   report on every push.
+
+**Full local pipeline against `main`:**
+
+```bash
+bun run visual:run -- --base origin/main
+```
+
+**Route configuration:** edit `playwright/visual-diff.config.ts` when a PR
+introduces a new screen that should be part of the visual diff set.
+
+**Outputs:**
+
+- `.context/visual-diff/before/` and `after/` — raw PNG captures
+- `.context/visual-diff/report/index.html` — side-by-side before/after/diff view
+- `.context/visual-diff/report/summary.md` — markdown table for the PR body
+
 ## Mobile Development
 
 ### Capacitor Configuration

package.json

@@ -68,6 +68,10 @@
     "files:prod": "wrangler dev -c cloudflare_workers/files/wrangler.jsonc --env=prod --env-file=internal/cloudflare/.env.prod",
     "stripe:emulator": "bun scripts/serve-stripe-emulator.ts",
     "init:playwright": "bunx playwright install",
+    "visual:capture:before": "bun scripts/visual-diff.ts capture --phase before",
+    "visual:capture:after": "bun scripts/visual-diff.ts capture --phase after",
+    "visual:diff": "bun scripts/visual-diff.ts diff",
+    "visual:run": "bun scripts/visual-diff.ts run",
     "test:front": "bun scripts/run-playwright-tests.ts",
     "test:local": "bun run test:all",
     "test:coverage:all": "bun run cli:build && bun run supabase:with-env -- bunx vitest run --coverage.enabled=true tests/*",
@@ -355,6 +359,8 @@
     "jose": "^6.2.3",
     "knip": "^6.17.1",
     "oxlint": "^1.70.0",
+    "pixelmatch": "^7.2.0",
+    "pngjs": "^7.0.0",
     "sass": "1.101.0",
     "simple-git-hooks": "^2.13.1",
     "supabase": "^2.106.0",

playwright/visual-diff.config.ts

@@ -0,0 +1,24 @@
+export interface VisualDiffRoute {
+  slug: string
+  path: string
+  /** When true, logs in as test@capgo.app before visiting the route. */
+  auth?: boolean
+}
+
+/**
+ * Console pages captured for before/after visual diffs.
+ * Add routes here when a PR touches a new screen reviewers should compare.
+ */
+export const visualDiffRoutes: VisualDiffRoute[] = [
+  { slug: 'login', path: '/login/', auth: false },
+  { slug: 'dashboard', path: '/dashboard', auth: true },
+  { slug: 'apps', path: '/apps', auth: true },
+  { slug: 'app-overview', path: '/app/com.demo.app', auth: true },
+  { slug: 'channels', path: '/app/com.demo.app/channels', auth: true },
+  { slug: 'devices', path: '/app/com.demo.app/devices', auth: true },
+]
+
+export const visualDiffViewport = {
+  width: 1280,
+  height: 720,
+} as const