# GrokBoy Playwright helper (optional)

Thin Node script used by Rust `browser_*` tools (P3) and human handoff (P4).

## Install

```bash
cd tools/playwright
npm install
npx playwright install chromium
```

## Protocol

- **JSONL daemon** (default): one JSON request per stdin line → one JSON response on stdout.
- **One-shot**: `node browser_helper.mjs --cmd '{"op":"ping"}'`
- **Self-test** (no Chromium): `npm run self-test`

Ops: `ping`, `navigate`, `snapshot`/`dom`, `click`, `type`, `eval`, `close`, `status`, **`handoff_prepare`**.

### `handoff_prepare`

Ensures a **headed** (visible) Chromium window and brings it to front. If the daemon was headless, closes and relaunches headed, then navigates back to the last URL when possible.

Note: relaunch uses a new browser context (cookies from the prior headless session are not carried unless storage state is added later). Prefer `GROKBOY_BROWSER_HEADED=1` so the first launch is already headed and state survives across handoff within one run.

Env: `GROKBOY_BROWSER_HEADED=1` launches headed for normal navigate as well.

Prefer CSS selector or `role`+`name` over screenshots.