hand-guest-control 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HoloLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# hand-guest-control
+
+Hand gesture detection and state management using MediaPipe landmarks. Extracted from `mn-hand-control`.
+
+## Demo UI (test package in browser)
+
+```bash
+cd npm/hand-guest-control
+npm install
+npm run demo
+```
+
+Open **http://localhost:5180** — webcam + live hand state overlay.
+
+## Install
+
+```bash
+npm install hand-guest-control @mediapipe/tasks-vision
+```
+
+Or local workspace link during development:
+
+```bash
+npm install ../npm/hand-guest-control
+```
+
+## Usage
+
+### Core — gesture state machine
+
+```javascript
+import { HandStateManager, HAND_STATES } from 'hand-guest-control';
+
+const manager = new HandStateManager({
+  rotationSensitivity: 4,
+  waitingTimeout: 10000,
+  startingDelay: 3000,
+  debug: false
+});
+
+// landmarks from MediaPipe HandLandmarker
+const { state, rotation } = manager.processLandmarks(landmarks);
+
+if (state === HAND_STATES.OPEN) {
+  // zoom in
+}
+
+if (state === HAND_STATES.SWIPE_NEXT) {
+  // next item
+}
+```
+
+### MediaPipe helper
+
+```javascript
+import { createHandLandmarker } from 'hand-guest-control/mediapipe';
+
+const landmarker = await createHandLandmarker({
+  minHandDetectionConfidence: 0.6
+});
+
+const results = await landmarker.detectForVideo(videoElement, Date.now());
+const { state, rotation } = manager.processLandmarks(results.landmarks?.[0]);
+```
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `HandStateManager` | Main state machine — `processLandmarks(landmarks)` → `{ state, rotation }` |
+| `HandGestureDetector` | Low-level gesture detection |
+| `HAND_STATES` | State constants (`open`, `closed`, `swipe_next`, …) |
+| `LANDMARKS` | MediaPipe landmark indices |
+| `HAND_CONNECTIONS` | Landmark pairs for debug drawing |
+| `DEFAULT_CONFIG` | Default configuration object |
+| `createHandLandmarker` | MediaPipe setup with GPU→CPU fallback |
+
+## Hand states
+
+- `not_detected` — no hand in frame
+- `waiting` — hand lost for extended period
+- `starting` — cooldown after re-detection
+- `open` — open palm (zoom)
+- `closed` — closed fist
+- `pointing` — index finger extended
+- `flipping` — middle finger gesture
+- `swipe_next` / `swipe_previous` — horizontal swipe while pointing

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "hand-guest-control",
+  "version": "0.1.0",
+  "description": "Hand gesture detection and state management using MediaPipe landmarks",
+  "type": "module",
+  "author": "HoloLab",
+  "license": "MIT",
+  "keywords": [
+    "hand-gesture",
+    "mediapipe",
+    "hand-tracking",
+    "gesture-control",
+    "hand-landmarks"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.js",
+    "./mediapipe": "./src/mediapipe.js"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm test",
+    "demo": "vite",
+    "demo:build": "vite build"
+  },
+  "devDependencies": {
+    "@mediapipe/tasks-vision": "^0.10.0",
+    "vite": "^7.0.0"
+  },
+  "peerDependencies": {
+    "@mediapipe/tasks-vision": "^0.10.0"
+  },
+  "peerDependenciesMeta": {
+    "@mediapipe/tasks-vision": {
+      "optional": true
+    }
+  }
+}

package/src/HandGestureDetector.js

@@ -0,0 +1,192 @@
+import { LANDMARKS } from './constants.js';
+
+export class HandGestureDetector {
+  constructor(config) {
+    this.config = config;
+  }
+
+  static getDistance(p1, p2) {
+    const dx = p1.x - p2.x;
+    const dy = p1.y - p2.y;
+    return Math.sqrt(dx * dx + dy * dy);
+  }
+
+  static getAngle(p1, p2, p3) {
+    const v1x = p2.x - p1.x;
+    const v1y = p2.y - p1.y;
+    const v2x = p3.x - p2.x;
+    const v2y = p3.y - p2.y;
+    const dot = v1x * v2x + v1y * v2y;
+    const det = v1x * v2y - v1y * v2x;
+    let angle = (Math.atan2(det, dot) * 180) / Math.PI;
+    return angle < 0 ? angle + 360 : angle;
+  }
+
+  computeDistances(landmarks) {
+    const wrist = landmarks[LANDMARKS.WRIST];
+    const tips = [
+      LANDMARKS.THUMB_TIP,
+      LANDMARKS.INDEX_TIP,
+      LANDMARKS.MIDDLE_TIP,
+      LANDMARKS.RING_TIP,
+      LANDMARKS.PINKY_TIP
+    ];
+
+    const distances = {};
+    const fingerNames = ['Thumb', 'Index', 'Middle', 'Ring', 'Pinky'];
+    const adjacentNames = ['thumbToIndex', 'indexToMiddle', 'middleToRing', 'ringToPinky'];
+
+    tips.forEach((tip, i) => {
+      distances[`palmTo${fingerNames[i]}`] = HandGestureDetector.getDistance(wrist, landmarks[tip]);
+
+      if (i > 0) {
+        distances[adjacentNames[i - 1]] = HandGestureDetector.getDistance(
+          landmarks[tips[i - 1]],
+          landmarks[tip]
+        );
+      }
+    });
+
+    return distances;
+  }
+
+  checkOpenHand(distances, histories, indices) {
+    const handSize = (distances.palmToThumb + distances.palmToMiddle) / 2 || 0.15;
+    const normalized = {
+      thumb: distances.palmToThumb / handSize,
+      index: distances.palmToIndex / handSize,
+      middle: distances.palmToMiddle / handSize,
+      ring: distances.palmToRing / handSize,
+      pinky: distances.palmToPinky / handSize,
+      thumbToIndex: distances.thumbToIndex / handSize
+    };
+
+    if (this.config.debug) {
+      console.log(`Hand state check (open): thumb=${normalized.thumb.toFixed(2)}, ` +
+        `index=${normalized.index.toFixed(2)}, middle=${normalized.middle.toFixed(2)}, ` +
+        `ring=${normalized.ring.toFixed(2)}, pinky=${normalized.pinky.toFixed(2)}, ` +
+        `thumbToIndex=${normalized.thumbToIndex.toFixed(2)}`);
+    }
+
+    const fingers = ['index', 'middle', 'ring', 'pinky'];
+    const extended = fingers.filter((finger) => normalized[finger] > normalized.thumb).length;
+
+    const isCandidate = extended >= this.config.openHandThresholds.minExtendedFingers;
+    histories.open[indices.open] = isCandidate;
+    indices.open = (indices.open + 1) % this.config.minOpenConfidence;
+
+    return histories.open.filter(Boolean).length >= Math.ceil(this.config.minOpenConfidence * 0.7);
+  }
+
+  checkClosedHand(distances, histories, indices) {
+    const handSize = (distances.palmToThumb + distances.palmToMiddle) / 2 || 0.15;
+    const normalized = {
+      thumb: distances.palmToThumb / handSize,
+      index: distances.palmToIndex / handSize,
+      middle: distances.palmToMiddle / handSize,
+      ring: distances.palmToRing / handSize,
+      pinky: distances.palmToPinky / handSize,
+      thumbToIndex: distances.thumbToIndex / handSize
+    };
+
+    if (this.config.debug) {
+      console.log(`Hand state check (closed): thumb=${normalized.thumb.toFixed(2)}, ` +
+        `index=${normalized.index.toFixed(2)}, middle=${normalized.middle.toFixed(2)}, ` +
+        `ring=${normalized.ring.toFixed(2)}, pinky=${normalized.pinky.toFixed(2)}, ` +
+        `thumbToIndex=${normalized.thumbToIndex.toFixed(2)}`);
+    }
+
+    const fingers = ['index', 'middle', 'ring', 'pinky'];
+    const closedFingers = fingers.filter((finger) => normalized[finger] < normalized.thumb).length;
+
+    const isCandidate = closedFingers >= this.config.openHandThresholds.minExtendedFingers;
+    histories.closed[indices.closed] = isCandidate;
+    indices.closed = (indices.closed + 1) % this.config.minClosedConfidence;
+
+    return histories.closed.filter(Boolean).length >= Math.ceil(this.config.minClosedConfidence * 0.7);
+  }
+
+  isPointing(distances, histories, indices) {
+    const handSize = distances.palmToIndex || 0.15;
+    const normalized = {
+      index: distances.palmToIndex / handSize,
+      middle: distances.palmToMiddle / handSize,
+      ring: distances.palmToRing / handSize,
+      pinky: distances.palmToPinky / handSize,
+      thumb: distances.palmToThumb / handSize
+    };
+
+    const otherFingers = [normalized.middle, normalized.ring, normalized.pinky, normalized.thumb];
+    const isIndexExtended = 0.5 > Math.max(...otherFingers) && normalized.thumb < 0.7;
+
+    histories.pointing[indices.pointing] = isIndexExtended;
+    indices.pointing = (indices.pointing + 1) % this.config.minPointingConfidence;
+
+    return histories.pointing.filter(Boolean).length >= Math.ceil(this.config.minPointingConfidence * 0.9);
+  }
+
+  isFlipping(distances, histories, indices) {
+    const handSize = distances.palmToIndex || 0.15;
+    const normalized = {
+      index: distances.palmToIndex / handSize,
+      middle: distances.palmToMiddle / handSize,
+      ring: distances.palmToRing / handSize,
+      pinky: distances.palmToPinky / handSize,
+      thumb: distances.palmToThumb / handSize
+    };
+
+    if (this.config.debug) {
+      console.log(`Hand state check (flip): index=${normalized.index.toFixed(2)}, ` +
+        `middle=${normalized.middle.toFixed(2)}, ring=${normalized.ring.toFixed(2)}, ` +
+        `pinky=${normalized.pinky.toFixed(2)}, thumb=${normalized.thumb.toFixed(2)}`);
+    }
+
+    const isFlippingGesture = normalized.middle > 0.8 &&
+      Math.max(normalized.ring, normalized.pinky, normalized.thumb) < 0.5;
+
+    histories.flipping[indices.flipping] = isFlippingGesture;
+    indices.flipping = (indices.flipping + 1) % this.config.minFlippingConfidence;
+
+    return histories.flipping.filter(Boolean).length >= Math.ceil(this.config.minFlippingConfidence * 0.9);
+  }
+
+  checkSwipeNext(landmarks, distances, histories, indices, pointingCount, lastActionTime) {
+    if (
+      !this.isPointing(distances, histories, indices) ||
+      !landmarks ||
+      histories.landmark0.filter(Boolean).length < 6 ||
+      pointingCount < this.config.minPointingCount ||
+      Date.now() - lastActionTime < 2000
+    ) {
+      return false;
+    }
+
+    const entries = histories.landmark0.filter(Boolean);
+    const xPositions = entries.map((e) => e.x);
+    const xRange = Math.max(...xPositions) - Math.min(...xPositions);
+    const firstX = entries[0].x;
+    const lastX = entries[entries.length - 1].x;
+
+    return xRange > 0.03 && lastX - firstX > 0.03;
+  }
+
+  checkSwipePrevious(landmarks, distances, histories, indices, pointingCount, lastActionTime) {
+    if (
+      !this.isPointing(distances, histories, indices) ||
+      !landmarks ||
+      histories.landmark0.filter(Boolean).length < 6 ||
+      pointingCount < this.config.minPointingCount ||
+      Date.now() - lastActionTime < 2000
+    ) {
+      return false;
+    }
+
+    const entries = histories.landmark0.filter(Boolean);
+    const xPositions = entries.map((e) => e.x);
+    const xRange = Math.max(...xPositions) - Math.min(...xPositions);
+    const firstX = entries[0].x;
+    const lastX = entries[entries.length - 1].x;
+
+    return xRange > 0.03 && firstX - lastX > 0.03;
+  }
+}

package/src/HandStateManager.js

@@ -0,0 +1,276 @@
+import { HAND_STATES, LANDMARKS, DEFAULT_CONFIG } from './constants.js';
+import { HandGestureDetector } from './HandGestureDetector.js';
+
+export class HandStateManager {
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.gestureDetector = new HandGestureDetector(this.config);
+
+    this.initializeState();
+  }
+
+  initializeState() {
+    this.histories = {
+      centroid: new Array(this.config.maxCentroidHistorySize).fill(null),
+      landmark0: new Array(this.config.maxHistorySize).fill(null),
+      open: new Array(this.config.minOpenConfidence).fill(false),
+      pointing: new Array(this.config.minPointingConfidence).fill(false),
+      flipping: new Array(this.config.minFlippingConfidence).fill(false),
+      closed: new Array(this.config.minClosedConfidence).fill(false)
+    };
+
+    this.indices = {
+      history: 0,
+      centroid: 0,
+      open: 0,
+      pointing: 0,
+      flipping: 0,
+      closed: 0
+    };
+
+    this.resetTrackingState();
+  }
+
+  resetTrackingState() {
+    this.prevLandmark0 = null;
+    this.lastActionTime = 0;
+    this.pointingCount = 0;
+    this.flippingCount = 0;
+    this.detectionPausedUntil = 0;
+    this.noDetectionStartTime = 0;
+    this.lastDetectionTime = 0;
+    this.lastState = null;
+  }
+
+  calculateCentroid(landmarks, now) {
+    if (!landmarks?.length) {
+      return { x: 0, y: 0 };
+    }
+
+    const landmark0 = landmarks[LANDMARKS.WRIST] || landmarks[0];
+    this.histories.landmark0[this.indices.history] = {
+      x: landmark0.x,
+      y: landmark0.y,
+      time: now
+    };
+    this.indices.history = (this.indices.history + 1) % this.config.maxHistorySize;
+
+    const validPoints = this.histories.landmark0.filter(Boolean);
+    if (!validPoints.length) {
+      return { x: landmark0.x, y: landmark0.y };
+    }
+
+    const sum = validPoints.reduce(
+      (acc, p) => ({ x: acc.x + p.x, y: acc.y + p.y }),
+      { x: 0, y: 0 }
+    );
+
+    return {
+      x: sum.x / validPoints.length,
+      y: sum.y / validPoints.length
+    };
+  }
+
+  getRotation(landmarks, centroid) {
+    if (!landmarks?.[LANDMARKS.MIDDLE_TIP]) {
+      return [0, 0, 0];
+    }
+
+    const handSize = HandGestureDetector.getDistance(
+      landmarks[LANDMARKS.WRIST],
+      landmarks[LANDMARKS.THUMB_TIP]
+    ) || 0.15;
+
+    const scaleFactor = 0.15 / handSize;
+    const delta = this.prevLandmark0 ? {
+      x: (centroid.x - this.prevLandmark0.x) * scaleFactor,
+      y: (centroid.y - this.prevLandmark0.y) * scaleFactor
+    } : { x: 0, y: 0 };
+
+    this.prevLandmark0 = { x: centroid.x, y: centroid.y };
+
+    return [
+      delta.y * this.config.rotationSensitivity,
+      delta.x * this.config.rotationSensitivity,
+      0
+    ];
+  }
+
+  handleNoDetection(now) {
+    this.pointingCount = 0;
+    this.flippingCount = 0;
+
+    if (!this.noDetectionStartTime) {
+      this.noDetectionStartTime = now;
+    }
+
+    const noDetectionDuration = now - this.noDetectionStartTime;
+
+    if (noDetectionDuration < this.config.detectionTolerance) {
+      return { state: this.lastState || HAND_STATES.NOT_DETECTED, rotation: [0, 0, 0] };
+    }
+
+    if (noDetectionDuration >= this.config.waitingTimeout) {
+      this.lastState = HAND_STATES.WAITING;
+      if (this.config.debug) {
+        console.log(`Transitioned to WAITING after ${this.config.waitingTimeout / 1000}s`);
+      }
+      return { state: HAND_STATES.WAITING, rotation: [0, 0, 0] };
+    }
+
+    this.lastState = HAND_STATES.NOT_DETECTED;
+    if (this.config.debug) {
+      console.log(`Transitioned to NOT_DETECTED after ${this.config.detectionTolerance / 1000}s`);
+    }
+    return { state: HAND_STATES.NOT_DETECTED, rotation: [0, 0, 0] };
+  }
+
+  handleDetectionReconnection(now) {
+    const isWaitingOrNotDetected = [HAND_STATES.WAITING, HAND_STATES.NOT_DETECTED].includes(this.lastState);
+    const isReconnection = ![HAND_STATES.WAITING, HAND_STATES.NOT_DETECTED, HAND_STATES.STARTING].includes(this.lastState) &&
+      now - this.lastDetectionTime <= this.config.detectionTolerance;
+
+    if (isReconnection) {
+      if (this.config.debug) {
+        console.log(`Short reconnection (${(now - this.lastDetectionTime) / 1000}s), continuing with last state: ${this.lastState}`);
+      }
+    } else if (isWaitingOrNotDetected) {
+      this.detectionPausedUntil = now + this.config.startingDelay;
+      this.noDetectionStartTime = 0;
+      this.lastState = HAND_STATES.STARTING;
+      return { state: HAND_STATES.STARTING, rotation: [0, 0, 0] };
+    }
+
+    return null;
+  }
+
+  determineHandState(distances) {
+    if (this.gestureDetector.checkSwipeNext(
+      this.histories.landmark0, distances, this.histories, this.indices,
+      this.pointingCount, this.lastActionTime
+    )) {
+      this.resetSwipeState();
+      return HAND_STATES.SWIPE_NEXT;
+    }
+
+    if (this.gestureDetector.checkSwipePrevious(
+      this.histories.landmark0, distances, this.histories, this.indices,
+      this.pointingCount, this.lastActionTime
+    )) {
+      this.resetSwipeState();
+      return HAND_STATES.SWIPE_PREVIOUS;
+    }
+
+    if (this.gestureDetector.isFlipping(distances, this.histories, this.indices)) {
+      return HAND_STATES.FLIPPING;
+    }
+
+    if (this.gestureDetector.checkClosedHand(distances, this.histories, this.indices)) {
+      return HAND_STATES.CLOSED;
+    }
+
+    if (this.gestureDetector.checkOpenHand(distances, this.histories, this.indices)) {
+      return HAND_STATES.OPEN;
+    }
+
+    if (this.gestureDetector.isPointing(distances, this.histories, this.indices)) {
+      return HAND_STATES.POINTING;
+    }
+
+    return HAND_STATES.CLOSED;
+  }
+
+  resetSwipeState() {
+    this.histories.landmark0.fill(null);
+    this.indices.history = 0;
+    this.lastActionTime = Date.now();
+    this.pointingCount = 0;
+    this.flippingCount = 0;
+  }
+
+  validateStateTransition(newState) {
+    const validTransitionStates = [HAND_STATES.OPEN, HAND_STATES.POINTING, HAND_STATES.CLOSED, HAND_STATES.FLIPPING];
+
+    if (newState === this.lastState || !validTransitionStates.includes(newState)) {
+      return newState;
+    }
+
+    const historyKeys = {
+      [HAND_STATES.OPEN]: 'open',
+      [HAND_STATES.POINTING]: 'pointing',
+      [HAND_STATES.CLOSED]: 'closed',
+      [HAND_STATES.FLIPPING]: 'flipping'
+    };
+
+    const historyKey = historyKeys[newState];
+    if (!historyKey) return newState;
+
+    const requiredConfidence = this.config[`min${historyKey.charAt(0).toUpperCase() + historyKey.slice(1)}Confidence`];
+    const actualConfidence = this.histories[historyKey].filter(Boolean).length;
+
+    if (actualConfidence < requiredConfidence * 0.9) {
+      return this.lastState;
+    }
+
+    return newState;
+  }
+
+  clearAllHistory() {
+    Object.values(this.histories).forEach((history) => history.fill(null));
+    Object.keys(this.indices).forEach((key) => { this.indices[key] = 0; });
+    this.resetTrackingState();
+  }
+
+  processLandmarks(landmarks) {
+    const now = Date.now();
+
+    if (this.detectionPausedUntil > now) {
+      if (this.config.debug) {
+        console.log(`In STARTING state until ${new Date(this.detectionPausedUntil).toLocaleTimeString()}`);
+      }
+      return { state: HAND_STATES.STARTING, rotation: [0, 0, 0] };
+    }
+
+    if (!landmarks?.[LANDMARKS.PINKY_TIP]) {
+      return this.handleNoDetection(now);
+    }
+
+    this.lastDetectionTime = now;
+    const reconnectionResult = this.handleDetectionReconnection(now);
+    if (reconnectionResult) {
+      return reconnectionResult;
+    }
+
+    this.noDetectionStartTime = 0;
+    this.detectionPausedUntil = 0;
+
+    const distances = this.gestureDetector.computeDistances(landmarks);
+    const centroid = this.calculateCentroid(landmarks, now);
+
+    this.histories.centroid[this.indices.centroid] = { x: centroid.x, y: centroid.y, time: now };
+    this.indices.centroid = (this.indices.centroid + 1) % this.config.maxCentroidHistorySize;
+
+    const rotation = this.getRotation(landmarks, centroid);
+
+    this.pointingCount += this.gestureDetector.isPointing(distances, this.histories, this.indices) ? 1 : 0;
+    this.flippingCount += this.gestureDetector.isFlipping(distances, this.histories, this.indices) ? 1 : 0;
+
+    let newState = this.determineHandState(distances);
+    newState = this.validateStateTransition(newState);
+
+    this.lastState = newState;
+
+    const rotationDisabledStates = [
+      HAND_STATES.POINTING,
+      HAND_STATES.SWIPE_NEXT,
+      HAND_STATES.SWIPE_PREVIOUS,
+      HAND_STATES.FLIPPING
+    ];
+
+    if (rotationDisabledStates.includes(newState)) {
+      rotation.fill(0);
+    }
+
+    return { state: newState, rotation };
+  }
+}

package/src/constants.js

@@ -0,0 +1,52 @@
+export const HAND_STATES = {
+  NOT_DETECTED: 'not_detected',
+  WAITING: 'waiting',
+  STARTING: 'starting',
+  OPEN: 'open',
+  CLOSED: 'closed',
+  POINTING: 'pointing',
+  FLIPPING: 'flipping',
+  SWIPE_NEXT: 'swipe_next',
+  SWIPE_PREVIOUS: 'swipe_previous'
+};
+
+export const LANDMARKS = {
+  WRIST: 0,
+  THUMB_TIP: 4,
+  INDEX_TIP: 8,
+  MIDDLE_TIP: 12,
+  RING_TIP: 16,
+  PINKY_TIP: 20
+};
+
+export const HAND_CONNECTIONS = [
+  [0, 1], [1, 2], [2, 3], [3, 4],
+  [0, 5], [5, 6], [6, 7], [7, 8],
+  [0, 9], [9, 10], [10, 11], [11, 12],
+  [0, 13], [13, 14], [14, 15], [15, 16],
+  [0, 17], [17, 18], [18, 19], [19, 20],
+  [5, 9], [9, 13], [13, 17]
+];
+
+export const DEFAULT_CONFIG = {
+  maxHistorySize: 10,
+  maxCentroidHistorySize: 10,
+  rotationSensitivity: 4,
+  detectionTolerance: 2000,
+  startingDelay: 1000,
+  waitingTimeout: 3000,
+  minOpenConfidence: 5,
+  minPointingConfidence: 25,
+  minFlippingConfidence: 25,
+  minClosedConfidence: 5,
+  minPointingCount: 5,
+  pointingThreshold: 0.3,
+  openHandThresholds: {
+    fingerSpread: 0.2,
+    indexToMiddle: 0.15,
+    minExtendedFingers: 4,
+    maxExtendedFingers: 6,
+    middleAngle: 50
+  },
+  debug: false
+};

package/src/index.js

@@ -0,0 +1,9 @@
+export {
+  HAND_STATES,
+  LANDMARKS,
+  HAND_CONNECTIONS,
+  DEFAULT_CONFIG
+} from './constants.js';
+
+export { HandGestureDetector } from './HandGestureDetector.js';
+export { HandStateManager } from './HandStateManager.js';

package/src/mediapipe.js

@@ -0,0 +1,59 @@
+import { HandLandmarker, FilesetResolver } from '@mediapipe/tasks-vision';
+
+export const DEFAULT_MEDIAPIPE_CONFIG = {
+  wasmPath: 'https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.0/wasm',
+  modelPath: 'https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task'
+};
+
+export const DEFAULT_DETECTION_CONFIG = {
+  runningMode: 'VIDEO',
+  numHands: 1,
+  minHandDetectionConfidence: 0.6,
+  minHandPresenceConfidence: 0.6,
+  minTrackingConfidence: 0.5
+};
+
+/**
+ * Create a MediaPipe HandLandmarker with GPU fallback to CPU.
+ * @param {object} [options]
+ * @param {string} [options.wasmPath]
+ * @param {string} [options.modelPath]
+ * @param {import('@mediapipe/tasks-vision').RunningMode} [options.runningMode]
+ * @param {number} [options.numHands]
+ * @param {number} [options.minHandDetectionConfidence]
+ * @param {number} [options.minHandPresenceConfidence]
+ * @param {number} [options.minTrackingConfidence]
+ */
+export async function createHandLandmarker(options = {}) {
+  const config = {
+    ...DEFAULT_MEDIAPIPE_CONFIG,
+    ...DEFAULT_DETECTION_CONFIG,
+    ...options
+  };
+
+  const vision = await FilesetResolver.forVisionTasks(config.wasmPath);
+
+  const landmarkerOptions = {
+    baseOptions: {
+      modelAssetPath: config.modelPath,
+      delegate: 'GPU'
+    },
+    runningMode: config.runningMode,
+    numHands: config.numHands,
+    minHandDetectionConfidence: config.minHandDetectionConfidence,
+    minHandPresenceConfidence: config.minHandPresenceConfidence,
+    minTrackingConfidence: config.minTrackingConfidence
+  };
+
+  try {
+    return await HandLandmarker.createFromOptions(vision, landmarkerOptions);
+  } catch (gpuError) {
+    console.warn('GPU delegate failed, falling back to CPU:', gpuError);
+    return HandLandmarker.createFromOptions(vision, {
+      ...landmarkerOptions,
+      baseOptions: {
+        modelAssetPath: config.modelPath
+      }
+    });
+  }
+}