# task-196.1: 브라우저 제어 유틸리티 스크립트

## 목적
아누가 텔레그램 환경에서 웹페이지를 직접 탐색(클릭/스크롤/입력/캡처)할 수 있는 도구 구축.
Playwright headless Chromium 기반.

## 요구사항

### 핵심 기능 (Python CLI 스크립트)
`/home/jay/workspace/scripts/browser.py` 에 구현

**명령어 구조:**
```
python3 scripts/browser.py <command> [options]
```

**필수 명령어:**
1. `navigate <url>` — 페이지 이동 + 자동 스크린샷
2. `click <selector>` — CSS 선택자 또는 텍스트로 요소 클릭 + 스크린샷
3. `type <selector> <text>` — 입력 필드에 텍스트 입력 + 스크린샷
4. `scroll <direction>` — up/down/top/bottom 스크롤 + 스크린샷
5. `screenshot` — 현재 상태 캡처
6. `screenshot --full` — 전체 페이지 캡처
7. `eval <js>` — JavaScript 실행 (DOM 조작 등)

**옵션:**
- `--output <path>` — 스크린샷 저장 경로 (기본: `/home/jay/workspace/dashboard/screenshot-live.png`)
- `--wait <ms>` — 동작 후 대기 시간 (기본: 1000ms)
- `--viewport <width>x<height>` — 뷰포트 크기 (기본: 1280x720)
- `--timeout <ms>` — 페이지 로드 타임아웃 (기본: 10000ms)

### 세션 관리
- 브라우저 컨텍스트를 `/tmp/playwright-session.json`에 저장하여 연속 명령 시 세션 유지
- `navigate`는 새 세션 시작 또는 기존 세션에서 이동
- 세션이 없으면 자동 생성, 있으면 재사용
- `close` 명령으로 세션 명시적 종료

### 출력 형식
- 항상 JSON 출력: `{"status": "ok", "screenshot": "<path>", "url": "<current_url>", "title": "<page_title>"}`
- 에러 시: `{"status": "error", "message": "..."}`
- 클릭/입력 시 대상 요소 정보 포함: `{"element": "<tag>", "text": "<visible_text>"}`

### 기술 스택
- Python 3 + playwright (async)
- `pip install playwright` 로 설치 (브라우저는 이미 설치됨: `~/.cache/ms-playwright/chromium-1208`)
- headless 모드 기본, `--headed` 옵션은 불필요 (서버 환경)

### 편의 기능
- `click`에서 CSS 선택자 대신 **텍스트 매칭** 지원: `click --text "로그인"` → 해당 텍스트를 가진 요소 클릭
- `click --nth 2` — 동일 선택자 중 N번째 요소
- 클릭 전 요소 하이라이트 (빨간 테두리) 후 스크린샷 → 어디를 클릭했는지 시각적 확인

### 제약사항
- 200줄 이하 (모듈화 원칙)
- 외부 패키지 최소화 (playwright만)
- 표준 라이브러리 적극 활용

## 테스트
- 대시보드(`http://100.76.130.39:8000/dashboard/`)에서 실제 동작 테스트
  - navigate → screenshot 정상
  - click으로 요소 클릭 → 상태 변화 캡처
  - scroll down → 스크린샷 변화 확인
- 존재하지 않는 선택자 클릭 시 에러 JSON 반환 확인

## 참고
- 한글 폰트 설치 완료: `~/.local/share/fonts/NotoSansCJKkr-Regular.otf`
- Chromium 경로: `~/.cache/ms-playwright/chromium-1208`
- Playwright 버전: 1.58.2