@makeitnow/jumpitnow 0.0.0-stage → 0.1.0-alpha.2

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# 변경 안내
+
+## 0.1.0-alpha.2 · 2026-10-10
+
+- 제품 이름을 반영해 npm 패키지 이름을 `@makeitnow/jumpitnow`로 정리했습니다.
+- JavaScript 함수·입력값·결과값·예제 중심으로 교사용 사용 안내를 정리했습니다.
+- README에 AI 코딩 도구용 요청문, 바로 실행하는 가상 장비 예제, 데이터 표시·저장 규칙을 추가했습니다.
+- 설치 파일 생성과 설치 안내를 복구했습니다.
+- 예제 화면에서 장비별 실행 결과를 읽기 쉬운 문장으로 표시합니다.
+
+연결·장비 선택·운동 설정·시작·데이터 수신·정지 기능을 제공합니다. 실제 장비 검증은 아직 진행하지 않았습니다.

package/README.md

@@ -1,3 +1,367 @@
-# Temporary Holding Version
+# Jumpitnow SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**줄넘기 데이터를 나만의 수업 화면, 운동 기록, 게임으로.**
+
+npm 패키지 이름: **`@makeitnow/jumpitnow`**
+
+Jumpitnow 게이트웨이와 스마트 줄넘기를 JavaScript 함수로 사용하는 SDK입니다. 연결, 장비 선택, 운동 설정, 시작·정지, 데이터 수신을 앱에 붙일 수 있습니다. 장비가 없어도 가상 줄넘기로 먼저 개발할 수 있습니다.
+
+이 README를 AI 코딩 도구에 전달하고 만들고 싶은 서비스를 설명하세요. 아래 요청문과 공개 함수로 개발을 시작할 수 있습니다.
+
+> **현재 버전: `0.1.0-alpha.2`**  
+> 개발 확인용입니다. 실제 장비 검증은 아직 진행하지 않았습니다. npm 공개가 완료된 버전 또는 전달받은 `.tgz` 설치 파일로 시작하세요. 가상 장비에서 동작한 결과가 실제 장비 호환성을 보장하지는 않습니다.
+
+[AI에게 전달할 요청문](#ai에게-전달할-요청문) · [설치](#설치) · [바로 실행하기](#가상-줄넘기로-바로-실행하기) · [함수 안내](#공개-함수-한눈에-보기) · [데이터 저장](#운동-데이터를-표시하고-저장하기)
+
+## 어떤 서비스를 만들 수 있나요?
+
+| 만들고 싶은 서비스 | SDK로 받는 기능 | 앱에서 만드는 기능 |
+|---|---|---|
+| 수업 현황판 | 여러 줄넘기의 횟수·경과 시간 수신 | 장비 선택, 카드 화면, 수업 진행 |
+| 개인 운동 기록장 | 운동 시작·정지와 마지막 측정값 | 기록 저장, 날짜별 조회, CSV 내보내기 |
+| 목표 달성 챌린지 | 목표 횟수·목표 시간 설정 | 진행률, 목표 달성 화면, 배지 |
+| 줄넘기 게임 | 선택한 줄넘기의 운동 데이터 | 점수 계산, 캐릭터 움직임, 게임 규칙 |
+
+SDK는 장비 기능을 제공합니다. 로그인, 학생 명단, 데이터베이스, 저장 API, 그래프와 게임 규칙은 앱에서 구현합니다. SDK가 학생 정보를 자동 수집하거나 기록을 외부 저장소에 자동 전송하지 않습니다.
+
+완성된 화면을 먼저 보려면 [줄넘기 기록실 예제](https://jumpitnow-records-example.kkongnamul11.workers.dev)를 열어 **가상 줄넘기 → 연결하고 검색 → 장비 선택 → 기록 시작 → 정지하고 저장**을 체험하세요. 이 예제는 브라우저별 기록 공간을 사용하며, 교사 계정 로그인이나 다른 기기와의 기록 동기화 기능은 없습니다.
+
+## AI에게 전달할 요청문
+
+아래 내용을 README와 함께 AI 코딩 도구에 붙여 넣으세요. `[만들 서비스]`만 원하는 내용으로 바꾸면 됩니다.
+
+```text
+Jumpitnow SDK를 사용해서 [만들 서비스: 예를 들어 줄넘기 수업 기록장]을 만들어줘.
+첨부한 README와 docs/API.md를 함수 사용의 기준으로 삼아줘.
+
+1. 개발 방식
+- 기존 프로젝트의 화면 구성과 프레임워크를 먼저 확인해줘.
+- SDK는 @makeitnow/jumpitnow의 공개 함수로만 사용해줘.
+- 문서에 없는 함수, 이벤트, 필드를 임의로 만들지 마.
+- npm에서 해당 버전을 조회할 수 있으면 버전을 고정해 설치해줘.
+  등록 전이거나 공개 처리 중이면 전달받은 .tgz로 설치해줘.
+- 처음에는 createSimulatedGateway({ deviceCount: 3 })로 개발해줘.
+- 화면에 '연습 모드'를 표시하고 가상 기록과 실제 기록을 구분해줘.
+- 실제 장비 모드에서는 createGateway()를 사용하고,
+  사용자가 연결 버튼을 눌렀을 때 connect()를 호출해줘.
+
+2. 화면과 운동 흐름
+- 연결 → 검색 → 장비 직접 선택 → 운동 설정 → 시작 → 데이터 표시
+  → 정지 확인 → 기록 저장 → 연결 종료 순서로 만들어줘.
+- 검색 결과 전체를 자동으로 운동 대상으로 선택하지 마.
+- 자유 운동, 목표 횟수, 목표 시간 중 하나를 선택하게 해줘.
+- configure()의 ok가 true일 때만 start()를 호출해줘.
+- 시작에 전달한 장비 목록은 별도로 보관하고, 정지할 때도 사용해줘.
+- 명령 처리 중에는 중복 클릭을 막고, 운동 중에는 대상과 모드 변경을 막아줘.
+- 결과의 ok와 장비별 results를 모두 확인해줘.
+- failed와 unknown, 일부 시작 실패 후 recovery 결과를 화면에 구분해줘.
+- 정지 여부를 확인하지 못하면 현장 확인을 안내하고 자동 재시작하지 마.
+
+3. 데이터와 저장
+- measurement 이벤트의 count는 누적값이므로 기존 횟수에 더하지 마.
+- deviceId + sessionId + segmentId별로 측정값을 구분해줘.
+- sessionId는 장비별 운동 식별값이므로 수업 전체에는 앱의 별도 기록 ID를 써줘.
+- elapsedMs는 밀리초, receivedAt은 수신 시각이야. 둘을 혼동하지 마.
+- 오래된 값과 연결 끊김을 표시하고 마지막 값을 최신처럼 표시하지 마.
+- stop()의 정지 결과와 finalMeasurement 확보 여부를 따로 확인해줘.
+- 저장은 앱에서 구현해줘. SDK에 save(), login() 같은 함수를 만들지 마.
+- 저장 실패 시 기록을 유지하고 같은 기록 ID로 재시도해 중복을 막아줘.
+- 연습용 데이터의 simulated 표시를 저장할 때도 유지해줘.
+
+4. 완료 확인
+- 연결 취소, 선택한 장비 없음, 일부 시작 실패, 연결 끊김,
+  마지막 측정값 없음, 저장 실패 상황을 확인해줘.
+- 이벤트 구독을 중복 등록하지 말고 사용이 끝나면 해제해줘.
+- 실행 방법, 변경한 파일, 확인한 동작과 실제 장비 검증이 남은 부분을 알려줘.
+```
+
+화면을 확장할 때는 다음처럼 덧붙일 수 있습니다.
+
+| 원하는 화면 | 요청문에 추가할 내용 |
+|---|---|
+| 교실 현황판 | “선택한 줄넘기를 큰 카드로 보여주고 횟수와 경과 시간을 표시해줘.” |
+| 기록장 | “종료한 운동을 저장하고 목록·상세 보기·CSV 다운로드를 만들어줘.” |
+| 게임 | “현재 운동 구간에서 늘어난 횟수만 점수에 반영하고, 구간이 바뀌면 기준값을 새로 잡아줘.” |
+
+## 설치
+
+JavaScript 또는 TypeScript 웹 프로젝트에 설치합니다. 패키지 설치·개발에는 Node.js 20 이상이 필요하며, 앱 개발 도구가 더 높은 버전을 요구하면 해당 조건을 따릅니다.
+
+### npm으로 설치
+
+npm 공개가 완료된 버전은 앱 프로젝트 폴더에서 다음과 같이 설치합니다.
+
+```sh
+npm install --save-exact @makeitnow/jumpitnow@0.1.0-alpha.2
+```
+
+등록 전이거나 발행 직후 아직 조회되지 않는다면 아래 설치 파일 방식을 사용하세요. 두 설치 방식 중 하나를 선택합니다.
+
+### 전달받은 파일로 설치
+
+프로젝트 안에 `vendor` 폴더를 만들고 전달받은 `makeitnow-jumpitnow-0.1.0-alpha.2.tgz` 파일을 넣은 뒤, 프로젝트 폴더에서 실행하세요.
+
+```sh
+npm install ./vendor/makeitnow-jumpitnow-0.1.0-alpha.2.tgz
+```
+
+아직 프로젝트가 없다면 `mkdir my-jumprope-app`, `cd my-jumprope-app`, `npm init -y`를 차례로 실행한 뒤 위와 같이 설치합니다. 이 방법으로 아래 가상 장비 예제를 바로 실행할 수 있습니다.
+
+JavaScript와 TypeScript에서 같은 방식으로 가져옵니다. 타입 정의가 포함되어 있어 별도의 타입 패키지는 필요하지 않습니다.
+
+```js
+import { createGateway, createSimulatedGateway, getSupport } from '@makeitnow/jumpitnow';
+```
+
+## 가상 줄넘기로 바로 실행하기
+
+설치한 프로젝트에 아래 내용을 `practice.mjs`로 저장하고 `node practice.mjs`를 실행하세요. **가상 줄넘기 한 대**의 연결부터 수신·정지·연결 종료까지 확인합니다. 실제 장비는 움직이지 않으며 기록을 외부로 저장하지 않습니다.
+
+```js
+import { createSimulatedGateway } from '@makeitnow/jumpitnow';
+
+const gateway = createSimulatedGateway({ deviceCount: 1 });
+const unsubscribe = gateway.on('measurement', value => {
+  console.log(`${value.count}회 / ${(value.elapsedMs / 1000).toFixed(1)}초`);
+});
+const unsubscribeError = gateway.on('error', error => {
+  console.error(error.code, error.message);
+});
+
+try {
+  await gateway.connect();
+  const { devices } = await gateway.scan();
+  // 이 예제에서만 가상 장비 한 대를 선택합니다.
+  // 실제 수업 앱에서는 사용자가 목록에서 직접 선택하게 만드세요.
+  const device = devices.find(item => item.state === 'available');
+  if (!device) throw new Error('사용할 줄넘기가 없습니다.');
+  const deviceIds = [device.deviceId];
+
+  const configured = await gateway.configure({ deviceIds, mode: { type: 'free' } });
+  if (!configured.ok) {
+    console.table(configured.results);
+    throw new Error('운동 설정 결과를 확인하세요.');
+  }
+
+  const started = await gateway.start({ deviceIds });
+  if (!started.ok) {
+    console.table(started.results);
+    throw new Error('시작 및 정지 복구 결과를 확인하세요.');
+  }
+
+  // 예제에서는 약 3초 동안 수신합니다. 앱에서는 사용자의 정지 버튼을 사용합니다.
+  await new Promise(resolve => setTimeout(resolve, 3000));
+
+  const stopped = await gateway.stop({ deviceIds });
+  console.table(stopped.results);
+  if (!stopped.ok) throw new Error('정지 여부를 확인하지 못한 장비가 있습니다.');
+
+  for (const result of stopped.results) {
+    const final = result.finalMeasurement;
+    if (final?.available && final.measurement) {
+      console.log('마지막 운동 값:', final.measurement);
+    } else {
+      console.log('정지는 확인했지만 마지막 운동 값은 확보하지 못했습니다.');
+    }
+  }
+} finally {
+  try {
+    const closed = await gateway.disconnect();
+    if (!closed.closed || (closed.stopResults && !closed.stopResults.ok)) {
+      console.error('연결 종료 또는 장비 정지 상태를 확인하세요.', closed);
+    }
+  } finally {
+    unsubscribe();
+    unsubscribeError();
+  }
+}
+```
+
+가상 장비는 앱 개발을 위한 연습 도구입니다. 화면 반응과 기록 흐름을 확인하는 데 사용하고, 수치의 증가 속도를 실제 운동 속도나 성능 측정 기준으로 사용하지 마세요.
+
+## 실제 장비를 사용하는 웹 화면
+
+컴퓨터용 Chrome 또는 Edge에서 HTTPS 페이지나 `localhost` 개발 환경을 사용합니다. 실제 장비 연결은 브라우저 화면에서 실행하며 서버의 API 처리 코드에서 실행하지 않습니다.
+
+먼저 `getSupport().supported`로 현재 브라우저의 연결 기능을 확인합니다. 이 값은 **브라우저 환경 확인**이며 실제 장비의 연결·호환성 검증 결과가 아닙니다.
+
+아래 코드는 웹 화면에 연결할 형태를 보여줍니다. `connectButton`, `showDevicePicker`, `showMessage`는 앱에서 구현하는 버튼과 화면 함수이며 SDK 함수가 아닙니다.
+
+```js
+import { createGateway, getSupport } from '@makeitnow/jumpitnow';
+
+const gateway = createGateway(); // 화면을 다시 그릴 때마다 새로 만들지 않습니다.
+
+connectButton.onclick = async () => {
+  if (!getSupport().supported) {
+    showMessage('컴퓨터용 Chrome 또는 Edge에서 실행 환경을 확인해주세요.');
+    return;
+  }
+  connectButton.disabled = true;
+  try {
+    await gateway.connect(); // 사용자의 클릭에서 바로 호출합니다.
+    const { devices } = await gateway.scan();
+    showDevicePicker(devices); // 사용 가능한 장비를 보여주고 직접 선택받습니다.
+  } catch (error) {
+    showMessage(error.message);
+  } finally {
+    connectButton.disabled = false;
+  }
+};
+```
+
+웹 앱에서는 운동 중 연결·검색·설정 버튼도 잠급니다. 가상/실제 모드를 바꿀 때는 기존 운동의 정지를 확인하고 연결 종료와 구독 해제를 마친 뒤 새 인스턴스를 만드세요.
+
+전체 화면 구성은 [브라우저 예제](examples/browser/app.js)와 [React 예제](examples/react/GatewayPanel.tsx)를 참고하세요. React에서는 SDK 인스턴스를 화면 수명 동안 유지하고 이벤트 구독을 해제합니다. 페이지를 닫거나 컴포넌트가 사라지는 순간에 비동기 정지가 완료될 것이라고 가정하지 말고, 명시적인 종료 버튼에서 정지 결과를 확인하세요.
+
+## 공개 함수 한눈에 보기
+
+**앱에서 가져오는 기능**
+
+| 함수·클래스 | 용도 |
+|---|---|
+| `createGateway()` | 실제 장비용 인스턴스 생성 |
+| `createSimulatedGateway({ deviceCount: 3 })` | 가상 장비용 인스턴스 생성 |
+| `getSupport()` | 현재 브라우저의 연결 기능 확인 |
+| `SDKError` | 함수 호출 오류의 `code`, `message` 확인 |
+
+**`gateway`에서 사용하는 함수**
+
+| 함수 | 입력·결과 요약 |
+|---|---|
+| `connect()` | 연결 후 정보 반환. 실패하면 오류 발생 |
+| `scan()` | `{ devices, status, windowMs }` 반환. 배열 자체를 반환하지 않음 |
+| `getDevices()` | 현재 장비 목록 반환 |
+| `configure({ deviceIds, mode })` | 선택한 장비의 운동 방식 설정 |
+| `start({ deviceIds })` | 설정된 장비의 운동 시작 |
+| `stop({ deviceIds })` | 운동 정지 및 장비별 마지막 값 확보 시도 |
+| `on('measurement', handler)` | 운동 값 수신. 구독 해제 함수 반환 |
+| `readMeasurement({ deviceId })` | 특정 장비의 현재 값 요청 |
+| `getLastMeasurement({ deviceId })` | 마지막 값 또는 `null` 반환. 새 값을 요청하지 않음 |
+| `readBattery({ deviceId })` | `{ kind: 'percent', value }` 또는 알 수 없음 표시 |
+| `identify({ deviceId, signal })` | 해당 장비에서 활성화된 경우에만 위치 확인 신호 사용 |
+| `getInfo()` / `getDiagnostics()` | 연결 정보 / 문제 확인용 요약 반환 |
+| `disconnect()` | `{ closed, stopResults }` 반환 |
+
+`connect`, `scan`, `configure`, `start`, `stop`, `readMeasurement`, `readBattery`, `identify`, `disconnect`는 비동기 함수입니다. `await`와 `try/catch`를 사용하세요. 장비 작업은 순서대로 실행하고 여러 장비의 개별 요청을 `Promise.all()`로 동시에 보내지 않습니다.
+
+`deviceIds`에는 검색 결과에서 선택한 `deviceId`를 넣습니다. 빈 배열, 중복 ID, 학생 이름, 장비 표시 번호를 대신 넣지 마세요. `identify()`는 기본적으로 활성화되어 있지 않으므로 필수 수업 흐름에 넣지 않습니다.
+
+### 운동 모드
+
+아래 셋 중 **하나**를 `configure({ deviceIds, mode })`의 `mode`에 전달합니다.
+
+```js
+const freeMode = { type: 'free' };
+const countMode = { type: 'count', targetCount: 100 };
+const timeMode = { type: 'time', durationSeconds: 60 };
+```
+
+목표값은 양의 정수입니다. 선택한 장비의 `capabilities`에 있는 `modes`, `maxTargetCount`, `maxDurationSeconds` 범위에서 입력받으세요. 목표 달성 표시와 앱의 기록 종료·저장 처리는 별도로 구현하며, 목표에 도달했다는 이유로 저장이 완료되었다고 표시하지 않습니다.
+
+### 명령 결과와 이벤트
+
+`configure()`, `start()`, `stop()`, `identify()`는 `{ requestId, ok, results }`를 반환합니다. 오류가 발생하지 않았더라도 **`ok: false`일 수 있습니다.**
+
+| 장비별 결과 | 앱에서 처리할 내용 |
+|---|---|
+| `status: 'acknowledged'` | 해당 요청이 확인됨 |
+| `status: 'failed'` | 해당 요청이 처리되지 않음 |
+| `status: 'unknown'` | 처리 여부 확인 필요. 성공으로 표시하지 않음 |
+| `recovery` | 일부 시작 실패 후 수행한 정지 시도의 결과 확인 |
+| `finalMeasurement` | 정지 시 마지막 값 확보 여부 확인 |
+
+`start()` 일부 실패 시 처음 시작 요청의 `acknowledged`만 보고 운동 중으로 표시하지 마세요. `recovery`로 이미 정지를 시도했을 수 있습니다. `stop()`을 기다린 결과의 `ok`는 정지 확인 여부이고, 마지막 측정값 확보 여부와는 다릅니다. `disconnect()` 결과의 `closed`도 장비 정지 성공 여부와 별개입니다.
+
+지원하는 이벤트는 아래 네 가지입니다. 별도의 `ready`, `data`, `finished`, `saved` 이벤트는 없습니다.
+
+| 이벤트 | 콜백에서 받는 값 |
+|---|---|
+| `measurement` | 측정값 객체 |
+| `deviceChanged` | `{ device, previousState }` |
+| `connectionChanged` | `{ state, previousState }` |
+| `error` | `{ code, message, recoverable, ... }` |
+
+이벤트의 `error` 처리와 비동기 함수의 `try/catch`를 모두 구현합니다. `recoverable: true`를 자동 재시작 허용으로 해석하지 마세요.
+
+## 운동 데이터를 표시하고 저장하기
+
+### 측정값 읽기
+
+| 필드 | 의미와 사용 규칙 |
+|---|---|
+| `deviceId` | 현재 SDK에서 장비를 구분하는 값. 문자열 내용을 해석하거나 학생의 영구 ID로 사용하지 않음 |
+| `displayNumber` | 화면에 보여줄 장비 번호. 미확인 시 `null` |
+| `sessionId` | 해당 장비의 운동 식별값. 수업 전체의 공통 ID가 아님 |
+| `segmentId` | 운동 안의 구간 식별값. 달라지면 새로운 구간으로 구분 |
+| `count` | 현재 구간의 누적 횟수 |
+| `elapsedMs` | 현재 구간의 경과 시간. 초 표시 시 `1000`으로 나눔 |
+| `pauseCount` | 멈춤 횟수. 알 수 없으면 `null`이며 0과 구분 |
+| `receivedAt` | 앱이 값을 받은 시각. Unix 시간, 밀리초 단위 |
+| `source` | `live`: 수신한 값 / `cache`: 마지막 보관 값 |
+| `stale` | 오래되었거나 현재 상태 확인이 필요한 값이면 `true` |
+| `simulated` | 연습용 가상 데이터이면 `true` |
+
+같은 구간에서 `10 → 12 → 15`를 받았다면 현재 횟수는 **15회**입니다. 합계 37회로 저장하지 마세요. 같은 `(deviceId, sessionId, segmentId)`의 기록은 마지막 누적값으로 갱신합니다. 여러 구간의 합계가 필요하면 구간마다 확정한 값을 한 번씩 합산하고, 누락된 마지막 값은 미확인 상태로 남깁니다.
+
+운동이 시작되면 SDK가 `measurement` 이벤트로 값을 전달하므로 기본 화면은 이벤트를 구독하면 됩니다. 별도로 반복 읽기를 중복 구현할 필요는 없습니다. `readMeasurement()`도 수신 이벤트를 발생시키므로 반환값과 이벤트를 각각 새 기록으로 추가하지 마세요.
+
+수신이 멈춘 경우 기존 객체의 `stale` 값이 저절로 바뀌지는 않습니다. 화면 갱신 시 `getLastMeasurement()`로 상태를 다시 확인하고 `connectionChanged`, `deviceChanged`도 함께 반영하세요.
+
+### 저장은 앱에서 구현하기
+
+SDK에는 `save()`, `saveRecord()`, 로그인, 기록 조회 함수가 없습니다. 브라우저 임시 보관, 서버 저장, CSV 다운로드를 앱 기능으로 만듭니다.
+
+권장 저장 흐름은 다음과 같습니다.
+
+1. 시작 전에 앱의 운동 기록 ID를 만들고 선택한 장비와 모드를 보관합니다.
+2. 수신한 측정값을 장비·운동·구간별로 갱신합니다. 전체 추이를 저장하려면 저장 간격도 앱에서 정합니다.
+3. 처음 시작에 전달한 장비 목록으로 `stop()`을 호출합니다.
+4. 장비별 정지 결과를 기록하고, 확보한 `finalMeasurement.measurement`로 마지막 값을 갱신합니다. 값이 없으면 이전 값을 확정값으로 꾸미거나 0으로 채우지 않습니다.
+5. 앱의 저장 API에 전송합니다. 정지 미확인 기록은 그 상태를 보존합니다.
+6. 저장소의 성공 응답을 확인한 뒤 “저장 완료”를 표시합니다. 실패하면 임시 기록과 같은 기록 ID로 재시도하며, 서버도 같은 ID의 중복 저장을 막도록 구현합니다.
+
+다음은 **앱에서 정할 수 있는 저장 형식**입니다. SDK의 반환 형식은 아닙니다.
+
+```text
+운동 기록
+├─ recordId                 앱이 만든 운동 기록 ID
+├─ startedAt / endedAt      앱에서 기록한 시작·종료 시각
+├─ mode                     사용한 운동 모드와 목표
+├─ simulated                연습용 여부
+└─ devices[]                선택한 장비별 기록
+   ├─ deviceId / displayNumber
+   ├─ stopStatus            acknowledged / failed / unknown
+   ├─ finalMeasurementAvailable
+   └─ segments[]            sessionId + segmentId별 마지막 값 또는 측정 이력
+```
+
+학교·교사 계정, 학생과 장비의 연결 관계, 조회 권한은 앱에서 관리하세요. 저장소 비밀키는 브라우저 코드에 넣지 않습니다. 연습 데이터는 실제 수업 통계에서 분리합니다.
+
+## 앱을 공유하기 전에 확인하기
+
+- [ ] 장비 없이 연습 모드에서 연결·검색·선택·시작·수신·정지가 된다.
+- [ ] 선택하지 않은 장비를 시작하지 않으며, 중복 클릭이 막힌다.
+- [ ] 설정 실패, 일부 시작 실패, 정지 미확인을 각각 표시한다.
+- [ ] 같은 구간의 누적값과 반복 수신을 중복 합산하지 않는다.
+- [ ] 연결이 끊기면 오래된 데이터를 구분하고 자동으로 운동을 재시작하지 않는다.
+- [ ] 마지막 값이 없거나 저장이 실패해도 기록을 성공으로 꾸미지 않는다.
+- [ ] 저장 재시도 시 같은 운동 기록이 중복 생성되지 않는다.
+- [ ] 화면을 다시 열어도 이벤트 구독이 중복되지 않는다.
+- [ ] 실제 사용 환경에서 장비 연결·횟수·시간·정지 결과를 확인한다.
+
+가상 장비로 예외 화면을 확인할 때는 `createSimulatedGateway({ deviceCount: 3, startFailures: [2] })`로 2번 장비의 시작 실패를 만들거나, `gateway.simulation.dropConnection()`으로 연결 끊김을 재현할 수 있습니다. 이 연습 기능은 가상 장비 인스턴스에서만 사용합니다.
+
+## 더 알아보기
+
+| 문서·예제 | 내용 |
+|---|---|
+| [함수 사용법](docs/API.md) | 입력값, 결과값, 이벤트 사용 예 |
+| [그림으로 보는 사용 가이드](docs/index.html) | 브라우저에서 열어 보는 기능 안내 |
+| [사용 환경](docs/COMPATIBILITY.md) | 실제 장비 사용 조건과 검증 상태 |
+| [수업 운영과 기록 관리](docs/SECURITY.md) | 장비 선택, 정지 확인, 기록 관리 |
+| [브라우저 예제](examples/browser/app.js) | 연결·선택·운동·수신 화면 구현 |
+| [React 예제](examples/react/GatewayPanel.tsx) | React 화면에서 공개 함수 사용 |
+| [변경 기록](CHANGELOG.md) | 버전별 변경 내용 |
+
+SDK 이용 조건은 배포자가 안내하는 정책을 확인하세요. 현재 패키지의 라이선스 표기는 `UNLICENSED`이며, 교사 배포용 이용 조건은 아직 확정되지 않았습니다.

package/dist/cjs/index.d.ts

@@ -0,0 +1,6 @@
+import type { Gateway, GatewayOptions, SimulatedGateway, SimulationOptions } from './types.js';
+export { getSupport } from './internal/link.js';
+export { SDKError } from './internal/errors.js';
+export type * from './types.js';
+export declare function createGateway(options?: GatewayOptions): Gateway;
+export declare function createSimulatedGateway(options?: SimulationOptions): SimulatedGateway;

package/dist/cjs/index.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDKError = exports.getSupport = void 0;
+exports.createGateway = createGateway;
+exports.createSimulatedGateway = createSimulatedGateway;
+const gateway_js_1 = require("./internal/gateway.js");
+const link_js_1 = require("./internal/link.js");
+const simulator_js_1 = require("./internal/simulator.js");
+var link_js_2 = require("./internal/link.js");
+Object.defineProperty(exports, "getSupport", { enumerable: true, get: function () { return link_js_2.getSupport; } });
+var errors_js_1 = require("./internal/errors.js");
+Object.defineProperty(exports, "SDKError", { enumerable: true, get: function () { return errors_js_1.SDKError; } });
+function facade(engine) {
+    return {
+        connect: () => engine.connect(), disconnect: () => engine.disconnect(),
+        getInfo: () => engine.getInfo(), scan: options => engine.scan(options), getDevices: () => engine.getDevices(),
+        configure: options => engine.configure(options), start: options => engine.start(options), stop: options => engine.stop(options),
+        readMeasurement: options => engine.readMeasurement(options), getLastMeasurement: options => engine.getLastMeasurement(options),
+        readBattery: options => engine.readBattery(options), identify: options => engine.identify(options),
+        on: (event, handler) => engine.on(event, handler), getDiagnostics: () => engine.getDiagnostics()
+    };
+}
+function createGateway(options = {}) {
+    return Object.freeze(facade(new gateway_js_1.GatewayEngine(new link_js_1.BrowserLink(), options)));
+}
+function createSimulatedGateway(options = {}) {
+    const link = new simulator_js_1.SimulationLink(options);
+    return Object.freeze({ ...facade(new gateway_js_1.GatewayEngine(link, options, true)), simulation: link.controls() });
+}

package/dist/cjs/internal/errors.d.ts

@@ -0,0 +1,15 @@
+import type { ErrorCode, ErrorInfo } from '../types.js';
+export declare class SDKError extends Error implements ErrorInfo {
+    readonly code: ErrorCode;
+    readonly recoverable: boolean;
+    readonly deviceId?: string;
+    readonly requestId?: string;
+    constructor(code: ErrorCode, context?: {
+        deviceId?: string;
+        requestId?: string;
+    });
+    toJSON(): ErrorInfo;
+}
+export declare const fail: (code: ErrorCode) => never;
+export declare const asError: (error: unknown, fallback?: ErrorCode) => SDKError;
+export declare function integer(value: unknown, min: number, max: number): number;

package/dist/cjs/internal/errors.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asError = exports.fail = exports.SDKError = void 0;
+exports.integer = integer;
+const messages = {
+    UNSUPPORTED_BROWSER: '이 브라우저는 USB 장비 연결을 지원하지 않습니다.',
+    INSECURE_CONTEXT: 'HTTPS 또는 localhost에서 실행해주세요.',
+    USER_CANCELLED: '포트 선택을 취소했습니다.', PORT_UNAVAILABLE: 'USB 포트를 열거나 해제할 수 없습니다.',
+    NOT_CONNECTED: '게이트웨이를 먼저 연결해주세요.', UNSUPPORTED_GATEWAY: '지원하는 게이트웨이 응답을 확인하지 못했습니다.',
+    UNSUPPORTED_FEATURE: '이 장비에서 활성화되지 않은 기능입니다.', INVALID_ARGUMENT: '입력값을 확인해주세요.',
+    INVALID_STATE: '현재 상태에서 실행할 수 없습니다. 장비 상태를 먼저 확인해주세요.',
+    DEVICE_OFFLINE: '장비의 응답을 확인할 수 없습니다.', AMBIGUOUS_DEVICE: '장비 번호가 중복되었거나 응답 대상을 확인할 수 없습니다.',
+    BUSY: '다른 장비 작업이 진행 중입니다.', TIMEOUT: '제한 시간 안에 응답을 받지 못했습니다.',
+    DEVICE_REJECTED: '장비 또는 게이트웨이가 요청을 거부했습니다.', CONNECTION_LOST: '게이트웨이 연결이 끊어졌습니다.',
+    PROTOCOL_ERROR: '지원하는 응답 형식이 아닙니다.'
+};
+class SDKError extends Error {
+    code;
+    recoverable;
+    deviceId;
+    requestId;
+    constructor(code, context = {}) {
+        super(messages[code]);
+        this.name = 'SDKError';
+        this.code = code;
+        this.recoverable = !['UNSUPPORTED_BROWSER', 'UNSUPPORTED_GATEWAY', 'UNSUPPORTED_FEATURE', 'INVALID_ARGUMENT'].includes(code);
+        this.deviceId = context.deviceId;
+        this.requestId = context.requestId;
+    }
+    toJSON() {
+        return { code: this.code, message: this.message, recoverable: this.recoverable,
+            ...(this.deviceId ? { deviceId: this.deviceId } : {}), ...(this.requestId ? { requestId: this.requestId } : {}) };
+    }
+}
+exports.SDKError = SDKError;
+const fail = (code) => { throw new SDKError(code); };
+exports.fail = fail;
+const asError = (error, fallback = 'PROTOCOL_ERROR') => error instanceof SDKError ? error : new SDKError(fallback);
+exports.asError = asError;
+function integer(value, min, max) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < min || value > max)
+        (0, exports.fail)('INVALID_ARGUMENT');
+    return value;
+}

package/dist/cjs/internal/gateway.d.ts

@@ -0,0 +1,41 @@
+import type { Battery, CommandResult, Device, Diagnostics, DisconnectResult, Events, Gateway, GatewayInfo, GatewayOptions, IdentifySignal, Measurement, Mode, ScanResult } from '../types.js';
+import type { Link } from './link.js';
+export declare const VERSION = "0.1.0-alpha.2";
+export declare class GatewayEngine implements Gateway {
+    #private;
+    constructor(link: Link, options?: GatewayOptions, simulated?: boolean);
+    on<K extends keyof Events>(name: K, handler: (value: Events[K]) => void): () => void;
+    connect(): Promise<GatewayInfo>;
+    scan(options?: {
+        timeoutMs?: number;
+    }): Promise<ScanResult>;
+    configure(options: {
+        deviceIds: string[];
+        mode: Mode;
+    }): Promise<CommandResult>;
+    start(options: {
+        deviceIds: string[];
+    }): Promise<CommandResult>;
+    stop(options: {
+        deviceIds: string[];
+    }): Promise<CommandResult>;
+    readMeasurement(options: {
+        deviceId: string;
+        timeoutMs?: number;
+    }): Promise<Measurement>;
+    getLastMeasurement(options: {
+        deviceId: string;
+    }): Measurement | null;
+    readBattery(options: {
+        deviceId: string;
+        timeoutMs?: number;
+    }): Promise<Battery>;
+    identify(options: {
+        deviceId: string;
+        signal: IdentifySignal;
+    }): Promise<CommandResult>;
+    disconnect(): Promise<DisconnectResult>;
+    getDevices(): Device[];
+    getInfo(): GatewayInfo;
+    getDiagnostics(): Diagnostics;
+}