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.

feat(companion): design the stage for a browser that cannot render it, and put the feature in the docs index

nirholasc1c632cdbaa4
diff --git a/README.md b/README.md
index c7df56ceb..4e7723273 100644
--- a/README.md
+++ b/README.md
@@ -8539,6 +8539,14 @@ three.ws is production-ready and serves [three.ws](https://three.ws) live on Goo
## Key Features
+**Companion (your notifications, delivered in person)**
+
+- [three.ws/companion](https://three.ws/companion): connect your own Telegram bot, the private iCal link your calendar publishes, your inbox over IMAP with an app password, or nothing but a token your phone, your Mac, a build script or an AI agent can POST to
+- Every message is scored out of 100 (a saved contact asking you something, a one-time code, a meeting in ten minutes, a payment that failed); what clears your bar is spoken out loud, and everything else is kept in a feed with the reason it stayed quiet
+- Give a contact an avatar and a voice, and their messages arrive wearing that body
+- Reaches you on the site, as a push on your phone, and on your desktop via the [companion app](apps/desktop), a character that walks across your screen
+- Developers: [`@three-ws/companion`](packages/companion-sdk) ships the client, the same triage rules the server runs (score your own mail locally), a drop-in 3D stage, a CLI, and an MCP server so an agent can interrupt a human in person
+
**Text → 3D Generation (Forge)**
- Prompt-to-3D at [three.ws/forge](https://three.ws/forge) — describe an object in a sentence and download a textured GLB
diff --git a/docs/start-here.md b/docs/start-here.md
index 92752925a..136ed8c0f 100644
--- a/docs/start-here.md
+++ b/docs/start-here.md
@@ -73,6 +73,7 @@ Curious what happens between the prompt and the model? [How the Forge works](./h
- **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 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
- **Want to drive your agent's computer yourself?** → [Take the wheel](./agent-screen-control.md), every agent has a live screen you can watch on [/agent-screen](https://three.ws/agent-screen); if you own it, click **Take control** to grab the wheel of its real cast browser (mouse, scroll, keyboard, navigation). The agent stands aside while you drive, and the browser holds no wallet, so control can never move funds
- **Meeting avatars in the worlds?** → Press <kbd>I</kbd> on anyone in `/play`, `/city`, a coin world, or `/agora` to see who they are — the [avatar inspector](./avatar-inspector.md) shows their reputation, wallet, and profile
diff --git a/pages/companion.html b/pages/companion.html
index 855b25006..51c178102 100644
--- a/pages/companion.html
+++ b/pages/companion.html
@@ -88,6 +88,9 @@
.stage-viewer{background:linear-gradient(180deg,rgba(59,130,246,.08),transparent 60%),var(--bg-2);border:1px solid var(--line);border-radius:var(--radius);min-height:340px;position:relative;overflow:hidden;display:flex;align-items:center;justify-content:center;}
.stage-viewer agent-3d{width:100%;height:340px;display:block;}
.stage-empty{color:var(--dim);font-size:13px;text-align:center;padding:24px;line-height:1.6;}
+ .stage-viewer[data-fallback="1"]{flex-direction:column;gap:6px;padding:20px;}
+ .stage-face{width:96px;height:96px;border-radius:50%;object-fit:cover;border:1px solid var(--line-2);}
+ .stage-face-initial{display:flex;align-items:center;justify-content:center;font-size:34px;font-weight:600;color:var(--muted);background:var(--card);}
.stage-body{display:flex;flex-direction:column;gap:14px;}
.bubble{background:var(--card);border:1px solid var(--line-2);border-radius:var(--radius);padding:18px 20px;position:relative;}
.bubble:before{content:'';position:absolute;left:-7px;top:28px;width:12px;height:12px;background:var(--card);border-left:1px solid var(--line-2);border-bottom:1px solid var(--line-2);transform:rotate(45deg);}
diff --git a/src/companion/page.js b/src/companion/page.js
index 0a5930cec..ddfe2b67c 100644
--- a/src/companion/page.js
+++ b/src/companion/page.js
@@ -100,7 +100,9 @@ function renderStage() {
node.setAttribute('background', 'transparent');
node.setAttribute('alt', `${event.contact_name || event.sender || 'Your companion'} delivering a message`);
viewer.appendChild(node);
+ guardStage(node);
}
+ renderStageFace(event);
line.textContent = event.spoken_line || event.title;
meta.innerHTML = `
@@ -124,6 +126,39 @@ function renderStage() {
`;
}
+// A stage with no body in it is a void, and a void reads as broken. If the 3D
+// element never defines (no WebGL, a blocked CDN, an extension that eats module
+// scripts) the viewer shows who is speaking instead: their face if they have
+// one, their initial if not. The delivery still reads, and still speaks.
+const STAGE_ELEMENT_TIMEOUT_MS = 6000;
+let stageGuarded = false;
+
+function guardStage(node) {
+ if (stageGuarded) return;
+ stageGuarded = true;
+ Promise.race([
+ customElements.whenDefined('agent-3d'),
+ new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), STAGE_ELEMENT_TIMEOUT_MS)),
+ ]).catch(() => {
+ node.remove();
+ el('stage-viewer').dataset.fallback = '1';
+ renderStageFace(state.stageEvent);
+ });
+}
+
+function renderStageFace(event) {
+ const viewer = el('stage-viewer');
+ if (viewer.dataset.fallback !== '1' || !event) return;
+ const name = event.contact_name || event.sender || 'Your companion';
+ viewer.innerHTML = event.contact_avatar_image_url
+ ? `<img class="stage-face" src="${esc(event.contact_avatar_image_url)}" alt="${esc(name)}" />`
+ : `<div class="stage-face stage-face-initial" aria-hidden="true">${esc(name.slice(0, 1).toUpperCase())}</div>`;
+ const caption = document.createElement('div');
+ caption.className = 'stage-empty';
+ caption.textContent = `${name} is speaking. The 3D stage could not start in this browser.`;
+ viewer.appendChild(caption);
+}
+
async function sayStage() {
const event = state.stageEvent;
if (!event) return;