## v149 현재 기준 — 0.67 scale A marker 인지·Heart 비가림

- 버전: Heart `2.3.8.149`, 내부 VERSION `97`, ZIP `v217`.
- A marker의 노란 내부 면은 30 CSS px다. 감지 폭/높이 20/24/30px를 약 0.67/0.8/1.0 scale로 계산한다.
- DOM origin은 `A_center_screen - (22×scale_x,18×scale_y)`로 산출한다.
- visual marker 최소 component 크기를 15px로 내려 0.67 A를 legacy 10px marker로 오인하지 않는다.
- Heart 좌표창은 detected A component 오른쪽 8px 밖을 우선하며, 공간 부족 시 아래/왼쪽/창 clamp를 사용한다.
- 최초 A에서 확보한 안전 offset은 saved DOM delta 추적에도 유지한다.
- overlay click-through와 Heart의 origin 제공 전용 역할은 유지한다. 실제 마우스 이동/클릭은 하지 않는다.
- `test_heart8772_scale_safe_overlay_v217.py` 4개와 Heart 전체 8개 pytest OK. 실제 Windows 0.67은 `[검증대기]`.


## v191 현재 기준

- Ext MAIN world는 `window.screenX/window.screenY` 변화를 0.5초 주기로 감지한다. 크기 변화 없이 위치만 바뀌어도 `WINDOW_MOVING`으로 판단한다.
- 창 이동 감지 즉시 자동 OS 클릭을 보류하고 기존 origin cache를 무효화한다. 화면에는 `사용자 창 이동중.. 자동 보류`를 표시한다.
- 마지막 이동 후 10초간 위치 변화가 없으면 `WINDOW_STABLE`로 전환하고 WS에 `ig_heart_origin_refresh`를 요청한 뒤 원점찾기를 다시 수행한다.
- 재보정 성공 시 `ORIGIN_RECALIBRATION_OK`로 중단 지점의 자동 흐름을 재개한다. 실패 시 `ORIGIN_RECALIBRATION_FAILED`와 한국어 사유를 남기고 중단한다.
- WS는 실제 재보정 요청에 한해 `HEART_REQ`/`HEART_RES`를 간략히 기록한다. Heart도 `log_exchange=true` 요청에 한해서만 `ORIGIN_REQ`/`ORIGIN_RES`를 기록하여 평상시 snapshot 조회 로그 폭증을 막는다.
- 버전: IG `2.3.8.179a39`, WS `2.3.8.166a17`, Heart `2.3.8.148`, ZIP `v191`.

# Heart8772 현재 기준서

최신 기준: v149 / 2026-07-17
포트: `127.0.0.1:8772`
패키지 버전: `2.3.8.149`
Heart 내부 VERSION: `97`

## 현재 절대 원칙

- Heart8772는 DOM origin `(x,y)` snapshot 제공과 Chrome 추적만 담당한다.
- Heart8772는 실제 마우스 이동/클릭/다운로드 판단을 하지 않는다.
- WS8771이 Heart origin + IG_Ext client 좌표를 합산해 실제 OS 마우스 이동/클릭을 수행한다.
- JS가 보낸 `screen_x/screen_y`는 참고 로그로만 본다.
- Heart overlay는 기본 click-through 상태다. A/B/C/D 원점보정 marker의 hover/click을 가로채면 안 된다.

## v147 현재 변경 핵심

- 좌표 표시 박스 `x:..., y:...` 더블클릭 수동 초기화를 추가했다.
  - 메모리의 `_FOUND_X/_FOUND_Y`, `_DOM_DX/_DOM_DY`, watch point를 함께 무효화한다.
  - 표시값만 0 또는 reset으로 바꾸는 방식이 아니다.
  - 기본 click-through 실행에서는 Windows가 마우스 이벤트를 Chrome으로 넘기므로, 더블클릭 초기화는 `--interactive-overlay` 실행 시 동작한다.
- IPC reset 명령을 추가했다.
  - `heart8772_ipc.reset_heart_calibration()` 또는 TCP payload `{"act":"reset_calibration"}`로 Heart DOM 보정을 초기화할 수 있다.
  - 이 기능도 마우스를 이동하거나 클릭하지 않는다.
- 화면 밖/다른 모니터 이동 후 복원 때 저장 delta가 고착되는 문제를 줄였다.
  - 감시 포인트를 못 읽는 `None` 상태를 더 이상 정상 delta로 확정하지 않는다.
  - 감시 포인트가 없거나 캡처 실패하면 전체 재탐지를 시도한다.
  - 재탐지 실패 시 기존 overlay 위치 표시는 유지하되 snapshot `ok=True` click-safe 기준에서는 제외한다.
  - 마지막으로 확인한 Heart Chrome hwnd를 계속 검사해 foreground가 아니더라도 복원된 창을 다시 추적한다.

## 현재 origin 산출 우선순위

1. IG_Ext A/TL visual calibration marker를 우선 탐지한다.
   - A/TL center client = `(22,18)`
   - `dom_origin = A_center_screen - (22,18)`
2. A/TL이 없으면 legacy Heart 10px marker fallback을 사용한다.
3. legacy fallback은 반드시 `detected_marker - visual_offset`으로 DOM origin을 역산한다.
   - `dom_origin_x = detected_legacy_marker_x - visual_offset_x`
   - `dom_origin_y = detected_legacy_marker_y - visual_offset_y`
   - 현재 기본값: `visual_offset_x=44`, `visual_offset_y=0`
4. C/BL marker는 같은 왼쪽 열 보정 marker 확인/진단용으로만 기록한다.

## 현재 click-safe snapshot 기준

- `ok=True` 허용:
  - `YELLOW_DOM_ORIGIN`
  - `SAVED_DOM_DELTA_POINT_OK`
- `ok=True` 금지:
  - `WINDOW_ZERO`
  - `SAVED_DOM_DELTA_UNVERIFIED_SCAN_FAIL`
  - Chrome 창 미발견/대기/예외 상태

## 실행 옵션

- 기본 실행:
  - `python heart8772_position.py --host 127.0.0.1 --port 8772`
  - overlay는 click-through다.
- 좌표 박스 선택/복사/더블클릭 초기화가 필요할 때만:
  - `python heart8772_position.py --host 127.0.0.1 --port 8772 --interactive-overlay`
  - 일반 원점보정/자동화 중에는 이 옵션을 켜지 않는다.
- 시작 시에는 항상 오래된 DOM 보정을 신뢰하지 않고 초기화한다.

## 주요 파일 역할

- `heart8772_position.py`
  - Heart8772 본체, overlay, Chrome 추적, marker 탐지, snapshot server 포함.
- `heart8772_ipc.py`
  - Heart8772 snapshot client/helper.
  - `get_heart_snapshot()` 및 `reset_heart_calibration()` 제공.
- `heart8772_position_tracker.py`
  - Heart8772 폴더 내부 호환 import wrapper.
- `run_Heart8772.bat`
  - Heart8772 기본 click-through 실행 bat.

## 폐기/주의

- Heart 클릭 기능 금지.
- Heart 10px marker를 주 기준점으로 강제 의존하는 방향 금지.
- legacy 10px marker를 origin 자체로 보는 계산 금지. 현재는 `detected_marker - visual_offset`이다.
- Heart가 IG marker hover/click을 먹는 구조 금지.
- 감시 포인트 미확인/캡처 실패 상태의 저장 delta를 click-safe로 내보내는 구조 금지.
- JS `screen_x/screen_y` 직접 클릭 기준 금지.
- `rank_total` 의존 No 판단 금지.
- 전역 WS Enter 기본 켜기 금지.