ci: add Lighthouse CI visual regression check to gate merges (Closes #941)

.github/workflows/ci.yml

@@ -1,13 +1,75 @@
 name: CI
+
 'on':
   push:
     branches:
     - main
   pull_request: null
+
+# Cancel in-progress runs for the same PR / branch when a new commit is pushed.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+env:
+  NODE_VERSION: '20'
+
 jobs:
+  # ─────────────────────────────────────────────────────────────────────
+  # Quality Gate — lint, type-check, unit tests, build
+  # ─────────────────────────────────────────────────────────────────────
   quality-gate:
     name: Quality Gate
     runs-on: ubuntu-latest
     steps:
-    - name: "Quality Gate (paused \u2014 CI stabilization in progress)"
-      run: echo 'Quality Gate check intentionally stubbed while main-branch CI is being stabilized.'
+    - name: Checkout
+      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+    - name: Setup Node.js ${{ env.NODE_VERSION }}
+      uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
+      with:
+        node-version: ${{ env.NODE_VERSION }}
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci --ignore-scripts
+
+    - name: Lint
+      run: npm run lint
+
+    - name: Type-check
+      run: npx tsc -b --noEmit
+
+    - name: Test
+      run: npm test
+
+    - name: Build
+      run: npm run build
+
+  # ─────────────────────────────────────────────────────────────────────
+  # Lighthouse CI — performance, accessibility, best-practices audit
+  # ─────────────────────────────────────────────────────────────────────
+  lighthouse:
+    name: Lighthouse CI
+    needs: quality-gate
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+    - name: Setup Node.js ${{ env.NODE_VERSION }}
+      uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
+      with:
+        node-version: ${{ env.NODE_VERSION }}
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci --ignore-scripts
+
+    - name: Build
+      run: npm run build
+
+    - name: Run Lighthouse CI
+      run: npx lhci autorun --config=./lighthouserc.json
+      env:
+        LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

README.md

@@ -171,6 +171,7 @@ See the [docs/](docs/) directory for detailed project documentation, including:
 - [Security Checklist](docs/SECURITY_CHECKLIST_FRONTEND.md) — CSP, storage, third-party scripts, and dependency posture for contributors.
 - [API Client Policies](docs/API_CLIENT_POLICIES.md) — Interceptors, retry policy, and error taxonomy for the API client.
 - [Cookie-Secret Rotation Runbook](docs/COOKIE_SECRETS.md) — Rotation cadence, blast radius, and step-by-step procedure for backend session/CSRF cookie secrets.
+- [Authentication Flows](docs/AUTH_FLOWS.md) — Sequence diagrams for login, logout, and session refresh flows.
 - [Hooks & Utilities Reference](docs/HOOKS.md) — Catalog of reusable hooks (`src/hooks/`) and helpers (`src/lib/`) with signatures and usage.
 - [Offline Strategy](docs/PWA.md) — What's cached, what's queued, and what happens on cache miss.
 - [Bundle Size Baseline](docs/BUNDLE.md) — Current production bundle sizes, per-route breakdowns, and profiling guide.

docs/README.md

@@ -121,7 +121,12 @@ This directory contains comprehensive design specifications and implementation g
     - Connection state machine and UX contract for connection/network states
     - Usage guide and network mismatch handling
 
-16. **[Security Checklist](./SECURITY_CHECKLIST_FRONTEND.md)**
+16. [Authentication Flows](./AUTH_FLOWS.md) ⭐ NEW
+    - Sequence diagrams for login (connect wallet), logout (disconnect), and session refresh (re-authentication)
+    - Session timeout (inactivity logout) flow
+    - Key code paths and cross-references
+
+17. **[Security Checklist](./SECURITY_CHECKLIST_FRONTEND.md)**
     - CSP policy, browser storage rules, third-party script posture, and dependency audit workflow
     - Concrete review checklist for each security area
       **[Settings Auto-Save Indicator](./auto-save.md)** ⭐ NEW (closes #564)
@@ -130,30 +135,30 @@ This directory contains comprehensive design specifications and implementation g
 - `<AutoSaveIndicator />` token-driven pill showing `Saving…` / `Saved just now` / "Couldn't save" with retry.
 - In-flight cancellation via `AbortController` so stale PATCHes can't overwrite newer state.
 
-16. **[Widget Cache & Per-Widget Refresh](./widget-cache.md)** ⭐ NEW (closes #561)
+18. **[Widget Cache & Per-Widget Refresh](./widget-cache.md)** ⭐ NEW (closes #561)
     - Shared in-app cache for dashboard widgets so a refresh button on one card only invalidates that card's key — others keep their state.
     - `useWidgetCache` hook + `<WidgetRefreshButton />` + token-driven styling.
     - Coverage includes mount, key isolation, error surfacing, and reduced-motion.
 
-17. **[API Client Policies](./API_CLIENT_POLICIES.md)** ⭐ NEW
+19. **[API Client Policies](./API_CLIENT_POLICIES.md)** ⭐ NEW
     - Interceptors, retry policy, and error taxonomy for the API client
     - `ApiError` structure and usage examples
 
-18. **[Bundle Size Baseline](./BUNDLE.md)** ⭐ NEW
+20. **[Bundle Size Baseline](./BUNDLE.md)** ⭐ NEW
     - Current production bundle size estimates and per-route breakdowns
     - Top 10 heaviest dependencies ranked by gzipped size
     - How to profile and compare bundle sizes with Vite, rollup-plugin-visualizer, and size-limit
     - Contributor guidelines for keeping the bundle lean
 
-19. **[Telemetry & Analytics](./telemetry.md)**
+21. **[Telemetry & Analytics](./telemetry.md)**
     - Privacy-first approach (no telemetry collected)
     - No PII handling or third-party analytics
 
-20. **[Offline Strategy](./PWA.md)**
+22. **[Offline Strategy](./PWA.md)**
     - What's cached (localStorage keys, in-memory widget cache), what's queued (pending transactions, auto-save retry), and what happens on cache miss
     - Offline-aware hooks (`useQuery`, `useWidgetCache`), offline banner, install prompt behaviour
 
-21. **[First Bond Coach Marks](./uiux/onboarding-coachmarks-first-bond.md)**
+23. **[First Bond Coach Marks](./uiux/onboarding-coachmarks-first-bond.md)**
     - First-run onboarding concept for creating a bond
     - Coach mark placement, copy, sequencing, and dismissal behavior
     - Accessibility, responsive behavior, and visual QA checklist