@deepnoid/canvas 0.1.85 → 0.1.86

package/README.md

@@ -31,9 +31,23 @@ Canvas 기반 이미지 annotation 라이브러리로, **TypeScript Engine + Rea
 ### 설치
 
 ```bash
-npm install deepnoid-canvas
+npm install @deepnoid/canvas
 ```
 
+### Claude Code 스킬 설치 (선택)
+
+소비자 프로젝트에서 Claude Code가 `@deepnoid/canvas` API를 정확하게 사용할 수 있도록 스킬을 복사합니다.
+
+```bash
+# .claude/skills 디렉토리가 없으면 생성
+mkdir -p .claude/skills
+
+# 스킬 복사
+cp -r node_modules/@deepnoid/canvas/skills/deepnoid-canvas .claude/skills/
+```
+
+복사 후 Claude Code에서 `@deepnoid/canvas`를 import하면 자동으로 올바른 사용법, Props, applyStyle 작성법 등을 안내합니다.
+
 ### 기본 사용법
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepnoid/canvas",
-  "version": "0.1.85",
+  "version": "0.1.86",
   "type": "module",
   "license": "MIT",
   "main": "./dist/index.cjs",
@@ -14,7 +14,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "build": "npx tsc -p tsconfig.json",

package/skills/deepnoid-canvas/DEPLOY.md

@@ -0,0 +1,57 @@
+# npm 배포 시 스킬 포함 방법
+
+## 1. package.json 설정
+
+`package.json`의 `files` 필드에 `skills`를 추가하여 npm 배포 시 스킬이 포함되도록 합니다.
+
+```json
+{
+  "name": "@deepnoid/canvas",
+  "files": [
+    "dist",
+    "skills"
+  ]
+}
+```
+
+## 2. 배포
+
+```bash
+# 빌드
+yarn build
+
+# 버전 업
+npm version patch  # 또는 minor, major
+
+# 배포
+npm publish
+```
+
+## 3. 소비자 프로젝트에서 설치
+
+```bash
+# 패키지 설치
+yarn add @deepnoid/canvas
+
+# 스킬 복사 (최초 1회 또는 업데이트 시)
+cp -r node_modules/@deepnoid/canvas/skills/deepnoid-canvas .claude/skills/
+```
+
+## 4. 확인
+
+배포 후 패키지에 스킬이 포함되었는지 확인:
+
+```bash
+# 패키지 내용 확인
+npm pack --dry-run
+```
+
+출력에 `skills/deepnoid-canvas/SKILL.md` 등이 포함되어야 합니다.
+
+## 5. 스킬 업데이트 시
+
+라이브러리 API가 변경되면 스킬도 함께 업데이트해야 합니다:
+
+1. `skills/deepnoid-canvas/` 내 관련 파일 수정
+2. 패키지 버전 업 후 배포
+3. 소비자 프로젝트에서 `cp -r` 명령으로 스킬 재복사

package/skills/deepnoid-canvas/README.md

@@ -0,0 +1,56 @@
+# @deepnoid/canvas Skill
+
+`@deepnoid/canvas` 라이브러리의 Claude Code용 지식 패키지. 소비자 프로젝트에서 Claude Code가 Canvas 어노테이션 API를 정확하게 사용할 수 있도록 합니다.
+
+## 설치
+
+```bash
+# 1. 패키지 설치
+yarn add @deepnoid/canvas
+
+# 2. 스킬 복사
+cp -r node_modules/@deepnoid/canvas/skills/deepnoid-canvas .claude/skills/
+```
+
+## 기능
+
+- **SKILL.md**: 핵심 원칙, 컴포넌트/모드 선택 가이드, 기본 사용 패턴
+- **rules/**: 올바른 사용법 vs 잘못된 사용법 코드 예시
+  - `rendering.md` — applyStyle 렌더링 규칙
+  - `annotations.md` — 어노테이션 데이터 구조 규칙
+  - `events.md` — 이벤트 핸들러, 단축키 규칙
+  - `layout.md` — 캔버스 레이아웃, 줌/팬 규칙
+- **references/**: 완전한 API 레퍼런스
+  - `components.md` — AnnotationEditor, AnnotationViewer Props
+  - `types.md` — Annotation, DrawMode, Label 등 전체 타입
+  - `apply-style.md` — applyStyle 함수 상세 가이드 + 3가지 실전 예제
+- **setup.md**: 소비자 프로젝트 초기 설정 가이드
+- **DEPLOY.md**: npm 배포 시 스킬 포함 방법
+
+## 파일 구조
+
+```
+skills/deepnoid-canvas/
+├── SKILL.md                      ← 핵심 진입점 (트리거 조건 포함)
+├── README.md                     ← 이 파일
+├── DEPLOY.md                     ← npm 배포 방식 안내
+├── setup.md                      ← 소비자 프로젝트 설정 가이드
+├── rules/
+│   ├── rendering.md              ← applyStyle 렌더링 규칙
+│   ├── annotations.md            ← 어노테이션 데이터 규칙
+│   ├── events.md                 ← 이벤트/단축키 규칙
+│   └── layout.md                 ← 레이아웃/줌/팬 규칙
+└── references/
+    ├── components.md             ← 컴포넌트 Props 레퍼런스
+    ├── types.md                  ← 타입 레퍼런스
+    └── apply-style.md            ← applyStyle 함수 레퍼런스
+```
+
+## 자동 트리거
+
+이 스킬은 다음 상황에서 Claude Code에 의해 자동 활성화됩니다:
+
+- import 경로에 `@deepnoid/canvas`가 포함될 때
+- `AnnotationEditor`, `AnnotationViewer`, `DrawMode`, `ApplyAnnotationStyle` 키워드 사용 시
+- Canvas 위 이미지 어노테이션(bounding box, polygon) 관련 질문 시
+- `applyStyle` 콜백 함수를 작성하거나 수정할 때

package/skills/deepnoid-canvas/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: deepnoid-canvas
+description: >
+  @deepnoid/canvas 라이브러리의 완전한 사용 가이드.
+  트리거 조건: import 경로에 '@deepnoid/canvas'가 포함될 때,
+  AnnotationEditor/AnnotationViewer/DrawMode/ApplyAnnotationStyle 키워드가 사용될 때,
+  Canvas 위 이미지 어노테이션(bounding box, polygon) 관련 질문이 있을 때,
+  applyStyle 콜백 함수를 작성하거나 수정할 때 자동 활성화.
+---
+
+# @deepnoid/canvas 스킬
+
+Canvas 기반 이미지 어노테이션 React 라이브러리. 이미지 위에 사각형(BBox)/폴리곤 어노테이션을 그리고, 편집하고, 표시하는 기능을 제공합니다.
+
+## 핵심 원칙
+
+1. **applyStyle은 필수**: 모든 어노테이션의 시각적 표현은 소비자가 `applyStyle` 콜백으로 완전 제어합니다. 라이브러리는 스타일을 자체 적용하지 않습니다.
+2. **컨테이너 크기 필수**: `AnnotationEditor`/`AnnotationViewer`를 감싸는 부모 `div`에 반드시 고정된 width/height (또는 flex: 1)를 설정해야 합니다.
+3. **zoom 보정 필수**: `applyStyle` 내에서 `lineWidth`, `font size`, `setLineDash` 등의 값은 반드시 `/ zoom`으로 나누어야 줌 레벨에 관계없이 일정하게 보입니다.
+4. **Editor vs Viewer 분리**: 편집이 필요하면 `AnnotationEditor`, 읽기 전용이면 `AnnotationViewer`를 사용합니다. 두 컴포넌트의 props가 다릅니다.
+5. **좌표는 원본 이미지 기준**: 모든 어노테이션 좌표(x, y, width, height, points)는 원본 이미지의 픽셀 좌표입니다. 캔버스 표시 좌표와 다릅니다.
+
+## Critical Rules
+
+| 규칙 파일 | 언제 읽어야 하는지 |
+|-----------|-------------------|
+| [rules/rendering.md](rules/rendering.md) | applyStyle 함수를 작성하거나 수정할 때 |
+| [rules/annotations.md](rules/annotations.md) | 어노테이션 데이터를 생성/변환하거나 상태를 관리할 때 |
+| [rules/events.md](rules/events.md) | 이벤트 핸들러, 단축키, annotationSelected 연동 시 |
+| [rules/layout.md](rules/layout.md) | 캔버스 컨테이너 레이아웃, 줌/팬, 리사이즈 관련 작업 시 |
+
+## 컴포넌트 선택 가이드
+
+| 상황 | 사용할 컴포넌트 | 설명 |
+|------|----------------|------|
+| 어노테이션 생성/편집 필요 | `AnnotationEditor` | drawing.mode로 그리기 모드 설정 |
+| 읽기 전용 표시만 필요 | `AnnotationViewer` | mode 불필요, 편집 비활성 |
+| ref로 캔버스 제어 필요 | 둘 다 지원 | `AnnotationCanvasHandle` ref 사용 |
+
+## 그리기 모드 선택 가이드
+
+| 상황 | DrawMode | 설명 |
+|------|----------|------|
+| 바운딩 박스 (사각형) | `DrawMode.RECTANGLE` | 드래그로 사각형 그리기 |
+| 다각형 영역 | `DrawMode.POLYGON` | 클릭으로 점 찍기, 더블클릭/시작점 클릭으로 완성 |
+
+## 핵심 사용 패턴
+
+### 기본 Editor 사용
+
+```tsx
+import { useState } from 'react';
+import { AnnotationEditor, DrawMode } from '@deepnoid/canvas';
+import type { Annotation, ApplyAnnotationStyle } from '@deepnoid/canvas';
+
+const applyStyle: ApplyAnnotationStyle = ({ variant, context, annotation, drawLineSize, zoom }) => {
+  if (variant === 'drawRect') {
+    context.strokeStyle = annotation.selected ? '#00FF00' : '#FF4136';
+    context.lineWidth = drawLineSize / zoom;
+    if (annotation.type === DrawMode.RECTANGLE) {
+      context.strokeRect(annotation.x, annotation.y, annotation.width, annotation.height);
+    } else if (annotation.type === DrawMode.POLYGON) {
+      context.beginPath();
+      annotation.points.forEach((p, i) => i === 0 ? context.moveTo(p.x, p.y) : context.lineTo(p.x, p.y));
+      context.closePath();
+      context.stroke();
+    }
+  }
+  if (variant === 'drawText') {
+    if (annotation.label) {
+      context.fillStyle = '#FF4136';
+      context.font = `bold ${14 / zoom}px sans-serif`;
+      const tx = annotation.type === DrawMode.RECTANGLE ? annotation.x : Math.min(...annotation.points.map(p => p.x));
+      const ty = annotation.type === DrawMode.RECTANGLE ? annotation.y - 5 : Math.min(...annotation.points.map(p => p.y)) - 5;
+      context.fillText(annotation.label.name, tx, ty);
+    }
+  }
+};
+
+function MyEditor() {
+  const [annotations, setAnnotations] = useState<Annotation[]>([]);
+
+  return (
+    <div style={{ width: 800, height: 600 }}>
+      <AnnotationEditor
+        image="https://example.com/image.jpg"
+        annotations={annotations}
+        setAnnotations={setAnnotations}
+        drawing={{
+          mode: DrawMode.RECTANGLE,
+          color: '#FF4136',
+          lineSize: 2,
+          applyStyle,
+        }}
+        events={{}}
+        enableHotkeys
+      />
+    </div>
+  );
+}
+```
+
+### 기본 Viewer 사용
+
+```tsx
+import { AnnotationViewer } from '@deepnoid/canvas';
+
+<div style={{ width: 800, height: 600 }}>
+  <AnnotationViewer
+    image="https://example.com/image.jpg"
+    annotations={annotations}
+    drawing={{ lineSize: 2, applyStyle }}
+    events={{}}
+    options={{ panZoomEnabled: true }}
+  />
+</div>
+```
+
+## API 레퍼런스
+
+상세 API 문서는 [references/](references/) 디렉토리를 참조하세요.
+
+| 레퍼런스 파일 | 내용 |
+|--------------|------|
+| [references/components.md](references/components.md) | AnnotationEditor, AnnotationViewer 전체 Props |
+| [references/types.md](references/types.md) | Annotation, DrawMode, Label 등 모든 타입 |
+| [references/apply-style.md](references/apply-style.md) | applyStyle 함수 시그니처, variant별 가이드, 예제 |
+
+## 초기 설정
+
+소비자 프로젝트에서의 설치 및 설정 방법은 [setup.md](setup.md)를 참조하세요.

package/skills/deepnoid-canvas/references/apply-style.md

@@ -0,0 +1,189 @@
+# applyStyle 함수 레퍼런스
+
+## 시그니처
+
+```typescript
+import type { ApplyAnnotationStyle } from '@deepnoid/canvas';
+
+const applyStyle: ApplyAnnotationStyle = (params) => {
+  const { variant, context, annotation, drawLineSize, zoom } = params;
+  // ...
+};
+```
+
+## 파라미터 상세
+
+| 파라미터 | 타입 | 설명 |
+|----------|------|------|
+| `variant` | `'drawRect' \| 'drawText'` | 현재 렌더링 단계 |
+| `context` | `CanvasRenderingContext2D` | Canvas 2D 그리기 컨텍스트 |
+| `annotation` | `Annotation` | 렌더링 대상 어노테이션 (type으로 판별 가능) |
+| `drawLineSize` | `number` | 설정된 선 두께 (현재 2px 고정 전달) |
+| `zoom` | `number` | 현재 줌 배율 (1 = 100%) |
+
+## 호출 순서
+
+엔진이 각 어노테이션에 대해 다음 순서로 `applyStyle`을 호출합니다:
+
+1. `variant: 'drawRect'` — 도형 외곽선/채우기 렌더링
+2. `variant: 'drawText'` — 라벨 텍스트 렌더링
+
+**중요**: 두 variant 모두에서 실제 Canvas2D 그리기 API(`strokeRect`, `fillText` 등)를 소비자가 직접 호출해야 합니다.
+
+## 예제 1: 기본 스타일 (Fense 스타일)
+
+color 필드에 따라 다른 색상으로 도형을 그리는 패턴.
+
+```typescript
+import { DrawMode } from '@deepnoid/canvas';
+import type { ApplyAnnotationStyle } from '@deepnoid/canvas';
+
+const fenseStyle: ApplyAnnotationStyle = ({ variant, context, annotation, zoom, drawLineSize }) => {
+  if (variant === 'drawRect') {
+    // color 필드로 색상 결정
+    const colorMap: Record<string, string> = {
+      danger: 'rgba(255, 70, 132, 1)',
+      warning: 'rgba(237, 164, 16, 1)',
+      success: 'rgba(36, 162, 91, 1)',
+    };
+    context.strokeStyle = colorMap[annotation.color ?? 'danger'] ?? 'rgba(255, 70, 132, 1)';
+    context.lineWidth = drawLineSize * (1 / zoom);
+
+    if (annotation.type === DrawMode.RECTANGLE) {
+      const { x, y, width, height } = annotation;
+      context.strokeRect(x, y, width, height);
+    } else if (annotation.type === DrawMode.POLYGON) {
+      context.beginPath();
+      annotation.points.forEach((p, idx) => {
+        if (idx === 0) context.moveTo(p.x, p.y);
+        else context.lineTo(p.x, p.y);
+      });
+      context.closePath();
+      context.stroke();
+    }
+  }
+  // drawText는 생략 — 라벨 표시 불필요한 경우
+};
+```
+
+## 예제 2: 고급 스타일 (Seed 스타일)
+
+선택 상태에 따른 색상 변경, 반투명 채우기, 십자 마커, 라벨 텍스트를 포함한 풀 스타일.
+
+```typescript
+const seedStyle: ApplyAnnotationStyle = ({ variant, context, annotation, zoom, drawLineSize }) => {
+  const DEFAULT_COLOR = '#A020F0';
+  const ACTIVE_COLOR = '#FF4136';
+  const baseColor = annotation.selected ? ACTIVE_COLOR : DEFAULT_COLOR;
+
+  if (variant === 'drawRect') {
+    // 스타일 설정
+    context.strokeStyle = `${baseColor}cc`;  // 80% 불투명
+    context.fillStyle = `${baseColor}1a`;    // 10% 불투명
+    context.lineWidth = drawLineSize * (1 / zoom);
+
+    if (annotation.type === DrawMode.RECTANGLE) {
+      const { x, y, width, height } = annotation;
+      context.strokeRect(x, y, width, height);
+      context.fillRect(x, y, width, height);
+
+      // 중심 십자 마커
+      const cx = x + width / 2;
+      const cy = y + height / 2;
+      context.beginPath();
+      context.moveTo(cx, cy - 10);
+      context.lineTo(cx, cy + 10);
+      context.stroke();
+      context.beginPath();
+      context.moveTo(cx - 10, cy);
+      context.lineTo(cx + 10, cy);
+      context.stroke();
+    } else if (annotation.type === DrawMode.POLYGON) {
+      context.beginPath();
+      annotation.points.forEach((p, idx) => {
+        if (idx === 0) context.moveTo(p.x, p.y);
+        else context.lineTo(p.x, p.y);
+      });
+      context.closePath();
+      context.stroke();
+      context.fill();
+    }
+  }
+
+  if (variant === 'drawText') {
+    if (annotation.label) {
+      context.fillStyle = baseColor;
+      context.font = `bold ${28 / zoom}px arial`;
+
+      let textX = 0, textY = 0;
+      if (annotation.type === DrawMode.RECTANGLE) {
+        textX = annotation.x;
+        textY = annotation.y - 5;
+      } else if (annotation.type === DrawMode.POLYGON && annotation.points.length > 0) {
+        textX = Math.min(...annotation.points.map(p => p.x));
+        textY = Math.min(...annotation.points.map(p => p.y)) - 5;
+      }
+      context.fillText(annotation.label.name, textX, textY);
+    }
+  }
+};
+```
+
+## 예제 3: 선택 상태 강조 (점선 + 글로우)
+
+```typescript
+const highlightStyle: ApplyAnnotationStyle = ({ variant, context, annotation, drawLineSize, zoom }) => {
+  if (variant === 'drawRect') {
+    const color = '#00BFFF';
+    context.strokeStyle = color;
+    context.lineWidth = drawLineSize / zoom;
+
+    // 선택 시 점선 + 그림자 효과
+    if (annotation.selected) {
+      context.setLineDash([6 / zoom, 3 / zoom]);
+      context.shadowColor = color;
+      context.shadowBlur = 8 / zoom;
+    } else {
+      context.setLineDash([]);
+      context.shadowColor = 'transparent';
+      context.shadowBlur = 0;
+    }
+
+    if (annotation.type === DrawMode.RECTANGLE) {
+      context.strokeRect(annotation.x, annotation.y, annotation.width, annotation.height);
+    } else if (annotation.type === DrawMode.POLYGON) {
+      context.beginPath();
+      annotation.points.forEach((p, i) => i === 0 ? context.moveTo(p.x, p.y) : context.lineTo(p.x, p.y));
+      context.closePath();
+      context.stroke();
+    }
+
+    // 그림자 초기화 (다음 어노테이션에 영향 방지)
+    context.shadowColor = 'transparent';
+    context.shadowBlur = 0;
+  }
+
+  if (variant === 'drawText') {
+    if (annotation.label) {
+      context.setLineDash([]); // 텍스트에 dash 적용 방지
+      context.fillStyle = '#00BFFF';
+      context.font = `${14 / zoom}px sans-serif`;
+      const tx = annotation.type === DrawMode.RECTANGLE ? annotation.x : Math.min(...annotation.points.map(p => p.x));
+      const ty = (annotation.type === DrawMode.RECTANGLE ? annotation.y : Math.min(...annotation.points.map(p => p.y))) - 5;
+      context.fillText(annotation.label.name, tx, ty);
+    }
+  }
+};
+```
+
+## 체크리스트
+
+applyStyle 함수 작성 시 확인할 사항:
+
+- [ ] `variant === 'drawRect'`와 `variant === 'drawText'` 분기 처리
+- [ ] `annotation.type`으로 RECTANGLE/POLYGON 분기 처리
+- [ ] `lineWidth`, `font`, `setLineDash` 등에 `/ zoom` 보정 적용
+- [ ] `setLineDash` 사용 후 `context.setLineDash([])` 초기화
+- [ ] `shadowBlur` 사용 후 초기화
+- [ ] `annotation.color` 필드를 직접 CSS 색상으로 사용하지 않음 (매핑 필요)
+- [ ] RECTANGLE과 POLYGON 모두에서 실제 도형 그리기 API 호출

package/skills/deepnoid-canvas/references/components.md

@@ -0,0 +1,197 @@
+# 컴포넌트 API 레퍼런스
+
+## AnnotationEditor
+
+이미지 위에 어노테이션을 생성하고 편집할 수 있는 컴포넌트.
+
+### Import
+
+```tsx
+import { AnnotationEditor } from '@deepnoid/canvas';
+import type { AnnotationCanvasHandle } from '@deepnoid/canvas';
+```
+
+### Props
+
+| Prop | Type | Required | Default | 설명 |
+|------|------|----------|---------|------|
+| `image` | `string` | ✅ | — | 이미지 URL |
+| `drawing` | `AnnotationCanvasDrawing` | ✅ | — | 그리기 모드 및 스타일 설정 |
+| `events` | `AnnotationCanvasEvents` | ✅ | — | 이미지 로드 이벤트 핸들러 (빈 객체 가능) |
+| `annotations` | `Annotation[]` | — | `[]` | 어노테이션 목록 |
+| `setAnnotations` | `Dispatch<SetStateAction<Annotation[] \| undefined>>` | — | — | 어노테이션 변경 콜백 |
+| `options` | `AnnotationCanvasOptions` | — | — | 줌/팬 및 기타 옵션 |
+| `enableHotkeys` | `boolean` | — | `true` | 단축키 활성화 여부 |
+| `keepCrossOnImageChange` | `boolean` | — | `false` | 이미지 변경 시 가이드 십자선 유지 |
+
+### ref (AnnotationCanvasHandle)
+
+```tsx
+const canvasRef = useRef<AnnotationCanvasHandle>(null);
+<AnnotationEditor ref={canvasRef} ... />
+```
+
+| Method | 설명 |
+|--------|------|
+| `resetImageSize()` | 캔버스 크기 및 줌을 초기 상태로 리셋 |
+
+### 전체 사용 예시
+
+```tsx
+import { useState, useRef } from 'react';
+import { AnnotationEditor, DrawMode } from '@deepnoid/canvas';
+import type { Annotation, ApplyAnnotationStyle, AnnotationCanvasHandle } from '@deepnoid/canvas';
+
+const applyStyle: ApplyAnnotationStyle = ({ variant, context, annotation, drawLineSize, zoom }) => {
+  if (variant === 'drawRect') {
+    context.strokeStyle = annotation.selected ? '#00FF00' : '#FF4136';
+    context.lineWidth = drawLineSize / zoom;
+    if (annotation.type === DrawMode.RECTANGLE) {
+      context.strokeRect(annotation.x, annotation.y, annotation.width, annotation.height);
+    } else if (annotation.type === DrawMode.POLYGON) {
+      context.beginPath();
+      annotation.points.forEach((p, i) => i === 0 ? context.moveTo(p.x, p.y) : context.lineTo(p.x, p.y));
+      context.closePath();
+      context.stroke();
+    }
+  }
+  if (variant === 'drawText') {
+    if (annotation.label) {
+      context.fillStyle = '#FF4136';
+      context.font = `bold ${14 / zoom}px sans-serif`;
+      const tx = annotation.type === DrawMode.RECTANGLE ? annotation.x : Math.min(...annotation.points.map(p => p.x));
+      const ty = (annotation.type === DrawMode.RECTANGLE ? annotation.y : Math.min(...annotation.points.map(p => p.y))) - 5;
+      context.fillText(annotation.label.name, tx, ty);
+    }
+  }
+};
+
+function MyEditor() {
+  const canvasRef = useRef<AnnotationCanvasHandle>(null);
+  const [annotations, setAnnotations] = useState<Annotation[]>([]);
+  const [mode, setMode] = useState(DrawMode.RECTANGLE);
+
+  return (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <AnnotationEditor
+        ref={canvasRef}
+        image="https://example.com/image.jpg"
+        annotations={annotations}
+        setAnnotations={setAnnotations}
+        drawing={{
+          mode,
+          color: '#FF4136',
+          lineSize: 2,
+          applyStyle,
+          label: { id: 1, name: 'defect', type: 'bbox' },
+        }}
+        events={{
+          onImageLoadSuccess: () => console.log('loaded'),
+          onImageLoadError: (err) => console.error(err),
+        }}
+        options={{
+          panZoomEnabled: true,
+          zoom: { min: 0.5, max: 4, step: 0.9 },
+        }}
+        enableHotkeys
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## AnnotationViewer
+
+이미지 위에 어노테이션을 읽기 전용으로 표시하는 컴포넌트.
+
+### Import
+
+```tsx
+import { AnnotationViewer } from '@deepnoid/canvas';
+```
+
+### Props
+
+| Prop | Type | Required | Default | 설명 |
+|------|------|----------|---------|------|
+| `image` | `string` | ✅ | — | 이미지 URL |
+| `drawing` | `Pick<AnnotationCanvasDrawing, 'lineSize' \| 'applyStyle'>` | ✅ | — | 렌더링 스타일 설정 (`mode`, `color`, `label` 불필요) |
+| `events` | `Pick<AnnotationCanvasEvents, 'onImageLoadSuccess' \| 'onImageLoadError'>` | ✅ | — | 이미지 로드 이벤트 핸들러 (빈 객체 가능) |
+| `annotations` | `Annotation[]` | — | `[]` | 표시할 어노테이션 목록 |
+| `options` | `AnnotationCanvasOptions` | — | — | 줌/팬 및 기타 옵션 |
+| `enableHotkeys` | `boolean` | — | `true` | 단축키 활성화 여부 |
+
+> **AnnotationEditor와의 차이**: `drawing`에서 `mode`, `color`, `label`이 제외됩니다. `setAnnotations`도 불필요합니다. `keepCrossOnImageChange`도 없습니다.
+
+### 전체 사용 예시
+
+```tsx
+import { AnnotationViewer } from '@deepnoid/canvas';
+
+function MyViewer({ annotations }) {
+  return (
+    <div style={{ width: '100%', height: 600 }}>
+      <AnnotationViewer
+        image="https://example.com/image.jpg"
+        annotations={annotations}
+        drawing={{
+          lineSize: 2,
+          applyStyle, // Editor와 동일한 함수 재사용 가능
+        }}
+        events={{
+          onImageLoadSuccess: () => console.log('loaded'),
+        }}
+        options={{
+          panZoomEnabled: true,
+          zoom: { min: 0.5, max: 4 },
+        }}
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## Props 상세 타입
+
+### AnnotationCanvasDrawing
+
+```typescript
+type AnnotationCanvasDrawing = {
+  lineSize: number;                   // 선 두께 (필수)
+  applyStyle: ApplyAnnotationStyle;   // 커스텀 렌더링 함수 (필수)
+  label?: Label;                      // 새 어노테이션에 부여할 라벨 (Editor 전용)
+  mode?: DrawMode;                    // 그리기 모드 (Editor 전용)
+  color?: string;                     // HEX 색상, 새 어노테이션 그리기 시 사용 (Editor 전용)
+};
+```
+
+### AnnotationCanvasOptions
+
+```typescript
+type AnnotationCanvasOptions = {
+  panZoomEnabled?: boolean;           // 줌/팬 활성화 (기본: false)
+  zoom?: {
+    min?: number;                     // 최소 줌 (기본: 0.1)
+    max?: number;                     // 최대 줌 (기본: Infinity)
+    step?: number;                    // 줌 단계 (기본: 0.9)
+  };
+  ZoomButton?: ComponentType<{        // 커스텀 줌 버튼
+    onClick: () => void;
+    children: ReactNode;
+  }>;
+  resetOnImageChange?: boolean;       // 이미지 변경 시 줌 리셋 (기본: false)
+};
+```
+
+### AnnotationCanvasEvents
+
+```typescript
+type AnnotationCanvasEvents = {
+  onImageLoadSuccess?: () => void;
+  onImageLoadError?: (error: Error) => void;
+};
+```