open-plant 1.3.7 → 1.4.0

package/CHANGELOG.md

@@ -7,25 +7,47 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-03-16
+
 ### Added
+- **선언적 레이어 컴포지션 API**: `WsiViewer` + 자식 레이어 컴포넌트로 관심사 분리.
+  - `WsiViewer`: Context Provider + WebGL 캔버스 관리 (~15개 core props).
+  - `PointLayer`: 포인트 렌더링, 클리핑, 히트 테스트 캡슐화.
+  - `RegionLayer`: ROI 리전 렌더링, 라벨, hover/active 상태 관리.
+  - `DrawingLayer`: 드로잉 도구 (freehand, rectangle, circular, stamp, brush).
+  - `PatchLayer`: 패치 리전 렌더링.
+  - `OverlayLayer`: 오버레이 셰이프 렌더링.
+- `ViewerContext` + `useViewerContext()`: 레이어 간 `rendererRef`, 좌표 변환, draw registry 공유.
+- `PointQueryHandle` + `forwardRef` 패턴: `getCellByCoordinatesRef`를 대체하는 `PointLayer` imperative handle.
+- `DrawTool` 타입 확장: `"eraser"`, `"region-brush"`, `"region-eraser"` 문자열 리터럴 추가.
+- `StampToolConfig` 구조화 타입: `{ stamp: { shape: "circle", areaMm2: 0.2 } }` — 매직 스트링 대체.
+- `StampShape` 타입: `"rectangle" | "circle"`.
+- `RegionLayerProps.labelStyle`: `Partial<RegionLabelStyle> | RegionLabelStyleResolver` 통합 prop.
 - Web Worker 기반 포인트 공간 인덱스 빌드 (`point-hit-index-worker`). 메인 스레드 ~175ms 블로킹 제거.
 - `FlatPointSpatialIndex` flat typed array 자료구조 + open-addressing hash table lookup.
 - `buildPointSpatialIndexAsync()`, `lookupCellIndex()`, `terminatePointHitIndexWorker()` public API.
 - 인접 tier (T±1) 타일 prefetch: 빠른 줌 시 blank frame 감소.
 - `getVisibleTilesForTier(tier)` public method on `WsiTileRenderer`.
+- 배율 스냅 줌 API: `zoomSnaps`, `zoomSnapFitAsMin` (`WsiViewerCanvas`/`WsiTileRenderer`).
+- `WsiTileRenderer.getViewBounds()` public method.
 - 최적화 리포트: `perf-optimization-report.md`.
 
 ### Changed
+- `WsiViewerCanvasProps`에 `@deprecated` JSDoc 추가. 기존 인터페이스는 동일하게 유지.
 - `pointHitIndex` 빌드가 `useMemo` (동기) → `useEffect` + `useState` (비동기 워커)로 전환.
 - 워커 인덱스 알고리즘: nested `Map` → 4-pass counting sort (GC-free, typed arrays only).
 - 워커 프로토콜: positions/ids를 워커가 반환하지 않음 — 메인 스레드가 원본 참조 (전송량 ~120MB → ~48MB).
 - `getCellByCoordinates` 내부 lookup: nested `Map.get()` → `Int32Array` hash table O(1).
 - 타일 스케줄링: 현재 tier 외 인접 tier 타일을 `distance2` 페널티 기반 낮은 우선순위로 포함.
 - 내부 perf logging (`logPerf`, `shouldLogPerf`, `PERF_LOG_*`) 제거.
+- Overview map viewport 인디케이터 렌더 경로 개선: `getViewBounds`가 없어도 `getViewCorners`만으로 현재 뷰포트 표시 가능.
+- Overview map 기본 viewport border 색상을 고대비 주황 계열로 조정.
 
 ### Docs
 - `performance-optimization.md` 업데이트: 워커 인덱스, prefetch, flat hash 내용 추가.
 - `README.md` 프로젝트 구조: 워커/클라이언트 파일 반영.
+- `README.md` API/props 섹션을 현재 export/동작 기준으로 정리(중복 제거 포함).
+- EN/KO API reference와 Getting Started에 `zoomSnaps`, `zoomSnapFitAsMin`, `pointInnerFillOpacity`, `regionLabelAnchor`, `clampRegionLabelToViewport` 반영.
 
 ## [1.2.4] - 2026-02-25
 

package/README.md

@@ -14,7 +14,7 @@
   <a href="https://github.com/frorong/open-plant">GitHub</a>
 </p>
 
-> Engine roadmap: [`engine-roadmap.md`](./engine-roadmap.md)
+> Engine process note: [`engine-build-process.md`](./engine-build-process.md)
 
 ---
 
@@ -76,8 +76,10 @@ draw mode에 진입하면 `setPointerCapture`로 입력을 독점해 팬(드래
 | **타일 전용 색상 보정** | `imageColorSettings`로 brightness/contrast/saturation 실시간 반영 (cell/ROI/draw overlay는 영향 없음) |
 | **회전 인터랙션** | `WsiViewState.rotationDeg`, `Ctrl/Cmd + drag` 회전, `resetRotation` 경로 |
 | **줌 범위 제어 + 전환 애니메이션** | `minZoom`/`maxZoom` clamp + `viewTransition`(duration/easing) |
+| **배율 스냅 줌** | `zoomSnaps`, `zoomSnapFitAsMin`으로 wheel/더블클릭을 표준 배율 단계에 맞춰 이동 |
 | **포인트 오버레이** | WebGL2 `gl.POINTS`로 수십, 수백만 개 포인트를 팔레트 텍스처 기반 컬러링. 파싱된 TypedArray만 입력 |
 | **포인트 크기 커스터마이즈** | `pointSizeByZoom` 객체로 zoom별 셀(px) 크기 지정 + 내부 선형 보간 |
+| **포인트 내부 채움 제어** | `pointInnerFillOpacity`로 ring 내부 채움 강도 제어 |
 | **포인트 렌더 모드 제어** | `pointData.fillModes`로 ring/solid 렌더링 제어 |
 | **모바일 타겟 성능** | iPhone 15급 환경에서 수백만 cell 워크로드를 전제로 pan/zoom 응답성을 유지하도록 설계 |
 | **드로잉 / ROI 도구** | Freehand · Rectangle · Circular · Brush + Stamp(사각형/원, mm² 지정) |
@@ -150,6 +152,8 @@ import { WsiViewerCanvas } from "open-plant";
   minZoom={0.25} // 미지정 시 fitZoom * 0.5
   maxZoom={1} // 미지정 시 fitZoom * 8
   viewTransition={{ duration: 300 }}
+  zoomSnaps={[1.25, 2.5, 5, 10, 20, 40]}
+  zoomSnapFitAsMin
   authToken={bearerToken}
   pointData={pointPayload}
   pointPalette={termPalette.colors}
@@ -159,6 +163,7 @@ import { WsiViewerCanvas } from "open-plant";
     10: 17.5,
     12: 28,
   }}
+  pointInnerFillOpacity={0.15}
   clipPointsToRois
   clipMode="worker"
   onClipStats={(s) => console.log(s.mode, s.durationMs)}
@@ -206,6 +211,14 @@ import { WsiViewerCanvas } from "open-plant";
     // stamp-rectangle-4096px 전용
     handlePatch(patch);
   }}
+  overviewMapConfig={{
+    show: true,
+    options: {
+      viewportBorderStyle: "dash",
+      viewportBorderColor: "rgba(255, 106, 61, 0.95)",
+      viewportFillColor: "rgba(255, 106, 61, 0.08)",
+    },
+  }}
   onViewStateChange={handleViewChange}
   onStats={setStats}
 />
@@ -219,6 +232,8 @@ import { WsiViewerCanvas } from "open-plant";
 - `activeRegionId`를 주면 controlled mode, 생략하면 uncontrolled mode로 동작합니다.
 - `minZoom`/`maxZoom`은 휠/더블클릭/`setViewState`/`fitToImage` 전 경로에 동일 clamp가 적용됩니다.
 - `viewTransition`은 `setViewState`/`fitToImage`/`zoomBy` 전환에 적용되며 `duration` 최대값은 `2000ms`입니다.
+- `zoomSnaps`는 배율(magnification) 배열 입력이며 `source.mpp`를 기준으로 내부 zoom 값으로 정규화됩니다.
+- `zoomSnapFitAsMin=true`이면 snap-out 경로에서 fit zoom을 하한으로 취급합니다.
 - `drawFillColor` 기본값은 `transparent`입니다.
 - `brushOptions.radius`는 HTML/CSS px 기준이며, 줌이 바뀌어도 on-screen 크기는 고정됩니다.
 - `brushOptions.clickSelectRoi=true`이면 브러시 탭(드래그 없음) 시 ROI를 먼저 선택하고, ROI 외부 탭은 일반 브러시 결과를 반환합니다.
@@ -226,7 +241,7 @@ import { WsiViewerCanvas } from "open-plant";
 - `drawAreaTooltip.enabled=true`이면 freehand/rectangle/circular 그리기 중 커서 근처에 실시간 면적(mm²)을 표시합니다.
 - `roiRegions[].coordinates`는 ring / polygon(with holes) / multipolygon을 모두 지원합니다.
 
-#### WsiViewerCanvas Props By Concern
+#### WsiViewerCanvas Props by concern
 
 **View / Camera**
 
@@ -240,6 +255,8 @@ import { WsiViewerCanvas } from "open-plant";
 | `ctrlDragRotate` | `boolean` | 기본 `true` |
 | `minZoom` / `maxZoom` | `number` | 미지정 시 `fitZoom*0.5` / `fitZoom*8` |
 | `viewTransition` | `{ duration?: number; easing?: (t)=>number }` | 기본 즉시 반영(duration 0) |
+| `zoomSnaps` | `number[]` | 확대 배율 스냅 목록(배율 단위) |
+| `zoomSnapFitAsMin` | `boolean` | 스냅 아웃 시 fit zoom을 하한으로 취급할지 여부 |
 | `authToken` | `string` | 타일/포인트 요청 인증 |
 | `overviewMapConfig` | `OverviewMapConfig` | 미니맵 표시/옵션 |
 
@@ -252,6 +269,7 @@ import { WsiViewerCanvas } from "open-plant";
 | `pointPalette` | `Uint8Array \| null` | RGBA 팔레트 텍스처 |
 | `pointSizeByZoom` | `Record<number, number>` | continuous zoom stop |
 | `pointStrokeScale` | `number` | point ring 두께 스케일 |
+| `pointInnerFillOpacity` | `number` | 포인트 내부 채움 불투명도 (`0..1`) |
 | `clipPointsToRois` | `boolean` | ROI 외부 포인트 필터 |
 | `clipMode` | `"sync" \| "worker" \| "hybrid-webgpu"` | 기본 `"worker"` |
 | `onClipStats` | `(event) => void` | clip 실행 통계 |
@@ -273,8 +291,10 @@ import { WsiViewerCanvas } from "open-plant";
 | `patchStrokeStyle` | `Partial<RegionStrokeStyle>` | patch 선 스타일 |
 | `resolveRegionStrokeStyle` | `RegionStrokeStyleResolver` | 상태별 동적 stroke |
 | `regionLabelStyle` | `Partial<RegionLabelStyle>` | 기본 배지 스타일 override |
+| `regionLabelAnchor` | `RegionLabelAnchorMode` | 라벨 anchor 모드 (`top-center`, `centroid`) |
 | `resolveRegionLabelStyle` | `RegionLabelStyleResolver` | 줌/region별 동적 라벨 스타일 |
 | `autoLiftRegionLabelAtMaxZoom` | `boolean` | max zoom 도달 시 라벨 auto-lift |
+| `clampRegionLabelToViewport` | `boolean` | 라벨 화면 경계 clamp 적용 |
 | `drawAreaTooltip` | `DrawAreaTooltipOptions` | draw 중 실시간 mm² tooltip |
 | `overlayShapes` | `DrawOverlayShape[]` | 커스텀 도형/반전 마스크 |
 | `customLayers` | `WsiCustomLayer[]` | host React 오버레이 슬롯 |
@@ -308,14 +328,25 @@ import { WsiViewerCanvas } from "open-plant";
 
 현재 뷰포트를 표시하는 인터랙티브 미니맵입니다. `overviewMapConfig.show`를 `true`로 설정하면 `WsiViewerCanvas`에 함께 렌더링됩니다.
 
+| Option | Type | Notes |
+|---|---|---|
+| `width` / `height` | `number` | 미니맵 캔버스 크기 |
+| `margin`, `position`, `borderRadius` | `number`, enum | 배치/모서리 |
+| `backgroundColor`, `borderColor` | `string` | 배경/테두리 색 |
+| `viewportBorderStyle` | `"stroke" \| "dash"` | 현재 뷰포트 선 스타일 |
+| `viewportBorderColor`, `viewportFillColor` | `string` | 현재 뷰포트 선/채움 |
+| `interactive` | `boolean` | 클릭/드래그로 recenter |
+| `showThumbnail`, `maxThumbnailTiles` | `boolean`, `number` | 썸네일 렌더링 제어 |
+| `onClose`, `closeIcon`, `closeButtonStyle` | callback / `ReactNode` / `CSSProperties` | 닫기 버튼 UI 옵션 |
+
 ## API
 
 | Export | 설명 |
 |---|---|
 | `WsiViewerCanvas`, `DrawLayer`, `OverviewMap`, `TileViewerCanvas` | React 컴포넌트 |
 | `WsiTileRenderer`, `M1TileRenderer`, `TileScheduler` | 렌더러/스케줄러 클래스 |
-| `normalizeImageInfo`, `toTileUrl` | 이미지 메타데이터/타일 URL 유틸 |
-| `buildTermPalette`, `calcScaleResolution`, `calcScaleLength`, `toBearerToken` | 공통 유틸 |
+| `normalizeImageInfo`, `toTileUrl`, `toRoiGeometry`, `parseWkt` | 이미지/좌표 유틸 |
+| `buildTermPalette`, `calcScaleResolution`, `calcScaleLength`, `toBearerToken`, `clamp` | 공통 유틸 |
 | `filterPointDataByPolygons`, `filterPointDataByPolygonsInWorker`, `filterPointDataByPolygonsHybrid` | ROI 포인트 클리핑 |
 | `filterPointIndicesByPolygons`, `filterPointIndicesByPolygonsInWorker`, `terminateRoiClipWorker` | 인덱스 기반 클리핑/워커 관리 |
 | `buildPointSpatialIndexAsync`, `lookupCellIndex`, `terminatePointHitIndexWorker` | 포인트 공간 인덱스 (워커) |
@@ -324,32 +355,6 @@ import { WsiViewerCanvas } from "open-plant";
 | `closeRing`, `createRectangle`, `createCircle` | 도형 유틸 |
 | 타입 export (`WsiViewerCanvasProps`, `WsiImageSource`, `WsiPointData`, `WsiViewTransitionOptions` 등) | TypeScript 통합용 공개 타입 |
 
-### `<DrawLayer>`
-
-Freehand, Rectangle, Circular + Stamp(사각형/원) 드로잉 오버레이.
-
-### `<OverviewMap>`
-
-현재 뷰포트를 표시하는 인터랙티브 미니맵.
-
-## API
-
-| Export | 설명 |
-|---|---|
-| `WsiTileRenderer` | WebGL2 WSI 타일 + 포인트 렌더러 클래스 |
-| `M1TileRenderer` | 기본 타일 렌더러 클래스 |
-| `normalizeImageInfo(raw, tileBaseUrl)` | API 응답 + 타일 베이스 URL을 `WsiImageSource`로 변환 |
-| `filterPointDataByPolygons()` | ROI 폴리곤으로 포인트 필터링 |
-| `filterPointDataByPolygonsInWorker()` | 워커 스레드 ROI 필터링 |
-| `filterPointIndicesByPolygons()` | 폴리곤 내부 원본 포인트 인덱스 추출(패치 JSON export용) |
-| `filterPointIndicesByPolygonsInWorker()` | 포인트 인덱스 추출 워커 버전 |
-| `filterPointDataByPolygonsHybrid()` | WebGPU bbox prefilter + polygon 정밀 판정(실험) |
-| `getWebGpuCapabilities()` | WebGPU 지원/어댑터 정보 조회 |
-| `buildTermPalette()` | Term 기반 컬러 팔레트 생성 |
-| `toTileUrl()` | 타일 URL 생성 |
-| `calcScaleResolution()` | 현재 줌 기준 μm/px 계산 |
-| `calcScaleLength()` | 100px 스케일 라벨 문자열 생성 |
-
 ## Scripts
 
 ```bash