fix: 컴포넌트 binding audit + 14건 수정 + props 11개 추가

[zeakd]

Summary

전체 컴포넌트의 props ↔ SDK 결합 audit + 2회 코드 리뷰 후속 + 외부 패턴 리서치까지 반영한 종합 라운드.

SDK 옵션 저장 패턴(A: _mapOptions 분리 / B: setX 부수효과 / C: _<key>_changed / D: 일방향·static) 정립.

3 commits: 2480ec0 (1차) → f470669 (1차 리뷰 후속 A-D) → 7348f88 (2차 리뷰 후속).

라이브러리 코어

• useControlledKVO: setter 우선순위 setX > setOptions > set. Map은 옵션을 별도 _mapOptions KVO에 저장하므로 직접 target.set()으론 SDK가 무시. setMapTypeId처럼 부수효과 있는 setX는 우선 사용.
• useKVO: Map의 옵션 키 구독을 _mapOptions로 라우팅. useKVO(map, 'draggable') 등 정상 발화 수신.
• kvoEquals: 양쪽 모두 시도 (prev=literal, new=instance 비대칭 해소)

컴포넌트 버그 수정

컴포넌트	변경
NaverMap	minZoom/maxZoom static → controlled
NaverMap	onInit/onIdle/onTilesloaded useEffect → useLayoutEffect (init 박빙 방지)
NaverMap	logoControl 일방향 controlled 분류 정밀화 + dev warn (한 번만, ref 가드)
TrafficLayer	autoRefresh undefined 시 endAutoRefresh 호출 안 함
InfoWindow	setOptions(obj) 일괄 → per-key useControlledKVO
InfoWindow	onOpen/onClose listener를 useLayoutEffect로 (방어적, fix-16)
GroundOverlay	SDK 미발화 이벤트(dblclick/mouseover/out/move) 타입 축소
CustomOverlay	pane static 명시 + position/anchor kvoEquals 비교

신규 controlled props (11개)

• NaverMap: cursor, tilt (+onTiltChanged), rotation (+onRotationChanged), tileDuration
• NaverMap static: repeatX, gl, customStyleId, useStyleMap
• GroundOverlay: crossOrigin
• Polygon/Polyline: simplifyLevel

개발자 경험

• 신규 internal hook useStaticProp: dev/prod 함수 선택 패턴으로 production DCE 시도. undefined grace period로 비동기 prop 패턴({config?.gl}) false positive 방지.
• DCE 실측 통과: Astro/Vite production 빌드에서 'static prop', 'useStaticPropDev', 한국어 dev warn 모두 0건 ✓
• 메시지 영문 + 한국어 병기: 외부 라이브러리(downshift/react-aria 등)는 영문만 — 1.0에서 영문 통일 검토

이벤트 등록 시점 정책 (fixes/16)

• SDK 동기 발화 (init/idle/open/close/tilesloaded): useLayoutEffect로 등록
• 사용자 인터랙션 (click/drag 등): useEffect 등록 OK
• audit 결과: 우리 노출 props 모두 적정 처리 (research/bindings/sync-fired-events-audit.md)

회귀 테스트

121 → 160 tests 통과 (25 files, +39 신규).

신규 회귀 테스트:

• naver-map-controlled.spec.tsx — fix 01/02/05/13/15
• info-window.spec.tsx 보강 — fix 08, fix-16 timing
• traffic-layer.spec.tsx 보강 — fix 07
• event-types.spec.ts 강화 — fix 09 (toEqualTypeOf)
• custom-overlay.spec.tsx 보강 — fix 10
• hooks/__tests__/use-kvo.spec.tsx — fix 06
• hooks/__tests__/use-static-prop.spec.tsx — fix 14 + grace period
• __tests__/strict-mode.spec.tsx 신규 — StrictMode 더블 마운트 7건
• __tests__/kvo-equals.spec.ts — 양쪽 비교

외부 패턴 리서치 (related-patterns-research.md)

4개 라이브러리 비교 (@react-google-maps/api, react-map-gl, react-leaflet, @react-three/fiber):

• react-map-gl과 가장 정렬 — useIsomorphicLayoutEffect + per-prop diff
• downshift의 initial-/default- prefix가 가장 깔끔 — 0.3에서 하이브리드 도입 검토
• useSyncExternalStore caveat 확인: 매 프레임 mutate 시 blocking으로 떨어짐 → 우리 useControlledKVO 재설계(dirty diff) 결정 정당화
• 0.3 후보: initial- prefix, useKVOFrame (RAF throttle), DCE 가드 표준화
• 1.0 후보: 영문 통일, Activity 호환성 명시, 번들 검사 CI

Breaking 가능성 (사실상 없음)

변경	영향
GroundOverlay 이벤트 타입 축소	SDK 미발화 이벤트라 실제 영향 0
CustomOverlay pane 변경 무시 명시	이전에도 무시됨

Changeset

patch bump (0.2.0 → 0.2.1).

보류 결정 (decisions/)

• CompassControl: SDK 번들에 클래스 정의 없음 (legacy stub) — 미노출

🤖 Generated with Claude Code