Examples

Everything here is a runnable, copy-me starting point, collected in one repo:

github.com/TheAleSch/gatecaster-examples — MIT licensed, meant to be copied.

Each example talks to Gatecaster through its documented public surfaces only — the Touch API socket and the declarative extension manifest format. No Gatecaster source is required or included; they depend on the protocol, not the app internals.

Requirement for everything here: Gatecaster must be running, and the process you launch (your terminal, usually) must have Accessibility and Input Monitoring granted in System Settings → Privacy & Security. The Touch API socket lives at ~/Library/Application Support/Gatecaster/api.sock — if it’s absent, Gatecaster isn’t up.

What’s in the repo

Folder	What it is	Run
`touch-api/`	Dependency-free reference clients (Python, Node, Swift) that subscribe to the finger + gesture channels, print a live readout, and demo kiosk-style input suppression.	`python3 touch-api/client.py`
`extensions/`	Declarative Deck tiles — each a folder with a `manifest.json`. No code to compile; describe a tile and the actions it fires.	drop into the Extensions folder
`games/touchdraw/`	TouchDraw — a native SwiftUI multitouch paint app. Paint with all ten fingers, drag shapes, pinch/scroll, with the system cursor suppressed.	`swift run` (in that folder)
`games/touchdraw-web/`	The same TouchDraw, for the browser via a tiny dependency-free Node bridge (Unix socket → Server-Sent Events).	`node bridge.js`

Touch API clients

Three deliberately feature-identical reference clients — pick whichever matches the language you’re integrating from and read it as the canonical example. Each connects to the socket, subscribes to the finger and gesture channels, prints a live readout, and (with --suppress) demonstrates kiosk-style input suppression. No packages to install — every client uses only its platform’s standard library.


python3 touch-api/client.py              # read-only: print fingers + gestures
python3 touch-api/client.py --suppress   # also suppress system input (kiosk demo)
 
node touch-api/client.js                 # Node.js equivalent
swift touch-api/client.swift             # Swift — runs as a script, no build step

The Swift client uses Network.framework (NWConnection) and Codable wire models — lift LineReader, the connection handling, and the structs straight into a real macOS app. See the Touch API reference for the full protocol.

Deck extensions

Coming soon — the Deck isn’t part of the Gatecaster beta. These tiles are here so you can author against the manifest format ahead of the release that ships it.

Declarative tiles for the Deck — each is a folder with a manifest.json (authoring guide). Drop a folder into the Extensions directory and reload the Deck:


cp -R extensions/com.gatecaster.nowplaying \
  ~/Library/Application\ Support/Gatecaster/Extensions/

Extension	What it does	Schema
`com.gatecaster.nowplaying`	Apple Music — now-playing track/artist with transport buttons, polled via `osascript`.	v1 (auto-migrates)
`com.gatecaster.audio`	Output volume — an interactive slider plus mute, driven by `osascript`.	v2
`com.gatecaster.spotify`	Spotify transport + now-playing, with a small helper script.	v2
`com.gatecaster.zoom`	Zoom meeting controls — mute, video, leave — as keystroke actions.	v2
`com.figma.shortcuts`	A pad of Figma tool shortcuts, each a keystroke action.	v1
`com.gatecaster.heartbeat`	A provider reference — pairs a v2 manifest with `provider.sh`. Parses and loads today, but the push provider runtime is roadmap, so the provider does not yet run.	v2 (roadmap)

TouchDraw — one API, two runtimes

games/touchdraw/ (native Swift) and games/touchdraw-web/ (web) are the same paint app built two ways, so you can see one Touch API consumed by two very different stacks. Each touch verb maps to one API feature:

Multitouch draw — every finger paints its own live stroke (the fingers channel: stable per-contact id, began/moved/ended phases).
Drag — touch down on an existing shape to move it (hit-testing sx/sy).
Scroll / pinch — pan and zoom the canvas (the gestures channel).
Suppress — on launch the client asks Gatecaster to stop injecting pointer input, so the cursor never fights the drawing. The lease is tied to the connection — quit and touch returns automatically.

For the full build-along, see Building a touch app, which walks through TouchDraw step by step.