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(spotlight): show one idling avatar instead of a T-posed preview behind it

nirholas1da0631d849e
diff --git a/data/changelog.json b/data/changelog.json
index cd5789045..74d5c65c0 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,13 @@
{
"$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, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-01",
+ "title": "Avatars no longer open in a T-pose, and Spotlight shows one avatar instead of two",
+ "summary": "On an Agent Spotlight page the avatar's preview picture, which is rendered arms out, never went away once the live 3D avatar loaded, so a second, T-posed copy stood behind the real one for as long as the page was open. The picture now gives way the moment the live avatar is ready. Separately, every embedded 3D avatar briefly showed its arms-out rest pose while its idle animation loaded and then faded in from it. The avatar now stays hidden until it is standing in its idle, then fades in, everywhere the avatar component is used.",
+ "tags": ["fix"],
+ "link": "/spotlight"
+ },
{
"date": "2026-10-01",
"title": "Trading agents stop leaking SOL on every trade and can now ride a runner",
diff --git a/docs/web-component.md b/docs/web-component.md
index 5e4fb8ff0..6c8b5e593 100644
--- a/docs/web-component.md
+++ b/docs/web-component.md
@@ -497,7 +497,7 @@ All events bubble and are `composed: true`, meaning they cross shadow DOM bounda
| Event | Detail | When |
|-------|--------|------|
-| `agent:ready` | `{ agent, manifest }` | Fully booted — manifest loaded, skills installed, brain connected. |
+| `agent:ready` | `{ agent, manifest }` | Fully booted: manifest loaded, skills installed, brain connected. The body is already on screen holding its first clip (idle, or the `clip` attribute): the element keeps its canvas hidden until that pose has rendered, so a bind-pose T-pose is never shown. This is the event to swap out your own placeholder image on. |
| `agent:load-progress` | `{ phase, pct }` | Incremental boot progress. `phase` is one of `"manifest"`, `"body"`, `"memory"`, `"skills"`, `"brain"`. `pct` is 0–1. |
| `agent:error` | `{ phase, error }` | A fatal error occurred during boot or at runtime. |
diff --git a/src/animation-manager.js b/src/animation-manager.js
index f040c5169..36ccbfc92 100644
--- a/src/animation-manager.js
+++ b/src/animation-manager.js
@@ -676,10 +676,15 @@ export class AnimationManager {
* (`celebrate`, `wave`, …). Lazily loads both the one-shot and the settle clip.
*
* @param {string} name
- * @param {{ settleTo?: string|null, fade?: number }} [opts]
+ * @param {{ settleTo?: string|null, fade?: number, fadeIn?: number }} [opts]
+ * `fade` is the settle crossfade back into `settleTo`; `fadeIn` (default
+ * `fade`) is the fade into the one-shot itself. A caller starting a freshly
+ * loaded body passes `fadeIn: 0`, since fading in from nothing is a fade
+ * from the bind pose.
*/
- async playOnce(name, { settleTo = 'idle', fade = DEFAULT_CROSSFADE } = {}) {
+ async playOnce(name, { settleTo = 'idle', fade = DEFAULT_CROSSFADE, fadeIn = fade } = {}) {
fade = Math.max(0, Math.min(fade, 5));
+ fadeIn = Math.max(0, Math.min(fadeIn, 5));
const ready = await this.ensureLoaded(name);
const action = ready ? this.actions.get(name) : null;
// Reject a fallen-pose retarget the same way an unavailable clip is handled:
@@ -687,7 +692,7 @@ export class AnimationManager {
if (!action || !this._guardAgainstFallenPose(name, action)) {
// One-shot unavailable on this rig — fall back to the settle clip so
// the avatar is never left frozen in its bind pose.
- if (settleTo) return this.crossfadeTo(settleTo, fade);
+ if (settleTo) return this.crossfadeTo(settleTo, fadeIn);
return;
}
@@ -698,9 +703,9 @@ export class AnimationManager {
action.clampWhenFinished = true;
action.play();
if (this.currentAction && this.currentAction !== action) {
- this.currentAction.crossFadeTo(action, fade, true);
+ this.currentAction.crossFadeTo(action, fadeIn, true);
} else {
- action.fadeIn(fade);
+ action.fadeIn(fadeIn);
}
this.currentAction = action;
this.currentName = name;
diff --git a/src/element.js b/src/element.js
index 077cf0261..0154fc274 100644
--- a/src/element.js
+++ b/src/element.js
@@ -195,7 +195,12 @@ const BASE_STYLE = `
inset: 0;
width: 100%;
height: 100%;
+ transition: opacity 220ms ease-out;
}
+ /* Held while a freshly loaded body has no pose yet. The renderer paints the
+ rig the moment the GLB lands, which is its bind pose (a T-pose), and the
+ idle clip only takes over after it is fetched and retargeted. */
+ .stage.is-settling { opacity: 0; transition: none; }
.stage canvas { display: block; }
/* Pill tap target — shown when collapsed to pill on narrow viewports */
.pill-btn {
@@ -1629,6 +1634,9 @@ class Agent3DElement extends HTMLElement {
// Bare avatars run the viewer in kiosk mode: GUI closed, camera snapped
// (no fly-in), and a lower DPR cap — the right profile for a lightweight
// decoration avatar. Chat agents get the full interactive viewer.
+ // The stage stays hidden until the body holds its first pose; see
+ // _startInitialPlayback.
+ this._stageEl.classList.add('is-settling');
const viewer = new Viewer(this._stageEl, {
kiosk: !this._isChatMode(),
framing: this.getAttribute('framing') === 'portrait' ? 'portrait' : 'full',
@@ -1731,13 +1739,8 @@ class Agent3DElement extends HTMLElement {
// reached this line threw "bodyURI is not defined" and the element
// showed its error overlay instead of the avatar. eslint knew (no-undef),
// but it was a warning, so nothing stopped it shipping.
- if (bodyCandidates.length) {
- if (this._isChatMode()) {
- this._scene.playClipByName('idle', { loop: true });
- } else {
- this._startDecorationPlayback();
- }
- }
+ if (bodyCandidates.length) await this._startInitialPlayback();
+ this._stageEl.classList.remove('is-settling');
// Memory
this._emit('agent:load-progress', { phase: 'memory', pct: 0.6 });
@@ -2133,6 +2136,7 @@ class Agent3DElement extends HTMLElement {
{ bubbles: true, composed: true },
);
} finally {
+ this._stageEl?.classList.remove('is-settling');
this._booting = false;
}
}
@@ -3284,16 +3288,44 @@ class Agent3DElement extends HTMLElement {
}
/**
- * Start initial playback for a bare/decoration avatar: honor the `clip`
- * attribute (default idle), the clip's loop flag, and prefers-reduced-motion.
+ * The first pose a freshly loaded body takes, held off-screen until it has
+ * rendered. Nothing is playing yet, so the usual crossfade would blend the
+ * clip in from the bind pose and every avatar would open on a T-pose with its
+ * arms swinging down. The clip snaps in instead (fade 0), and the stage is
+ * revealed two frames later: microtasks (the cached clip's lazy-load await)
+ * always drain before a frame, the first frame ticks the mixer and paints the
+ * pose, and the second is composited. A rig that cannot take the clip is
+ * revealed all the same, on whatever pose the viewer gave it.
+ *
+ * @returns {Promise<void>}
+ */
+ async _startInitialPlayback() {
+ if (this._isChatMode()) {
+ this._scene.playClipByName('idle', { loop: true, fade_ms: 0 });
+ } else {
+ // idle and walk were fetched during the load; a `clip` attribute naming
+ // anything else is fetched here, so the reveal waits for it too.
+ const clip = this.getAttribute('clip');
+ if (clip) await this._viewer?.animationManager?.ensureLoaded(clip);
+ this._startDecorationPlayback({ fade_ms: 0 });
+ }
+ this._viewer?.invalidate();
+ await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+ }
+
+ /**
+ * Start playback for a bare/decoration avatar: honor the `clip` attribute
+ * (default idle), the clip's loop flag, and prefers-reduced-motion.
+ * @param {{ fade_ms?: number }} [opts] fade into the clip; 0 snaps, which is
+ * what the first pose after a load needs (see _startInitialPlayback).
*/
- _startDecorationPlayback() {
+ _startDecorationPlayback({ fade_ms = 400 } = {}) {
if (!this._scene) return;
if (this._prefersReducedMotion()) {
this._playStaticIdle();
return;
}
- this._playDecorationClip(this.getAttribute('clip') || 'idle', 400);
+ this._playDecorationClip(this.getAttribute('clip') || 'idle', fade_ms);
}
/**
@@ -3311,7 +3343,9 @@ class Agent3DElement extends HTMLElement {
if (loops) {
this._scene?.playClipByName(name, { loop: true, fade_ms });
} else if (am && typeof am.playOnce === 'function') {
- am.playOnce(name, { settleTo: 'idle', fade: fade_ms / 1000 });
+ // A snapped start (fade_ms 0) still settles back into idle with a
+ // real crossfade rather than a hard cut.
+ am.playOnce(name, { settleTo: 'idle', fade: (fade_ms || 400) / 1000, fadeIn: fade_ms / 1000 });
} else {
this._scene?.playClipByName(name, { loop: false, fade_ms });
}
diff --git a/src/spotlight-shared.js b/src/spotlight-shared.js
index 3f9fe8de1..0c8cc63cc 100644
--- a/src/spotlight-shared.js
+++ b/src/spotlight-shared.js
@@ -83,28 +83,37 @@ function loadAgent3d() {
document.head.appendChild(s);
}
-// Hide the still only once <agent-3d> has painted a canvas of its own. There is
-// no documented ready event on the component, and a canvas in the DOM is the one
-// signal that means the model is genuinely on screen. Give up after a bounded
-// wait and leave the still in place, which is the correct outcome when the GLB
-// never arrives.
-function revealWhenPainted(viewer, still) {
- let settled = false;
- const painted = () =>
- Boolean(viewer.querySelector('canvas') || viewer.shadowRoot?.querySelector('canvas'));
- const done = () => {
- if (settled) return;
- settled = true;
- observer.disconnect();
- clearTimeout(timer);
- still.classList.add('is-hidden');
- };
- const observer = new MutationObserver(() => {
- if (painted()) done();
- });
- observer.observe(viewer, { childList: true, subtree: true });
- const timer = setTimeout(() => observer.disconnect(), 15000);
- if (painted()) done();
+// Swap the still for the viewer only when <agent-3d> reports `agent:ready`, the
+// component's one success signal: the GLB is loaded, framed and holding its
+// idle. Until then the viewer stays transparent (spotlight.css), and at that
+// moment the still goes and the viewer fades in, in the same frame. The still
+// is a bind-pose render and the viewer's canvas is transparent, so any moment
+// both are visible reads as a second, T-posed copy of the avatar standing
+// behind the live one. Watching for a canvas used to be the signal here, but the
+// component draws into its shadow root, which a MutationObserver on the host
+// never sees, so the still stayed up for the life of the page.
+//
+// On `agent:error` the viewer is removed instead, leaving the still as the only
+// thing on the stage: an image of the avatar beats an empty, draggable void.
+// When neither event fires (the loader script never arrived) the still simply
+// stays, which is also the right outcome.
+export function revealWhenReady(viewer, still) {
+ viewer.addEventListener(
+ 'agent:ready',
+ () => {
+ still.classList.add('is-hidden');
+ still.setAttribute('aria-hidden', 'true');
+ viewer.classList.add('is-ready');
+ },
+ { once: true },
+ );
+ viewer.addEventListener(
+ 'agent:error',
+ () => {
+ if (!still.classList.contains('is-hidden')) viewer.remove();
+ },
+ { once: true },
+ );
}
/**
@@ -142,8 +151,10 @@ export function stageFor(entry, { badge = null, eager = false } = {}) {
'camera-controls': 'true',
'aria-label': `${entry.agent.name} in 3D`,
});
+ // Listeners go on before the element is attached, so a model that is
+ // already cached cannot report ready before anyone is listening.
+ revealWhenReady(viewer, still);
stage.append(viewer);
- revealWhenPainted(viewer, still);
};
if (eager || !('IntersectionObserver' in window)) {
diff --git a/src/spotlight.css b/src/spotlight.css
index 99f801ef0..89382056c 100644
--- a/src/spotlight.css
+++ b/src/spotlight.css
@@ -309,11 +309,22 @@
height: 100%;
min-height: 320px;
display: block;
+ opacity: 0;
+ pointer-events: none;
+ transition: opacity var(--duration-base, 240ms) var(--ease-out, ease-out);
+}
+
+.sp-stage agent-3d.is-ready {
+ opacity: 1;
+ pointer-events: auto;
}
-/* The still sits under the 3D viewer and is removed only once that viewer has
- painted. A GLB that never loads therefore degrades to the avatar image
- instead of an empty hero. */
+/* The still sits under the 3D viewer and is removed only once that viewer
+ reports agent:ready, which is also when the viewer itself is shown. A GLB
+ that never loads therefore degrades to the avatar image instead of an empty
+ hero. The still leaves in one frame rather than fading: it is a bind-pose
+ render framed differently from the live viewer, so any overlap between the
+ two reads as a ghost of the avatar, arms out, behind the real one. */
.sp-stage-still,
.sp-stage .sp-mono {
position: absolute;
@@ -321,7 +332,6 @@
width: 100%;
height: 100%;
object-fit: cover;
- transition: opacity var(--duration-slow, var(--duration-slow)) var(--ease-out);
}
.sp-stage-still.is-hidden,
diff --git a/tests/spotlight-stage.test.js b/tests/spotlight-stage.test.js
new file mode 100644
index 000000000..9daf551d1
--- /dev/null
+++ b/tests/spotlight-stage.test.js
@@ -0,0 +1,82 @@
+// @vitest-environment jsdom
+//
+// The /spotlight 3D stage (stageFor in src/spotlight-shared.js). The stage
+// layers a still image under a transparent <agent-3d> canvas, so the still must
+// leave exactly when the live avatar is ready. It used to wait for a canvas to
+// appear, but the component draws inside its shadow root, which the host-level
+// observer never saw: the bind-pose still stayed up for the life of the page and
+// read as a second, T-posed avatar standing behind the animated one.
+import { describe, it, expect } from 'vitest';
+import { stageFor } from '../src/spotlight-shared.js';
+
+function entryWith(agent = {}) {
+ return {
+ id: 'entry-1',
+ title: 'An entry',
+ agent: {
+ id: 'agent-1',
+ name: 'Glyph',
+ thumbnail: 'https://cdn.example/avatar_og.png',
+ glb_url: 'https://cdn.example/avatar.glb',
+ ...agent,
+ },
+ };
+}
+
+function mountEager(entry) {
+ const stage = stageFor(entry, { eager: true });
+ document.body.append(stage);
+ return {
+ stage,
+ still: stage.querySelector('.sp-stage-still'),
+ viewer: stage.querySelector('agent-3d'),
+ };
+}
+
+function fire(node, type) {
+ node.dispatchEvent(new CustomEvent(type, { bubbles: true, composed: true }));
+}
+
+describe('stageFor still and viewer handoff', () => {
+ it('keeps the still while the viewer has only drawn into its shadow root', () => {
+ const { still, viewer } = mountEager(entryWith());
+ viewer.attachShadow({ mode: 'open' }).append(document.createElement('canvas'));
+ expect(still.classList.contains('is-hidden')).toBe(false);
+ expect(viewer.classList.contains('is-ready')).toBe(false);
+ });
+
+ it('swaps the still for the viewer once the viewer reports agent:ready', () => {
+ const { still, viewer } = mountEager(entryWith());
+ fire(viewer, 'agent:ready');
+ expect(viewer.classList.contains('is-ready')).toBe(true);
+ expect(still.classList.contains('is-hidden')).toBe(true);
+ expect(still.getAttribute('aria-hidden')).toBe('true');
+ expect(viewer.isConnected).toBe(true);
+ });
+
+ it('drops the viewer and keeps the still when boot fails', () => {
+ const { stage, still, viewer } = mountEager(entryWith());
+ fire(viewer, 'agent:error');
+ expect(stage.querySelector('agent-3d')).toBeNull();
+ expect(still.classList.contains('is-hidden')).toBe(false);
+ });
+
+ it('keeps a ready viewer when a later error (a failed chat send) arrives', () => {
+ const { stage, viewer } = mountEager(entryWith());
+ fire(viewer, 'agent:ready');
+ fire(viewer, 'agent:error');
+ expect(stage.querySelector('agent-3d')).toBe(viewer);
+ });
+
+ it('mounts exactly one viewer and one still', () => {
+ const { stage } = mountEager(entryWith());
+ expect(stage.querySelectorAll('agent-3d')).toHaveLength(1);
+ expect(stage.querySelectorAll('.sp-stage-still')).toHaveLength(1);
+ });
+
+ it('shows only the monogram when the agent has neither thumbnail nor model', () => {
+ const { stage } = mountEager(entryWith({ thumbnail: null, glb_url: null }));
+ expect(stage.querySelector('agent-3d')).toBeNull();
+ expect(stage.querySelector('.sp-mono')).not.toBeNull();
+ });
+});
diff --git a/tests/src/animation-decoration-playback.test.js b/tests/src/animation-decoration-playback.test.js
index e6e0584df..7fc2c549d 100644
--- a/tests/src/animation-decoration-playback.test.js
+++ b/tests/src/animation-decoration-playback.test.js
@@ -128,6 +128,27 @@ describe('AnimationManager.playOnce (one-shot → settle, no hard snap)', () =>
expect(crossfadeSpy).not.toHaveBeenCalled();
});
+ it('snaps a one-shot in with fadeIn 0 but still settles with the full fade', async () => {
+ // A freshly loaded body has nothing playing, so fading in means fading
+ // from the bind pose: <agent-3d> starts its first clip with fadeIn 0.
+ const mgr = seedManager(['celebrate', 'idle']);
+ const celebrate = mgr.actions.get('celebrate');
+ const fadeInSpy = vi.spyOn(celebrate, 'fadeIn');
+ const crossfadeSpy = vi.spyOn(mgr, 'crossfadeTo');
+ await mgr.playOnce('celebrate', { settleTo: 'idle', fade: 0.4, fadeIn: 0 });
+ expect(fadeInSpy).toHaveBeenCalledWith(0);
+
+ mgr.mixer.dispatchEvent({ type: 'finished', action: celebrate });
+ expect(crossfadeSpy).toHaveBeenCalledWith('idle', 0.4);
+ });
+
+ it('snaps straight into the settle clip when a snapped one-shot is unavailable', async () => {
+ const mgr = seedManager(['idle']);
+ const crossfadeSpy = vi.spyOn(mgr, 'crossfadeTo');
+ await mgr.playOnce('celebrate', { settleTo: 'idle', fade: 0.4, fadeIn: 0 });
+ expect(crossfadeSpy).toHaveBeenCalledWith('idle', 0);
+ });
+
it('settles into the fallback clip when the one-shot is unavailable on the rig', async () => {
const mgr = seedManager(['idle']); // celebrate not loaded / unsupported
const crossfadeSpy = vi.spyOn(mgr, 'crossfadeTo');
diff --git a/tests/src/element-initial-pose.test.js b/tests/src/element-initial-pose.test.js
new file mode 100644
index 000000000..b572959ef
--- /dev/null
+++ b/tests/src/element-initial-pose.test.js
@@ -0,0 +1,90 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// The first pose a freshly loaded <agent-3d> body takes. The renderer paints a
+// rig the moment its GLB lands, in its bind pose (a T-pose), and the idle clip
+// only takes over once it is fetched and retargeted; the clip then used to fade
+// in from that bind pose. Every bare embed opened on a T-pose with its arms
+// swinging down, which the /spotlight filming run caught on 2026-10-01. Boot now
+// holds the stage hidden (`.stage.is-settling`) and snaps the first clip in
+// (fade 0) before revealing it.
+vi.mock('../../src/viewer.js', () => ({ Viewer: class {} }));
+vi.mock('dat.gui', () => ({
+ GUI: class {
+ addFolder() { return this; }
+ add() { return { onChange: () => this, name: () => this }; }
+ addColor() { return { onChange: () => this, name: () => this }; }
+ destroy() {}
+ },
+}));
+
+import '../../src/element.js';
+
+function rigged(el, { defs = [{ name: 'idle', loop: true }] } = {}) {
+ const scene = { playClipByName: vi.fn(() => true) };
+ const am = {
+ getAnimationDefs: () => defs,
+ ensureLoaded: vi.fn(async () => true),
+ playOnce: vi.fn(async () => {}),
+ };
+ el._scene = scene;
+ el._viewer = { animationManager: am, invalidate: vi.fn() };
+ return { scene, am };
+}
+
+beforeEach(() => {
+ vi.stubGlobal('requestAnimationFrame', (cb) => setTimeout(() => cb(performance.now()), 0));
+ vi.stubGlobal('matchMedia', () => ({ matches: false, addEventListener() {}, removeEventListener() {} }));
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+});
+
+describe('<agent-3d> first pose after a body loads', () => {
+ it('hides the stage while settling, in the shadow stylesheet', () => {
+ const el = document.createElement('agent-3d');
+ document.body.appendChild(el);
+ const css = [...el.shadowRoot.querySelectorAll('style')].map((s) => s.textContent).join('\n');
+ expect(css).toMatch(/\.stage\.is-settling\s*\{\s*opacity:\s*0/);
+ el.remove();
+ });
+
+ it('snaps a bare avatar into idle instead of fading in from the bind pose', async () => {
+ const el = document.createElement('agent-3d');
+ const { scene } = rigged(el);
+ await el._startInitialPlayback();
+ expect(scene.playClipByName).toHaveBeenCalledWith('idle', { loop: true, fade_ms: 0 });
+ expect(el._viewer.invalidate).toHaveBeenCalled();
+ });
+
+ it('snaps a chat agent into idle the same way', async () => {
+ const el = document.createElement('agent-3d');
+ el.setAttribute('chat', '');
+ expect(el._isChatMode()).toBe(true);
+ const { scene } = rigged(el);
+ await el._startInitialPlayback();
+ expect(scene.playClipByName).toHaveBeenCalledWith('idle', { loop: true, fade_ms: 0 });
+ });
+
+ it('fetches a requested one-shot clip before the reveal and settles with a real crossfade', async () => {
+ const el = document.createElement('agent-3d');
+ el.setAttribute('clip', 'wave');
+ const { am } = rigged(el, {
+ defs: [
+ { name: 'idle', loop: true },
+ { name: 'wave', loop: false },
+ ],
+ });
+ await el._startInitialPlayback();
+ expect(am.ensureLoaded).toHaveBeenCalledWith('wave');
+ expect(am.playOnce).toHaveBeenCalledWith('wave', { settleTo: 'idle', fade: 0.4, fadeIn: 0 });
+ });
+
+ it('keeps the default crossfade for clip changes after boot', () => {
+ const el = document.createElement('agent-3d');
+ const { scene } = rigged(el);
+ el._startDecorationPlayback();
+ expect(scene.playClipByName).toHaveBeenCalledWith('idle', { loop: true, fade_ms: 400 });
+ });
+});