LazyBoy2/tools/playwright/README.md

# 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.
P3: Playwright DOM browser tools (optional) 2026-09-13 07:57:57 +00:00			`# GrokBoy Playwright helper (optional)`

P4: human browser handoff + product notes 2026-09-13 08:15:27 +00:00			Thin Node script used by Rust `browser_*` tools (P3) and human handoff (P4).
P3: Playwright DOM browser tools (optional) 2026-09-13 07:57:57 +00:00
			`## 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`

P4: human browser handoff + product notes 2026-09-13 08:15:27 +00:00			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.
P3: Playwright DOM browser tools (optional) 2026-09-13 07:57:57 +00:00
			Prefer CSS selector or `role`+`name` over screenshots.