@whatpull/handface 0.1.0 → 0.2.1

package/README.md

@@ -2,9 +2,16 @@
 
 > MediaPipe 기반 핸드 제스처 → 마우스 이벤트 제어 웹 라이브러리
 
+[![npm version](https://img.shields.io/npm/v/@whatpull/handface?color=cb3837&logo=npm)](https://www.npmjs.com/package/@whatpull/handface)
+[![npm downloads](https://img.shields.io/npm/dm/@whatpull/handface?color=cb3837)](https://www.npmjs.com/package/@whatpull/handface)
+[![license](https://img.shields.io/github/license/whatpull/handface)](https://github.com/whatpull/handface/blob/main/LICENSE)
+[![demo](https://img.shields.io/badge/demo-live-6e40c9?logo=github)](https://whatpull.github.io/handface/)
+
 손동작으로 마우스 클릭, 커서 이동, 스크롤을 제어할 수 있는 **프레임워크 독립(framework agnostic)** npm 라이브러리입니다.  
 React, Vue, Svelte, 바닐라 JS 어디서든 동일하게 동작합니다.
 
+**[라이브 데모 →](https://whatpull.github.io/handface/)**
+
 ---
 
 ## 설치
@@ -76,8 +83,8 @@ control.stop();
 | 이벤트 | 제스처 | 페이로드 |
 |--------|--------|---------|
 | `move` | 검지 손가락 이동 | `{ x, y, screenX, screenY }` |
-| `click` | 엄지+검지 핀치 | `{ x, y, screenX, screenY }` |
-| `scroll` | 검지+중지 수직 이동 | `{ deltaY }` |
+| `click` | 엄지+중지 핀치 | `{ x, y, screenX, screenY }` |
+| `scroll` | 주먹(줌 인) / 펼친 손(줌 아웃) | `{ deltaY }` |
 | `rightclick` | (예정) | - |
 | `drag` / `dragstart` / `dragend` | (예정) | - |
 
@@ -86,8 +93,9 @@ control.stop();
 | 제스처 | 동작 |
 |--------|------|
 | ☝️ 검지만 펴기 | 커서 이동 (`move`) |
-| 🤏 엄지+검지 붙이기 | 클릭 (`click`) |
-| ✌️ 검지+중지 위아래 | 스크롤 (`scroll`) |
+| 🤏 엄지+중지 붙이기 | 클릭 (`click`) |
+| ✊ 손가락 모두 오무림 | 줌 인 (`scroll` deltaY > 0) |
+| 🖐️ 손가락 모두 펼침 | 줌 아웃 (`scroll` deltaY < 0) |
 
 ---
 
@@ -146,6 +154,19 @@ npm run typecheck  # TypeScript 타입 체크
 
 ## 개발 로그
 
+### v0.2.0 — 2026-04-11
+
+**제스처 설정 패널 + 개발자 제스처 이벤트 API**
+
+- `GestureRecognizer` 기반으로 교체 (MediaPipe 7가지 내장 제스처: 👍👎✌️🤟✊🖐️☝️)
+- `HandControl.createPanel()` — 우측 하단 플로팅 ✋ 버튼 + 설정 패널 주입
+- 일반 사용자: 패널에서 제스처 → 단축키 바인딩 (localStorage 영구 저장)
+- 개발자 API: `control.on('thumbsup' | 'victory' | 'iloveyou' | ...)` 제스처 이벤트 구독
+- `GestureMapper` 클래스 — `bind()` / `unbind()` / `trigger()` 직접 제어
+- 데모 업데이트: 커스텀 제스처로 크리스탈 색상 변화 연동
+
+---
+
 ### v0.1.0 — 2026-04-11
 
 **초기 구현**
@@ -162,4 +183,4 @@ npm run typecheck  # TypeScript 타입 체크
 
 ## 라이선스
 
-MIT
+Apache 2.0

package/dist/ControlPanel.d.ts

@@ -0,0 +1,33 @@
+import { GestureMapper } from './GestureMapper';
+import { GestureName } from './types';
+
+/** 핸드페이스 플로팅 설정 패널 */
+export declare class ControlPanel {
+    private readonly mapper;
+    private root;
+    private fab;
+    private panel;
+    private styleEl;
+    private isOpen;
+    private capturingGesture;
+    private captureHandler;
+    private detectedGesture;
+    constructor(mapper: GestureMapper);
+    /** HandControl 에서 매 프레임 호출 — 현재 감지 제스처 표시 */
+    setDetected(gesture: GestureName | null, confidence: number): void;
+    destroy(): void;
+    private toggle;
+    private open;
+    private close;
+    private startCapture;
+    private stopCapture;
+    private createFab;
+    private createPanel;
+    private renderRows;
+    private renderBuiltin;
+    private renderBindings;
+    private makeReadonlyRow;
+    private makeBindingRow;
+    private buildKeyLabel;
+    private injectStyles;
+}

package/dist/GestureDetector.d.ts

@@ -1,21 +1,43 @@
-export type GestureType = 'pinch' | 'point' | 'two-finger' | 'open' | 'none';
+import { GestureName } from './types';
+
+export type DetectedGesture = GestureName | 'click' | 'none';
 export interface DetectionResult {
-    gesture: GestureType;
-    pinchDistance: number;
+    /** 최우선 결정된 제스처 (click 핀치 > GestureRecognizer 결과) */
+    gesture: DetectedGesture;
+    /** GestureRecognizer 원본 결과 (null = None 또는 미감지) */
+    gestureName: GestureName | null;
+    gestureConfidence: number;
+    /** 클릭 감지용 엄지 ↔ 중지 거리 */
+    clickPinchDistance: number;
+    /** 검지 끝 위치 (cursorAnchor: 'index' 용) */
     indexTip: {
         x: number;
         y: number;
     };
-    middleTip: {
+    /** 손목 위치 (cursorAnchor: 'wrist' 용) */
+    wrist: {
+        x: number;
+        y: number;
+    };
+    /** 손바닥 중심 위치 (cursorAnchor: 'palm' 용) */
+    palmCenter: {
         x: number;
         y: number;
     };
 }
 export declare class GestureDetector {
     private readonly wasmPath;
-    private readonly pinchThreshold;
-    private landmarker;
-    constructor(wasmPath?: string, pinchThreshold?: number);
+    private readonly clickThreshold;
+    private readonly handednessFilter;
+    private recognizer;
+    /**
+     * @param handednessFilter
+     *   MediaPipe 카테고리 이름 기준. 정면 카메라의 raw (비반전) 피드를 사용할 때:
+     *   - 사용자의 오른손 → MediaPipe 'Left'
+     *   - 사용자의 왼손  → MediaPipe 'Right'
+     *   null = 필터 없음 (감지된 첫 번째 손 사용)
+     */
+    constructor(wasmPath?: string, clickThreshold?: number, handednessFilter?: 'Left' | 'Right' | null);
     init(): Promise<void>;
     detect(video: HTMLVideoElement, timestampMs: number): DetectionResult | null;
     private analyze;

package/dist/GestureMapper.d.ts

@@ -0,0 +1,17 @@
+import { GestureName, GestureKeyBinding } from './types';
+
+/** KeyboardEvent.key → 화면 표시용 레이블 */
+export declare function formatKeyLabel(key: string): string;
+/** 단축키 바인딩 + 키보드 이벤트 디스패치 엔진 */
+export declare class GestureMapper {
+    private bindings;
+    constructor();
+    bind(gesture: GestureName, key: string, modifiers?: GestureKeyBinding['modifiers']): void;
+    unbind(gesture: GestureName): void;
+    getBinding(gesture: GestureName): GestureKeyBinding | undefined;
+    getAll(): GestureKeyBinding[];
+    /** 제스처에 바인딩된 키보드 이벤트 디스패치 */
+    trigger(gesture: GestureName): void;
+    private save;
+    private load;
+}

package/dist/HandControl.d.ts

@@ -1,4 +1,6 @@
 import { EventEmitter } from './EventEmitter';
+import { GestureMapper } from './GestureMapper';
+import { ControlPanel } from './ControlPanel';
 import { HandControlEventMap, HandControlOptions } from './types';
 
 export declare class HandControl extends EventEmitter<HandControlEventMap> {
@@ -6,20 +8,29 @@ export declare class HandControl extends EventEmitter<HandControlEventMap> {
     private detector;
     private rafId;
     private stream;
-    private isPinching;
+    private panel;
+    private isClicking;
     private lastClickMs;
-    private prevTwoFingerY;
+    /** GestureName → 마지막 발화 타임스탬프 */
+    private lastGestureMs;
     private smoothX;
     private smoothY;
-    private readonly threshold;
     private readonly smoothing;
     private readonly flipHorizontal;
+    private readonly cursorAnchor;
     private readonly ownedVideo;
+    /** 단축키 바인딩 엔진 — 직접 접근 가능 */
+    readonly mapper: GestureMapper;
     constructor(options?: HandControlOptions);
     /** 카메라 열고 감지 시작 */
     start(): Promise<void>;
     /** 감지 중지 및 리소스 해제 */
     stop(): void;
+    /**
+     * 플로팅 설정 패널을 생성하고 document.body 에 주입합니다.
+     * 이미 생성된 경우 기존 인스턴스를 반환합니다.
+     */
+    createPanel(): ControlPanel;
     private createHiddenVideo;
     private loop;
     private tick;

package/dist/handface.js

@@ -1,112 +1,552 @@
-var f = Object.defineProperty;
-var u = (n, t, e) => t in n ? f(n, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : n[t] = e;
-var s = (n, t, e) => u(n, typeof t != "symbol" ? t + "" : t, e);
-import { FilesetResolver as w, HandLandmarker as g } from "@mediapipe/tasks-vision";
-class T {
+var E = Object.defineProperty;
+var M = (o, e, t) => e in o ? E(o, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : o[e] = t;
+var r = (o, e, t) => M(o, typeof e != "symbol" ? e + "" : e, t);
+import { FilesetResolver as C, GestureRecognizer as L } from "@mediapipe/tasks-vision";
+class _ {
   constructor() {
-    s(this, "_listeners", /* @__PURE__ */ new Map());
+    r(this, "_listeners", /* @__PURE__ */ new Map());
   }
-  on(t, e) {
-    return this._listeners.has(t) || this._listeners.set(t, /* @__PURE__ */ new Set()), this._listeners.get(t).add(e), this;
+  on(e, t) {
+    return this._listeners.has(e) || this._listeners.set(e, /* @__PURE__ */ new Set()), this._listeners.get(e).add(t), this;
   }
-  off(t, e) {
-    var i;
-    return (i = this._listeners.get(t)) == null || i.delete(e), this;
+  off(e, t) {
+    var n;
+    return (n = this._listeners.get(e)) == null || n.delete(t), this;
   }
-  emit(t, e) {
-    var i;
-    (i = this._listeners.get(t)) == null || i.forEach((o) => o(e));
+  emit(e, t) {
+    var n;
+    (n = this._listeners.get(e)) == null || n.forEach((i) => i(t));
   }
-  removeAllListeners(t) {
-    return t ? this._listeners.delete(t) : this._listeners.clear(), this;
+  removeAllListeners(e) {
+    return e ? this._listeners.delete(e) : this._listeners.clear(), this;
   }
 }
-function _(n, t) {
-  return Math.sqrt((n.x - t.x) ** 2 + (n.y - t.y) ** 2);
+function P(o, e) {
+  return Math.sqrt((o.x - e.x) ** 2 + (o.y - e.y) ** 2);
 }
-function p(n, t, e) {
-  return n + e * (t - n);
+function x(o, e, t) {
+  return o + t * (e - o);
 }
-const d = {
+const b = {
+  WRIST: 0,
   THUMB_TIP: 4,
-  INDEX_MCP: 5,
   INDEX_TIP: 8,
   MIDDLE_TIP: 12,
-  MIDDLE_MCP: 9
-}, v = "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.14/wasm", M = "https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task";
-class x {
-  constructor(t = v, e = 0.06) {
-    s(this, "landmarker", null);
-    this.wasmPath = t, this.pinchThreshold = e;
+  // palm center 계산용 (손목 + 각 손가락 MCP)
+  INDEX_MCP: 5,
+  MIDDLE_MCP: 9,
+  RING_MCP: 13,
+  PINKY_MCP: 17
+}, g = [b.WRIST, b.INDEX_MCP, b.MIDDLE_MCP, b.RING_MCP, b.PINKY_MCP], I = {
+  Pointing_Up: "pointing",
+  Closed_Fist: "fist",
+  Open_Palm: "openpalm",
+  Thumb_Up: "thumbsup",
+  Thumb_Down: "thumbsdown",
+  Victory: "victory",
+  ILoveYou: "iloveyou"
+}, T = "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.14/wasm", D = "https://storage.googleapis.com/mediapipe-models/gesture_recognizer/gesture_recognizer/float16/1/gesture_recognizer.task";
+class S {
+  /**
+   * @param handednessFilter
+   *   MediaPipe 카테고리 이름 기준. 정면 카메라의 raw (비반전) 피드를 사용할 때:
+   *   - 사용자의 오른손 → MediaPipe 'Left'
+   *   - 사용자의 왼손  → MediaPipe 'Right'
+   *   null = 필터 없음 (감지된 첫 번째 손 사용)
+   */
+  constructor(e = T, t = 0.06, n = null) {
+    r(this, "recognizer", null);
+    this.wasmPath = e, this.clickThreshold = t, this.handednessFilter = n;
   }
   async init() {
-    const t = await w.forVisionTasks(this.wasmPath);
-    this.landmarker = await g.createFromOptions(t, {
+    const e = await C.forVisionTasks(this.wasmPath);
+    this.recognizer = await L.createFromOptions(e, {
       baseOptions: {
-        modelAssetPath: M,
+        modelAssetPath: D,
         delegate: "GPU"
       },
-      numHands: 1,
+      // 핸드니스 필터링을 위해 2개 감지 후 선택
+      numHands: this.handednessFilter ? 2 : 1,
       runningMode: "VIDEO"
     });
   }
-  detect(t, e) {
-    if (!this.landmarker) return null;
-    const { landmarks: i } = this.landmarker.detectForVideo(t, e);
-    return !i || i.length === 0 ? null : this.analyze(i[0]);
-  }
-  analyze(t) {
-    const e = t[d.THUMB_TIP], i = t[d.INDEX_TIP], o = t[d.MIDDLE_TIP], c = t[d.INDEX_MCP], m = t[d.MIDDLE_MCP], l = _(e, i), a = i.y < c.y, r = o.y < m.y;
-    let h;
-    return l < this.pinchThreshold ? h = "pinch" : a && r ? h = "two-finger" : a ? h = "point" : h = "open", {
-      gesture: h,
-      pinchDistance: l,
+  detect(e, t) {
+    if (!this.recognizer) return null;
+    const n = this.recognizer.recognizeForVideo(e, t);
+    if (!n.landmarks || n.landmarks.length === 0) return null;
+    let i = 0;
+    if (this.handednessFilter) {
+      const a = n.handedness.findIndex(
+        (c) => {
+          var d;
+          return ((d = c[0]) == null ? void 0 : d.categoryName) === this.handednessFilter;
+        }
+      );
+      if (a === -1) return null;
+      i = a;
+    }
+    const l = n.gestures[i] ?? [];
+    return this.analyze(n.landmarks[i], l);
+  }
+  analyze(e, t) {
+    const n = e[b.THUMB_TIP], i = e[b.INDEX_TIP], l = e[b.MIDDLE_TIP], a = e[b.WRIST], c = {
+      x: g.reduce((u, m) => u + e[m].x, 0) / g.length,
+      y: g.reduce((u, m) => u + e[m].y, 0) / g.length
+    }, d = P(n, l), p = t[0], h = p ? I[p.categoryName] ?? null : null, f = (p == null ? void 0 : p.score) ?? 0;
+    return {
+      gesture: d < this.clickThreshold ? "click" : h ?? "none",
+      gestureName: h,
+      gestureConfidence: f,
+      clickPinchDistance: d,
       indexTip: { x: i.x, y: i.y },
-      middleTip: { x: o.x, y: o.y }
+      wrist: { x: a.x, y: a.y },
+      palmCenter: c
     };
   }
   destroy() {
-    var t;
-    (t = this.landmarker) == null || t.close(), this.landmarker = null;
+    var e;
+    (e = this.recognizer) == null || e.close(), this.recognizer = null;
+  }
+}
+const w = "handface_key_bindings";
+function A(o) {
+  return {
+    " ": "Space",
+    ArrowUp: "↑",
+    ArrowDown: "↓",
+    ArrowLeft: "←",
+    ArrowRight: "→",
+    Escape: "Esc",
+    Backspace: "⌫",
+    Delete: "Del",
+    Enter: "↵",
+    Tab: "Tab",
+    PageUp: "PgUp",
+    PageDown: "PgDn",
+    Home: "Home",
+    End: "End"
+  }[o] ?? o;
+}
+class z {
+  constructor() {
+    r(this, "bindings", /* @__PURE__ */ new Map());
+    this.load();
+  }
+  bind(e, t, n) {
+    this.bindings.set(e, { gesture: e, key: t, modifiers: n }), this.save();
+  }
+  unbind(e) {
+    this.bindings.delete(e), this.save();
+  }
+  getBinding(e) {
+    return this.bindings.get(e);
+  }
+  getAll() {
+    return [...this.bindings.values()];
+  }
+  /** 제스처에 바인딩된 키보드 이벤트 디스패치 */
+  trigger(e) {
+    var i, l, a, c;
+    const t = this.bindings.get(e);
+    if (!t) return;
+    const n = {
+      key: t.key,
+      bubbles: !0,
+      cancelable: !0,
+      ctrlKey: ((i = t.modifiers) == null ? void 0 : i.ctrl) ?? !1,
+      altKey: ((l = t.modifiers) == null ? void 0 : l.alt) ?? !1,
+      shiftKey: ((a = t.modifiers) == null ? void 0 : a.shift) ?? !1,
+      metaKey: ((c = t.modifiers) == null ? void 0 : c.meta) ?? !1
+    };
+    document.dispatchEvent(new KeyboardEvent("keydown", n)), document.dispatchEvent(new KeyboardEvent("keyup", n));
+  }
+  save() {
+    try {
+      localStorage.setItem(w, JSON.stringify([...this.bindings.entries()]));
+    } catch {
+    }
+  }
+  load() {
+    try {
+      const e = localStorage.getItem(w);
+      e && (this.bindings = new Map(JSON.parse(e)));
+    } catch {
+    }
+  }
+}
+const v = {
+  pointing: { icon: "☝️", label: "Pointing Up", labelKo: "검지 가리키기", builtin: !0, builtinAction: "커서 이동" },
+  fist: { icon: "✊", label: "Closed Fist", labelKo: "주먹", builtin: !0, builtinAction: "스크롤 다운" },
+  openpalm: { icon: "🖐️", label: "Open Palm", labelKo: "펼친 손", builtin: !0, builtinAction: "스크롤 업" },
+  thumbsup: { icon: "👍", label: "Thumbs Up", labelKo: "엄지 위", builtin: !1 },
+  thumbsdown: { icon: "👎", label: "Thumbs Down", labelKo: "엄지 아래", builtin: !1 },
+  victory: { icon: "✌️", label: "Victory", labelKo: "브이", builtin: !1 },
+  iloveyou: { icon: "🤟", label: "I Love You", labelKo: "아이 러브 유", builtin: !1 }
+}, s = "hf-", R = ["thumbsup", "thumbsdown", "victory", "iloveyou"], H = ["pointing", "fist", "openpalm"];
+class K {
+  constructor(e) {
+    r(this, "root");
+    r(this, "fab");
+    r(this, "panel");
+    r(this, "styleEl");
+    r(this, "isOpen", !1);
+    r(this, "capturingGesture", null);
+    r(this, "captureHandler", null);
+    r(this, "detectedGesture", null);
+    this.mapper = e, this.styleEl = this.injectStyles(), this.fab = this.createFab(), this.panel = this.createPanel(), this.root = document.createElement("div"), this.root.setAttribute("data-handface", ""), this.root.appendChild(this.fab), this.root.appendChild(this.panel), document.body.appendChild(this.root), this.fab.addEventListener("click", () => this.toggle());
+  }
+  /** HandControl 에서 매 프레임 호출 — 현재 감지 제스처 표시 */
+  setDetected(e, t) {
+    this.isOpen && this.detectedGesture !== e && (this.detectedGesture = e, this.panel.querySelectorAll(`.${s}row[data-gesture]`).forEach((n) => {
+      const i = n.dataset.gesture;
+      n.classList.toggle(`${s}active`, i === e && t > 0.6);
+    }));
+  }
+  destroy() {
+    this.stopCapture(), this.styleEl.remove(), this.root.remove();
+  }
+  // ─────────────────────────────────────────
+  // Panel open / close
+  // ─────────────────────────────────────────
+  toggle() {
+    this.isOpen ? this.close() : this.open();
+  }
+  open() {
+    this.isOpen = !0, this.renderRows(), this.panel.classList.add(`${s}open`), this.fab.classList.add(`${s}fab-open`);
+  }
+  close() {
+    this.isOpen = !1, this.stopCapture(), this.panel.classList.remove(`${s}open`), this.fab.classList.remove(`${s}fab-open`);
+  }
+  // ─────────────────────────────────────────
+  // Key capture
+  // ─────────────────────────────────────────
+  startCapture(e) {
+    this.stopCapture(), this.capturingGesture = e, this.captureHandler = (t) => {
+      if (t.preventDefault(), t.stopImmediatePropagation(), ["Shift", "Control", "Alt", "Meta"].includes(t.key)) {
+        document.addEventListener("keydown", this.captureHandler, { once: !0, capture: !0 });
+        return;
+      }
+      this.mapper.bind(e, t.key, {
+        ctrl: t.ctrlKey || void 0,
+        alt: t.altKey || void 0,
+        shift: t.shiftKey || void 0,
+        meta: t.metaKey || void 0
+      }), this.capturingGesture = null, this.captureHandler = null, this.renderRows();
+    }, document.addEventListener("keydown", this.captureHandler, { once: !0, capture: !0 }), this.renderRows();
+  }
+  stopCapture() {
+    this.captureHandler && (document.removeEventListener("keydown", this.captureHandler, { capture: !0 }), this.captureHandler = null, this.capturingGesture = null);
+  }
+  // ─────────────────────────────────────────
+  // DOM construction
+  // ─────────────────────────────────────────
+  createFab() {
+    const e = document.createElement("button");
+    return e.className = `${s}fab`, e.title = "handface 제스처 설정", e.innerHTML = "✋", e;
+  }
+  createPanel() {
+    const e = document.createElement("div");
+    return e.className = `${s}panel`, e.innerHTML = `
+      <div class="${s}header">
+        <span class="${s}title">✋ handface</span>
+        <button class="${s}close-btn" title="닫기">✕</button>
+      </div>
+      <div class="${s}body">
+        <div class="${s}section-label">기본 동작</div>
+        <div class="${s}builtin-rows"></div>
+        <div class="${s}section-label" style="margin-top:10px">단축키 바인딩</div>
+        <div class="${s}binding-rows"></div>
+      </div>
+    `, e.querySelector(`.${s}close-btn`).addEventListener("click", () => this.close()), e;
+  }
+  renderRows() {
+    this.renderBuiltin(), this.renderBindings();
+  }
+  renderBuiltin() {
+    const e = this.panel.querySelector(`.${s}builtin-rows`);
+    e.innerHTML = "", e.appendChild(this.makeReadonlyRow("🤏", "엄지+중지 핀치", "클릭", null));
+    for (const t of H) {
+      const n = v[t];
+      e.appendChild(
+        this.makeReadonlyRow(n.icon, n.labelKo, n.builtinAction, t)
+      );
+    }
+  }
+  renderBindings() {
+    const e = this.panel.querySelector(`.${s}binding-rows`);
+    e.innerHTML = "";
+    for (const t of R) {
+      const n = v[t], i = this.mapper.getBinding(t), l = this.capturingGesture === t;
+      e.appendChild(
+        this.makeBindingRow(t, n.icon, n.labelKo, (i == null ? void 0 : i.key) ?? null, l)
+      );
+    }
+  }
+  makeReadonlyRow(e, t, n, i) {
+    const l = document.createElement("div");
+    return l.className = `${s}row`, i && (l.dataset.gesture = i), l.innerHTML = `
+      <span class="${s}icon">${e}</span>
+      <span class="${s}name">${t}</span>
+      <span class="${s}badge">${n}</span>
+    `, l;
+  }
+  makeBindingRow(e, t, n, i, l) {
+    var d;
+    const a = document.createElement("div");
+    a.className = `${s}row`, a.dataset.gesture = e;
+    const c = i ? this.buildKeyLabel(this.mapper.getBinding(e)) : null;
+    return l ? (a.innerHTML = `
+        <span class="${s}icon">${t}</span>
+        <span class="${s}name">${n}</span>
+        <span class="${s}capture-hint">단축키 입력...</span>
+        <button class="${s}cancel-btn">취소</button>
+      `, a.querySelector(`.${s}cancel-btn`).addEventListener("click", () => {
+      this.stopCapture(), this.renderRows();
+    })) : (a.innerHTML = `
+        <span class="${s}icon">${t}</span>
+        <span class="${s}name">${n}</span>
+        ${c ? `<span class="${s}key-tag">${c}</span>
+             <button class="${s}bind-btn ${s}clear-btn" data-gesture="${e}" title="제거">✕</button>` : `<span class="${s}no-bind">—</span>`}
+        <button class="${s}bind-btn ${s}edit-btn" data-gesture="${e}" title="단축키 설정">✎</button>
+      `, a.querySelector(`.${s}edit-btn`).addEventListener("click", () => this.startCapture(e)), (d = a.querySelector(`.${s}clear-btn`)) == null || d.addEventListener("click", () => {
+      this.mapper.unbind(e), this.renderRows();
+    })), a;
+  }
+  buildKeyLabel(e) {
+    var n, i, l, a;
+    const t = [];
+    return (n = e.modifiers) != null && n.ctrl && t.push("Ctrl"), (i = e.modifiers) != null && i.alt && t.push("Alt"), (l = e.modifiers) != null && l.shift && t.push("Shift"), (a = e.modifiers) != null && a.meta && t.push("⌘"), t.push(A(e.key)), t.join("+");
+  }
+  // ─────────────────────────────────────────
+  // Styles
+  // ─────────────────────────────────────────
+  injectStyles() {
+    const e = document.createElement("style");
+    return e.dataset.handface = "styles", e.textContent = `
+      .${s}fab {
+        position: fixed;
+        right: 20px;
+        bottom: 20px;
+        width: 46px;
+        height: 46px;
+        border-radius: 50%;
+        background: linear-gradient(135deg, #7c6af7, #5b4dd4);
+        color: #fff;
+        border: none;
+        cursor: pointer;
+        font-size: 1.25rem;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        box-shadow: 0 4px 20px rgba(124,106,247,0.45);
+        z-index: 999998;
+        transition: transform 0.18s, box-shadow 0.18s;
+        user-select: none;
+      }
+      .${s}fab:hover { transform: scale(1.1); box-shadow: 0 6px 28px rgba(124,106,247,0.65); }
+      .${s}fab-open  { transform: rotate(20deg) scale(1.05); }
+
+      .${s}panel {
+        position: fixed;
+        right: 20px;
+        bottom: 76px;
+        width: 272px;
+        background: rgba(10, 10, 20, 0.97);
+        border: 1px solid rgba(124,106,247,0.28);
+        border-radius: 16px;
+        z-index: 999999;
+        -webkit-backdrop-filter: blur(24px);
+        backdrop-filter: blur(24px);
+        box-shadow: 0 12px 48px rgba(0,0,0,0.55);
+        color: #ddddf5;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+        font-size: 13px;
+        opacity: 0;
+        transform: translateY(10px) scale(0.97);
+        pointer-events: none;
+        transition: opacity 0.2s ease, transform 0.2s ease;
+      }
+      .${s}open {
+        opacity: 1;
+        transform: translateY(0) scale(1);
+        pointer-events: all;
+      }
+
+      .${s}header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        padding: 13px 16px 11px;
+        border-bottom: 1px solid rgba(255,255,255,0.07);
+      }
+      .${s}title {
+        font-weight: 700;
+        font-size: 0.85rem;
+        letter-spacing: -0.01em;
+      }
+      .${s}close-btn {
+        background: none;
+        border: none;
+        color: rgba(221,221,245,0.45);
+        cursor: pointer;
+        font-size: 0.8rem;
+        padding: 2px 4px;
+        border-radius: 4px;
+        transition: color 0.12s;
+      }
+      .${s}close-btn:hover { color: #ddddf5; }
+
+      .${s}body {
+        padding: 12px 14px 14px;
+      }
+      .${s}section-label {
+        font-size: 0.6rem;
+        text-transform: uppercase;
+        letter-spacing: 0.11em;
+        opacity: 0.35;
+        margin-bottom: 7px;
+      }
+
+      .${s}row {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        padding: 5px 6px;
+        border-radius: 8px;
+        margin-bottom: 3px;
+        transition: background 0.15s;
+      }
+      .${s}row.${s}active {
+        background: rgba(124,106,247,0.18);
+      }
+
+      .${s}icon { font-size: 1rem; width: 22px; text-align: center; flex-shrink: 0; }
+      .${s}name { flex: 1; opacity: 0.8; font-size: 0.76rem; }
+
+      .${s}badge {
+        font-size: 0.65rem;
+        background: rgba(124,106,247,0.25);
+        color: #9d8dff;
+        padding: 2px 7px;
+        border-radius: 99px;
+        white-space: nowrap;
+      }
+
+      .${s}key-tag {
+        font-size: 0.65rem;
+        font-family: 'SF Mono', 'Fira Code', monospace;
+        background: rgba(78,205,196,0.15);
+        color: #4ecdc4;
+        padding: 2px 7px;
+        border-radius: 6px;
+        white-space: nowrap;
+        max-width: 80px;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
+
+      .${s}no-bind {
+        font-size: 0.72rem;
+        opacity: 0.3;
+      }
+
+      .${s}bind-btn {
+        background: none;
+        border: none;
+        cursor: pointer;
+        border-radius: 5px;
+        padding: 2px 5px;
+        font-size: 0.75rem;
+        transition: background 0.12s, color 0.12s;
+        flex-shrink: 0;
+      }
+      .${s}edit-btn  { color: rgba(221,221,245,0.45); }
+      .${s}edit-btn:hover  { background: rgba(124,106,247,0.2); color: #9d8dff; }
+      .${s}clear-btn { color: rgba(221,221,245,0.3); }
+      .${s}clear-btn:hover { background: rgba(255,80,80,0.15); color: #ff6b6b; }
+
+      .${s}capture-hint {
+        flex: 1;
+        font-size: 0.7rem;
+        color: #ffd166;
+        animation: ${s}blink 1s step-end infinite;
+      }
+      .${s}cancel-btn {
+        background: none;
+        border: 1px solid rgba(255,80,80,0.3);
+        color: rgba(255,100,100,0.7);
+        border-radius: 5px;
+        padding: 2px 7px;
+        font-size: 0.65rem;
+        cursor: pointer;
+        flex-shrink: 0;
+      }
+      .${s}cancel-btn:hover { background: rgba(255,80,80,0.1); }
+
+      @keyframes ${s}blink {
+        0%, 100% { opacity: 1; }
+        50%       { opacity: 0.3; }
+      }
+    `, document.head.appendChild(e), e;
   }
 }
-const I = 0.09, y = 600;
-class k extends T {
-  constructor(e = {}) {
+const N = 0.09, O = 600, $ = 12, G = 900;
+function F(o) {
+  return o === "right" ? "Left" : o === "left" ? "Right" : null;
+}
+class B extends _ {
+  constructor(t = {}) {
     super();
-    s(this, "video");
-    s(this, "detector");
-    s(this, "rafId", null);
-    s(this, "stream", null);
-    // gesture state
-    s(this, "isPinching", !1);
-    s(this, "lastClickMs", 0);
-    s(this, "prevTwoFingerY", 0);
-    // smoothed cursor position
-    s(this, "smoothX", 0.5);
-    s(this, "smoothY", 0.5);
-    s(this, "threshold");
-    s(this, "smoothing");
-    s(this, "flipHorizontal");
-    s(this, "ownedVideo");
-    this.threshold = e.threshold ?? 0.05, this.smoothing = e.smoothing ?? 0.6, this.flipHorizontal = e.flipHorizontal ?? !0, e.video ? (this.video = e.video, this.ownedVideo = !1) : (this.video = this.createHiddenVideo(), this.ownedVideo = !0), this.detector = new x(e.wasmPath, this.threshold);
+    r(this, "video");
+    r(this, "detector");
+    r(this, "rafId", null);
+    r(this, "stream", null);
+    r(this, "panel", null);
+    // 제스처 상태
+    r(this, "isClicking", !1);
+    r(this, "lastClickMs", 0);
+    /** GestureName → 마지막 발화 타임스탬프 */
+    r(this, "lastGestureMs", /* @__PURE__ */ new Map());
+    // 스무딩된 커서 위치
+    r(this, "smoothX", 0.5);
+    r(this, "smoothY", 0.5);
+    r(this, "smoothing");
+    r(this, "flipHorizontal");
+    r(this, "cursorAnchor");
+    r(this, "ownedVideo");
+    /** 단축키 바인딩 엔진 — 직접 접근 가능 */
+    r(this, "mapper", new z());
+    this.smoothing = t.smoothing ?? 0.6, this.flipHorizontal = t.flipHorizontal ?? !0, this.cursorAnchor = t.cursorAnchor ?? "wrist";
+    const n = t.threshold ?? 0.05;
+    t.video ? (this.video = t.video, this.ownedVideo = !1) : (this.video = this.createHiddenVideo(), this.ownedVideo = !0), this.detector = new S(
+      t.wasmPath,
+      n,
+      F(t.handedness ?? "right")
+    );
   }
   /** 카메라 열고 감지 시작 */
   async start() {
-    await this.detector.init(), this.stream = await navigator.mediaDevices.getUserMedia({ video: !0 }), this.video.srcObject = this.stream, await new Promise((e) => {
+    await this.detector.init(), this.stream = await navigator.mediaDevices.getUserMedia({ video: !0 }), this.video.srcObject = this.stream, await new Promise((t) => {
       this.video.onloadedmetadata = () => {
-        this.video.play(), e();
+        this.video.play(), t();
       };
     }), this.loop();
   }
   /** 감지 중지 및 리소스 해제 */
   stop() {
-    var e;
-    this.rafId !== null && (cancelAnimationFrame(this.rafId), this.rafId = null), (e = this.stream) == null || e.getTracks().forEach((i) => i.stop()), this.stream = null, this.detector.destroy(), this.ownedVideo && this.video.remove(), this.removeAllListeners();
+    var t, n;
+    this.rafId !== null && (cancelAnimationFrame(this.rafId), this.rafId = null), (t = this.stream) == null || t.getTracks().forEach((i) => i.stop()), this.stream = null, this.detector.destroy(), (n = this.panel) == null || n.destroy(), this.panel = null, this.ownedVideo && this.video.remove(), this.removeAllListeners();
+  }
+  /**
+   * 플로팅 설정 패널을 생성하고 document.body 에 주입합니다.
+   * 이미 생성된 경우 기존 인스턴스를 반환합니다.
+   */
+  createPanel() {
+    return this.panel || (this.panel = new K(this.mapper)), this.panel;
   }
   createHiddenVideo() {
-    const e = document.createElement("video");
-    return e.style.cssText = "position:fixed;top:0;left:0;width:1px;height:1px;opacity:0;pointer-events:none;", document.body.appendChild(e), e;
+    const t = document.createElement("video");
+    return t.style.cssText = "position:fixed;top:0;left:0;width:1px;height:1px;opacity:0;pointer-events:none;", document.body.appendChild(t), t;
   }
   loop() {
     this.rafId = requestAnimationFrame(() => {
@@ -114,34 +554,46 @@ class k extends T {
     });
   }
   tick() {
-    const e = performance.now(), i = this.detector.detect(this.video, e);
-    if (!i) return;
-    const o = this.flipHorizontal ? 1 - i.indexTip.x : i.indexTip.x, c = i.indexTip.y;
-    this.smoothX = p(this.smoothX, o, 1 - this.smoothing), this.smoothY = p(this.smoothY, c, 1 - this.smoothing);
-    const m = Math.round(this.smoothX * window.innerWidth), l = Math.round(this.smoothY * window.innerHeight), a = {
+    var f, y;
+    const t = performance.now(), n = this.detector.detect(this.video, t);
+    if (!n) return;
+    const i = this.cursorAnchor === "index" ? n.indexTip : this.cursorAnchor === "palm" ? n.palmCenter : n.wrist, l = this.flipHorizontal ? 1 - i.x : i.x, a = i.y;
+    this.smoothX = x(this.smoothX, l, 1 - this.smoothing), this.smoothY = x(this.smoothY, a, 1 - this.smoothing);
+    const c = Math.round(this.smoothX * window.innerWidth), d = Math.round(this.smoothY * window.innerHeight), p = {
       x: this.smoothX,
       y: this.smoothY,
-      screenX: m,
-      screenY: l
+      screenX: c,
+      screenY: d
     };
-    if (this.emit("move", a), i.gesture === "pinch") {
-      if (!this.isPinching) {
-        this.isPinching = !0;
-        const r = Date.now();
-        r - this.lastClickMs > y && (this.lastClickMs = r, this.emit("click", a));
-      }
-    } else i.pinchDistance > I && (this.isPinching = !1);
-    if (i.gesture === "two-finger") {
-      const r = i.indexTip.y;
-      if (this.prevTwoFingerY !== 0) {
-        const h = (r - this.prevTwoFingerY) * 1e3;
-        this.emit("scroll", { deltaY: h });
-      }
-      this.prevTwoFingerY = r;
+    if (this.emit("move", p), n.gesture === "click") {
+      if (!this.isClicking) {
+        this.isClicking = !0;
+        const u = Date.now();
+        u - this.lastClickMs > O && (this.lastClickMs = u, this.emit("click", p));
+      }
+    } else n.clickPinchDistance > N && (this.isClicking = !1);
+    this.isClicking || (n.gestureName === "fist" ? this.emit("scroll", { deltaY: $ }) : n.gestureName === "openpalm" && this.emit("scroll", { deltaY: -$ }));
+    const h = n.gestureName;
+    if (h) {
+      (f = this.panel) == null || f.setDetected(h, n.gestureConfidence);
+      const u = Date.now(), m = this.lastGestureMs.get(h) ?? 0;
+      if (u - m > G) {
+        this.lastGestureMs.set(h, u);
+        const k = {
+          gesture: h,
+          ...p,
+          confidence: n.gestureConfidence
+        };
+        this.emit(h, k), this.mapper.trigger(h);
+      }
     } else
-      this.prevTwoFingerY = 0;
+      (y = this.panel) == null || y.setDetected(null, 0);
   }
 }
 export {
-  k as HandControl
+  K as ControlPanel,
+  v as GESTURE_META,
+  z as GestureMapper,
+  B as HandControl,
+  A as formatKeyLabel
 };

package/dist/handface.umd.cjs

@@ -1 +1,192 @@
-(function(o,n){typeof exports=="object"&&typeof module<"u"?n(exports,require("@mediapipe/tasks-vision")):typeof define=="function"&&define.amd?define(["exports","@mediapipe/tasks-vision"],n):(o=typeof globalThis<"u"?globalThis:o||self,n(o.Handface={},o.MediaPipeTasks))})(this,function(o,n){"use strict";var I=Object.defineProperty;var P=(o,n,l)=>n in o?I(o,n,{enumerable:!0,configurable:!0,writable:!0,value:l}):o[n]=l;var s=(o,n,l)=>P(o,typeof n!="symbol"?n+"":n,l);class l{constructor(){s(this,"_listeners",new Map)}on(e,t){return this._listeners.has(e)||this._listeners.set(e,new Set),this._listeners.get(e).add(t),this}off(e,t){var i;return(i=this._listeners.get(e))==null||i.delete(t),this}emit(e,t){var i;(i=this._listeners.get(e))==null||i.forEach(h=>h(t))}removeAllListeners(e){return e?this._listeners.delete(e):this._listeners.clear(),this}}function g(r,e){return Math.sqrt((r.x-e.x)**2+(r.y-e.y)**2)}function w(r,e,t){return r+t*(e-r)}const c={THUMB_TIP:4,INDEX_MCP:5,INDEX_TIP:8,MIDDLE_TIP:12,MIDDLE_MCP:9},T="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.14/wasm",v="https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task";class M{constructor(e=T,t=.06){s(this,"landmarker",null);this.wasmPath=e,this.pinchThreshold=t}async init(){const e=await n.FilesetResolver.forVisionTasks(this.wasmPath);this.landmarker=await n.HandLandmarker.createFromOptions(e,{baseOptions:{modelAssetPath:v,delegate:"GPU"},numHands:1,runningMode:"VIDEO"})}detect(e,t){if(!this.landmarker)return null;const{landmarks:i}=this.landmarker.detectForVideo(e,t);return!i||i.length===0?null:this.analyze(i[0])}analyze(e){const t=e[c.THUMB_TIP],i=e[c.INDEX_TIP],h=e[c.MIDDLE_TIP],f=e[c.INDEX_MCP],u=e[c.MIDDLE_MCP],p=g(t,i),m=i.y<f.y,d=h.y<u.y;let a;return p<this.pinchThreshold?a="pinch":m&&d?a="two-finger":m?a="point":a="open",{gesture:a,pinchDistance:p,indexTip:{x:i.x,y:i.y},middleTip:{x:h.x,y:h.y}}}destroy(){var e;(e=this.landmarker)==null||e.close(),this.landmarker=null}}const _=.09,y=600;class x extends l{constructor(t={}){super();s(this,"video");s(this,"detector");s(this,"rafId",null);s(this,"stream",null);s(this,"isPinching",!1);s(this,"lastClickMs",0);s(this,"prevTwoFingerY",0);s(this,"smoothX",.5);s(this,"smoothY",.5);s(this,"threshold");s(this,"smoothing");s(this,"flipHorizontal");s(this,"ownedVideo");this.threshold=t.threshold??.05,this.smoothing=t.smoothing??.6,this.flipHorizontal=t.flipHorizontal??!0,t.video?(this.video=t.video,this.ownedVideo=!1):(this.video=this.createHiddenVideo(),this.ownedVideo=!0),this.detector=new M(t.wasmPath,this.threshold)}async start(){await this.detector.init(),this.stream=await navigator.mediaDevices.getUserMedia({video:!0}),this.video.srcObject=this.stream,await new Promise(t=>{this.video.onloadedmetadata=()=>{this.video.play(),t()}}),this.loop()}stop(){var t;this.rafId!==null&&(cancelAnimationFrame(this.rafId),this.rafId=null),(t=this.stream)==null||t.getTracks().forEach(i=>i.stop()),this.stream=null,this.detector.destroy(),this.ownedVideo&&this.video.remove(),this.removeAllListeners()}createHiddenVideo(){const t=document.createElement("video");return t.style.cssText="position:fixed;top:0;left:0;width:1px;height:1px;opacity:0;pointer-events:none;",document.body.appendChild(t),t}loop(){this.rafId=requestAnimationFrame(()=>{this.tick(),this.rafId!==null&&this.loop()})}tick(){const t=performance.now(),i=this.detector.detect(this.video,t);if(!i)return;const h=this.flipHorizontal?1-i.indexTip.x:i.indexTip.x,f=i.indexTip.y;this.smoothX=w(this.smoothX,h,1-this.smoothing),this.smoothY=w(this.smoothY,f,1-this.smoothing);const u=Math.round(this.smoothX*window.innerWidth),p=Math.round(this.smoothY*window.innerHeight),m={x:this.smoothX,y:this.smoothY,screenX:u,screenY:p};if(this.emit("move",m),i.gesture==="pinch"){if(!this.isPinching){this.isPinching=!0;const d=Date.now();d-this.lastClickMs>y&&(this.lastClickMs=d,this.emit("click",m))}}else i.pinchDistance>_&&(this.isPinching=!1);if(i.gesture==="two-finger"){const d=i.indexTip.y;if(this.prevTwoFingerY!==0){const a=(d-this.prevTwoFingerY)*1e3;this.emit("scroll",{deltaY:a})}this.prevTwoFingerY=d}else this.prevTwoFingerY=0}}o.HandControl=x,Object.defineProperty(o,Symbol.toStringTag,{value:"Module"})});
+(function(l,d){typeof exports=="object"&&typeof module<"u"?d(exports,require("@mediapipe/tasks-vision")):typeof define=="function"&&define.amd?define(["exports","@mediapipe/tasks-vision"],d):(l=typeof globalThis<"u"?globalThis:l||self,d(l.Handface={},l.MediaPipeTasks))})(this,function(l,d){"use strict";var U=Object.defineProperty;var F=(l,d,g)=>d in l?U(l,d,{enumerable:!0,configurable:!0,writable:!0,value:g}):l[d]=g;var o=(l,d,g)=>F(l,typeof d!="symbol"?d+"":d,g);class g{constructor(){o(this,"_listeners",new Map)}on(e,t){return this._listeners.has(e)||this._listeners.set(e,new Set),this._listeners.get(e).add(t),this}off(e,t){var n;return(n=this._listeners.get(e))==null||n.delete(t),this}emit(e,t){var n;(n=this._listeners.get(e))==null||n.forEach(i=>i(t))}removeAllListeners(e){return e?this._listeners.delete(e):this._listeners.clear(),this}}function P(c,e){return Math.sqrt((c.x-e.x)**2+(c.y-e.y)**2)}function k(c,e,t){return c+t*(e-c)}const f={WRIST:0,THUMB_TIP:4,INDEX_TIP:8,MIDDLE_TIP:12,INDEX_MCP:5,MIDDLE_MCP:9,RING_MCP:13,PINKY_MCP:17},w=[f.WRIST,f.INDEX_MCP,f.MIDDLE_MCP,f.RING_MCP,f.PINKY_MCP],_={Pointing_Up:"pointing",Closed_Fist:"fist",Open_Palm:"openpalm",Thumb_Up:"thumbsup",Thumb_Down:"thumbsdown",Victory:"victory",ILoveYou:"iloveyou"},I="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.14/wasm",S="https://storage.googleapis.com/mediapipe-models/gesture_recognizer/gesture_recognizer/float16/1/gesture_recognizer.task";class A{constructor(e=I,t=.06,n=null){o(this,"recognizer",null);this.wasmPath=e,this.clickThreshold=t,this.handednessFilter=n}async init(){const e=await d.FilesetResolver.forVisionTasks(this.wasmPath);this.recognizer=await d.GestureRecognizer.createFromOptions(e,{baseOptions:{modelAssetPath:S,delegate:"GPU"},numHands:this.handednessFilter?2:1,runningMode:"VIDEO"})}detect(e,t){if(!this.recognizer)return null;const n=this.recognizer.recognizeForVideo(e,t);if(!n.landmarks||n.landmarks.length===0)return null;let i=0;if(this.handednessFilter){const r=n.handedness.findIndex(h=>{var p;return((p=h[0])==null?void 0:p.categoryName)===this.handednessFilter});if(r===-1)return null;i=r}const a=n.gestures[i]??[];return this.analyze(n.landmarks[i],a)}analyze(e,t){const n=e[f.THUMB_TIP],i=e[f.INDEX_TIP],a=e[f.MIDDLE_TIP],r=e[f.WRIST],h={x:w.reduce((b,y)=>b+e[y].x,0)/w.length,y:w.reduce((b,y)=>b+e[y].y,0)/w.length},p=P(n,a),m=t[0],u=m?_[m.categoryName]??null:null,x=(m==null?void 0:m.score)??0;return{gesture:p<this.clickThreshold?"click":u??"none",gestureName:u,gestureConfidence:x,clickPinchDistance:p,indexTip:{x:i.x,y:i.y},wrist:{x:r.x,y:r.y},palmCenter:h}}destroy(){var e;(e=this.recognizer)==null||e.close(),this.recognizer=null}}const E="handface_key_bindings";function M(c){return{" ":"Space",ArrowUp:"↑",ArrowDown:"↓",ArrowLeft:"←",ArrowRight:"→",Escape:"Esc",Backspace:"⌫",Delete:"Del",Enter:"↵",Tab:"Tab",PageUp:"PgUp",PageDown:"PgDn",Home:"Home",End:"End"}[c]??c}class C{constructor(){o(this,"bindings",new Map);this.load()}bind(e,t,n){this.bindings.set(e,{gesture:e,key:t,modifiers:n}),this.save()}unbind(e){this.bindings.delete(e),this.save()}getBinding(e){return this.bindings.get(e)}getAll(){return[...this.bindings.values()]}trigger(e){var i,a,r,h;const t=this.bindings.get(e);if(!t)return;const n={key:t.key,bubbles:!0,cancelable:!0,ctrlKey:((i=t.modifiers)==null?void 0:i.ctrl)??!1,altKey:((a=t.modifiers)==null?void 0:a.alt)??!1,shiftKey:((r=t.modifiers)==null?void 0:r.shift)??!1,metaKey:((h=t.modifiers)==null?void 0:h.meta)??!1};document.dispatchEvent(new KeyboardEvent("keydown",n)),document.dispatchEvent(new KeyboardEvent("keyup",n))}save(){try{localStorage.setItem(E,JSON.stringify([...this.bindings.entries()]))}catch{}}load(){try{const e=localStorage.getItem(E);e&&(this.bindings=new Map(JSON.parse(e)))}catch{}}}const v={pointing:{icon:"☝️",label:"Pointing Up",labelKo:"검지 가리키기",builtin:!0,builtinAction:"커서 이동"},fist:{icon:"✊",label:"Closed Fist",labelKo:"주먹",builtin:!0,builtinAction:"스크롤 다운"},openpalm:{icon:"🖐️",label:"Open Palm",labelKo:"펼친 손",builtin:!0,builtinAction:"스크롤 업"},thumbsup:{icon:"👍",label:"Thumbs Up",labelKo:"엄지 위",builtin:!1},thumbsdown:{icon:"👎",label:"Thumbs Down",labelKo:"엄지 아래",builtin:!1},victory:{icon:"✌️",label:"Victory",labelKo:"브이",builtin:!1},iloveyou:{icon:"🤟",label:"I Love You",labelKo:"아이 러브 유",builtin:!1}},s="hf-",D=["thumbsup","thumbsdown","victory","iloveyou"],H=["pointing","fist","openpalm"];class L{constructor(e){o(this,"root");o(this,"fab");o(this,"panel");o(this,"styleEl");o(this,"isOpen",!1);o(this,"capturingGesture",null);o(this,"captureHandler",null);o(this,"detectedGesture",null);this.mapper=e,this.styleEl=this.injectStyles(),this.fab=this.createFab(),this.panel=this.createPanel(),this.root=document.createElement("div"),this.root.setAttribute("data-handface",""),this.root.appendChild(this.fab),this.root.appendChild(this.panel),document.body.appendChild(this.root),this.fab.addEventListener("click",()=>this.toggle())}setDetected(e,t){this.isOpen&&this.detectedGesture!==e&&(this.detectedGesture=e,this.panel.querySelectorAll(`.${s}row[data-gesture]`).forEach(n=>{const i=n.dataset.gesture;n.classList.toggle(`${s}active`,i===e&&t>.6)}))}destroy(){this.stopCapture(),this.styleEl.remove(),this.root.remove()}toggle(){this.isOpen?this.close():this.open()}open(){this.isOpen=!0,this.renderRows(),this.panel.classList.add(`${s}open`),this.fab.classList.add(`${s}fab-open`)}close(){this.isOpen=!1,this.stopCapture(),this.panel.classList.remove(`${s}open`),this.fab.classList.remove(`${s}fab-open`)}startCapture(e){this.stopCapture(),this.capturingGesture=e,this.captureHandler=t=>{if(t.preventDefault(),t.stopImmediatePropagation(),["Shift","Control","Alt","Meta"].includes(t.key)){document.addEventListener("keydown",this.captureHandler,{once:!0,capture:!0});return}this.mapper.bind(e,t.key,{ctrl:t.ctrlKey||void 0,alt:t.altKey||void 0,shift:t.shiftKey||void 0,meta:t.metaKey||void 0}),this.capturingGesture=null,this.captureHandler=null,this.renderRows()},document.addEventListener("keydown",this.captureHandler,{once:!0,capture:!0}),this.renderRows()}stopCapture(){this.captureHandler&&(document.removeEventListener("keydown",this.captureHandler,{capture:!0}),this.captureHandler=null,this.capturingGesture=null)}createFab(){const e=document.createElement("button");return e.className=`${s}fab`,e.title="handface 제스처 설정",e.innerHTML="✋",e}createPanel(){const e=document.createElement("div");return e.className=`${s}panel`,e.innerHTML=`
+      <div class="${s}header">
+        <span class="${s}title">✋ handface</span>
+        <button class="${s}close-btn" title="닫기">✕</button>
+      </div>
+      <div class="${s}body">
+        <div class="${s}section-label">기본 동작</div>
+        <div class="${s}builtin-rows"></div>
+        <div class="${s}section-label" style="margin-top:10px">단축키 바인딩</div>
+        <div class="${s}binding-rows"></div>
+      </div>
+    `,e.querySelector(`.${s}close-btn`).addEventListener("click",()=>this.close()),e}renderRows(){this.renderBuiltin(),this.renderBindings()}renderBuiltin(){const e=this.panel.querySelector(`.${s}builtin-rows`);e.innerHTML="",e.appendChild(this.makeReadonlyRow("🤏","엄지+중지 핀치","클릭",null));for(const t of H){const n=v[t];e.appendChild(this.makeReadonlyRow(n.icon,n.labelKo,n.builtinAction,t))}}renderBindings(){const e=this.panel.querySelector(`.${s}binding-rows`);e.innerHTML="";for(const t of D){const n=v[t],i=this.mapper.getBinding(t),a=this.capturingGesture===t;e.appendChild(this.makeBindingRow(t,n.icon,n.labelKo,(i==null?void 0:i.key)??null,a))}}makeReadonlyRow(e,t,n,i){const a=document.createElement("div");return a.className=`${s}row`,i&&(a.dataset.gesture=i),a.innerHTML=`
+      <span class="${s}icon">${e}</span>
+      <span class="${s}name">${t}</span>
+      <span class="${s}badge">${n}</span>
+    `,a}makeBindingRow(e,t,n,i,a){var p;const r=document.createElement("div");r.className=`${s}row`,r.dataset.gesture=e;const h=i?this.buildKeyLabel(this.mapper.getBinding(e)):null;return a?(r.innerHTML=`
+        <span class="${s}icon">${t}</span>
+        <span class="${s}name">${n}</span>
+        <span class="${s}capture-hint">단축키 입력...</span>
+        <button class="${s}cancel-btn">취소</button>
+      `,r.querySelector(`.${s}cancel-btn`).addEventListener("click",()=>{this.stopCapture(),this.renderRows()})):(r.innerHTML=`
+        <span class="${s}icon">${t}</span>
+        <span class="${s}name">${n}</span>
+        ${h?`<span class="${s}key-tag">${h}</span>
+             <button class="${s}bind-btn ${s}clear-btn" data-gesture="${e}" title="제거">✕</button>`:`<span class="${s}no-bind">—</span>`}
+        <button class="${s}bind-btn ${s}edit-btn" data-gesture="${e}" title="단축키 설정">✎</button>
+      `,r.querySelector(`.${s}edit-btn`).addEventListener("click",()=>this.startCapture(e)),(p=r.querySelector(`.${s}clear-btn`))==null||p.addEventListener("click",()=>{this.mapper.unbind(e),this.renderRows()})),r}buildKeyLabel(e){var n,i,a,r;const t=[];return(n=e.modifiers)!=null&&n.ctrl&&t.push("Ctrl"),(i=e.modifiers)!=null&&i.alt&&t.push("Alt"),(a=e.modifiers)!=null&&a.shift&&t.push("Shift"),(r=e.modifiers)!=null&&r.meta&&t.push("⌘"),t.push(M(e.key)),t.join("+")}injectStyles(){const e=document.createElement("style");return e.dataset.handface="styles",e.textContent=`
+      .${s}fab {
+        position: fixed;
+        right: 20px;
+        bottom: 20px;
+        width: 46px;
+        height: 46px;
+        border-radius: 50%;
+        background: linear-gradient(135deg, #7c6af7, #5b4dd4);
+        color: #fff;
+        border: none;
+        cursor: pointer;
+        font-size: 1.25rem;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        box-shadow: 0 4px 20px rgba(124,106,247,0.45);
+        z-index: 999998;
+        transition: transform 0.18s, box-shadow 0.18s;
+        user-select: none;
+      }
+      .${s}fab:hover { transform: scale(1.1); box-shadow: 0 6px 28px rgba(124,106,247,0.65); }
+      .${s}fab-open  { transform: rotate(20deg) scale(1.05); }
+
+      .${s}panel {
+        position: fixed;
+        right: 20px;
+        bottom: 76px;
+        width: 272px;
+        background: rgba(10, 10, 20, 0.97);
+        border: 1px solid rgba(124,106,247,0.28);
+        border-radius: 16px;
+        z-index: 999999;
+        -webkit-backdrop-filter: blur(24px);
+        backdrop-filter: blur(24px);
+        box-shadow: 0 12px 48px rgba(0,0,0,0.55);
+        color: #ddddf5;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+        font-size: 13px;
+        opacity: 0;
+        transform: translateY(10px) scale(0.97);
+        pointer-events: none;
+        transition: opacity 0.2s ease, transform 0.2s ease;
+      }
+      .${s}open {
+        opacity: 1;
+        transform: translateY(0) scale(1);
+        pointer-events: all;
+      }
+
+      .${s}header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        padding: 13px 16px 11px;
+        border-bottom: 1px solid rgba(255,255,255,0.07);
+      }
+      .${s}title {
+        font-weight: 700;
+        font-size: 0.85rem;
+        letter-spacing: -0.01em;
+      }
+      .${s}close-btn {
+        background: none;
+        border: none;
+        color: rgba(221,221,245,0.45);
+        cursor: pointer;
+        font-size: 0.8rem;
+        padding: 2px 4px;
+        border-radius: 4px;
+        transition: color 0.12s;
+      }
+      .${s}close-btn:hover { color: #ddddf5; }
+
+      .${s}body {
+        padding: 12px 14px 14px;
+      }
+      .${s}section-label {
+        font-size: 0.6rem;
+        text-transform: uppercase;
+        letter-spacing: 0.11em;
+        opacity: 0.35;
+        margin-bottom: 7px;
+      }
+
+      .${s}row {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        padding: 5px 6px;
+        border-radius: 8px;
+        margin-bottom: 3px;
+        transition: background 0.15s;
+      }
+      .${s}row.${s}active {
+        background: rgba(124,106,247,0.18);
+      }
+
+      .${s}icon { font-size: 1rem; width: 22px; text-align: center; flex-shrink: 0; }
+      .${s}name { flex: 1; opacity: 0.8; font-size: 0.76rem; }
+
+      .${s}badge {
+        font-size: 0.65rem;
+        background: rgba(124,106,247,0.25);
+        color: #9d8dff;
+        padding: 2px 7px;
+        border-radius: 99px;
+        white-space: nowrap;
+      }
+
+      .${s}key-tag {
+        font-size: 0.65rem;
+        font-family: 'SF Mono', 'Fira Code', monospace;
+        background: rgba(78,205,196,0.15);
+        color: #4ecdc4;
+        padding: 2px 7px;
+        border-radius: 6px;
+        white-space: nowrap;
+        max-width: 80px;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
+
+      .${s}no-bind {
+        font-size: 0.72rem;
+        opacity: 0.3;
+      }
+
+      .${s}bind-btn {
+        background: none;
+        border: none;
+        cursor: pointer;
+        border-radius: 5px;
+        padding: 2px 5px;
+        font-size: 0.75rem;
+        transition: background 0.12s, color 0.12s;
+        flex-shrink: 0;
+      }
+      .${s}edit-btn  { color: rgba(221,221,245,0.45); }
+      .${s}edit-btn:hover  { background: rgba(124,106,247,0.2); color: #9d8dff; }
+      .${s}clear-btn { color: rgba(221,221,245,0.3); }
+      .${s}clear-btn:hover { background: rgba(255,80,80,0.15); color: #ff6b6b; }
+
+      .${s}capture-hint {
+        flex: 1;
+        font-size: 0.7rem;
+        color: #ffd166;
+        animation: ${s}blink 1s step-end infinite;
+      }
+      .${s}cancel-btn {
+        background: none;
+        border: 1px solid rgba(255,80,80,0.3);
+        color: rgba(255,100,100,0.7);
+        border-radius: 5px;
+        padding: 2px 7px;
+        font-size: 0.65rem;
+        cursor: pointer;
+        flex-shrink: 0;
+      }
+      .${s}cancel-btn:hover { background: rgba(255,80,80,0.1); }
+
+      @keyframes ${s}blink {
+        0%, 100% { opacity: 1; }
+        50%       { opacity: 0.3; }
+      }
+    `,document.head.appendChild(e),e}}const R=.09,z=600,T=12,K=900;function N(c){return c==="right"?"Left":c==="left"?"Right":null}class G extends g{constructor(t={}){super();o(this,"video");o(this,"detector");o(this,"rafId",null);o(this,"stream",null);o(this,"panel",null);o(this,"isClicking",!1);o(this,"lastClickMs",0);o(this,"lastGestureMs",new Map);o(this,"smoothX",.5);o(this,"smoothY",.5);o(this,"smoothing");o(this,"flipHorizontal");o(this,"cursorAnchor");o(this,"ownedVideo");o(this,"mapper",new C);this.smoothing=t.smoothing??.6,this.flipHorizontal=t.flipHorizontal??!0,this.cursorAnchor=t.cursorAnchor??"wrist";const n=t.threshold??.05;t.video?(this.video=t.video,this.ownedVideo=!1):(this.video=this.createHiddenVideo(),this.ownedVideo=!0),this.detector=new A(t.wasmPath,n,N(t.handedness??"right"))}async start(){await this.detector.init(),this.stream=await navigator.mediaDevices.getUserMedia({video:!0}),this.video.srcObject=this.stream,await new Promise(t=>{this.video.onloadedmetadata=()=>{this.video.play(),t()}}),this.loop()}stop(){var t,n;this.rafId!==null&&(cancelAnimationFrame(this.rafId),this.rafId=null),(t=this.stream)==null||t.getTracks().forEach(i=>i.stop()),this.stream=null,this.detector.destroy(),(n=this.panel)==null||n.destroy(),this.panel=null,this.ownedVideo&&this.video.remove(),this.removeAllListeners()}createPanel(){return this.panel||(this.panel=new L(this.mapper)),this.panel}createHiddenVideo(){const t=document.createElement("video");return t.style.cssText="position:fixed;top:0;left:0;width:1px;height:1px;opacity:0;pointer-events:none;",document.body.appendChild(t),t}loop(){this.rafId=requestAnimationFrame(()=>{this.tick(),this.rafId!==null&&this.loop()})}tick(){var x,$;const t=performance.now(),n=this.detector.detect(this.video,t);if(!n)return;const i=this.cursorAnchor==="index"?n.indexTip:this.cursorAnchor==="palm"?n.palmCenter:n.wrist,a=this.flipHorizontal?1-i.x:i.x,r=i.y;this.smoothX=k(this.smoothX,a,1-this.smoothing),this.smoothY=k(this.smoothY,r,1-this.smoothing);const h=Math.round(this.smoothX*window.innerWidth),p=Math.round(this.smoothY*window.innerHeight),m={x:this.smoothX,y:this.smoothY,screenX:h,screenY:p};if(this.emit("move",m),n.gesture==="click"){if(!this.isClicking){this.isClicking=!0;const b=Date.now();b-this.lastClickMs>z&&(this.lastClickMs=b,this.emit("click",m))}}else n.clickPinchDistance>R&&(this.isClicking=!1);this.isClicking||(n.gestureName==="fist"?this.emit("scroll",{deltaY:T}):n.gestureName==="openpalm"&&this.emit("scroll",{deltaY:-T}));const u=n.gestureName;if(u){(x=this.panel)==null||x.setDetected(u,n.gestureConfidence);const b=Date.now(),y=this.lastGestureMs.get(u)??0;if(b-y>K){this.lastGestureMs.set(u,b);const O={gesture:u,...m,confidence:n.gestureConfidence};this.emit(u,O),this.mapper.trigger(u)}}else($=this.panel)==null||$.setDetected(null,0)}}l.ControlPanel=L,l.GESTURE_META=v,l.GestureMapper=C,l.HandControl=G,l.formatKeyLabel=M,Object.defineProperty(l,Symbol.toStringTag,{value:"Module"})});

package/dist/index.d.ts

@@ -1,2 +1,5 @@
 export { HandControl } from './HandControl';
-export type { HandControlOptions, HandControlEventMap, MoveEvent, ClickEvent, ScrollEvent, DragEvent, } from './types';
+export { GestureMapper, formatKeyLabel } from './GestureMapper';
+export { ControlPanel } from './ControlPanel';
+export type { HandControlOptions, HandControlEventMap, MoveEvent, ClickEvent, ScrollEvent, DragEvent, GestureName, GestureEvent, GestureKeyBinding, } from './types';
+export { GESTURE_META } from './types';

package/dist/types.d.ts

@@ -24,6 +24,26 @@ export interface DragEvent {
     screenX: number;
     screenY: number;
 }
+/** MediaPipe GestureRecognizer 제스처 이름 */
+export type GestureName = 'pointing' | 'fist' | 'openpalm' | 'thumbsup' | 'thumbsdown' | 'victory' | 'iloveyou';
+export interface GestureEvent {
+    gesture: GestureName;
+    x: number;
+    y: number;
+    screenX: number;
+    screenY: number;
+    confidence: number;
+}
+export interface GestureKeyBinding {
+    gesture: GestureName;
+    key: string;
+    modifiers?: {
+        ctrl?: boolean;
+        alt?: boolean;
+        shift?: boolean;
+        meta?: boolean;
+    };
+}
 export type HandControlEventMap = {
     click: ClickEvent;
     rightclick: ClickEvent;
@@ -32,6 +52,13 @@ export type HandControlEventMap = {
     drag: DragEvent;
     dragstart: ClickEvent;
     dragend: ClickEvent;
+    pointing: GestureEvent;
+    fist: GestureEvent;
+    openpalm: GestureEvent;
+    thumbsup: GestureEvent;
+    thumbsdown: GestureEvent;
+    victory: GestureEvent;
+    iloveyou: GestureEvent;
 };
 export interface HandControlOptions {
     /** 기존 video 엘리먼트를 전달하면 그것을 사용, 없으면 자동 생성 */
@@ -44,4 +71,24 @@ export interface HandControlOptions {
     smoothing?: number;
     /** MediaPipe wasm 파일 경로 (CDN 기본값 제공) */
     wasmPath?: string;
+    /**
+     * 감지할 손 방향 (default 'right')
+     * 정면 카메라 raw 피드 기준. 기기/환경에 따라 'left'로 전환 필요할 수 있음.
+     */
+    handedness?: 'right' | 'left' | 'any';
+    /**
+     * 커서 추적 기준점 (default 'wrist')
+     * - 'wrist'  : 손목 (손 전체 위치 기반)
+     * - 'palm'   : 손바닥 중심
+     * - 'index'  : 검지 끝 (기존 동작)
+     */
+    cursorAnchor?: 'wrist' | 'palm' | 'index';
 }
+/** 제스처 표시 메타데이터 */
+export declare const GESTURE_META: Record<GestureName, {
+    icon: string;
+    label: string;
+    labelKo: string;
+    builtin: boolean;
+    builtinAction?: string;
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whatpull/handface",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Hand gesture to mouse event control library using MediaPipe",
   "type": "module",
   "main": "./dist/handface.umd.cjs",
@@ -12,10 +12,14 @@
       "require": "./dist/handface.umd.cjs"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "dev": "vite",
     "build": "vite build",
+    "build:demo": "vite build --config vite.config.demo.ts",
+    "deploy:demo": "npm run build:demo && gh-pages -d dist-demo",
     "typecheck": "tsc --noEmit",
     "preview": "vite preview"
   },
@@ -24,12 +28,20 @@
   },
   "devDependencies": {
     "@mediapipe/tasks-vision": "^0.10.14",
+    "@types/three": "^0.183.1",
+    "gh-pages": "^6.3.0",
     "typescript": "^5.4.0",
     "vite": "^5.2.0",
     "vite-plugin-dts": "^3.9.0"
   },
-  "keywords": ["mediapipe", "hand-tracking", "gesture", "mouse", "typescript"],
-  "license": "MIT",
+  "keywords": [
+    "mediapipe",
+    "hand-tracking",
+    "gesture",
+    "mouse",
+    "typescript"
+  ],
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/whatpull/handface.git"
@@ -37,5 +49,8 @@
   "homepage": "https://github.com/whatpull/handface#readme",
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "three": "^0.183.2"
   }
 }