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
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.jsonindex 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.mdindex 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 browserdiff --git a/docs/sonar.md b/docs/sonar.mdindex 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.mdindex 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 agentdiff --git a/pages/gestures.html b/pages/gestures.htmlindex 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.htmlindex 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.cssindex 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.jsindex 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.jsindex 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.jsindex 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;