npm package: @hatiolab/scene-monitor
Description: Chrome DevTools extension for Things Scene monitoring and inspection
Author: heartyoh
Latest version: 1.2.1

# @hatiolab/scene-monitor

Things Scene 보드의 성능 모니터링과 컴포넌트 인스펙션을 위한 Chrome DevTools 확장 프로그램입니다.

---

## 설치

### 방법 1: npm (권장)

프로젝트 루트에서 설치합니다:

```bash
npm install @hatiolab/scene-monitor
```

설치 후 확장 프로그램 파일이 다음 경로에 위치합니다:

```
node_modules/@hatiolab/scene-monitor/
```

### 방법 2: 직접 다운로드

GitHub 저장소에서 `monitor-extension` 폴더를 다운로드합니다:

```bash
git clone https://github.com/user/things-scene.git
cd things-scene/monitor-extension
```

---

## Chrome에 등록

확장 프로그램은 Chrome Web Store를 거치지 않고 직접 로드합니다.

### Step 1: 확장 프로그램 페이지 열기

Chrome 주소창에 입력합니다:

```
chrome://extensions
```

### Step 2: 개발자 모드 활성화

페이지 우측 상단의 **개발자 모드** 토글을 켭니다.

### Step 3: 확장 프로그램 로드

**압축해제된 확장 프로그램을 로드합니다** 버튼을 클릭하고, 폴더를 선택합니다:

- npm 설치한 경우:
  ```
  {프로젝트 루트}/node_modules/@hatiolab/scene-monitor
  ```
- 직접 다운로드한 경우:
  ```
  {다운로드 경로}/things-scene/monitor-extension
  ```

### Step 4: 확인

등록이 완료되면:
- `chrome://extensions` 목록에 **Scene Monitor**가 나타납니다
- Chrome 툴바에 Scene Monitor 아이콘이 추가됩니다
- DevTools (F12)에 **Scene Monitor** 탭이 생깁니다

---

## 사용법

### DevTools 패널 열기

1. Things Scene 보드가 포함된 페이지를 엽니다
2. `F12` (Mac: `Cmd+Option+I`)로 DevTools를 엽니다
3. 상단 탭 목록에서 **Scene Monitor**를 선택합니다

> Scene Monitor 탭이 보이지 않으면 탭 목록 끝의 `>>` 화살표를 클릭하세요.

### Monitor 탭

실시간 성능 지표를 차트로 확인합니다.

| 지표 | 설명 |
|------|------|
| **FPS** | 초당 프레임 수 (높을수록 좋음) |
| **Draw (ms)** | 프레임당 렌더링 소요 시간 (낮을수록 좋음) |
| **Events** | 수집 간격 내 이벤트 트리거 횟수 |
| **Components** | 현재 씬의 총 컴포넌트 수 |

**컨트롤:**
- **Interval 슬라이더**: 데이터 수집 간격 조절 (1초 ~ 30초)
- **Pause**: 수집 일시정지
- **Resume**: 수집 재개
- **Clear**: 차트 데이터 초기화

### Inspector 탭

씬의 컴포넌트 구조를 탐색하고 상태를 확인합니다.

- **좌측 패널**: 컴포넌트 트리. 클릭하여 선택합니다.
- **우측 패널**: 선택된 컴포넌트의 state(상태값)를 JSON으로 표시합니다.
- **보드 연동**: 보드에서 컴포넌트를 클릭하면 Inspector 트리에서 해당 컴포넌트가 자동 선택됩니다.
- **씬 전환 감지**: 새 보드가 열리거나 닫히면 트리가 자동 갱신됩니다.

### 팝업 (툴바 아이콘)

Chrome 툴바의 Scene Monitor 아이콘을 클릭하면 간단한 모니터링 팝업이 열립니다. DevTools를 열지 않고도 FPS 등 기본 지표를 확인할 수 있습니다.

---

## 업데이트

### npm

```bash
npm update @hatiolab/scene-monitor
```

### 직접 다운로드

새 버전의 `monitor-extension` 폴더를 다운로드합니다.

### Chrome 반영

npm 업데이트 또는 파일 교체 후, Chrome에서 확장 프로그램을 새로고침해야 합니다:

1. `chrome://extensions` 열기
2. Scene Monitor 카드의 **새로고침 버튼(↻)** 클릭

> 새로고침 없이는 이전 버전이 계속 실행됩니다.

---

## 트러블슈팅

### Scene Monitor 탭이 보이지 않음

- `chrome://extensions`에서 **개발자 모드**가 활성화되어 있는지 확인
- Scene Monitor가 목록에 있고 **활성화(토글 ON)** 상태인지 확인
- DevTools를 닫았다가 다시 열기 (`F12` 두 번)

### 데이터가 수집되지 않음 (차트가 비어있음)

- 보드 페이지가 완전히 로드되었는지 확인
- **Pause** 상태가 아닌지 확인
- Things Scene v10 이상이 필요합니다 (v9 이하는 `scene.metrics` API 미지원)
- 페이지를 새로고침(`F5`)한 후 DevTools를 다시 열어보세요

### Inspector에서 "Scene not available"

- 보드가 아직 로딩 중일 수 있습니다. 잠시 후 다시 시도하세요.
- 확장 프로그램이 업데이트된 경우, `chrome://extensions`에서 새로고침 필요

### 확장 프로그램이 갑자기 동작하지 않음

Chrome 확장 프로그램이 업데이트되면 기존 연결이 끊어집니다:

1. `chrome://extensions`에서 Scene Monitor **새로고침(↻)**
2. 모니터링 중이던 페이지를 **새로고침(F5)**
3. DevTools를 닫았다가 다시 열기

---

## 요구사항

- **Chrome** 88 이상 (Manifest V3 지원)
- **Things Scene** v10 이상 (`scene.metrics` API 필요)

---

## 연결 방식

확장 프로그램은 페이지의 `globalThis.scene` 또는 `window.scene` 객체를 감지합니다.
Things Scene v10은 씬 생성 시 자동으로 `globalThis.scene`을 설정하므로 별도 설정이 필요 없습니다.

씬이 비동기로 초기화되는 경우에도 최대 30초간 자동 재시도하여 감지합니다.