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): control a 3D agent by hand with no camera, using the speakers and microphone
nirholas7ae970356a89
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex bfdbce118..da889a285 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,9 +6,11 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr## 2026-09-10+- **Sonar Control** (`/sonar`): Control a 3D agent with your hands and no camera. three.ws plays an inaudible carrier tone through your speakers and reads the Doppler shift of your hand off the microphone, so a sweep, a push or a lift moves the avatar on screen.- **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]`+- **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]`- **The image check now moves on when a model answers in the wrong format**: Generated models are inspected by a vision model before you see them, and that inspection asks several providers in turn so one being busy is never the end of it. The catch was that a provider only had to reply, not reply usefully: a model that narrated its thinking instead of returning the requested format counted as the answer, and the healthy providers waiting behind it were never asked. A reply the check cannot read is now treated as that provider failing, so it moves straight to the next one, and it only gives up once every provider has been tried. The practical effect is that the quality check returns a real verdict far more often, and when it cannot, the reason it reports names the provider that actually lost. `[fix, improvement]`diff --git a/STRUCTURE.md b/STRUCTURE.mdindex 514af66f8..1d00397c3 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -155,6 +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) || 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 219389911..21edbcccb 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,15 @@{"$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": "Control a 3D agent with your hands, no camera needed",+ "summary": "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.",+ "tags": [+ "feature"+ ],+ "link": "/sonar"+ },{"date": "2026-09-10","title": "three.ws now reads in 38 languages",diff --git a/data/pages.json b/data/pages.jsonindex 0ea41f93f..61b878a54 100644--- a/data/pages.json+++ b/data/pages.json@@ -56,6 +56,14 @@"changefreq": "weekly","added": "2026-07-30"},+ {+ "path": "/sonar",+ "title": "Sonar Control",+ "description": "Control a 3D agent with your hands and no camera. three.ws plays an inaudible carrier tone through your speakers and reads the Doppler shift of your hand off the microphone, so a sweep, a push or a lift moves the avatar on screen.",+ "priority": 0.7,+ "changefreq": "weekly",+ "added": "2026-09-10"+ },{"path": "/choreograph","title": "Choreographer",@@ -2775,7 +2783,7 @@},{"path": "/docs/globe",- "title": "Docs \u00b7 Global Intel Globe",+ "title": "Docs · Global Intel Globe","description": "The live 3D globe at /globe: its eleven keyless open-data layers and where each comes from, the URL parameters that make any view a shareable link, the one API call that returns every layer, and why an ingest cron has to keep its own GDELT window for the time control to be honest.","priority": 0.6,"changefreq": "monthly",@@ -4733,6 +4741,13 @@"priority": 0.6,"changefreq": "monthly"},+ {+ "path": "/docs/sonar",+ "title": "Docs · Sonar",+ "description": "The developer reference for acoustic gesture control: the Doppler sensor and its Reading, the three detectors ported from Sonar and SoundWave, why running more than one at a time needs a mode, and what the technique needs from the room.",+ "priority": 0.6,+ "changefreq": "monthly"+ },{"path": "/docs/architecture","title": "Docs · Architecture overview",diff --git a/docs/nav.json b/docs/nav.jsonindex dd97dfab7..781aa6d0d 100644--- a/docs/nav.json+++ b/docs/nav.json@@ -781,6 +781,10 @@"label": "Choreography (gesture routines)","path": "choreography"},+ {+ "label": "Sonar (hand control)",+ "path": "sonar"+ },{"label": "Avatar inspector","path": "avatar-inspector"diff --git a/docs/sonar.md b/docs/sonar.mdnew file mode 100644index 000000000..db40c0e28--- /dev/null+++ b/docs/sonar.md@@ -0,0 +1,138 @@+# Sonar: acoustic gesture control++Every laptop already ships a motion sensor. It is the speaker and the microphone.++Play a tone above human hearing, and a hand moving in front of the machine reflects it back **frequency-shifted**: higher as the hand closes in, lower as it pulls away. That is the Doppler effect, the same thing that drops the pitch of a passing siren, and it is enough to read a sweep, a push and a lift with no camera, no permissions beyond the microphone, and no model weights.++Try it at **[three.ws/sonar](https://three.ws/sonar)**, where the three gestures drive a real 3D agent. This page is the developer reference: the two modules, their surface, and what they will and will not do.++- The live page: [/sonar](https://three.ws/sonar)+- The gestures a sweep steps through: [/gestures](https://three.ws/gestures)+- Putting an agent on your own site: [Embedding](embedding.md)++---++## Where this comes from++The technique is [SoundWave](https://www.microsoft.com/en-us/research/project/soundwave-using-the-doppler-effect-to-sense-gestures/) (Gupta, Morris, Patel and Tan, CHI 2012). The analysis and the three detectors here are ported from [Sonar](https://github.com/nirholas/sonar.cool), Emanuel Perez's MIT-licensed macOS implementation of that paper, with [Daniel Rapp's Doppler](https://github.com/DanielRapp/doppler) as the prior art for doing it in a browser at all.++The port is deliberate about staying close: the transform size, the analysis window, the calibration period and every detector threshold are reproduced exactly, because each one is a tuning result rather than a taste. `tests/sonar-gestures.test.js` drives the detectors with the same synthetic frames the Swift suite uses, so a future edit that "cleans up" a constant fails there.++---++## The two modules++Neither module touches the DOM or three.js. They are usable anywhere in the browser.++### `src/sonar/doppler.js`: the sensor++```js+import { DopplerSensor, DIRECTION, isSupported } from '/src/sonar/doppler.js';++if (!isSupported()) throw new Error('No Web Audio microphone input here.');++const sensor = new DopplerSensor({+ onReading: (r) => {+ if (r.direction === DIRECTION.approaching) console.log('hand closing in');+ },+});++await sensor.start(); // prompts for the microphone+// later+sensor.stop();+```++| Option | Default | Meaning |+| --- | --- | --- |+| `tone` | `20000` | Carrier in Hz. |+| `amplitude` | `0.08` | Speaker level for the carrier, 0 to 1. |+| `autoTone` | `true` | Measure every candidate in `TONE_CANDIDATES` against this machine's own hardware on start and keep the one that comes back loudest. |+| `onReading` | none | Called once per analysis frame with a `Reading`. |+| `onStatus` | none | Called with `{state, message}` at `starting`, `tuning`, `calibrating`, `stopped`. |++Methods: `start()`, `stop()`, `setTone(hz)`, `setAmplitude(0..1)`, `recalibrate()`.++Why `autoTone` exists: laptop speakers roll off hard near the top of their range, and every model rolls off somewhere different. A carrier the speakers cannot actually project reads exactly like a room with nothing moving in it, which is indistinguishable from a broken sensor. Measuring first turns a mystery into a number.++### The `Reading`++One per frame, at the same 2048-sample hop the desktop app uses.++| Field | Meaning |+| --- | --- |+| `direction` | One of the `DIRECTION` values: `approaching`, `away`, `mixed`, `still`, `listening`, `calibrating`, `weak-tone`. |+| `strength` | Sideband energy that was not in the still room, over the carrier. Above `0.0003` is motion. |+| `snr` | Carrier minus noise floor, in dB. Below 15 the tone is not usable and every detector stands down. |+| `waveBands` | Eight log-compressed bands across the analysis window. The lower four are recession, the upper four approach; their balance is what makes a sweep readable. |+| `spectrumDb` / `baselineDb` | The window and the still-room reference, both in dB. Draw them to see the shift with your own eyes. |+| `calibrationRemaining` | Seconds left of the 2.5 s baseline measurement, then `null`. |+| `carrierDb`, `binWidth`, `firstFrequency`, `sampleRate`, `tone`, `opposedStrength` | Enough to label an axis and to reason about a bad reading. |++### `src/sonar/gestures.js`: the detectors++Three pure state machines over Readings plus a clock. No audio, no DOM.++```js+import { SwipeDetector, PushPullDetector, LiftMotion } from '/src/sonar/gestures.js';++const swipe = new SwipeDetector();+const sensor = new DopplerSensor({+ onReading: (r) => {+ const event = swipe.feed(r, performance.now() / 1000);+ if (event === 'next') nextSlide();+ if (event === 'previous') previousSlide();+ },+});+```++| Detector | Call | Emits |+| --- | --- | --- |+| `SwipeDetector` | `feed(reading, now)` | `'next'`, `'previous'` or `null` |+| `PushPullDetector` | `feed(reading, now, reversed)` | `3` on the push, `-1` per step of the return, `0` on the step that lands back at rest, else `null` |+| `LiftMotion` | `feed(reading, now)` then `step(dt, now)` per frame | distance travelled this frame |++`SwipeDetector` needs a pause between sweeps, and that is not a limitation to design around, it is the physics. The microphone senses distance, not direction: a sweep registers as one coherent approach followed by its retreat. The detector takes the first coherent lobe and suppresses the return for 650 ms, which is exactly what stops one wave from firing two navigations.++`PushPullDetector` paces the return by reading how far the reflected energy sits from the carrier, so a quick pull snaps back and a slow one eases. A push while already pushed is ignored rather than stacked.++`LiftMotion` is continuous rather than discrete: `feed()` sets a target from the returned energy, `step()` eases toward it and returns the distance for that frame. It bridges a couple of uncertain frames on purpose, so a momentary misread mid-lift does not drop the motion.++---++## Running more than one detector++They cross-trigger, and the fix is a mode rather than a filter.++A sweep passing the microphone looks like an approach followed by a retreat. So does a push followed by a pull. The hardware cannot separate them, so [/sonar](https://three.ws/sonar) makes the active gesture an explicit choice, with an **All three** setting that is honest about misreading more often. Build the same way: pick the gesture your surface needs, and only feed that detector.++---++## What it needs from the room++| Requirement | Why |+| --- | --- |+| Built-in speakers and microphone | Headphones break the reflection path. There is nothing for the tone to bounce off on its way back. |+| The volume up | The carrier has to reach the hand and return. A muted machine senses a still room forever. |+| A quiet-ish 20 kHz band | A nearby machine emitting in the same band raises the floor. The carrier picker routes around most of it. |+| Two and a half seconds of stillness at the start | Everything the microphone hears during calibration becomes the baseline that a hand is later measured against. Move during it and the room learns your hand as background. |++Cats and dogs hear near 20 kHz. Say so wherever you ship this, as [/sonar](https://three.ws/sonar) does.++---++## Privacy++The microphone stream is analysed in memory and never leaves the page: no recording, no upload, no storage. Only the frequency-domain magnitudes around the carrier are ever read, and the page keeps a hardware carrier choice and nothing else. Stopping releases the microphone track, which is what turns the browser's recording indicator off.++---++## Reusing it elsewhere++The modules ship in the frontend bundle and are plain ES modules with no dependencies beyond each other:++```js+import { DopplerSensor } from 'https://three.ws/src/sonar/doppler.js';+import { SwipeDetector } from 'https://three.ws/src/sonar/gestures.js';+```++Both are MIT, and so is the work they are ported from. Credit Sonar and the SoundWave paper if you build on them.diff --git a/pages/sonar.html b/pages/sonar.htmlnew file mode 100644index 000000000..aec090b60--- /dev/null+++ b/pages/sonar.html@@ -0,0 +1,276 @@+<!doctype html>+<html lang="en">+ <head>+ <script>/* three.ws theme boot: no-flash */(function(){try{var m=localStorage.getItem('twx_theme');var l=m==='auto'?(window.matchMedia&&window.matchMedia('(prefers-color-scheme: light)').matches):m==='light';document.documentElement.setAttribute('data-theme',l?'light':'dark');}catch(e){document.documentElement.setAttribute('data-theme','dark');}})();</script>+ <meta charset="utf-8" />+ <meta http-equiv="X-UA-Compatible" content="IE=edge" />+ <title>Sonar Control · three.ws</title>+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />+ <meta name="description" content="Control a 3D agent with your hands and no camera. three.ws emits an inaudible tone through your speakers and reads the Doppler shift off your microphone, so a sweep, a push or a lift moves the avatar on screen." />+ <meta name="theme-color" content="#000000" />+ <link rel="canonical" href="https://three.ws/sonar" />++ <meta property="og:type" content="website" />+ <meta property="og:site_name" content="three.ws" />+ <meta property="og:title" content="Sonar Control · three.ws" />+ <meta property="og:description" content="Wave at your laptop and your 3D agent answers. Acoustic gesture control: inaudible tone out of the speakers, Doppler shift in through the microphone, no camera at any point." />+ <meta property="og:url" content="https://three.ws/sonar" />+ <meta property="og:image" content="https://three.ws/api/page-og?s=main&t=Sonar+Control&d=Control+a+3D+agent+with+your+hands+and+no+camera%3A+an+inaudible+tone+out+of+the+speakers%2C+the+Doppler+shift+in+through+the+microphone&p=%2Fsonar" />+ <meta name="twitter:card" content="summary_large_image" />+ <meta name="twitter:site" content="@trythreews" />+ <meta name="twitter:title" content="Sonar Control · three.ws" />+ <meta name="twitter:description" content="Hand control for 3D agents with no camera. Your speakers emit a tone, your hand bends it, the avatar moves." />+ <meta name="twitter:image" content="https://three.ws/api/page-og?s=main&t=Sonar+Control&d=Control+a+3D+agent+with+your+hands+and+no+camera%3A+an+inaudible+tone+out+of+the+speakers%2C+the+Doppler+shift+in+through+the+microphone&p=%2Fsonar" />++ <link rel="icon" href="/favicon.ico" sizes="any" />+ <link rel="icon" type="image/svg+xml" href="/favicon.svg" />+ <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />+ <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />+ <link rel="apple-touch-icon" href="/apple-touch-icon.png" />+ <link rel="manifest" href="/manifest.webmanifest" />+ <link rel="stylesheet" href="/style.css" />+ <link rel="stylesheet" href="/nav.css" />+ <link rel="stylesheet" href="/footer.css" />+ <link rel="stylesheet" href="/fonts/fonts.css" />+ <link rel="stylesheet" href="/sonar.css" />++ <script type="application/ld+json">{"@context":"https://schema.org","@type":"WebPage","name":"Sonar Control","description":"Acoustic gesture control for three.ws agents: an inaudible carrier tone from the speakers, the Doppler shift of your hand read off the microphone, and a 3D avatar that answers it.","url":"https://three.ws/sonar","isPartOf":{"@type":"WebSite","name":"three.ws","url":"https://three.ws"}}</script>++ <meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1">+ <meta property="og:locale" content="en_US">+ <meta property="og:image:alt" content="Sonar Control on three.ws">+ </head>+ <body class="sn-page">+ <header>+ <div id="nav-container"></div>+ </header>+ <script src="/nav.js"></script>++ <main>+ <section class="sn-hero">+ <div class="sn-hero-chip">+ <span class="sn-hero-dot" aria-hidden="true"></span>+ <span>No camera. Just sound.</span>+ </div>+ <h1>Wave at your laptop. Your agent answers.</h1>+ <p class="sn-hero-lede">+ Your speakers play a tone you cannot hear. Your hand reflects it, and the reflection+ comes back <strong>bent</strong>: higher when you move in, lower when you pull away.+ That shift is enough to read a sweep, a push and a lift, and to drive a real 3D agent+ with them. Nothing is recorded, nothing leaves the page, and the camera stays shut.+ </p>+ <div class="sn-hero-actions">+ <button type="button" class="sn-btn sn-btn--primary" data-role="start">+ Start sensing+ </button>+ <button type="button" class="sn-btn sn-btn--secondary" data-role="stop" hidden>+ Stop+ </button>+ <a class="sn-btn sn-btn--ghost" href="/gestures">The gesture vocabulary</a>+ <a class="sn-btn sn-btn--ghost" href="/docs/sonar">How it works</a>+ </div>+ <p class="sn-hero-note">+ Use the built-in speakers and microphone, and keep the volume up. Headphones break the+ reflection path, so the sensing has nothing to read.+ <strong>The carrier sits near 20 kHz: cats and dogs can hear it,</strong> so stop+ if a pet in the room seems bothered.+ </p>+ </section>++ <div class="sn-alert sn-alert--warn" data-role="unsupported" hidden>+ <h2>This browser cannot run the sensor</h2>+ <p data-role="unsupported-reason">+ Acoustic sensing needs Web Audio and microphone input. Safari, Chrome, Edge and Firefox+ on a laptop all qualify.+ </p>+ <p>+ The keyboard controls below work regardless, and+ <a href="/gestures">the gesture vocabulary</a> is browsable without any hardware.+ </p>+ </div>++ <div class="sn-alert sn-alert--error" data-role="error" hidden>+ <h2 data-role="error-title">Sensing stopped</h2>+ <p data-role="error-detail"></p>+ <button type="button" class="sn-btn sn-btn--secondary" data-role="retry">Try again</button>+ </div>++ <section class="sn-console" aria-label="Sonar console">+ <div class="sn-stage-wrap">+ <div class="sn-stage" data-role="stage" aria-label="Live 3D agent">+ <div class="sn-stage-overlay" data-role="stage-empty">+ <p class="sn-stage-title">The stage is idle</p>+ <p class="sn-stage-sub">Press <strong>Start sensing</strong>, or use the keyboard controls to drive it without a microphone.</p>+ </div>+ <div class="sn-stage-overlay" data-role="stage-loading" hidden>+ <div class="sn-spinner" aria-hidden="true"></div>+ <p class="sn-stage-sub">Loading the agent</p>+ </div>+ <div class="sn-stage-overlay" data-role="stage-error" hidden>+ <p class="sn-stage-title" data-role="stage-error-title">The clip could not be staged</p>+ <p class="sn-stage-sub">Every other gesture still works. Sweep again to move on.</p>+ </div>+ </div>++ <div class="sn-hud" data-role="hud">+ <div class="sn-hud-row">+ <span class="sn-hud-label">Motion</span>+ <span class="sn-hud-value" data-role="hud-direction">Not sensing</span>+ </div>+ <div class="sn-meter" role="img" aria-label="Reflected motion strength" data-role="hud-meter">+ <span class="sn-meter-fill" data-role="hud-strength"></span>+ </div>+ <div class="sn-hud-row sn-hud-row--small">+ <span data-role="hud-tone">Carrier off</span>+ <span data-role="hud-snr">Contrast off</span>+ </div>+ </div>++ <div class="sn-calibrating" data-role="calibrating" hidden>+ <p class="sn-calibrating-title">Measuring the room</p>+ <p class="sn-calibrating-sub">Hold still. Everything the microphone hears right now becomes the baseline that your hand is measured against.</p>+ <div class="sn-progress"><span data-role="calibrating-bar"></span></div>+ </div>+ </div>++ <div class="sn-side">+ <div class="sn-panel">+ <h2 class="sn-panel-title">Signal</h2>+ <p class="sn-panel-sub">+ The carrier and 600 Hz either side of it. Grey is the still room. Green is+ what is coming back right now: energy to the <em>right</em> of the spike is a hand+ closing in, to the <em>left</em> is a hand pulling away.+ </p>+ <canvas data-role="signal" class="sn-signal" width="640" height="180" aria-label="Live spectrum around the carrier tone"></canvas>+ <p class="sn-signal-legend">+ <span class="sn-key sn-key--base"></span> still room+ <span class="sn-key sn-key--live"></span> live+ <span class="sn-key sn-key--carrier"></span> carrier+ </p>+ </div>++ <div class="sn-panel">+ <h2 class="sn-panel-title">Controls</h2>+ <fieldset class="sn-modes" data-role="modes">+ <legend>Gesture in play</legend>+ <p class="sn-modes-note">+ The microphone senses distance, not direction, so a sweep and a push look+ alike coming in. Pick the one you are making; <em>All three</em> runs every+ detector at once and will misread more often.+ </p>+ <div class="sn-modes-row"></div>+ </fieldset>+ <div class="sn-control">+ <label for="sn-volume">Carrier level</label>+ <input type="range" id="sn-volume" data-role="volume" min="1" max="20" step="1" value="8" />+ <output data-role="volume-out">8%</output>+ </div>+ <div class="sn-control">+ <label for="sn-tone">Carrier</label>+ <select id="sn-tone" data-role="tone"></select>+ </div>+ <div class="sn-toggles">+ <label><input type="checkbox" data-role="reverse-swipe" /> Reverse sweep</label>+ <label><input type="checkbox" data-role="reverse-zoom" /> Reverse push</label>+ </div>+ <div class="sn-control-actions">+ <button type="button" class="sn-btn sn-btn--secondary" data-role="recalibrate" disabled>Re-measure the room</button>+ <button type="button" class="sn-btn sn-btn--ghost" data-role="reset-view">Reset the shot</button>+ </div>+ </div>+ </div>+ </section>++ <section class="sn-vocab" aria-label="What each gesture does">+ <h2 class="sn-section-title">Three gestures</h2>+ <div class="sn-cards">+ <article class="sn-card" data-gesture="swipe">+ <div class="sn-card-icon" aria-hidden="true">↔</div>+ <h3>Sweep sideways</h3>+ <p>Palm down over the keyboard, sweep across, then pause before sweeping back. Each sweep steps to the next gesture in the agent's vocabulary.</p>+ <p class="sn-card-live" data-role="live-swipe">Waiting</p>+ <p class="sn-card-keys">Keyboard: <kbd>←</kbd> <kbd>→</kbd></p>+ </article>+ <article class="sn-card" data-gesture="push">+ <div class="sn-card-icon" aria-hidden="true">⤢</div>+ <h3>Push and pull</h3>+ <p>Push your palm toward the screen to move the camera in. Pull back and it eases out, paced by how fast your hand actually moves.</p>+ <p class="sn-card-live" data-role="live-push">Waiting</p>+ <p class="sn-card-keys">Keyboard: <kbd>+</kbd> <kbd>−</kbd></p>+ </article>+ <article class="sn-card" data-gesture="lift">+ <div class="sn-card-icon" aria-hidden="true">↕</div>+ <h3>Lift and hold</h3>+ <p>Raise your hand off the keyboard and hold it there. The camera turns around the agent for as long as you hold, and settles when you lower it.</p>+ <p class="sn-card-live" data-role="live-lift">Waiting</p>+ <p class="sn-card-keys">Keyboard: <kbd>[</kbd> <kbd>]</kbd></p>+ </article>+ </div>+ </section>++ <section class="sn-log-section" aria-label="Recognised gestures">+ <div class="sn-log-head">+ <h2 class="sn-section-title">What it read</h2>+ <span class="sn-log-count" data-role="log-count">Nothing yet</span>+ </div>+ <ol class="sn-log" data-role="log" aria-live="polite">+ <li class="sn-log-empty" data-role="log-empty">+ Every gesture the sensor recognises lands here, with the reading that triggered it.+ A run of misreads is usually the carrier: try a different one in Controls.+ </li>+ </ol>+ </section>++ <section class="sn-explain">+ <h2 class="sn-section-title">Why this works</h2>+ <div class="sn-explain-grid">+ <div>+ <h3>The Doppler effect, indoors</h3>+ <p>+ A siren drops in pitch as it passes you. The same thing happens to a 20 kHz+ tone reflecting off your hand, only the shift is a few hertz rather than a few+ hundred. Averaging the room while you hold still gives a reference, and anything+ that appears beside the carrier afterwards is something that moved.+ </p>+ </div>+ <div>+ <h3>Distance, not direction</h3>+ <p>+ The microphone only senses whether something got closer or further away. A sweep+ is read as one coherent approach followed by its retreat, which is why pausing+ before you sweep back matters: without the pause, the return stroke reads as a+ second sweep in the other direction.+ </p>+ </div>+ <div>+ <h3>Standing on prior work</h3>+ <p>+ The technique is <a href="https://www.microsoft.com/en-us/research/project/soundwave-using-the-doppler-effect-to-sense-gestures/" rel="noopener">SoundWave</a>+ (Gupta, Morris, Patel and Tan, CHI 2012). The detectors here are ported from+ <a href="https://github.com/nirholas/sonar.cool" rel="noopener">Sonar</a>, Emanuel Perez's+ MIT-licensed macOS implementation, with+ <a href="https://github.com/DanielRapp/doppler" rel="noopener">Daniel Rapp's Doppler</a>+ as the prior art for doing it in a browser at all.+ </p>+ </div>+ <div>+ <h3>Take it with you</h3>+ <p>+ The sensor and the detectors are two plain modules with no 3D and no DOM in them.+ Point them at anything: a slide deck, a kiosk, an+ <a href="/docs/embedding">embedded agent</a>. The+ <a href="/docs/sonar">developer reference</a> has the whole surface.+ </p>+ </div>+ </div>+ </section>+ </main>++ <div id="footer-container"></div>+ <script src="/footer.js" defer></script>++ <script type="module" src="/src/sonar-page.js"></script>+ <!-- Runtime i18n: detects locale, swaps annotated copy, mounts <lang-switcher>. -->+ <script type="module" src="/i18n.js"></script>+ </body>+</html>diff --git a/public/changelog-recent.json b/public/changelog-recent.jsonindex a808c5ac0..ffcdf00a8 100644--- a/public/changelog-recent.json+++ b/public/changelog-recent.json@@ -1,14 +1,24 @@{- "generated_at": "2026-09-10T15:26:08.096Z",+ "generated_at": "2026-09-10T15:46:14.944Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws","url": "https://three.ws"},- "total": 3665,+ "total": 3667,"complete": false,"full_feed": "/changelog.json","entries": [+ {+ "date": "2026-09-10",+ "type": "launch",+ "title": "Sonar Control",+ "summary": "Control a 3D agent with your hands and no camera. three.ws plays an inaudible carrier tone through your speakers and reads the Doppler shift of your hand off the microphone, so a sweep, a push or a lift moves the avatar on screen.",+ "link": "/sonar",+ "tags": [+ "launch"+ ]+ },{"date": "2026-09-10","type": "update",@@ -41,6 +51,16 @@"improvement"]},+ {+ "date": "2026-09-10",+ "type": "update",+ "title": "Control a 3D agent with your hands, no camera needed",+ "summary": "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.",+ "link": "/sonar",+ "tags": [+ "feature"+ ]+ },{"date": "2026-09-10","type": "update",@@ -1596,27 +1616,6 @@"tags": ["fix"]- },- {- "date": "2026-09-07",- "type": "update",- "title": "The partner-hosted demo page loads all of its pieces again",- "summary": "Our partnership page is published once onto a partner's own website, so everything it loads comes from three.ws across origins. Two of its scripts were being refused by the browser there, which quietly cost the page its in-editor map and its iOS handoff. Both are now served with the same cross-origin permission the rest of the page already had, and an audit that loads the page from a foreign origin now passes end to end.",- "link": null,- "tags": [- "fix"- ]- },- {- "date": "2026-09-07",- "type": "update",- "title": "The splat viewer opens the compressed formats captures actually ship",- "summary": "Gaussian-splat scenes used to arrive as enormous PLY files, and the tools that make them now export compressed containers instead: the same capture that is a gigabyte of PLY is about 100 MB as SPZ and about 42 MB as SOG. The viewer could not open either. It now reads .spz and .sog alongside .ply, .splat, and .ksplat, works out the format from the file contents instead of trusting the filename, and frames the camera on the scene it actually loaded rather than a fixed distance that suited one file in ten. It also shows the real splat count, and waits for the first sorted frame before going live so a slow machine no longer shows an empty stage.",- "link": "/splat",- "tags": [- "improvement",- "feature"- ]}]}diff --git a/public/changelog.json b/public/changelog.jsonindex 0cbb72ac7..0b6beac7f 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,11 +1,21 @@{- "generated_at": "2026-09-10T15:26:08.075Z",+ "generated_at": "2026-09-10T15:46:14.923Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws","url": "https://three.ws"},"entries": [+ {+ "date": "2026-09-10",+ "type": "launch",+ "title": "Sonar Control",+ "summary": "Control a 3D agent with your hands and no camera. three.ws plays an inaudible carrier tone through your speakers and reads the Doppler shift of your hand off the microphone, so a sweep, a push or a lift moves the avatar on screen.",+ "link": "/sonar",+ "tags": [+ "launch"+ ]+ },{"date": "2026-09-10","type": "update",@@ -38,6 +48,16 @@"improvement"]},+ {+ "date": "2026-09-10",+ "type": "update",+ "title": "Control a 3D agent with your hands, no camera needed",+ "summary": "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.",+ "link": "/sonar",+ "tags": [+ "feature"+ ]+ },{"date": "2026-09-10","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex b9323c1a5..2037ffda6 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -6,6 +6,14 @@<atom:link href="https://three.ws/changelog.xml" rel="self" type="application/rss+xml"/><description>What's new on three.ws: features, improvements, and releases, newest first.</description><language>en</language>+ <item>+ <title>Sonar Control</title>+ <link>https://three.ws/sonar</link>+ <guid isPermaLink="false">2026-09-10:Sonar Control</guid>+ <pubDate>Thu, 10 Sep 2026 12:00:00 GMT</pubDate>+ <category>launch</category>+ <description>Control a 3D agent with your hands and no camera. three.ws plays an inaudible carrier tone through your speakers and reads the Doppler shift of your hand off the microphone, so a sweep, a push or a lift moves the avatar on screen.</description>+ </item><item><title>3D assets now load on any website, not just ours</title><link>https://three.ws/changelog</link>@@ -30,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>Control a 3D agent with your hands, no camera needed</title>+ <link>https://three.ws/sonar</link>+ <guid isPermaLink="false">2026-09-10:Control a 3D agent with your hands, no camera needed</guid>+ <pubDate>Thu, 10 Sep 2026 12:00:00 GMT</pubDate>+ <category>feature</category>+ <description>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.</description>+ </item><item><title>Generated motion clips rebuilt so they no longer slide across the floor</title><link>https://three.ws/animations</link>diff --git a/public/features.json b/public/features.jsonindex b9d678978..c6ce22fcb 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-09-10T15:26:08.064Z",+ "generated_at": "2026-09-10T15:46:14.912Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",@@ -66,6 +66,16 @@"tags": [],"showcase": false},+ {+ "path": "/sonar",+ "title": "Sonar Control",+ "description": "Control a 3D agent with your hands and no camera. three.ws plays an inaudible carrier tone through your speakers and reads the Doppler shift of your hand off the microphone, so a sweep, a push or a lift moves the avatar on screen.",+ "added": "2026-09-10",+ "auth": null,+ "indexable": true,+ "tags": [],+ "showcase": false+ },{"path": "/choreograph","title": "Choreographer",@@ -6038,6 +6048,16 @@"tags": [],"showcase": false},+ {+ "path": "/docs/sonar",+ "title": "Docs · Sonar",+ "description": "The developer reference for acoustic gesture control: the Doppler sensor and its Reading, the three detectors ported from Sonar and SoundWave, why running more than one at a time needs a mode, and what the technique needs from the room.",+ "added": null,+ "auth": null,+ "indexable": true,+ "tags": [],+ "showcase": false+ },{"path": "/docs/architecture","title": "Docs · Architecture overview",diff --git a/public/llms-full.txt b/public/llms-full.txtindex 7d0fedbd1..a5aa66917 100644--- a/public/llms-full.txt+++ b/public/llms-full.txt@@ -44,6 +44,12 @@ URL: https://three.ws/gesturesThe three.ws agent gesture vocabulary: every animation slot, the clip it plays, the skills that trigger it, and a builder for overriding any slot on your own agent. Previewed live on a real avatar.+### Sonar Control++URL: https://three.ws/sonar++Control a 3D agent with your hands and no camera. three.ws plays an inaudible carrier tone through your speakers and reads the Doppler shift of your hand off the microphone, so a sweep, a push or a lift moves the avatar on screen.+### ChoreographerURL: https://three.ws/choreograph@@ -3670,6 +3676,12 @@ URL: https://three.ws/docs/choreographyThe developer reference for agent gesture routines: the routine format, the storage and manifest fields, the URL wire format that makes a link a routine, and every way to play one from an embed or your own renderer.+### Docs · Sonar++URL: https://three.ws/docs/sonar++The developer reference for acoustic gesture control: the Doppler sensor and its Reading, the three detectors ported from Sonar and SoundWave, why running more than one at a time needs a mode, and what the technique needs from the room.+### Docs · Architecture overviewURL: https://three.ws/docs/architecturediff --git a/public/llms.txt b/public/llms.txtindex 3cad562d2..4759947a6 100644--- a/public/llms.txt+++ b/public/llms.txt@@ -36,6 +36,7 @@ Entry points into the product.- [Avatar Gallery](https://three.ws/gallery): Every public 3D avatar in the system, browsable as a grid.- [Animation Gallery](https://three.ws/animations): Browse and preview public animations authored by the three.ws community. Apply any clip to your avatar in the Animation Studio.- [Agent Gestures](https://three.ws/gestures): The three.ws agent gesture vocabulary: every animation slot, the clip it plays, the skills that trigger it, and a builder for overriding any slot on your own agent. Previewed live on a real avatar.+- [Sonar Control](https://three.ws/sonar): Control a 3D agent with your hands and no camera. three.ws plays an inaudible carrier tone through your speakers and reads the Doppler shift of your hand off the microphone, so a sweep, a push or a lift moves the avatar on screen.- [Choreographer](https://three.ws/choreograph): Compose agent gestures into a timed routine on a real timeline, preview the whole performance on a live 3D avatar, then save it to your agent and play it by name from any embed.- [Character Library](https://three.ws/character-library): Professionally rigged 3D characters, free to use. Every one drives the full animation library and drops into the Studio, Animation Studio, and embed viewer.- [Sign Language Avatars](https://three.ws/sign-language): three.ws avatars sign in American Sign Language: fingerspell any word or number, get signed chat replies, and sign back with your webcam. The whole loop, live in 3D.@@ -627,6 +628,7 @@ Docs, tutorials, and reference.- [Docs · Agents vs. avatars](https://three.ws/docs/agents-vs-avatars): three.ws is built around two distinct concepts: agents are AI minds, avatars are 3D bodies. The short, plain-language explanation of which is which, how they combine, and why the distinction matters when you go looking for a feature.- [Docs · Animations](https://three.ws/docs/animations): The motion clips (idle, wave, dance, and about 3,000 more) that bring three.ws avatars to life: how the registry is organised, how clips load at runtime, how they retarget onto any humanoid rig, and how to preview every one in the browser.- [Docs · Choreography](https://three.ws/docs/choreography): The developer reference for agent gesture routines: the routine format, the storage and manifest fields, the URL wire format that makes a link a routine, and every way to play one from an embed or your own renderer.+- [Docs · Sonar](https://three.ws/docs/sonar): The developer reference for acoustic gesture control: the Doppler sensor and its Reading, the three detectors ported from Sonar and SoundWave, why running more than one at a time needs a mode, and what the technique needs from the room.- [Docs · Architecture overview](https://three.ws/docs/architecture): The engineering map of three.ws: how a request flows from the browser through the route table to a handler, where 3D generation runs, how state is stored, and which layer to extend when you want to add something.- [Docs · Avatar creation](https://three.ws/docs/avatar-creation): The three ways to give an agent a 3D body: generate one from a photo, build one in the browser with the avatar builder, or upload your own GLB. What each path costs, what each produces, and when to choose which.- [Docs · Avatar inspector](https://three.ws/docs/avatar-inspector): Every avatar you meet in a three.ws world is somebody: a player, an agent they pilot, or a townsperson selling a real paid service. Press I on anyone to see their reputation, wallet, and profile without leaving the world.diff --git a/public/sitemap/index.html b/public/sitemap/index.htmlindex f40dd6600..e87fc1331 100644--- a/public/sitemap/index.html+++ b/public/sitemap/index.html@@ -96,7 +96,7 @@<main class="sm-wrap"><div class="sm-hero"><h1>Sitemap</h1>- <p>All 928 pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</p>+ <p>All 930 pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</p><div class="sm-formats"><a href="/sitemap.xml"><code>sitemap.xml</code> · for search engines</a><a href="/llms.txt"><code>llms.txt</code> · for AI agents</a>@@ -108,7 +108,7 @@</div><div class="sm-filter"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="11" cy="11" r="7"/><path d="m21 21-4.3-4.3"/></svg>- <input id="sm-filter-input" type="search" placeholder="Filter 928 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />+ <input id="sm-filter-input" type="search" placeholder="Filter 930 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" /><kbd id="sm-filter-kbd" aria-hidden="true">/</kbd></div><p class="sm-filter-count" role="status" aria-live="polite"><span id="sm-filter-count"></span><span id="sm-filter-hint" aria-hidden="true"></span></p>@@ -116,6 +116,14 @@<h2 id="sm-new-title">Newest<a class="sm-new-more" href="/changelog">full changelog →</a></h2><p class="sm-section-desc">The 9 most recently launched pages, straight to the live surface.</p><ul class="sm-list">+ <li>+ <a href="/sonar">+ <span class="sm-new-date">Sep 10, 2026</span>+ <span class="sm-title">Sonar Control</span>+ <span class="sm-path">/sonar</span>+ <span class="sm-desc">Control a 3D agent with your hands and no camera. three.ws plays an inaudible carrier tone through your speakers and reads the Doppler shift of your hand off the microphone, so a sweep, a push or a lift moves the avatar on screen.</span>+ </a>+ </li><li><a href="/fade"><span class="sm-new-date">Sep 9, 2026</span>@@ -180,14 +188,6 @@<span class="sm-desc">A live onchain trading desk for any Robinhood Chain (4663) wallet: book value, native balance history rebuilt from the indexer, an activity tape of swaps and transfers, positions priced against Chainlink NAV and the deepest Uniswap pool, the NAV premium ridge layered by pool depth, counterparty flow, and memecoin movers.</span></a></li>- <li>- <a href="/markets/robinhood/portfolios">- <span class="sm-new-date">Sep 7, 2026</span>- <span class="sm-title">Robinhood Portfolios</span>- <span class="sm-path">/markets/robinhood/portfolios</span>- <span class="sm-desc">Describe a portfolio in a sentence and get a real basket of Robinhood Chain assets: tokenized equities, crypto majors and chain-native tokens in one index. A screen ranks the whole 700-asset universe against the prompt, the weights are committed on-chain as a signed immutable manifest, and a vault holds the basket in kind and rebalances it back to target on a published schedule.</span>- </a>- </li></ul></section><nav class="sm-toc" aria-label="Sections">@@ -205,7 +205,7 @@</nav><section class="sm-section" id="main"><header>- <h2>Main<span class="sm-count" data-count>58</span></h2>+ <h2>Main<span class="sm-count" data-count>59</span></h2><p class="sm-section-desc">Entry points into the product.</p></header><ul class="sm-list">@@ -244,6 +244,13 @@<span class="sm-desc">The three.ws agent gesture vocabulary: every animation slot, the clip it plays, the skills that trigger it, and a builder for overriding any slot on your own agent. Previewed live on a real avatar.</span></a></li>+ <li>+ <a href="/sonar">+ <span class="sm-title">Sonar Control</span>+ <span class="sm-path">/sonar</span>+ <span class="sm-desc">Control a 3D agent with your hands and no camera. three.ws plays an inaudible carrier tone through your speakers and reads the Doppler shift of your hand off the microphone, so a sweep, a push or a lift moves the avatar on screen.</span>+ </a>+ </li><li><a href="/choreograph"><span class="sm-title">Choreographer</span>@@ -2555,7 +2562,7 @@<section class="sm-section" id="learn"><header>- <h2>Learn<span class="sm-count" data-count>428</span></h2>+ <h2>Learn<span class="sm-count" data-count>429</span></h2><p class="sm-section-desc">Docs, tutorials, and reference.</p></header><ul class="sm-list">@@ -4449,6 +4456,13 @@<span class="sm-desc">The developer reference for agent gesture routines: the routine format, the storage and manifest fields, the URL wire format that makes a link a routine, and every way to play one from an embed or your own renderer.</span></a></li>+ <li>+ <a href="/docs/sonar">+ <span class="sm-title">Docs · Sonar</span>+ <span class="sm-path">/docs/sonar</span>+ <span class="sm-desc">The developer reference for acoustic gesture control: the Doppler sensor and its Reading, the three detectors ported from Sonar and SoundWave, why running more than one at a time needs a mode, and what the technique needs from the room.</span>+ </a>+ </li><li><a href="/docs/architecture"><span class="sm-title">Docs · Architecture overview</span>diff --git a/public/sonar.css b/public/sonar.cssnew file mode 100644index 000000000..9f82d7060--- /dev/null+++ b/public/sonar.css@@ -0,0 +1,569 @@+/* /sonar: acoustic gesture control.+ *+ * Page-scoped tokens layer over /style.css so the page follows the site theme+ * in both directions (the theme boot script stamps data-theme on <html>).+ * The one colour that carries meaning is --sn-live: it is the "something moved"+ * green, and it is the only place the page uses saturation.+ */++:root {+ --sn-radius: 14px;+ --sn-border: rgba(255, 255, 255, 0.08);+ --sn-border-strong: rgba(255, 255, 255, 0.2);+ --sn-surface: rgba(255, 255, 255, 0.03);+ --sn-surface-2: rgba(255, 255, 255, 0.06);+ --sn-surface-3: rgba(255, 255, 255, 0.1);+ --sn-accent: #7dd3fc;+ --sn-accent-ink: #04141f;+ --sn-muted: rgba(255, 255, 255, 0.6);+ --sn-live: #4ade80;+ --sn-warn: #fbbf24;+ --sn-error: #f87171;+}+:root[data-theme='light'] {+ --sn-border: rgba(0, 0, 0, 0.1);+ --sn-border-strong: rgba(0, 0, 0, 0.24);+ --sn-surface: rgba(0, 0, 0, 0.03);+ --sn-surface-2: rgba(0, 0, 0, 0.05);+ --sn-surface-3: rgba(0, 0, 0, 0.09);+ --sn-accent: #0369a1;+ --sn-accent-ink: #f8fbff;+ --sn-muted: rgba(0, 0, 0, 0.58);+ --sn-live: #15803d;+ --sn-warn: #a16207;+ --sn-error: #b91c1c;+}++.sn-page {+ min-height: 100vh;+ background: var(--bg, #000);+ color: var(--text, #fafafa);+ font-family: 'Inter', system-ui, -apple-system, sans-serif;+ -webkit-font-smoothing: antialiased;+}++.sn-page main {+ max-width: 1360px;+ margin: 0 auto;+ padding: 0 clamp(16px, 4vw, 40px) 96px;+}++/* ── hero ─────────────────────────────────────────────────────────────── */++.sn-hero {+ padding: clamp(40px, 7vw, 88px) 0 clamp(24px, 4vw, 40px);+ max-width: 780px;+}++.sn-hero-chip {+ display: inline-flex;+ align-items: center;+ gap: 8px;+ padding: 6px 12px;+ border: 1px solid var(--sn-border);+ border-radius: 999px;+ background: var(--sn-surface);+ font-size: 12px;+ letter-spacing: 0.04em;+ text-transform: uppercase;+ color: var(--sn-muted);+}++.sn-hero-dot {+ width: 7px;+ height: 7px;+ border-radius: 50%;+ background: var(--sn-live);+ box-shadow: 0 0 0 0 color-mix(in srgb, var(--sn-live) 60%, transparent);+ animation: sn-pulse 2.4s ease-out infinite;+}++@keyframes sn-pulse {+ 0% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--sn-live) 55%, transparent); }+ 70% { box-shadow: 0 0 0 9px transparent; }+ 100% { box-shadow: 0 0 0 0 transparent; }+}++.sn-hero h1 {+ margin: 18px 0 14px;+ font-size: clamp(32px, 5.2vw, 54px);+ line-height: 1.04;+ letter-spacing: -0.03em;+}++.sn-hero-lede {+ margin: 0 0 24px;+ font-size: clamp(15px, 1.5vw, 18px);+ line-height: 1.6;+ color: var(--sn-muted);+}++.sn-hero-lede strong { color: var(--text, #fafafa); }++.sn-hero-actions {+ display: flex;+ flex-wrap: wrap;+ gap: 10px;+ margin-bottom: 20px;+}++.sn-hero-note {+ margin: 0;+ font-size: 13px;+ line-height: 1.6;+ color: var(--sn-muted);+ max-width: 62ch;+}++.sn-hero-note strong { color: var(--sn-warn); }++/* ── buttons ──────────────────────────────────────────────────────────── */++.sn-btn {+ display: inline-flex;+ align-items: center;+ justify-content: center;+ gap: 8px;+ padding: 10px 18px;+ border-radius: 10px;+ border: 1px solid var(--sn-border);+ background: var(--sn-surface-2);+ color: inherit;+ font: inherit;+ font-size: 14px;+ font-weight: 500;+ text-decoration: none;+ cursor: pointer;+ transition: background 0.16s ease, border-color 0.16s ease, transform 0.12s ease;+}++.sn-btn:hover { background: var(--sn-surface-3); border-color: var(--sn-border-strong); }+.sn-btn:active { transform: translateY(1px); }+.sn-btn:focus-visible { outline: 2px solid var(--sn-accent); outline-offset: 2px; }+.sn-btn[disabled] { opacity: 0.45; cursor: not-allowed; transform: none; }++.sn-btn--primary {+ background: var(--sn-accent);+ border-color: transparent;+ color: var(--sn-accent-ink);+ font-weight: 600;+}+.sn-btn--primary:hover { background: color-mix(in srgb, var(--sn-accent) 88%, white); }+.sn-btn--ghost { background: transparent; }++/* ── alerts ───────────────────────────────────────────────────────────── */++.sn-alert {+ margin: 0 0 28px;+ padding: 18px 20px;+ border-radius: var(--sn-radius);+ border: 1px solid var(--sn-border-strong);+ background: var(--sn-surface);+}++.sn-alert h2 { margin: 0 0 8px; font-size: 16px; }+.sn-alert p { margin: 0 0 10px; font-size: 14px; line-height: 1.6; color: var(--sn-muted); }+.sn-alert p:last-of-type { margin-bottom: 0; }+.sn-alert--warn { border-color: color-mix(in srgb, var(--sn-warn) 45%, transparent); }+.sn-alert--error { border-color: color-mix(in srgb, var(--sn-error) 55%, transparent); }+.sn-alert--error h2 { color: var(--sn-error); }+.sn-alert .sn-btn { margin-top: 6px; }++/* ── console: stage + side panels ─────────────────────────────────────── */++.sn-console {+ display: grid;+ grid-template-columns: minmax(0, 1.35fr) minmax(320px, 0.9fr);+ gap: 20px;+ align-items: start;+}++.sn-stage-wrap {+ position: relative;+ border-radius: var(--sn-radius);+ border: 1px solid var(--sn-border);+ background:+ radial-gradient(120% 80% at 50% 0%, var(--sn-surface-2), transparent 70%),+ var(--sn-surface);+ overflow: hidden;+}++.sn-stage {+ position: relative;+ aspect-ratio: 4 / 3;+ min-height: 380px;+ display: grid;+ place-items: center;+}++.sn-stage canvas { display: block; }++.sn-stage-overlay {+ position: absolute;+ inset: 0;+ display: grid;+ place-content: center;+ justify-items: center;+ gap: 8px;+ padding: 24px;+ text-align: center;+ pointer-events: none;+}++.sn-stage-title { margin: 0; font-size: 16px; font-weight: 600; }+.sn-stage-sub { margin: 0; font-size: 13px; line-height: 1.6; color: var(--sn-muted); max-width: 44ch; }++.sn-spinner {+ width: 26px;+ height: 26px;+ border-radius: 50%;+ border: 2px solid var(--sn-border-strong);+ border-top-color: var(--sn-accent);+ animation: sn-spin 0.8s linear infinite;+}++@keyframes sn-spin { to { transform: rotate(360deg); } }++/* HUD over the stage */++.sn-hud {+ position: absolute;+ left: 14px;+ right: 14px;+ bottom: 14px;+ padding: 12px 14px;+ border-radius: 12px;+ border: 1px solid var(--sn-border);+ background: color-mix(in srgb, var(--bg, #000) 70%, transparent);+ backdrop-filter: blur(10px);+ display: grid;+ gap: 8px;+ transition: border-color 0.2s ease;+}++.sn-hud[data-direction='approaching'],+.sn-hud[data-direction='away'] { border-color: color-mix(in srgb, var(--sn-live) 55%, transparent); }+.sn-hud[data-direction='weak-tone'] { border-color: color-mix(in srgb, var(--sn-warn) 55%, transparent); }++.sn-hud-row {+ display: flex;+ align-items: baseline;+ justify-content: space-between;+ gap: 12px;+ font-size: 14px;+}++.sn-hud-row--small { font-size: 12px; color: var(--sn-muted); font-variant-numeric: tabular-nums; }+.sn-hud-label { font-size: 11px; letter-spacing: 0.06em; text-transform: uppercase; color: var(--sn-muted); }+.sn-hud-value { font-weight: 600; text-align: right; }++.sn-meter {+ height: 5px;+ border-radius: 999px;+ background: var(--sn-surface-3);+ overflow: hidden;+}++.sn-meter-fill {+ display: block;+ height: 100%;+ width: 0%;+ border-radius: inherit;+ background: var(--sn-accent);+ transition: width 0.08s linear, background 0.2s ease;+}++.sn-meter-fill.is-hot { background: var(--sn-live); }++/* Calibration curtain */++.sn-calibrating {+ position: absolute;+ inset: 0;+ display: grid;+ place-content: center;+ justify-items: center;+ gap: 10px;+ padding: 28px;+ text-align: center;+ background: color-mix(in srgb, var(--bg, #000) 82%, transparent);+ backdrop-filter: blur(4px);+}++.sn-calibrating-title { margin: 0; font-size: 17px; font-weight: 600; }+.sn-calibrating-sub { margin: 0; font-size: 13px; line-height: 1.6; color: var(--sn-muted); max-width: 46ch; }++.sn-progress {+ width: min(280px, 70vw);+ height: 4px;+ border-radius: 999px;+ background: var(--sn-surface-3);+ overflow: hidden;+}++.sn-progress span {+ display: block;+ height: 100%;+ width: 0%;+ background: var(--sn-accent);+ transition: width 0.12s linear;+}++/* ── side panels ──────────────────────────────────────────────────────── */++.sn-side { display: grid; gap: 20px; }++.sn-panel {+ padding: 18px;+ border-radius: var(--sn-radius);+ border: 1px solid var(--sn-border);+ background: var(--sn-surface);+}++.sn-panel-title { margin: 0 0 6px; font-size: 14px; letter-spacing: 0.02em; }+.sn-panel-sub { margin: 0 0 12px; font-size: 12.5px; line-height: 1.6; color: var(--sn-muted); }++.sn-signal {+ display: block;+ width: 100%;+ height: 180px;+ border-radius: 10px;+ border: 1px solid var(--sn-border);+ background: color-mix(in srgb, var(--bg, #000) 55%, transparent);+}++.sn-signal-legend {+ display: flex;+ flex-wrap: wrap;+ align-items: center;+ gap: 6px 14px;+ margin: 10px 0 0;+ font-size: 11.5px;+ color: var(--sn-muted);+}++.sn-key { width: 14px; height: 2px; border-radius: 2px; display: inline-block; }+.sn-key--base { background: rgba(255, 255, 255, 0.4); }+:root[data-theme='light'] .sn-key--base { background: rgba(0, 0, 0, 0.4); }+.sn-key--live { background: var(--sn-live); }+.sn-key--carrier { background: var(--sn-border-strong); }++/* Modes */++.sn-modes { border: 0; margin: 0 0 16px; padding: 0; }+.sn-modes legend { padding: 0; font-size: 12px; letter-spacing: 0.05em; text-transform: uppercase; color: var(--sn-muted); }+.sn-modes-note { margin: 8px 0 10px; font-size: 12.5px; line-height: 1.6; color: var(--sn-muted); }+.sn-modes-row { display: flex; flex-wrap: wrap; gap: 8px; }++.sn-mode {+ display: inline-flex;+ align-items: center;+ gap: 7px;+ padding: 7px 12px;+ border-radius: 999px;+ border: 1px solid var(--sn-border);+ background: var(--sn-surface-2);+ font-size: 13px;+ cursor: pointer;+ transition: border-color 0.16s ease, background 0.16s ease;+}++.sn-mode:hover { border-color: var(--sn-border-strong); }+.sn-mode:has(input:checked) { border-color: var(--sn-accent); background: color-mix(in srgb, var(--sn-accent) 14%, transparent); }+.sn-mode:has(input:focus-visible) { outline: 2px solid var(--sn-accent); outline-offset: 2px; }++/* Controls */++.sn-control {+ display: grid;+ grid-template-columns: auto 1fr auto;+ align-items: center;+ gap: 10px;+ margin-bottom: 12px;+ font-size: 13px;+}++.sn-control label { color: var(--sn-muted); }+.sn-control output { font-variant-numeric: tabular-nums; color: var(--sn-muted); min-width: 4ch; text-align: right; }+.sn-control select,+.sn-control input[type='range'] { width: 100%; }++.sn-control select {+ grid-column: 2 / -1;+ padding: 7px 10px;+ border-radius: 8px;+ border: 1px solid var(--sn-border);+ background: var(--sn-surface-2);+ color: inherit;+ font: inherit;+ font-size: 13px;+}++.sn-control select:focus-visible,+.sn-control input:focus-visible { outline: 2px solid var(--sn-accent); outline-offset: 2px; }++.sn-toggles { display: grid; gap: 8px; margin: 14px 0; font-size: 13px; color: var(--sn-muted); }+.sn-toggles label { display: flex; align-items: center; gap: 8px; cursor: pointer; }+.sn-control-actions { display: flex; flex-wrap: wrap; gap: 8px; }+.sn-control-actions .sn-btn { padding: 8px 12px; font-size: 13px; }++/* ── vocabulary cards ─────────────────────────────────────────────────── */++.sn-section-title {+ margin: 0;+ font-size: clamp(19px, 2.4vw, 24px);+ letter-spacing: -0.02em;+}++.sn-vocab { margin-top: 44px; }+.sn-vocab .sn-section-title { margin-bottom: 16px; }++.sn-cards {+ display: grid;+ grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));+ gap: 14px;+}++.sn-card {+ padding: 18px;+ border-radius: var(--sn-radius);+ border: 1px solid var(--sn-border);+ background: var(--sn-surface);+ transition: opacity 0.2s ease, border-color 0.2s ease, transform 0.16s ease;+}++.sn-card:hover { transform: translateY(-2px); border-color: var(--sn-border-strong); }+.sn-card.is-off { opacity: 0.45; }+.sn-card.is-off:hover { transform: none; }+.sn-card-icon { font-size: 22px; line-height: 1; color: var(--sn-accent); }+.sn-card h3 { margin: 10px 0 8px; font-size: 15px; }+.sn-card p { margin: 0 0 8px; font-size: 13px; line-height: 1.6; color: var(--sn-muted); }++.sn-card-live {+ margin: 12px 0 8px !important;+ padding: 7px 10px;+ border-radius: 8px;+ background: var(--sn-surface-2);+ font-size: 12.5px;+ font-weight: 500;+ color: var(--sn-muted) !important;+ font-variant-numeric: tabular-nums;+}++.sn-card-live.is-live {+ color: var(--sn-accent-ink) !important;+ background: var(--sn-live);+ animation: sn-flash 0.7s ease-out;+}++@keyframes sn-flash {+ from { transform: scale(1.03); }+ to { transform: scale(1); }+}++.sn-card-keys { margin: 0 !important; font-size: 12px; }++kbd {+ display: inline-block;+ min-width: 20px;+ padding: 2px 6px;+ border-radius: 5px;+ border: 1px solid var(--sn-border-strong);+ background: var(--sn-surface-2);+ font: inherit;+ font-size: 11px;+ text-align: center;+}++/* ── log ──────────────────────────────────────────────────────────────── */++.sn-log-section { margin-top: 44px; }++.sn-log-head {+ display: flex;+ align-items: baseline;+ justify-content: space-between;+ gap: 12px;+ margin-bottom: 14px;+}++.sn-log-count { font-size: 12.5px; color: var(--sn-muted); font-variant-numeric: tabular-nums; }++.sn-log {+ list-style: none;+ margin: 0;+ padding: 0;+ border-radius: var(--sn-radius);+ border: 1px solid var(--sn-border);+ background: var(--sn-surface);+ max-height: 320px;+ overflow-y: auto;+}++.sn-log-empty {+ padding: 20px;+ font-size: 13px;+ line-height: 1.6;+ color: var(--sn-muted);+}++.sn-log-row {+ display: grid;+ grid-template-columns: 78px 110px minmax(0, 1fr) minmax(0, 1.2fr);+ gap: 12px;+ align-items: baseline;+ padding: 10px 16px;+ border-top: 1px solid var(--sn-border);+ font-size: 13px;+ animation: sn-row-in 0.24s ease-out;+}++.sn-log-row:first-child { border-top: 0; }+.sn-log-time { color: var(--sn-muted); font-variant-numeric: tabular-nums; font-size: 12px; }+.sn-log-gesture { font-weight: 600; }+.sn-log-detail { color: var(--sn-accent); }+.sn-log-evidence { color: var(--sn-muted); font-size: 12px; text-align: right; }++@keyframes sn-row-in {+ from { opacity: 0; transform: translateY(-4px); }+ to { opacity: 1; transform: none; }+}++/* ── explainer ────────────────────────────────────────────────────────── */++.sn-explain { margin-top: 52px; }+.sn-explain .sn-section-title { margin-bottom: 18px; }++.sn-explain-grid {+ display: grid;+ grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));+ gap: 22px 32px;+}++.sn-explain h3 { margin: 0 0 8px; font-size: 15px; }+.sn-explain p { margin: 0; font-size: 13.5px; line-height: 1.7; color: var(--sn-muted); }+.sn-explain a { color: var(--sn-accent); }++/* ── responsive ───────────────────────────────────────────────────────── */++@media (max-width: 1040px) {+ .sn-console { grid-template-columns: minmax(0, 1fr); }+ .sn-stage { min-height: 320px; }+}++@media (max-width: 560px) {+ .sn-stage { aspect-ratio: 3 / 4; min-height: 300px; }+ .sn-hud { left: 10px; right: 10px; bottom: 10px; padding: 10px 12px; }+ .sn-log-row { grid-template-columns: 1fr; gap: 2px; }+ .sn-log-evidence { text-align: left; }+ .sn-hero-actions .sn-btn { flex: 1 1 auto; }+}++@media (prefers-reduced-motion: reduce) {+ .sn-hero-dot,+ .sn-spinner,+ .sn-card-live.is-live,+ .sn-log-row { animation: none; }+ .sn-card:hover { transform: none; }+ .sn-btn, .sn-card, .sn-hud, .sn-meter-fill { transition: none; }+}diff --git a/src/animations-live-preview.js b/src/animations-live-preview.jsindex e3e3b67ad..54583d9b8 100644--- a/src/animations-live-preview.js+++ b/src/animations-live-preview.js@@ -26,6 +26,12 @@ export class AnimationLivePreview {this._bones = [];this._restPose = new Map();this._maps = null; // canonical maps captured at bind pose+ // Framing computed by _frameCamera, plus the viewer's own offsets on top+ // of it. Kept apart so a new clip can re-frame without throwing away a+ // turn or a zoom the viewer asked for.+ this._framing = null;+ this._yaw = 0;+ this._zoom = 1;this._retargetMod = null;this._clipJsonCache = new Map(); // clip name → raw clip JSON promise@@ -247,18 +253,60 @@ export class AnimationLivePreview {const distV = size.y / 2 / Math.tan(fovV / 2);const distH = Math.max(size.x, size.z) / 2 / Math.tan(fovH / 2);const dist = Math.max(distV, distH) * 1.15 + Math.max(size.z, size.x) / 2;- const azimuth = THREE.MathUtils.degToRad(24);- const elevation = THREE.MathUtils.degToRad(11);+ this._framing = {+ center,+ dist,+ azimuth: THREE.MathUtils.degToRad(24),+ elevation: THREE.MathUtils.degToRad(11),+ };+ this._applyCamera();+ }++ /** Place the camera from the current framing plus the viewer's turn and zoom. */+ _applyCamera() {+ const f = this._framing;+ if (!f || !this._camera) return;+ const cam = this._camera;+ const azimuth = f.azimuth + this._yaw;+ const dist = f.dist / this._zoom;cam.position.set(- center.x + dist * Math.cos(elevation) * Math.sin(azimuth),- center.y + dist * Math.sin(elevation),- center.z + dist * Math.cos(elevation) * Math.cos(azimuth),+ f.center.x + dist * Math.cos(f.elevation) * Math.sin(azimuth),+ f.center.y + dist * Math.sin(f.elevation),+ f.center.z + dist * Math.cos(f.elevation) * Math.cos(azimuth),);- cam.lookAt(center);- this._keyLight.target.position.copy(center);+ cam.lookAt(f.center);+ this._keyLight.target.position.copy(f.center);this._keyLight.target.updateMatrixWorld();}+ /**+ * Turn the camera around the avatar, in radians. Additive, and it survives+ * the re-framing a crossfaded clip change does. A cold mount starts from the+ * framed shot again, so a caller holding a viewing angle across cuts+ * re-applies it after play() resolves.+ */+ orbitBy(radians) {+ this._yaw += radians;+ this._applyCamera();+ }++ /** Dolly in or out. 1 is the framed distance; clamped to a usable range. */+ setZoom(factor) {+ this._zoom = Math.max(0.6, Math.min(3, factor || 1));+ this._applyCamera();+ }++ getZoom() {+ return this._zoom;+ }++ /** Drop the viewer's turn and zoom, back to the framed shot. */+ resetView() {+ this._yaw = 0;+ this._zoom = 1;+ this._applyCamera();+ }+/** Stop every crossfade source whose fade has elapsed. */_retireFaded(incoming) {const now = performance.now();@@ -414,6 +462,8 @@ export class AnimationLivePreview {this._renderer.domElement.parentNode.removeChild(this._renderer.domElement);}this._container = null;+ this._yaw = 0;+ this._zoom = 1;}/** Modal transport controls. No-ops when nothing is playing. */diff --git a/src/sonar-page.js b/src/sonar-page.jsnew file mode 100644index 000000000..e92485684--- /dev/null+++ b/src/sonar-page.js@@ -0,0 +1,607 @@+// /sonar: acoustic gesture control for a live 3D agent.+//+// Three layers, none of which knows about the other two:+//+// • src/sonar/doppler.js emits the carrier and reports one Reading per frame+// • src/sonar/gestures.js turns Readings into sweep / push / lift events+// • this file maps those events onto the shared preview engine+//+// The mapping is the product decision: a sweep steps through the agent's+// gesture vocabulary (the same slots /gestures documents), a push dollies the+// camera, and a held lift turns it. Every one of them is also on the keyboard,+// so the page is complete on a machine with no microphone, in a browser that+// blocks one, and for anyone who is not going to wave at a laptop.++import { DopplerSensor, DIRECTION, DIRECTION_LABEL, TONE_CANDIDATES, isSupported, CALIBRATION_SECONDS } from './sonar/doppler.js';+import { SwipeDetector, PushPullDetector, LiftMotion } from './sonar/gestures.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'];++/** Camera distance for each push step. Step 0 is the framed shot. */+const ZOOM_STEPS = [1, 1.18, 1.36, 1.6];++/**+ * 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.+ */+const ORBIT_SCALE = 0.0045;++/** Which detectors are live. Running all three at once is opt-in; see MODES. */+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'] },+};+const MODE_KEY = 'twx_sonar_mode';++const q = (role) => document.querySelector(`[data-role="${role}"]`);+const qa = (role) => Array.from(document.querySelectorAll(`[data-role="${role}"]`));++const state = {+ sensor: null,+ preview: null,+ clips: new Map(), // clip name -> manifest entry+ index: 0,+ playing: null,+ zoomSteps: 0,+ yaw: 0,+ log: [],+ lastReading: null,+ swipe: new SwipeDetector(),+ push: new PushPullDetector(),+ lift: new LiftMotion(),+ liftRaf: 0,+ liftLast: 0,+ running: false,+ signalCtx: null,+ mode: 'swipe',+ liftLabelAt: 0,+ logEmpty: null,+};++/* ── copy helpers ──────────────────────────────────────────────────────── */++function setStatus(el, text) {+ if (el && el.textContent !== text) el.textContent = text;+}++function flash(role, text) {+ const el = q(role);+ if (!el) return;+ el.textContent = text;+ el.classList.remove('is-live');+ // Restarting a CSS animation needs the class to actually leave the element+ // for a frame; toggling it in the same tick is a no-op.+ requestAnimationFrame(() => el.classList.add('is-live'));+}++function showError(title, detail) {+ const box = q('error');+ if (!box) return;+ q('error-title').textContent = title;+ q('error-detail').textContent = detail;+ box.hidden = false;+}++function clearError() {+ const box = q('error');+ if (box) box.hidden = true;+}++/* ── the 3D stage ──────────────────────────────────────────────────────── */++async function getPreview() {+ if (!state.preview) {+ const mod = await import('./animations-live-preview.js');+ state.preview = mod.getLivePreview();+ }+ return state.preview;+}++function setStageState(name, detail = '') {+ q('stage-empty').hidden = name !== 'empty';+ q('stage-loading').hidden = name !== 'loading';+ q('stage-error').hidden = name !== 'error';+ if (name === 'error' && detail) q('stage-error-title').textContent = detail;+}++async function loadManifest() {+ const res = await fetch(MANIFEST_URL);+ if (!res.ok) throw new Error(`The clip manifest answered ${res.status}.`);+ for (const clip of await res.json()) state.clips.set(clip.name, clip);+}++/** Re-apply the viewer's turn and zoom after a cold mount reframes the shot. */+function applyView(preview) {+ preview.setZoom(ZOOM_STEPS[state.zoomSteps] ?? 1);+ if (state.yaw) preview.orbitBy(state.yaw);+}++/**+ * Stage the gesture at `state.index`. A one-shot clip returns to idle on its+ * own last frame rather than freezing clamped at the end of it.+ */+async function playCurrent({ crossfade = 0.25 } = {}) {+ const slot = CAST[state.index];+ const name = DEFAULT_ANIMATION_MAP[slot];+ const def = state.clips.get(name);+ if (!def) {+ setStageState('error', `"${name}" is not in the clip manifest.`);+ return;+ }+ state.playing = slot;+ if (!state.preview) setStageState('loading');+ try {+ const preview = await getPreview();+ const loop = def.loop !== false;+ await preview.play(+ q('stage'),+ { id: name, source: 'curated', url: def.url, loop },+ {+ crossfade,+ onFrame: loop+ ? null+ : (t, d) => {+ // A crossfaded one-shot does not self-replay, so hand the stage+ // back to idle as the clip lands instead of leaving the agent+ // frozen on its last pose.+ if (state.playing === slot && d && t >= d - 0.12) toIdle();+ },+ },+ );+ if (state.playing !== slot) return;+ applyView(preview);+ setStageState('none');+ } catch (err) {+ if (state.playing !== slot) return;+ setStageState('error', err?.message ? `Preview failed: ${err.message}` : undefined);+ }+}++async function toIdle() {+ const def = state.clips.get(DEFAULT_ANIMATION_MAP.idle);+ if (!def) return;+ state.playing = 'idle';+ const preview = await getPreview();+ await preview.play(+ q('stage'),+ { id: def.name, source: 'curated', url: def.url, loop: true },+ { crossfade: 0.35 },+ );+ applyView(preview);+}++/* ── the three gestures ────────────────────────────────────────────────── */++function step(direction, source) {+ state.index = (state.index + direction + CAST.length) % CAST.length;+ flash('live-swipe', `${direction > 0 ? 'Next' : 'Previous'}: ${CAST[state.index]}`);+ logEvent(direction > 0 ? 'Sweep right' : 'Sweep left', CAST[state.index], source);+ playCurrent();+}++async function applyZoom(action, source) {+ if (action > 0) state.zoomSteps = 3;+ else if (action === 0) state.zoomSteps = 0;+ else state.zoomSteps = Math.max(0, state.zoomSteps - 1);+ const preview = await getPreview();+ preview.setZoom(ZOOM_STEPS[state.zoomSteps]);+ const label = state.zoomSteps === 0 ? 'Back to the framed shot' : `Camera in, step ${state.zoomSteps}`;+ flash('live-push', label);+ if (action > 0 || action === 0) logEvent(action > 0 ? 'Push' : 'Pull, released', label, source);+}++async function orbit(radians, source) {+ state.yaw += radians;+ const preview = await getPreview();+ preview.orbitBy(radians);+ if (source === 'keyboard') {+ flash('live-lift', `Turned ${radians > 0 ? 'right' : 'left'}`);+ logEvent('Turn', `${Math.round((state.yaw * 180) / Math.PI)}°`, source);+ }+}++/* ── the log ───────────────────────────────────────────────────────────── */++function logEvent(gesture, detail, source) {+ const reading = state.lastReading;+ const evidence =+ source === 'keyboard'+ ? 'keyboard'+ : reading+ ? `${DIRECTION_LABEL[reading.direction] || reading.direction}, ${(reading.strength * 1000).toFixed(2)} units, ${reading.snr.toFixed(0)} dB contrast`+ : '';+ state.log.unshift({+ gesture,+ detail,+ evidence,+ at: new Date().toLocaleTimeString([], { hour12: false }),+ });+ state.log = state.log.slice(0, 40);+ renderLog();+}++function renderLog() {+ const list = q('log');+ if (!list) return;+ // The placeholder is pulled out of the list once and kept, because rendering+ // rows replaces the list's markup and would otherwise drop it for good.+ if (!state.logEmpty) state.logEmpty = q('log-empty');+ const empty = state.logEmpty;+ if (!state.log.length) {+ if (empty) empty.hidden = false;+ setStatus(q('log-count'), 'Nothing yet');+ return;+ }+ if (empty) empty.hidden = true;+ setStatus(q('log-count'), `${state.log.length} read`);+ const rows = state.log+ .map(+ (e) => `<li class="sn-log-row">+ <span class="sn-log-time">${e.at}</span>+ <span class="sn-log-gesture">${e.gesture}</span>+ <span class="sn-log-detail">${e.detail}</span>+ <span class="sn-log-evidence">${e.evidence}</span>+ </li>`,+ )+ .join('');+ list.innerHTML = rows;+ if (empty) list.prepend(empty);+}++/* ── the signal scope ──────────────────────────────────────────────────── */++function drawSignal(reading) {+ const canvas = q('signal');+ if (!canvas) return;+ if (!state.signalCtx) state.signalCtx = canvas.getContext('2d');+ const ctx = state.signalCtx;+ const dpr = Math.min(2, window.devicePixelRatio || 1);+ const w = canvas.clientWidth || 640;+ const h = canvas.clientHeight || 180;+ if (canvas.width !== Math.round(w * dpr) || canvas.height !== Math.round(h * dpr)) {+ canvas.width = Math.round(w * dpr);+ canvas.height = Math.round(h * dpr);+ }+ ctx.setTransform(dpr, 0, 0, dpr, 0, 0);+ ctx.clearRect(0, 0, w, h);++ if (!reading) {+ ctx.fillStyle = 'rgba(255,255,255,0.28)';+ ctx.font = '12px ui-monospace, SFMono-Regular, Menlo, monospace';+ ctx.fillText('No signal. Start sensing to see the carrier.', 12, h / 2);+ return;+ }++ const { spectrumDb, baselineDb } = reading;+ const n = spectrumDb.length;+ // A fixed window keeps the trace from rescaling under its own motion, which+ // is what makes a shift readable rather than just busy.+ const top = Math.max(reading.carrierDb, -30) + 6;+ const bottom = top - 90;+ const x = (i) => (i / (n - 1)) * w;+ const y = (db) => h - ((Math.max(bottom, Math.min(top, db)) - bottom) / (top - bottom)) * h;++ const carrierX = x((n - 1) / 2);+ ctx.strokeStyle = 'rgba(255,255,255,0.16)';+ ctx.lineWidth = 1;+ ctx.beginPath();+ ctx.moveTo(carrierX, 0);+ ctx.lineTo(carrierX, h);+ ctx.stroke();++ const trace = (values, stroke, fill) => {+ ctx.beginPath();+ for (let i = 0; i < n; i++) {+ const px = x(i);+ const py = y(values[i]);+ if (i === 0) ctx.moveTo(px, py);+ else ctx.lineTo(px, py);+ }+ ctx.strokeStyle = stroke;+ ctx.lineWidth = 1.5;+ ctx.stroke();+ if (fill) {+ ctx.lineTo(w, h);+ ctx.lineTo(0, h);+ ctx.closePath();+ ctx.fillStyle = fill;+ ctx.fill();+ }+ };++ trace(baselineDb, 'rgba(255,255,255,0.35)', null);+ const moving =+ reading.direction === DIRECTION.approaching || reading.direction === DIRECTION.away;+ trace(spectrumDb, moving ? '#4ade80' : 'rgba(120,220,170,0.75)', 'rgba(74,222,128,0.10)');+}++/* ── sensing ───────────────────────────────────────────────────────────── */++function onReading(reading) {+ state.lastReading = reading;+ drawSignal(reading);++ const calibrating = reading.calibrationRemaining !== null;+ const panel = q('calibrating');+ if (panel) panel.hidden = !calibrating;+ if (calibrating) {+ const pct = 100 * (1 - reading.calibrationRemaining / CALIBRATION_SECONDS);+ q('calibrating-bar').style.width = `${pct.toFixed(0)}%`;+ }++ setStatus(q('hud-direction'), DIRECTION_LABEL[reading.direction] || reading.direction);+ setStatus(q('hud-tone'), `Carrier ${(reading.tone / 1000).toFixed(1)} kHz`);+ setStatus(q('hud-snr'), `Contrast ${reading.snr.toFixed(0)} dB`);+ const meter = q('hud-strength');+ if (meter) {+ // Log-scaled: the interesting range spans three orders of magnitude and a+ // linear bar spends all of it pinned at either end.+ const pct = Math.min(100, Math.max(0, (Math.log1p(reading.strength / 0.0003) / Math.log1p(40)) * 100));+ meter.style.width = `${pct.toFixed(1)}%`;+ meter.classList.toggle('is-hot', reading.strength > 0.002);+ }+ const hud = q('hud');+ if (hud) hud.dataset.direction = reading.direction;++ if (reading.direction === DIRECTION.weakTone) {+ setStatus(+ q('hud-direction'),+ 'Carrier too faint. Raise the volume, or pick another carrier below.',+ );+ }++ // Only the detectors this mode owns get fed. The three gestures are not+ // separable at the hardware level: a sweep passes the microphone as 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.+ const now = performance.now() / 1000;+ const live = MODES[state.mode].detectors;++ if (live.includes('swipe')) {+ const swipe = state.swipe.feed(reading, now);+ if (swipe) {+ const reversed = q('reverse-swipe')?.checked;+ const forward = reversed ? swipe === 'previous' : swipe === 'next';+ step(forward ? 1 : -1, 'sonar');+ }+ }+ if (live.includes('push')) {+ const zoom = state.push.feed(reading, now, Boolean(q('reverse-zoom')?.checked));+ if (zoom !== null) applyZoom(zoom, 'sonar');+ }+ if (live.includes('lift')) state.lift.feed(reading, now);+}++/** Lift is continuous, so it advances on the display clock, not on readings. */+function liftLoop() {+ state.liftRaf = requestAnimationFrame(liftLoop);+ const now = performance.now() / 1000;+ const dt = state.liftLast ? Math.min(0.1, now - state.liftLast) : 0;+ state.liftLast = now;+ const travelled = state.lift.step(dt, now);+ if (!travelled) return;+ orbit(travelled * ORBIT_SCALE, 'sonar');+ // The turn updates every frame; the label does not need to.+ if (now - state.liftLabelAt > 0.2) {+ state.liftLabelAt = now;+ flash('live-lift', `Turning, ${Math.abs(state.lift.velocity).toFixed(0)} units`);+ }+}++async function start() {+ clearError();+ if (!isSupported()) return;+ q('start').disabled = true;+ setStatus(q('hud-direction'), 'Opening the microphone');+ state.sensor = new DopplerSensor({+ amplitude: Number(q('volume').value) / 100,+ onReading,+ onStatus: ({ state: s, message }) => {+ if (s === 'tuning' || s === 'starting') setStatus(q('hud-direction'), message);+ },+ });+ try {+ await state.sensor.start();+ } catch (err) {+ state.sensor = null;+ q('start').disabled = false;+ setStatus(q('hud-direction'), 'Not sensing');+ showError('The microphone could not be opened', err.message);+ return;+ }+ state.running = true;+ q('start').hidden = true;+ q('start').disabled = false;+ q('stop').hidden = false;+ q('recalibrate').disabled = false;+ syncToneSelect();+ state.swipe.reset();+ state.lift.reset();+ state.liftLast = 0;+ state.liftRaf = requestAnimationFrame(liftLoop);+ if (!state.preview) await toIdle();+}++function stop() {+ state.sensor?.stop();+ state.sensor = null;+ state.running = false;+ cancelAnimationFrame(state.liftRaf);+ state.liftRaf = 0;+ state.lift.reset();+ q('start').hidden = false;+ q('stop').hidden = true;+ q('recalibrate').disabled = true;+ const panel = q('calibrating');+ if (panel) panel.hidden = true;+ setStatus(q('hud-direction'), 'Not sensing');+ setStatus(q('hud-tone'), 'Carrier off');+ setStatus(q('hud-snr'), 'Contrast off');+ const meter = q('hud-strength');+ if (meter) meter.style.width = '0%';+ state.lastReading = null;+ drawSignal(null);+}++function syncToneSelect() {+ const select = q('tone');+ if (select && state.sensor) select.value = String(state.sensor.tone);+}++/* ── wiring ────────────────────────────────────────────────────────────── */++function buildToneSelect() {+ const select = q('tone');+ if (!select) return;+ select.innerHTML = TONE_CANDIDATES.map(+ (t) => `<option value="${t}">${(t / 1000).toFixed(1)} kHz</option>`,+ ).join('');+ select.value = String(20000);+ select.addEventListener('change', () => {+ const tone = Number(select.value);+ if (state.sensor) {+ // A hand-picked carrier is a deliberate override of the automatic pick,+ // so stop re-choosing one on the next start.+ state.sensor.autoTone = false;+ state.sensor.setTone(tone);+ }+ });+}++function buildModes() {+ const row = document.querySelector('[data-role="modes"] .sn-modes-row');+ if (!row) return;+ let saved = null;+ try {+ saved = localStorage.getItem(MODE_KEY);+ } catch {+ // A browser with storage blocked still gets the default mode.+ }+ if (saved && MODES[saved]) state.mode = saved;+ row.innerHTML = Object.entries(MODES)+ .map(+ ([key, def]) => `<label class="sn-mode">+ <input type="radio" name="sn-mode" value="${key}"${key === state.mode ? ' checked' : ''} />+ <span>${def.label}</span>+ </label>`,+ )+ .join('');+ row.addEventListener('change', (e) => {+ if (e.target.name !== 'sn-mode') return;+ state.mode = e.target.value;+ try {+ localStorage.setItem(MODE_KEY, state.mode);+ } catch {+ // Not persisting the choice is not a reason to refuse it.+ }+ // Whatever half-formed stroke the old mode was tracking is meaningless now.+ state.swipe.reset();+ state.push.clearEvidence();+ state.lift.reset();+ syncModeCards();+ });+ syncModeCards();+}++/** Dim the cards whose gesture the current mode is not listening for. */+function syncModeCards() {+ const live = MODES[state.mode].detectors;+ for (const card of document.querySelectorAll('.sn-card[data-gesture]')) {+ const on = live.includes(card.dataset.gesture);+ card.classList.toggle('is-off', !on);+ const label = q(`live-${card.dataset.gesture}`);+ if (label && !on) label.textContent = 'Not in this mode';+ else if (label && label.textContent === 'Not in this mode') label.textContent = 'Waiting';+ }+}++function bindControls() {+ q('start')?.addEventListener('click', start);+ q('stop')?.addEventListener('click', stop);+ q('retry')?.addEventListener('click', () => {+ clearError();+ start();+ });+ q('recalibrate')?.addEventListener('click', () => {+ state.sensor?.recalibrate();+ state.swipe.reset();+ state.lift.reset();+ });+ q('reset-view')?.addEventListener('click', async () => {+ state.zoomSteps = 0;+ state.yaw = 0;+ state.push.steps = 0;+ state.push.clearEvidence();+ (await getPreview()).resetView();+ flash('live-push', 'Back to the framed shot');+ });+ const volume = q('volume');+ volume?.addEventListener('input', () => {+ q('volume-out').textContent = `${volume.value}%`;+ state.sensor?.setAmplitude(Number(volume.value) / 100);+ });++ document.addEventListener('keydown', (e) => {+ if (e.metaKey || e.ctrlKey || e.altKey) return;+ const tag = e.target?.tagName;+ if (tag === 'INPUT' || tag === 'SELECT' || tag === 'TEXTAREA') return;+ const handlers = {+ ArrowRight: () => step(1, 'keyboard'),+ ArrowLeft: () => step(-1, 'keyboard'),+ '+': () => applyZoom(3, 'keyboard'),+ '=': () => applyZoom(3, 'keyboard'),+ '-': () => applyZoom(state.zoomSteps > 1 ? -1 : 0, 'keyboard'),+ ']': () => orbit(0.35, 'keyboard'),+ '[': () => orbit(-0.35, 'keyboard'),+ };+ const handler = handlers[e.key];+ if (!handler) return;+ e.preventDefault();+ handler();+ });++ // A backgrounded tab should not keep a 20 kHz tone running in someone's room.+ document.addEventListener('visibilitychange', () => {+ if (document.hidden && state.running) stop();+ });+ window.addEventListener('pagehide', () => stop());+ window.addEventListener('resize', () => drawSignal(state.lastReading));+}++async function boot() {+ bindControls();+ buildToneSelect();+ buildModes();+ drawSignal(null);+ renderLog();++ if (!isSupported()) {+ const box = q('unsupported');+ if (box) box.hidden = false;+ q('start').disabled = true;+ q('start').textContent = 'Sensing unavailable';+ setStatus(q('hud-direction'), 'Keyboard control only');+ }++ try {+ await loadManifest();+ if (isSupported()) setStatus(q('hud-direction'), 'Ready');+ } catch (err) {+ showError('The gesture library could not be loaded', err.message);+ }+}++boot();diff --git a/src/sonar/doppler.js b/src/sonar/doppler.jsnew file mode 100644index 000000000..6e22919df--- /dev/null+++ b/src/sonar/doppler.js@@ -0,0 +1,434 @@+// Acoustic motion sensing in the browser: no camera, no permissions beyond the+// microphone, no model weights.+//+// The speakers emit a steady inaudible tone. A hand moving in front of the+// laptop reflects it, and the reflection comes back frequency-shifted: higher+// when the hand approaches, lower when it recedes. That is the Doppler effect,+// and it is enough to read a sweep, a push and a lift off the microphone.+//+// The technique is SoundWave (Gupta, Morris, Patel & Tan, CHI 2012). This+// module is a port of the analysis in Emanuel Perez's Sonar+// (https://github.com/nirholas/sonar.cool, MIT), which is itself an+// independent implementation of that paper, with Daniel Rapp's browser Doppler+// as the prior art for doing it in Web Audio at all. The Swift analyzer's+// constants are reproduced exactly (8192-point transform, a 600 Hz window+// either side of the carrier, a 2.5 s baseline, the 1.7x sideband ratio), so+// the detectors in ./gestures.js keep behaving the way they were tuned to.+//+// What this file owns: the tone, the microphone, the transform, the baseline,+// and one Reading per frame. It knows nothing about gestures or about 3D.++/** Frame size of the analysis transform. Sonar's `Analyzer.n`. */+const FFT_SIZE = 8192;+/** Half-width of the analysis window around the carrier, in Hz. */+const WINDOW_HZ = 600;+/** Seconds of stillness averaged into the room baseline before sensing starts. */+export const CALIBRATION_SECONDS = 2.5;+/** Carrier-to-floor contrast below which the tone is not usable. */+const MIN_SNR_DB = 15;+/** Sideband excess below which the room counts as still. */+const MIN_STRENGTH = 0.0003;++/** Reading.direction is one of these. Detectors compare against them. */+export const DIRECTION = {+ approaching: 'approaching',+ away: 'away',+ mixed: 'mixed',+ still: 'still',+ listening: 'listening',+ calibrating: 'calibrating',+ weakTone: 'weak-tone',+};++/** Human copy for each direction, so the UI never spells these out itself. */+export const DIRECTION_LABEL = {+ [DIRECTION.approaching]: 'Approaching',+ [DIRECTION.away]: 'Moving away',+ [DIRECTION.mixed]: 'Mixed movement',+ [DIRECTION.still]: 'Still',+ [DIRECTION.listening]: 'Listening',+ [DIRECTION.calibrating]: 'Calibrating, hold still',+ [DIRECTION.weakTone]: 'Tone not clear',+};++/**+ * Carrier candidates, quietest-to-the-ear last. Laptop speakers roll off hard+ * near Nyquist and every model rolls off somewhere different, so the sensor+ * measures each one against this machine's own hardware instead of assuming+ * 20 kHz reaches the microphone (the Sonar desktop app asks the user to try+ * another frequency by hand when it does not).+ */+export const TONE_CANDIDATES = [18000, 18500, 19000, 19500, 20000, 20500, 21000];++export const DEFAULT_TONE = 20000;++/** True when this browser can run the sensor at all. */+export function isSupported() {+ return Boolean(+ typeof window !== 'undefined' &&+ (window.AudioContext || window.webkitAudioContext) &&+ navigator.mediaDevices?.getUserMedia,+ );+}++/**+ * Microphone constraints. All three cleanups have to be off: echo cancellation+ * exists specifically to remove the speaker's own output from the microphone+ * signal, which is the entire signal here. Noise suppression and AGC chew the+ * sidebands the same way.+ */+const MIC_CONSTRAINTS = {+ audio: {+ echoCancellation: false,+ noiseSuppression: false,+ autoGainControl: false,+ channelCount: 1,+ },+};++/** Wall-clock seconds. See the note in _frame for why this is not the audio clock. */+const now = () => performance.now() / 1000;++/**+ * The analyser reports a bin with no energy at all as -Infinity, which turns+ * every level comparison downstream into NaN and silently disables every+ * threshold. Digital silence in this band is a real state (a muted machine, a+ * carrier the speakers cannot project), so it is floored rather than special-cased.+ */+const FLOOR_DB = -180;+const readDb = (value) => (Number.isFinite(value) ? value : FLOOR_DB);++const dbToPower = (db) => 10 ** (db / 10);++/**+ * One analysis frame.+ *+ * @typedef {object} Reading+ * @property {Float32Array} spectrumDb the analysis window, in dB+ * @property {Float32Array} baselineDb the still-room reference, in dB+ * @property {string} direction a DIRECTION value+ * @property {number} carrierDb peak level at the carrier+ * @property {number} snr carrier minus noise floor, in dB+ * @property {number} strength sideband excess over the carrier+ * @property {number[]} waveBands 8 log-compressed bands across the window+ * @property {number} opposedStrength the weaker sideband, same units as strength+ * @property {number} binWidth Hz per bin+ * @property {number} firstFrequency Hz at spectrumDb[0]+ * @property {number} sampleRate+ * @property {number} tone+ * @property {number|null} calibrationRemaining seconds left, null once sensing+ */++/**+ * Emits a tone, listens to its reflections, and reports one Reading per frame.+ *+ * ```js+ * const sensor = new DopplerSensor({ onReading: (r) => console.log(r.direction) });+ * await sensor.start(); // prompts for the microphone+ * sensor.stop();+ * ```+ */+export class DopplerSensor {+ /**+ * @param {{tone?: number, amplitude?: number, autoTone?: boolean,+ * onReading?: (r: Reading) => void, onStatus?: (s: {state: string, message: string}) => void}} [opts]+ */+ constructor(opts = {}) {+ this.tone = opts.tone || DEFAULT_TONE;+ this.amplitude = opts.amplitude ?? 0.08;+ this.autoTone = opts.autoTone !== false;+ this.onReading = opts.onReading || null;+ this.onStatus = opts.onStatus || null;++ this._ctx = null;+ this._stream = null;+ this._osc = null;+ this._gain = null;+ this._analyser = null;+ this._source = null;+ this._raf = 0;+ this._db = null; // scratch dB buffer, reused every frame+ this._baseline = null; // linear power, the still-room reference+ this._frames = 0;+ this._startedAt = 0;+ this._history = [];+ this._lastFrameAt = 0;+ this.running = false;+ }++ _status(state, message) {+ this.onStatus?.({ state, message });+ }++ /**+ * Prompt for the microphone, start the tone, and begin reporting.+ * Rejects with a message worth showing the user.+ */+ async start() {+ if (this.running) return;+ if (!isSupported()) throw new Error('This browser has no Web Audio microphone input.');+ this._status('starting', 'Requesting the microphone');+ try {+ this._stream = await navigator.mediaDevices.getUserMedia(MIC_CONSTRAINTS);+ } catch (err) {+ throw new Error(+ err?.name === 'NotAllowedError'+ ? 'Microphone access was denied. Allow it in the browser address bar and start again.'+ : `The microphone could not be opened: ${err?.message || err}`,+ );+ }+ const Ctx = window.AudioContext || window.webkitAudioContext;+ this._ctx = new Ctx();+ await this._ctx.resume();++ if (this._ctx.sampleRate < this.tone * 2 + 1000) {+ const usable = TONE_CANDIDATES.filter((t) => this._ctx.sampleRate >= t * 2 + 1000);+ if (!usable.length) {+ await this._teardown();+ throw new Error(+ `This device samples audio at ${Math.round(this._ctx.sampleRate)} Hz, too low for an inaudible carrier.`,+ );+ }+ this.tone = usable[usable.length - 1];+ }++ this._analyser = this._ctx.createAnalyser();+ this._analyser.fftSize = FFT_SIZE;+ // Sonar averages the room itself, over its own window. Any smoothing here+ // would average twice and blunt the sidebands a fast sweep depends on.+ this._analyser.smoothingTimeConstant = 0;+ this._db = new Float32Array(this._analyser.frequencyBinCount);++ this._source = this._ctx.createMediaStreamSource(this._stream);+ this._source.connect(this._analyser);+ // The analyser is a sink here. Connecting it onward would put the+ // microphone into the speakers.++ this._gain = this._ctx.createGain();+ this._gain.gain.value = 0;+ this._gain.connect(this._ctx.destination);+ this._osc = this._ctx.createOscillator();+ this._osc.type = 'sine';+ this._osc.frequency.value = this.tone;+ this._osc.connect(this._gain);+ this._osc.start();+ // Sonar's 0.15 s envelope: a hard start on a 20 kHz sine is an audible click.+ this._gain.gain.linearRampToValueAtTime(this.amplitude, this._ctx.currentTime + 0.15);++ this.running = true;+ if (this.autoTone) {+ this._status('tuning', 'Finding a carrier this hardware can hear');+ await this._pickTone();+ }+ this.recalibrate();+ this._status('calibrating', 'Hold still while the room is measured');+ this._lastFrameAt = 0;+ this._raf = requestAnimationFrame(this._frame);+ }++ /**+ * Measure carrier contrast at each candidate and keep the best. Every laptop+ * rolls off at a different frequency, and a carrier the speakers cannot+ * project reads exactly like a room with nothing moving in it.+ */+ async _pickTone() {+ let best = { tone: this.tone, snr: -Infinity };+ for (const tone of TONE_CANDIDATES) {+ if (this._ctx.sampleRate < tone * 2 + 1000) continue;+ this._osc.frequency.setValueAtTime(tone, this._ctx.currentTime);+ await this._settle(90);+ if (!this.running) return;+ this._analyser.getFloatFrequencyData(this._db);+ const { snr } = this._carrier(tone);+ if (snr > best.snr) best = { tone, snr };+ }+ this.tone = best.tone;+ this._osc.frequency.setValueAtTime(this.tone, this._ctx.currentTime);+ await this._settle(120);+ }++ _settle(ms) {+ return new Promise((r) => setTimeout(r, ms));+ }++ /** Carrier peak and noise floor for `tone`, read from the current dB buffer. */+ _carrier(tone) {+ const { center, radius } = this._window(tone);+ let peak = FLOOR_DB;+ for (let i = center - 1; i <= center + 1; i++) peak = Math.max(peak, readDb(this._db[i]));+ let floor = 0;+ for (let k = 0; k < 5; k++) {+ floor += readDb(this._db[center - radius + k]) + readDb(this._db[center + radius - k]);+ }+ return { carrierDb: peak, snr: peak - floor / 10 };+ }++ _window(tone) {+ const n = this._analyser.fftSize;+ const rate = this._ctx.sampleRate;+ const center = Math.round((tone / rate) * n);+ const radius = Math.round((WINDOW_HZ / rate) * n);+ return { center, radius, n, rate };+ }++ /** Throw away the room reference and measure it again. */+ recalibrate() {+ this._baseline = null;+ this._frames = 0;+ this._history = [];+ this._startedAt = now();+ }++ /** Retune the carrier without restarting the microphone. */+ setTone(tone) {+ this.tone = tone;+ if (this._osc) this._osc.frequency.setValueAtTime(tone, this._ctx.currentTime);+ this.recalibrate();+ }++ /** Speaker level for the carrier, 0..1. */+ setAmplitude(amplitude) {+ this.amplitude = amplitude;+ if (this._gain) {+ this._gain.gain.linearRampToValueAtTime(amplitude, this._ctx.currentTime + 0.05);+ }+ }++ _frame = () => {+ if (!this.running) return;+ this._raf = requestAnimationFrame(this._frame);+ // Sonar advances one analysis per 2048-sample hop. A display-rate loop+ // would re-read overlapping windows and hand the detectors more votes per+ // second than their thresholds were tuned against.+ //+ // The clock is the wall clock, not AudioContext.currentTime: a machine+ // with no audio sink (a headless browser, a VM, a laptop with everything+ // muted at the device level) leaves the context clock frozen at zero, and+ // every duration in this file then reads as "no time has passed": the+ // calibration never completes and the page waits forever on a room it has+ // already measured.+ const t = now();+ const hop = 2048 / this._ctx.sampleRate;+ if (t - this._lastFrameAt < hop) return;+ this._lastFrameAt = t;+ this._analyser.getFloatFrequencyData(this._db);+ const reading = this._analyze(t);+ this.onReading?.(reading);+ };++ /** @param {number} t wall-clock seconds @returns {Reading} */+ _analyze(t) {+ const { center, radius, rate } = this._window(this.tone);+ const width = radius * 2 + 1;+ const power = new Float64Array(width);+ const spectrumDb = new Float32Array(width);+ for (let i = 0; i < width; i++) {+ const db = readDb(this._db[center - radius + i]);+ spectrumDb[i] = db;+ power[i] = Math.max(1e-16, dbToPower(db));+ }++ let carrierDb = FLOOR_DB;+ for (let i = radius - 1; i <= radius + 1; i++) carrierDb = Math.max(carrierDb, spectrumDb[i]);+ let floor = 0;+ for (let k = 0; k < 5; k++) floor += spectrumDb[k] + spectrumDb[width - 1 - k];+ floor /= 10;+ const snr = carrierDb - floor;++ if (!this._baseline) this._baseline = Float64Array.from(power);+ const elapsed = t - this._startedAt;+ const calibrating = elapsed < CALIBRATION_SECONDS;+ if (calibrating) {+ // A running mean over the calibration window, exactly as Sonar weights it.+ const a = 1 / (this._frames + 1);+ for (let i = 0; i < width; i++) {+ this._baseline[i] = this._baseline[i] * (1 - a) + power[i] * a;+ }+ }+ this._frames++;++ // Energy that was not in the still room, split by which side of the+ // carrier it landed on. Higher than the carrier means closing distance.+ let left = 0;+ let right = 0;+ const bands = new Array(8).fill(0);+ const reference = Math.max(power[radius - 1] + power[radius] + power[radius + 1], 1e-12);+ for (let i = 0; i < width; i++) {+ if (Math.abs(i - radius) < 3) continue;+ const excess = Math.max(0, power[i] - this._baseline[i] * 2);+ if (i < radius) left += excess;+ else right += excess;+ bands[Math.min(7, Math.floor((i * 8) / width))] += excess / reference;+ }+ const strength = Math.max(left, right) / reference;++ let raw = DIRECTION.still;+ if (strength > MIN_STRENGTH && snr > MIN_SNR_DB) {+ if (right > left * 1.7) raw = DIRECTION.approaching;+ else if (left > right * 1.7) raw = DIRECTION.away;+ else raw = DIRECTION.mixed;+ }+ this._history.push(raw);+ if (this._history.length > 2) this._history.shift();+ const stable = this._history.length === 2 && this._history[0] === this._history[1];++ let direction;+ if (calibrating) direction = DIRECTION.calibrating;+ else if (snr < MIN_SNR_DB) direction = DIRECTION.weakTone;+ else direction = stable ? raw : DIRECTION.listening;++ const baselineDb = new Float32Array(width);+ for (let i = 0; i < width; i++) baselineDb[i] = 10 * Math.log10(Math.max(this._baseline[i], 1e-16));++ return {+ spectrumDb,+ baselineDb,+ direction,+ carrierDb,+ snr,+ strength,+ waveBands: bands.map((b) => Math.log1p(b / MIN_STRENGTH)),+ opposedStrength: Math.min(left, right) / reference,+ binWidth: rate / this._analyser.fftSize,+ firstFrequency: ((center - radius) * rate) / this._analyser.fftSize,+ sampleRate: rate,+ tone: this.tone,+ calibrationRemaining: calibrating ? Math.max(0, CALIBRATION_SECONDS - elapsed) : null,+ };+ }++ /** Silence the tone, release the microphone, and stop reporting. */+ stop() {+ this.running = false;+ cancelAnimationFrame(this._raf);+ this._raf = 0;+ this._teardown();+ this._status('stopped', 'Sensing stopped');+ }++ async _teardown() {+ try {+ if (this._gain && this._ctx) {+ this._gain.gain.linearRampToValueAtTime(0, this._ctx.currentTime + 0.05);+ }+ this._osc?.stop(this._ctx ? this._ctx.currentTime + 0.08 : 0);+ } catch {+ // An oscillator that never started, or a context already closed by a+ // navigation, has nothing to ramp down.+ }+ for (const track of this._stream?.getTracks() || []) track.stop();+ this._stream = null;+ if (this._ctx && this._ctx.state !== 'closed') {+ try {+ await this._ctx.close();+ } catch {+ // Closing twice is not an error worth surfacing.+ }+ }+ this._ctx = null;+ this._osc = null;+ this._gain = null;+ this._analyser = null;+ this._source = null;+ }+}diff --git a/src/sonar/gestures.js b/src/sonar/gestures.jsnew file mode 100644index 000000000..b32c75910--- /dev/null+++ b/src/sonar/gestures.js@@ -0,0 +1,297 @@+// Gesture detectors over a stream of Doppler Readings.+//+// Ports of the three detectors in Sonar (https://github.com/nirholas/sonar.cool,+// MIT): ImmediateWave (a sideways sweep), ZoomMotion (a push and its paced+// return) and ScrollMotion (a held lift). Their constants are reproduced to the+// digit, because every one of them is a tuning result rather than a choice: the+// 0.22 s re-arm is what stops a returning hand from firing a second sweep, and+// the 1.7x sideband ratio is what keeps a still room from drifting into a+// direction.+//+// Everything here is pure state machines over {direction, strength, snr,+// waveBands} plus a clock. No audio, no DOM, no 3D. That is what makes them+// testable without a microphone (tests/sonar-gestures.test.js drives them with+// the same synthetic frames the Swift suite uses).++import { DIRECTION } from './doppler.js';++/**+ * A sideways sweep, read as a direction without any training.+ *+ * A sweep is not sideways to the microphone at all: the hardware only senses+ * distance, so a sweep registers as one coherent lobe (a hand closing on the+ * speaker) followed by the opposite lobe as it passes. The detector takes the+ * first coherent lobe and suppresses the return, which is why a pause before+ * sweeping back matters.+ *+ * Emits `'next'` or `'previous'`.+ */+export class SwipeDetector {+ constructor() {+ this.reset();+ }++ reset() {+ this._quietSince = null;+ this._armed = false;+ this._started = null;+ this._lastSample = -Infinity;+ this._cooldownUntil = 0;+ this._balanceSum = 0;+ this._votes = 0;+ }++ _clearCandidate() {+ this._started = null;+ this._votes = 0;+ this._balanceSum = 0;+ }++ /**+ * @param {object} reading+ * @param {number} now seconds, monotonic+ * @returns {'next'|'previous'|null}+ */+ feed(reading, now) {+ // A gap this long means frames were dropped; the candidate in flight+ // cannot be trusted to be one continuous motion. The one deviation from+ // the Swift here: it also drops the cooldown, which would let a return+ // stroke fire a second sweep if frames stuttered inside that window.+ if (now - this._lastSample > 0.2) {+ const cooldown = this._cooldownUntil;+ this.reset();+ this._cooldownUntil = cooldown;+ }+ this._lastSample = now;++ if (reading.direction === DIRECTION.calibrating || reading.snr <= 15) {+ this._armed = false;+ this._quietSince = null;+ this._clearCandidate();+ return null;+ }+ if (now < this._cooldownUntil) return null;++ const moving = reading.strength > 0.00022;+ if (!moving) {+ // Separate an interrupted candidate from a completed sweep: a quiet+ // stretch re-arms, an interruption only clears.+ this._clearCandidate();+ if (this._quietSince === null) this._quietSince = now;+ if (now - this._quietSince >= 0.22) {+ this._armed = true;+ this._clearCandidate();+ }+ return null;+ }+ this._quietSince = null;+ if (!this._armed) return null;+ if (this._started === null) this._started = now;++ let balance = 0;+ if (reading.waveBands?.length === 8) {+ const power = reading.waveBands.map((b) => Math.expm1(Math.min(20, Math.max(0, b))));+ const away = power.slice(0, 4).reduce((a, b) => a + b, 0);+ const toward = power.slice(4).reduce((a, b) => a + b, 0);+ balance = (toward - away) / Math.max(1e-9, toward + away);+ } else if (reading.direction === DIRECTION.approaching) {+ balance = 1;+ } else if (reading.direction === DIRECTION.away) {+ balance = -1;+ }++ if (Math.abs(balance) > 0.16) {+ // A clear lobe must not be cancelled by an earlier opposite twitch:+ // restart the candidate on it rather than averaging the two to zero.+ if (this._votes > 0 && balance * this._balanceSum < 0) {+ this._started = now;+ this._votes = 0;+ this._balanceSum = 0;+ }+ this._balanceSum += balance;+ this._votes += 1;+ } else {+ this._started = now;+ this._votes = 0;+ this._balanceSum = 0;+ }++ const elapsed = now - this._started;+ if (elapsed > 0.65) {+ // Too slow to be a sweep. Something else is moving in the room.+ this._armed = false;+ this._clearCandidate();+ return null;+ }+ if (elapsed < 0.04 || this._votes < 3 || Math.abs(this._balanceSum) / this._votes <= 0.24) {+ return null;+ }+ const event = this._balanceSum > 0 ? 'next' : 'previous';+ this._armed = false;+ this._clearCandidate();+ this._cooldownUntil = now + 0.65;+ return event;+ }+}++/**+ * A push toward the screen, and the paced pull that undoes it.+ *+ * Emits `+3` on the push (three steps at once, so the response is visible),+ * `-1` per step of the return, and `0` on the step that lands back at rest. The+ * return is paced by how fast the hand is actually moving, read off how far the+ * reflected energy sits from the carrier, so a quick pull snaps back and a slow+ * one eases.+ */+export class PushPullDetector {+ constructor() {+ this.steps = 0;+ this._direction = '';+ this._began = 0;+ this._last = -Infinity;+ this._budget = 0;+ }++ get enlarged() {+ return this.steps > 0;+ }++ /** Forget the stroke in flight without forgetting where the zoom sits. */+ clearEvidence() {+ this._direction = '';+ this._last = -Infinity;+ this._budget = 0;+ }++ /**+ * Steps per second for the return, from the Doppler shift itself: energy+ * further from the carrier is a faster hand.+ */+ static returnRate(reading) {+ const spectrum = reading.spectrumDb;+ const baseline = reading.baselineDb;+ if (!spectrum || !baseline || spectrum.length !== baseline.length) return 15;+ if (spectrum.length <= 7 || !(reading.binWidth > 0)) return 15;+ const center = Math.floor(spectrum.length / 2);+ let weighted = 0;+ let total = 0;+ for (let i = 0; i < spectrum.length; i++) {+ if (Math.abs(i - center) < 3) continue;+ if ((reading.direction === DIRECTION.away) !== (i < center)) continue;+ const energy = Math.max(0, 10 ** (spectrum[i] / 10) - 2 * 10 ** (baseline[i] / 10));+ weighted += energy * Math.abs(i - center) * reading.binWidth;+ total += energy;+ }+ if (!(total > 0) || !Number.isFinite(weighted)) return 15;+ return Math.min(45, Math.max(5, (weighted / total) * 0.15));+ }++ /**+ * @param {object} reading+ * @param {number} now seconds+ * @param {boolean} [reversed] swap which way is "in"+ * @returns {3|-1|0|null}+ */+ feed(reading, now, reversed = false) {+ const gap = now - this._last;+ this._last = now;+ if (gap > 0.16) {+ this._direction = '';+ this._budget = 0;+ }+ const usable =+ reading.snr > 15 &&+ reading.strength > 0.0003 &&+ (reading.direction === DIRECTION.approaching || reading.direction === DIRECTION.away);+ if (!usable) {+ // A couple of ambiguous frames must not erase a return stroke midway.+ if (now - this._began > 0.16) {+ this._direction = '';+ this._budget = 0;+ }+ return null;+ }++ const toward = (reading.direction === DIRECTION.approaching) !== reversed;+ if (this._direction !== reading.direction) {+ this._direction = reading.direction;+ this._began = now;+ this._budget = 0;+ }+ if (toward) {+ if (this.steps !== 0 || now - this._began < 0.1) return null;+ this.steps = 3;+ this._direction = '';+ return 3;+ }+ if (this.steps <= 0) return null;+ this._budget += Math.min(0.06, Math.max(0, Number.isFinite(gap) ? gap : 0)) * PushPullDetector.returnRate(reading);+ if (now - this._began < 0.025 || this._budget < 1) return null;+ this._budget -= 1;+ this.steps -= 1;+ return this.steps === 0 ? 0 : -1;+ }+}++/**+ * A held lift, read as a continuous velocity rather than a discrete event.+ *+ * Lifting the hand off the keyboard reads as sustained recession; the velocity+ * eases toward a target set by how much energy that motion is returning, and+ * eases back to nothing the moment the hand settles. `step()` is called once+ * per animation frame and returns the distance travelled in that frame.+ */+export class LiftMotion {+ constructor() {+ this.velocity = 0;+ this.target = 0;+ this.forward = true;+ this.toggles = 0;+ this._lastAway = -Infinity;+ }++ switchDirection() {+ this.forward = !this.forward;+ this.toggles += 1;+ this.velocity = 0;+ this.target = 0;+ this._lastAway = -Infinity;+ }++ reset() {+ this.velocity = 0;+ this.target = 0;+ this._lastAway = -Infinity;+ }++ /** @param {object} reading @param {number} now seconds */+ feed(reading, now) {+ if (reading.direction === DIRECTION.away) {+ this._lastAway = now;+ this.target =+ (this.forward ? 1 : -1) * Math.min(700, 110 + 120 * Math.log1p(reading.strength / 0.0003));+ } else if (+ reading.direction === DIRECTION.approaching ||+ reading.direction === DIRECTION.calibrating ||+ reading.direction === DIRECTION.weakTone+ ) {+ this.target = 0;+ this._lastAway = -Infinity;+ }+ // Anything else (a listening or mixed frame) bridges: brief uncertainty+ // mid-lift should not drop the motion, only a confirmed return should.+ }++ /**+ * @param {number} dt seconds since the last step+ * @param {number} now seconds+ * @returns {number} distance travelled this frame+ */+ step(dt, now) {+ if (now - this._lastAway > 0.09) this.target = 0;+ const tau = this.target === 0 ? 0.075 : 0.07;+ this.velocity += (this.target - this.velocity) * (1 - Math.exp(-dt / tau));+ if (Math.abs(this.velocity) < 2 && this.target === 0) this.velocity = 0;+ return this.velocity * dt;+ }+}diff --git a/tests/sonar-gestures.test.js b/tests/sonar-gestures.test.jsnew file mode 100644index 000000000..dca92e007--- /dev/null+++ b/tests/sonar-gestures.test.js@@ -0,0 +1,264 @@+/**+ * The acoustic gesture detectors (src/sonar/gestures.js), driven by the same+ * synthetic frames Sonar's Swift suite uses (work/Sonar/WaveCalibration.swift+ * and work/Sonar/Zoom.swift in https://github.com/nirholas/sonar.cool).+ *+ * These detectors cannot be exercised by hand in CI: they need a speaker, a+ * microphone and a moving hand. What they CAN be held to is the behaviour every+ * one of their constants was tuned to produce, which is exactly what these+ * vectors encode. Each case is a bug that shipped once:+ *+ * · a sweep and its return stroke firing two navigations instead of one+ * · symmetric motion (a fan, a passing body) being read as a direction+ * · a faint opposite twitch at the start of a sweep cancelling it+ * · a push re-triggering while already zoomed, or the pull skipping levels+ * · a weak carrier being read as a room full of motion+ */++import { describe, it, expect } from 'vitest';+import { DIRECTION } from '../src/sonar/doppler.js';+import { SwipeDetector, PushPullDetector, LiftMotion } from '../src/sonar/gestures.js';++/** A frame with the sideband energy a sweep of `balance` sign would return. */+function sweepFrame({ moving, balance = 0, bands = null }) {+ return {+ direction: DIRECTION.mixed,+ snr: 40,+ strength: moving ? 0.004 : 0,+ waveBands: bands || (moving && balance ? bandsFor(balance) : new Array(8).fill(0)),+ };+}++/** Energy in the band a hand moving with this sign would light up. */+function bandsFor(sign) {+ const bands = new Array(8).fill(0);+ bands[sign > 0 ? 5 : 2] = 2;+ return bands;+}++describe('SwipeDetector', () => {+ for (const sign of [1, -1]) {+ const expected = sign > 0 ? 'next' : 'previous';++ it(`reads a ${expected} sweep and suppresses its return stroke`, () => {+ const detector = new SwipeDetector();+ const events = [];+ for (let frame = 0; frame < 80; frame++) {+ const moving = frame >= 20 && frame < 48;+ // The lobe flips partway through: the hand passes the microphone and+ // starts receding. Only the first lobe may count.+ const value = frame < 33 ? sign : -sign;+ const event = detector.feed(+ sweepFrame({ moving, balance: value }),+ frame * 0.02,+ );+ if (event) events.push(event);+ }+ expect(events).toEqual([expected]);+ });++ it(`fires twice for two deliberate ${expected} sweeps, not for the pause between`, () => {+ const detector = new SwipeDetector();+ const fired = [];+ const times = [];+ for (let frame = 0; frame < 120; frame++) {+ const t = frame * 0.02;+ const forward = (t >= 0.3 && t < 0.44) || (t >= 1.6 && t < 1.74);+ const returning = t >= 0.7 && t < 0.9;+ const bands = new Array(8).fill(0);+ if (forward) bands[sign > 0 ? 5 : 2] = 2;+ if (returning) bands[sign > 0 ? 2 : 5] = 2;+ const event = detector.feed(+ {+ direction: DIRECTION.mixed,+ snr: 40,+ strength: forward || returning ? 0.004 : 0,+ waveBands: bands,+ },+ t,+ );+ if (event) {+ fired.push(event);+ times.push(t);+ }+ }+ expect(fired).toEqual([expected, expected]);+ // The first sweep must still land fast. A slower re-arm would make the+ // page feel like it is thinking about it.+ expect(times[0]).toBeLessThanOrEqual(0.38);+ });++ it(`does not let a faint opposite precursor cancel a ${expected} sweep`, () => {+ const detector = new SwipeDetector();+ const fired = [];+ for (let frame = 0; frame < 40; frame++) {+ const active = frame >= 20 && frame < 26;+ const balance = frame < 22 ? -sign * 0.18 : sign * 0.32;+ const bands = new Array(8).fill(0);+ if (active) {+ bands[2] = Math.log1p(1 - balance);+ bands[5] = Math.log1p(1 + balance);+ }+ const event = detector.feed(+ {+ direction: DIRECTION.mixed,+ snr: 40,+ strength: active ? 0.004 : 0,+ waveBands: bands,+ },+ frame * 0.02,+ );+ if (event) fired.push(event);+ }+ expect(fired).toEqual([expected]);+ });+ }++ it('refuses to guess a direction from symmetric motion', () => {+ const detector = new SwipeDetector();+ for (let frame = 0; frame < 100; frame++) {+ const event = detector.feed(+ {+ direction: DIRECTION.mixed,+ snr: 40,+ strength: frame > 20 ? 0.004 : 0,+ waveBands: new Array(8).fill(1),+ },+ frame * 0.02,+ );+ expect(event).toBeNull();+ }+ });++ it('stays silent while the room baseline is still being measured', () => {+ const detector = new SwipeDetector();+ for (let frame = 0; frame < 60; frame++) {+ const event = detector.feed(+ {+ direction: DIRECTION.calibrating,+ snr: 40,+ strength: 0.004,+ waveBands: bandsFor(1),+ },+ frame * 0.02,+ );+ expect(event).toBeNull();+ }+ });+});++describe('PushPullDetector', () => {+ /** A frame whose reflected energy sits `offset` bins off the carrier. */+ function sample(direction, offset) {+ const spectrumDb = new Float32Array(121).fill(-100);+ spectrumDb[60 + (direction === DIRECTION.approaching ? offset : -offset)] = -30;+ return {+ spectrumDb,+ baselineDb: new Float32Array(121).fill(-100),+ direction,+ carrierDb: -20,+ snr: 40,+ strength: 0.004,+ opposedStrength: 0.0004,+ binWidth: 10,+ };+ }++ /** Push for 7 frames, then pull, and report when it landed back at rest. */+ function trial(offset, reversed = false) {+ const detector = new PushPullDetector();+ const actions = [];+ let resetTime = 0;+ for (let i = 0; i < 100; i++) {+ const pushing = i < 7;+ const direction =+ pushing !== reversed ? DIRECTION.approaching : DIRECTION.away;+ const event = detector.feed(sample(direction, offset), i * 0.02, reversed);+ if (event !== null) {+ actions.push(event);+ if (event === 0) resetTime = i * 0.02;+ }+ }+ expect(actions).toEqual([3, -1, -1, 0]);+ return resetTime;+ }++ it('steps back one level at a time without re-triggering the push', () => {+ trial(4);+ });++ it('paces the return by how fast the hand is actually moving', () => {+ const slow = trial(4);+ const fast = trial(30);+ expect(fast).toBeLessThan(slow);+ expect(fast).toBeLessThan(0.32);+ });++ it('honours a reversed mapping', () => {+ trial(30, true);+ });++ it('ignores motion when the carrier is not clear', () => {+ const detector = new PushPullDetector();+ for (let i = 0; i < 20; i++) {+ const reading = { ...sample(DIRECTION.approaching, 30), snr: 0 };+ expect(detector.feed(reading, i * 0.02, false)).toBeNull();+ }+ expect(detector.steps).toBe(0);+ });++ it('falls back to a usable return rate when there is no spectrum to read', () => {+ expect(PushPullDetector.returnRate({ direction: DIRECTION.away })).toBe(15);+ });+});++describe('LiftMotion', () => {+ it('accelerates while the hand is held up and settles once it drops', () => {+ const motion = new LiftMotion();+ let travelled = 0;+ for (let i = 0; i < 40; i++) {+ const t = i * 0.02;+ motion.feed({ direction: DIRECTION.away, strength: 0.004 }, t);+ travelled += motion.step(0.02, t);+ }+ expect(travelled).toBeGreaterThan(0);+ expect(motion.velocity).toBeGreaterThan(100);++ const held = motion.velocity;+ let t = 0.8;+ for (let i = 0; i < 40; i++) {+ t += 0.02;+ motion.feed({ direction: DIRECTION.approaching, strength: 0 }, t);+ motion.step(0.02, t);+ }+ expect(motion.velocity).toBe(0);+ expect(held).toBeGreaterThan(0);+ });++ it('bridges brief uncertain frames instead of stalling mid-lift', () => {+ const motion = new LiftMotion();+ let t = 0;+ for (let i = 0; i < 20; i++, t += 0.02) {+ motion.feed({ direction: DIRECTION.away, strength: 0.004 }, t);+ motion.step(0.02, t);+ }+ const before = motion.velocity;+ // Two frames the analyser could not call. The hand has not moved.+ for (let i = 0; i < 2; i++, t += 0.02) {+ motion.feed({ direction: DIRECTION.listening, strength: 0.004 }, t);+ motion.step(0.02, t);+ }+ expect(motion.velocity).toBeGreaterThan(before * 0.8);+ });++ it('reverses on demand and forgets the motion in flight', () => {+ const motion = new LiftMotion();+ motion.feed({ direction: DIRECTION.away, strength: 0.004 }, 0);+ motion.step(0.02, 0.02);+ motion.switchDirection();+ expect(motion.velocity).toBe(0);+ expect(motion.forward).toBe(false);+ motion.feed({ direction: DIRECTION.away, strength: 0.004 }, 0.04);+ expect(motion.target).toBeLessThan(0);+ });+});diff --git a/vercel.json b/vercel.jsonindex ee28f21b1..d78d0c0cc 100644--- a/vercel.json+++ b/vercel.json@@ -4594,6 +4594,10 @@"src": "/gestures/?","dest": "/gestures.html"},+ {+ "src": "/sonar/?",+ "dest": "/sonar.html"+ },{"src": "/choreograph/?","dest": "/choreograph.html"diff --git a/vite.config.js b/vite.config.jsindex fadc11dbd..42589d9d6 100644--- a/vite.config.js+++ b/vite.config.js@@ -977,6 +977,7 @@ const appConfig = {'pose-mini': resolve(__dirname, 'pages/pose-mini.html'),animations: resolve(__dirname, 'pages/animations.html'),gestures: resolve(__dirname, 'pages/gestures.html'),+ sonar: resolve(__dirname, 'pages/sonar.html'),choreograph: resolve(__dirname, 'pages/choreograph.html'),'character-library': resolve(__dirname, 'pages/character-library.html'),'sign-language': resolve(__dirname, 'pages/sign-language.html'),