map gesture controls - Moses Yebei

The Problem

Touchless interaction with web maps is limited to expensive hardware or proprietary SDKs. Standard mouse and touch controls exclude kiosk, exhibit, and accessibility use cases where users cannot or should not touch a screen. This library solves that with a browser-only, camera-based gesture layer.

What This Does

map-gesture-controls is a TypeScript monorepo that lets users pan, zoom, and rotate OpenLayers and Google Maps views using hand gestures detected via MediaPipe's in-browser WASM. Camera frames never leave the device.

The core logic lives in packages/map-gesture-core/src/, with framework-specific adapters in packages/ol-gesture-controls/ and packages/google-maps-gesture-controls/. The src/ directory contains a legacy copy of the core, likely pre-monorepo. docs/ holds a VitePress site with full API documentation.

How It Is Wired

Execution starts at GestureMapController.ts in each adapter package. The start method (line 75 in the Google Maps version) calls init, attachVideo, mount, and renderLoop — the latter is the hot path. renderLoop calls classifyGesture on each frame, which routes through dist, areAllFingersExtended, and areAllFingersCurled to determine the active gesture.

The GestureStateMachine (in packages/map-gesture-core/src/GestureStateMachine.ts) is the central hub: 13 functions and 5 classes, called from one other file. Its update method is invoked 21 times from the classifier's buildOutput, and transitionTo 14 times — these carry the widest blast radius. The GestureController.ts orchestrates lifecycle (start, stop, destroy), while WebcamOverlay.ts handles DOM mounting and video attachment.

The module graph shows no circular dependencies across 51 files and 66 edges. The types.ts files in both src/ and packages/map-gesture-core/src/ are stable hubs (8 importers each, zero outgoing edges), so changing gesture types will ripple widely.

How To Use It

git clone https://github.com/moses-y/map-gesture-controls
cd map-gesture-controls
npm install
npm run build

For OpenLayers: npm install @map-gesture-controls/ol ol, then import GestureMapController and pass an existing ol/Map instance. For Google Maps: npm install @map-gesture-controls/google-maps @googlemaps/js-api-loader. No environment variables are required; the .env.example is for demo keys. Webcam permission is mandatory.

Real-World Use

A museum kiosk running an OpenLayers exhibit map: instantiate GestureMapController with the map, request camera access, and visitors pan with a fist, zoom with a pinch, and rotate with both hands. The actionDwellMs (80ms) and releaseGraceMs (150ms) constants in packages/map-gesture-core/src/constants.ts are tunable per installation.

Code Health & Issues

Static analysis (not opinion) found:

High — Duplicated code: 617 repeated 6-line blocks across 43 files, concentrated in examples/demo-*-gmaps.ts. Extract shared helpers.
High — No LICENSE file at root, despite README claiming MIT. Redistribution rights are undefined.
High — CI pins googleapis/release-please-action@v4 to a mutable tag. Pin to a commit SHA.
Medium — No permissions block in .github/workflows/ci.yml; GITHUB_TOKEN inherits repo defaults.
Medium — No Dependabot/Renovate configured for 4 manifests.
Medium — No dependency vulnerability scan in CI.
Medium — Three GIFs over 5MB in docs/public/ (largest 24.5MB), bloating every clone.
Medium — persist-credentials not disabled on checkout in CI.
Low — No timeout-minutes on workflow jobs.

Tests exist (7 files) with coverage of classifiers and state machines.

The Bottom Line

Solid, well-structured library with a clean core/adapter split and zero circular dependencies. The duplicated demo code and missing license are real blockers for production use. Worth adopting if you need touchless map interaction and can accept the webcam requirement; the MIT claim in the README needs a license file to be legally enforceable.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

116 files

TypeScript51
Markdown21
JSON16
HTML12
YAML3
CSS3

React

Module dependencies

The 10 most depended-upon modules of 51, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_examples_fullscreen_toolbar["fullscreen-toolbar"] n1_s_map_gesture_core_src_types["types"] n2_src_types["types"] n3_p_gesture_core_src_constants["constants"] n4_src_constants["constants"] n5_e_core_src_gestureClassifier["gestureClassifier"] n6_src_GestureStateMachine["GestureStateMachine"] n7_src_gestureClassifier["gestureClassifier"] n8_GoogleMapsGestureInteraction["GoogleMapsGestureInterac"] n9_OpenLayersGestureInteraction["OpenLayersGestureInterac"] n3_p_gesture_core_src_constants --> n1_s_map_gesture_core_src_types n5_e_core_src_gestureClassifier --> n1_s_map_gesture_core_src_types n5_e_core_src_gestureClassifier --> n3_p_gesture_core_src_constants n6_src_GestureStateMachine --> n2_src_types n6_src_GestureStateMachine --> n7_src_gestureClassifier n4_src_constants --> n2_src_types n7_src_gestureClassifier --> n2_src_types n7_src_gestureClassifier --> n4_src_constants

Findings

MediumNo LICENSE file - unclear usage/redistribution rights root

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

googleapis/release-please-action@v4

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Add a LICENSE; redistribution rights are undefinedhigh

no licence file at the repository root

Fix: Add MIT or Apache-2.0 at the repository root.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/ci.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

4 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium3 occurrences

docs/public/openlayers-gesture-control-demo-v2.gif

3 blobs over 5MB: openlayers-gesture-control-demo-v2.gif 24.5MB, openlayers-gesture-control-demo.gif 24.5MB, google-maps-gesture-controls-mediapipe.gif 17.1MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/ci.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.