fix: 그리드 모드 click 좌표 단일 컬럼 가정 + getPageAtY X 무시 일괄 정정 (closes #685, #689)

[johndoekim]

Stacked on PR #645 (Task #595) — fix/issue-595-header-bbox-bleed 브랜치 위 cherry-pick. PR #645 머지 시 본 PR diff 가 자동으로 #685 + #689 commits 만 남음.

PR #645 의 후속 sweep (mydocs/troubleshootings/grid_mode_click_coord.md 진단노트) 에서 발견된 본 영역 결함 (#685, #689) 정합화. Task #685 + Task #689 합본 — 그리드 모드 click 좌표 한컴 호환 완성.

본질 결함 (2 영역)

Issue #685 — pageLeft 공식 단일 컬럼 가정 (14곳)

virtual-scroll.ts 는 zoom ≤ 0.5 + pages > 1 조건에서 다중 컬럼 그리드 (pageLefts[i] = marginLeft + col * (pw + gap)) 로 페이지 X 좌표를 열별 분리 저장. 그러나 input-handler-mouse.ts 의 14곳 모두 단일 컬럼 가정 공식 `(scrollContent.clientWidth - pageDisplayWidth) / 2` 사용 → 그리드 모드 click 좌표 ±수백 px 어긋남.

Issue #689 — getPageAtY 가 X 좌표 무시

`virtual-scroll.ts:133-140 getPageAtY(docY)` 가 Y 좌표만 보고 row 의 last page idx 만 반환 → non-last col 페이지 click 시 row 의 last col 페이지로 cursor 처리.

→ 두 결함이 결합되어야 그리드 모드 모든 col click 정합 (한컴 호환). #685 단독으로는 last col 만 정합. #685 발견 후 후속 sweep 으로 #689 등록.

한컴 호환 결함

한컴 오피스 그리드 모드 (다중 페이지 동시 보기) 는 모든 col 클릭 정상 처리 (사용자 직접 시연, 2026-05-07/08). RHWP 만 어긋남.

정정 영역

Task #685 — `getPageLeftResolved(pageIdx, containerWidth)` 헬퍼 도입 + 15곳 치환

• `virtual-scroll.ts` 헬퍼 신규 (+12 LOC): 그리드 `pageLefts[i]`, 단일 컬럼 `(containerWidth - pageWidth) / 2` fallback (sentinel −1 해소).
• `input-handler-mouse.ts` 14곳 + `input-handler.ts` 1곳 (`formBboxToOverlayRect` verbose sentinel 정리) = 15곳 헬퍼 일괄 치환.
• e2e (`grid-mode-click-coord.test.mjs`) 회귀 assert 추가 (last-col strict).

Task #689 — `getPageAtPoint(docX, docY)` 헬퍼 도입 + 18곳 치환 + 누락 10곳 동반 정정

• `virtual-scroll.ts` 헬퍼 신규 (+33 LOC): 단일 컬럼은 `getPageAtY` 동치, 그리드는 row(Y) 안에서 X 로 col 결정, gap 영역은 가장 가까운 페이지 fallback.
• 마우스 컨텍스트 18곳 `getPageAtY` → `getPageAtPoint` 치환: input-handler-mouse 12곳 + input-handler.ts 4곳 + table 1곳 + picture 1곳.
• Task rhwp-studio: zoom ≤ 0.5 그리드 모드 click 좌표 단일 컬럼 가정 — 14곳 분기 일괄 어긋남 #685 sweep 누락 buggy `pageLeft` 10곳 동반 정정 (작업지시자 추가 승인): input-handler.ts 4곳 + table 3곳 (L400/74/111) + picture 1곳 + connector 2곳 (L85/152). `getPageLeftResolved` 재사용 — 신규 좌표 계산 코드 0줄.
• e2e SKIP 분기 제거 → 모든 col strict assert 일원화. zoom=0.25 col 0~4 5건 모두 probe 추가.

회귀 영역 좁힘 (의도적 미수정)

• `canvas-view.ts` (vpCenter 2곳), `input-handler-keyboard.ts` (vpCenter 1곳) — viewport-center 의미 (X 무관) → `getPageAtY` 그대로 유지.
• `coordinate-system.ts:18` (`documentToPage`) — dead code (호출자 0건) → 미수정.
• `canvas-view.ts:156`, `field-marker-renderer.ts:84`, `caret-renderer.ts:127` — 기존 `getPageLeft` 호출 (raw accessor) 그대로 유지. 이미 그리드 인프라 정상 처리 중.

검증 (정량)

자동 검증 (모두 PASS)

검증 항목	결과
`npx tsc --noEmit`	✅ 무에러
`npx vite build`	✅ 성공 (85 modules transformed)
`body-outside-click-fallback.test.mjs --mode=headless`	✅ exit 0, 단일 컬럼 무회귀
`grid-mode-click-coord.test.mjs --mode=headless`	✅ PASS=21 / FAIL=0 / SKIP=0

Before vs After

케이스	Before	After
zoom=1.0 page 0 (single col)	rectPageIdx=0 ✅	rectPageIdx=0 ✅ (무회귀)
zoom=0.5 page 0 (col 0)	rectPageIdx=1 ❌	rectPageIdx=0 ✅
zoom=0.5 page 1 (col 1 last)	rectPageIdx=1 ✅	rectPageIdx=1 ✅
zoom=0.5 page 2 (col 0 row 1)	rectPageIdx=3 ❌	rectPageIdx=2 ✅
zoom=0.25 col 0~3 (non-last)	(어긋남)	모두 정합 ✅
zoom=0.25 col 4 (last)	rectPageIdx=4 ✅	rectPageIdx=4 ✅

시각 검증 (작업지시자 직접, 2026-05-08)

`samples/hwpctl_action_table_v11.hwp` 그리드 모드 (zoom=0.5, columns=3) — 이전 보고된 "1, 2 페이지 클릭 안 됨" 결함 정합화. 작업지시자 평가: "오 정상적으로 잘 된다."

코드 품질 결정 (작업지시자 review, 2026-05-08)

`getPageLeftResolved(pageIdx, containerWidth)` API 의 `containerWidth` 인자 leaky abstraction 검토 — Option A (현재, stateless click 시점 `clientWidth` 직접 사용) vs Option B (`setPageDimensions` 시점 단일 컬럼도 실좌표 저장) 비교.

결정: Option A 유지. 이유:

• A 는 stateless — race condition 없음, ResizeObserver 누락 케이스 robust, 미래 코드 변경 시 fragile 안 함
• B 는 stateful — `pageLefts[i]` cache 가 setPageDimensions 호출에 의존
• verbose trade-off 보다 robustness 우선

회귀 위험 영역

영역	위험	결과
단일 컬럼 모드 (zoom > 0.5)	헬퍼 fallback 식 회귀	✅ OK — 명시 분기 + e2e 무회귀
그리드 모드 last-col	#685 정합 영역	✅ OK — strict assert 통과
그리드 모드 non-last col	본 PR 의 본질 효과	✅ OK — 모든 col strict assert 통과
양식 오버레이 (`formBboxToOverlayRect`)	헬퍼 적용 동치성	✅ OK — body-outside-click-fallback 무회귀
viewport-center (canvas-view, keyboard)	미수정 영역	✅ OK — 기능 무관

산출물 (mydocs/)

• `mydocs/plans/task_m100_{685,689}.md` (수행계획서 2종)
• `mydocs/plans/task_m100_{685,689}_impl.md` (구현계획서 2종)
• `mydocs/working/task_m100_{685,689}_stage{1,2,3}.md` (단계 보고서 6종)
• `mydocs/report/task_m100_{685,689}_report.md` (최종 결과 보고서 2종)
• `mydocs/troubleshootings/grid_mode_click_coord.md` (진단노트, "완전 정정 완료 (rhwp-studio: zoom ≤ 0.5 그리드 모드 click 좌표 단일 컬럼 가정 — 14곳 분기 일괄 어긋남 #685 + rhwp-studio: 그리드 모드 getPageAtY가 row 안에서 X 좌표 무시 — non-last col 페이지 click 시 잘못된 pageIdx 반환 #689 결합)" 섹션 추가)
• `mydocs/orders/20260508.md` (5/8 오늘 할일)

코드 변경 (rhwp-studio)

• `src/view/virtual-scroll.ts` (+45 LOC: getPageLeftResolved + getPageAtPoint)
• `src/engine/input-handler-mouse.ts` (12곳 getPageAtY + 14곳 pageLeft)
• `src/engine/input-handler.ts` (4곳 getPageAtY + 5곳 pageLeft)
• `src/engine/input-handler-table.ts` (1곳 getPageAtY + 3곳 pageLeft)
• `src/engine/input-handler-picture.ts` (1곳 getPageAtY + 1곳 pageLeft)
• `src/engine/input-handler-connector.ts` (2곳 pageLeft)
• `e2e/grid-mode-click-coord.test.mjs` (assert 강화 + 모든 col probe)

closes #685
closes #689