Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(sonar): bring hand control to every embedded agent, not just the /sonar page
nirholasbae65c273e10
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ef0fd79a0..c9206b331 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -10,6 +10,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **3D assets now load on any website, not just ours**: Files served straight from our asset storage carried a permission list that only named a handful of sites, so a browser on any other site quietly threw the file away after downloading it. Anyone embedding a three.ws avatar or model from its direct storage link saw an empty viewer with a cross-origin error, and the workarounds were our /cdn and /api/glb routes. Storage now allows reads from everywhere while keeping uploads locked to our own pages, so direct links work in any embed. This also fixed a first-party case: the www version of the site served every page correctly but had all of its 3D blocked. `[fix, infra]`- **A smart home that stops answering now says so, instead of reading Live**: If your house went offline while three.ws already had a connection open to it, the home card could keep showing Live, updated moments ago for as long as you watched. The live 3D scene knew and went stale correctly, but the stored status did not, so anything reading it (the card, the home list, a wall display) kept describing a house that was gone as healthy. A house dropping out is now recorded the moment it is noticed, and recorded again when it comes back, so every surface agrees. This was invisible on a first visit and permanent on a busy one, which is why it survived so long. (`/smart-home`) `[fix]`- **Adding more AI providers no longer makes the image check slower to answer**: The image check behind generated models asks several providers in turn, and it shared its time limit out equally between all of them. That had a perverse effect: every provider added to the list shortened the time given to the first and best one, so growing the list made the check worse rather than more resilient. Three providers were added last week and the first one's window fell just below what it needs to answer, which is why the check started timing out instead of returning verdicts. Each provider is now given whatever time the ones behind it do not need, with a guaranteed minimum still held back for every one of them, so the check gets a real answer from the first healthy provider and still falls through to the rest when it has to. `[fix, improvement]`+- **Any embedded agent can now be waved at, not just the one on our own page**: Hand control arrived last week on a page of ours: your speakers play a tone too high to hear, and your microphone listens for how your hand bends it on the way back, so you can drive a 3D agent by waving at your laptop with the camera shut. It now works on any agent embedded anywhere. Add sonar to the embed tag, give people a button to switch it on, and a sweep of the hand steps the agent through its gestures, a push moves the camera in, and a held hand turns it around. Sites that want the gestures to do something else entirely can take them over and drive their own page with them. Nothing is recorded, nothing is downloaded until somebody actually turns it on, and it stops the moment they navigate away. (`/sonar`) `[feature, sdk]`- **Control a 3D agent with your hands, no camera needed**: Your laptop already has a motion sensor: the speakers and the microphone. The new Sonar page plays a tone too high to hear, then listens for how your hand bends it on the way back, the same effect that drops the pitch of a passing siren. Sweep your hand across the keyboard and the agent on screen steps to its next gesture. Push your palm toward the screen and the camera moves in. Lift your hand and hold it, and the camera turns around the agent. Nothing is recorded and nothing leaves the page, and every gesture is on the keyboard too, so the page works with the microphone switched off. The sensing itself is two small modules you are free to point at anything, documented for developers. (`/sonar`) `[feature]`- **Generated motion clips rebuilt so they no longer slide across the floor**: The generated half of the animation library was written in the wrong rest pose and carried a constant forward drift that was never in the original motion, which made characters glide instead of plant their feet. Every published clip was re-derived from the motion already generated, re-checked against the quality gate, and republished: 39 clips that now pass are live, and the 94 that still failed on foot-sliding were withdrawn rather than left on the shelf. No new generation was needed, because the motion was correct all along and only written down wrong. (`/animations`) `[fix, improvement]`- **Repaired the free AI lanes, which had been quietly answering nothing**: Several of the free AI models the platform falls back to had been retired by their provider and were answering every request with a Gone error. Nothing logged it as a problem, because a dead model looks the same as a busy one to a fallback chain: it just moves on. The cost was real though, since each dead entry ate one of the limited retry slots that should have gone to a lane that could actually answer, making the whole chain fail sooner and more often under load. Every model id is now checked against the provider's live catalog, the dead ones are replaced with working models, and the same applies to the search-and-memory embedding lane, which had been failing for two weeks. Older stored memories keep working: they are tagged with the model that created them and still resolve. `[fix, infra]`diff --git a/STRUCTURE.md b/STRUCTURE.mdindex 1d00397c3..36c805d84 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -155,7 +155,7 @@ bottom.| Parametric avatar base (change-everything sliders) | Baker [scripts/build-parametric-base.mjs](scripts/build-parametric-base.mjs) → [public/avatars/parametric-base.glb](public/avatars), CC0 source data [avatar-sources/anny/](avatar-sources/anny), studio wiring [src/avatar-studio.js](src/avatar-studio.js) (`?base=parametric`) + [src/avatar-sculpt.js](src/avatar-sculpt.js) | Live in Avatar Studio (Base switcher) | One canonical humanoid whose identity is **306 baked morph-target sliders** (nose/ears/mouth/eyes/brows/cheeks/jaw/head shape/neck plus gender, ethnicity, muscle, weight, age, height, torso, hips, midsection, arms and legs), built from the CC0 MakeHuman/MPFB2 body vendored via [naver/anny](https://github.com/naver/anny). 52-bone `mixamorig:*` skeleton, so the full clip library retargets onto every slider combination. Sparse-accessor morphs keep the GLB at 6.5 MB; the baker enforces a 96 MB morph-texture VRAM ceiling because three.js allocates one dense texture layer per target. On top of the sliders: skeleton-space **proportions** ([src/avatar-proportions.js](src/avatar-proportions.js), baked server-side by [api/_lib/bake-proportions.js](api/_lib/bake-proportions.js)) and a **free-sculpt brush** ([src/avatar-sculpt-brush.js](src/avatar-sculpt-brush.js), wire format [src/avatar-sculpt-doc.js](src/avatar-sculpt-doc.js), baked by [api/_lib/bake-sculpt.js](api/_lib/bake-sculpt.js)) for the shapes no catalogue has. Contract: [specs/PARAMETRIC_AVATAR.md](specs/PARAMETRIC_AVATAR.md). Tests: [tests/parametric-base.test.js](tests/parametric-base.test.js), [tests/bake-proportions.test.js](tests/bake-proportions.test.js), [tests/avatar-sculpt-brush.test.js](tests/avatar-sculpt-brush.test.js) || Animation gallery | [pages/animations.html](pages/animations.html) + [src/animations-gallery.js](src/animations-gallery.js) | Live at `/animations` | 2,100+ clips with poster thumbnails ([scripts/build-animation-thumbnails.mjs](scripts/build-animation-thumbnails.mjs)), derived categories ([src/animation-categories.js](src/animation-categories.js)), shared live-preview engine ([src/animations-live-preview.js](src/animations-live-preview.js)) · see [docs/animations.md](docs/animations.md) || Gesture vocabulary | [pages/gestures.html](pages/gestures.html) + [src/gestures-page.js](src/gestures-page.js), slots [src/runtime/animation-slots.js](src/runtime/animation-slots.js) | Live at `/gestures` | The 19 gesture slots an agent plays, each previewed on a live avatar, with the skill hints that trigger it and a builder that saves a per-slot clip override straight onto an agent (`meta.edits.animations`). Hint table is generated from the shipped skill definitions by [scripts/build-agent-hints.mjs](scripts/build-agent-hints.mjs), so attribution cannot go stale · see [docs/animations.md](docs/animations.md) |-| Acoustic gesture control | [pages/sonar.html](pages/sonar.html) + [src/sonar-page.js](src/sonar-page.js), sensor [src/sonar/doppler.js](src/sonar/doppler.js), detectors [src/sonar/gestures.js](src/sonar/gestures.js) | Live at `/sonar` | Hand control for a 3D agent with no camera: the speakers emit an inaudible carrier and the microphone reads the Doppler shift of a hand off it, so a sweep steps through the gesture vocabulary, a push dollies the camera and a held lift turns it. The sensor picks a carrier by measuring every candidate against the machine's own hardware, because the frequency a laptop's speakers can actually project differs per model and an unprojectable one reads exactly like an empty room. Both modules are DOM-free and 3D-free, so any surface can consume them. Ported from [Sonar](https://github.com/nirholas/sonar.cool) (MIT), itself an implementation of SoundWave (CHI 2012) · see [docs/sonar.md](docs/sonar.md). Tests: [tests/sonar-gestures.test.js](tests/sonar-gestures.test.js) |+| Acoustic gesture control | [pages/sonar.html](pages/sonar.html) + [src/sonar-page.js](src/sonar-page.js), sensor [src/sonar/doppler.js](src/sonar/doppler.js), detectors [src/sonar/gestures.js](src/sonar/gestures.js), shared input chain [src/sonar/controller.js](src/sonar/controller.js), embed surface `<agent-3d sonar>` ([src/element.js](src/element.js) `startSonar()`) | Live at `/sonar` | Hand control for a 3D agent with no camera: the speakers emit an inaudible carrier and the microphone reads the Doppler shift of a hand off it, so a sweep steps through the gesture vocabulary, a push dollies the camera and a held lift turns it. The sensor picks a carrier by measuring every candidate against the machine's own hardware, because the frequency a laptop's speakers can actually project differs per model and an unprojectable one reads exactly like an empty room. Both modules are DOM-free and 3D-free, so any surface can consume them. Ported from [Sonar](https://github.com/nirholas/sonar.cool) (MIT), itself an implementation of SoundWave (CHI 2012) One controller serves both surfaces, so the mode arbitration and reverse handling exist once; the embed loads none of the sensing until a page calls `startSonar()`, and every gesture fires a cancelable `sonar-gesture` event a host page can take over · see [docs/sonar.md](docs/sonar.md), [docs/web-component.md](docs/web-component.md). Tests: [tests/sonar-gestures.test.js](tests/sonar-gestures.test.js), [tests/sonar-controller.test.js](tests/sonar-controller.test.js) || Choreographer | [pages/choreograph.html](pages/choreograph.html) + [src/choreograph-page.js](src/choreograph-page.js), engine [src/runtime/choreography.js](src/runtime/choreography.js) | Live at `/choreograph` | Timeline for composing gesture slots into named, timed routines, previewed on the shared live-preview engine with crossfades and a scrubbable playhead. One dependency-free module defines the routine format, the URL wire format and the timing engine; the studio, `PUT /api/agents/:id/animations` (stored at `meta.choreographies`), the public manifest and `AgentAvatar.playChoreography` all import it, and `<agent-3d>.playRoutine('welcome')` performs one from any embed. Also published as `@three-ws/avatar/runtime/choreography.js` · see [docs/choreography.md](docs/choreography.md) || Character Library | [pages/character-library.html](pages/character-library.html) + [src/character-library.js](src/character-library.js) (search/sort/link logic in [src/shared/character-library-view.js](src/shared/character-library-view.js), covered by [tests/character-library-view.test.js](tests/character-library-view.test.js)) → `/character-library`, API [api/avatars/library.js](api/avatars/library.js) | Live at `/character-library` | Professionally rigged Mixamo characters (skinned GLB + thumbnails on R2, `avatars/mixamo/`), each drives the full animation library. The live count comes from the R2 manifest and renders in the hero; no page copy hard-codes it. Pipeline: [scripts/fetch-mixamo-avatars.mjs](scripts/fetch-mixamo-avatars.mjs) → [scripts/convert-mixamo-avatars.mjs](scripts/convert-mixamo-avatars.mjs) → [scripts/fetch-mixamo-avatar-thumbnails.mjs](scripts/fetch-mixamo-avatar-thumbnails.mjs) → [scripts/build-mixamo-avatar-library.mjs](scripts/build-mixamo-avatar-library.mjs) publishes `avatars/library/manifest.json`. Cards deep-link into the 3D viewer (`/app#model=`), Widget Studio (`/studio?model=`), and Animation Studio (`/pose?src=`). Mirrors the animation-library R2-manifest pattern (no DB). See [public/avatars/mixamo/README.md](public/avatars/mixamo/README.md) || Object Library | [pages/objects.html](pages/objects.html) + [src/objects-library.js](src/objects-library.js) → `/objects`, API [api/objects/library.js](api/objects/library.js) | Live at `/objects` | Hundreds of CC0 (public-domain) 3D props from Poly Haven (packed to GLB on R2, `objects/polyhaven/`). Pipeline: [scripts/fetch-polyhaven-objects.mjs](scripts/fetch-polyhaven-objects.mjs) (glTF→GLB via @gltf-transform) → [scripts/render-glb-thumbnails.mjs](scripts/render-glb-thumbnails.mjs) → [scripts/build-object-library.mjs](scripts/build-object-library.mjs) publishes `objects/library/manifest.json`. Same R2-manifest pattern as the Character/animation libraries (no DB). Cards preview in the 3D viewer (`/app#model=`), place into AR Studio (`/ar/studio?src=`), and download the GLB directly (CC0). AR Studio's tray also has an Objects tab over the same manifest. The grid renders 48 cards at a time (a Load more button, plus an IntersectionObserver that pulls the next chunk as you approach it) and each card is a still thumbnail until you dwell on it, at which point that one card upgrades to a live auto-rotating `<model-viewer>`; at most six stay mounted. The manifest read falls back to the bucket's public CDN domain when the signed S3 read fails (`getPublicObjectBuffer` in [api/_lib/r2.js](api/_lib/r2.js)), so a bad storage credential can no longer empty a library of public CC0 bytes. |diff --git a/data/changelog.json b/data/changelog.jsonindex b51cb5437..e2fe33afb 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,16 @@{"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-09-10",+ "title": "Any embedded agent can now be waved at, not just the one on our own page",+ "summary": "Hand control arrived last week on a page of ours: your speakers play a tone too high to hear, and your microphone listens for how your hand bends it on the way back, so you can drive a 3D agent by waving at your laptop with the camera shut. It now works on any agent embedded anywhere. Add sonar to the embed tag, give people a button to switch it on, and a sweep of the hand steps the agent through its gestures, a push moves the camera in, and a held hand turns it around. Sites that want the gestures to do something else entirely can take them over and drive their own page with them. Nothing is recorded, nothing is downloaded until somebody actually turns it on, and it stops the moment they navigate away.",+ "tags": [+ "feature",+ "sdk"+ ],+ "link": "/sonar"+ },{"date": "2026-09-10","title": "Control a 3D agent with your hands, no camera needed",diff --git a/docs/sonar.md b/docs/sonar.mdindex 2b2489d88..f7d46c217 100644--- a/docs/sonar.md+++ b/docs/sonar.md@@ -126,6 +126,69 @@ The microphone stream is analysed in memory and never leaves the page: no record---+## On an embedded agent++Any `<agent-3d>` embed can be driven by hand. The attribute permits it; the page+starts it, because opening a microphone and putting a tone into someone's room is+the viewer's decision, not the embed's:++```html+<agent-3d agent-id="your-agent" sonar></agent-3d>+```++```js+const el = document.querySelector('agent-3d');+startButton.addEventListener('click', () => el.startSonar({ mode: 'swipe' }));+```++A sweep steps the agent through its gesture vocabulary, a push moves the camera+in and a pull eases it back out, a held lift turns the camera. Every recognised+gesture also fires a cancelable `sonar-gesture` event, so a host page can take+the gestures and do something else entirely with them:++```js+el.addEventListener('sonar-gesture', (e) => {+ e.preventDefault();+ if (e.detail.gesture === 'swipe') e.detail.direction > 0 ? nextSlide() : prevSlide();+});+```++Nothing of the sensing ships until `startSonar()` is called for the first time,+so an embed that never uses it pays nothing for the capability. The attribute,+the methods and the event detail are specified in+[Web component](./web-component.md#hand-control-no-camera).++---++## The shared controller++`src/sonar/controller.js` is the layer both surfaces sit on. It owns the sensor,+the three detectors, the mode arbitration and the reverse switches, and reports+what it read through callbacks. What a gesture *means* stays with the consumer.++```js+import { SonarController } from '/src/sonar/controller.js';++const sonar = new SonarController({+ mode: 'swipe',+ onSwipe: (direction) => (direction > 0 ? next() : previous()),+ onZoom: (action) => zoom(action),+ onTurn: (radians) => camera.orbitBy(radians),+});+await sonar.start();+```++| Member | Purpose |+| --- | --- |+| `start()` / `stop()` | Open and release the microphone. `stop()` is safe when nothing is running. |+| `setMode(mode)` | `'swipe'`, `'push'`, `'lift'` or `'all'`. Drops the stroke in flight, so a half-formed gesture cannot complete under the new mapping. |+| `setReversed(gesture, on)` | Flip a gesture's direction. `'lift'` reverses through the motion itself, so a held turn stops rather than snapping the other way. |+| `recalibrate()` | Re-measure the still room without restarting the microphone. |+| `feed(reading)` | Drive it from a Reading you already have. The sensor calls this for you; it is public so a recorded stream can be replayed through the same mapping, which is how `tests/sonar-controller.test.js` covers the mode and reverse behaviour with no microphone. |+| `GESTURE_CAST` | The ordered gesture slots a sweep walks through, shared so the page and an embed step the same cast. |++---+## Reusing it elsewhereThe modules ship in the frontend bundle and are plain ES modules with no dependencies beyond each other:diff --git a/docs/web-component.md b/docs/web-component.mdindex 203fc0179..5e4fb8ff0 100644--- a/docs/web-component.md+++ b/docs/web-component.md@@ -105,6 +105,50 @@ in the hosted app and in an embed. A runnable page isvocabulary are documented in [Sign language](./sign-language.md), and thealphabet is browsable at [/asl-alphabet](https://three.ws/asl-alphabet).+### Hand control, no camera++| Attribute | Type | Default | Description |+|-----------|------|---------|-------------|+| `sonar` | boolean | off | Permits acoustic hand control on this element. The speakers emit a tone above hearing and the microphone reads how a hand bends it on the way back, so a viewer can drive the agent by waving at their laptop with the camera shut. Any value except `off` or `false` permits it; removing the attribute stops a session already running. |++The attribute only **permits** the capability. Nothing starts until the page calls+`startSonar()`, and that call needs a real user gesture behind it, because it+prompts for the microphone and puts a tone into the viewer's room. An embed that+never calls it ships none of the sensing code: the modules load on first use.++```html+<agent-3d agent-id="your-agent" sonar></agent-3d>+```++```js+const el = document.querySelector('agent-3d');+document.querySelector('#wave-at-me').addEventListener('click', async () => {+ try {+ await el.startSonar({ mode: 'swipe' });+ } catch (err) {+ // A denied or unavailable microphone. err.message is written to be shown.+ show(err.message);+ }+});+```++Out of the box a sweep steps the agent through its gesture vocabulary, a push+moves the camera in and a pull eases it back out, and a held lift turns the+camera around the agent. To map the gestures to your own behaviour instead,+cancel the event:++```js+el.addEventListener('sonar-gesture', (e) => {+ e.preventDefault(); // suppress the built-in response+ if (e.detail.gesture === 'swipe') e.detail.direction > 0 ? nextSlide() : prevSlide();+});+```++Say plainly wherever you ship this that the carrier sits near 20 kHz, which cats+and dogs can hear. The technique, its three gestures, what it needs from the+room, and why running more than one gesture at a time needs a mode are all in+[Sonar](./sonar.md).+### Skills and memory| Attribute | Type | Default | Description |@@ -163,6 +207,8 @@ el.skills // Array of installed Skill objects**`el.skills`** — Array of all currently installed `Skill` objects. Updated live as skills are installed or uninstalled.+**`el.sonarRunning`** - Read-only boolean, true while the microphone is open and hand gestures are being read. See [`startSonar()`](#startsonaropts).+---## Methods@@ -281,6 +327,32 @@ Resolves once the motion finishes, with `{ signed, spelled }`, or with `null` wh---+### `startSonar(opts?)`++Starts reading hand gestures from the microphone. Requires the `sonar` attribute and a real user gesture behind the call.++```js+const started = await el.startSonar({ mode: 'push' });+```++| Parameter | Type | Description |+|-----------|------|-------------|+| `opts.mode` | `'swipe'` \| `'push'` \| `'lift'` \| `'all'` | Which gesture is live. Default `'swipe'`. |+| `opts.amplitude` | number | Speaker level for the carrier, 0 to 1. Default `0.08`. |+| `opts.tone` | number | Carrier in Hz. Omit it: the sensor measures the candidates against the machine's own hardware and keeps the best. |++Only one gesture is live at a time because they are not separable at the hardware level: the microphone senses distance, so a sweep passing it is an approach followed by a retreat, which is exactly what a push and a pull look like. `'all'` runs every detector and misreads more often.++Resolves `true` once sensing has begun, or `false` when the `sonar` attribute is absent, a session is already running, or the browser has no Web Audio microphone input. Rejects with a user-showable message when the microphone is denied or unavailable.++---++### `stopSonar()`++Silences the tone and releases the microphone, which is what turns the browser's recording indicator off. Safe to call when nothing is running. Removing the `sonar` attribute does this for you, and so does removing the element from the page.++---+### `speakAudio(audio, opts?)`Plays audio you supply and drives the avatar's mouth from it. The built-in voice pipeline already lip-syncs its own TTS; this is the way in for audio synthesized somewhere else, a recorded clip, or a line you cached. The audio is routed through the same analyser the internal path uses, so the visemes follow the real waveform rather than approximating it from the text.@@ -445,6 +517,20 @@ All events bubble and are `composed: true`, meaning they cross shadow DOM bounda| `voice:listen-start` | `{}` | Microphone opens. || `voice:transcript` | `{ text, final }` | STT chunk received. `final: true` means the utterance is complete. |+### Hand control events++| Event | Detail | When |+|-------|--------|------|+| `sonar-gesture` | `{ gesture, ... }` | A hand gesture was recognised. Cancelable: `preventDefault()` suppresses the built-in response and leaves the gesture entirely to your handler. Bubbles and crosses the shadow boundary. |++`detail.gesture` is `"swipe"`, `"push"` or `"lift"`, each carrying what its own response needs:++| Gesture | Detail fields |+|---------|---------------|+| `swipe` | `direction` (`1` next, `-1` previous) and `slot`, the gesture slot the agent is about to play. |+| `push` | `action` (`3` on the push, `-1` per step of the paced return, `0` as it lands back at rest) and `factor`, the camera dolly it maps to. |+| `lift` | `radians` turned this frame and the current `velocity`. Fires per animation frame while a hand is held up, so treat it as a stream, not an event. |+### Skill events| Event | Detail | When |diff --git a/public/changelog-recent.json b/public/changelog-recent.jsonindex fe736aaeb..7a0ebe32c 100644--- a/public/changelog-recent.json+++ b/public/changelog-recent.json@@ -1,11 +1,11 @@{- "generated_at": "2026-09-10T16:27:25.836Z",+ "generated_at": "2026-09-10T20:30:13.068Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws","url": "https://three.ws"},- "total": 3667,+ "total": 3668,"complete": false,"full_feed": "/changelog.json","entries": [@@ -51,6 +51,17 @@"improvement"]},+ {+ "date": "2026-09-10",+ "type": "update",+ "title": "Any embedded agent can now be waved at, not just the one on our own page",+ "summary": "Hand control arrived last week on a page of ours: your speakers play a tone too high to hear, and your microphone listens for how your hand bends it on the way back, so you can drive a 3D agent by waving at your laptop with the camera shut. It now works on any agent embedded anywhere. Add sonar to the embed tag, give people a button to switch it on, and a sweep of the hand steps the agent through its gestures, a push moves the camera in, and a held hand turns it around. Sites that want the gestures to do something else entirely can take them over and drive their own page with them. Nothing is recorded, nothing is downloaded until somebody actually turns it on, and it stops the moment they navigate away.",+ "link": "/sonar",+ "tags": [+ "feature",+ "sdk"+ ]+ },{"date": "2026-09-10","type": "update",@@ -1606,16 +1617,6 @@"improvement","feature"]- },- {- "date": "2026-09-07",- "type": "update",- "title": "The featured agent is one you can actually open",- "summary": "The agent we spotlight is picked automatically from real activity, but the pick only checked whether an agent was public, not whether its owner had published it. That let a brand new starter agent, the draft every account is given on signup, take the spot, and every panel that tried to read it came back empty with a live feed error. The pick now requires a published agent, so the spotlight lands on one that every part of the site can open.",- "link": null,- "tags": [- "fix"- ]}]}diff --git a/public/changelog.json b/public/changelog.jsonindex 5b07bbfc1..6f3917fd3 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-09-10T16:27:25.816Z",+ "generated_at": "2026-09-10T20:30:13.046Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -48,6 +48,17 @@"improvement"]},+ {+ "date": "2026-09-10",+ "type": "update",+ "title": "Any embedded agent can now be waved at, not just the one on our own page",+ "summary": "Hand control arrived last week on a page of ours: your speakers play a tone too high to hear, and your microphone listens for how your hand bends it on the way back, so you can drive a 3D agent by waving at your laptop with the camera shut. It now works on any agent embedded anywhere. Add sonar to the embed tag, give people a button to switch it on, and a sweep of the hand steps the agent through its gestures, a push moves the camera in, and a held hand turns it around. Sites that want the gestures to do something else entirely can take them over and drive their own page with them. Nothing is recorded, nothing is downloaded until somebody actually turns it on, and it stops the moment they navigate away.",+ "link": "/sonar",+ "tags": [+ "feature",+ "sdk"+ ]+ },{"date": "2026-09-10","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex 8085ea185..9762dfe6c 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -38,6 +38,14 @@<category>fix</category><description>The image check behind generated models asks several providers in turn, and it shared its time limit out equally between all of them. That had a perverse effect: every provider added to the list shortened the time given to the first and best one, so growing the list made the check worse rather than more resilient. Three providers were added last week and the first one's window fell just below what it needs to answer, which is why the check started timing out instead of returning verdicts. Each provider is now given whatever time the ones behind it do not need, with a guaranteed minimum still held back for every one of them, so the check gets a real answer from the first healthy provider and still falls through to the rest when it has to.</description></item>+ <item>+ <title>Any embedded agent can now be waved at, not just the one on our own page</title>+ <link>https://three.ws/sonar</link>+ <guid isPermaLink="false">2026-09-10:Any embedded agent can now be waved at, not just the one on our own page</guid>+ <pubDate>Thu, 10 Sep 2026 12:00:00 GMT</pubDate>+ <category>feature</category>+ <description>Hand control arrived last week on a page of ours: your speakers play a tone too high to hear, and your microphone listens for how your hand bends it on the way back, so you can drive a 3D agent by waving at your laptop with the camera shut. It now works on any agent embedded anywhere. Add sonar to the embed tag, give people a button to switch it on, and a sweep of the hand steps the agent through its gestures, a push moves the camera in, and a held hand turns it around. Sites that want the gestures to do something else entirely can take them over and drive their own page with them. Nothing is recorded, nothing is downloaded until somebody actually turns it on, and it stops the moment they navigate away.</description>+ </item><item><title>Control a 3D agent with your hands, no camera needed</title><link>https://three.ws/sonar</link>diff --git a/public/features.json b/public/features.jsonindex 99c8d6d2d..4f095bd40 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-09-10T16:27:25.805Z",+ "generated_at": "2026-09-10T20:30:13.034Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",diff --git a/src/element.js b/src/element.jsindex ccf55d318..b8104b6ca 100644--- a/src/element.js+++ b/src/element.js@@ -643,6 +643,7 @@ class Agent3DElement extends HTMLElement {'framing','wallet','sign-language',+ 'sonar',];}@@ -689,6 +690,7 @@ class Agent3DElement extends HTMLElement {// WebGL context budget bookkeeping.this._inViewport = false;this._lastVisibleAt = 0;+ this._sonar = null; // acoustic hand control, only once startSonar() is called// Reduced-motion bookkeeping.this._mqReduce = null;this._mqReduceHandler = null;@@ -855,6 +857,11 @@ class Agent3DElement extends HTMLElement {if (name === 'framing') {this._viewer?.setFraming?.(newVal === 'portrait' ? 'portrait' : 'full');}+ // Acoustic hand control is capability-gated, never auto-started: opening a+ // microphone and putting a 20 kHz tone into someone's room is the viewer's+ // decision, so the attribute only permits startSonar(). Removing it, or+ // setting it off, stops a session already running.+ if (name === 'sonar' && !this._sonarAllowed()) this.stopSonar();// ASL replies: any value except "off"/"false" enables signing.if (name === 'sign-language') {const on = newVal != null && newVal !== 'off' && newVal !== 'false';@@ -2820,6 +2827,8 @@ class Agent3DElement extends HTMLElement {}this._autoResolvedManifest = false;}+ // A torn-down element must not leave a microphone open or a tone playing.+ this.stopSonar();_untrackLiveViewer(this);try {this._io?.disconnect();@@ -3139,6 +3148,97 @@ class Agent3DElement extends HTMLElement {sc._addHook(tick);}+ /* ── acoustic hand control ─────────────────────────────────────────────+ *+ * The speakers emit a tone above hearing and the microphone reads how a hand+ * bends it on the way back, so an embedded agent can be driven by hand with+ * no camera. The sensing lives in src/sonar/ and is loaded only when a page+ * actually calls startSonar(), so an embed that never uses it ships none of+ * it. The full technique and its limits: docs/sonar.md.+ */++ /** True when the host page has permitted acoustic control on this element. */+ _sonarAllowed() {+ const v = this.getAttribute('sonar');+ return v != null && v !== 'off' && v !== 'false';+ }++ /** True while the microphone is open and gestures are being read. */+ get sonarRunning() {+ return Boolean(this._sonar?.running);+ }++ /**+ * Start reading hand gestures. Requires the `sonar` attribute and a real user+ * gesture behind the call, because it prompts for the microphone and puts a+ * tone through the speakers.+ *+ * By default a sweep steps the agent through its gesture vocabulary, a push+ * moves the camera in and a pull eases it back out, and a held lift turns the+ * camera around the agent. Pass `mode` to choose which gesture is live: the+ * three are not separable at the hardware level, so running all of them at+ * once ('all') misreads more often.+ *+ * Every recognised gesture also fires a cancelable `sonar-gesture` event, so+ * a host page can map them to its own behaviour instead:+ * `el.addEventListener('sonar-gesture', (e) => { e.preventDefault(); ... })`.+ *+ * @param {{ mode?: 'swipe'|'push'|'lift'|'all', amplitude?: number, tone?: number }} [opts]+ * @returns {Promise<boolean>} false when the attribute is absent or the+ * browser cannot sense; rejects with a user-showable message on a denied+ * or unavailable microphone.+ */+ async startSonar(opts = {}) {+ if (!this._sonarAllowed() || this.sonarRunning) return false;+ const [{ SonarController, GESTURE_CAST }, { isSupported }] = await Promise.all([+ import('./sonar/controller.js'),+ import('./sonar/doppler.js'),+ ]);+ if (!isSupported()) return false;++ let index = 0;+ const emit = (gesture, detail) =>+ this.dispatchEvent(+ new CustomEvent('sonar-gesture', {+ detail: { gesture, ...detail },+ bubbles: true,+ composed: true,+ cancelable: true,+ }),+ );++ this._sonar = new SonarController({+ mode: opts.mode,+ amplitude: opts.amplitude,+ tone: opts.tone,+ onSwipe: (direction) => {+ index = (index + direction + GESTURE_CAST.length) % GESTURE_CAST.length;+ const slot = GESTURE_CAST[index];+ if (emit('swipe', { direction, slot })) this._scene?.playAnimationByHint(slot);+ },+ onZoom: (action) => {+ // +3 on the push, -1 per step of the paced return, 0 as it lands.+ const factor = action > 0 ? 1 / 1.35 : action < 0 ? 1.1 : 1;+ if (!emit('push', { action, factor })) return;+ if (action === 0) this._scene?.viewer?.frameContent?.({ animate: true });+ else this._scene?.viewer?.dollyBy?.(factor);+ },+ onTurn: (radians, velocity) => {+ if (emit('lift', { radians, velocity })) this._scene?.viewer?.orbitBy?.(radians, 0);+ },+ onError: () => this.stopSonar(),+ });+ await this._sonar.start();+ return true;+ }++ /** Silence the tone and release the microphone. Safe to call when idle. */+ stopSonar() {+ if (!this._sonar) return;+ this._sonar.stop();+ this._sonar = null;+ }+async wave(opts) {return this._scene?.playAnimationByHint('wave', opts);}diff --git a/src/sonar-page.js b/src/sonar-page.jsindex ca195c09c..a014dde18 100644--- a/src/sonar-page.js+++ b/src/sonar-page.js@@ -14,17 +14,13 @@import { DopplerSensor, DIRECTION, DIRECTION_LABEL, TONE_CANDIDATES, isSupported, CALIBRATION_SECONDS } from './sonar/doppler.js';import { SwipeDetector, PushPullDetector, LiftMotion } from './sonar/gestures.js';+import { GESTURE_CAST } from './sonar/controller.js';import { DEFAULT_ANIMATION_MAP } from './runtime/animation-slots.js';const MANIFEST_URL = '/animations/manifest.json';-/**- * The slots a sweep walks through, in the order they read best on stage: an- * opener, two reactions, a loop worth landing on, then the rest of the- * vocabulary. Every entry resolves through DEFAULT_ANIMATION_MAP, so a slot- * that gets re-pointed there moves here too.- */-const CAST = ['wave', 'nod', 'celebrate', 'dance', 'point', 'shrug', 'think', 'bow', 'concern', 'shake'];+/** The slots a sweep walks through. Shared with the <agent-3d> embed. */+const CAST = GESTURE_CAST;/** Camera distance for each push step. Step 0 is the framed shot. */const ZOOM_STEPS = [1, 1.18, 1.36, 1.6];diff --git a/src/sonar/controller.js b/src/sonar/controller.jsnew file mode 100644index 000000000..e5379f3d3--- /dev/null+++ b/src/sonar/controller.js@@ -0,0 +1,238 @@+// One place that owns the acoustic input chain, so every surface driving an+// agent by hand shares the same wiring instead of rebuilding it.+//+// Below this file: the sensor (./doppler.js) and the three detectors+// (./gestures.js). Above it: whatever is being driven. /sonar drives the shared+// animation preview, the <agent-3d> web component drives an embedded avatar,+// and neither one repeats the mode arbitration, the reverse handling or the+// lift's per-frame integration.+//+// What this owns:+// • starting and stopping the sensor+// • which detectors are live (see MODES: they cross-trigger, so it is a mode)+// • the three reverse switches+// • turning a held lift into a per-frame turn+//+// What it does not own: what a gesture means. That is the consumer's decision,+// taken through the callbacks.++import { DopplerSensor, DIRECTION } from './doppler.js';+import { SwipeDetector, PushPullDetector, LiftMotion } from './gestures.js';++/**+ * Which detectors are live at once.+ *+ * The three gestures are not separable at the hardware level: the microphone+ * senses distance, so a sweep passing it is an approach followed by a retreat,+ * which is also exactly what a push and a pull look like. Sonar solves that with+ * modes, and so does this. `all` is offered because it is genuinely more fun,+ * and is honest about misreading more often.+ */+export const MODES = {+ swipe: { label: 'Sweep', detectors: ['swipe'] },+ push: { label: 'Push and pull', detectors: ['push'] },+ lift: { label: 'Lift', detectors: ['lift'] },+ all: { label: 'All three', detectors: ['swipe', 'push', 'lift'] },+};++/**+ * Radians of turn per unit of lift travel. A hand held at full strength returns+ * about 700 units a second, which lands a full revolution at a little under two+ * seconds: fast enough to feel connected to the hand, slow enough to stop on a+ * face.+ */+export const ORBIT_SCALE = 0.0045;++/**+ * The gesture slots a sweep walks through, in the order they read best on+ * stage: an opener, two reactions, a loop worth landing on, then the rest of the+ * vocabulary. Shared so /sonar and an <agent-3d> embed step the same cast+ * rather than drifting apart. Every entry is a slot name from+ * src/runtime/animation-slots.js, so a slot re-pointed there moves here too.+ */+export const GESTURE_CAST = [+ 'wave',+ 'nod',+ 'celebrate',+ 'dance',+ 'point',+ 'shrug',+ 'think',+ 'bow',+ 'concern',+ 'shake',+];++const now = () => performance.now() / 1000;++/**+ * Drives one acoustic input chain and reports what it read.+ *+ * ```js+ * const sonar = new SonarController({+ * mode: 'swipe',+ * onSwipe: (dir) => dir > 0 ? next() : previous(),+ * onZoom: (action) => applyZoom(action),+ * onTurn: (radians) => camera.orbitBy(radians),+ * });+ * await sonar.start(); // prompts for the microphone+ * sonar.stop();+ * ```+ */+export class SonarController {+ /**+ * @param {{+ * mode?: keyof typeof MODES,+ * amplitude?: number,+ * tone?: number,+ * autoTone?: boolean,+ * onReading?: (r: object) => void,+ * onSwipe?: (direction: 1|-1, reading: object) => void,+ * onZoom?: (action: 3|-1|0, reading: object) => void,+ * onTurn?: (radians: number, velocity: number) => void,+ * onStatus?: (s: {state: string, message: string}) => void,+ * onError?: (err: Error) => void,+ * }} [opts]+ */+ constructor(opts = {}) {+ this.mode = MODES[opts.mode] ? opts.mode : 'swipe';+ this.reverse = { swipe: false, push: false };+ this.onReading = opts.onReading || null;+ this.onSwipe = opts.onSwipe || null;+ this.onZoom = opts.onZoom || null;+ this.onTurn = opts.onTurn || null;+ this.onStatus = opts.onStatus || null;+ this.onError = opts.onError || null;+ this._opts = opts;++ this._sensor = null;+ this._swipe = new SwipeDetector();+ this._push = new PushPullDetector();+ this._lift = new LiftMotion();+ this._raf = 0;+ this._liftLast = 0;+ this.lastReading = null;+ }++ get running() {+ return Boolean(this._sensor?.running);+ }++ /** The sensor, once started. Null before that, for tone and level controls. */+ get sensor() {+ return this._sensor;+ }++ /**+ * Prompt for the microphone and begin reading. Rejects with a message worth+ * showing a user; `onError` also receives it, for callers started from a+ * place that cannot await.+ */+ async start() {+ if (this.running) return;+ this._sensor = new DopplerSensor({+ tone: this._opts.tone,+ autoTone: this._opts.autoTone,+ amplitude: this._opts.amplitude ?? 0.08,+ onStatus: (s) => this.onStatus?.(s),+ onReading: (r) => this.feed(r),+ });+ try {+ await this._sensor.start();+ } catch (err) {+ this._sensor = null;+ this.onError?.(err);+ throw err;+ }+ this.resetDetectors();+ this._liftLast = 0;+ this._raf = requestAnimationFrame(this._tick);+ }++ /** Silence the tone, release the microphone, and stop reporting. */+ stop() {+ this._sensor?.stop();+ this._sensor = null;+ // Guarded rather than unconditional: stop() is a teardown path, reachable+ // from an element being removed and from a failed start, and it must not+ // throw in a context that has no frame loop to cancel.+ if (this._raf) cancelAnimationFrame(this._raf);+ this._raf = 0;+ this._lift.reset();+ this.lastReading = null;+ }++ /** Forget every stroke in flight. Called on a mode change and on start. */+ resetDetectors() {+ this._swipe.reset();+ this._push.clearEvidence();+ this._push.steps = 0;+ this._lift.reset();+ }++ /** @param {keyof typeof MODES} mode */+ setMode(mode) {+ if (!MODES[mode] || mode === this.mode) return;+ this.mode = mode;+ // Whatever half-formed stroke the old mode was tracking is meaningless now.+ this.resetDetectors();+ }++ /** Flip a gesture's direction. `lift` reverses through the motion itself. */+ setReversed(gesture, on) {+ if (gesture === 'lift') {+ if (Boolean(on) !== !this._lift.forward) this._lift.switchDirection();+ return;+ }+ if (gesture in this.reverse) this.reverse[gesture] = Boolean(on);+ }++ /** Re-measure the still room without restarting the microphone. */+ recalibrate() {+ this._sensor?.recalibrate();+ this.resetDetectors();+ }++ /**+ * Drive the controller from one Reading. Called for you by the sensor while+ * running; public so a caller can also replay a recorded stream through the+ * same mapping, which is how the mode and reverse behaviour is tested without+ * a microphone (tests/sonar-controller.test.js).+ *+ * @param {object} reading a Reading from ./doppler.js+ */+ feed(reading) {+ this.lastReading = reading;+ this.onReading?.(reading);+ const live = MODES[this.mode].detectors;+ const t = now();++ if (live.includes('swipe')) {+ const event = this._swipe.feed(reading, t);+ if (event) {+ const forward = this.reverse.swipe ? event === 'previous' : event === 'next';+ this.onSwipe?.(forward ? 1 : -1, reading);+ }+ }+ if (live.includes('push')) {+ const action = this._push.feed(reading, t, this.reverse.push);+ if (action !== null) this.onZoom?.(action, reading);+ }+ if (live.includes('lift')) this._lift.feed(reading, t);+ }++ /**+ * A lift is continuous, so it advances on the display clock rather than on+ * readings: the turn has to keep easing between analysis frames or it steps.+ */+ _tick = () => {+ this._raf = requestAnimationFrame(this._tick);+ const t = now();+ const dt = this._liftLast ? Math.min(0.1, t - this._liftLast) : 0;+ this._liftLast = t;+ const travelled = this._lift.step(dt, t);+ if (travelled) this.onTurn?.(travelled * ORBIT_SCALE, this._lift.velocity);+ };+}++export { DIRECTION };diff --git a/src/viewer.js b/src/viewer.jsindex 78bc64578..d7636f66f 100644--- a/src/viewer.js+++ b/src/viewer.js@@ -490,29 +490,68 @@ export class Viewer {// every three.ws viewer surface; reduced-motion halves the step so users// who asked for less motion get finer, calmer control instead of smoothing._handleOrbitKeydown(event) {- if (!this.controls || !this.activeCamera) return;const stepScale = this._reducedMotion ? 0.5 : 1;const rotateStep = 0.05 * stepScale;const zoomStep = 1.08;- const offset = this._tempVec.subVectors(this.activeCamera.position, this.controls.target);- const spherical = new Spherical().setFromVector3(offset);let handled = true;switch (event.key) {- case 'ArrowLeft': spherical.theta -= rotateStep; break;- case 'ArrowRight': spherical.theta += rotateStep; break;- case 'ArrowUp': spherical.phi = Math.max(0.05, spherical.phi - rotateStep); break;- case 'ArrowDown': spherical.phi = Math.min(Math.PI - 0.05, spherical.phi + rotateStep); break;+ case 'ArrowLeft': handled = this.orbitBy(-rotateStep, 0); break;+ case 'ArrowRight': handled = this.orbitBy(rotateStep, 0); break;+ case 'ArrowUp': handled = this.orbitBy(0, -rotateStep); break;+ case 'ArrowDown': handled = this.orbitBy(0, rotateStep); break;case '+':case '=':- case 'PageUp': spherical.radius /= zoomStep; break;+ case 'PageUp': handled = this.dollyBy(1 / zoomStep); break;case '-':case '_':- case 'PageDown': spherical.radius *= zoomStep; break;+ case 'PageDown': handled = this.dollyBy(zoomStep); break;default: handled = false;}if (!handled) return;event.preventDefault();event.stopPropagation();+ }++ /**+ * Move the camera around its orbit target, in radians. `dTheta` turns+ * around the model, `dPhi` raises and lowers the shot (clamped clear of the+ * poles, where the up vector flips and the view snaps).+ *+ * Public because the keyboard is no longer the only thing that steers this+ * camera: acoustic gestures drive it too (src/sonar/controller.js), and both+ * need the same spherical move rather than two copies of it.+ *+ * @returns {boolean} false when there is no camera to move yet.+ */+ orbitBy(dTheta = 0, dPhi = 0) {+ if (!this.controls || !this.activeCamera) return false;+ const offset = this._tempVec.subVectors(this.activeCamera.position, this.controls.target);+ const spherical = new Spherical().setFromVector3(offset);+ spherical.theta += dTheta;+ spherical.phi = Math.max(0.05, Math.min(Math.PI - 0.05, spherical.phi + dPhi));+ this._applySpherical(spherical);+ return true;+ }++ /**+ * Dolly the camera along its view ray. Factors below 1 move in, above 1 move+ * out; the range is clamped against the framed distance so a caller cannot+ * drive the camera inside the model or off into the void.+ *+ * @returns {boolean} false when there is no camera to move yet.+ */+ dollyBy(factor) {+ if (!this.controls || !this.activeCamera || !(factor > 0)) return false;+ const offset = this._tempVec.subVectors(this.activeCamera.position, this.controls.target);+ const spherical = new Spherical().setFromVector3(offset);+ const min = this.controls.minDistance || spherical.radius * 0.2;+ const max = this.controls.maxDistance || spherical.radius * 5;+ spherical.radius = Math.max(min, Math.min(max, spherical.radius * factor));+ this._applySpherical(spherical);+ return true;+ }++ _applySpherical(spherical) {const newOffset = new Vector3().setFromSpherical(spherical);this.activeCamera.position.copy(this.controls.target).add(newOffset);this.controls.update();diff --git a/tests/sonar-controller.test.js b/tests/sonar-controller.test.jsnew file mode 100644index 000000000..809f982c5--- /dev/null+++ b/tests/sonar-controller.test.js@@ -0,0 +1,172 @@+/**+ * The shared acoustic input chain (src/sonar/controller.js).+ *+ * The detectors themselves are covered against the original's own vectors in+ * tests/sonar-gestures.test.js. What is pinned here is everything the two+ * surfaces driving them rely on and would otherwise each get wrong on their own:+ *+ * · mode gating, which is the only thing stopping a sweep from also firing a+ * push (the microphone senses distance, so the two look alike coming in)+ * · the reverse switches, including the lift's, which reverses through the+ * motion rather than through a flag+ * · that a mode change drops the stroke in flight instead of completing it+ * under the new mapping+ *+ * The controller is driven through its public feed(), so none of this needs a+ * microphone, a speaker, or a browser.+ */++import { describe, it, expect } from 'vitest';+import { DIRECTION } from '../src/sonar/doppler.js';+import { SonarController, MODES, GESTURE_CAST } from '../src/sonar/controller.js';+import { DEFAULT_ANIMATION_MAP } from '../src/runtime/animation-slots.js';++/** Frames for a clean one-way sweep, quiet either side so the detector arms. */+function sweep(sign) {+ const frames = [];+ for (let i = 0; i < 40; i++) {+ const moving = i >= 20 && i < 30;+ const bands = new Array(8).fill(0);+ if (moving) bands[sign > 0 ? 5 : 2] = 2;+ frames.push({+ direction: DIRECTION.mixed,+ snr: 40,+ strength: moving ? 0.004 : 0,+ waveBands: bands,+ });+ }+ return frames;+}++/** A sustained approach, which is what a push toward the screen returns. */+function push(count = 12) {+ const spectrumDb = new Float32Array(121).fill(-100);+ spectrumDb[90] = -30;+ return Array.from({ length: count }, () => ({+ spectrumDb,+ baselineDb: new Float32Array(121).fill(-100),+ direction: DIRECTION.approaching,+ carrierDb: -20,+ snr: 40,+ strength: 0.004,+ binWidth: 10,+ }));+}++/** Drive frames through a controller at a realistic frame interval. */+function run(controller, frames) {+ for (const f of frames) {+ controller.feed(f);+ // The detectors read performance.now() themselves, so the frames have to+ // be spaced in real time rather than on a supplied clock.+ const until = performance.now() + 21;+ while (performance.now() < until) {+ /* the analysis hop, spent rather than mocked */+ }+ }+}++describe('SonarController', () => {+ it('reports a sweep as a direction, not as a detector event', () => {+ const seen = [];+ const c = new SonarController({ mode: 'swipe', onSwipe: (d) => seen.push(d) });+ run(c, sweep(1));+ expect(seen).toEqual([1]);+ });++ it('honours the sweep reverse switch', () => {+ const seen = [];+ const c = new SonarController({ mode: 'swipe', onSwipe: (d) => seen.push(d) });+ c.setReversed('swipe', true);+ run(c, sweep(1));+ expect(seen).toEqual([-1]);+ });++ it('does not fire a push while the mode is watching for sweeps', () => {+ const zooms = [];+ const c = new SonarController({ mode: 'swipe', onZoom: (a) => zooms.push(a) });+ run(c, push());+ expect(zooms).toEqual([]);+ });++ it('fires that same push once the mode is watching for it', () => {+ const zooms = [];+ const c = new SonarController({ mode: 'push', onZoom: (a) => zooms.push(a) });+ run(c, push());+ expect(zooms[0]).toBe(3);+ });++ it('runs every detector in the all mode', () => {+ const seen = [];+ const c = new SonarController({+ mode: 'all',+ onSwipe: () => seen.push('swipe'),+ onZoom: () => seen.push('push'),+ });+ run(c, sweep(1));+ expect(seen).toContain('swipe');+ });++ it('drops the stroke in flight when the mode changes', () => {+ const seen = [];+ const c = new SonarController({ mode: 'swipe', onSwipe: (d) => seen.push(d) });+ const frames = sweep(1);+ // Cut before the third vote: a sweep needs three coherent frames, so this+ // leaves a half-formed candidate rather than one already fired.+ run(c, frames.slice(0, 22));+ c.setMode('all');+ run(c, frames.slice(22));+ expect(seen).toEqual([]);+ });++ it('reverses a lift through the motion itself, and is idempotent', () => {+ const c = new SonarController({ mode: 'lift' });+ c.setReversed('lift', true);+ c.feed({ direction: DIRECTION.away, strength: 0.004, snr: 40 });+ expect(c._lift.target).toBeLessThan(0);+ c.setReversed('lift', true);+ c.feed({ direction: DIRECTION.away, strength: 0.004, snr: 40 });+ expect(c._lift.target).toBeLessThan(0);+ c.setReversed('lift', false);+ c.feed({ direction: DIRECTION.away, strength: 0.004, snr: 40 });+ expect(c._lift.target).toBeGreaterThan(0);+ });++ it('passes every reading through, whatever the mode reads from it', () => {+ const readings = [];+ const c = new SonarController({ mode: 'lift', onReading: (r) => readings.push(r) });+ run(c, push(3));+ expect(readings).toHaveLength(3);+ expect(c.lastReading).toBe(readings[2]);+ });++ it('refuses an unknown mode instead of silencing every detector', () => {+ const c = new SonarController({ mode: 'nonsense' });+ expect(c.mode).toBe('swipe');+ c.setMode('also-nonsense');+ expect(c.mode).toBe('swipe');+ });++ it('is not running before start and survives a stop it never started', () => {+ const c = new SonarController();+ expect(c.running).toBe(false);+ expect(() => c.stop()).not.toThrow();+ expect(c.sensor).toBeNull();+ });++ it('steps a cast every entry of which is a real gesture slot', () => {+ expect(GESTURE_CAST.length).toBeGreaterThan(1);+ for (const slot of GESTURE_CAST) {+ expect(DEFAULT_ANIMATION_MAP[slot], `${slot} is not a gesture slot`).toBeTruthy();+ }+ expect(new Set(GESTURE_CAST).size).toBe(GESTURE_CAST.length);+ });++ it('declares a detector set for every mode it offers', () => {+ for (const [name, def] of Object.entries(MODES)) {+ expect(def.label, name).toBeTruthy();+ expect(def.detectors.length, name).toBeGreaterThan(0);+ for (const d of def.detectors) expect(['swipe', 'push', 'lift']).toContain(d);+ }+ });+});