@deepnoid/canvas 0.1.85 → 0.1.86

package/skills/deepnoid-canvas/rules/rendering.md

@@ -0,0 +1,142 @@
+# applyStyle 렌더링 규칙
+
+## 규칙 1: applyStyle은 반드시 제공해야 한다
+
+`drawing.applyStyle`은 필수 prop입니다. 이 함수 없이는 어노테이션이 화면에 표시되지 않습니다.
+
+```tsx
+// ✅ 올바른 사용
+<AnnotationEditor
+  drawing={{
+    lineSize: 2,
+    applyStyle: myStyleFunction,
+    mode: DrawMode.RECTANGLE,
+    color: '#FF4136',
+  }}
+  ...
+/>
+
+// ❌ 잘못된 사용 — applyStyle 누락
+<AnnotationEditor
+  drawing={{
+    lineSize: 2,
+    mode: DrawMode.RECTANGLE,
+  }}
+  ...
+/>
+```
+
+## 규칙 2: variant별로 분기 처리해야 한다
+
+`applyStyle`은 `drawRect`과 `drawText` 두 번 호출됩니다. 각 variant에 맞는 Canvas2D 속성을 설정해야 합니다.
+
+```tsx
+// ✅ 올바른 사용 — variant별 분기
+const applyStyle: ApplyAnnotationStyle = ({ variant, context, annotation, drawLineSize, zoom }) => {
+  if (variant === 'drawRect') {
+    context.strokeStyle = '#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') {
+    context.fillStyle = '#FF4136';
+    context.font = `bold ${14 / zoom}px sans-serif`;
+    // 텍스트 렌더링 로직...
+  }
+};
+
+// ❌ 잘못된 사용 — variant 무시
+const applyStyle: ApplyAnnotationStyle = ({ context, annotation }) => {
+  context.strokeStyle = '#FF4136';
+  context.strokeRect(annotation.x, annotation.y, annotation.width, annotation.height);
+};
+```
+
+## 규칙 3: 모든 크기 값에 zoom 보정을 적용해야 한다
+
+줌 배율이 변해도 어노테이션 선 두께, 폰트 크기, 대시 간격 등이 일정하게 보이려면 반드시 `/ zoom`으로 나누어야 합니다.
+
+```tsx
+// ✅ 올바른 사용 — zoom 보정
+context.lineWidth = drawLineSize / zoom;
+context.font = `bold ${14 / zoom}px sans-serif`;
+context.setLineDash([6 / zoom, 3 / zoom]);
+
+// ❌ 잘못된 사용 — zoom 보정 없음 (줌인하면 선이 점점 두꺼워짐)
+context.lineWidth = drawLineSize;
+context.font = `bold 14px sans-serif`;
+context.setLineDash([6, 3]);
+```
+
+## 규칙 4: annotation.type으로 분기하여 도형을 직접 그려야 한다
+
+`applyStyle`의 `drawRect` variant에서는 스타일 설정뿐 아니라 **실제 도형 그리기**까지 소비자가 담당합니다.
+
+```tsx
+// ✅ 올바른 사용 — 타입별 도형 그리기
+if (variant === 'drawRect') {
+  context.strokeStyle = '#FF4136';
+  context.lineWidth = drawLineSize / 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();
+  }
+}
+
+// ❌ 잘못된 사용 — RECTANGLE만 처리하고 POLYGON 무시
+if (variant === 'drawRect') {
+  context.strokeRect(annotation.x, annotation.y, annotation.width, annotation.height);
+}
+```
+
+## 규칙 5: setLineDash 사용 후 반드시 초기화해야 한다
+
+Canvas2D 컨텍스트는 상태를 유지합니다. `setLineDash`로 점선을 설정하면 다음 어노테이션에도 영향을 줍니다.
+
+```tsx
+// ✅ 올바른 사용 — 조건부 dash + 초기화
+if (annotation.selected) {
+  context.setLineDash([6 / zoom, 3 / zoom]);
+} else {
+  context.setLineDash([]);
+}
+
+// ❌ 잘못된 사용 — selected일 때만 dash 설정, else 빠짐
+if (annotation.selected) {
+  context.setLineDash([6 / zoom, 3 / zoom]);
+}
+// → 다음 어노테이션도 점선으로 그려짐
+```
+
+## 규칙 6: annotation.color를 활용한 상태별 스타일링
+
+어노테이션의 `color` 필드(`'success' | 'warning' | 'danger'`)를 활용하여 상태별 색상을 적용할 수 있습니다.
+
+```tsx
+// ✅ 올바른 사용 — color 필드 매핑
+const colorMap = {
+  success: 'rgba(36, 162, 91, 1)',
+  warning: 'rgba(237, 164, 16, 1)',
+  danger: 'rgba(255, 70, 132, 1)',
+};
+context.strokeStyle = colorMap[annotation.color ?? 'danger'];
+
+// ❌ 잘못된 사용 — color 필드를 직접 CSS 색상으로 사용
+context.strokeStyle = annotation.color; // 'danger'는 유효한 CSS 색상이 아님
+```

package/skills/deepnoid-canvas/setup.md

@@ -0,0 +1,147 @@
+# 소비자 프로젝트 설정 가이드
+
+## 1. 설치
+
+```bash
+# npm
+npm install @deepnoid/canvas
+
+# yarn
+yarn add @deepnoid/canvas
+```
+
+**Peer dependency**: React 19.0.0 이상 필수.
+
+## 2. Claude Code 스킬 설치
+
+패키지에 포함된 스킬을 프로젝트의 `.claude/skills/`에 복사합니다.
+
+```bash
+cp -r node_modules/@deepnoid/canvas/skills/deepnoid-canvas .claude/skills/
+```
+
+이후 Claude Code가 `@deepnoid/canvas` 관련 코드를 작성할 때 자동으로 스킬을 참조합니다.
+
+## 3. 기본 설정
+
+### 최소 구성 (Editor)
+
+```tsx
+import { useState } from 'react';
+import { AnnotationEditor, DrawMode } from '@deepnoid/canvas';
+import type { Annotation, ApplyAnnotationStyle } from '@deepnoid/canvas';
+
+// Step 1: applyStyle 함수 정의 (필수)
+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();
+    }
+  }
+};
+
+// Step 2: 컴포넌트 사용
+function AnnotationPage() {
+  const [annotations, setAnnotations] = useState<Annotation[]>([]);
+
+  return (
+    // Step 3: 반드시 고정 크기의 컨테이너로 감싸기
+    <div style={{ width: '100%', height: '100vh' }}>
+      <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';
+
+function ViewerPage({ annotations }) {
+  return (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <AnnotationViewer
+        image="https://example.com/image.jpg"
+        annotations={annotations}
+        drawing={{ lineSize: 2, applyStyle }}
+        events={{}}
+      />
+    </div>
+  );
+}
+```
+
+## 4. 권장 설정
+
+### 줌/팬 활성화
+
+```tsx
+<AnnotationEditor
+  options={{
+    panZoomEnabled: true,
+    zoom: { min: 0.5, max: 4, step: 0.9 },
+  }}
+  ...
+/>
+```
+
+### annotationSelected 이벤트 연동
+
+어노테이션 클릭 시 그리기 모드 자동 전환:
+
+```tsx
+const [mode, setMode] = useState(DrawMode.RECTANGLE);
+
+useEffect(() => {
+  const handler = (e: CustomEvent) => {
+    if (e.detail?.type) setMode(e.detail.type);
+  };
+  window.addEventListener('annotationSelected', handler);
+  return () => window.removeEventListener('annotationSelected', handler);
+}, []);
+
+<AnnotationEditor drawing={{ mode, ... }} ... />
+```
+
+### ref를 통한 줌 리셋 버튼
+
+```tsx
+import { useRef } from 'react';
+import type { AnnotationCanvasHandle } from '@deepnoid/canvas';
+
+const canvasRef = useRef<AnnotationCanvasHandle>(null);
+
+<button onClick={() => canvasRef.current?.resetImageSize()}>초기화</button>
+<AnnotationEditor ref={canvasRef} ... />
+```
+
+## 5. 체크리스트
+
+소비자 프로젝트 설정 후 확인 사항:
+
+- [ ] React 19+ 설치 확인
+- [ ] `applyStyle` 함수에서 `drawRect`/`drawText` variant 분기 처리
+- [ ] `applyStyle` 내 모든 크기 값에 `/ zoom` 보정 적용
+- [ ] 컨테이너 `div`에 고정 크기(width/height) 설정
+- [ ] RECTANGLE/POLYGON 모두에서 도형 그리기 처리
+- [ ] `events` prop에 최소 빈 객체 `{}` 전달