@map-gesture-controls/core 0.1.8 → 0.1.9

package/README.md

@@ -16,7 +16,7 @@
 ## What it does
 
 - Detects hands and classifies gestures at 30+ fps using MediaPipe Hand Landmarker
-- Recognizes **fist** (left = pan, right = zoom, both = rotate) and **idle** states
+- Recognizes **fist** and **pinch** as interchangeable triggers (left = pan, right = zoom, both = rotate)
 - Manages gesture transitions with dwell timers and grace periods to avoid flickering
 - Provides a configurable webcam overlay with corner/full/hidden display modes
 - Ships fully typed TypeScript declarations
@@ -59,7 +59,8 @@ controller.start();
 | `GestureController` | Class | Opens the webcam, runs MediaPipe detection, and emits gesture frames |
 | `GestureStateMachine` | Class | Manages gesture state transitions with dwell and grace timers |
 | `WebcamOverlay` | Class | Renders a configurable camera preview overlay |
-| `classifyGesture` | Function | Classifies a set of hand landmarks into `fist` or `none` |
+| `classifyGesture` | Function | Stateless classifier: returns `fist`, `pinch`, `openPalm`, or `none` for a set of landmarks |
+| `createHandClassifier` | Function | Returns a stateful per-hand classifier with pinch hysteresis (use this instead of `classifyGesture` in custom pipelines) |
 | `getHandSize` | Function | Computes the bounding size of a hand from its landmarks |
 | `getTwoHandDistance` | Function | Measures the distance between two detected hands |
 | `DEFAULT_WEBCAM_CONFIG` | Constant | Default webcam overlay settings |
@@ -69,13 +70,19 @@ Full TypeScript types are exported for `GestureMode`, `GestureFrame`, `DetectedH
 
 ## Gesture recognition
 
-| Gesture | Detection rule | Use case |
+Both **fist** and **pinch** trigger the same map actions — users can use whichever is more comfortable.
+
+| Gesture | Detection rule | Map action |
 | --- | --- | --- |
 | **Left fist** | Left hand, 3+ fingers curled | Pan / drag |
-| **Right fist** | Right hand, 3+ fingers curled | Zoom in/out (vertical movement) |
-| **Both fists** | Both hands, 3+ fingers curled each | Rotate map |
+| **Left pinch** | Left hand, thumb and index tip within 25% of hand size (exits at 35%) | Pan / drag |
+| **Right fist** | Right hand, 3+ fingers curled | Zoom (move up = in, down = out) |
+| **Right pinch** | Right hand, thumb and index tip within 25% of hand size (exits at 35%) | Zoom (move up = in, down = out) |
+| **Both hands active** | Both hands fist or pinch (mixed is fine) | Rotate map |
 | **Idle** | Anything else | No action |
 
+Pinch detection uses hysteresis: the gesture is entered at 25% of hand size and held until fingers open beyond 35%. This prevents flickering when fingers hover near the threshold during a held pinch.
+
 Gestures are confirmed after a configurable dwell period (default 80 ms) and held through a grace period (default 150 ms) to prevent flickering when tracking briefly drops.
 
 ## Use cases

package/dist/GestureController.d.ts

@@ -15,6 +15,8 @@ export declare class GestureController {
     private onFrame;
     private tuning;
     private lastVideoTime;
+    private leftClassifier;
+    private rightClassifier;
     constructor(tuning: TuningConfig, onFrame: FrameCallback);
     /**
      * Initialise MediaPipe and request webcam access.

package/dist/GestureController.js

@@ -1,5 +1,5 @@
 import { FilesetResolver } from '@mediapipe/tasks-vision';
-import { classifyGesture } from './gestureClassifier.js';
+import { createHandClassifier } from './gestureClassifier.js';
 import { MEDIAPIPE_WASM_URL } from './constants.js';
 /**
  * GestureController
@@ -57,6 +57,19 @@ export class GestureController {
             writable: true,
             value: -1
         });
+        // One stateful classifier per hand label; persists pinch hysteresis across frames.
+        Object.defineProperty(this, "leftClassifier", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: createHandClassifier()
+        });
+        Object.defineProperty(this, "rightClassifier", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: createHandClassifier()
+        });
         this.tuning = tuning;
         this.onFrame = onFrame;
     }
@@ -146,7 +159,8 @@ export class GestureController {
             const rawLabel = handednessArr?.[0]?.categoryName;
             const label = rawLabel === 'Left' ? 'Left' : 'Right';
             const score = handednessArr?.[0]?.score ?? 0;
-            const gesture = classifyGesture(landmarks);
+            const classify = label === 'Left' ? this.leftClassifier : this.rightClassifier;
+            const gesture = classify(landmarks);
             return { handedness: label, score, landmarks, gesture };
         });
         const leftHand = hands.find((h) => h.handedness === 'Left') ?? null;

package/dist/GestureStateMachine.d.ts

@@ -33,6 +33,9 @@ export declare class GestureStateMachine {
     private prevZoomDist;
     private rotateSmoother;
     private prevRotateAngle;
+    private leftActiveFrames;
+    private rightActiveFrames;
+    private static readonly ESCALATION_FRAMES;
     constructor(tuning: TuningConfig);
     getMode(): GestureMode;
     update(frame: GestureFrame): StateMachineOutput;

package/dist/GestureStateMachine.js

@@ -142,6 +142,22 @@ export class GestureStateMachine {
             writable: true,
             value: null
         });
+        // Tracks how many consecutive frames each hand has been active.
+        // Used to require the secondary hand to be stable before escalating
+        // the mode (e.g. pan → rotate), preventing a single noisy frame from
+        // interrupting an ongoing single-hand gesture.
+        Object.defineProperty(this, "leftActiveFrames", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "rightActiveFrames", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
         this.panSmoother = new EMAPoint(tuning.smoothingAlpha);
         this.zoomSmoother = new EMAScalar(tuning.smoothingAlpha);
         this.rotateSmoother = new EMAScalar(tuning.smoothingAlpha);
@@ -154,17 +170,35 @@ export class GestureStateMachine {
         const { actionDwellMs, releaseGraceMs } = this.tuning;
         const { leftHand, rightHand } = frame;
         // ── Determine desired mode for this frame ─────────────────────────────────
-        const rightFist = rightHand !== null && rightHand.gesture === 'fist';
-        const leftFist = leftHand !== null && leftHand.gesture === 'fist';
-        const bothFists = rightFist && leftFist;
-        // Both fists → rotate; right only → zoom; left only → pan
-        const desired = bothFists
+        // Both fist and pinch trigger the same modes — users can choose either.
+        const isActive = (hand) => hand !== null && (hand.gesture === 'fist' || hand.gesture === 'pinch');
+        const rightActive = isActive(rightHand);
+        const leftActive = isActive(leftHand);
+        // Track consecutive active frames per hand. Used to guard against a single
+        // noisy frame from the secondary hand escalating (or interrupting) an
+        // ongoing single-hand gesture. Counts reset to 0 the moment a hand drops.
+        this.leftActiveFrames = leftActive ? this.leftActiveFrames + 1 : 0;
+        this.rightActiveFrames = rightActive ? this.rightActiveFrames + 1 : 0;
+        // Escalation to 'rotating' requires both hands to have been active for at
+        // least ESCALATION_FRAMES consecutive frames. This prevents one brief noisy
+        // frame on the secondary hand from interrupting an ongoing pan or zoom.
+        const bothStable = this.leftActiveFrames >= GestureStateMachine.ESCALATION_FRAMES &&
+            this.rightActiveFrames >= GestureStateMachine.ESCALATION_FRAMES;
+        // Both stable → rotate; right only → zoom; left only → pan.
+        // When both hands are active but not yet stable, we preserve the current
+        // single-hand mode (panning/zooming) so the secondary hand must be held
+        // for ESCALATION_FRAMES before rotating kicks in. This prevents a single
+        // noisy frame from the secondary hand from interrupting an ongoing gesture.
+        const bothActiveButUnstable = leftActive && rightActive && !bothStable;
+        const desired = bothStable
             ? 'rotating'
-            : rightFist
-                ? 'zooming'
-                : leftFist
-                    ? 'panning'
-                    : 'idle';
+            : bothActiveButUnstable && (this.mode === 'panning' || this.mode === 'zooming')
+                ? this.mode // hold current mode until secondary hand is confirmed stable
+                : rightActive
+                    ? 'zooming'
+                    : leftActive
+                        ? 'panning'
+                        : 'idle';
         // ── idle ──────────────────────────────────────────────────────────────────
         if (this.mode === 'idle') {
             if (desired !== 'idle') {
@@ -182,6 +216,11 @@ export class GestureStateMachine {
         }
         // ── panning ───────────────────────────────────────────────────────────────
         if (this.mode === 'panning') {
+            // Escalate to rotating once the right hand becomes stably active too.
+            if (bothStable) {
+                this.transitionTo('rotating');
+                return this.buildOutput(null, null, null);
+            }
             if (desired !== 'panning') {
                 if (this.releaseTimer === null) {
                     this.releaseTimer = now;
@@ -192,7 +231,7 @@ export class GestureStateMachine {
                 return this.buildOutput(null, null, null);
             }
             this.releaseTimer = null;
-            const fistHand = leftHand?.gesture === 'fist' ? leftHand : null;
+            const fistHand = isActive(leftHand) ? leftHand : null;
             if (!fistHand) {
                 this.transitionTo('idle');
                 return this.buildOutput(null, null, null);
@@ -213,6 +252,11 @@ export class GestureStateMachine {
         }
         // ── zooming ───────────────────────────────────────────────────────────────
         if (this.mode === 'zooming') {
+            // Escalate to rotating once the left hand becomes stably active too.
+            if (bothStable) {
+                this.transitionTo('rotating');
+                return this.buildOutput(null, null, null);
+            }
             if (desired !== 'zooming') {
                 if (this.releaseTimer === null) {
                     this.releaseTimer = now;
@@ -283,6 +327,13 @@ export class GestureStateMachine {
         this.mode = next;
         this.releaseTimer = null;
         this.actionDwell = null;
+        // Reset both counters so escalation requires a fresh stable run in the new mode.
+        // Exception: keep the dominant hand's counter when entering a single-hand mode so
+        // it does not need to re-accumulate from zero if the hand was already stable.
+        if (next !== 'panning' && next !== 'rotating')
+            this.leftActiveFrames = 0;
+        if (next !== 'zooming' && next !== 'rotating')
+            this.rightActiveFrames = 0;
         if (next !== 'panning') {
             this.panSmoother.reset();
             this.prevPanPos = null;
@@ -303,3 +354,9 @@ export class GestureStateMachine {
         this.transitionTo('idle');
     }
 }
+Object.defineProperty(GestureStateMachine, "ESCALATION_FRAMES", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: 3
+});

package/dist/GestureStateMachine.test.js

@@ -43,10 +43,20 @@ function enterZooming(fsm, right = makeHand('fist')) {
     fsm.update(makeFrame(0, null, right));
 }
 /**
- * Drive the FSM into 'rotating' with dwell=0 (requires two identical frames).
+ * Drive the FSM into 'rotating' with dwell=0.
+ * Requires ESCALATION_FRAMES (3) consecutive both-active frames, then one
+ * more for the dwell to fire (dwell=0 means it fires on the frame that meets
+ * the threshold, so 3 stable frames + 1 dwell frame = 4 total).
  * Rotate = both fists.
  */
 function enterRotating(fsm, left = makeHand('fist'), right = makeHand('fist')) {
+    // Frame 1: both active, dwell timer starts (idle branch, no transition yet).
+    // Frame 2: dwell fires → transitionTo('zooming'), resets leftActiveFrames to 0.
+    // Frames 3-5: leftActiveFrames counts 1 → 2 → 3 (= ESCALATION_FRAMES).
+    // Frame 5: bothStable=true → zooming branch escalates to rotating.
+    fsm.update(makeFrame(0, left, right));
+    fsm.update(makeFrame(0, left, right));
+    fsm.update(makeFrame(0, left, right));
     fsm.update(makeFrame(0, left, right));
     fsm.update(makeFrame(0, left, right));
 }
@@ -75,21 +85,37 @@ describe('GestureStateMachine', () => {
         expect(out.mode).toBe('zooming');
     });
     // ── idle → rotating ────────────────────────────────────────────────────────
-    it('transitions to rotating when both fists are held (two frames, dwell=0)', () => {
+    it('transitions to rotating when both fists are held stably (5 frames: dwell + 3 escalation)', () => {
         const left = makeHand('fist');
         const right = makeHand('fist');
         fsm.update(makeFrame(0, left, right));
+        fsm.update(makeFrame(0, left, right));
+        fsm.update(makeFrame(0, left, right));
+        fsm.update(makeFrame(0, left, right));
         const out = fsm.update(makeFrame(0, left, right));
         expect(out.mode).toBe('rotating');
     });
-    it('prefers rotating over zooming when both fists are held', () => {
+    it('prefers rotating over zooming once both fists are held stably', () => {
         const left = makeHand('fist');
         const right = makeHand('fist');
         fsm.update(makeFrame(0, left, right));
+        fsm.update(makeFrame(0, left, right));
+        fsm.update(makeFrame(0, left, right));
+        fsm.update(makeFrame(0, left, right));
         const out = fsm.update(makeFrame(0, left, right));
-        // both fists = rotating, not zooming
+        // both fists stable for ESCALATION_FRAMES = rotating, not zooming
         expect(out.mode).toBe('rotating');
     });
+    it('does NOT transition to rotating if second hand only appears for 1-2 frames (noise guard)', () => {
+        const left = makeHand('fist');
+        const right = makeHand('fist');
+        // Only 2 frames with both hands — below ESCALATION_FRAMES threshold
+        fsm.update(makeFrame(0, left, null)); // establish left pan
+        fsm.update(makeFrame(0, left, null)); // → panning
+        fsm.update(makeFrame(1, left, right)); // right appears — 1 frame, not stable yet
+        const out = fsm.update(makeFrame(1, left, right)); // 2 frames — still below threshold
+        expect(out.mode).toBe('panning');
+    });
     // ── panning → idle ─────────────────────────────────────────────────────────
     it('returns to idle when the left fist is released (releaseGraceMs=0)', () => {
         enterPanning(fsm);
@@ -173,10 +199,12 @@ describe('GestureStateMachine', () => {
     });
     // ── rotateDelta output ─────────────────────────────────────────────────────
     it('emits no rotateDelta on the first rotating frame', () => {
-        const left = makeHand('fist');
-        const right = makeHand('fist');
-        fsm.update(makeFrame(0, left, right));
-        const out = fsm.update(makeFrame(0, left, right)); // enters rotating, sets prevRotateAngle
+        // enterRotating drives into rotating mode (5 frames); the escalation frame
+        // itself returns null (no prevAngle yet). The *next* frame sets prevAngle,
+        // still no delta. Only the frame after that can emit a delta.
+        enterRotating(fsm);
+        // First full frame inside rotating — sets prevRotateAngle, no delta yet
+        const out = fsm.update(makeFrame(1, makeHand('fist'), makeHand('fist')));
         expect(out.rotateDelta).toBeNull();
     });
     it('emits rotateDelta once a previous angle is established', () => {
@@ -186,9 +214,13 @@ describe('GestureStateMachine', () => {
         // Tilt clockwise: right wrist drops, left wrist rises → angle increases
         const lmL2 = makeLandmarks({ [LANDMARKS.WRIST]: { x: 0.2, y: 0.4, z: 0 } });
         const lmR2 = makeLandmarks({ [LANDMARKS.WRIST]: { x: 0.8, y: 0.6, z: 0 } });
-        fsm.update(makeFrame(0, makeHand('fist', lmL1), makeHand('fist', lmR1)));
-        fsm.update(makeFrame(0, makeHand('fist', lmL1), makeHand('fist', lmR1)));
+        // Get into rotating mode (5 frames with lmL1/lmR1)
+        for (let i = 0; i < 5; i++) {
+            fsm.update(makeFrame(0, makeHand('fist', lmL1), makeHand('fist', lmR1)));
+        }
+        // First frame inside rotating: sets prevRotateAngle, no delta
         fsm.update(makeFrame(1, makeHand('fist', lmL1), makeHand('fist', lmR1)));
+        // Second frame: emits delta
         const out = fsm.update(makeFrame(2, makeHand('fist', lmL2), makeHand('fist', lmR2)));
         expect(out.mode).toBe('rotating');
         expect(out.rotateDelta).not.toBeNull();

package/dist/constants.d.ts

@@ -13,6 +13,8 @@ export declare const LANDMARKS: {
     readonly PINKY_TIP: 20;
     readonly PINKY_MCP: 17;
 };
+export declare const PINCH_THRESHOLD = 0.25;
+export declare const PINCH_RELEASE_THRESHOLD = 0.35;
 export declare const FINGERTIP_INDICES: readonly [8, 12, 16, 20];
 export declare const FINGER_BASE_INDICES: readonly [5, 9, 13, 17];
 export declare const COLORS: {

package/dist/constants.js

@@ -29,6 +29,12 @@ export const LANDMARKS = {
     PINKY_TIP: 20,
     PINKY_MCP: 17,
 };
+// Pinch detection thresholds as a fraction of hand size.
+// Hysteresis: enter pinch at PINCH_THRESHOLD, exit (release) at PINCH_RELEASE_THRESHOLD.
+// The wider release threshold prevents the classifier from flickering between
+// 'pinch' and 'none' when the fingers hover at the edge of the enter threshold.
+export const PINCH_THRESHOLD = 0.25;
+export const PINCH_RELEASE_THRESHOLD = 0.35;
 // Fingertip indices for open-palm detection
 export const FINGERTIP_INDICES = [
     LANDMARKS.INDEX_TIP,

package/dist/gestureClassifier.d.ts

@@ -14,9 +14,24 @@ export declare function getTwoHandDistance(landmarksA: HandLandmark[], landmarks
 /**
  * Classify the gesture for a single hand from its landmarks.
  *
- * Priority: fist > openPalm > none
+ * Priority: fist > pinch > openPalm > none
  *
- * Fist: most fingers curled
- * Open palm: all fingers extended
+ * Fist:      most fingers curled
+ * Pinch:     thumb tip and index tip close together
+ * Open palm: all fingers extended and spread
+ *
+ * NOTE: This stateless version has no pinch hysteresis. Use `createHandClassifier`
+ * for a stateful per-hand classifier that prevents pinch flickering.
  */
 export declare function classifyGesture(landmarks: HandLandmark[]): GestureType;
+/**
+ * Returns a stateful classify function for a single hand.
+ *
+ * Pinch uses hysteresis: the hand enters 'pinch' when tips are within
+ * PINCH_THRESHOLD of hand size, and stays in 'pinch' until tips separate
+ * beyond PINCH_RELEASE_THRESHOLD. This prevents rapid toggling when fingers
+ * hover at the entry threshold during a held pinch gesture.
+ *
+ * Use one instance per hand (left / right) and reset between hand sessions.
+ */
+export declare function createHandClassifier(): (landmarks: HandLandmark[]) => GestureType;

package/dist/gestureClassifier.js

@@ -1,4 +1,4 @@
-import { LANDMARKS, FINGERTIP_INDICES, FINGER_BASE_INDICES } from './constants.js';
+import { LANDMARKS, FINGERTIP_INDICES, FINGER_BASE_INDICES, PINCH_THRESHOLD, PINCH_RELEASE_THRESHOLD } from './constants.js';
 /**
  * Euclidean distance between two landmarks (ignoring Z).
  */
@@ -89,13 +89,42 @@ export function getTwoHandDistance(landmarksA, landmarksB) {
         return 0;
     return dist(tipA, tipB);
 }
+/**
+ * Stateless pinch check used only as the entry condition.
+ * Returns true when thumb tip and index tip are within PINCH_THRESHOLD of hand size.
+ */
+function isPinchEnter(landmarks) {
+    const handSize = getHandSize(landmarks);
+    if (handSize === 0)
+        return false;
+    const thumbTip = landmarks[LANDMARKS.THUMB_TIP];
+    const indexTip = landmarks[LANDMARKS.INDEX_TIP];
+    return dist(thumbTip, indexTip) < handSize * PINCH_THRESHOLD;
+}
+/**
+ * Returns true when thumb tip and index tip are still within PINCH_RELEASE_THRESHOLD.
+ * Used as the exit condition to implement hysteresis: once pinching, we stay in
+ * 'pinch' until the fingers open wider than the release threshold.
+ */
+function isPinchHeld(landmarks) {
+    const handSize = getHandSize(landmarks);
+    if (handSize === 0)
+        return false;
+    const thumbTip = landmarks[LANDMARKS.THUMB_TIP];
+    const indexTip = landmarks[LANDMARKS.INDEX_TIP];
+    return dist(thumbTip, indexTip) < handSize * PINCH_RELEASE_THRESHOLD;
+}
 /**
  * Classify the gesture for a single hand from its landmarks.
  *
- * Priority: fist > openPalm > none
+ * Priority: fist > pinch > openPalm > none
+ *
+ * Fist:      most fingers curled
+ * Pinch:     thumb tip and index tip close together
+ * Open palm: all fingers extended and spread
  *
- * Fist: most fingers curled
- * Open palm: all fingers extended
+ * NOTE: This stateless version has no pinch hysteresis. Use `createHandClassifier`
+ * for a stateful per-hand classifier that prevents pinch flickering.
  */
 export function classifyGesture(landmarks) {
     if (landmarks.length < 21)
@@ -103,8 +132,48 @@ export function classifyGesture(landmarks) {
     if (areAllFingersCurled(landmarks)) {
         return 'fist';
     }
+    if (isPinchEnter(landmarks)) {
+        return 'pinch';
+    }
     if (areAllFingersExtended(landmarks)) {
         return 'openPalm';
     }
     return 'none';
 }
+/**
+ * Returns a stateful classify function for a single hand.
+ *
+ * Pinch uses hysteresis: the hand enters 'pinch' when tips are within
+ * PINCH_THRESHOLD of hand size, and stays in 'pinch' until tips separate
+ * beyond PINCH_RELEASE_THRESHOLD. This prevents rapid toggling when fingers
+ * hover at the entry threshold during a held pinch gesture.
+ *
+ * Use one instance per hand (left / right) and reset between hand sessions.
+ */
+export function createHandClassifier() {
+    let pinching = false;
+    return function classify(landmarks) {
+        if (landmarks.length < 21) {
+            pinching = false;
+            return 'none';
+        }
+        if (areAllFingersCurled(landmarks)) {
+            pinching = false;
+            return 'fist';
+        }
+        // Hysteresis: enter pinch on PINCH_THRESHOLD, exit on PINCH_RELEASE_THRESHOLD.
+        if (pinching) {
+            pinching = isPinchHeld(landmarks);
+        }
+        else {
+            pinching = isPinchEnter(landmarks);
+        }
+        if (pinching) {
+            return 'pinch';
+        }
+        if (areAllFingersExtended(landmarks)) {
+            return 'openPalm';
+        }
+        return 'none';
+    };
+}

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export { GestureController } from './GestureController.js';
 export { GestureStateMachine } from './GestureStateMachine.js';
 export type { StateMachineOutput } from './GestureStateMachine.js';
 export { WebcamOverlay } from './WebcamOverlay.js';
-export { classifyGesture, getHandSize, getTwoHandDistance } from './gestureClassifier.js';
+export { classifyGesture, createHandClassifier, getHandSize, getTwoHandDistance } from './gestureClassifier.js';
 export type { GestureMode, GestureType, HandednessLabel, GestureFrame, DetectedHand, WebcamConfig, TuningConfig, SmoothedPoint, Point2D, HandLandmark, } from './types.js';
 export { DEFAULT_WEBCAM_CONFIG, DEFAULT_TUNING_CONFIG, LANDMARKS, COLORS, } from './constants.js';

package/dist/index.js

@@ -1,15 +1,15 @@
-var E = Object.defineProperty;
-var M = (o, t, e) => t in o ? E(o, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : o[t] = e;
-var l = (o, t, e) => M(o, typeof t != "symbol" ? t + "" : t, e);
-import { FilesetResolver as C } from "@mediapipe/tasks-vision";
-const L = {
+var O = Object.defineProperty;
+var x = (i, t, e) => t in i ? O(i, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : i[t] = e;
+var l = (i, t, e) => x(i, typeof t != "symbol" ? t + "" : t, e);
+import { FilesetResolver as H } from "@mediapipe/tasks-vision";
+const Y = {
   enabled: !0,
   mode: "corner",
   opacity: 0.85,
   position: "bottom-right",
   width: 320,
   height: 240
-}, H = {
+}, Z = {
   actionDwellMs: 80,
   releaseGraceMs: 150,
   panDeadzonePx: 10,
@@ -29,17 +29,17 @@ const L = {
   RING_MCP: 13,
   PINKY_TIP: 20,
   PINKY_MCP: 17
-}, P = [
+}, L = 0.25, z = 0.35, E = [
   r.INDEX_TIP,
   r.MIDDLE_TIP,
   r.RING_TIP,
   r.PINKY_TIP
-], b = [
+], _ = [
   r.INDEX_MCP,
   r.MIDDLE_MCP,
   r.RING_MCP,
   r.PINKY_MCP
-], y = {
+], D = {
   idle: "#888888",
   panning: "#00ccff",
   zooming: "#00ffcc",
@@ -47,49 +47,67 @@ const L = {
   landmark: "rgba(255,255,255,0.6)",
   connection: "rgba(255,255,255,0.3)",
   fingertipGlow: "#4488ff"
-}, _ = "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.14/wasm";
-function T(o, t) {
-  const e = o.x - t.x, i = o.y - t.y;
-  return Math.sqrt(e * e + i * i);
+}, G = "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.14/wasm";
+function T(i, t) {
+  const e = i.x - t.x, n = i.y - t.y;
+  return Math.sqrt(e * e + n * n);
 }
-function N(o) {
-  const t = o[r.WRIST];
-  for (let n = 0; n < P.length; n++) {
-    const d = o[P[n]], c = o[b[n]];
-    if (T(d, t) < T(c, t) * 0.9)
+function N(i) {
+  const t = i[r.WRIST];
+  for (let s = 0; s < E.length; s++) {
+    const u = i[E[s]], c = i[_[s]];
+    if (T(u, t) < T(c, t) * 0.9)
       return !1;
   }
-  const e = x(o);
+  const e = w(i);
   if (e === 0) return !1;
-  const i = P.map((n) => o[n]);
-  let s = 1 / 0;
-  for (let n = 0; n < i.length - 1; n++) {
-    const d = T(i[n], i[n + 1]);
-    d < s && (s = d);
+  const n = E.map((s) => i[s]);
+  let o = 1 / 0;
+  for (let s = 0; s < n.length - 1; s++) {
+    const u = T(n[s], n[s + 1]);
+    u < o && (o = u);
   }
-  return s >= e * 0.18;
+  return o >= e * 0.18;
 }
-function S(o) {
-  const t = o[r.WRIST];
+function R(i) {
+  const t = i[r.WRIST];
   let e = 0;
-  for (let i = 0; i < P.length; i++) {
-    const s = o[P[i]], a = o[b[i]];
-    T(s, t) < T(a, t) * 1.1 && e++;
+  for (let n = 0; n < E.length; n++) {
+    const o = i[E[n]], a = i[_[n]];
+    T(o, t) < T(a, t) * 1.1 && e++;
   }
   return e >= 3;
 }
-function x(o) {
-  const t = o[r.WRIST], e = o[r.MIDDLE_MCP];
+function w(i) {
+  const t = i[r.WRIST], e = i[r.MIDDLE_MCP];
   return !t || !e ? 0 : T(t, e);
 }
-function k(o, t) {
-  const e = o[r.INDEX_TIP], i = t[r.INDEX_TIP];
-  return !e || !i ? 0 : T(e, i);
+function j(i, t) {
+  const e = i[r.INDEX_TIP], n = t[r.INDEX_TIP];
+  return !e || !n ? 0 : T(e, n);
 }
-function R(o) {
-  return o.length < 21 ? "none" : S(o) ? "fist" : N(o) ? "openPalm" : "none";
+function F(i) {
+  const t = w(i);
+  if (t === 0) return !1;
+  const e = i[r.THUMB_TIP], n = i[r.INDEX_TIP];
+  return T(e, n) < t * L;
 }
-class B {
+function B(i) {
+  const t = w(i);
+  if (t === 0) return !1;
+  const e = i[r.THUMB_TIP], n = i[r.INDEX_TIP];
+  return T(e, n) < t * z;
+}
+function k(i) {
+  return i.length < 21 ? "none" : R(i) ? "fist" : F(i) ? "pinch" : N(i) ? "openPalm" : "none";
+}
+function C() {
+  let i = !1;
+  return function(e) {
+    return e.length < 21 ? (i = !1, "none") : R(e) ? (i = !1, "fist") : (i ? i = B(e) : i = F(e), i ? "pinch" : N(e) ? "openPalm" : "none");
+  };
+}
+class $ {
   constructor(t, e) {
     l(this, "landmarker", null);
     l(this, "videoEl", null);
@@ -99,6 +117,9 @@ class B {
     l(this, "onFrame");
     l(this, "tuning");
     l(this, "lastVideoTime", -1);
+    // One stateful classifier per hand label; persists pinch hysteresis across frames.
+    l(this, "leftClassifier", C());
+    l(this, "rightClassifier", C());
     this.tuning = t, this.onFrame = e;
   }
   /**
@@ -106,7 +127,7 @@ class B {
    * Returns the video element so the overlay can render it.
    */
   async init() {
-    const t = await C.forVisionTasks(_), { HandLandmarker: e } = await import("@mediapipe/tasks-vision");
+    const t = await H.forVisionTasks(G), { HandLandmarker: e } = await import("@mediapipe/tasks-vision");
     return this.landmarker = await e.createFromOptions(t, {
       baseOptions: {
         modelAssetPath: "https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task",
@@ -119,8 +140,8 @@ class B {
       minTrackingConfidence: this.tuning.minTrackingConfidence
     }), this.videoEl = document.createElement("video"), this.videoEl.setAttribute("playsinline", ""), this.videoEl.setAttribute("autoplay", ""), this.videoEl.muted = !0, this.videoEl.width = 640, this.videoEl.height = 480, this.stream = await navigator.mediaDevices.getUserMedia({
       video: { width: 640, height: 480, facingMode: "user" }
-    }), this.videoEl.srcObject = this.stream, await new Promise((i) => {
-      this.videoEl.addEventListener("loadeddata", () => i(), { once: !0 });
+    }), this.videoEl.srcObject = this.stream, await new Promise((n) => {
+      this.videoEl.addEventListener("loadeddata", () => n(), { once: !0 });
     }), this.videoEl;
   }
   start() {
@@ -131,7 +152,7 @@ class B {
   }
   destroy() {
     var t, e;
-    this.stop(), (t = this.stream) == null || t.getTracks().forEach((i) => i.stop()), (e = this.landmarker) == null || e.close(), this.landmarker = null, this.videoEl = null, this.stream = null;
+    this.stop(), (t = this.stream) == null || t.getTracks().forEach((n) => n.stop()), (e = this.landmarker) == null || e.close(), this.landmarker = null, this.videoEl = null, this.stream = null;
   }
   loop() {
     this.running && (this.rafHandle = requestAnimationFrame(() => this.loop()), this.processFrame());
@@ -139,31 +160,31 @@ class B {
   processFrame() {
     const t = this.videoEl, e = this.landmarker;
     if (!t || !e || t.readyState < 2) return;
-    const i = performance.now();
+    const n = performance.now();
     if (t.currentTime === this.lastVideoTime) return;
     this.lastVideoTime = t.currentTime;
-    let s;
+    let o;
     try {
-      s = e.detectForVideo(t, i);
+      o = e.detectForVideo(t, n);
     } catch {
       return;
     }
-    const a = this.buildFrame(s, i);
+    const a = this.buildFrame(o, n);
     this.onFrame(a);
   }
   buildFrame(t, e) {
-    const i = t.landmarks.map((n, d) => {
-      var p, g;
-      const c = t.handedness[d], h = ((p = c == null ? void 0 : c[0]) == null ? void 0 : p.categoryName) === "Left" ? "Left" : "Right", m = ((g = c == null ? void 0 : c[0]) == null ? void 0 : g.score) ?? 0, f = R(n);
-      return { handedness: h, score: m, landmarks: n, gesture: f };
-    }), s = i.find((n) => n.handedness === "Left") ?? null, a = i.find((n) => n.handedness === "Right") ?? null;
-    return { timestamp: e, hands: i, leftHand: s, rightHand: a };
+    const n = t.landmarks.map((s, u) => {
+      var m, p;
+      const c = t.handedness[u], d = ((m = c == null ? void 0 : c[0]) == null ? void 0 : m.categoryName) === "Left" ? "Left" : "Right", P = ((p = c == null ? void 0 : c[0]) == null ? void 0 : p.score) ?? 0, f = (d === "Left" ? this.leftClassifier : this.rightClassifier)(s);
+      return { handedness: d, score: P, landmarks: s, gesture: f };
+    }), o = n.find((s) => s.handedness === "Left") ?? null, a = n.find((s) => s.handedness === "Right") ?? null;
+    return { timestamp: e, hands: n, leftHand: o, rightHand: a };
   }
   getVideoElement() {
     return this.videoEl;
   }
 }
-class A {
+class U {
   constructor(t) {
     l(this, "value", null);
     this.alpha = t;
@@ -178,7 +199,7 @@ class A {
     this.value = null;
   }
 }
-class D {
+class M {
   constructor(t) {
     l(this, "value", null);
     this.alpha = t;
@@ -190,7 +211,7 @@ class D {
     this.value = null;
   }
 }
-class U {
+const y = class y {
   constructor(t) {
     l(this, "mode", "idle");
     l(this, "actionDwell", null);
@@ -201,69 +222,83 @@ class U {
     l(this, "prevZoomDist", null);
     l(this, "rotateSmoother");
     l(this, "prevRotateAngle", null);
-    this.tuning = t, this.panSmoother = new A(t.smoothingAlpha), this.zoomSmoother = new D(t.smoothingAlpha), this.rotateSmoother = new D(t.smoothingAlpha);
+    // Tracks how many consecutive frames each hand has been active.
+    // Used to require the secondary hand to be stable before escalating
+    // the mode (e.g. pan → rotate), preventing a single noisy frame from
+    // interrupting an ongoing single-hand gesture.
+    l(this, "leftActiveFrames", 0);
+    l(this, "rightActiveFrames", 0);
+    this.tuning = t, this.panSmoother = new U(t.smoothingAlpha), this.zoomSmoother = new M(t.smoothingAlpha), this.rotateSmoother = new M(t.smoothingAlpha);
   }
   getMode() {
     return this.mode;
   }
   update(t) {
-    const e = t.timestamp, { actionDwellMs: i, releaseGraceMs: s } = this.tuning, { leftHand: a, rightHand: n } = t, d = n !== null && n.gesture === "fist", c = a !== null && a.gesture === "fist", h = d && c ? "rotating" : d ? "zooming" : c ? "panning" : "idle";
+    const e = t.timestamp, { actionDwellMs: n, releaseGraceMs: o } = this.tuning, { leftHand: a, rightHand: s } = t, u = (f) => f !== null && (f.gesture === "fist" || f.gesture === "pinch"), c = u(s), h = u(a);
+    this.leftActiveFrames = h ? this.leftActiveFrames + 1 : 0, this.rightActiveFrames = c ? this.rightActiveFrames + 1 : 0;
+    const d = this.leftActiveFrames >= y.ESCALATION_FRAMES && this.rightActiveFrames >= y.ESCALATION_FRAMES, g = d ? "rotating" : h && c && !d && (this.mode === "panning" || this.mode === "zooming") ? this.mode : c ? "zooming" : h ? "panning" : "idle";
     if (this.mode === "idle")
-      return h !== "idle" ? this.actionDwell === null || this.actionDwell.gesture !== h ? this.actionDwell = { gesture: h, startMs: e } : e - this.actionDwell.startMs >= i && this.transitionTo(h) : this.actionDwell = null, this.buildOutput(null, null, null);
+      return g !== "idle" ? this.actionDwell === null || this.actionDwell.gesture !== g ? this.actionDwell = { gesture: g, startMs: e } : e - this.actionDwell.startMs >= n && this.transitionTo(g) : this.actionDwell = null, this.buildOutput(null, null, null);
     if (this.mode === "panning") {
-      if (h !== "panning")
-        return this.releaseTimer === null ? this.releaseTimer = e : e - this.releaseTimer >= s && this.transitionTo("idle"), this.buildOutput(null, null, null);
+      if (d)
+        return this.transitionTo("rotating"), this.buildOutput(null, null, null);
+      if (g !== "panning")
+        return this.releaseTimer === null ? this.releaseTimer = e : e - this.releaseTimer >= o && this.transitionTo("idle"), this.buildOutput(null, null, null);
       this.releaseTimer = null;
-      const m = (a == null ? void 0 : a.gesture) === "fist" ? a : null;
-      if (!m)
+      const f = u(a) ? a : null;
+      if (!f)
         return this.transitionTo("idle"), this.buildOutput(null, null, null);
-      const f = m.landmarks[0], p = this.panSmoother.update(f.x, f.y);
-      let g = null;
+      const m = f.landmarks[0], p = this.panSmoother.update(m.x, m.y);
+      let I = null;
       if (this.prevPanPos !== null) {
-        const I = p.x - this.prevPanPos.x, v = p.y - this.prevPanPos.y, w = this.tuning.panDeadzonePx / 640;
-        (Math.abs(I) > w || Math.abs(v) > w) && (g = { x: I, y: v });
+        const b = p.x - this.prevPanPos.x, v = p.y - this.prevPanPos.y, A = this.tuning.panDeadzonePx / 640;
+        (Math.abs(b) > A || Math.abs(v) > A) && (I = { x: b, y: v });
       }
-      return this.prevPanPos = p, this.buildOutput(g, null, null);
+      return this.prevPanPos = p, this.buildOutput(I, null, null);
     }
     if (this.mode === "zooming") {
-      if (h !== "zooming")
-        return this.releaseTimer === null ? this.releaseTimer = e : e - this.releaseTimer >= s && this.transitionTo("idle"), this.buildOutput(null, null, null);
-      if (this.releaseTimer = null, !n)
+      if (d)
+        return this.transitionTo("rotating"), this.buildOutput(null, null, null);
+      if (g !== "zooming")
+        return this.releaseTimer === null ? this.releaseTimer = e : e - this.releaseTimer >= o && this.transitionTo("idle"), this.buildOutput(null, null, null);
+      if (this.releaseTimer = null, !s)
         return this.transitionTo("idle"), this.buildOutput(null, null, null);
-      const m = n.landmarks[0], f = this.zoomSmoother.update(m.y);
+      const f = s.landmarks[0], m = this.zoomSmoother.update(f.y);
       let p = null;
       if (this.prevZoomDist !== null) {
-        const g = f - this.prevZoomDist;
-        Math.abs(g) > this.tuning.zoomDeadzoneRatio && (p = -g);
+        const I = m - this.prevZoomDist;
+        Math.abs(I) > this.tuning.zoomDeadzoneRatio && (p = -I);
       }
-      return this.prevZoomDist = f, this.buildOutput(null, p, null);
+      return this.prevZoomDist = m, this.buildOutput(null, p, null);
     }
     if (this.mode === "rotating") {
-      if (h !== "rotating")
-        return this.releaseTimer === null ? this.releaseTimer = e : e - this.releaseTimer >= s && this.transitionTo("idle"), this.buildOutput(null, null, null);
-      if (this.releaseTimer = null, !a || !n)
+      if (g !== "rotating")
+        return this.releaseTimer === null ? this.releaseTimer = e : e - this.releaseTimer >= o && this.transitionTo("idle"), this.buildOutput(null, null, null);
+      if (this.releaseTimer = null, !a || !s)
         return this.transitionTo("idle"), this.buildOutput(null, null, null);
-      const m = a.landmarks[0], f = n.landmarks[0], p = Math.atan2(f.y - m.y, f.x - m.x), g = this.rotateSmoother.update(p);
-      let I = null;
+      const f = a.landmarks[0], m = s.landmarks[0], p = Math.atan2(m.y - f.y, m.x - f.x), I = this.rotateSmoother.update(p);
+      let b = null;
       if (this.prevRotateAngle !== null) {
-        let v = g - this.prevRotateAngle;
-        v > Math.PI && (v -= 2 * Math.PI), v < -Math.PI && (v += 2 * Math.PI), Math.abs(v) > 5e-3 && (I = v);
+        let v = I - this.prevRotateAngle;
+        v > Math.PI && (v -= 2 * Math.PI), v < -Math.PI && (v += 2 * Math.PI), Math.abs(v) > 5e-3 && (b = v);
       }
-      return this.prevRotateAngle = g, this.buildOutput(null, null, I);
+      return this.prevRotateAngle = I, this.buildOutput(null, null, b);
     }
     return this.buildOutput(null, null, null);
   }
   transitionTo(t) {
-    this.mode = t, this.releaseTimer = null, this.actionDwell = null, t !== "panning" && (this.panSmoother.reset(), this.prevPanPos = null), t !== "zooming" && (this.zoomSmoother.reset(), this.prevZoomDist = null), t !== "rotating" && (this.rotateSmoother.reset(), this.prevRotateAngle = null);
+    this.mode = t, this.releaseTimer = null, this.actionDwell = null, t !== "panning" && t !== "rotating" && (this.leftActiveFrames = 0), t !== "zooming" && t !== "rotating" && (this.rightActiveFrames = 0), t !== "panning" && (this.panSmoother.reset(), this.prevPanPos = null), t !== "zooming" && (this.zoomSmoother.reset(), this.prevZoomDist = null), t !== "rotating" && (this.rotateSmoother.reset(), this.prevRotateAngle = null);
   }
-  buildOutput(t, e, i) {
-    return { mode: this.mode, panDelta: t, zoomDelta: e, rotateDelta: i };
+  buildOutput(t, e, n) {
+    return { mode: this.mode, panDelta: t, zoomDelta: e, rotateDelta: n };
   }
   reset() {
     this.transitionTo("idle");
   }
-}
-const F = [
+};
+l(y, "ESCALATION_FRAMES", 3);
+let S = y;
+const X = [
   [0, 1],
   [1, 2],
   [2, 3],
@@ -293,14 +328,14 @@ const F = [
   [9, 13],
   [13, 17]
   // palm cross
-], O = [
+], V = [
   r.THUMB_TIP,
   r.INDEX_TIP,
   r.MIDDLE_TIP,
   r.RING_TIP,
   r.PINKY_TIP
 ];
-class V {
+class q {
   constructor(t) {
     l(this, "container");
     l(this, "canvas");
@@ -327,19 +362,19 @@ class V {
   /** Called each frame with the latest gesture frame and mode. */
   render(t, e) {
     this.updateBadge(e);
-    const i = this.config.width, s = this.config.height;
-    if (this.canvas.width = i, this.canvas.height = s, this.ctx.clearRect(0, 0, i, s), t !== null)
+    const n = this.config.width, o = this.config.height;
+    if (this.canvas.width = n, this.canvas.height = o, this.ctx.clearRect(0, 0, n, o), t !== null)
       for (const a of t.hands)
         this.drawSkeleton(a.landmarks, e, a.gesture === "fist");
   }
-  drawSkeleton(t, e, i) {
-    const { ctx: s } = this, a = this.config.width, n = this.config.height, d = (u) => (1 - u.x) * a, c = (u) => u.y * n;
-    s.strokeStyle = y.connection, s.lineWidth = 1.5;
-    for (const [u, h] of F)
-      !t[u] || !t[h] || (s.beginPath(), s.moveTo(d(t[u]), c(t[u])), s.lineTo(d(t[h]), c(t[h])), s.stroke());
-    for (let u = 0; u < t.length; u++) {
-      const h = t[u], m = O.includes(u), f = e !== "idle" && m ? y.fingertipGlow : y.landmark;
-      s.beginPath(), s.arc(d(h), c(h), m ? 5 : 3, 0, Math.PI * 2), s.fillStyle = f, s.fill(), e !== "idle" && m && (s.shadowBlur = i ? 12 : 6, s.shadowColor = y.fingertipGlow, s.fill(), s.shadowBlur = 0);
+  drawSkeleton(t, e, n) {
+    const { ctx: o } = this, a = this.config.width, s = this.config.height, u = (h) => (1 - h.x) * a, c = (h) => h.y * s;
+    o.strokeStyle = D.connection, o.lineWidth = 1.5;
+    for (const [h, d] of X)
+      !t[h] || !t[d] || (o.beginPath(), o.moveTo(u(t[h]), c(t[h])), o.lineTo(u(t[d]), c(t[d])), o.stroke());
+    for (let h = 0; h < t.length; h++) {
+      const d = t[h], P = V.includes(h), g = e !== "idle" && P ? D.fingertipGlow : D.landmark;
+      o.beginPath(), o.arc(u(d), c(d), P ? 5 : 3, 0, Math.PI * 2), o.fillStyle = g, o.fill(), e !== "idle" && P && (o.shadowBlur = n ? 12 : 6, o.shadowColor = D.fingertipGlow, o.fill(), o.shadowBlur = 0);
     }
   }
   updateBadge(t) {
@@ -352,11 +387,11 @@ class V {
     this.badge.textContent = e[t], this.badge.className = `ol-gesture-badge ol-gesture-badge--${t}`;
   }
   applyContainerStyles() {
-    const { mode: t, position: e, width: i, height: s, opacity: a } = this.config;
+    const { mode: t, position: e, width: n, height: o, opacity: a } = this.config;
     if (this.container.style.cssText = "", this.container.style.position = "fixed", this.container.style.zIndex = "9999", this.container.style.overflow = "hidden", this.container.style.borderRadius = "8px", this.container.style.opacity = String(a), this.container.style.display = t === "hidden" ? "none" : "block", t === "corner") {
-      this.container.style.width = `${i}px`, this.container.style.height = `${s}px`;
-      const n = "16px";
-      e === "bottom-right" ? (this.container.style.bottom = n, this.container.style.right = n) : e === "bottom-left" ? (this.container.style.bottom = n, this.container.style.left = n) : e === "top-right" ? (this.container.style.top = n, this.container.style.right = n) : (this.container.style.top = n, this.container.style.left = n);
+      this.container.style.width = `${n}px`, this.container.style.height = `${o}px`;
+      const s = "16px";
+      e === "bottom-right" ? (this.container.style.bottom = s, this.container.style.right = s) : e === "bottom-left" ? (this.container.style.bottom = s, this.container.style.left = s) : e === "top-right" ? (this.container.style.top = s, this.container.style.right = s) : (this.container.style.top = s, this.container.style.left = s);
     } else t === "full" && (this.container.style.top = "0", this.container.style.left = "0", this.container.style.width = "100vw", this.container.style.height = "100vh", this.container.style.borderRadius = "0");
   }
   updateConfig(t) {
@@ -364,14 +399,15 @@ class V {
   }
 }
 export {
-  y as COLORS,
-  H as DEFAULT_TUNING_CONFIG,
-  L as DEFAULT_WEBCAM_CONFIG,
-  B as GestureController,
-  U as GestureStateMachine,
+  D as COLORS,
+  Z as DEFAULT_TUNING_CONFIG,
+  Y as DEFAULT_WEBCAM_CONFIG,
+  $ as GestureController,
+  S as GestureStateMachine,
   r as LANDMARKS,
-  V as WebcamOverlay,
-  R as classifyGesture,
-  x as getHandSize,
-  k as getTwoHandDistance
+  q as WebcamOverlay,
+  k as classifyGesture,
+  C as createHandClassifier,
+  w as getHandSize,
+  j as getTwoHandDistance
 };

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 export type GestureMode = 'idle' | 'panning' | 'zooming' | 'rotating';
 export type HandednessLabel = 'Left' | 'Right';
-export type GestureType = 'openPalm' | 'fist' | 'none';
+export type GestureType = 'openPalm' | 'fist' | 'pinch' | 'none';
 export interface Point2D {
     x: number;
     y: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@map-gesture-controls/core",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Map-agnostic hand gesture detection and state machine (MediaPipe)",
   "type": "module",
   "main": "dist/index.js",