Here is the **definitive, consolidated guide** for setting up Playwright on **Arch Linux (WSL)**.

This summary skips the trial-and-error we just went through and provides the "Happy Path" to get everything working in one go.

---

### 📋 Prerequisites
*   **WSL 2** (Recommended).
*   **Proxy (Optional):** If you are behind a proxy, remember to use `sudo -E` to preserve environment variables.

---

### 🚀 Step 1: System Prep & Node.js
First, ensure your package database is fresh (fixes 404 errors) and install Node.js.

```bash
# Update system and install Node.js/npm
# Use -E if you have https_proxy set in your shell
sudo -E pacman -Syu nodejs npm
```

### 📦 Step 2: Install System Dependencies (The Critical Step)
**Do not** use `npx playwright install-deps` (it fails on Arch). Instead, install these packages manually. This list includes all the X11, Graphics, and Network libraries required by Chromium, Firefox, and WebKit.

```bash
sudo -E pacman -S --needed \
    git \
    nss \
    nspr \
    libdrm \
    alsa-lib \
    mesa \
    gtk3 \
    at-spi2-core \
    pango \
    cairo \
    gdk-pixbuf2 \
    libx11 \
    libxcomposite \
    libxdamage \
    libxext \
    libxfixes \
    libxrandr \
    libxcursor \
    libxi \
    libxrender \
    libxcb \
    freetype2 \
    fontconfig \
    ffmpeg
```

### 🛠️ Step 3: Initialize Playwright
Set up your project and download the browser binaries (these are separate from the system libs above).

```bash
# Create project directory
mkdir my-tests && cd my-tests

# Initialize (Select TypeScript/JavaScript as preferred)
npm init playwright@latest

# If prompted to "Install Playwright browsers", select True.
# If you need to install them manually later:
npx playwright install
```

### ✅ Step 4: Run Tests
You are now ready to run.

```bash
npx playwright test
```

---

### 💡 Troubleshooting Cheat Sheet

| Issue                     | Solution                                                                          |
| :------------------------ | :-------------------------------------------------------------------------------- |
| **`install-deps` fails**  | **Ignore it.** It only supports Ubuntu. Use the `pacman` command in Step 2.       |
| **`libxxx.so not found`** | You are missing a package. Use `pkgfile libxxx.so` to find the Arch package name. |
| **404 Errors (Pacman)**   | Your mirrors are out of sync. Run `sudo pacman -Syu` to refresh.                  |
| **Browser won't launch**  | Ensure `nspr` and `nss` are installed (included in Step 2).                       |
| **GUI/Headless issues**   | If visual mode fails, try `xvfb-run npx playwright test`.                         |