@map-gesture-controls/core 0.1.3

package/dist/GestureController.d.ts

@@ -0,0 +1,32 @@
+import type { GestureFrame, TuningConfig } from './types.js';
+type FrameCallback = (frame: GestureFrame) => void;
+/**
+ * GestureController
+ *
+ * Manages the webcam stream and MediaPipe HandLandmarker inference loop.
+ * Calls `onFrame` with classified hand data every animation frame.
+ */
+export declare class GestureController {
+    private landmarker;
+    private videoEl;
+    private stream;
+    private rafHandle;
+    private running;
+    private onFrame;
+    private tuning;
+    private lastVideoTime;
+    constructor(tuning: TuningConfig, onFrame: FrameCallback);
+    /**
+     * Initialise MediaPipe and request webcam access.
+     * Returns the video element so the overlay can render it.
+     */
+    init(): Promise<HTMLVideoElement>;
+    start(): void;
+    stop(): void;
+    destroy(): void;
+    private loop;
+    private processFrame;
+    private buildFrame;
+    getVideoElement(): HTMLVideoElement | null;
+}
+export {};

package/dist/GestureController.js

@@ -0,0 +1,159 @@
+import { FilesetResolver } from '@mediapipe/tasks-vision';
+import { classifyGesture } from './gestureClassifier.js';
+import { MEDIAPIPE_WASM_URL } from './constants.js';
+/**
+ * GestureController
+ *
+ * Manages the webcam stream and MediaPipe HandLandmarker inference loop.
+ * Calls `onFrame` with classified hand data every animation frame.
+ */
+export class GestureController {
+    constructor(tuning, onFrame) {
+        Object.defineProperty(this, "landmarker", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "videoEl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "stream", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "rafHandle", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "running", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "onFrame", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "tuning", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "lastVideoTime", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: -1
+        });
+        this.tuning = tuning;
+        this.onFrame = onFrame;
+    }
+    /**
+     * Initialise MediaPipe and request webcam access.
+     * Returns the video element so the overlay can render it.
+     */
+    async init() {
+        const vision = await FilesetResolver.forVisionTasks(MEDIAPIPE_WASM_URL);
+        // Dynamic import to avoid bundling issues
+        const { HandLandmarker } = await import('@mediapipe/tasks-vision');
+        this.landmarker = await HandLandmarker.createFromOptions(vision, {
+            baseOptions: {
+                modelAssetPath: 'https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task',
+                delegate: 'GPU',
+            },
+            runningMode: 'VIDEO',
+            numHands: 2,
+            minHandDetectionConfidence: this.tuning.minDetectionConfidence,
+            minHandPresenceConfidence: this.tuning.minPresenceConfidence,
+            minTrackingConfidence: this.tuning.minTrackingConfidence,
+        });
+        this.videoEl = document.createElement('video');
+        this.videoEl.setAttribute('playsinline', '');
+        this.videoEl.setAttribute('autoplay', '');
+        this.videoEl.muted = true;
+        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((resolve) => {
+            this.videoEl.addEventListener('loadeddata', () => resolve(), { once: true });
+        });
+        return this.videoEl;
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.loop();
+    }
+    stop() {
+        this.running = false;
+        if (this.rafHandle !== null) {
+            cancelAnimationFrame(this.rafHandle);
+            this.rafHandle = null;
+        }
+    }
+    destroy() {
+        this.stop();
+        this.stream?.getTracks().forEach((t) => t.stop());
+        this.landmarker?.close();
+        this.landmarker = null;
+        this.videoEl = null;
+        this.stream = null;
+    }
+    loop() {
+        if (!this.running)
+            return;
+        this.rafHandle = requestAnimationFrame(() => this.loop());
+        this.processFrame();
+    }
+    processFrame() {
+        const video = this.videoEl;
+        const landmarker = this.landmarker;
+        if (!video || !landmarker || video.readyState < 2)
+            return;
+        const nowMs = performance.now();
+        if (video.currentTime === this.lastVideoTime)
+            return;
+        this.lastVideoTime = video.currentTime;
+        let result;
+        try {
+            result = landmarker.detectForVideo(video, nowMs);
+        }
+        catch {
+            return;
+        }
+        const frame = this.buildFrame(result, nowMs);
+        this.onFrame(frame);
+    }
+    buildFrame(result, timestamp) {
+        const hands = result.landmarks.map((landmarks, i) => {
+            const handednessArr = result.handedness[i];
+            const rawLabel = handednessArr?.[0]?.categoryName;
+            const label = rawLabel === 'Left' ? 'Left' : 'Right';
+            const score = handednessArr?.[0]?.score ?? 0;
+            const gesture = classifyGesture(landmarks);
+            return { handedness: label, score, landmarks, gesture };
+        });
+        const leftHand = hands.find((h) => h.handedness === 'Left') ?? null;
+        const rightHand = hands.find((h) => h.handedness === 'Right') ?? null;
+        return { timestamp, hands, leftHand, rightHand };
+    }
+    getVideoElement() {
+        return this.videoEl;
+    }
+}

package/dist/GestureStateMachine.d.ts

@@ -0,0 +1,35 @@
+import type { GestureMode, GestureFrame, TuningConfig, SmoothedPoint } from './types.js';
+export interface StateMachineOutput {
+    mode: GestureMode;
+    panDelta: SmoothedPoint | null;
+    zoomDelta: number | null;
+}
+/**
+ * GestureStateMachine — 3-state FSM
+ *
+ * Priority rules (evaluated every frame):
+ *   both hands visible AND both open palm → desired = 'zooming'
+ *   one hand visible AND gesture = 'fist' → desired = 'panning'
+ *   otherwise                             → desired = 'idle'
+ *
+ * Transitions:
+ *   idle → panning/zooming : desired stable for actionDwellMs
+ *   panning/zooming → idle : desired changes, grace period releaseGraceMs,
+ *                            then idle (next frame starts new dwell if needed)
+ */
+export declare class GestureStateMachine {
+    private tuning;
+    private mode;
+    private actionDwell;
+    private releaseTimer;
+    private panSmoother;
+    private prevPanPos;
+    private zoomSmoother;
+    private prevZoomDist;
+    constructor(tuning: TuningConfig);
+    getMode(): GestureMode;
+    update(frame: GestureFrame): StateMachineOutput;
+    private transitionTo;
+    private buildOutput;
+    reset(): void;
+}

package/dist/GestureStateMachine.js

@@ -0,0 +1,243 @@
+import { getTwoHandDistance } from './gestureClassifier.js';
+/**
+ * Exponential Moving Average smoother for 2D points.
+ */
+class EMAPoint {
+    constructor(alpha) {
+        Object.defineProperty(this, "alpha", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: alpha
+        });
+        Object.defineProperty(this, "value", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+    update(x, y) {
+        if (this.value === null) {
+            this.value = { x, y };
+        }
+        else {
+            this.value = {
+                x: this.alpha * x + (1 - this.alpha) * this.value.x,
+                y: this.alpha * y + (1 - this.alpha) * this.value.y,
+            };
+        }
+        return this.value;
+    }
+    reset() {
+        this.value = null;
+    }
+}
+/**
+ * Exponential Moving Average smoother for a scalar value.
+ */
+class EMAScalar {
+    constructor(alpha) {
+        Object.defineProperty(this, "alpha", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: alpha
+        });
+        Object.defineProperty(this, "value", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+    update(v) {
+        if (this.value === null) {
+            this.value = v;
+        }
+        else {
+            this.value = this.alpha * v + (1 - this.alpha) * this.value;
+        }
+        return this.value;
+    }
+    reset() {
+        this.value = null;
+    }
+}
+/**
+ * GestureStateMachine — 3-state FSM
+ *
+ * Priority rules (evaluated every frame):
+ *   both hands visible AND both open palm → desired = 'zooming'
+ *   one hand visible AND gesture = 'fist' → desired = 'panning'
+ *   otherwise                             → desired = 'idle'
+ *
+ * Transitions:
+ *   idle → panning/zooming : desired stable for actionDwellMs
+ *   panning/zooming → idle : desired changes, grace period releaseGraceMs,
+ *                            then idle (next frame starts new dwell if needed)
+ */
+export class GestureStateMachine {
+    constructor(tuning) {
+        Object.defineProperty(this, "tuning", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: tuning
+        });
+        Object.defineProperty(this, "mode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'idle'
+        });
+        Object.defineProperty(this, "actionDwell", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "releaseTimer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "panSmoother", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "prevPanPos", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "zoomSmoother", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "prevZoomDist", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.panSmoother = new EMAPoint(tuning.smoothingAlpha);
+        this.zoomSmoother = new EMAScalar(tuning.smoothingAlpha);
+    }
+    getMode() {
+        return this.mode;
+    }
+    update(frame) {
+        const now = frame.timestamp;
+        const { actionDwellMs, releaseGraceMs } = this.tuning;
+        const { leftHand, rightHand } = frame;
+        // ── Determine desired mode for this frame ─────────────────────────────────
+        const bothOpen = leftHand !== null &&
+            rightHand !== null &&
+            leftHand.gesture === 'openPalm' &&
+            rightHand.gesture === 'openPalm';
+        const oneFist = (leftHand !== null && leftHand.gesture === 'fist' && rightHand === null) ||
+            (rightHand !== null && rightHand.gesture === 'fist' && leftHand === null);
+        const desired = bothOpen ? 'zooming' : oneFist ? 'panning' : 'idle';
+        // ── idle ──────────────────────────────────────────────────────────────────
+        if (this.mode === 'idle') {
+            if (desired !== 'idle') {
+                if (this.actionDwell === null || this.actionDwell.gesture !== desired) {
+                    this.actionDwell = { gesture: desired, startMs: now };
+                }
+                else if (now - this.actionDwell.startMs >= actionDwellMs) {
+                    this.transitionTo(desired);
+                }
+            }
+            else {
+                this.actionDwell = null;
+            }
+            return this.buildOutput(null, null);
+        }
+        // ── panning ───────────────────────────────────────────────────────────────
+        if (this.mode === 'panning') {
+            if (desired !== 'panning') {
+                if (this.releaseTimer === null) {
+                    this.releaseTimer = now;
+                }
+                else if (now - this.releaseTimer >= releaseGraceMs) {
+                    this.transitionTo('idle');
+                }
+                return this.buildOutput(null, null);
+            }
+            this.releaseTimer = null;
+            const fistHand = leftHand?.gesture === 'fist' ? leftHand : rightHand;
+            if (!fistHand) {
+                this.transitionTo('idle');
+                return this.buildOutput(null, null);
+            }
+            const wrist = fistHand.landmarks[0];
+            const smooth = this.panSmoother.update(wrist.x, wrist.y);
+            let panDelta = null;
+            if (this.prevPanPos !== null) {
+                const rawDx = smooth.x - this.prevPanPos.x;
+                const rawDy = smooth.y - this.prevPanPos.y;
+                const deadzone = this.tuning.panDeadzonePx / 640;
+                if (Math.abs(rawDx) > deadzone || Math.abs(rawDy) > deadzone) {
+                    panDelta = { x: rawDx, y: rawDy };
+                }
+            }
+            this.prevPanPos = smooth;
+            return this.buildOutput(panDelta, null);
+        }
+        // ── zooming ───────────────────────────────────────────────────────────────
+        if (this.mode === 'zooming') {
+            if (desired !== 'zooming') {
+                if (this.releaseTimer === null) {
+                    this.releaseTimer = now;
+                }
+                else if (now - this.releaseTimer >= releaseGraceMs) {
+                    this.transitionTo('idle');
+                }
+                return this.buildOutput(null, null);
+            }
+            this.releaseTimer = null;
+            if (!leftHand || !rightHand) {
+                this.transitionTo('idle');
+                return this.buildOutput(null, null);
+            }
+            const rawDist = getTwoHandDistance(leftHand.landmarks, rightHand.landmarks);
+            const smoothDist = this.zoomSmoother.update(rawDist);
+            let zoomDelta = null;
+            if (this.prevZoomDist !== null) {
+                const delta = smoothDist - this.prevZoomDist;
+                if (Math.abs(delta) > this.tuning.zoomDeadzoneRatio) {
+                    zoomDelta = delta;
+                }
+            }
+            this.prevZoomDist = smoothDist;
+            return this.buildOutput(null, zoomDelta);
+        }
+        return this.buildOutput(null, null);
+    }
+    transitionTo(next) {
+        this.mode = next;
+        this.releaseTimer = null;
+        this.actionDwell = null;
+        if (next !== 'panning') {
+            this.panSmoother.reset();
+            this.prevPanPos = null;
+        }
+        if (next !== 'zooming') {
+            this.zoomSmoother.reset();
+            this.prevZoomDist = null;
+        }
+    }
+    buildOutput(panDelta, zoomDelta) {
+        return { mode: this.mode, panDelta, zoomDelta };
+    }
+    reset() {
+        this.transitionTo('idle');
+    }
+}

package/dist/GestureStateMachine.test.d.ts

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

package/dist/GestureStateMachine.test.js

@@ -0,0 +1,163 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { GestureStateMachine } from './GestureStateMachine.js';
+import { LANDMARKS } from './constants.js';
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+const FAST_TUNING = {
+    actionDwellMs: 0, // dwell=0: transition fires on the SECOND frame (first sets timer)
+    releaseGraceMs: 0, // grace=0: idle on the SECOND frame after release
+    panDeadzonePx: 0,
+    zoomDeadzoneRatio: 0,
+    smoothingAlpha: 1, // no smoothing — raw values pass through
+    minDetectionConfidence: 0.65,
+    minTrackingConfidence: 0.65,
+    minPresenceConfidence: 0.60,
+};
+function makeLandmarks(overrides = {}) {
+    const lm = Array.from({ length: 21 }, () => ({ x: 0.5, y: 0.5, z: 0 }));
+    for (const [idx, vals] of Object.entries(overrides)) {
+        lm[Number(idx)] = { ...lm[Number(idx)], ...vals };
+    }
+    return lm;
+}
+function makeHand(gesture, landmarks = makeLandmarks()) {
+    return { handedness: 'Right', score: 1, landmarks, gesture };
+}
+function makeFrame(timestamp, leftHand, rightHand) {
+    const hands = [leftHand, rightHand].filter(Boolean);
+    return { timestamp, hands, leftHand, rightHand };
+}
+/**
+ * Drive the FSM into 'panning' with dwell=0 (requires two identical frames).
+ */
+function enterPanning(fsm, hand = makeHand('fist')) {
+    fsm.update(makeFrame(0, hand, null)); // starts dwell timer
+    fsm.update(makeFrame(0, hand, null)); // dwell elapsed → panning
+}
+/**
+ * Drive the FSM into 'zooming' with dwell=0 (requires two identical frames).
+ */
+function enterZooming(fsm, left = makeHand('openPalm'), right = makeHand('openPalm')) {
+    fsm.update(makeFrame(0, left, right));
+    fsm.update(makeFrame(0, left, right));
+}
+// ─── Tests ────────────────────────────────────────────────────────────────────
+describe('GestureStateMachine', () => {
+    let fsm;
+    beforeEach(() => {
+        fsm = new GestureStateMachine(FAST_TUNING);
+    });
+    // ── Initial state ──────────────────────────────────────────────────────────
+    it('starts in idle mode', () => {
+        expect(fsm.getMode()).toBe('idle');
+    });
+    // ── idle → panning ─────────────────────────────────────────────────────────
+    it('transitions to panning after the dwell elapses (two frames, dwell=0)', () => {
+        const fistHand = makeHand('fist');
+        fsm.update(makeFrame(0, fistHand, null)); // starts dwell
+        const out = fsm.update(makeFrame(0, fistHand, null)); // 0 >= 0 → panning
+        expect(out.mode).toBe('panning');
+    });
+    // ── idle → zooming ─────────────────────────────────────────────────────────
+    it('transitions to zooming when two open palms are held (two frames, dwell=0)', () => {
+        const left = makeHand('openPalm');
+        const right = makeHand('openPalm');
+        fsm.update(makeFrame(0, left, right));
+        const out = fsm.update(makeFrame(0, left, right));
+        expect(out.mode).toBe('zooming');
+    });
+    // ── panning → idle ─────────────────────────────────────────────────────────
+    it('returns to idle when the fist is released (releaseGraceMs=0)', () => {
+        enterPanning(fsm);
+        expect(fsm.getMode()).toBe('panning');
+        fsm.update(makeFrame(1, null, null)); // starts release timer
+        const out = fsm.update(makeFrame(1, null, null)); // 0 >= 0 → idle
+        expect(out.mode).toBe('idle');
+    });
+    // ── zooming → idle ─────────────────────────────────────────────────────────
+    it('returns to idle when open palms are released (releaseGraceMs=0)', () => {
+        enterZooming(fsm);
+        expect(fsm.getMode()).toBe('zooming');
+        fsm.update(makeFrame(1, null, null)); // starts release timer
+        const out = fsm.update(makeFrame(1, null, null)); // 0 >= 0 → idle
+        expect(out.mode).toBe('idle');
+    });
+    // ── panDelta output ────────────────────────────────────────────────────────
+    it('emits no panDelta on the first panning frame (no previous position)', () => {
+        const fistHand = makeHand('fist');
+        fsm.update(makeFrame(0, fistHand, null)); // dwell starts
+        const out = fsm.update(makeFrame(0, fistHand, null)); // enters panning, sets prevPos
+        expect(out.panDelta).toBeNull();
+    });
+    it('emits panDelta once a previous position is established', () => {
+        const wristPos1 = { x: 0.3, y: 0.4, z: 0 };
+        const wristPos2 = { x: 0.35, y: 0.45, z: 0 };
+        const lm1 = makeLandmarks({ [LANDMARKS.WRIST]: wristPos1 });
+        const lm2 = makeLandmarks({ [LANDMARKS.WRIST]: wristPos2 });
+        // Frame 1: start dwell (idle)
+        fsm.update(makeFrame(0, makeHand('fist', lm1), null));
+        // Frame 2: transition fires → panning, but buildOutput returns from idle branch (panDelta=null)
+        fsm.update(makeFrame(0, makeHand('fist', lm1), null));
+        // Frame 3: first real panning frame — sets prevPanPos = wristPos1, no delta yet
+        fsm.update(makeFrame(1, makeHand('fist', lm1), null));
+        // Frame 4: second panning frame — emits delta
+        const out = fsm.update(makeFrame(2, makeHand('fist', lm2), null));
+        expect(out.mode).toBe('panning');
+        expect(out.panDelta).not.toBeNull();
+        expect(out.panDelta.x).toBeCloseTo(wristPos2.x - wristPos1.x);
+        expect(out.panDelta.y).toBeCloseTo(wristPos2.y - wristPos1.y);
+    });
+    // ── zoomDelta output ───────────────────────────────────────────────────────
+    it('emits no zoomDelta on the first zooming frame', () => {
+        const left = makeHand('openPalm');
+        const right = makeHand('openPalm');
+        fsm.update(makeFrame(0, left, right));
+        const out = fsm.update(makeFrame(0, left, right)); // enters zooming, sets prevZoomDist
+        expect(out.zoomDelta).toBeNull();
+    });
+    it('emits zoomDelta once a previous distance is established', () => {
+        const lmL1 = makeLandmarks({ [LANDMARKS.INDEX_TIP]: { x: 0.4, y: 0.5, z: 0 } });
+        const lmR1 = makeLandmarks({ [LANDMARKS.INDEX_TIP]: { x: 0.6, y: 0.5, z: 0 } });
+        const lmL2 = makeLandmarks({ [LANDMARKS.INDEX_TIP]: { x: 0.3, y: 0.5, z: 0 } });
+        const lmR2 = makeLandmarks({ [LANDMARKS.INDEX_TIP]: { x: 0.7, y: 0.5, z: 0 } });
+        // Frame 1+2: dwell + transition (zooming entered on frame 2, but output comes from idle branch)
+        fsm.update(makeFrame(0, makeHand('openPalm', lmL1), makeHand('openPalm', lmR1)));
+        fsm.update(makeFrame(0, makeHand('openPalm', lmL1), makeHand('openPalm', lmR1)));
+        // Frame 3: first real zooming frame — sets prevZoomDist, no delta yet
+        fsm.update(makeFrame(1, makeHand('openPalm', lmL1), makeHand('openPalm', lmR1)));
+        // Frame 4: wider spread → positive delta
+        const out = fsm.update(makeFrame(2, makeHand('openPalm', lmL2), makeHand('openPalm', lmR2)));
+        expect(out.mode).toBe('zooming');
+        expect(out.zoomDelta).not.toBeNull();
+        expect(out.zoomDelta).toBeGreaterThan(0);
+    });
+    // ── reset ──────────────────────────────────────────────────────────────────
+    it('reset() returns the FSM to idle', () => {
+        enterPanning(fsm);
+        expect(fsm.getMode()).toBe('panning');
+        fsm.reset();
+        expect(fsm.getMode()).toBe('idle');
+    });
+    // ── dwell timer ────────────────────────────────────────────────────────────
+    it('does NOT transition before actionDwellMs elapses', () => {
+        const slowFsm = new GestureStateMachine({ ...FAST_TUNING, actionDwellMs: 200 });
+        const fistHand = makeHand('fist');
+        const out1 = slowFsm.update(makeFrame(0, fistHand, null));
+        expect(out1.mode).toBe('idle');
+        const out2 = slowFsm.update(makeFrame(100, fistHand, null)); // 100 ms < 200 ms
+        expect(out2.mode).toBe('idle');
+        const out3 = slowFsm.update(makeFrame(200, fistHand, null)); // 200 ms >= 200 ms
+        expect(out3.mode).toBe('panning');
+    });
+    // ── release grace period ───────────────────────────────────────────────────
+    it('stays in panning during release grace period', () => {
+        const graceFsm = new GestureStateMachine({ ...FAST_TUNING, releaseGraceMs: 100 });
+        enterPanning(graceFsm);
+        expect(graceFsm.getMode()).toBe('panning');
+        const out1 = graceFsm.update(makeFrame(1, null, null)); // grace starts
+        expect(out1.mode).toBe('panning');
+        const out2 = graceFsm.update(makeFrame(50, null, null)); // 50 ms < 100 ms
+        expect(out2.mode).toBe('panning');
+        const out3 = graceFsm.update(makeFrame(101, null, null)); // 101 ms >= 100 ms
+        expect(out3.mode).toBe('idle');
+    });
+});

package/dist/WebcamOverlay.d.ts

@@ -0,0 +1,30 @@
+import type { GestureFrame, GestureMode, WebcamConfig } from './types.js';
+/**
+ * WebcamOverlay
+ *
+ * Manages a DOM container with:
+ *   - <video> element (webcam feed)
+ *   - <canvas> for landmark drawing
+ *   - mode badge
+ *
+ * Supports 'corner', 'full', and 'hidden' modes.
+ */
+export declare class WebcamOverlay {
+    private container;
+    private canvas;
+    private ctx;
+    private badge;
+    private config;
+    constructor(config: WebcamConfig);
+    /** Attach video element produced by GestureController */
+    attachVideo(video: HTMLVideoElement): void;
+    /** Mount the overlay into the given parent (usually document.body or map container) */
+    mount(parent: HTMLElement): void;
+    unmount(): void;
+    /** Called each frame with the latest gesture frame and mode. */
+    render(frame: GestureFrame | null, mode: GestureMode): void;
+    private drawSkeleton;
+    private updateBadge;
+    private applyContainerStyles;
+    updateConfig(config: Partial<WebcamConfig>): void;
+}