OctaTouch

OctaTouch

OctaTouch

A universal gesture-interaction specification and C++17 engine that unifies touch controls across every major OS and hardware platform.

CI CodeQL C++17 MIT License

What is OctaTouch?

OctaTouch maps raw multi-touch input onto eight functional channels — L1–L4 on the left hand, R1–R4 on the right — with the thumb acting as a global modifier (Navigate / Switch / Confirm). The result is a consistent, hardware-agnostic gesture vocabulary that works identically whether the surface is a phone screen, a tablet, an in-vehicle display, or a resistive touchscreen on embedded hardware.

When it works, it is invisible.

The Channel Model

OctaTouch gesture map — eight channels with thumb modifier

Channel Hand Finger position
L1 Left Index, top zone
L2 Left Index, mid zone
L3 Left Ring, top zone
L4 Left Ring, mid zone
R1 Right Index, top zone
R2 Right Index, mid zone
R3 Right Ring, top zone
R4 Right Ring, mid zone

The thumb modifier changes the semantic of any channel gesture:

Modifier Meaning
None Default action
Navigate Move / scroll
Switch Context switch
Confirm Commit / select

Processing Pipeline

OctaTouch processing pipeline

Raw hardware input flows through four stages:

  1. FingerTracker — assigns stable finger IDs across frames
  2. GestureRecognizer — classifies tap, hold, swipe, and chord-press
  3. IntentResolver — maps gestures to archive-bound channel intents
  4. App — receives typed ChannelIntent events

The entire pipeline is implemented in core/ as a dependency-free C++17 library.

Quick Start

Build & test (C++ engine)

# Requires CMake >= 3.16 and a C++17 compiler
make build   # cmake configure + build
make test    # ctest

Run the JS smoke test

node tests/runtime/expo_runtime_smoke.mjs

Expo demo app

cd apps/expo-demo
npm install
npx expo start

Platform Support

Platform Adapter Status
Web platforms/web/PointerEventAdapter.ts ✅
iOS / Android (Expo) apps/expo-demo/modules/octatouch-native/ ✅
AD7879 resistive touchscreen integrations/firmware-ad7879/ad7879_driver.c ✅
In-vehicle HMI (CAN bus) integrations/in-vehicle-hmi/DrivingModeGate.cpp ✅

Safety States

OctaTouch in-vehicle safety state machine

The in-vehicle HMI integration enforces a DrivingModeGate that restricts available channels based on vehicle speed and handbrake state. See integrations/in-vehicle-hmi/ and docs/adr/0002-storage-enforces-policy.md.

Repository Layout

core/                        C++17 gesture engine (no OS dependencies)
├── include/                 Types.h, GestureEngine.h, FingerTracker.h, ...
└── src/                     Implementations

platforms/
├── expo/                    React Native design system (OctaButton, OctaCard, ...)
└── web/                     PointerEventAdapter.ts

integrations/
├── firmware-ad7879/         Resistive touchscreen driver (C)
├── in-vehicle-hmi/          DrivingModeGate + CANBusMonitor (C++)
└── text-editor/             TextSelectionPlugin.ts

apps/expo-demo/              Runnable Expo demo application
tests/                       Unit, integration, runtime smoke tests
docs/                        ADRs, architecture, PRD, gesture vocabulary
assets/                      SVG diagrams used in this README

Documentation

Document Description
docs/architecture.md Engine architecture and data flow
docs/gesture-vocabulary.md Full gesture taxonomy
docs/prd.md Product requirements
docs/adr/0001-eight-channel-archive-model.md Why eight channels
docs/adr/0002-storage-enforces-policy.md Archive binding policy
docs/security-threat-model.md Threat model

Contributing

  1. Fork the repo and create a branch from main.
  2. Run make test before opening a PR — all CTest and JS smoke tests must pass.
  3. Follow the existing C++17 style in core/; no OS-specific headers in the core library.
  4. For platform adapters, keep the adapter thin — translate input to GestureInputFrame, then call GestureEngine::Submit().

See docs/agent-guides/ for AI-assisted contribution guidelines.

This site is open source. Improve this page.