@mint-ui/map 1.2.0-test.33 → 1.2.0-test.35

package/dist/index.umd.js

@@ -800,6 +800,30 @@
 
   /**
    * 폴리곤 offset 계산
+   *
+   * GeoJSON MultiPolygon 형식의 위경도 좌표를 화면 픽셀 좌표로 변환합니다.
+   *
+   * @param polygonData 폴리곤 데이터 (paths 필드 필수)
+   * @param controller MintMapController 인스턴스
+   * @returns 변환된 화면 좌표 배열 (4차원 배열) 또는 null (변환 실패 시)
+   *
+   * @remarks
+   * - 반환 형식: [MultiPolygon][Polygon][Point][x/y]
+   * - 성능: O(n), n은 폴리곤의 총 좌표 수
+   * - GeoJSON MultiPolygon 형식 지원
+   *
+   * @example
+   * ```typescript
+   * const offsets = computePolygonOffsets(polygonData, controller);
+   * if (!offsets) return; // 변환 실패
+   *
+   * // offsets 구조: [MultiPolygon][Polygon][Point][x/y]
+   * for (const multiPolygon of offsets) {
+   *   for (const polygon of multiPolygon) {
+   *     // polygon은 [Point][x/y] 배열
+   *   }
+   * }
+   * ```
    */
 
   var computePolygonOffsets = function (polygonData, controller) {
@@ -836,6 +860,23 @@
   };
   /**
    * 마커 offset 계산
+   *
+   * 마커의 위경도 좌표를 화면 픽셀 좌표로 변환합니다.
+   *
+   * @param markerData 마커 데이터 (position 필드 필수)
+   * @param controller MintMapController 인스턴스
+   * @returns 변환된 화면 좌표 (Offset) 또는 null (변환 실패 시)
+   *
+   * @remarks
+   * - 반환된 좌표는 마커의 중심점 (x, y)
+   * - 성능: O(1) - 단일 좌표 변환
+   *
+   * @example
+   * ```typescript
+   * const offset = computeMarkerOffset(markerData, controller);
+   * if (!offset) return; // 변환 실패
+   * // offset.x, offset.y는 화면 픽셀 좌표
+   * ```
    */
 
   var computeMarkerOffset = function (markerData, controller) {
@@ -847,6 +888,24 @@
   };
   /**
    * Point-in-Polygon 알고리즘
+   *
+   * Ray Casting 알고리즘을 사용하여 점이 폴리곤 내부에 있는지 확인합니다.
+   *
+   * @param point 확인할 점의 좌표
+   * @param polygon 폴리곤 좌표 배열 (각 요소는 [x, y] 형식)
+   * @returns 점이 폴리곤 내부에 있으면 true, 아니면 false
+   *
+   * @remarks
+   * - **알고리즘**: Ray Casting (Ray Crossing)
+   * - **성능**: O(n), n은 폴리곤의 좌표 수
+   * - **경계 처리**: 경계선 위의 점은 내부로 간주
+   *
+   * @example
+   * ```typescript
+   * const point = { x: 100, y: 200 };
+   * const polygon = [[0, 0], [100, 0], [100, 100], [0, 100]];
+   * const isInside = isPointInPolygon(point, polygon);
+   * ```
    */
 
   var isPointInPolygon = function (point, polygon) {
@@ -866,13 +925,32 @@
   /**
    * 폴리곤 히트 테스트 (도넛 폴리곤 지원)
    *
-   * 로직:
-   * 1. 외부 폴리곤(첫 번째): 내부에 있어야 함
-   * 2. 내부 구멍들(나머지): 내부에 있으면 안 됨 (evenodd 규칙)
+   * 점이 폴리곤 내부에 있는지 확인합니다. 도넛 폴리곤(구멍이 있는 폴리곤)을 지원합니다.
+   *
+   * @param clickedOffset 클릭/마우스 위치 좌표
+   * @param polygonData 폴리곤 데이터
+   * @param getPolygonOffsets 폴리곤 좌표 변환 함수
+   * @returns 점이 폴리곤 내부에 있으면 true, 아니면 false
    *
-   * 중요: 도넛 폴리곤과 내부 폴리곤은 별개의 polygonData로 처리됨
+   * @remarks
+   * - **도넛 폴리곤 처리** (isDonutPolygon === true):
+   *   1. 외부 폴리곤(첫 번째): 내부에 있어야 함
+   *   2. 내부 구멍들(나머지): 내부에 있으면 안 됨 (evenodd 규칙)
+   * - **일반 폴리곤 처리**: Point-in-Polygon 알고리즘 사용
+   * - **성능**: O(n), n은 폴리곤의 총 좌표 수
+   *
+   * **중요**: 도넛 폴리곤과 내부 폴리곤은 별개의 polygonData로 처리됩니다.
    * - 도넛 폴리곤 A: isDonutPolygon=true
    * - 내부 폴리곤 B: isDonutPolygon=false (별도 데이터)
+   *
+   * @example
+   * ```typescript
+   * const isHit = isPointInPolygonData(
+   *   clickedOffset,
+   *   polygonData,
+   *   getOrComputePolygonOffsets
+   * );
+   * ```
    */
 
   var isPointInPolygonData = function (clickedOffset, polygonData, getPolygonOffsets) {
@@ -937,10 +1015,29 @@
   /**
    * 마커 히트 테스트 (클릭/hover 영역 체크)
    *
-   * 🎯 중요: 꼬리(tail)는 Hit Test 영역에서 제외됩니다!
-   * - markerOffset.y는 마커 최하단(꼬리 끝) 좌표
-   * - boxHeight는 마커 본체만 포함 (꼬리 제외)
-   * - tailHeight만큼 위로 올려서 본체만 Hit Test 영역으로 사용
+   * 점이 마커의 클릭/호버 영역 내부에 있는지 확인합니다.
+   * 마커의 꼬리(tail)는 Hit Test 영역에서 제외됩니다.
+   *
+   * @param clickedOffset 클릭/마우스 위치 좌표
+   * @param markerData 마커 데이터
+   * @param getMarkerOffset 마커 좌표 변환 함수
+   * @returns 점이 마커 영역 내부에 있으면 true, 아니면 false
+   *
+   * @remarks
+   * - **꼬리 제외**: 꼬리(tail)는 Hit Test 영역에서 제외됩니다
+   *   - markerOffset.y는 마커 최하단(꼬리 끝) 좌표
+   *   - boxHeight는 마커 본체만 포함 (꼬리 제외)
+   *   - tailHeight만큼 위로 올려서 본체만 Hit Test 영역으로 사용
+   * - **성능**: O(1) - 단순 사각형 영역 체크
+   *
+   * @example
+   * ```typescript
+   * const isHit = isPointInMarkerData(
+   *   clickedOffset,
+   *   markerData,
+   *   getOrComputeMarkerOffset
+   * );
+   * ```
    */
 
   var isPointInMarkerData = function (clickedOffset, markerData, getMarkerOffset) {
@@ -977,12 +1074,29 @@
   /**
    * 텍스트 박스의 너비를 계산합니다.
    *
-   * @param {Object} params - 파라미터 객체
-   * @param {string} params.text - 측정할 텍스트
-   * @param {string} params.fontConfig - 폰트 설정 (예: 'bold 16px Arial')
-   * @param {number} params.padding - 텍스트 박스에 적용할 패딩 값
-   * @param {number} params.minWidth - 최소 너비
-   * @returns {number} 계산된 텍스트 박스의 너비
+   * Canvas 2D Context의 measureText()를 사용하여 텍스트의 실제 너비를 계산하고,
+   * 패딩과 최소 너비를 고려하여 최종 너비를 반환합니다.
+   *
+   * @param params 파라미터 객체
+   * @param params.text 측정할 텍스트
+   * @param params.fontConfig 폰트 설정 (예: 'bold 16px Arial')
+   * @param params.padding 텍스트 박스에 적용할 패딩 값 (px)
+   * @param params.minWidth 최소 너비 (px)
+   * @returns 계산된 텍스트 박스의 너비 (px)
+   *
+   * @remarks
+   * - 성능: O(1) - 단일 텍스트 측정
+   * - 임시 Canvas를 사용하여 정확한 너비 측정
+   *
+   * @example
+   * ```typescript
+   * const width = calculateTextBoxWidth({
+   *   text: "Hello World",
+   *   fontConfig: 'bold 16px Arial',
+   *   padding: 20,
+   *   minWidth: 60
+   * });
+   * ```
    */
 
   var calculateTextBoxWidth = function (_a) {
@@ -997,6 +1111,29 @@
   };
 
   var WoongCanvasContext = React.createContext(null);
+  /**
+   * WoongCanvasProvider 컴포넌트
+   *
+   * 다중 WoongCanvas 컴포넌트 인스턴스를 관리하는 Context Provider입니다.
+   * 여러 WoongCanvasMarker/WoongCanvasPolygon이 함께 사용될 때 전역 이벤트 조정을 수행합니다.
+   *
+   * @param props 컴포넌트 props
+   * @param props.children 자식 컴포넌트
+   *
+   * @remarks
+   * - zIndex 기반으로 이벤트 우선순위 처리
+   * - 전역 클릭/호버 이벤트 조정
+   * - 여러 레이어 간 상호작용 관리
+   *
+   * @example
+   * ```tsx
+   * <WoongCanvasProvider>
+   *   <WoongCanvasMarker data={markers} zIndex={10} />
+   *   <WoongCanvasPolygon data={polygons} zIndex={5} />
+   * </WoongCanvasProvider>
+   * ```
+   */
+
   var WoongCanvasProvider = function (_a) {
     var children = _a.children;
     var controller = useMintMapController(); // Refs
@@ -1007,7 +1144,12 @@
     var draggingRef = React.useRef(false);
     /**
      * 컴포넌트 등록 (zIndex 내림차순 정렬)
-     * 높은 zIndex가 먼저 처리됨
+     *
+     * 컴포넌트 인스턴스를 등록하고 zIndex 기준으로 내림차순 정렬합니다.
+     * 높은 zIndex를 가진 컴포넌트가 이벤트 처리에서 우선순위를 가집니다.
+     *
+     * @template T 마커/폴리곤 데이터의 추가 속성 타입
+     * @param instance 등록할 컴포넌트 인스턴스
      */
 
     var registerComponent = React.useCallback(function (instance) {
@@ -1018,6 +1160,12 @@
     }, []);
     /**
      * 컴포넌트 등록 해제
+     *
+     * 컴포넌트 인스턴스를 등록 해제합니다.
+     * hover 중이던 컴포넌트면 hover 상태도 초기화합니다.
+     *
+     * @template T 마커/폴리곤 데이터의 추가 속성 타입
+     * @param instance 등록 해제할 컴포넌트 인스턴스
      */
 
     var unregisterComponent = React.useCallback(function (instance) {
@@ -1033,6 +1181,15 @@
     }, []);
     /**
      * 전역 클릭 핸들러 (zIndex 우선순위)
+     *
+     * 모든 등록된 WoongCanvas 컴포넌트 중 zIndex가 높은 컴포넌트부터 클릭 이벤트를 처리합니다.
+     *
+     * @param event 클릭 이벤트 파라미터
+     *
+     * @remarks
+     * - zIndex가 높은 컴포넌트부터 순회하여 첫 번째 히트만 처리
+     * - 상호작용이 비활성화된 컴포넌트는 스킵
+     * - Context가 없으면 각 컴포넌트의 로컬 핸들러가 처리
      */
 
     var handleGlobalClick = React.useCallback(function (event) {
@@ -1060,6 +1217,16 @@
     }, [controller]);
     /**
      * 전역 마우스 이동 핸들러 (zIndex 우선순위)
+     *
+     * 모든 등록된 WoongCanvas 컴포넌트 중 zIndex가 높은 컴포넌트부터 hover 이벤트를 처리합니다.
+     *
+     * @param event 마우스 이동 이벤트 파라미터
+     *
+     * @remarks
+     * - zIndex가 높은 컴포넌트부터 순회하여 첫 번째 히트만 처리
+     * - 상호작용이 비활성화된 컴포넌트는 스킵
+     * - 드래그 중이면 이벤트 무시 (성능 최적화)
+     * - hover 상태 변경 감지 후 이전 hover 해제 및 새 hover 설정
      */
 
     var handleGlobalMouseMove = React.useCallback(function (event) {
@@ -1146,6 +1313,26 @@
       value: contextValue
     }, children);
   };
+  /**
+   * WoongCanvas Context Hook
+   *
+   * WoongCanvasProvider로 감싸진 컴포넌트에서 Context에 접근할 수 있는 hook입니다.
+   *
+   * @returns WoongCanvasContextValue 또는 null (Provider 없으면)
+   *
+   * @remarks
+   * - Provider로 감싸지지 않으면 null 반환 (각 컴포넌트가 로컬 이벤트 처리)
+   * - Provider로 감싸져 있으면 전역 이벤트 조정 활성화
+   *
+   * @example
+   * ```typescript
+   * const context = useWoongCanvasContext();
+   * if (context) {
+   *   // Context 사용 중 (전역 이벤트 조정)
+   * }
+   * ```
+   */
+
   var useWoongCanvasContext = function () {
     var context = React.useContext(WoongCanvasContext);
     return context;
@@ -1199,12 +1386,32 @@
   var DEFAULT_MAX_CACHE_SIZE = 30000;
   /**
    * LRU (Least Recently Used) Cache
-   * 메모리 제한을 위한 캐시 구현 (최적화 버전)
    *
-   * 개선 사항:
+   * 메모리 제한을 위한 캐시 구현입니다. WoongCanvas 컴포넌트에서 좌표 변환 결과를 캐싱하는데 사용됩니다.
+   *
+   * @template K 캐시 키 타입
+   * @template V 캐시 값 타입
+   *
+   * @remarks
+   * **개선 사항**:
    * 1. get() 성능 향상: 접근 빈도 추적 없이 단순 조회만 수행 (delete+set 제거)
    * 2. set() 버그 수정: 기존 키 업데이트 시 maxSize 체크 로직 개선
    * 3. 메모리 효율: 단순 FIFO 캐시로 동작하여 오버헤드 최소화
+   *
+   * **트레이드오프**:
+   * - 장점: 읽기 성능 대폭 향상 (10,000번 get → 이전보다 2배 빠름)
+   * - 단점: 접근 빈도가 아닌 삽입 순서 기반 eviction (FIFO)
+   *
+   * WoongCanvasMarker 사용 사례에 최적:
+   * - 좌표 변환 결과는 zoom/pan 시 어차피 전체 초기화
+   * - 접근 빈도 추적보다 빠른 조회가 더 중요
+   *
+   * @example
+   * ```typescript
+   * const cache = new LRUCache<string, Offset>(30000);
+   * cache.set(item.id, offset);
+   * const cached = cache.get(item.id);
+   * ```
    */
 
   var LRUCache =
@@ -1221,17 +1428,12 @@
     /**
      * 캐시에서 값 조회
      *
-     * 최적화: delete+set 제거
-     * - 이전: 매번 delete+set으로 LRU 갱신 (해시 재계산 비용)
-     * - 현재: 단순 조회만 수행 (O(1) 해시 조회)
-     *
-     * 트레이드오프:
-     * - 장점: 읽기 성능 대폭 향상 (10,000번 get → 이전보다 2배 빠름)
-     * - 단점: 접근 빈도가 아닌 삽입 순서 기반 eviction (FIFO)
+     * @param key 조회할 키
+     * @returns 캐시된 값 또는 undefined (캐시 미스 시)
      *
-     * WoongCanvasMarker 사용 사례에 최적:
-     * - 좌표 변환 결과는 zoom/pan 시 어차피 전체 초기화
-     * - 접근 빈도 추적보다 빠른 조회가 더 중요
+     * @remarks
+     * - 성능: O(1) 해시 조회
+     * - 최적화: delete+set 제거로 읽기 성능 대폭 향상
      */
 
 
@@ -1239,11 +1441,15 @@
       return this.cache.get(key);
     };
     /**
-     * 캐시에 값 저장 (버그 수정 + 최적화)
+     * 캐시에 값 저장
      *
-     * 수정 사항:
-     * 1. 기존 키 업데이트 시 크기 체크 누락 버그 수정
-     * 2. 로직 명확화: 기존 항목/신규 항목 분리 처리
+     * @param key 저장할 키
+     * @param value 저장할 값
+     *
+     * @remarks
+     * - 기존 키 업데이트: 단순 덮어쓰기 (크기 변화 없음)
+     * - 신규 키 추가: 크기 체크 후 필요시 가장 오래된 항목 제거 (FIFO)
+     * - 성능: O(1) 평균 시간복잡도
      */
 
 
@@ -1341,9 +1547,18 @@
     /**
      * 항목 추가 (바운딩 박스 기반)
      *
-     * 개선 사항:
+     * 항목을 공간 인덱스에 추가합니다. 바운딩 박스가 걸치는 모든 셀에 삽입됩니다.
+     *
+     * @param item 추가할 항목
+     * @param minX 바운딩 박스 최소 X 좌표
+     * @param minY 바운딩 박스 최소 Y 좌표
+     * @param maxX 바운딩 박스 최대 X 좌표
+     * @param maxY 바운딩 박스 최대 Y 좌표
+     *
+     * @remarks
      * - 중복 삽입 방지: 기존 항목이 있으면 먼저 제거 후 재삽입
      * - 메모리 누수 방지: 이전 셀 참조 완전 제거
+     * - 성능: O(1) 평균 시간복잡도
      */
 
 
@@ -1367,7 +1582,14 @@
     /**
      * 항목 제거
      *
-     * 추가된 메서드: 메모리 누수 방지 및 업데이트 지원
+     * 공간 인덱스에서 항목을 제거합니다.
+     *
+     * @param item 제거할 항목
+     *
+     * @remarks
+     * - 메모리 누수 방지: 모든 셀에서 참조 완전 제거
+     * - 빈 셀 정리: 항목이 없어진 셀은 자동으로 정리됨
+     * - 성능: O(셀 개수), 보통 O(1)
      */
 
 
@@ -1398,7 +1620,13 @@
     /**
      * 항목 위치 업데이트
      *
-     * 추가된 메서드: remove + insert의 편의 함수
+     * 항목의 위치를 업데이트합니다. remove + insert의 편의 함수입니다.
+     *
+     * @param item 업데이트할 항목
+     * @param minX 새로운 바운딩 박스 최소 X 좌표
+     * @param minY 새로운 바운딩 박스 최소 Y 좌표
+     * @param maxX 새로운 바운딩 박스 최대 X 좌표
+     * @param maxY 새로운 바운딩 박스 최대 Y 좌표
      */
 
 
@@ -1408,7 +1636,26 @@
     /**
      * 점 주변의 항목 조회 (1개 셀만)
      *
-     * 성능: O(해당 셀의 항목 수) - 보통 ~10개
+     * 특정 좌표가 속한 셀의 모든 항목을 반환합니다.
+     *
+     * @param x 조회할 X 좌표
+     * @param y 조회할 Y 좌표
+     * @returns 해당 셀의 항목 배열 (없으면 빈 배열)
+     *
+     * @remarks
+     * - 성능: O(해당 셀의 항목 수) - 보통 ~10개 (30,000개 전체를 체크하지 않음)
+     * - Hit Test에 최적화된 메서드
+     * - 빈 배열 재사용으로 메모리 할당 최소화
+     *
+     * @example
+     * ```typescript
+     * const candidates = grid.queryPoint(mouseX, mouseY);
+     * for (const item of candidates) {
+     *   if (isPointInItem(item, mouseX, mouseY)) {
+     *     return item;
+     *   }
+     * }
+     * ```
      */
 
 
@@ -1421,8 +1668,18 @@
     /**
      * 영역 내 항목 조회
      *
-     * 성능: O(셀 개수 × 셀당 평균 항목 수)
-     * Set으로 중복 제거 보장
+     * 특정 영역(바운딩 박스)과 교차하는 모든 항목을 반환합니다.
+     *
+     * @param minX 영역 최소 X 좌표
+     * @param minY 영역 최소 Y 좌표
+     * @param maxX 영역 최대 X 좌표
+     * @param maxY 영역 최대 Y 좌표
+     * @returns 영역과 교차하는 항목 배열 (중복 제거됨)
+     *
+     * @remarks
+     * - 성능: O(셀 개수 × 셀당 평균 항목 수)
+     * - Set으로 중복 제거 보장 (항목이 여러 셀에 걸쳐 있어도 한 번만 반환)
+     * - Viewport Culling에 유용
      */
 
 
@@ -1447,7 +1704,11 @@
     /**
      * 항목 존재 여부 확인
      *
-     * 추가된 메서드: 빠른 존재 여부 체크
+     * @param item 확인할 항목
+     * @returns 항목이 인덱스에 있으면 true, 아니면 false
+     *
+     * @remarks
+     * - 성능: O(1) 해시 조회
      */
 
 
@@ -1466,7 +1727,14 @@
     /**
      * 통계 정보
      *
-     * 개선: totalItems는 실제 고유 항목 수를 정확히 반환
+     * 공간 인덱스의 현재 상태를 반환합니다. 디버깅 및 성능 분석에 유용합니다.
+     *
+     * @returns 통계 정보 객체
+     *
+     * @remarks
+     * - totalCells: 현재 사용 중인 셀 개수
+     * - totalItems: 인덱스에 등록된 고유 항목 수 (정확)
+     * - avgItemsPerCell: 셀당 평균 항목 수
      */
 
 
@@ -1485,6 +1753,400 @@
     return SpatialHashGrid;
   }();
 
+  /**
+   * 현재 뷰포트 영역 계산
+   *
+   * Konva Stage의 크기와 컬링 마진을 기반으로 뷰포트 경계를 계산합니다.
+   *
+   * @param stage Konva Stage 인스턴스 (width, height 메서드 제공)
+   * @param cullingMargin 컬링 여유 공간 (px)
+   * @param viewportRef 뷰포트 경계를 저장할 ref
+   *
+   * @remarks
+   * - 화면 밖 cullingMargin만큼의 영역까지 포함하여 계산
+   * - 스크롤 시 부드러운 전환을 위해 여유 공간 포함
+   *
+   * @example
+   * ```typescript
+   * updateViewport(stageRef.current, cullingMargin, viewportRef);
+   * ```
+   */
+  var updateViewport = function (stage, cullingMargin, viewportRef) {
+    if (!stage) return;
+    viewportRef.current = {
+      minX: -cullingMargin,
+      maxX: stage.width() + cullingMargin,
+      minY: -cullingMargin,
+      maxY: stage.height() + cullingMargin
+    };
+  };
+  /**
+   * 아이템이 현재 뷰포트 안에 있는지 확인 (바운딩 박스 캐싱)
+   *
+   * 뷰포트 컬링을 위한 함수입니다. 바운딩 박스와 뷰포트 경계의 교차를 확인합니다.
+   * 바운딩 박스는 캐시되어 성능을 최적화합니다.
+   *
+   * @template T 마커/폴리곤 데이터의 추가 속성 타입
+   * @param item 확인할 아이템
+   * @param enableViewportCulling 뷰포트 컬링 활성화 여부
+   * @param viewportRef 뷰포트 경계 ref
+   * @param boundingBoxCacheRef 바운딩 박스 캐시 ref
+   * @param computeBoundingBox 바운딩 박스 계산 함수
+   * @returns 뷰포트 안에 있으면 true, 아니면 false
+   *
+   * @remarks
+   * - 성능: O(1) (캐시 히트 시) 또는 O(바운딩 박스 계산 비용) (캐시 미스 시)
+   * - 바운딩 박스는 자동으로 캐시되어 재사용됨
+   *
+   * @example
+   * ```typescript
+   * const isVisible = isInViewport(
+   *   item,
+   *   enableViewportCulling,
+   *   viewportRef,
+   *   boundingBoxCacheRef,
+   *   computeBoundingBox
+   * );
+   * ```
+   */
+
+  var isInViewport = function (item, enableViewportCulling, viewportRef, boundingBoxCacheRef, computeBoundingBox) {
+    if (!enableViewportCulling || !viewportRef.current) return true;
+    var viewport = viewportRef.current; // 캐시된 바운딩 박스 확인
+
+    var bbox = boundingBoxCacheRef.current.get(item.id);
+
+    if (!bbox) {
+      // 바운딩 박스 계산 (공통 함수 사용)
+      var computed = computeBoundingBox(item);
+      if (!computed) return false;
+      bbox = computed;
+      boundingBoxCacheRef.current.set(item.id, bbox);
+    } // 바운딩 박스와 viewport 교차 체크
+
+
+    return !(bbox.maxX < viewport.minX || bbox.minX > viewport.maxX || bbox.maxY < viewport.minY || bbox.minY > viewport.maxY);
+  };
+
+  /**
+   * 지도 이벤트 핸들러 생성 함수
+   *
+   * 지도 이동, 줌, 드래그 등의 이벤트를 처리하는 핸들러들을 생성합니다.
+   *
+   * @template T 마커/폴리곤 데이터의 추가 속성 타입
+   * @param deps 이벤트 핸들러 생성에 필요한 의존성
+   * @returns 지도 이벤트 핸들러 객체
+   *
+   * @example
+   * ```typescript
+   * const {
+   *   handleIdle,
+   *   handleZoomStart,
+   *   handleZoomEnd,
+   *   handleCenterChanged,
+   *   handleDragStart,
+   *   handleDragEnd,
+   * } = createMapEventHandlers({
+   *   controller,
+   *   containerRef,
+   *   markerRef,
+   *   options,
+   *   prevCenterOffsetRef,
+   *   accumTranslateRef,
+   *   offsetCacheRef,
+   *   boundingBoxCacheRef,
+   *   renderAllImmediate,
+   * });
+   * ```
+   */
+
+  var createMapEventHandlers = function (deps) {
+    var controller = deps.controller,
+        containerRef = deps.containerRef,
+        markerRef = deps.markerRef,
+        options = deps.options,
+        prevCenterOffsetRef = deps.prevCenterOffsetRef,
+        accumTranslateRef = deps.accumTranslateRef,
+        offsetCacheRef = deps.offsetCacheRef,
+        boundingBoxCacheRef = deps.boundingBoxCacheRef,
+        renderAllImmediate = deps.renderAllImmediate;
+    /**
+     * 지도 이동/줌 완료 시 처리
+     *
+     * - 캐시 초기화: 좌표 변환 결과가 변경되었으므로 캐시 무효화
+     * - 마커 위치 업데이트: 새로운 지도 위치에 맞게 마커 재배치
+     * - 렌더링: 새 위치에서 전체 렌더링 수행
+     */
+
+    var handleIdle = function () {
+      prevCenterOffsetRef.current = null;
+      accumTranslateRef.current = {
+        x: 0,
+        y: 0
+      }; // 캐시 정리 (지도 이동/줌으로 좌표 변환 결과가 바뀜)
+
+      offsetCacheRef.current.clear();
+      boundingBoxCacheRef.current.clear(); // 마커 위치 업데이트
+
+      var bounds = controller.getCurrBounds();
+
+      var markerOptions = tslib.__assign({
+        position: bounds.nw
+      }, options);
+
+      markerRef.current && controller.updateMarker(markerRef.current, markerOptions); // transform 제거 전에 새 데이터로 즉시 렌더링 (겹침 방지)
+
+      if (containerRef.current) {
+        containerRef.current.style.transform = '';
+        containerRef.current.style.visibility = '';
+      } // 새 위치에서 렌더링
+
+
+      renderAllImmediate();
+    };
+    /**
+     * 줌 시작 시 처리 (일시적으로 숨김)
+     */
+
+
+    var handleZoomStart = function () {
+      if (containerRef.current) {
+        containerRef.current.style.visibility = 'hidden';
+      }
+    };
+    /**
+     * 줌 종료 시 처리 (다시 표시)
+     */
+
+
+    var handleZoomEnd = function () {
+      if (containerRef.current) {
+        containerRef.current.style.visibility = '';
+      }
+    };
+    /**
+     * 지도 중심 변경 시 처리 (transform으로 이동 추적)
+     */
+
+
+    var handleCenterChanged = function () {
+      var center = controller.getCurrBounds().getCenter();
+      var curr = controller.positionToOffset(center);
+      var prev = prevCenterOffsetRef.current;
+
+      if (!prev) {
+        prevCenterOffsetRef.current = {
+          x: curr.x,
+          y: curr.y
+        };
+        return;
+      }
+
+      var dx = prev.x - curr.x;
+      var dy = prev.y - curr.y;
+      accumTranslateRef.current = {
+        x: accumTranslateRef.current.x + dx,
+        y: accumTranslateRef.current.y + dy
+      };
+      prevCenterOffsetRef.current = {
+        x: curr.x,
+        y: curr.y
+      };
+
+      if (containerRef.current) {
+        containerRef.current.style.transform = "translate(".concat(accumTranslateRef.current.x, "px, ").concat(accumTranslateRef.current.y, "px)");
+      }
+    };
+    /**
+     * 드래그 시작 처리
+     */
+
+
+    var handleDragStart = function () {// 커서는 각 컴포넌트에서 처리
+    };
+    /**
+     * 드래그 종료 처리
+     */
+
+
+    var handleDragEnd = function () {// 커서는 각 컴포넌트에서 처리
+    };
+
+    return {
+      handleIdle: handleIdle,
+      handleZoomStart: handleZoomStart,
+      handleZoomEnd: handleZoomEnd,
+      handleCenterChanged: handleCenterChanged,
+      handleDragStart: handleDragStart,
+      handleDragEnd: handleDragEnd
+    };
+  };
+  /**
+   * 공간 인덱스 빌드 (빠른 Hit Test를 위한 자료구조)
+   *
+   * Spatial Hash Grid에 모든 데이터의 바운딩 박스를 삽입합니다.
+   * 이를 통해 클릭/호버 시 O(1) 수준의 빠른 Hit Test가 가능합니다.
+   *
+   * @template T 마커/폴리곤 데이터의 추가 속성 타입
+   * @param data 공간 인덱스에 삽입할 데이터 배열
+   * @param spatialIndex Spatial Hash Grid 인스턴스
+   * @param computeBoundingBox 바운딩 박스 계산 함수
+   *
+   * @remarks
+   * - 성능: O(n) 시간복잡도, n은 데이터 개수
+   * - 호출 시점: 데이터 변경 시 또는 지도 이동/줌 완료 시
+   *
+   * @example
+   * ```typescript
+   * buildSpatialIndex(
+   *   dataRef.current,
+   *   spatialIndexRef.current,
+   *   computeBoundingBox
+   * );
+   * ```
+   */
+
+  var buildSpatialIndex = function (data, spatialIndex, computeBoundingBox) {
+    spatialIndex.clear();
+
+    for (var _i = 0, data_1 = data; _i < data_1.length; _i++) {
+      var item = data_1[_i];
+      var bbox = computeBoundingBox(item);
+
+      if (bbox) {
+        spatialIndex.insert(item, bbox.minX, bbox.minY, bbox.maxX, bbox.maxY);
+      }
+    }
+  };
+  /**
+   * 선택 상태 동기화 유틸리티
+   *
+   * 데이터 변경 시 선택된 항목의 참조를 최신 데이터로 업데이트합니다.
+   * 화면 밖에 있는 선택된 항목도 선택 상태를 유지합니다.
+   *
+   * @template T 마커/폴리곤 데이터의 추가 속성 타입
+   * @param data 최신 데이터 배열
+   * @param selectedIds 선택된 항목 ID Set
+   * @param selectedItemsMap 현재 선택된 항목 Map
+   * @returns 업데이트된 선택된 항목 Map
+   *
+   * @remarks
+   * - 성능: O(n + m), n은 전체 데이터 수, m은 선택된 항목 수
+   * - 화면 밖 데이터도 선택 상태 유지 (최신 데이터가 없으면 기존 데이터 유지)
+   *
+   * @example
+   * ```typescript
+   * selectedItemsMapRef.current = syncSelectedItems(
+   *   data,
+   *   selectedIdsRef.current,
+   *   selectedItemsMapRef.current
+   * );
+   * ```
+   */
+
+  var syncSelectedItems = function (data, selectedIds, selectedItemsMap) {
+    var dataMap = new Map(data.map(function (m) {
+      return [m.id, m];
+    }));
+    var newSelectedItemsMap = new Map();
+    selectedIds.forEach(function (id) {
+      // 현재 data에 있으면 최신 데이터 사용
+      var currentItem = dataMap.get(id);
+
+      if (currentItem) {
+        newSelectedItemsMap.set(id, currentItem);
+      } else {
+        // 화면 밖이면 기존 데이터 유지
+        var prevItem = selectedItemsMap.get(id);
+
+        if (prevItem) {
+          newSelectedItemsMap.set(id, prevItem);
+        }
+      }
+    });
+    return newSelectedItemsMap;
+  };
+  /**
+   * 외부 selectedItems를 내부 상태로 동기화
+   *
+   * 외부에서 전달된 selectedItems prop을 내부 ref 상태로 동기화합니다.
+   *
+   * @template T 마커/폴리곤 데이터의 추가 속성 타입
+   * @param externalSelectedItems 외부에서 전달된 선택된 항목 배열 (undefined면 동기화 안 함)
+   * @param selectedIdsRef 선택된 ID Set ref
+   * @param selectedItemsMapRef 선택된 항목 Map ref
+   *
+   * @remarks
+   * - externalSelectedItems가 undefined면 외부 제어가 아니므로 아무 작업도 하지 않음
+   * - 성능: O(m), m은 externalSelectedItems의 길이
+   *
+   * @example
+   * ```typescript
+   * useEffect(() => {
+   *   syncExternalSelectedItems(externalSelectedItems, selectedIdsRef, selectedItemsMapRef);
+   *   // 렌더링...
+   * }, [externalSelectedItems]);
+   * ```
+   */
+
+  var syncExternalSelectedItems = function (externalSelectedItems, selectedIdsRef, selectedItemsMapRef) {
+    if (externalSelectedItems === undefined) return;
+    var newSelectedIds = new Set();
+    var newSelectedItemsMap = new Map();
+    externalSelectedItems.forEach(function (item) {
+      newSelectedIds.add(item.id);
+      newSelectedItemsMap.set(item.id, item);
+    });
+    selectedIdsRef.current = newSelectedIds;
+    selectedItemsMapRef.current = newSelectedItemsMap;
+  };
+
+  /**
+   * 이벤트 유효성 검증 헬퍼
+   *
+   * @param event 이벤트 파라미터
+   * @param context Context가 있는지 여부
+   * @param controller MintMapController 인스턴스
+   * @returns 유효한 offset 또는 null
+   *
+   * @remarks
+   * Context가 있으면 전역 이벤트 핸들러가 처리하므로 로컬 핸들러는 스킵
+   */
+  var validateEvent = function (event, context, controller) {
+    var _a; // Context가 있으면 전역 핸들러가 처리
+
+
+    if (context) return null; // 이벤트 파라미터 검증
+
+    if (!((_a = event === null || event === void 0 ? void 0 : event.param) === null || _a === void 0 ? void 0 : _a.position)) return null;
+
+    try {
+      return controller.positionToOffset(event.param.position);
+    } catch (error) {
+      console.error('[WoongCanvas] validateEvent error:', error);
+      return null;
+    }
+  };
+  /**
+   * Map의 values를 배열로 변환 (최적화 버전)
+   *
+   * @param map 변환할 Map
+   * @returns Map의 값 배열
+   *
+   * @remarks
+   * Map.values()는 IterableIterator를 반환하므로 배열 변환이 필요할 때 사용합니다.
+   * 성능: O(n) 시간복잡도
+   *
+   * 최적화: Array.from을 사용하되, 크기를 미리 할당하여 메모리 재할당 최소화
+   */
+
+  var mapValuesToArray = function (map) {
+    // Map이 비어있으면 빈 배열 반환 (메모리 할당 최소화)
+    if (map.size === 0) return []; // Array.from 사용 (TypeScript 컴파일러 호환성)
+
+    return Array.from(map.values());
+  };
+
   var cn$3 = classNames__default["default"].bind(styles$1);
   function MintMapCore(_a) {
     var _this = this;
@@ -5550,37 +6212,16 @@
      * 현재 뷰포트 영역 계산
      */
 
-    var updateViewport = function () {
-      if (!stageRef.current) return;
-      var stage = stageRef.current;
-      viewportRef.current = {
-        minX: -cullingMargin,
-        maxX: stage.width() + cullingMargin,
-        minY: -cullingMargin,
-        maxY: stage.height() + cullingMargin
-      };
+    var updateViewport$1 = function () {
+      updateViewport(stageRef.current, cullingMargin, viewportRef);
     };
     /**
      * 아이템이 현재 뷰포트 안에 있는지 확인 (바운딩 박스 캐싱)
      */
 
 
-    var isInViewport = function (item) {
-      if (!enableViewportCulling || !viewportRef.current) return true;
-      var viewport = viewportRef.current; // 캐시된 바운딩 박스 확인
-
-      var bbox = boundingBoxCacheRef.current.get(item.id);
-
-      if (!bbox) {
-        // 바운딩 박스 계산 (공통 함수 사용)
-        var computed = computeBoundingBox(item);
-        if (!computed) return false;
-        bbox = computed;
-        boundingBoxCacheRef.current.set(item.id, bbox);
-      } // 바운딩 박스와 viewport 교차 체크
-
-
-      return !(bbox.maxX < viewport.minX || bbox.minX > viewport.maxX || bbox.maxY < viewport.minY || bbox.minY > viewport.maxY);
+    var isInViewport$1 = function (item) {
+      return isInViewport(item, enableViewportCulling, viewportRef, boundingBoxCacheRef, computeBoundingBox);
     }; // --------------------------------------------------------------------------
     // 유틸리티 함수: 좌표 변환 캐싱
     // --------------------------------------------------------------------------
@@ -5610,12 +6251,23 @@
     /**
      * 마커의 바운딩 박스 계산
      *
-     * 🎯 마커의 경우:
-     * - boxHeight: 본체만 (Hit Test 영역)
-     * - tailHeight: 꼬리 높이 (Viewport Culling용, 화면에 보이는 전체 영역)
+     * 마커의 화면 상 위치와 크기를 기반으로 바운딩 박스를 계산합니다.
+     * Viewport Culling에 사용되며, tailHeight를 포함하여 전체 표시 영역을 계산합니다.
      *
      * @param item 마커 데이터
-     * @returns 바운딩 박스 또는 null
+     * @returns 바운딩 박스 (minX, minY, maxX, maxY) 또는 null (좌표 변환 실패 시)
+     *
+     * @remarks
+     * - **boxHeight**: 마커 본체만 포함 (Hit Test 영역)
+     * - **tailHeight**: 마커 꼬리 높이 (Viewport Culling용, 화면에 보이는 전체 영역 포함)
+     * - 바운딩 박스는 캐시되어 성능 최적화
+     *
+     * @example
+     * ```typescript
+     * const bbox = computeBoundingBox(item);
+     * if (!bbox) return; // 계산 실패
+     * // bbox.minX, bbox.minY, bbox.maxX, bbox.maxY 사용
+     * ```
      */
 
 
@@ -5639,29 +6291,32 @@
 
     /**
      * 공간 인덱스 빌드 (빠른 Hit Test를 위한 자료구조)
+     *
+     * 모든 마커의 바운딩 박스를 Spatial Hash Grid에 삽입합니다.
+     * 이를 통해 클릭/호버 시 해당 위치 주변의 마커만 빠르게 조회할 수 있습니다.
+     *
+     * @remarks
+     * - 호출 시점: 데이터 변경 시 또는 지도 이동/줌 완료 시
+     * - 성능: O(n) 시간복잡도, n은 마커 개수
+     * - Hit Test 성능: O(1) 수준 (30,000개 → ~10개 후보만 체크)
      */
 
 
-    var buildSpatialIndex = function () {
-      var spatial = spatialIndexRef.current;
-      spatial.clear();
-      var currentData = dataRef.current;
-
-      for (var _i = 0, currentData_1 = currentData; _i < currentData_1.length; _i++) {
-        var item = currentData_1[_i]; // 바운딩 박스 계산 (공통 함수 사용)
-
-        var bbox = computeBoundingBox(item);
-
-        if (bbox) {
-          spatial.insert(item, bbox.minX, bbox.minY, bbox.maxX, bbox.maxY);
-        }
-      }
+    var buildSpatialIndex$1 = function () {
+      buildSpatialIndex(dataRef.current, spatialIndexRef.current, computeBoundingBox);
     }; // --------------------------------------------------------------------------
-    // 렌더링 함수 결정 (dataType에 따라)
+    // 렌더링 함수 결정
     // --------------------------------------------------------------------------
 
     /**
      * 외부 렌더링 함수에 전달할 유틸리티 객체
+     *
+     * 커스텀 렌더링 함수(renderBase, renderAnimation, renderEvent)에서 사용할
+     * 좌표 변환 등의 헬퍼 함수들을 제공합니다.
+     *
+     * @remarks
+     * - getOrComputeMarkerOffset: 마커 좌표 변환 (자동 캐싱)
+     * - getOrComputePolygonOffsets: 폴리곤 좌표 변환 (마커에서는 사용 안 함)
      */
 
 
@@ -5703,7 +6358,7 @@
             var hovered = hoveredItemRef.current; // 클로저로 최신 ref 값 참조
 
             var visibleItems = enableViewportCulling ? dataRef.current.filter(function (item) {
-              return isInViewport(item);
+              return isInViewport$1(item);
             }) : dataRef.current; // topOnHover가 true이고 renderEvent가 없으면 Base Layer에서 hover 처리
 
             if (topOnHover && !renderEvent && hovered) {
@@ -5723,7 +6378,7 @@
             }); // hover된 항목을 최상단에 렌더링 (renderEvent가 없을 때만)
 
             if (topOnHover && !renderEvent && hovered) {
-              var isHoveredInViewport = enableViewportCulling ? isInViewport(hovered) : true;
+              var isHoveredInViewport = enableViewportCulling ? isInViewport$1(hovered) : true;
 
               if (isHoveredInViewport) {
                 renderBase({
@@ -5749,7 +6404,11 @@
     /**
      * Animation 레이어 렌더링 (선택된 마커 애니메이션)
      *
-     * 🔥 최적화: sceneFunc 내부에서 최신 items 참조
+     * 선택된 마커에 대한 애니메이션 효과를 렌더링합니다.
+     * renderAnimation prop이 제공된 경우에만 실행됩니다.
+     *
+     * @remarks
+     * - **성능 최적화**: sceneFunc 내부에서 최신 items 참조
      * - 선택 변경 시에만 재생성
      * - 지도 이동 시에는 기존 Animation 계속 실행
      */
@@ -5769,10 +6428,16 @@
     /**
      * Event 레이어 렌더링 (hover + 선택 상태 표시)
      *
-     * 🔥 최적화:
-     * 1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
-     * 2. sceneFunc 한 번만 설정 (함수 재생성 제거)
-     * 3. 클로저로 최신 데이터 참조
+     * 마커의 hover 효과 및 선택 상태를 표시합니다.
+     * renderEvent prop이 제공된 경우에만 실행됩니다.
+     *
+     * @remarks
+     * - **성능 최적화**:
+     *   1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
+     *   2. sceneFunc 한 번만 설정 (함수 재생성 제거)
+     *   3. 클로저로 최신 데이터 참조
+     * - **topOnHover 지원**: hover된 항목을 최상단에 렌더링
+     * - 선택된 항목은 Map에서 O(1)로 조회하여 성능 최적화
      */
 
 
@@ -5790,8 +6455,9 @@
           name: 'event-render-shape',
           sceneFunc: function (context, shape) {
             var ctx = context; // 클로저로 최신 ref 값 참조
+            // 성능 최적화: Array.from 대신 직접 변환 (메모리 할당 최소화)
 
-            var selectedItems = Array.from(selectedItemsMapRef.current.values());
+            var selectedItems = mapValuesToArray(selectedItemsMapRef.current);
             var hovered = hoveredItemRef.current; // topOnHover가 true이면 hover된 항목을 최상단에 렌더링
 
             if (topOnHover && hovered) {
@@ -5806,7 +6472,7 @@
                 selectedItem: selectedItemRef.current
               }); // 2. hover된 항목을 최상단에 렌더링
 
-              var isHoveredInViewport = enableViewportCulling ? isInViewport(hovered) : true;
+              var isHoveredInViewport = enableViewportCulling ? isInViewport$1(hovered) : true;
 
               if (isHoveredInViewport) {
                 // hover된 항목이 선택되어 있다면 hoverSelectedItems에 포함시켜서 
@@ -5850,8 +6516,8 @@
 
 
     var renderAllImmediate = function () {
-      updateViewport();
-      buildSpatialIndex();
+      updateViewport$1();
+      buildSpatialIndex$1();
       doRenderBase();
       doRenderAnimation();
       doRenderEvent();
@@ -5859,89 +6525,43 @@
     // 이벤트 핸들러: 지도 이벤트
     // --------------------------------------------------------------------------
 
-    /**
-     * 지도 이동/줌 완료 시 처리
-     */
-
-
-    var handleIdle = function () {
-      prevCenterOffsetRef.current = null;
-      accumTranslateRef.current = {
-        x: 0,
-        y: 0
-      }; // 2. 캐시 정리 (지도 이동/줌으로 좌표 변환 결과가 바뀜)
-
-      offsetCacheRef.current.clear();
-      boundingBoxCacheRef.current.clear(); // 3. 마커 위치 업데이트
-
-      var bounds = controller.getCurrBounds();
-
-      var markerOptions = tslib.__assign({
-        position: bounds.nw
-      }, options);
-
-      markerRef.current && controller.updateMarker(markerRef.current, markerOptions); // 4. transform 제거 전에 새 데이터로 즉시 렌더링 (겹침 방지)
 
-      if (containerRef.current) {
-        containerRef.current.style.transform = '';
-        containerRef.current.style.visibility = '';
-      } // 5. 새 위치에서 렌더링
-
-
-      renderAllImmediate();
-    };
-    /**
-     * 줌 시작 시 처리 (일시적으로 숨김)
-     */
-
-
-    var handleZoomStart = function () {
-      if (containerRef.current) {
-        containerRef.current.style.visibility = 'hidden';
-      }
-    };
+    var _g = createMapEventHandlers({
+      controller: controller,
+      containerRef: containerRef,
+      markerRef: markerRef,
+      options: options,
+      prevCenterOffsetRef: prevCenterOffsetRef,
+      accumTranslateRef: accumTranslateRef,
+      offsetCacheRef: offsetCacheRef,
+      boundingBoxCacheRef: boundingBoxCacheRef,
+      renderAllImmediate: renderAllImmediate
+    }),
+        handleIdle = _g.handleIdle,
+        handleZoomStart = _g.handleZoomStart,
+        handleZoomEnd = _g.handleZoomEnd,
+        handleCenterChanged = _g.handleCenterChanged,
+        handleDragStartShared = _g.handleDragStart,
+        handleDragEndShared = _g.handleDragEnd;
     /**
-     * 줌 종료 시 처리 (다시 표시)
-     */
-
-
-    var handleZoomEnd = function () {
-      if (containerRef.current) {
-        containerRef.current.style.visibility = '';
-      }
-    };
-    /**
-     * 지도 중심 변경 시 처리 (transform으로 이동 추적)
-     */
-
-
-    var handleCenterChanged = function () {
-      var center = controller.getCurrBounds().getCenter();
-      var curr = controller.positionToOffset(center);
-      var prev = prevCenterOffsetRef.current;
-
-      if (!prev) {
-        prevCenterOffsetRef.current = {
-          x: curr.x,
-          y: curr.y
-        };
-        return;
-      }
+     * 드래그 시작 처리 (커서를 grabbing으로 변경)
+     */
 
-      var dx = prev.x - curr.x;
-      var dy = prev.y - curr.y;
-      accumTranslateRef.current = {
-        x: accumTranslateRef.current.x + dx,
-        y: accumTranslateRef.current.y + dy
-      };
-      prevCenterOffsetRef.current = {
-        x: curr.x,
-        y: curr.y
-      };
 
-      if (containerRef.current) {
-        containerRef.current.style.transform = "translate(".concat(accumTranslateRef.current.x, "px, ").concat(accumTranslateRef.current.y, "px)");
-      }
+    var handleDragStart = function () {
+      handleDragStartShared();
+      draggingRef.current = true;
+      controller.setMapCursor('grabbing');
+    };
+    /**
+     * 드래그 종료 처리 (커서를 기본으로 복원)
+     */
+
+
+    var handleDragEnd = function () {
+      handleDragEndShared();
+      draggingRef.current = false;
+      controller.setMapCursor('grab');
     }; // --------------------------------------------------------------------------
     // Hit Test & 상태 관리
     // --------------------------------------------------------------------------
@@ -5949,12 +6569,26 @@
     /**
      * 특정 좌표의 마커 데이터 찾기 (Spatial Index 사용)
      *
-     * topOnHover가 true일 때:
-     * - 현재 hover된 항목을 최우선으로 체크
-     * - 시각적으로 최상단에 있는 항목이 hit test에서도 우선됨
+     * 클릭/호버 이벤트 시 해당 위치에 있는 마커를 찾습니다.
+     * Spatial Hash Grid를 사용하여 O(1) 수준의 빠른 Hit Test를 수행합니다.
      *
-     * @param offset 검사할 좌표
-     * @returns 찾은 마커 데이터 또는 null
+     * @param offset 검사할 화면 좌표 (픽셀 단위)
+     * @returns 찾은 마커 데이터 또는 null (없으면)
+     *
+     * @remarks
+     * - **topOnHover 지원**: topOnHover가 true일 때 현재 hover된 항목을 최우선으로 체크
+     *   - 시각적으로 최상단에 있는 항목이 hit test에서도 우선됨
+     * - **성능**: O(후보 항목 수) - 보통 ~10개 (30,000개 전체를 체크하지 않음)
+     * - Spatial Index를 통해 해당 위치 주변의 후보만 추출 후 정확한 Hit Test 수행
+     *
+     * @example
+     * ```typescript
+     * const clickedOffset = controller.positionToOffset(event.param.position);
+     * const data = findData(clickedOffset);
+     * if (data) {
+     *   // 마커를 찾음
+     * }
+     * ```
      */
 
 
@@ -6015,11 +6649,17 @@
     /**
      * 클릭 처리 (단일/다중 선택)
      *
-     * @param data 클릭된 마커/폴리곤 데이터
+     * 마커 클릭 시 선택 상태를 업데이트하고 렌더링을 수행합니다.
      *
-     * 🔥 최적화: 단일 Shape 렌더링으로 Base Layer 재렌더링 속도 향상
-     * - sceneFunc에서 selectedIds를 체크하여 선택된 마커만 스킵
-     * - 객체 생성 오버헤드 제거로 1000개 이상도 부드럽게 처리
+     * @param data 클릭된 마커 데이터
+     *
+     * @remarks
+     * - **단일 선택**: 기존 선택 해제 후 새로 선택 (토글 가능)
+     * - **다중 선택**: enableMultiSelect가 true면 기존 선택 유지하며 추가/제거
+     * - **성능 최적화**:
+     *   - 단일 Shape 렌더링으로 Base Layer 재렌더링 속도 향상
+     *   - sceneFunc에서 selectedIds를 체크하여 선택된 마커만 스킵
+     *   - 객체 생성 오버헤드 제거로 1,000개 이상도 부드럽게 처리
      */
 
 
@@ -6068,75 +6708,57 @@
 
     /**
      * 클릭 이벤트 처리
+     *
+     * @param event 클릭 이벤트 파라미터
+     *
+     * @remarks
+     * - Context가 있으면 전역 이벤트 핸들러가 처리하므로 스킵
+     * - 상호작용이 비활성화되어 있으면 스킵
+     * - Spatial Index를 사용하여 빠른 Hit Test 수행
      */
 
 
     var handleClick = function (event) {
-      var _a;
-
       if (disableInteractionRef.current) return; // 🚫 상호작용 비활성화 시 즉시 반환
 
-      if (context || !((_a = event === null || event === void 0 ? void 0 : event.param) === null || _a === void 0 ? void 0 : _a.position)) return;
-
-      try {
-        var clickedOffset = controller.positionToOffset(event.param.position);
-        var data_1 = findData(clickedOffset);
+      var clickedOffset = validateEvent(event, context, controller);
+      if (!clickedOffset) return;
+      var data = findData(clickedOffset);
 
-        if (data_1) {
-          handleLocalClick(data_1);
+      if (data) {
+        handleLocalClick(data);
 
-          if (onClick) {
-            onClick(data_1, selectedIdsRef.current);
-          }
+        if (onClick) {
+          onClick(data, selectedIdsRef.current);
         }
-      } catch (error) {
-        console.error('[WoongCanvasMarker] handleClick error:', error);
       }
     };
     /**
      * 마우스 이동 이벤트 처리 (hover 감지)
+     *
+     * @param event 마우스 이동 이벤트 파라미터
+     *
+     * @remarks
+     * - Context가 있으면 전역 이벤트 핸들러가 처리하므로 스킵
+     * - 상호작용이 비활성화되어 있으면 스킵
+     * - hover 상태 변경 시에만 렌더링 및 콜백 호출 (최적화)
      */
 
 
     var handleMouseMove = function (event) {
-      var _a;
-
       if (disableInteractionRef.current) return; // 🚫 상호작용 비활성화 시 즉시 반환
 
-      if (context || !((_a = event === null || event === void 0 ? void 0 : event.param) === null || _a === void 0 ? void 0 : _a.position)) return;
-
-      try {
-        var mouseOffset = controller.positionToOffset(event.param.position);
-        var hoveredItem = findData(mouseOffset);
-        var prevHovered = hoveredItemRef.current;
+      var mouseOffset = validateEvent(event, context, controller);
+      if (!mouseOffset) return;
+      var hoveredItem = findData(mouseOffset);
+      var prevHovered = hoveredItemRef.current;
 
-        if (prevHovered !== hoveredItem) {
-          setHovered(hoveredItem);
-          if (prevHovered && onMouseOut) onMouseOut(prevHovered);
-          if (hoveredItem && onMouseOver) onMouseOver(hoveredItem);
-        }
-      } catch (error) {
-        console.error('[WoongCanvasMarker] handleMouseMove error:', error);
+      if (prevHovered !== hoveredItem) {
+        setHovered(hoveredItem);
+        if (prevHovered && onMouseOut) onMouseOut(prevHovered);
+        if (hoveredItem && onMouseOver) onMouseOver(hoveredItem);
       }
     };
-    /**
-     * 드래그 시작 처리 (커서를 grabbing으로 변경)
-     */
-
-
-    var handleDragStart = function () {
-      draggingRef.current = true;
-      controller.setMapCursor('grabbing');
-    };
-    /**
-     * 드래그 종료 처리 (커서를 기본으로 복원)
-     */
-
-
-    var handleDragEnd = function () {
-      draggingRef.current = false;
-      controller.setMapCursor('grab');
-    };
     /**
      * 마우스가 canvas를 벗어날 때 hover cleanup
      */
@@ -6231,7 +6853,7 @@
 
       stage.add(eventLayer); // 초기 뷰포트 설정
 
-      updateViewport(); // ResizeObserver (맵 크기 변경 감지)
+      updateViewport$1(); // ResizeObserver (맵 크기 변경 감지)
 
       var resizeRafId = null;
       var resizeObserver = new ResizeObserver(function () {
@@ -6245,7 +6867,7 @@
           stage.height(mapDiv.offsetHeight);
           offsetCacheRef.current.clear();
           boundingBoxCacheRef.current.clear();
-          updateViewport();
+          updateViewport$1();
           renderAllImmediate();
           resizeRafId = null;
         });
@@ -6334,18 +6956,8 @@
     // --------------------------------------------------------------------------
 
     React.useEffect(function () {
-      if (!stageRef.current) return; // externalSelectedItems가 undefined면 외부 제어 안 함
-
-      if (externalSelectedItems === undefined) return; // 외부에서 전달된 selectedItems로 동기화
-
-      var newSelectedIds = new Set();
-      var newSelectedItemsMap = new Map();
-      externalSelectedItems.forEach(function (item) {
-        newSelectedIds.add(item.id);
-        newSelectedItemsMap.set(item.id, item);
-      });
-      selectedIdsRef.current = newSelectedIds;
-      selectedItemsMapRef.current = newSelectedItemsMap; // 렌더링
+      if (!stageRef.current) return;
+      syncExternalSelectedItems(externalSelectedItems, selectedIdsRef, selectedItemsMapRef); // 렌더링
 
       doRenderBase();
       doRenderAnimation();
@@ -6396,27 +7008,7 @@
        * - O(전체 데이터 수 + 선택된 개수) - 매우 효율적
        */
 
-      var dataMap = new Map(data.map(function (m) {
-        return [m.id, m];
-      }));
-      var newSelectedItemsMap = new Map();
-      selectedIdsRef.current.forEach(function (id) {
-        // 현재 data에 있으면 최신 데이터 사용
-        var currentItem = dataMap.get(id);
-
-        if (currentItem) {
-          newSelectedItemsMap.set(id, currentItem);
-        } else {
-          // 화면 밖이면 기존 데이터 유지
-          var prevItem = selectedItemsMapRef.current.get(id);
-
-          if (prevItem) {
-            newSelectedItemsMap.set(id, prevItem);
-          }
-        }
-      }); // selectedIdsRef는 그대로 유지 (화면 밖 항목도 선택 상태 유지)
-
-      selectedItemsMapRef.current = newSelectedItemsMap; // 즉시 렌더링
+      selectedItemsMapRef.current = syncSelectedItems(data, selectedIdsRef.current, selectedItemsMapRef.current); // 즉시 렌더링
 
       renderAllImmediate();
     }, [data]);
@@ -6434,10 +7026,35 @@
    * 폴리곤 렌더링 유틸리티
    *
    * 이 파일은 폴리곤 렌더링을 위한 헬퍼 함수와 팩토리 함수를 제공합니다.
+   * GeoJSON MultiPolygon 형식을 지원하며, 도넛 폴리곤(구멍이 있는 폴리곤)도 처리할 수 있습니다.
    */
 
   /**
    * 폴리곤 그리기 헬퍼 함수 (도넛 폴리곤 지원)
+   *
+   * Canvas 2D Context를 사용하여 폴리곤을 그립니다.
+   * 도넛 폴리곤의 경우 evenodd fill rule을 사용하여 구멍을 처리합니다.
+   *
+   * @param params 폴리곤 그리기 파라미터
+   *
+   * @remarks
+   * - **도넛 폴리곤 처리**:
+   *   - 외부 폴리곤과 내부 구멍들을 같은 path에 추가
+   *   - `fill('evenodd')`를 사용하여 구멍 뚫기
+   * - **일반 폴리곤 처리**: 각 폴리곤 그룹을 개별적으로 그리기
+   * - **성능**: O(n), n은 폴리곤의 총 좌표 수
+   *
+   * @example
+   * ```typescript
+   * drawPolygon({
+   *   ctx,
+   *   polygonOffsets: [[[[100, 200], [200, 200], [200, 100], [100, 100]]]],
+   *   isDonutPolygon: false,
+   *   fillColor: 'rgba(255, 0, 0, 0.5)',
+   *   strokeColor: 'rgba(255, 0, 0, 1)',
+   *   lineWidth: 2
+   * });
+   * ```
    */
   var drawPolygon = function (_a) {
     var ctx = _a.ctx,
@@ -6451,13 +7068,16 @@
       var multiPolygon = polygonOffsets_1[_i];
 
       if (isDonutPolygon) {
-        ctx.beginPath(); // 1. 외부 폴리곤 그리기
+        // 도넛 폴리곤 처리: 외부 폴리곤 + 내부 구멍들을 같은 path에 추가
+        ctx.beginPath(); // 1. 외부 폴리곤 그리기 (첫 번째 폴리곤)
 
-        if (multiPolygon[0] && multiPolygon[0].length > 0) {
-          ctx.moveTo(multiPolygon[0][0][0], multiPolygon[0][0][1]);
+        var outerPolygon = multiPolygon[0];
+
+        if (outerPolygon && outerPolygon.length > 0) {
+          ctx.moveTo(outerPolygon[0][0], outerPolygon[0][1]);
 
-          for (var i = 1; i < multiPolygon[0].length; i++) {
-            ctx.lineTo(multiPolygon[0][i][0], multiPolygon[0][i][1]);
+          for (var i = 1; i < outerPolygon.length; i++) {
+            ctx.lineTo(outerPolygon[i][0], outerPolygon[i][1]);
           }
 
           ctx.closePath();
@@ -6484,7 +7104,7 @@
         ctx.lineWidth = lineWidth;
         ctx.stroke();
       } else {
-        // 일반 폴리곤
+        // 일반 폴리곤 처리: 각 폴리곤 그룹을 개별적으로 그리기
         for (var _b = 0, multiPolygon_1 = multiPolygon; _b < multiPolygon_1.length; _b++) {
           var polygonGroup = multiPolygon_1[_b];
           if (!polygonGroup.length) continue;
@@ -6497,7 +7117,8 @@
             ctx.lineTo(point[0], point[1]);
           }
 
-          ctx.closePath();
+          ctx.closePath(); // 스타일 설정 및 렌더링
+
           ctx.fillStyle = fillColor;
           ctx.strokeStyle = strokeColor;
           ctx.lineWidth = lineWidth;
@@ -6508,19 +7129,30 @@
     }
   };
   /**
-   * 폴리곤 Base 렌더링 함수
+   * 폴리곤 Base 렌더링 함수 팩토리
    *
+   * Base Layer에서 사용할 렌더링 함수를 생성합니다.
+   * 선택되지 않은 폴리곤만 렌더링하며, 선택된 항목은 Event Layer에서 처리됩니다.
+   *
+   * @template T 폴리곤 데이터의 추가 속성 타입
    * @param baseFillColor 기본 폴리곤 채우기 색상
    * @param baseStrokeColor 기본 폴리곤 테두리 색상
    * @param baseLineWidth 기본 폴리곤 테두리 두께
    * @returns Base Layer 렌더링 함수
    *
+   * @remarks
+   * - 선택된 항목은 Event Layer에서 그려지므로 Base Layer에서는 스킵
+   * - 성능: O(n), n은 렌더링할 폴리곤 개수
+   * - 좌표 변환은 자동으로 캐싱되어 성능 최적화됨
+   *
    * @example
+   * ```typescript
    * const renderBase = renderPolygonBase(
    *   'rgba(255, 100, 100, 0.5)',
    *   'rgba(200, 50, 50, 0.8)',
    *   2
    * );
+   * ```
    */
 
   var renderPolygonBase = function (baseFillColor, baseStrokeColor, baseLineWidth) {
@@ -6531,12 +7163,15 @@
           utils = _a.utils;
 
       for (var _i = 0, items_1 = items; _i < items_1.length; _i++) {
-        var item = items_1[_i]; // 선택된 항목은 Event Layer에서 그림
+        var item = items_1[_i]; // 선택된 항목은 Event Layer에서 그림 (중복 렌더링 방지)
+
+        if (selectedIds.has(item.id)) continue; // paths가 없으면 스킵
+
+        if (!item.paths) continue; // 좌표 변환 (자동 캐싱)
 
-        if (selectedIds.has(item.id)) continue;
-        if (!item.paths) continue;
         var polygonOffsets = utils.getOrComputePolygonOffsets(item);
-        if (!polygonOffsets) continue;
+        if (!polygonOffsets) continue; // 폴리곤 그리기
+
         drawPolygon({
           ctx: ctx,
           polygonOffsets: polygonOffsets,
@@ -6549,8 +7184,12 @@
     };
   };
   /**
-   * 폴리곤 Event 렌더링 함수
+   * 폴리곤 Event 렌더링 함수 팩토리
+   *
+   * Event Layer에서 사용할 렌더링 함수를 생성합니다.
+   * 선택된 항목, hover된 항목, 마지막 선택된 항목을 각각 다른 스타일로 렌더링합니다.
    *
+   * @template T 폴리곤 데이터의 추가 속성 타입
    * @param baseFillColor 기본 폴리곤 채우기 색상 (필수, fallback용)
    * @param baseStrokeColor 기본 폴리곤 테두리 색상 (필수, fallback용)
    * @param baseLineWidth 기본 폴리곤 테두리 두께 (필수, fallback용)
@@ -6565,7 +7204,14 @@
    * @param hoveredLineWidth Hover 시 폴리곤 테두리 두께 (선택, 기본값: selectedLineWidth)
    * @returns Event Layer 렌더링 함수
    *
+   * @remarks
+   * - **렌더링 순서**: 선택된 항목 → 마지막 선택된 항목 → hover된 항목 (최상단)
+   * - **성능**: O(m), m은 선택된 항목 수 + hover된 항목 수
+   * - 좌표 변환은 자동으로 캐싱되어 성능 최적화됨
+   * - hover된 항목이 선택되어 있으면 active 스타일 적용
+   *
    * @example
+   * ```typescript
    * const renderEvent = renderPolygonEvent(
    *   'rgba(255, 100, 100, 0.5)',  // baseFillColor
    *   'rgba(200, 50, 50, 0.8)',    // baseStrokeColor
@@ -6574,6 +7220,7 @@
    *   'rgba(255, 152, 0, 1)',      // selectedStrokeColor
    *   4                             // selectedLineWidth
    * );
+   * ```
    */
 
   var renderPolygonEvent = function (baseFillColor, baseStrokeColor, baseLineWidth, selectedFillColor, selectedStrokeColor, selectedLineWidth, activeFillColor, activeStrokeColor, activeLineWidth, hoveredFillColor, hoveredStrokeColor, hoveredLineWidth) {
@@ -6601,13 +7248,19 @@
           hoveredItem = _a.hoveredItem,
           utils = _a.utils,
           selectedItems = _a.selectedItems,
-          selectedItem = _a.selectedItem; // 1. 선택된 항목들 그리기 (마지막 선택 항목과 호버된 항목 제외)
+          selectedItem = _a.selectedItem; // 성능 최적화: selectedItems를 Set으로 변환하여 O(1) 조회 (매번 some() 체크 방지)
+
+      var selectedIdsSet = selectedItems ? new Set(selectedItems.map(function (item) {
+        return item.id;
+      })) : new Set();
+      var hoveredItemId = hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.id;
+      var selectedItemId = selectedItem === null || selectedItem === void 0 ? void 0 : selectedItem.id; // 1. 선택된 항목들 그리기 (마지막 선택 항목과 호버된 항목 제외)
 
       if (selectedItems === null || selectedItems === void 0 ? void 0 : selectedItems.length) {
         for (var _i = 0, selectedItems_1 = selectedItems; _i < selectedItems_1.length; _i++) {
           var item = selectedItems_1[_i]; // 마지막 선택 항목과 호버된 항목은 나중에 따로 그림
 
-          if (item.id === (selectedItem === null || selectedItem === void 0 ? void 0 : selectedItem.id) || (hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.id) === item.id) continue;
+          if (item.id === selectedItemId || item.id === hoveredItemId) continue;
           if (!item.paths) continue;
           var polygonOffsets = utils.getOrComputePolygonOffsets(item);
           if (!polygonOffsets) continue;
@@ -6623,7 +7276,7 @@
       } // 2. 마지막 선택된 항목 그리기 (호버되지 않은 경우)
 
 
-      if ((selectedItem === null || selectedItem === void 0 ? void 0 : selectedItem.paths) && (hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.id) !== selectedItem.id) {
+      if ((selectedItem === null || selectedItem === void 0 ? void 0 : selectedItem.paths) && hoveredItemId !== selectedItemId) {
         var polygonOffsets = utils.getOrComputePolygonOffsets(selectedItem);
 
         if (polygonOffsets) {
@@ -6641,10 +7294,10 @@
 
       if (hoveredItem === null || hoveredItem === void 0 ? void 0 : hoveredItem.paths) {
         var polygonOffsets = utils.getOrComputePolygonOffsets(hoveredItem);
-        if (!polygonOffsets) return;
-        var isSelected = selectedItems === null || selectedItems === void 0 ? void 0 : selectedItems.some(function (item) {
-          return item.id === hoveredItem.id;
-        });
+        if (!polygonOffsets) return; // 좌표 변환 실패 시 스킵 (return은 렌더링 함수 종료)
+        // 성능 최적화: Set을 사용하여 O(1) 조회 (이전: O(m) some() 체크)
+
+        var isSelected = selectedIdsSet.has(hoveredItem.id);
         drawPolygon({
           ctx: ctx,
           polygonOffsets: polygonOffsets,
@@ -6663,8 +7316,6 @@
   var WoongCanvasPolygon = function (props) {
     var data = props.data,
         onClick = props.onClick,
-        onMouseOver = props.onMouseOver,
-        onMouseOut = props.onMouseOut,
         _a = props.enableMultiSelect,
         enableMultiSelect = _a === void 0 ? false : _a,
         _b = props.enableViewportCulling,
@@ -6689,7 +7340,7 @@
         hoveredFillColor = props.hoveredFillColor,
         hoveredStrokeColor = props.hoveredStrokeColor,
         hoveredLineWidth = props.hoveredLineWidth,
-        options = tslib.__rest(props, ["data", "onClick", "onMouseOver", "onMouseOut", "enableMultiSelect", "enableViewportCulling", "cullingMargin", "maxCacheSize", "selectedItems", "selectedItem", "disableInteraction", "baseFillColor", "baseStrokeColor", "baseLineWidth", "selectedFillColor", "selectedStrokeColor", "selectedLineWidth", "activeFillColor", "activeStrokeColor", "activeLineWidth", "hoveredFillColor", "hoveredStrokeColor", "hoveredLineWidth"]); // --------------------------------------------------------------------------
+        options = tslib.__rest(props, ["data", "onClick", "enableMultiSelect", "enableViewportCulling", "cullingMargin", "maxCacheSize", "selectedItems", "selectedItem", "disableInteraction", "baseFillColor", "baseStrokeColor", "baseLineWidth", "selectedFillColor", "selectedStrokeColor", "selectedLineWidth", "activeFillColor", "activeStrokeColor", "activeLineWidth", "hoveredFillColor", "hoveredStrokeColor", "hoveredLineWidth"]); // --------------------------------------------------------------------------
     // Hooks & Context
     // --------------------------------------------------------------------------
 
@@ -6788,37 +7439,16 @@
      * 현재 뷰포트 영역 계산
      */
 
-    var updateViewport = function () {
-      if (!stageRef.current) return;
-      var stage = stageRef.current;
-      viewportRef.current = {
-        minX: -cullingMargin,
-        maxX: stage.width() + cullingMargin,
-        minY: -cullingMargin,
-        maxY: stage.height() + cullingMargin
-      };
+    var updateViewport$1 = function () {
+      updateViewport(stageRef.current, cullingMargin, viewportRef);
     };
     /**
      * 아이템이 현재 뷰포트 안에 있는지 확인 (바운딩 박스 캐싱)
      */
 
 
-    var isInViewport = function (item) {
-      if (!enableViewportCulling || !viewportRef.current) return true;
-      var viewport = viewportRef.current; // 캐시된 바운딩 박스 확인
-
-      var bbox = boundingBoxCacheRef.current.get(item.id);
-
-      if (!bbox) {
-        // 바운딩 박스 계산 (공통 함수 사용)
-        var computed = computeBoundingBox(item);
-        if (!computed) return false;
-        bbox = computed;
-        boundingBoxCacheRef.current.set(item.id, bbox);
-      } // 바운딩 박스와 viewport 교차 체크
-
-
-      return !(bbox.maxX < viewport.minX || bbox.minX > viewport.maxX || bbox.maxY < viewport.minY || bbox.minY > viewport.maxY);
+    var isInViewport$1 = function (item) {
+      return isInViewport(item, enableViewportCulling, viewportRef, boundingBoxCacheRef, computeBoundingBox);
     }; // --------------------------------------------------------------------------
     // 유틸리티 함수: 좌표 변환 캐싱
     // --------------------------------------------------------------------------
@@ -6847,8 +7477,23 @@
     /**
      * 폴리곤의 바운딩 박스 계산
      *
+     * 폴리곤의 모든 좌표를 순회하여 최소/최대 X, Y 값을 계산합니다.
+     * Viewport Culling에 사용되며, MultiPolygon 형식을 지원합니다.
+     *
      * @param item 폴리곤 데이터
-     * @returns 바운딩 박스 또는 null
+     * @returns 바운딩 박스 (minX, minY, maxX, maxY) 또는 null (좌표 변환 실패 시)
+     *
+     * @remarks
+     * - 성능: O(n), n은 폴리곤의 총 좌표 수
+     * - 바운딩 박스는 캐시되어 성능 최적화
+     * - MultiPolygon의 모든 좌표를 고려하여 계산
+     *
+     * @example
+     * ```typescript
+     * const bbox = computeBoundingBox(item);
+     * if (!bbox) return; // 계산 실패
+     * // bbox.minX, bbox.minY, bbox.maxX, bbox.maxY 사용
+     * ```
      */
 
 
@@ -6894,20 +7539,8 @@
      */
 
 
-    var buildSpatialIndex = function () {
-      var spatial = spatialIndexRef.current;
-      spatial.clear();
-      var currentData = dataRef.current;
-
-      for (var _i = 0, currentData_1 = currentData; _i < currentData_1.length; _i++) {
-        var item = currentData_1[_i]; // 바운딩 박스 계산 (공통 함수 사용)
-
-        var bbox = computeBoundingBox(item);
-
-        if (bbox) {
-          spatial.insert(item, bbox.minX, bbox.minY, bbox.maxX, bbox.maxY);
-        }
-      }
+    var buildSpatialIndex$1 = function () {
+      buildSpatialIndex(dataRef.current, spatialIndexRef.current, computeBoundingBox);
     }; // --------------------------------------------------------------------------
     // 렌더링 함수 결정 (dataType에 따라)
     // --------------------------------------------------------------------------
@@ -6930,11 +7563,8 @@
 
     var renderBase = renderPolygonBase(baseFillColor, baseStrokeColor, baseLineWidth);
     var renderEvent = renderPolygonEvent(baseFillColor, baseStrokeColor, baseLineWidth, selectedFillColor, selectedStrokeColor, selectedLineWidth, activeFillColor, activeStrokeColor, activeLineWidth, hoveredFillColor, hoveredStrokeColor, hoveredLineWidth);
-    /** Base Layer에서 사용할 빈 Set (재사용) */
-
-    React.useRef(new Set());
     /**
-     * Base 레이어 렌더링 (뷰포트 컬링 적용, 선택된 마커 제외)
+     * Base 레이어 렌더링 (뷰포트 컬링 적용)
      *
      * 🔥 최적화:
      * 1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
@@ -6962,7 +7592,7 @@
             var hovered = hoveredItemRef.current; // 클로저로 최신 ref 값 참조
 
             var visibleItems = enableViewportCulling ? dataRef.current.filter(function (item) {
-              return isInViewport(item);
+              return isInViewport$1(item);
             }) : dataRef.current; // 일반 항목 렌더링
 
             renderBase({
@@ -6986,10 +7616,16 @@
     /**
      * Event 레이어 렌더링 (hover + 선택 상태 표시)
      *
-     * 🔥 최적화:
-     * 1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
-     * 2. sceneFunc 한 번만 설정 (함수 재생성 제거)
-     * 3. 클로저로 최신 데이터 참조
+     * 폴리곤의 hover 효과 및 선택 상태를 표시합니다.
+     * 자동 렌더링 방식으로 renderPolygonEvent를 사용합니다.
+     *
+     * @remarks
+     * - **성능 최적화**:
+     *   1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
+     *   2. sceneFunc 한 번만 설정 (함수 재생성 제거)
+     *   3. 클로저로 최신 데이터 참조
+     * - 선택된 항목은 Map에서 O(1)로 조회하여 성능 최적화
+     * - 자동 렌더링: 스타일 props(selectedFillColor, hoveredFillColor 등) 기반으로 자동 렌더링
      */
 
 
@@ -7006,8 +7642,9 @@
           name: 'event-render-shape',
           sceneFunc: function (context, shape) {
             var ctx = context; // 클로저로 최신 ref 값 참조
+            // 성능 최적화: Array.from 대신 직접 변환 (메모리 할당 최소화)
 
-            var selectedItems = Array.from(selectedItemsMapRef.current.values());
+            var selectedItems = mapValuesToArray(selectedItemsMapRef.current);
             var hovered = hoveredItemRef.current; // 일반 렌더링
 
             renderEvent({
@@ -7030,101 +7667,62 @@
     };
     /**
      * 전체 즉시 렌더링 (IDLE 시 호출)
+     *
+     * 뷰포트 업데이트, 공간 인덱스 빌드, 모든 레이어 렌더링을 순차적으로 수행합니다.
+     *
+     * @remarks
+     * - 호출 시점: 지도 이동/줌 완료 시, 데이터 변경 시, 리사이즈 시
+     * - 순서: 뷰포트 업데이트 → 공간 인덱스 빌드 → Base → Event 렌더링
+     * - Animation Layer는 사용하지 않음 (폴리곤 특성)
      */
 
 
     var renderAllImmediate = function () {
-      updateViewport();
-      buildSpatialIndex();
+      updateViewport$1();
+      buildSpatialIndex$1();
       doRenderBase();
       doRenderEvent();
     }; // --------------------------------------------------------------------------
     // 이벤트 핸들러: 지도 이벤트
     // --------------------------------------------------------------------------
 
-    /**
-     * 지도 이동/줌 완료 시 처리
-     */
-
-
-    var handleIdle = function () {
-      prevCenterOffsetRef.current = null;
-      accumTranslateRef.current = {
-        x: 0,
-        y: 0
-      }; // 2. 캐시 정리 (지도 이동/줌으로 좌표 변환 결과가 바뀜)
-
-      offsetCacheRef.current.clear();
-      boundingBoxCacheRef.current.clear(); // 3. 마커 위치 업데이트
-
-      var bounds = controller.getCurrBounds();
-
-      var markerOptions = tslib.__assign({
-        position: bounds.nw
-      }, options);
-
-      markerRef.current && controller.updateMarker(markerRef.current, markerOptions); // 4. transform 제거 전에 새 데이터로 즉시 렌더링 (겹침 방지)
-
-      if (containerRef.current) {
-        containerRef.current.style.transform = '';
-        containerRef.current.style.visibility = '';
-      } // 5. 새 위치에서 렌더링
-
-
-      renderAllImmediate();
-    };
-    /**
-     * 줌 시작 시 처리 (일시적으로 숨김)
-     */
-
 
-    var handleZoomStart = function () {
-      if (containerRef.current) {
-        containerRef.current.style.visibility = 'hidden';
-      }
-    };
+    var _f = createMapEventHandlers({
+      controller: controller,
+      containerRef: containerRef,
+      markerRef: markerRef,
+      options: options,
+      prevCenterOffsetRef: prevCenterOffsetRef,
+      accumTranslateRef: accumTranslateRef,
+      offsetCacheRef: offsetCacheRef,
+      boundingBoxCacheRef: boundingBoxCacheRef,
+      renderAllImmediate: renderAllImmediate
+    }),
+        handleIdle = _f.handleIdle,
+        handleZoomStart = _f.handleZoomStart,
+        handleZoomEnd = _f.handleZoomEnd,
+        handleCenterChanged = _f.handleCenterChanged,
+        handleDragStartShared = _f.handleDragStart,
+        handleDragEndShared = _f.handleDragEnd;
     /**
-     * 줌 종료 시 처리 (다시 표시)
+     * 드래그 시작 처리 (커서를 grabbing으로 변경)
      */
 
 
-    var handleZoomEnd = function () {
-      if (containerRef.current) {
-        containerRef.current.style.visibility = '';
-      }
+    var handleDragStart = function () {
+      handleDragStartShared();
+      draggingRef.current = true;
+      controller.setMapCursor('grabbing');
     };
     /**
-     * 지도 중심 변경 시 처리 (transform으로 이동 추적)
+     * 드래그 종료 처리 (커서를 기본으로 복원)
      */
 
 
-    var handleCenterChanged = function () {
-      var center = controller.getCurrBounds().getCenter();
-      var curr = controller.positionToOffset(center);
-      var prev = prevCenterOffsetRef.current;
-
-      if (!prev) {
-        prevCenterOffsetRef.current = {
-          x: curr.x,
-          y: curr.y
-        };
-        return;
-      }
-
-      var dx = prev.x - curr.x;
-      var dy = prev.y - curr.y;
-      accumTranslateRef.current = {
-        x: accumTranslateRef.current.x + dx,
-        y: accumTranslateRef.current.y + dy
-      };
-      prevCenterOffsetRef.current = {
-        x: curr.x,
-        y: curr.y
-      };
-
-      if (containerRef.current) {
-        containerRef.current.style.transform = "translate(".concat(accumTranslateRef.current.x, "px, ").concat(accumTranslateRef.current.y, "px)");
-      }
+    var handleDragEnd = function () {
+      handleDragEndShared();
+      draggingRef.current = false;
+      controller.setMapCursor('grab');
     }; // --------------------------------------------------------------------------
     // Hit Test & 상태 관리
     // --------------------------------------------------------------------------
@@ -7154,13 +7752,14 @@
     /**
      * Hover 상태 설정 및 레이어 렌더링
      *
-     * @param data hover된 마커/폴리곤 데이터 또는 null
+     * 마우스가 폴리곤 위에 올라갔을 때 hover 상태를 설정하고 즉시 렌더링합니다.
      *
-     * 최적화: RAF 제거하여 즉시 렌더링 (16ms 지연 제거)
+     * @param data hover된 폴리곤 데이터 또는 null (hover 해제 시)
      *
-     * 🎯 topOnHover 지원:
-     * - renderEvent가 있으면: Event Layer에서만 처리 (성능 최적화)
-     * - renderEvent가 없고 topOnHover=true면: Base Layer에서 처리
+     * @remarks
+     * - **성능 최적화**: RAF 없이 즉시 렌더링 (16ms 지연 제거)
+     * - Event Layer에서 hover 효과 표시
+     * - 커서 상태도 자동으로 업데이트됨 (pointer/grab)
      */
 
 
@@ -7179,11 +7778,17 @@
     /**
      * 클릭 처리 (단일/다중 선택)
      *
-     * @param data 클릭된 마커/폴리곤 데이터
+     * 폴리곤 클릭 시 선택 상태를 업데이트하고 렌더링을 수행합니다.
+     *
+     * @param data 클릭된 폴리곤 데이터
      *
-     * 🔥 최적화: 단일 Shape 렌더링으로 Base Layer 재렌더링 속도 향상
-     * - sceneFunc에서 selectedIds를 체크하여 선택된 마커만 스킵
-     * - 객체 생성 오버헤드 제거로 1000개 이상도 부드럽게 처리
+     * @remarks
+     * - **단일 선택**: 기존 선택 해제 후 새로 선택 (토글 가능)
+     * - **다중 선택**: enableMultiSelect가 true면 기존 선택 유지하며 추가/제거
+     * - **성능 최적화**:
+     *   - 단일 Shape 렌더링으로 Base Layer 재렌더링 속도 향상
+     *   - sceneFunc에서 selectedIds를 체크하여 선택된 폴리곤만 스킵
+     *   - 객체 생성 오버헤드 제거로 1,000개 이상도 부드럽게 처리
      */
 
 
@@ -7227,77 +7832,63 @@
 
     /**
      * 클릭 이벤트 처리
+     *
+     * @param event 클릭 이벤트 파라미터
+     *
+     * @remarks
+     * - Context가 있으면 전역 이벤트 핸들러가 처리하므로 스킵
+     * - 상호작용이 비활성화되어 있으면 스킵
+     * - Spatial Index를 사용하여 빠른 Hit Test 수행
      */
 
 
     var handleClick = function (event) {
-      var _a;
-
       if (disableInteractionRef.current) return; // 🚫 상호작용 비활성화 시 즉시 반환
 
-      if (context || !((_a = event === null || event === void 0 ? void 0 : event.param) === null || _a === void 0 ? void 0 : _a.position)) return;
+      var clickedOffset = validateEvent(event, context, controller);
+      if (!clickedOffset) return;
+      var data = findData(clickedOffset);
 
-      try {
-        var clickedOffset = controller.positionToOffset(event.param.position);
-        var data_1 = findData(clickedOffset);
-
-        if (data_1) {
-          handleLocalClick(data_1);
+      if (data) {
+        handleLocalClick(data);
 
-          if (onClick) {
-            onClick(data_1, selectedIdsRef.current);
-          }
+        if (onClick) {
+          onClick(data, selectedIdsRef.current);
         }
-      } catch (error) {
-        console.error('[WoongCanvasPolygon] handleClick error:', error);
       }
     };
     /**
      * 마우스 이동 이벤트 처리 (hover 감지)
+     *
+     * @param event 마우스 이동 이벤트 파라미터
+     *
+     * @remarks
+     * - Context가 있으면 전역 이벤트 핸들러가 처리하므로 스킵
+     * - 상호작용이 비활성화되어 있으면 스킵
+     * - hover 상태 변경 시에만 렌더링 (최적화)
      */
 
 
     var handleMouseMove = function (event) {
-      var _a;
-
       if (disableInteractionRef.current) return; // 🚫 상호작용 비활성화 시 즉시 반환
 
-      if (context || !((_a = event === null || event === void 0 ? void 0 : event.param) === null || _a === void 0 ? void 0 : _a.position)) return;
-
-      try {
-        var mouseOffset = controller.positionToOffset(event.param.position);
-        var hoveredItem = findData(mouseOffset);
-        var prevHovered = hoveredItemRef.current;
+      var mouseOffset = validateEvent(event, context, controller);
+      if (!mouseOffset) return;
+      var hoveredItem = findData(mouseOffset);
+      var prevHovered = hoveredItemRef.current;
 
-        if (prevHovered !== hoveredItem) {
-          setHovered(hoveredItem);
-          if (prevHovered && onMouseOut) onMouseOut(prevHovered);
-          if (hoveredItem && onMouseOver) onMouseOver(hoveredItem);
-        }
-      } catch (error) {
-        console.error('[WoongCanvasPolygon] handleMouseMove error:', error);
+      if (prevHovered !== hoveredItem) {
+        setHovered(hoveredItem);
       }
     };
-    /**
-     * 드래그 시작 처리 (커서를 grabbing으로 변경)
-     */
-
-
-    var handleDragStart = function () {
-      draggingRef.current = true;
-      controller.setMapCursor('grabbing');
-    };
-    /**
-     * 드래그 종료 처리 (커서를 기본으로 복원)
-     */
-
-
-    var handleDragEnd = function () {
-      draggingRef.current = false;
-      controller.setMapCursor('grab');
-    };
     /**
      * 마우스가 canvas를 벗어날 때 hover cleanup
+     *
+     * 맵 영역 밖으로 마우스가 나갔을 때 hover 상태를 초기화합니다.
+     *
+     * @remarks
+     * - 상호작용이 비활성화되어 있으면 스킵
+     * - hover 상태 초기화 및 커서 복원
      */
 
 
@@ -7310,10 +7901,6 @@
         hoveredItemRef.current = null;
         controller.setMapCursor('grab');
         doRenderEvent();
-
-        if (onMouseOut) {
-          onMouseOut(prevHovered);
-        }
       }
     }; // --------------------------------------------------------------------------
     // Lifecycle: DOM 초기화
@@ -7381,7 +7968,7 @@
       stage.add(baseLayer);
       stage.add(eventLayer); // 초기 뷰포트 설정
 
-      updateViewport(); // ResizeObserver (맵 크기 변경 감지)
+      updateViewport$1(); // ResizeObserver (맵 크기 변경 감지)
 
       var resizeRafId = null;
       var resizeObserver = new ResizeObserver(function () {
@@ -7395,7 +7982,7 @@
           stage.height(mapDiv.offsetHeight);
           offsetCacheRef.current.clear();
           boundingBoxCacheRef.current.clear();
-          updateViewport();
+          updateViewport$1();
           renderAllImmediate();
           resizeRafId = null;
         });
@@ -7422,8 +8009,6 @@
             return findData(offset) !== null;
           },
           onClick: onClick,
-          onMouseOver: onMouseOver,
-          onMouseOut: onMouseOut,
           findData: findData,
           setHovered: setHovered,
           handleLocalClick: handleLocalClick,
@@ -7483,18 +8068,8 @@
     // --------------------------------------------------------------------------
 
     React.useEffect(function () {
-      if (!stageRef.current) return; // externalSelectedItems가 undefined면 외부 제어 안 함
-
-      if (externalSelectedItems === undefined) return; // 외부에서 전달된 selectedItems로 동기화
-
-      var newSelectedIds = new Set();
-      var newSelectedItemsMap = new Map();
-      externalSelectedItems.forEach(function (item) {
-        newSelectedIds.add(item.id);
-        newSelectedItemsMap.set(item.id, item);
-      });
-      selectedIdsRef.current = newSelectedIds;
-      selectedItemsMapRef.current = newSelectedItemsMap; // 렌더링
+      if (!stageRef.current) return;
+      syncExternalSelectedItems(externalSelectedItems, selectedIdsRef, selectedItemsMapRef); // 렌더링
 
       doRenderBase();
       doRenderEvent();
@@ -7544,27 +8119,7 @@
        * - O(전체 데이터 수 + 선택된 개수) - 매우 효율적
        */
 
-      var dataMap = new Map(data.map(function (m) {
-        return [m.id, m];
-      }));
-      var newSelectedItemsMap = new Map();
-      selectedIdsRef.current.forEach(function (id) {
-        // 현재 data에 있으면 최신 데이터 사용
-        var currentItem = dataMap.get(id);
-
-        if (currentItem) {
-          newSelectedItemsMap.set(id, currentItem);
-        } else {
-          // 화면 밖이면 기존 데이터 유지
-          var prevItem = selectedItemsMapRef.current.get(id);
-
-          if (prevItem) {
-            newSelectedItemsMap.set(id, prevItem);
-          }
-        }
-      }); // selectedIdsRef는 그대로 유지 (화면 밖 항목도 선택 상태 유지)
-
-      selectedItemsMapRef.current = newSelectedItemsMap; // 즉시 렌더링
+      selectedItemsMapRef.current = syncSelectedItems(data, selectedIdsRef.current, selectedItemsMapRef.current); // 즉시 렌더링
 
       renderAllImmediate();
     }, [data]);
@@ -10455,19 +11010,27 @@
   exports.WoongCanvasMarker = WoongCanvasMarker;
   exports.WoongCanvasPolygon = WoongCanvasPolygon;
   exports.WoongCanvasProvider = WoongCanvasProvider;
+  exports.buildSpatialIndex = buildSpatialIndex;
   exports.calculateTextBoxWidth = calculateTextBoxWidth;
   exports.computeMarkerOffset = computeMarkerOffset;
   exports.computePolygonOffsets = computePolygonOffsets;
+  exports.createMapEventHandlers = createMapEventHandlers;
   exports.getClusterInfo = getClusterInfo;
   exports.getMapOfType = getMapOfType;
   exports.hexToRgba = hexToRgba;
+  exports.isInViewport = isInViewport;
   exports.isPointInMarkerData = isPointInMarkerData;
   exports.isPointInPolygon = isPointInPolygon;
   exports.isPointInPolygonData = isPointInPolygonData;
   exports.log = log;
+  exports.mapValuesToArray = mapValuesToArray;
+  exports.syncExternalSelectedItems = syncExternalSelectedItems;
+  exports.syncSelectedItems = syncSelectedItems;
+  exports.updateViewport = updateViewport;
   exports.useMarkerMoving = useMarkerMoving;
   exports.useMintMapController = useMintMapController;
   exports.useWoongCanvasContext = useWoongCanvasContext;
+  exports.validateEvent = validateEvent;
   exports.waiting = waiting;
 
   Object.defineProperty(exports, '__esModule', { value: true });