# ui-reference-lab

X 에서 본 UI·인터랙션을 던지면 에이전트(Codex / Claude Code)가 실행 가능한 단일 파일 데모로 재현해 쌓고, 어느 개발 세션에서든 MCP 로 "용도"로 검색해 꺼내 쓰는 루프. **독립 R&D** (2026-09-14 시작, 로컬 단독).

- 왜·무엇: [PROJECT.md](PROJECT.md) · 어떻게: [DESIGN.md](DESIGN.md) · 진행 기록: `docs/` (m1-report · m2-report · m3-log)
- 저장 단위는 **사례** `cases/<id>/` = `index.html`(데모) · `notes.md`(배운 것) · `design-decisions.json`(팔레트·이징·지속시간·간격) · `meta.json`(용도 색인·게이트·비용) · 렌더 2장
- 원본 미디어는 `private/`(미추적) 밖으로 나가지 않는다. `public:false` 기본.
- `ledger/` 는 런·호출 원장 스냅숏이다. DB(`uiref.db`)는 미추적이라 새로 받은 리포는 여기서 원장을 되살린다.

## 새로 받은 리포에서

```bash
uv sync && uv run playwright install chromium
uv run uiref index --all     # cases/ 로 검색 색인을 만들고, 비어 있는 런·호출 원장을 ledger/ 에서 채운다
uv run uiref searcheval      # 검색 회귀 시험
uv run uiref app             # app/index.html (작동 방식 · 사례 · 검색 · 원장)
```

재현(`reproduce` · `drain`)에는 codex 또는 claude CLI 로그인과 ffmpeg · yt-dlp 가 따로 필요하다. 원장 스냅숏 갱신은 `uv run uiref ledger export`.

## 빠른 시작

```bash
uv sync && uv run playwright install chromium
uv run uiref add "https://x.com/<user>/status/<id>" --id 2026-09-14-<slug> --note "한 줄 메모" --panel "2x3:1"
uv run uiref fetch 2026-09-14-<slug> && uv run uiref frames 2026-09-14-<slug>
uv run uiref capture 2026-09-14-<slug> --steps steps.json   # 필요형: 실제 페이지를 조작하며 직접 녹화(발견형 fetch 의 짝). --setup · --subject · --panel 은 DESIGN §2.1
uv run uiref inbox                                          # 폰 인테이크(UIREF_INBOX 폴더) 비우기. drain 이 시작할 때 자동으로 먼저 부른다
uv run uiref searcheval                                     # 검색 회귀 시험: 원장 질의로 동의어 끔/켬 순위 비교
uv run uiref app                                            # 표면 웹앱 app/index.html: 작동 방식·사례·검색·원장 (로컬 · 배포 안 함)
uv run uiref reproduce 2026-09-14-<slug> --engine both     # codex · claude 각각 사례 생성 + 게이트 + 재시도 1회 + 색인
uv run uiref rate 2026-09-14-<slug>-codex --layout 재현 --motion 근사   # 사람 판정 (L3)
uv run uiref mcp                                            # http://127.0.0.1:8787/mcp · Bearer 토큰 ~/.uiref/token
uv run uiref runs                                           # 실행 원장 (엔진·토큰·초·설정읽기·고아·게이트)
uv run uiref probe --engine both                            # 배치 앞 엔진 가용성 (죽었으면 건너뛴다. 종료 코드만 보지 않고 is_error 도 본다)
uv run uiref usage <세션 작업 디렉터리>                       # 산출물에서 어느 사례가 쓰였는지 (feedback 호출률 1/4 라 그것에 기대지 않는다)
uv run uiref gaps                                           # calls 원장에서 찾았는데 못 찾은 것 (검색만 하고 get 이 없으면 결핍)
```

에이전트 등록(문법 실측): `claude mcp add --transport http ui-reference-lab http://127.0.0.1:8787/mcp -H "Authorization: Bearer $(cat ~/.uiref/token)"` · `codex mcp add ui-reference-lab --url http://127.0.0.1:8787/mcp --bearer-token-env-var UIREF_TOKEN`

## 게이트

G1 스키마 · G2 자립(외부 참조 0) · G3 렌더(Playwright 실제 브라우저, 1280·390, 콘솔 오류·가로 오버플로·외부 요청) · G4 모션(**실시간** 3시점 피사체 변위). 가상시간으로 모션을 판정하지 않는다. 게이트는 증거를 남기고, 재현 품질은 사람이 `rate` 로 판정한다.