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

package/dist/index.es.js

@@ -1,4 +1,4 @@
-import { __extends, __awaiter, __generator, __spreadArray, __assign, __rest } from 'tslib';
+import { __extends, __assign, __awaiter, __generator, __spreadArray, __rest } from 'tslib';
 import React, { createContext, useContext, useRef, useCallback, useEffect, useMemo, useState } from 'react';
 import classNames from 'classnames/bind';
 import styleInject from 'style-inject';
@@ -796,6 +796,30 @@ function () {
 
 /**
  * 폴리곤 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) {
@@ -832,6 +856,23 @@ var computePolygonOffsets = function (polygonData, controller) {
 };
 /**
  * 마커 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) {
@@ -843,6 +884,24 @@ var computeMarkerOffset = function (markerData, controller) {
 };
 /**
  * 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) {
@@ -862,13 +921,32 @@ var isPointInPolygon = function (point, polygon) {
 /**
  * 폴리곤 히트 테스트 (도넛 폴리곤 지원)
  *
- * 로직:
- * 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) {
@@ -933,10 +1011,29 @@ var isPointInPolygonData = function (clickedOffset, polygonData, getPolygonOffse
 /**
  * 마커 히트 테스트 (클릭/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) {
@@ -973,12 +1070,29 @@ var tempCtx = tempCanvas.getContext('2d');
 /**
  * 텍스트 박스의 너비를 계산합니다.
  *
- * @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) {
@@ -993,6 +1107,29 @@ var calculateTextBoxWidth = function (_a) {
 };
 
 var WoongCanvasContext = 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
@@ -1003,7 +1140,12 @@ var WoongCanvasProvider = function (_a) {
   var draggingRef = useRef(false);
   /**
    * 컴포넌트 등록 (zIndex 내림차순 정렬)
-   * 높은 zIndex가 먼저 처리됨
+   *
+   * 컴포넌트 인스턴스를 등록하고 zIndex 기준으로 내림차순 정렬합니다.
+   * 높은 zIndex를 가진 컴포넌트가 이벤트 처리에서 우선순위를 가집니다.
+   *
+   * @template T 마커/폴리곤 데이터의 추가 속성 타입
+   * @param instance 등록할 컴포넌트 인스턴스
    */
 
   var registerComponent = useCallback(function (instance) {
@@ -1014,6 +1156,12 @@ var WoongCanvasProvider = function (_a) {
   }, []);
   /**
    * 컴포넌트 등록 해제
+   *
+   * 컴포넌트 인스턴스를 등록 해제합니다.
+   * hover 중이던 컴포넌트면 hover 상태도 초기화합니다.
+   *
+   * @template T 마커/폴리곤 데이터의 추가 속성 타입
+   * @param instance 등록 해제할 컴포넌트 인스턴스
    */
 
   var unregisterComponent = useCallback(function (instance) {
@@ -1029,6 +1177,15 @@ var WoongCanvasProvider = function (_a) {
   }, []);
   /**
    * 전역 클릭 핸들러 (zIndex 우선순위)
+   *
+   * 모든 등록된 WoongCanvas 컴포넌트 중 zIndex가 높은 컴포넌트부터 클릭 이벤트를 처리합니다.
+   *
+   * @param event 클릭 이벤트 파라미터
+   *
+   * @remarks
+   * - zIndex가 높은 컴포넌트부터 순회하여 첫 번째 히트만 처리
+   * - 상호작용이 비활성화된 컴포넌트는 스킵
+   * - Context가 없으면 각 컴포넌트의 로컬 핸들러가 처리
    */
 
   var handleGlobalClick = useCallback(function (event) {
@@ -1056,6 +1213,16 @@ var WoongCanvasProvider = function (_a) {
   }, [controller]);
   /**
    * 전역 마우스 이동 핸들러 (zIndex 우선순위)
+   *
+   * 모든 등록된 WoongCanvas 컴포넌트 중 zIndex가 높은 컴포넌트부터 hover 이벤트를 처리합니다.
+   *
+   * @param event 마우스 이동 이벤트 파라미터
+   *
+   * @remarks
+   * - zIndex가 높은 컴포넌트부터 순회하여 첫 번째 히트만 처리
+   * - 상호작용이 비활성화된 컴포넌트는 스킵
+   * - 드래그 중이면 이벤트 무시 (성능 최적화)
+   * - hover 상태 변경 감지 후 이전 hover 해제 및 새 hover 설정
    */
 
   var handleGlobalMouseMove = useCallback(function (event) {
@@ -1142,6 +1309,26 @@ var WoongCanvasProvider = function (_a) {
     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 = useContext(WoongCanvasContext);
   return context;
@@ -1195,12 +1382,32 @@ var DEFAULT_CULLING_MARGIN = 100;
 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 =
@@ -1217,17 +1424,12 @@ function () {
   /**
    * 캐시에서 값 조회
    *
-   * 최적화: 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 제거로 읽기 성능 대폭 향상
    */
 
 
@@ -1235,11 +1437,15 @@ function () {
     return this.cache.get(key);
   };
   /**
-   * 캐시에 값 저장 (버그 수정 + 최적화)
+   * 캐시에 값 저장
    *
-   * 수정 사항:
-   * 1. 기존 키 업데이트 시 크기 체크 누락 버그 수정
-   * 2. 로직 명확화: 기존 항목/신규 항목 분리 처리
+   * @param key 저장할 키
+   * @param value 저장할 값
+   *
+   * @remarks
+   * - 기존 키 업데이트: 단순 덮어쓰기 (크기 변화 없음)
+   * - 신규 키 추가: 크기 체크 후 필요시 가장 오래된 항목 제거 (FIFO)
+   * - 성능: O(1) 평균 시간복잡도
    */
 
 
@@ -1337,9 +1543,18 @@ function () {
   /**
    * 항목 추가 (바운딩 박스 기반)
    *
-   * 개선 사항:
+   * 항목을 공간 인덱스에 추가합니다. 바운딩 박스가 걸치는 모든 셀에 삽입됩니다.
+   *
+   * @param item 추가할 항목
+   * @param minX 바운딩 박스 최소 X 좌표
+   * @param minY 바운딩 박스 최소 Y 좌표
+   * @param maxX 바운딩 박스 최대 X 좌표
+   * @param maxY 바운딩 박스 최대 Y 좌표
+   *
+   * @remarks
    * - 중복 삽입 방지: 기존 항목이 있으면 먼저 제거 후 재삽입
    * - 메모리 누수 방지: 이전 셀 참조 완전 제거
+   * - 성능: O(1) 평균 시간복잡도
    */
 
 
@@ -1363,7 +1578,14 @@ function () {
   /**
    * 항목 제거
    *
-   * 추가된 메서드: 메모리 누수 방지 및 업데이트 지원
+   * 공간 인덱스에서 항목을 제거합니다.
+   *
+   * @param item 제거할 항목
+   *
+   * @remarks
+   * - 메모리 누수 방지: 모든 셀에서 참조 완전 제거
+   * - 빈 셀 정리: 항목이 없어진 셀은 자동으로 정리됨
+   * - 성능: O(셀 개수), 보통 O(1)
    */
 
 
@@ -1394,7 +1616,13 @@ function () {
   /**
    * 항목 위치 업데이트
    *
-   * 추가된 메서드: remove + insert의 편의 함수
+   * 항목의 위치를 업데이트합니다. remove + insert의 편의 함수입니다.
+   *
+   * @param item 업데이트할 항목
+   * @param minX 새로운 바운딩 박스 최소 X 좌표
+   * @param minY 새로운 바운딩 박스 최소 Y 좌표
+   * @param maxX 새로운 바운딩 박스 최대 X 좌표
+   * @param maxY 새로운 바운딩 박스 최대 Y 좌표
    */
 
 
@@ -1404,7 +1632,26 @@ function () {
   /**
    * 점 주변의 항목 조회 (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;
+   *   }
+   * }
+   * ```
    */
 
 
@@ -1417,8 +1664,18 @@ function () {
   /**
    * 영역 내 항목 조회
    *
-   * 성능: O(셀 개수 × 셀당 평균 항목 수)
-   * Set으로 중복 제거 보장
+   * 특정 영역(바운딩 박스)과 교차하는 모든 항목을 반환합니다.
+   *
+   * @param minX 영역 최소 X 좌표
+   * @param minY 영역 최소 Y 좌표
+   * @param maxX 영역 최대 X 좌표
+   * @param maxY 영역 최대 Y 좌표
+   * @returns 영역과 교차하는 항목 배열 (중복 제거됨)
+   *
+   * @remarks
+   * - 성능: O(셀 개수 × 셀당 평균 항목 수)
+   * - Set으로 중복 제거 보장 (항목이 여러 셀에 걸쳐 있어도 한 번만 반환)
+   * - Viewport Culling에 유용
    */
 
 
@@ -1443,7 +1700,11 @@ function () {
   /**
    * 항목 존재 여부 확인
    *
-   * 추가된 메서드: 빠른 존재 여부 체크
+   * @param item 확인할 항목
+   * @returns 항목이 인덱스에 있으면 true, 아니면 false
+   *
+   * @remarks
+   * - 성능: O(1) 해시 조회
    */
 
 
@@ -1462,7 +1723,14 @@ function () {
   /**
    * 통계 정보
    *
-   * 개선: totalItems는 실제 고유 항목 수를 정확히 반환
+   * 공간 인덱스의 현재 상태를 반환합니다. 디버깅 및 성능 분석에 유용합니다.
+   *
+   * @returns 통계 정보 객체
+   *
+   * @remarks
+   * - totalCells: 현재 사용 중인 셀 개수
+   * - totalItems: 인덱스에 등록된 고유 항목 수 (정확)
+   * - avgItemsPerCell: 셀당 평균 항목 수
    */
 
 
@@ -1481,6 +1749,400 @@ function () {
   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 = __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.bind(styles$1);
 function MintMapCore(_a) {
   var _this = this;
@@ -5546,37 +6208,16 @@ var WoongCanvasMarker = function (props) {
    * 현재 뷰포트 영역 계산
    */
 
-  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);
   }; // --------------------------------------------------------------------------
   // 유틸리티 함수: 좌표 변환 캐싱
   // --------------------------------------------------------------------------
@@ -5606,12 +6247,23 @@ var WoongCanvasMarker = function (props) {
   /**
    * 마커의 바운딩 박스 계산
    *
-   * 🎯 마커의 경우:
-   * - 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 사용
+   * ```
    */
 
 
@@ -5635,29 +6287,32 @@ var WoongCanvasMarker = function (props) {
 
   /**
    * 공간 인덱스 빌드 (빠른 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: 폴리곤 좌표 변환 (마커에서는 사용 안 함)
    */
 
 
@@ -5699,7 +6354,7 @@ var WoongCanvasMarker = function (props) {
           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) {
@@ -5719,7 +6374,7 @@ var WoongCanvasMarker = function (props) {
           }); // hover된 항목을 최상단에 렌더링 (renderEvent가 없을 때만)
 
           if (topOnHover && !renderEvent && hovered) {
-            var isHoveredInViewport = enableViewportCulling ? isInViewport(hovered) : true;
+            var isHoveredInViewport = enableViewportCulling ? isInViewport$1(hovered) : true;
 
             if (isHoveredInViewport) {
               renderBase({
@@ -5745,7 +6400,11 @@ var WoongCanvasMarker = function (props) {
   /**
    * Animation 레이어 렌더링 (선택된 마커 애니메이션)
    *
-   * 🔥 최적화: sceneFunc 내부에서 최신 items 참조
+   * 선택된 마커에 대한 애니메이션 효과를 렌더링합니다.
+   * renderAnimation prop이 제공된 경우에만 실행됩니다.
+   *
+   * @remarks
+   * - **성능 최적화**: sceneFunc 내부에서 최신 items 참조
    * - 선택 변경 시에만 재생성
    * - 지도 이동 시에는 기존 Animation 계속 실행
    */
@@ -5765,10 +6424,16 @@ var WoongCanvasMarker = function (props) {
   /**
    * Event 레이어 렌더링 (hover + 선택 상태 표시)
    *
-   * 🔥 최적화:
-   * 1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
-   * 2. sceneFunc 한 번만 설정 (함수 재생성 제거)
-   * 3. 클로저로 최신 데이터 참조
+   * 마커의 hover 효과 및 선택 상태를 표시합니다.
+   * renderEvent prop이 제공된 경우에만 실행됩니다.
+   *
+   * @remarks
+   * - **성능 최적화**:
+   *   1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
+   *   2. sceneFunc 한 번만 설정 (함수 재생성 제거)
+   *   3. 클로저로 최신 데이터 참조
+   * - **topOnHover 지원**: hover된 항목을 최상단에 렌더링
+   * - 선택된 항목은 Map에서 O(1)로 조회하여 성능 최적화
    */
 
 
@@ -5786,8 +6451,9 @@ var WoongCanvasMarker = function (props) {
         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) {
@@ -5802,7 +6468,7 @@ var WoongCanvasMarker = function (props) {
               selectedItem: selectedItemRef.current
             }); // 2. hover된 항목을 최상단에 렌더링
 
-            var isHoveredInViewport = enableViewportCulling ? isInViewport(hovered) : true;
+            var isHoveredInViewport = enableViewportCulling ? isInViewport$1(hovered) : true;
 
             if (isHoveredInViewport) {
               // hover된 항목이 선택되어 있다면 hoverSelectedItems에 포함시켜서 
@@ -5846,8 +6512,8 @@ var WoongCanvasMarker = function (props) {
 
 
   var renderAllImmediate = function () {
-    updateViewport();
-    buildSpatialIndex();
+    updateViewport$1();
+    buildSpatialIndex$1();
     doRenderBase();
     doRenderAnimation();
     doRenderEvent();
@@ -5855,89 +6521,43 @@ var WoongCanvasMarker = function (props) {
   // 이벤트 핸들러: 지도 이벤트
   // --------------------------------------------------------------------------
 
-  /**
-   * 지도 이동/줌 완료 시 처리
-   */
-
-
-  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 = __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 & 상태 관리
   // --------------------------------------------------------------------------
@@ -5945,12 +6565,26 @@ var WoongCanvasMarker = function (props) {
   /**
    * 특정 좌표의 마커 데이터 찾기 (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) {
+   *   // 마커를 찾음
+   * }
+   * ```
    */
 
 
@@ -6011,11 +6645,17 @@ var WoongCanvasMarker = function (props) {
   /**
    * 클릭 처리 (단일/다중 선택)
    *
-   * @param data 클릭된 마커/폴리곤 데이터
+   * 마커 클릭 시 선택 상태를 업데이트하고 렌더링을 수행합니다.
    *
-   * 🔥 최적화: 단일 Shape 렌더링으로 Base Layer 재렌더링 속도 향상
-   * - sceneFunc에서 selectedIds를 체크하여 선택된 마커만 스킵
-   * - 객체 생성 오버헤드 제거로 1000개 이상도 부드럽게 처리
+   * @param data 클릭된 마커 데이터
+   *
+   * @remarks
+   * - **단일 선택**: 기존 선택 해제 후 새로 선택 (토글 가능)
+   * - **다중 선택**: enableMultiSelect가 true면 기존 선택 유지하며 추가/제거
+   * - **성능 최적화**:
+   *   - 단일 Shape 렌더링으로 Base Layer 재렌더링 속도 향상
+   *   - sceneFunc에서 selectedIds를 체크하여 선택된 마커만 스킵
+   *   - 객체 생성 오버헤드 제거로 1,000개 이상도 부드럽게 처리
    */
 
 
@@ -6064,75 +6704,57 @@ var WoongCanvasMarker = function (props) {
 
   /**
    * 클릭 이벤트 처리
+   *
+   * @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
    */
@@ -6227,7 +6849,7 @@ var WoongCanvasMarker = function (props) {
 
     stage.add(eventLayer); // 초기 뷰포트 설정
 
-    updateViewport(); // ResizeObserver (맵 크기 변경 감지)
+    updateViewport$1(); // ResizeObserver (맵 크기 변경 감지)
 
     var resizeRafId = null;
     var resizeObserver = new ResizeObserver(function () {
@@ -6241,7 +6863,7 @@ var WoongCanvasMarker = function (props) {
         stage.height(mapDiv.offsetHeight);
         offsetCacheRef.current.clear();
         boundingBoxCacheRef.current.clear();
-        updateViewport();
+        updateViewport$1();
         renderAllImmediate();
         resizeRafId = null;
       });
@@ -6330,18 +6952,8 @@ var WoongCanvasMarker = function (props) {
   // --------------------------------------------------------------------------
 
   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();
@@ -6392,27 +7004,7 @@ var WoongCanvasMarker = function (props) {
      * - 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]);
@@ -6430,10 +7022,35 @@ var WoongCanvasMarker = function (props) {
  * 폴리곤 렌더링 유틸리티
  *
  * 이 파일은 폴리곤 렌더링을 위한 헬퍼 함수와 팩토리 함수를 제공합니다.
+ * 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,
@@ -6447,13 +7064,16 @@ var drawPolygon = function (_a) {
     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();
@@ -6480,7 +7100,7 @@ var drawPolygon = function (_a) {
       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;
@@ -6493,7 +7113,8 @@ var drawPolygon = function (_a) {
           ctx.lineTo(point[0], point[1]);
         }
 
-        ctx.closePath();
+        ctx.closePath(); // 스타일 설정 및 렌더링
+
         ctx.fillStyle = fillColor;
         ctx.strokeStyle = strokeColor;
         ctx.lineWidth = lineWidth;
@@ -6504,19 +7125,30 @@ var drawPolygon = function (_a) {
   }
 };
 /**
- * 폴리곤 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) {
@@ -6527,12 +7159,15 @@ var renderPolygonBase = function (baseFillColor, baseStrokeColor, baseLineWidth)
         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,
@@ -6545,8 +7180,12 @@ var renderPolygonBase = function (baseFillColor, baseStrokeColor, baseLineWidth)
   };
 };
 /**
- * 폴리곤 Event 렌더링 함수
+ * 폴리곤 Event 렌더링 함수 팩토리
+ *
+ * Event Layer에서 사용할 렌더링 함수를 생성합니다.
+ * 선택된 항목, hover된 항목, 마지막 선택된 항목을 각각 다른 스타일로 렌더링합니다.
  *
+ * @template T 폴리곤 데이터의 추가 속성 타입
  * @param baseFillColor 기본 폴리곤 채우기 색상 (필수, fallback용)
  * @param baseStrokeColor 기본 폴리곤 테두리 색상 (필수, fallback용)
  * @param baseLineWidth 기본 폴리곤 테두리 두께 (필수, fallback용)
@@ -6561,7 +7200,14 @@ var renderPolygonBase = function (baseFillColor, baseStrokeColor, baseLineWidth)
  * @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
@@ -6570,6 +7216,7 @@ var renderPolygonBase = function (baseFillColor, baseStrokeColor, baseLineWidth)
  *   'rgba(255, 152, 0, 1)',      // selectedStrokeColor
  *   4                             // selectedLineWidth
  * );
+ * ```
  */
 
 var renderPolygonEvent = function (baseFillColor, baseStrokeColor, baseLineWidth, selectedFillColor, selectedStrokeColor, selectedLineWidth, activeFillColor, activeStrokeColor, activeLineWidth, hoveredFillColor, hoveredStrokeColor, hoveredLineWidth) {
@@ -6597,13 +7244,19 @@ var renderPolygonEvent = function (baseFillColor, baseStrokeColor, baseLineWidth
         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;
@@ -6619,7 +7272,7 @@ var renderPolygonEvent = function (baseFillColor, baseStrokeColor, baseLineWidth
     } // 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) {
@@ -6637,10 +7290,10 @@ var renderPolygonEvent = function (baseFillColor, baseStrokeColor, baseLineWidth
 
     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,
@@ -6659,8 +7312,6 @@ var renderPolygonEvent = function (baseFillColor, baseStrokeColor, baseLineWidth
 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,
@@ -6685,7 +7336,7 @@ var WoongCanvasPolygon = function (props) {
       hoveredFillColor = props.hoveredFillColor,
       hoveredStrokeColor = props.hoveredStrokeColor,
       hoveredLineWidth = props.hoveredLineWidth,
-      options = __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 = __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
   // --------------------------------------------------------------------------
 
@@ -6784,37 +7435,16 @@ var WoongCanvasPolygon = function (props) {
    * 현재 뷰포트 영역 계산
    */
 
-  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);
   }; // --------------------------------------------------------------------------
   // 유틸리티 함수: 좌표 변환 캐싱
   // --------------------------------------------------------------------------
@@ -6843,8 +7473,23 @@ var WoongCanvasPolygon = function (props) {
   /**
    * 폴리곤의 바운딩 박스 계산
    *
+   * 폴리곤의 모든 좌표를 순회하여 최소/최대 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 사용
+   * ```
    */
 
 
@@ -6890,20 +7535,8 @@ var WoongCanvasPolygon = function (props) {
    */
 
 
-  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에 따라)
   // --------------------------------------------------------------------------
@@ -6926,11 +7559,8 @@ var WoongCanvasPolygon = function (props) {
 
   var renderBase = renderPolygonBase(baseFillColor, baseStrokeColor, baseLineWidth);
   var renderEvent = renderPolygonEvent(baseFillColor, baseStrokeColor, baseLineWidth, selectedFillColor, selectedStrokeColor, selectedLineWidth, activeFillColor, activeStrokeColor, activeLineWidth, hoveredFillColor, hoveredStrokeColor, hoveredLineWidth);
-  /** Base Layer에서 사용할 빈 Set (재사용) */
-
-  useRef(new Set());
   /**
-   * Base 레이어 렌더링 (뷰포트 컬링 적용, 선택된 마커 제외)
+   * Base 레이어 렌더링 (뷰포트 컬링 적용)
    *
    * 🔥 최적화:
    * 1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
@@ -6958,7 +7588,7 @@ var WoongCanvasPolygon = function (props) {
           var hovered = hoveredItemRef.current; // 클로저로 최신 ref 값 참조
 
           var visibleItems = enableViewportCulling ? dataRef.current.filter(function (item) {
-            return isInViewport(item);
+            return isInViewport$1(item);
           }) : dataRef.current; // 일반 항목 렌더링
 
           renderBase({
@@ -6982,10 +7612,16 @@ var WoongCanvasPolygon = function (props) {
   /**
    * Event 레이어 렌더링 (hover + 선택 상태 표시)
    *
-   * 🔥 최적화:
-   * 1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
-   * 2. sceneFunc 한 번만 설정 (함수 재생성 제거)
-   * 3. 클로저로 최신 데이터 참조
+   * 폴리곤의 hover 효과 및 선택 상태를 표시합니다.
+   * 자동 렌더링 방식으로 renderPolygonEvent를 사용합니다.
+   *
+   * @remarks
+   * - **성능 최적화**:
+   *   1. Shape 재사용으로 객체 생성/파괴 오버헤드 제거
+   *   2. sceneFunc 한 번만 설정 (함수 재생성 제거)
+   *   3. 클로저로 최신 데이터 참조
+   * - 선택된 항목은 Map에서 O(1)로 조회하여 성능 최적화
+   * - 자동 렌더링: 스타일 props(selectedFillColor, hoveredFillColor 등) 기반으로 자동 렌더링
    */
 
 
@@ -7002,8 +7638,9 @@ var WoongCanvasPolygon = function (props) {
         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({
@@ -7026,101 +7663,62 @@ var WoongCanvasPolygon = function (props) {
   };
   /**
    * 전체 즉시 렌더링 (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 = __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 & 상태 관리
   // --------------------------------------------------------------------------
@@ -7150,13 +7748,14 @@ var WoongCanvasPolygon = function (props) {
   /**
    * 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)
    */
 
 
@@ -7175,11 +7774,17 @@ var WoongCanvasPolygon = function (props) {
   /**
    * 클릭 처리 (단일/다중 선택)
    *
-   * @param data 클릭된 마커/폴리곤 데이터
+   * 폴리곤 클릭 시 선택 상태를 업데이트하고 렌더링을 수행합니다.
+   *
+   * @param data 클릭된 폴리곤 데이터
    *
-   * 🔥 최적화: 단일 Shape 렌더링으로 Base Layer 재렌더링 속도 향상
-   * - sceneFunc에서 selectedIds를 체크하여 선택된 마커만 스킵
-   * - 객체 생성 오버헤드 제거로 1000개 이상도 부드럽게 처리
+   * @remarks
+   * - **단일 선택**: 기존 선택 해제 후 새로 선택 (토글 가능)
+   * - **다중 선택**: enableMultiSelect가 true면 기존 선택 유지하며 추가/제거
+   * - **성능 최적화**:
+   *   - 단일 Shape 렌더링으로 Base Layer 재렌더링 속도 향상
+   *   - sceneFunc에서 selectedIds를 체크하여 선택된 폴리곤만 스킵
+   *   - 객체 생성 오버헤드 제거로 1,000개 이상도 부드럽게 처리
    */
 
 
@@ -7223,77 +7828,63 @@ var WoongCanvasPolygon = function (props) {
 
   /**
    * 클릭 이벤트 처리
+   *
+   * @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 상태 초기화 및 커서 복원
    */
 
 
@@ -7306,10 +7897,6 @@ var WoongCanvasPolygon = function (props) {
       hoveredItemRef.current = null;
       controller.setMapCursor('grab');
       doRenderEvent();
-
-      if (onMouseOut) {
-        onMouseOut(prevHovered);
-      }
     }
   }; // --------------------------------------------------------------------------
   // Lifecycle: DOM 초기화
@@ -7377,7 +7964,7 @@ var WoongCanvasPolygon = function (props) {
     stage.add(baseLayer);
     stage.add(eventLayer); // 초기 뷰포트 설정
 
-    updateViewport(); // ResizeObserver (맵 크기 변경 감지)
+    updateViewport$1(); // ResizeObserver (맵 크기 변경 감지)
 
     var resizeRafId = null;
     var resizeObserver = new ResizeObserver(function () {
@@ -7391,7 +7978,7 @@ var WoongCanvasPolygon = function (props) {
         stage.height(mapDiv.offsetHeight);
         offsetCacheRef.current.clear();
         boundingBoxCacheRef.current.clear();
-        updateViewport();
+        updateViewport$1();
         renderAllImmediate();
         resizeRafId = null;
       });
@@ -7418,8 +8005,6 @@ var WoongCanvasPolygon = function (props) {
           return findData(offset) !== null;
         },
         onClick: onClick,
-        onMouseOver: onMouseOver,
-        onMouseOut: onMouseOut,
         findData: findData,
         setHovered: setHovered,
         handleLocalClick: handleLocalClick,
@@ -7479,18 +8064,8 @@ var WoongCanvasPolygon = function (props) {
   // --------------------------------------------------------------------------
 
   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();
@@ -7540,27 +8115,7 @@ var WoongCanvasPolygon = function (props) {
      * - 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]);
@@ -10405,4 +10960,4 @@ function MintMap(_a) {
   }), loading));
 }
 
-export { AnimationPlayer, Bounds, CanvasDataType, CanvasMarker, CanvasMarkerClaude, CanvasMarkerHanquf, CircleMarker, DEFAULT_CULLING_MARGIN, DEFAULT_MAX_CACHE_SIZE, Drawable, GeoCalulator, GoogleMintMapController, LRUCache, MapBuildingProjection, MapCanvasMarkerWrapper, MapCanvasWrapper, MapControlWrapper, MapEvent, MapLoadingWithImage, MapMarkerWrapper, MapPolygonWrapper, MapPolylineWrapper, MapUIEvent, Marker, MintMap, MintMapCanvasRenderer, MintMapController, MintMapCore, MintMapProvider, NaverMintMapController, Offset, PointLoading, Polygon, PolygonCalculator, PolygonMarker, Polyline, Position, SPATIAL_GRID_CELL_SIZE, SVGCircle, SVGPolygon, SVGRect, Spacing, SpatialHashGrid, Status, WoongCanvasMarker, WoongCanvasPolygon, WoongCanvasProvider, calculateTextBoxWidth, computeMarkerOffset, computePolygonOffsets, getClusterInfo, getMapOfType, hexToRgba, isPointInMarkerData, isPointInPolygon, isPointInPolygonData, log, useMarkerMoving, useMintMapController, useWoongCanvasContext, waiting };
+export { AnimationPlayer, Bounds, CanvasDataType, CanvasMarker, CanvasMarkerClaude, CanvasMarkerHanquf, CircleMarker, DEFAULT_CULLING_MARGIN, DEFAULT_MAX_CACHE_SIZE, Drawable, GeoCalulator, GoogleMintMapController, LRUCache, MapBuildingProjection, MapCanvasMarkerWrapper, MapCanvasWrapper, MapControlWrapper, MapEvent, MapLoadingWithImage, MapMarkerWrapper, MapPolygonWrapper, MapPolylineWrapper, MapUIEvent, Marker, MintMap, MintMapCanvasRenderer, MintMapController, MintMapCore, MintMapProvider, NaverMintMapController, Offset, PointLoading, Polygon, PolygonCalculator, PolygonMarker, Polyline, Position, SPATIAL_GRID_CELL_SIZE, SVGCircle, SVGPolygon, SVGRect, Spacing, SpatialHashGrid, Status, WoongCanvasMarker, WoongCanvasPolygon, WoongCanvasProvider, buildSpatialIndex, calculateTextBoxWidth, computeMarkerOffset, computePolygonOffsets, createMapEventHandlers, getClusterInfo, getMapOfType, hexToRgba, isInViewport, isPointInMarkerData, isPointInPolygon, isPointInPolygonData, log, mapValuesToArray, syncExternalSelectedItems, syncSelectedItems, updateViewport, useMarkerMoving, useMintMapController, useWoongCanvasContext, validateEvent, waiting };