Skip to content

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.

fix(sonar): stop the camera drifting, uncover the live stage, and make every state reachable

nirholasf5240584e19a
diff --git a/data/pages.json b/data/pages.json
index 61b878a54..fbce2ec0b 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -2783,7 +2783,7 @@
},
{
"path": "/docs/globe",
- "title": "Docs · Global Intel Globe",
+ "title": "Docs \u00b7 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",
diff --git a/docs/animations.md b/docs/animations.md
index c1e63c232..9d52824f4 100644
--- a/docs/animations.md
+++ b/docs/animations.md
@@ -145,6 +145,7 @@ Resolved (see `public/animations/registry.json` under `resolved_issues`): the `w
- [Agent Gestures](/gestures): the live slot-and-hint reference, with an override builder
- [Choreography](/docs/choreography): sequence gesture slots into named, replayable routines, authored at [/choreograph](https://three.ws/choreograph)
+- [Sonar](/docs/sonar): step through these slots by hand, with no camera, at [/sonar](https://three.ws/sonar). The speakers emit an inaudible tone and the microphone reads the Doppler shift of a moving hand off it
- [Give your agent body language](/tutorials/animate-your-agent): the walkthrough
- [3D asset pipeline](/docs/3d-asset-pipeline): the full generate, rig, animate, export chain
- [Animation Studio](/docs/animation-studio): author and preview clips in the browser
diff --git a/docs/sonar.md b/docs/sonar.md
index db40c0e28..2b2489d88 100644
--- a/docs/sonar.md
+++ b/docs/sonar.md
@@ -95,7 +95,7 @@ const sensor = new DopplerSensor({
`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.
+`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. `switchDirection()` flips which way a lift travels and drops the motion in flight with it, rather than reversing a camera that is still moving under the hand; `reset()` clears the motion without changing the direction.
---
diff --git a/docs/start-here.md b/docs/start-here.md
index f26813feb..2df07c26b 100644
--- a/docs/start-here.md
+++ b/docs/start-here.md
@@ -76,6 +76,7 @@ Want the model in your hands rather than on a screen? [Materialize](./materializ
- **Creating your first agent** → Go to [/start](/start) — a 5-step wizard walks you through it
- **Want to know why the avatars feel alive?** → [Procedural animation](./procedural-animation.md) — the runtime IK layers that run on top of the recorded clips: gaze that follows your cursor or meets your eyes, and feet that land on uneven ground instead of floating over it
- **Want your agent to perform, not just react?** → [Choreography](./choreography.md): compose gestures into a named routine on a real timeline at [/choreograph](https://three.ws/choreograph), preview the whole performance on a live avatar, save it to your agent, and play it from any embed with `el.playRoutine('welcome')`. A routine is also just a link, so you can share one with someone who has no account
+- **Want to drive it with your hands?** → [Sonar](./sonar.md): your speakers play a tone too high to hear and your microphone listens for how your hand bends it on the way back, so a sweep, a push or a lift moves a real 3D agent at [/sonar](https://three.ws/sonar) with the camera switched off. The sensing is two small modules you can point at anything
- **Want your avatar to sign in ASL?** → Start with the 15-minute walkthrough, [Make your avatar sign](https://three.ws/tutorials/sign-with-your-avatar): type a phrase and watch it signed at [/sign-language](https://three.ws/sign-language), share it as a link (`?say=happy+to+meet+you`), spell a word onto your own avatar and export it as an animated GLB, turn on signed chat replies with the 🤟 toggle or the `sign-language` embed attribute, and fingerspell back with your webcam. The full reference is [Sign language](./sign-language.md)
- **Want that character to tell you what actually matters?** → [The Companion](./companion.md): connect your own Telegram bot, calendar, inbox, or phone at [/companion](https://three.ws/companion), set the bar for what is worth interrupting you for, and a 3D character delivers it in person, wearing the avatar of whoever sent it. Also a desktop app, an SDK, a CLI, and an MCP server so your agents can reach you the same way
- **Wondering who the little character in the corner is?** → [The agent shell](./agent-shell.md) — every visitor gets a named agent in the first five seconds (claim it to make it real), the ⌘K palette runs real commands (`forge …`, `digest`, `price btc`, `ask …`), and shell pages navigate without ever unloading your agent
diff --git a/pages/gestures.html b/pages/gestures.html
index 9c609e9a4..3ec04e327 100644
--- a/pages/gestures.html
+++ b/pages/gestures.html
@@ -63,6 +63,7 @@
<a class="gv-btn gv-btn--primary" href="/choreograph">Sequence gestures into a routine</a>
<a class="gv-btn gv-btn--secondary" href="/animations">Browse every clip</a>
<a class="gv-btn gv-btn--ghost" href="/pose">Animation Studio</a>
+ <a class="gv-btn gv-btn--ghost" href="/sonar">Play these by hand, no camera</a>
<a class="gv-btn gv-btn--ghost" href="/docs/animations">Developer reference</a>
</div>
<dl class="gv-stats" data-role="stats" aria-live="polite">
diff --git a/pages/sonar.html b/pages/sonar.html
index aec090b60..3497387ea 100644
--- a/pages/sonar.html
+++ b/pages/sonar.html
@@ -117,7 +117,16 @@
<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">
+ <div
+ class="sn-meter"
+ role="progressbar"
+ aria-label="Reflected motion strength"
+ aria-valuemin="0"
+ aria-valuemax="100"
+ aria-valuenow="0"
+ aria-valuetext="No motion"
+ data-role="hud-meter"
+ >
<span class="sn-meter-fill" data-role="hud-strength"></span>
</div>
<div class="sn-hud-row sn-hud-row--small">
@@ -129,7 +138,17 @@
<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
+ class="sn-progress"
+ role="progressbar"
+ aria-label="Measuring the room"
+ aria-valuemin="0"
+ aria-valuemax="100"
+ aria-valuenow="0"
+ data-role="calibrating-meter"
+ >
+ <span data-role="calibrating-bar"></span>
+ </div>
</div>
</div>
@@ -172,6 +191,7 @@
<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>
+ <label><input type="checkbox" data-role="reverse-lift" /> Reverse lift</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>
@@ -213,7 +233,8 @@
<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">
+ <p class="sn-visually-hidden" data-role="log-latest" aria-live="polite"></p>
+ <ol class="sn-log" data-role="log">
<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.
diff --git a/public/sonar.css b/public/sonar.css
index 9f82d7060..faa97453b 100644
--- a/public/sonar.css
+++ b/public/sonar.css
@@ -34,6 +34,19 @@
--sn-error: #b91c1c;
}
+/* Announced by screen readers, never painted. */
+.sn-visually-hidden {
+ position: absolute;
+ width: 1px;
+ height: 1px;
+ margin: -1px;
+ padding: 0;
+ overflow: hidden;
+ clip-path: inset(50%);
+ white-space: nowrap;
+ border: 0;
+}
+
.sn-page {
min-height: 100vh;
background: var(--bg, #000);
@@ -402,8 +415,24 @@
.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-toggles { display: grid; gap: 4px; margin: 14px 0; font-size: 13px; color: var(--sn-muted); }
+
+.sn-toggles label {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ padding: 4px 6px;
+ margin-left: -6px;
+ border-radius: 7px;
+ cursor: pointer;
+ transition: background 0.16s ease, color 0.16s ease;
+}
+
+.sn-toggles label:hover { background: var(--sn-surface-2); color: inherit; }
+.sn-toggles label:active { background: var(--sn-surface-3); }
+.sn-toggles label:has(input:checked) { color: inherit; }
+.sn-toggles label:has(input:focus-visible) { outline: 2px solid var(--sn-accent); outline-offset: 1px; }
+.sn-toggles input { accent-color: var(--sn-accent); cursor: pointer; }
.sn-control-actions { display: flex; flex-wrap: wrap; gap: 8px; }
.sn-control-actions .sn-btn { padding: 8px 12px; font-size: 13px; }
@@ -439,29 +468,30 @@
.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;
+/* Specificity, not !important, so the flash keyframes below can win. */
+.sn-card p.sn-card-live {
+ margin: 12px 0 8px;
padding: 7px 10px;
border-radius: 8px;
background: var(--sn-surface-2);
font-size: 12.5px;
font-weight: 500;
- color: var(--sn-muted) !important;
+ color: var(--sn-muted);
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;
-}
+/* The highlight decays inside the animation rather than being cleared by a
+ * timer, so a card cannot latch green: when the animation is off (reduced
+ * motion) the pill simply never lights, which is the right answer there too. */
+.sn-card p.sn-card-live.is-live { animation: sn-flash 0.9s ease-out; }
@keyframes sn-flash {
- from { transform: scale(1.03); }
- to { transform: scale(1); }
+ 0% { background: var(--sn-live); color: var(--sn-accent-ink); transform: scale(1.03); }
+ 55% { background: var(--sn-live); color: var(--sn-accent-ink); transform: scale(1); }
+ 100% { background: var(--sn-surface-2); color: var(--sn-muted); transform: scale(1); }
}
-.sn-card-keys { margin: 0 !important; font-size: 12px; }
+.sn-card p.sn-card-keys { margin: 0; font-size: 12px; }
kbd {
display: inline-block;
@@ -542,7 +572,29 @@ kbd {
.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); }
+
+/* /style.css carries no global link hover or focus rule, so prose links on this
+ * page state their own. Every one of them is a real destination. */
+.sn-page main p a,
+.sn-alert a {
+ color: var(--sn-accent);
+ text-decoration: underline;
+ text-decoration-color: color-mix(in srgb, var(--sn-accent) 40%, transparent);
+ text-underline-offset: 2px;
+ transition: color 0.16s ease, text-decoration-color 0.16s ease;
+}
+
+.sn-page main p a:hover,
+.sn-alert a:hover { text-decoration-color: currentcolor; }
+.sn-page main p a:active,
+.sn-alert a:active { color: color-mix(in srgb, var(--sn-accent) 75%, var(--text, #fafafa)); }
+
+.sn-page main p a:focus-visible,
+.sn-alert a:focus-visible {
+ outline: 2px solid var(--sn-accent);
+ outline-offset: 2px;
+ border-radius: 3px;
+}
/* ── responsive ───────────────────────────────────────────────────────── */
@@ -562,8 +614,8 @@ kbd {
@media (prefers-reduced-motion: reduce) {
.sn-hero-dot,
.sn-spinner,
- .sn-card-live.is-live,
+ .sn-card p.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; }
+ .sn-btn, .sn-card, .sn-hud, .sn-meter-fill, .sn-toggles label { transition: none; }
}
diff --git a/src/animations-live-preview.js b/src/animations-live-preview.js
index 54583d9b8..bf3b46d23 100644
--- a/src/animations-live-preview.js
+++ b/src/animations-live-preview.js
@@ -280,13 +280,14 @@ export class AnimationLivePreview {
}
/**
- * 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.
+ * Turn the camera around the avatar: an absolute angle in radians, measured
+ * from the framed shot. Absolute rather than additive on purpose, because a
+ * crossfaded clip change keeps the yaw it already had while a cold mount
+ * resets it; a caller re-applying its own angle after every cut would double
+ * it on the warm path and the shot would drift further with every gesture.
*/
- orbitBy(radians) {
- this._yaw += radians;
+ setYaw(radians) {
+ this._yaw = radians || 0;
this._applyCamera();
}
@@ -296,10 +297,6 @@ export class AnimationLivePreview {
this._applyCamera();
}
- getZoom() {
- return this._zoom;
- }
-
/** Drop the viewer's turn and zoom, back to the framed shot. */
resetView() {
this._yaw = 0;
diff --git a/src/sonar-page.js b/src/sonar-page.js
index e92485684..ca195c09c 100644
--- a/src/sonar-page.js
+++ b/src/sonar-page.js
@@ -123,10 +123,28 @@ async function loadManifest() {
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. */
+/**
+ * Push the viewer's turn and zoom onto the stage. This page owns both numbers;
+ * the preview is told the absolute value every time, so re-applying after a cut
+ * cannot compound with the angle the stage is already holding.
+ */
function applyView(preview) {
preview.setZoom(ZOOM_STEPS[state.zoomSteps] ?? 1);
- if (state.yaw) preview.orbitBy(state.yaw);
+ preview.setYaw(state.yaw);
+}
+
+/**
+ * Run something against the preview engine, reporting a failure on the stage
+ * instead of throwing into a click handler or an animation frame. Every path
+ * here touches a dynamic import and a clip fetch, so every path can fail.
+ */
+async function withPreview(fn) {
+ try {
+ return await fn(await getPreview());
+ } catch (err) {
+ setStageState('error', err?.message ? `The stage failed: ${err.message}` : undefined);
+ return null;
+ }
}
/**
@@ -172,15 +190,22 @@ async function playCurrent({ crossfade = 0.25 } = {}) {
async function toIdle() {
const def = state.clips.get(DEFAULT_ANIMATION_MAP.idle);
- if (!def) return;
+ if (!def) {
+ setStageState('error', `"${DEFAULT_ANIMATION_MAP.idle}" is not in the clip manifest.`);
+ 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);
+ if (!state.preview) setStageState('loading');
+ await withPreview(async (preview) => {
+ await preview.play(
+ q('stage'),
+ { id: def.name, source: 'curated', url: def.url, loop: true },
+ { crossfade: 0.35 },
+ );
+ if (state.playing !== 'idle') return;
+ applyView(preview);
+ setStageState('none');
+ });
}
/* ── the three gestures ────────────────────────────────────────────────── */
@@ -196,8 +221,7 @@ 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]);
+ await withPreview((preview) => 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);
@@ -205,8 +229,7 @@ async function applyZoom(action, source) {
async function orbit(radians, source) {
state.yaw += radians;
- const preview = await getPreview();
- preview.orbitBy(radians);
+ await withPreview((preview) => preview.setYaw(state.yaw));
if (source === 'keyboard') {
flash('live-lift', `Turned ${radians > 0 ? 'right' : 'left'}`);
logEvent('Turn', `${Math.round((state.yaw * 180) / Math.PI)}°`, source);
@@ -230,6 +253,10 @@ function logEvent(gesture, detail, source) {
at: new Date().toLocaleTimeString([], { hour12: false }),
});
state.log = state.log.slice(0, 40);
+ // The list itself is not a live region: replacing its markup would make a
+ // screen reader re-read all forty rows on every gesture. One sentence for the
+ // event that just happened is the whole announcement.
+ setStatus(q('log-latest'), `${gesture}. ${detail}.`);
renderLog();
}
@@ -340,6 +367,7 @@ function onReading(reading) {
if (calibrating) {
const pct = 100 * (1 - reading.calibrationRemaining / CALIBRATION_SECONDS);
q('calibrating-bar').style.width = `${pct.toFixed(0)}%`;
+ q('calibrating-meter')?.setAttribute('aria-valuenow', pct.toFixed(0));
}
setStatus(q('hud-direction'), DIRECTION_LABEL[reading.direction] || reading.direction);
@@ -352,6 +380,16 @@ function onReading(reading) {
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 gauge = q('hud-meter');
+ if (gauge) {
+ gauge.setAttribute('aria-valuenow', pct.toFixed(0));
+ gauge.setAttribute(
+ 'aria-valuetext',
+ reading.strength > 0.0003
+ ? `${DIRECTION_LABEL[reading.direction] || reading.direction}, ${pct.toFixed(0)} percent`
+ : 'No motion',
+ );
+ }
}
const hud = q('hud');
if (hud) hud.dataset.direction = reading.direction;
@@ -452,6 +490,11 @@ function stop() {
setStatus(q('hud-snr'), 'Contrast off');
const meter = q('hud-strength');
if (meter) meter.style.width = '0%';
+ const gauge = q('hud-meter');
+ if (gauge) {
+ gauge.setAttribute('aria-valuenow', '0');
+ gauge.setAttribute('aria-valuetext', 'No motion');
+ }
state.lastReading = null;
drawSignal(null);
}
@@ -523,8 +566,13 @@ function syncModeCards() {
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';
+ if (!label) continue;
+ if (!on) {
+ label.classList.remove('is-live');
+ label.textContent = 'Not in this mode';
+ } else if (label.textContent === 'Not in this mode') {
+ label.textContent = 'Waiting';
+ }
}
}
@@ -545,9 +593,14 @@ function bindControls() {
state.yaw = 0;
state.push.steps = 0;
state.push.clearEvidence();
- (await getPreview()).resetView();
+ await withPreview((preview) => preview.resetView());
flash('live-push', 'Back to the framed shot');
});
+ q('reverse-lift')?.addEventListener('change', () => {
+ // LiftMotion carries its own direction, so flipping it mid-turn drops the
+ // motion in flight rather than reversing a moving camera under the hand.
+ state.lift.switchDirection();
+ });
const volume = q('volume');
volume?.addEventListener('input', () => {
q('volume-out').textContent = `${volume.value}%`;
diff --git a/src/sonar/gestures.js b/src/sonar/gestures.js
index b32c75910..12b8dbf48 100644
--- a/src/sonar/gestures.js
+++ b/src/sonar/gestures.js
@@ -152,10 +152,6 @@ export class PushPullDetector {
this._budget = 0;
}
- get enlarged() {
- return this.steps > 0;
- }
-
/** Forget the stroke in flight without forgetting where the zoom sits. */
clearEvidence() {
this._direction = '';
@@ -246,13 +242,12 @@ export class LiftMotion {
this.velocity = 0;
this.target = 0;
this.forward = true;
- this.toggles = 0;
this._lastAway = -Infinity;
}
+ /** Flip which way a lift travels, dropping the motion in flight with it. */
switchDirection() {
this.forward = !this.forward;
- this.toggles += 1;
this.velocity = 0;
this.target = 0;
this._lastAway = -Infinity;