Feat/smoke env docs cleanup ci (#584)

* test: add Playwright smoke coverage for login and wallets

Adds tests/e2e/login.spec.ts and tests/e2e/wallets.spec.ts covering the
primary login (empty state, validation, success, failure) and wallet
monitoring (auth redirect, loading/error/empty/populated table, add
wallet modal, sidebar nav) paths, run against desktop and a narrow
mobile (Pixel 7) viewport via playwright.config.ts. Adds the
@playwright/test devDependency and test:e2e / test:e2e:ui scripts.

* docs: document frontend env vars in README

Adds a full environment variable reference table to README.md and a
companion docs/frontend-env-vars.md covering every NEXT_PUBLIC_* and
server-only var read by the app (src/lib/env.ts, src/lib/api/config.ts,
the auth/wallets API routes, and the analytics tracking hooks),
clarifies that network selection (testnet vs mainnet) is driven purely
by which backend NEXT_PUBLIC_API_URL points at, and expands
.env.example to list every documented variable with inline comments.

* docs: remove obsolete feature markdown clutter from root

Deletes 44 stale implementation-summary / PR-description / checklist
markdown files from the repo root (ADDRESS_*, ANALYTICS_*, RECOVERY_*,
WALLETS_UI_*, IMPLEMENTATION_*, etc.). They only ever cross-referenced
each other, were superseded by the current README and docs/ folder, and
made it hard to find the docs that actually matter. Points README.md at
docs/ for ongoing reference material and keeps the root to just README.md.

* ci: ensure next build passes typecheck in CI

Splits .github/workflows/ci.yml into typecheck, unit-tests, and a
testnet/mainnet build matrix (previously the workflow never ran the
Vitest suite in CI at all, and built only once against a single
hardcoded API URL). Adds a `typecheck` npm script so CI and local
runs use the identical command, excludes tests/e2e and
playwright.config.ts from the app tsconfig so Playwright's own types
don't leak into the strict app-wide tsc pass, and dedupes the
duplicate @storybook/* keys in package.json devDependencies. See
docs/ci-typecheck.md for the full rundown, including a follow-up note
that pnpm-lock.yaml still needs a local `pnpm install` to pick up the
@playwright/test devDependency added earlier in this branch.

---------

Co-authored-by: James Aklo <jamesjambox@gmail.com>

Author: levi0005

.env.example

@@ -1,3 +1,33 @@
-# Base URL for the Mux backend API (no trailing slash)
+# Frontend environment variables — see the "Environment variables" section
+# of README.md for full descriptions, defaults, and testnet/mainnet notes.
+# Copy this file to .env.local and fill in real values as needed; every
+# var here is optional in local development.
+
+# Base URL for the Mux backend API (no trailing slash).
+# Point at a testnet-configured backend for staging, or the production
+# backend for mainnet. Falls back to an in-repo mock when unset.
 # Example: https://api.muxprotocol.com
 NEXT_PUBLIC_API_URL=
+
+# Legacy alias for NEXT_PUBLIC_API_URL, checked second in the fallback chain.
+NEXT_PUBLIC_MUX_API_URL=
+
+# Public-facing URL of this application (used for absolute links).
+NEXT_PUBLIC_APP_URL=
+
+# Client-visible Mux Protocol API key. Never put secrets here — anything
+# prefixed NEXT_PUBLIC_ ships in client-side JS.
+NEXT_PUBLIC_MUX_API_KEY=
+
+# WalletConnect project ID, only needed if wallet-connect flows are enabled.
+NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID=
+
+# --- Server-only vars (never exposed to the browser) ---
+
+# Mux Protocol API key/secret used by Next.js API routes / server components.
+MUX_API_KEY=
+MUX_API_SECRET=
+
+# Database connection string, if this deployment persists data outside
+# the backend API.
+DATABASE_URL=

.github/workflows/ci.yml

@@ -15,8 +15,8 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  build-and-test:
-    name: Build and test
+  typecheck:
+    name: Typecheck
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -33,10 +33,69 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      # Runs `tsc --noEmit` against the same tsconfig.json used by `next
+      # build` (via the `next` compiler plugin), so a type error here is
+      # guaranteed to also fail the build step below. This job intentionally
+      # runs before build/test so type errors fail fast.
       - name: Typecheck
-        run: pnpm exec tsc --noEmit
+        run: pnpm run typecheck
+
+  unit-tests:
+    name: Unit tests (Vitest)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run unit/component tests
+        run: pnpm test
+
+  build:
+    name: Build (${{ matrix.network }})
+    needs: [typecheck, unit-tests]
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # `next build` type-checks and statically analyzes every route,
+        # including the API routes that branch on NEXT_PUBLIC_API_URL
+        # (see src/app/api/auth/login/route.ts and
+        # src/lib/api/config.ts::getApiBaseUrl()). Building once with a
+        # testnet-shaped URL and once with a mainnet-shaped URL catches
+        # env-specific breakage before it reaches either environment.
+        network: [testnet, mainnet]
+        include:
+          - network: testnet
+            api_url: https://testnet-api.example.com
+          - network: mainnet
+            api_url: https://api.example.com
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
 
       - name: Build
         run: pnpm run build
         env:
-          NEXT_PUBLIC_API_URL: https://api.example.com
+          NEXT_PUBLIC_API_URL: ${{ matrix.api_url }}

.gitignore

@@ -13,6 +13,10 @@
 
 # testing
 /coverage
+/playwright-report
+/test-results
+/blob-report
+/playwright/.cache
 
 # next.js
 /.next/