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

package/dist/esm/internal/link.js

@@ -0,0 +1,106 @@
+import { SDKError, asError } from './errors.js';
+const provider = () => globalThis.navigator?.serial;
+export function getSupport() {
+    const secureContext = globalThis.isSecureContext === true;
+    const webSerial = !!provider();
+    return { supported: secureContext && webSerial, secureContext, webSerial,
+        reason: !secureContext ? 'INSECURE_CONTEXT' : !webSerial ? 'UNSUPPORTED_BROWSER' : null };
+}
+export class BrowserLink {
+    #port = null;
+    #reader = null;
+    #writer = null;
+    #reading = null;
+    #closing = false;
+    #openedByUs = false;
+    async open(line, lost) {
+        const support = getSupport();
+        if (!support.supported)
+            throw new SDKError(support.reason);
+        this.#closing = false;
+        try {
+            this.#port = await provider().requestPort();
+        }
+        catch (e) {
+            throw new SDKError(e?.name === 'NotFoundError' ? 'USER_CANCELLED' : 'PORT_UNAVAILABLE');
+        }
+        try {
+            await this.#port.open({ baudRate: 115200 });
+            this.#openedByUs = true;
+            if (!this.#port.readable || !this.#port.writable)
+                throw new SDKError('PORT_UNAVAILABLE');
+            this.#reader = this.#port.readable.getReader();
+            this.#writer = this.#port.writable.getWriter();
+            this.#reading = this.#read(line, lost);
+        }
+        catch {
+            await this.close().catch(() => { });
+            throw new SDKError('PORT_UNAVAILABLE');
+        }
+    }
+    async #read(line, lost) {
+        const reader = this.#reader;
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let discarding = false;
+        try {
+            while (!this.#closing) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                const text = decoder.decode(value, { stream: true });
+                for (const ch of text) {
+                    if (ch === '\n') {
+                        if (!discarding)
+                            line(buffer.replace(/\r$/, ''));
+                        buffer = '';
+                        discarding = false;
+                    }
+                    else if (!discarding) {
+                        buffer += ch;
+                        if (buffer.length > 4096) {
+                            buffer = '';
+                            discarding = true;
+                        }
+                    }
+                }
+            }
+        }
+        catch { /* The public error deliberately omits OS and raw device details. */ }
+        finally {
+            reader.releaseLock();
+            this.#reader = null;
+            if (!this.#closing)
+                lost();
+        }
+    }
+    async write(command) {
+        if (!this.#writer || this.#closing)
+            throw new SDKError('CONNECTION_LOST');
+        try {
+            await this.#writer.write(new TextEncoder().encode(`${command}\n`));
+        }
+        catch {
+            throw new SDKError('CONNECTION_LOST');
+        }
+    }
+    async close() {
+        this.#closing = true;
+        try {
+            await this.#reader?.cancel().catch(() => { });
+            await this.#reading;
+            if (this.#writer) {
+                await this.#writer.abort().catch(() => { });
+                this.#writer.releaseLock();
+                this.#writer = null;
+            }
+            if (this.#port && this.#openedByUs)
+                await this.#port.close();
+            this.#port = null;
+            this.#openedByUs = false;
+        }
+        catch (error) {
+            throw asError(error, 'PORT_UNAVAILABLE');
+        }
+    }
+}

package/dist/esm/internal/protocol.d.ts

@@ -0,0 +1,29 @@
+export type Frame = {
+    kind: 'help';
+    text: string;
+} | {
+    kind: 'list';
+    phase: 'BEGIN' | 'END';
+} | {
+    kind: 'device';
+    number: number;
+    endpoint: string;
+    battery: number;
+    version: string;
+} | {
+    kind: 'tx';
+    target: string;
+    endpoint: string;
+    bytes: number[];
+    ok: boolean;
+} | {
+    kind: 'rx';
+    number: number;
+    endpoint: string;
+    bytes: number[];
+} | {
+    kind: 'error';
+};
+export declare function bytes(hex: string): number[] | null;
+export declare function parse(line: string): Frame | null;
+export declare const u16: (data: number[], offset: number) => number;

package/dist/esm/internal/protocol.js

@@ -0,0 +1,32 @@
+export function bytes(hex) {
+    if (!/^(?:[0-9a-f]{2}){1,48}$/i.test(hex))
+        return null;
+    return hex.match(/../g).map(v => Number.parseInt(v, 16));
+}
+const number = (s, max = 255) => s !== undefined && /^\d+$/.test(s) && Number(s) <= max ? Number(s) : null;
+const endpoint = (s) => !!s && /^[a-z0-9:.%-]{1,63}$/i.test(s);
+export function parse(line) {
+    const p = line.trim().split(',');
+    if (line.startsWith('HELP'))
+        return { kind: 'help', text: line };
+    if (p[0] === 'LIST' && (p[1] === 'BEGIN' || p[1] === 'END'))
+        return { kind: 'list', phase: p[1] };
+    if (p[0] === 'DEVICE' && p.length === 10 && number(p[1], 40) !== null && number(p[2]) !== null && endpoint(p[3]) && /^\d+\.\d+\.\d+$/.test(p[8]) && /^-?\d+$/.test(p[5])) {
+        return { kind: 'device', number: Number(p[2]), endpoint: p[3], battery: Number(p[5]), version: p[8] };
+    }
+    if (p[0] === 'TXB' && p.length === 5 && endpoint(p[2]) && p[1] && (p[4] === 'OK' || p[4] === 'FAIL')) {
+        const b = bytes(p[3]);
+        if (b)
+            return { kind: 'tx', target: p[1], endpoint: p[2], bytes: b, ok: p[4] === 'OK' };
+    }
+    if (p[0] === 'RXB' && p.length === 4 && number(p[1]) !== null && endpoint(p[2])) {
+        const b = bytes(p[3]);
+        if (b && b.length >= 2 && b[1] === Number(p[1]))
+            return { kind: 'rx', number: Number(p[1]), endpoint: p[2], bytes: b };
+    }
+    // Normalized measurement lines have no unambiguous endpoint. Use the addressed response above only.
+    if (p[0] === 'ERR' && p[1] !== 'DEVICE')
+        return { kind: 'error' };
+    return null;
+}
+export const u16 = (data, offset) => data[offset] | (data[offset + 1] << 8);

package/dist/esm/internal/simulator.d.ts

@@ -0,0 +1,15 @@
+import type { SimulationOptions } from '../types.js';
+import type { Link } from './link.js';
+export declare class SimulationLink implements Link {
+    #private;
+    constructor(options: SimulationOptions);
+    open(line: (line: string) => void, lost: () => void): Promise<void>;
+    write(command: string): Promise<void>;
+    controls(): Readonly<{
+        disconnectDevice: (displayNumber: number) => void;
+        reconnectDevice: (displayNumber: number) => void;
+        setStartFailure: (displayNumber: number, fail: boolean) => void;
+        dropConnection: () => void;
+    }>;
+    close(): Promise<void>;
+}

package/dist/esm/internal/simulator.js

@@ -0,0 +1,113 @@
+import { SDKError, integer } from './errors.js';
+const codes = { free: 16, count: 17, time: 18, start: 19, stop: 20, getData: 21, getBattery: 6, vibrate: 49, buzzer: 48, showId: 51 };
+const hex = (values) => values.map(v => v.toString(16).padStart(2, '0')).join('').toUpperCase();
+const word = (n) => [n & 255, (n >> 8) & 255];
+export class SimulationLink {
+    #line = null;
+    #lost = null;
+    #units;
+    #delay;
+    #failures;
+    #seed;
+    #timers = new Set();
+    constructor(options) {
+        if (!options || typeof options !== 'object' || Array.isArray(options))
+            throw new SDKError('INVALID_ARGUMENT');
+        const count = integer(options.deviceCount ?? 3, 1, 40);
+        this.#delay = integer(options.responseDelayMs ?? 10, 0, 30000);
+        this.#seed = integer(options.seed ?? 1, 0, 0xffffffff);
+        if (options.startFailures && !Array.isArray(options.startFailures))
+            throw new SDKError('INVALID_ARGUMENT');
+        this.#failures = new Set((options.startFailures ?? []).map(n => integer(n, 1, count)));
+        this.#units = Array.from({ length: count }, (_, i) => ({ number: i + 1, online: true, mode: 0, running: false, count: 0, ticks: 0, target: 0 }));
+    }
+    async open(line, lost) { this.#line = line; this.#lost = lost; }
+    #send(lines) {
+        const timer = setTimeout(() => { this.#timers.delete(timer); for (const line of lines)
+            this.#line?.(line); }, this.#delay);
+        this.#timers.add(timer);
+    }
+    async write(command) {
+        if (!this.#line)
+            throw new SDKError('CONNECTION_LOST');
+        if (command === 'help') {
+            this.#send(['HELP: target=all|0|id|#index|!addr', 'HELP: getData|status|fw', 'HELP: getList|clearList|scanList|refreshList']);
+            return;
+        }
+        if (command === 'getList') {
+            this.#send(['LIST,BEGIN', ...this.#units.filter(u => u.online).map(u => `DEVICE,${u.number},${u.number},unit-${u.number},-,85,0,0,1.0.0,-`), 'LIST,END']);
+            return;
+        }
+        if (command === 'discover all') {
+            this.#send(['TXB,all,group,01,OK', ...this.#units.filter(u => u.online).map(u => `RXB,${u.number},unit-${u.number},${hex([1, u.number])}`)]);
+            return;
+        }
+        const [name, target, parameter] = command.split(' ');
+        const code = codes[name];
+        const unit = this.#units.find(u => `!unit-${u.number}` === target);
+        if (code === undefined || !unit) {
+            this.#send(['ERR,BAD_TARGET']);
+            return;
+        }
+        const request = hex([code, ...(parameter === undefined ? [] : word(Number(parameter)))]);
+        const tx = `TXB,${target},unit-${unit.number},${request},OK`;
+        if (!unit.online) {
+            this.#send([tx]);
+            return;
+        }
+        if (code === 19 && this.#failures.has(unit.number)) {
+            this.#send([tx, `RXB,${unit.number},unit-${unit.number},${hex([127, unit.number, 1, code])}`]);
+            return;
+        }
+        let payload = [code, unit.number];
+        if ([16, 17, 18].includes(code)) {
+            unit.mode = code - 16;
+            unit.target = Number(parameter ?? 0);
+        }
+        if (code === 19) {
+            unit.running = true;
+            unit.count = 0;
+            unit.ticks = 0;
+        }
+        if (code === 20)
+            unit.running = false;
+        if (code === 21) {
+            if (unit.running) {
+                this.#seed = (Math.imul(this.#seed, 1664525) + 1013904223) >>> 0;
+                unit.count += 1 + this.#seed % 3;
+                unit.ticks += 5;
+                if (unit.mode === 1 && unit.count >= unit.target) {
+                    unit.count = unit.target;
+                    unit.running = false;
+                }
+                if (unit.mode === 2 && unit.ticks >= unit.target * 10) {
+                    unit.ticks = unit.target * 10;
+                    unit.running = false;
+                }
+            }
+            payload = [...payload, unit.mode, ...word(unit.count % 65536), ...word(unit.ticks % 65536), 0, 0];
+        }
+        if (code === 6)
+            payload.push(85);
+        this.#send([tx, `RXB,${unit.number},unit-${unit.number},${hex(payload)}`]);
+    }
+    #unit(displayNumber) { integer(displayNumber, 1, this.#units.length); return this.#units[displayNumber - 1]; }
+    controls() {
+        return Object.freeze({
+            disconnectDevice: (displayNumber) => { this.#unit(displayNumber).online = false; },
+            reconnectDevice: (displayNumber) => { this.#unit(displayNumber).online = true; },
+            setStartFailure: (displayNumber, fail) => {
+                this.#unit(displayNumber);
+                if (typeof fail !== 'boolean')
+                    throw new SDKError('INVALID_ARGUMENT');
+                if (fail)
+                    this.#failures.add(displayNumber);
+                else
+                    this.#failures.delete(displayNumber);
+            },
+            dropConnection: () => { const lost = this.#lost; void this.close(); lost?.(); }
+        });
+    }
+    async close() { for (const timer of this.#timers)
+        clearTimeout(timer); this.#timers.clear(); this.#line = null; this.#lost = null; }
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,182 @@
+export type ErrorCode = 'UNSUPPORTED_BROWSER' | 'INSECURE_CONTEXT' | 'USER_CANCELLED' | 'PORT_UNAVAILABLE' | 'NOT_CONNECTED' | 'UNSUPPORTED_GATEWAY' | 'UNSUPPORTED_FEATURE' | 'INVALID_ARGUMENT' | 'INVALID_STATE' | 'DEVICE_OFFLINE' | 'AMBIGUOUS_DEVICE' | 'BUSY' | 'TIMEOUT' | 'DEVICE_REJECTED' | 'CONNECTION_LOST' | 'PROTOCOL_ERROR';
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'disconnecting' | 'lost';
+export type DeviceState = 'available' | 'running' | 'unknown' | 'offline';
+export type Mode = {
+    type: 'free';
+} | {
+    type: 'count';
+    targetCount: number;
+} | {
+    type: 'time';
+    durationSeconds: number;
+};
+export type IdentifySignal = 'vibrate' | 'buzzer' | 'displayId';
+export type Battery = {
+    kind: 'percent';
+    value: number;
+} | {
+    kind: 'unknown';
+};
+export interface Capabilities {
+    modes: Array<Mode['type']>;
+    maxTargetCount: number;
+    maxDurationSeconds: number;
+    identifySignals: IdentifySignal[];
+    /** Actual hardware combinations must still pass the release acceptance checks. */
+    hardwareVerified: boolean;
+}
+export interface Device {
+    deviceId: string;
+    displayNumber: number | null;
+    state: DeviceState;
+    firmwareVersion: string | null;
+    battery: Battery;
+    capabilities: Capabilities;
+    simulated: boolean;
+}
+export interface Measurement {
+    deviceId: string;
+    displayNumber: number | null;
+    sessionId: string;
+    segmentId: string;
+    count: number;
+    elapsedMs: number;
+    pauseCount: number | null;
+    receivedAt: number;
+    source: 'live' | 'cache';
+    stale: boolean;
+    simulated: boolean;
+}
+export interface ErrorInfo {
+    code: ErrorCode;
+    message: string;
+    recoverable: boolean;
+    deviceId?: string;
+    requestId?: string;
+}
+export type ResultStatus = 'acknowledged' | 'failed' | 'unknown';
+export interface DeviceResult {
+    deviceId: string;
+    status: ResultStatus;
+    errorCode?: ErrorCode;
+    recovery?: {
+        action: 'stop';
+        status: ResultStatus;
+    };
+    finalMeasurement?: {
+        available: boolean;
+        measurement: Measurement | null;
+    };
+}
+export interface CommandResult {
+    requestId: string;
+    ok: boolean;
+    results: DeviceResult[];
+}
+export interface DisconnectResult {
+    closed: boolean;
+    stopResults: CommandResult | null;
+}
+export interface ScanResult {
+    devices: Device[];
+    status: 'complete';
+    windowMs: number;
+}
+export interface Support {
+    supported: boolean;
+    secureContext: boolean;
+    webSerial: boolean;
+    reason: ErrorCode | null;
+}
+export interface GatewayInfo {
+    connection: ConnectionState;
+    sdkVersion: string;
+    interfaceVersion: string;
+    firmwareVersion: string | null;
+    simulated: boolean;
+    features: string[];
+}
+export interface Diagnostics {
+    sdkVersion: string;
+    interfaceVersion: string;
+    connection: ConnectionState;
+    simulated: boolean;
+    deviceCount: number;
+    blockedOperationCount: number;
+    recentRequests: Array<{
+        requestId: string;
+        durationMs: number;
+        errorCode: ErrorCode | null;
+    }>;
+}
+export interface Events {
+    measurement: Measurement;
+    deviceChanged: {
+        device: Device;
+        previousState: DeviceState | null;
+    };
+    connectionChanged: {
+        state: ConnectionState;
+        previousState: ConnectionState;
+    };
+    error: ErrorInfo;
+}
+export interface GatewayOptions {
+    requestTimeoutMs?: number;
+    scanWindowMs?: number;
+    pollIntervalMs?: number;
+    staleAfterMs?: number;
+    /** Empty by default; enable only signals validated for the actual product. */
+    identifySignals?: IdentifySignal[];
+}
+export interface Gateway {
+    connect(): Promise<GatewayInfo>;
+    disconnect(): Promise<DisconnectResult>;
+    getInfo(): GatewayInfo;
+    scan(options?: {
+        timeoutMs?: number;
+    }): Promise<ScanResult>;
+    getDevices(): Device[];
+    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>;
+    on<K extends keyof Events>(event: K, handler: (value: Events[K]) => void): () => void;
+    getDiagnostics(): Diagnostics;
+}
+export interface SimulationOptions extends GatewayOptions {
+    deviceCount?: number;
+    seed?: number;
+    responseDelayMs?: number;
+    /** Display numbers that reject start, for testing partial failure recovery. */
+    startFailures?: number[];
+}
+export interface SimulatedGateway extends Gateway {
+    simulation: {
+        disconnectDevice(displayNumber: number): void;
+        reconnectDevice(displayNumber: number): void;
+        setStartFailure(displayNumber: number, fail: boolean): void;
+        dropConnection(): void;
+    };
+}

package/dist/esm/types.js

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

package/docs/API.md

@@ -0,0 +1,106 @@
+# Jumpitnow SDK · 함수 사용법
+
+교사 앱에서 사용하는 JavaScript 함수와 입력값, 결과값을 설명합니다. 현재 버전은 `0.1.0-alpha.2`입니다. 설치 방법은 [사용 안내](../README.md)를 참고하세요.
+
+## 연결하고 장비 선택하기
+
+```js
+await gateway.connect();
+const { devices } = await gateway.scan();
+```
+
+`connect()`는 연결 버튼을 눌렀을 때 호출합니다. 검색 결과에서 수업에 사용할 장비를 선택하세요. 각 장비의 `deviceId`는 이후 함수에 전달하는 키이고, `displayNumber`는 장비 표시 번호입니다. 학생 이름이나 학생 번호를 `deviceId`로 보내지 않습니다.
+
+| 함수 | 결과 |
+|---|---|
+| `getSupport()` | `supported`가 true이면 실행 환경에서 연결 기능을 사용할 수 있음 |
+| `connect()` | 연결 완료 또는 오류 |
+| `scan()` | `{ devices, status }` |
+| `getDevices()` | 현재 장비 목록 |
+| `disconnect()` | `{ closed, stopResults }` |
+
+검색한 장비가 모두 수업 대상이 되는 것은 아닙니다. 선생님이 선택한 장비만 명령에 지정하세요. `closed`는 연결 종료 여부이고 `stopResults`는 장비 정지 결과입니다.
+
+## 운동 설정하기
+
+```js
+await gateway.configure({ deviceIds, mode: { type: 'free' } });
+await gateway.configure({ deviceIds, mode: { type: 'count', targetCount: 100 } });
+await gateway.configure({ deviceIds, mode: { type: 'time', durationSeconds: 60 } });
+```
+
+- `deviceIds`: 선택한 장비의 키 목록. 빈 목록이나 같은 장비의 중복 선택은 허용하지 않습니다.
+- `targetCount`: 목표 횟수. 양의 정수입니다.
+- `durationSeconds`: 목표 시간. 초 단위의 양의 정수입니다.
+
+설정 결과가 성공인지 확인한 후 운동을 시작하세요. 가능한 목표값은 장비의 지원 범위를 따릅니다.
+
+## 시작과 정지
+
+```js
+const started = await gateway.start({ deviceIds });
+const stopped = await gateway.stop({ deviceIds });
+```
+
+정지에는 시작할 때 선택했던 장비 목록을 사용합니다. 운동 중 선택 화면을 바꾸더라도 시작한 장비 목록을 잊지 않도록 보관하세요.
+
+| 결과 필드 | 선생님 앱에서의 의미 |
+|---|---|
+| `ok` | 선택한 모든 장비의 요청이 확인되면 true |
+| `results` | 장비별 처리 결과 |
+| `status: 'acknowledged'` | 요청이 확인됨 |
+| `status: 'failed'` | 요청이 처리되지 않음 |
+| `status: 'unknown'` | 결과를 확인할 수 없음. 장비 상태 확인 필요 |
+| `recovery` | 일부 시작 실패 후 정지 시도 결과 |
+| `finalMeasurement` | 정지할 때 마지막 운동 값을 확보했는지와 해당 값 |
+
+`unknown`을 성공으로 표시하지 마세요. 결과 확인 없이 시작 버튼을 반복 실행하지 않습니다. 정지 확인이 되지 않으면 장비를 현장에서 확인합니다.
+
+## 운동 데이터 받기
+
+```js
+const unsubscribe = gateway.on('measurement', data => {
+  renderCount(data.deviceId, data.count);
+  renderTime(data.deviceId, data.elapsedMs);
+});
+
+const current = await gateway.readMeasurement({ deviceId });
+const previous = gateway.getLastMeasurement({ deviceId });
+const battery = await gateway.readBattery({ deviceId });
+
+// 더 이상 화면을 사용하지 않을 때
+unsubscribe();
+```
+
+| 데이터 | 의미 |
+|---|---|
+| `deviceId` | 어느 장비의 값인지 구분하는 키 |
+| `displayNumber` | 장비 표시 번호. 미확인 시 null |
+| `count` | 현재 운동 구간의 누적 횟수 |
+| `elapsedMs` | 경과 시간, 밀리초 단위 |
+| `pauseCount` | 멈춤 횟수. 알 수 없으면 null |
+| `receivedAt` | 앱이 값을 받은 시각 |
+| `source` | `live`는 이번에 받은 값, `cache`는 저장된 마지막 값 |
+| `stale` | 값이 오래되었거나 현재 상태 확인이 필요한 경우 true |
+| `simulated` | 연습용 가상 장비이면 true |
+
+횟수는 기존 값에 더하지 않고 새 값으로 바꿉니다. `sessionId`와 `segmentId`가 달라지면 다른 운동 또는 구간으로 구분하고 임의로 합산하지 않습니다. 마지막 값이 없으면 `getLastMeasurement()`는 null을 반환합니다. 배터리 결과의 `kind: 'percent'`는 퍼센트이며 `value`가 잔량입니다.
+
+## 상태 변경과 오류
+
+```js
+gateway.on('deviceChanged', ({ device }) => updateDevice(device));
+gateway.on('connectionChanged', ({ state }) => updateConnection(state));
+gateway.on('error', error => showError(error.message));
+```
+
+연결 해제나 확인 필요 상태를 화면에 보여주세요. 함수 호출 오류는 try/catch로 처리합니다. 입력값 오류는 값을 고치고, 연결 오류는 장비 상태를 확인합니다. 운동 종료 여부가 불확실하면 시작을 반복하지 않습니다.
+
+## 장비 없이 연습하기
+
+```js
+import { createSimulatedGateway } from '@makeitnow/jumpitnow';
+const gateway = createSimulatedGateway({ deviceCount: 3 });
+```
+
+같은 함수로 연결·선택·시작·수신·정지를 연습할 수 있습니다. 가상 데이터는 실제 수업 기록과 구분하세요.

package/docs/COMPATIBILITY.md

@@ -0,0 +1,11 @@
+# 사용 환경
+
+- 컴퓨터의 Chrome 또는 Edge에서 사용합니다.
+- 보안 연결로 제공되는 웹페이지 또는 컴퓨터의 로컬 개발 환경에서 실행합니다.
+- 호환되는 Jumpitnow 게이트웨이와 스마트 줄넘기를 준비합니다.
+- 하나의 수업 화면에서 하나의 게이트웨이를 사용합니다.
+- 연결 버튼을 눌러 사용할 게이트웨이를 선택합니다.
+
+현재 설치 파일은 개발 확인용 alpha 버전입니다. 지원하는 장비 조합은 실제 장비 확인 후 안내할 예정입니다. 가상 장비로 화면을 확인한 것은 실제 장비 검증을 대신하지 않습니다.
+
+연결이 끊기면 운동 상태를 먼저 확인하세요. 사용한 장비의 정지를 확인한 뒤 다시 연결합니다. 자동으로 운동이 다시 시작되었다고 가정하지 않습니다.

package/docs/SECURITY.md

@@ -0,0 +1,17 @@
+# 수업 운영과 기록 관리
+
+## 장비 선택
+
+검색 결과에서 이번 수업에 사용할 줄넘기를 직접 선택하세요. 표시 번호가 겹치거나 장비를 구분하기 어렵다면 먼저 장비를 확인합니다.
+
+## 운동 시작과 종료
+
+설정 결과를 확인한 뒤 시작하고, 수업이 끝나면 사용한 장비를 정지합니다. 장비가 정지했는지 확인한 후 연결을 종료하세요. 연결이 끊기거나 화면을 닫았다는 이유만으로 장비가 정지했다고 판단하지 않습니다.
+
+## 기록 관리
+
+학생 명단과 수업 기록의 저장 여부·위치는 선생님의 앱에서 정합니다. SDK는 학생 정보를 자동으로 수집하거나 수업 기록을 외부로 전송하지 않습니다. 장비 키를 학생의 영구 식별자로 사용하지 마세요.
+
+## 연습 데이터
+
+가상 장비의 값은 연습용입니다. 실제 학생의 수업 기록에 합치지 않습니다.