# Setup

## What you need

| Requirement | Why | Have it already? |
|---|---|---|
| Python 3 (any recent version, 3.9+ recommended) | `capture.py` is a plain Python script | Run `python3 --version` to check |
| pip | installs the `playwright` package | ships with Python 3 |
| The `playwright` pip package | drives a real browser to render pages | installed in Step 2 below |
| Chromium browser binary (via `playwright install chromium`) | Playwright needs its own downloaded browser — a system Chrome/Safari install does NOT count | installed in Step 3 below, this is the step people forget |
| Internet access | the script loads the URL you point it at | — |

**NOT needed:** no Docker, no account/login, no API key, no GPU, no `.env` file. The script only talks to the target website you give it — nothing else. It runs fine on macOS, Linux, or Windows (no macOS-only APIs are used, even though the script's fake browser user-agent string mentions "Macintosh" — that's just what it tells the target site, not a requirement of your machine).

## Install, step by step

1. **Install Python 3** (skip if `python3 --version` already prints 3.9 or higher).

   macOS (Homebrew):
   ```bash
   brew install python
   ```
   If you don't have Homebrew yet:
   ```bash
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   ```
   Windows / Linux: download from https://www.python.org/downloads/ (Windows) or use your package manager, e.g. `sudo apt install python3 python3-pip` (Debian/Ubuntu).

   Check it worked:
   ```bash
   python3 --version
   ```
   Expected output: something like `Python 3.11.6` (any 3.x version is fine).

2. **Install the Python dependency (`playwright`).** From the repo root:
   ```bash
   pip3 install -r requirements.txt
   ```
   This installs the `playwright` package, which is what drives the headless browser.

   Check it worked:
   ```bash
   python3 -c "import playwright; print('playwright ok')"
   ```
   Expected output: `playwright ok`

3. **Download the Chromium browser Playwright actually drives.** This is a separate step from installing the `playwright` pip package — the package is just the automation library, it does not come with a browser.
   ```bash
   playwright install chromium
   ```
   Windows / Linux: same command, works identically once step 2 is done.

   Check it worked:
   ```bash
   playwright install chromium --dry-run
   ```
   Expected output: reports Chromium is already installed (no download triggered). If you'd rather just confirm visually, re-running `playwright install chromium` a second time will print "chromium is already installed" instead of downloading again.

## Configure

Nothing to configure. There is no `.env` file, no API key, and no account to sign into. The script only contacts the URL you pass it on the command line.

## Run it

From the repo root:
```bash
python3 capture.py https://example.com
```

What success looks like — the script prints:
```
→ capturing https://example.com
→ output: /path/to/design-capture/captures/example
✓ done — /path/to/design-capture/captures/example
  screenshots, rendered.html, tokens.json, REPORT.md, N stylesheets
```
and a new folder `captures/example/` appears containing `desktop-full.png`, `mobile-full.png`, `rendered.html`, `tokens.json`, `REPORT.md`, and a `css/` folder of downloaded stylesheets.

Optional second argument to control the output folder name:
```bash
python3 capture.py https://example.com my-study
```

## Troubleshooting

- **`Executable doesn't exist at .../chromium-.../chrome` or similar Playwright browser-not-found error** — you installed the `playwright` pip package but skipped the browser download. Run `playwright install chromium` (Step 3 above) and try again.
- **`ModuleNotFoundError: No module named 'playwright'`** — you ran `python3 capture.py ...` with a different Python/pip than the one you installed the package into (common with multiple Python installs, or a venv that isn't active). Confirm with `python3 -c "import playwright"`; if that fails, re-run `pip3 install -r requirements.txt` using the same `python3`/`pip3` you use to run the script (or create and activate a virtualenv first: `python3 -m venv .venv && source .venv/bin/activate` on macOS/Linux, `.venv\Scripts\activate` on Windows).
- **Script hangs or times out on `page.goto(...)`** — the target site is slow, blocking headless browsers, or unreachable. The script gives up after 60 seconds with a timeout error; try a different URL to confirm the tool itself works, or check your network connection.