@ssafy-mhk/e-ver 1.0.1 → 1.0.3

package/README.md

@@ -1,9 +1,10 @@
 # `@ssafy-mhk/e-ver` - Virtual Fitting React SDK 👗👕
 
-S14P21M104 가상 피팅(WebAR) 프로젝트를 위한 공식 프론트엔드 React SDK입니다. 
+S14P21M104 가상 피팅(WebAR) 프로젝트를 위한 공식 프론트엔드 React SDK입니다.
 복잡한 Three.js 카메라 및 조명 설정, MediaPipe AI 바디 트래킹 연동, SkinnedMesh 기반 의류 렌더링 로직을 추상화하여, **단순한 React 컴포넌트와 Hook**으로 증강현실(AR) 가상 피팅 기능을 빠르게 구현할 수 있도록 지원합니다.
 
 ## 개발 스택 (Technology Stack)
+
 - **Framework**: React / Next.js 호환
 - **3D & AR Rendering**: Three.js, React Three Fiber (R3F), Drei, three-vrm
 - **AI Tracking**: MediaPipe Pose Landmarker (Lite)
@@ -13,21 +14,36 @@ S14P21M104 가상 피팅(WebAR) 프로젝트를 위한 공식 프론트엔드 Re
 
 ## 🛠 설치 방법 (Installation)
 
-이 패키지는 사내 또는 외부 NPM에 직접 배포되기 전 로컬 저장소를 통한 심볼릭 링크(Symbolic Link) 방식으로 연결하거나 파일 디렉토리를 참조하여 사용할 수 있습니다.
+이 패키지는 배포 전 로컬 검증 시 tarball로 패키징한 뒤 소비 애플리케이션에 설치해서 확인하는 방식을 권장합니다.
+
+### 배포된 패키지 설치
 
-### 로컬 프로젝트에서 참조하여 설치할 경우:
-여러분의 Next.js 프로젝트 최상위 폴더(`frontend`)에서 아래 명령어를 실행하세요.
+여러분의 Next.js 프로젝트 최상위 폴더에서 아래 명령어를 실행하세요.
 
 ```bash
 # pnpm 사용 시
-pnpm add ../sdk
+pnpm add @ssafy-mhk/e-ver
 
 # 또는 패키지 매니저에 따라
-npm install ../sdk
-yarn add file:../sdk
+npm install @ssafy-mhk/e-ver
+yarn add @ssafy-mhk/e-ver
+```
+
+_(의존성 설치가 잘 되었는지 꼭 `package.json` 코드를 확인하세요.)_
+
+### 이 레포에서 `frontend`로 로컬 검증할 경우
+
+`/ever/frontend`에서 아래 명령어를 실행하면 `/ever/sdk`를 빌드하고 tarball로 패키징한 뒤 현재 프론트엔드에 설치합니다.
+
+```bash
+pnpm run sdk:use-tarball
 ```
 
-*(의존성 설치가 잘 되었는지 꼭 `package.json` 코드를 확인하세요.)*
+검증 후 퍼블리시된 버전으로 되돌릴 때는 아래 명령어를 사용합니다.
+
+```bash
+pnpm run sdk:use-version -- 1.0.3
+```
 
 ---
 
@@ -35,15 +51,15 @@ yarn add file:../sdk
 
 SDK는 크게 **State(상태 관리)**, **Renderer(렌더링 UI)**, **Tracker(추적/측정 Hook)** 이렇게 3가지 핵심 축으로 구성됩니다.
 
-| 분류 | 모듈명 | 역할 |
-|---|---|---|
-| **State** | `useEverStore` | 웹캠 활성화 여부, 렌더링 중인 옷/아바타 주소, 최종 핏 결과(체형 측정) 관리 |
-| **Renderer** | `EverCanvas` | AR/3D 환경에 최적화된 조명과 카메라 세팅을 내장한 R3F 캔버스 래퍼 |
-| **Renderer** | `AvatarModel` | 사용자의 AI 기반 생성 3D 아바타(GLB)를 로딩하고, 뼈대(Bone) 구조를 추출 |
-| **Renderer** | `GarmentModel` | 사용자가 선택한 옷(GLB)을 로딩하고, 옷의 SkinnedMesh를 대상 아바타에 입힘 |
-| **Tracker** | `usePoseTracker` | 브라우저 내에서 MediaPipe를 가동시켜 실시간 30-60Hz 웹캠 추적 |
-| **Tracker** | `usePoseMapper` | 웹캠에서 얻은 2D/3D 점(Landmarks)을 필수 13본(Bone)의 회전값(Quaternion)으로 변환 |
-| **Tracker** | `useBodyMeasurer` | AR 카메라 상에서 사용자 실루엣 기반 사이즈(어깨, 가슴, 허리)를 연산하여 옷의 핏 평가 |
+| 분류         | 모듈명            | 역할                                                                                 |
+| ------------ | ----------------- | ------------------------------------------------------------------------------------ |
+| **State**    | `useEverStore`    | 웹캠 활성화 여부, 렌더링 중인 옷/아바타 주소, 최종 핏 결과(체형 측정) 관리           |
+| **Renderer** | `EverCanvas`      | AR/3D 환경에 최적화된 조명과 카메라 세팅을 내장한 R3F 캔버스 래퍼                    |
+| **Renderer** | `AvatarModel`     | 사용자의 AI 기반 생성 3D 아바타(GLB)를 로딩하고, 뼈대(Bone) 구조를 추출              |
+| **Renderer** | `GarmentModel`    | 사용자가 선택한 옷(GLB)을 로딩하고, 옷의 SkinnedMesh를 대상 아바타에 입힘            |
+| **Tracker**  | `usePoseTracker`  | 브라우저 내에서 MediaPipe를 가동시켜 실시간 30-60Hz 웹캠 추적                        |
+| **Tracker**  | `usePoseMapper`   | 웹캠에서 얻은 2D/3D 점(Landmarks)을 필수 13본(Bone)의 회전값(Quaternion)으로 변환    |
+| **Tracker**  | `useBodyMeasurer` | AR 카메라 상에서 사용자 실루엣 기반 사이즈(어깨, 가슴, 허리)를 연산하여 옷의 핏 평가 |
 
 ---
 
@@ -53,7 +69,7 @@ SDK는 크게 **State(상태 관리)**, **Renderer(렌더링 UI)**, **Tracker(
 
 ### Step 1. Zustand로 글로벌 상태 세팅하기
 
-우선, 애플리케이션 외부 버튼 조작을 위해 스토어를 호출할 수 있습니다. 
+우선, 애플리케이션 외부 버튼 조작을 위해 스토어를 호출할 수 있습니다.
 
 ```tsx
 // app/fitting/page.tsx
@@ -67,7 +83,7 @@ export default function FittingControls() {
   return (
     <div className="absolute top-4 left-4 z-10 flex flex-col gap-2">
       <button onClick={() => setWebcamActive(true)}>웹캠 가동 시작 🎥</button>
-      <button onClick={() => setActiveGarmentUrl('/path/to/clothes.glb')}>
+      <button onClick={() => setActiveGarmentUrl("/path/to/clothes.glb")}>
         새로운 옷 입어보기 👕
       </button>
 
@@ -83,46 +99,44 @@ export default function FittingControls() {
 
 ### Step 2. 3D AR 캔버스 및 모델 구축하기
 
-SDK에서 제공하는 `EverCanvas`, `AvatarModel`, `GarmentModel`을 활용하여 화면을 그립니다. 
+SDK에서 제공하는 `EverCanvas`, `AvatarModel`, `GarmentModel`을 활용하여 화면을 그립니다.
 
 ```tsx
 // components/VirtualFittingScene.tsx
 "use client";
 
 import { useState } from "react";
-import { 
-  EverCanvas, 
-  AvatarModel, 
-  GarmentModel, 
-  useEverStore 
+import {
+  EverCanvas,
+  AvatarModel,
+  GarmentModel,
+  useEverStore,
 } from "@ssafy-mhk/e-ver";
 
 export default function VirtualFittingScene() {
   const [avatarBones, setAvatarBones] = useState<Record<string, THREE.Bone>>();
   const { activeGarmentUrl } = useEverStore();
-  
+
   // 내 계정의 3D 아바타 파일 경로
-  const AVATAR_URL = "/models/my-avatar.glb"; 
+  const AVATAR_URL = "/models/my-avatar.glb";
 
   return (
     <div className="w-full h-screen bg-transparent relative">
       {/* 1. 기본 AR 조명이 세팅된 캔버스 호출 */}
       <EverCanvas showEnvironment={true}>
-        
         {/* 2. 사용자의 베이스 아바타 불러오기 */}
-        <AvatarModel 
-          url={AVATAR_URL} 
-          onBonesReady={(bones) => setAvatarBones(bones)} 
+        <AvatarModel
+          url={AVATAR_URL}
+          onBonesReady={(bones) => setAvatarBones(bones)}
         />
-        
+
         {/* 3. 활성화된 옷이 있다면 아바타 위에 덧입히기 */}
         {activeGarmentUrl && avatarBones && (
-          <GarmentModel 
-            url={activeGarmentUrl} 
-            targetAvatarBones={avatarBones} 
+          <GarmentModel
+            url={activeGarmentUrl}
+            targetAvatarBones={avatarBones}
           />
         )}
-
       </EverCanvas>
     </div>
   );
@@ -142,23 +156,23 @@ import { usePoseTracker, useEverStore } from "@ssafy-mhk/e-ver";
 
 export default function ArCameraView() {
   const videoRef = useRef<HTMLVideoElement>(null);
-  
+
   // SDK 내부의 로직을 통해 실시간으로 프레임을 MediaPipe에 전송
   const { isTrackerReady } = usePoseTracker(videoRef);
   const { isWebcamActive } = useEverStore();
 
   return (
     <div className="absolute inset-0 z-0">
-       <video
-          ref={videoRef}
-          autoPlay
-          playsInline
-          muted
-          className="w-full h-full object-cover"
-          style={{ display: isWebcamActive ? "block" : "none" }}
-       />
-       {/* Tracker가 로딩 중일 때 로딩 오버레이 표시 가능 */}
-       {!isTrackerReady && isWebcamActive && <p>AI 모델 로딩 중...</p>}
+      <video
+        ref={videoRef}
+        autoPlay
+        playsInline
+        muted
+        className="w-full h-full object-cover"
+        style={{ display: isWebcamActive ? "block" : "none" }}
+      />
+      {/* Tracker가 로딩 중일 때 로딩 오버레이 표시 가능 */}
+      {!isTrackerReady && isWebcamActive && <p>AI 모델 로딩 중...</p>}
     </div>
   );
 }

package/dist/api/EverClient.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/EverProvider.d.ts

@@ -1,12 +1,4 @@
 import React from "react";
-import * as THREE from "three";
-export interface EverContextType {
-    videoRef: React.RefObject<HTMLVideoElement | null>;
-    avatarBones: Record<string, THREE.Bone> | null;
-    setAvatarBones: (bones: Record<string, THREE.Bone> | null) => void;
-    isProviderReady: boolean;
-}
-export declare const useEver: () => EverContextType;
 export interface EverProviderProps {
     children: React.ReactNode;
 }

package/dist/components/ever-context.d.ts

@@ -0,0 +1,9 @@
+import * as THREE from "three";
+export interface EverContextType {
+    videoRef: React.RefObject<HTMLVideoElement | null>;
+    avatarBones: Record<string, THREE.Bone> | null;
+    setAvatarBones: (bones: Record<string, THREE.Bone> | null) => void;
+    isProviderReady: boolean;
+}
+export declare const EverContext: import("react").Context<EverContextType | undefined>;
+export declare function useEver(): EverContextType;

package/dist/hooks/useBodyMeasurer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/useEverGeneration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/usePoseMapper.d.ts

@@ -1,7 +1,13 @@
 import * as THREE from "three";
+interface PoseLandmark {
+    x: number;
+    y: number;
+    z: number;
+}
 /**
  * Custom hook to map MediaPipe 2D/3D landmarks to 3D bones (Quaternions).
  */
 export declare const usePoseMapper: () => {
-    mapPoseToBones: (landmarks: any[], targetBones: Record<string, THREE.Bone>) => void;
+    mapPoseToBones: (landmarks: PoseLandmark[], targetBones: Record<string, THREE.Bone>) => void;
 };
+export {};

package/dist/hooks/usePoseTracker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./store/useEverStore";
 export * from "./components/EverProvider";
+export * from "./components/ever-context";
 export * from "./components/EverCanvas";
 export * from "./components/CameraView";
 export * from "./components/AvatarModel";

package/dist/index.es.js

@@ -17837,11 +17837,15 @@ var mg = class {
 		let t = this.getContext();
 		t.drawingBufferColorSpace = $n._getDrawingBufferColorSpace(e), t.unpackColorSpace = $n._getUnpackColorSpace();
 	}
-}, hg = i(void 0), gg = () => {
+}, hg = i(void 0);
+function gg() {
 	let e = o(hg);
 	if (!e) throw Error("useEver must be used within an EverProvider");
 	return e;
-}, _g = ({ children: e }) => {
+}
+//#endregion
+//#region src/components/EverProvider.tsx
+var _g = ({ children: e }) => {
 	let t = u(null), [n, r] = d(null), i = {
 		videoRef: t,
 		avatarBones: n,
@@ -35941,7 +35945,7 @@ var Ux = ({ children: e, showEnvironment: t = !0 }) => /* @__PURE__ */ p(_g, { c
 		if (!n) return;
 		let e = {};
 		return n.traverse((t) => {
-			t.isBone && (e[t.name] = t);
+			t instanceof oo && (e[t.name] = t);
 		}), i(e), t && t(e), () => i(null);
 	}, [
 		n,
@@ -35959,7 +35963,7 @@ var Ux = ({ children: e, showEnvironment: t = !0 }) => /* @__PURE__ */ p(_g, { c
 	let { scene: n } = ax(e), r = u(null), { avatarBones: i } = gg(), a = t || i;
 	return s(() => {
 		!n || !a || n.traverse((e) => {
-			if (e.isSkinnedMesh) {
+			if (e instanceof ao) {
 				let t = e, n = [];
 				t.skeleton.bones.forEach((e) => {
 					a[e.name] ? n.push(a[e.name]) : n.push(e);
@@ -40789,4 +40793,4 @@ function iM(e) {
 	};
 }
 //#endregion
-export { Gx as AvatarModel, Wx as CameraView, Ux as EverCanvas, tM as EverClient, _g as EverProvider, qx as GarmentModel, Qj as useBodyMeasurer, gg as useEver, iM as useEverGeneration, E as useEverStore, Zj as usePoseMapper, Xj as usePoseTracker };
+export { Gx as AvatarModel, Wx as CameraView, Ux as EverCanvas, tM as EverClient, hg as EverContext, _g as EverProvider, qx as GarmentModel, Qj as useBodyMeasurer, gg as useEver, iM as useEverGeneration, E as useEverStore, Zj as usePoseMapper, Xj as usePoseTracker };