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): explain the product to a signed-out visitor, and document delivering as a contact

nirholasdc073287e92d
diff --git a/pages/companion.html b/pages/companion.html
index 51c178102..a3a6fa2dd 100644
--- a/pages/companion.html
+++ b/pages/companion.html
@@ -142,9 +142,19 @@
.notice{background:rgba(59,130,246,.07);border:1px solid rgba(59,130,246,.22);border-radius:10px;padding:14px 16px;font-size:13px;line-height:1.6;color:var(--muted);}
.skeleton{background:var(--skeleton-base);background-image:linear-gradient(90deg,var(--skeleton-base) 0%,var(--skeleton-sheen) 50%,var(--skeleton-base) 100%);background-size:200% 100%;border-radius:8px;animation:shimmer 1.4s ease-in-out infinite;}
@keyframes shimmer{0%{background-position:200% 0;}100%{background-position:-200% 0;}}
- .auth-wall{text-align:center;padding:110px 20px;}
- .auth-wall h2{font-size:22px;font-weight:700;margin-bottom:12px;}
- .auth-wall p{color:var(--muted);font-size:14px;margin-bottom:24px;line-height:1.6;}
+ /* Signed-out pitch */
+ .pitch{padding:32px 0 40px;}
+ .pitch-lead h2{font-size:30px;font-weight:700;letter-spacing:-0.02em;line-height:1.25;max-width:680px;}
+ .pitch-lead p{color:var(--muted);font-size:15.5px;line-height:1.65;margin:14px 0 22px;max-width:640px;}
+ .pitch-grid{list-style:none;display:grid;grid-template-columns:repeat(auto-fit,minmax(228px,1fr));gap:14px;margin-top:36px;}
+ .pitch-grid li{background:var(--card);border:1px solid var(--line);border-radius:var(--radius);padding:18px;font-size:13.5px;color:var(--muted);line-height:1.6;}
+ .pitch-grid strong{display:block;color:var(--text);font-size:14.5px;font-weight:650;margin-bottom:7px;}
+ .pitch-steps{list-style:none;display:flex;flex-direction:column;gap:12px;margin-top:32px;counter-reset:step;}
+ .pitch-steps li{display:flex;gap:12px;align-items:flex-start;font-size:14px;color:var(--muted);line-height:1.6;}
+ .pitch-steps span{flex-shrink:0;width:24px;height:24px;border-radius:50%;background:rgba(59,130,246,.14);color:var(--blue);display:flex;align-items:center;justify-content:center;font-size:12px;font-weight:700;}
+ .pitch-foot{margin-top:30px;font-size:13.5px;color:var(--dim);line-height:1.65;max-width:640px;}
+ .pitch-foot a{color:var(--blue);}
+ @media(max-width:600px){.pitch-lead h2{font-size:24px;}}
/* Settings */
.settings-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:18px;}
input[type=range]{width:100%;accent-color:var(--blue);}
@@ -185,10 +195,57 @@
</div>
</div>
- <div id="auth-wall" class="auth-wall" hidden>
- <h2>Sign in to set up your companion</h2>
- <p>Your connections, contacts, and messages are private to your account and encrypted at rest.</p>
- <a href="/login?next=/companion" class="btn btn-primary">Sign in</a>
+ <!-- Signed out, this page still has to explain itself: someone arriving
+ from a link has never seen the idea before, and an empty sign-in
+ box tells them nothing about what they would be signing in to. -->
+ <div id="auth-wall" hidden>
+ <section class="pitch">
+ <div class="pitch-lead">
+ <h2>Your phone buzzes forty times a day. Two of those mattered.</h2>
+ <p>
+ The companion reads what comes in from the accounts you already use, decides what a
+ person would actually want a tap on the shoulder for, and then walks over and says it.
+ Everything else stays quiet, in a feed, with the reason it stayed quiet.
+ </p>
+ <div class="hero-actions">
+ <a href="/login?next=/companion" class="btn btn-primary">Sign in and set it up</a>
+ <a href="/register?next=/companion" class="btn">Create an account</a>
+ <a href="/docs/companion" class="btn">Read the docs</a>
+ </div>
+ </div>
+ <ul class="pitch-grid">
+ <li>
+ <strong>📱 Your phone, your Mac, anything</strong>
+ One token, one endpoint. An Android profile, a Shortcut, a Mail rule, a build script,
+ or an agent that decided you need to know.
+ </li>
+ <li>
+ <strong>✈️ Telegram</strong>
+ A bot you create yourself relays only the chats you add it to. Revoke it and the
+ connection is gone, with nothing left behind here.
+ </li>
+ <li>
+ <strong>📅 Calendar</strong>
+ The private iCal link Google, Apple, Outlook and CalDAV all publish. It tells you the
+ meeting is starting while you can still make it.
+ </li>
+ <li>
+ <strong>✉️ Email</strong>
+ IMAP with an app password. Read only, headers and a preview, and your unread state is
+ never touched. Or triage it on your own machine and send nothing but the sentence.
+ </li>
+ </ul>
+ <ol class="pitch-steps">
+ <li><span>1</span> Connect what you already use. Every credential is yours, and encrypted here.</li>
+ <li><span>2</span> Give the people who matter a face and a voice. Their messages arrive as them.</li>
+ <li><span>3</span> Set the bar, and the hours you will not be disturbed. That is the whole product.</li>
+ </ol>
+ <p class="pitch-foot">
+ It reaches you here, as a push on your phone, and on your desktop as a character that walks
+ across your screen. Developers get all of it as
+ <a href="/docs/companion">an SDK, a CLI, and an MCP server</a>.
+ </p>
+ </section>
</div>
<div id="page-error" class="error" hidden></div>
diff --git a/src/companion/page.js b/src/companion/page.js
index ddfe2b67c..b147ace57 100644
--- a/src/companion/page.js
+++ b/src/companion/page.js
@@ -660,9 +660,19 @@ function thumbnailFor(glbUrl) {
return avatar?.thumbnail_url || null;
}
+// Signed out: the page becomes an explanation of itself rather than a locked
+// door. The two buttons in the hero are for people who already have this set
+// up, so they go with the control room.
+function showPitch() {
+ el('auth-wall').hidden = false;
+ el('check-now').hidden = true;
+ document.querySelector('.hero p').textContent =
+ 'A 3D character that walks on and tells you the things worth interrupting you for, from the accounts you already use.';
+}
+
async function boot() {
if (!isAuthed()) {
- el('auth-wall').hidden = false;
+ showPitch();
return;
}
@@ -681,7 +691,7 @@ async function boot() {
state.avatars = avatars.avatars || [];
} catch (err) {
if (err.status === 401) {
- el('auth-wall').hidden = false;
+ showPitch();
return;
}
showError(`Could not load your companion: ${err.message}`);
diff --git a/walk-sdk/README.md b/walk-sdk/README.md
index 8ca921c94..1abb27e87 100644
--- a/walk-sdk/README.md
+++ b/walk-sdk/README.md
@@ -194,6 +194,30 @@ if (!delivered) showYourOwnToast(); // no WebGL, an iframe, or an excluded route
| `tone` | `'alert'` | `'alert'` tints the bubble; `'neutral'` is the ambient style |
| `emote` | `'wave'` | gesture on arrival, falling back to a wave on rigs without it |
| `actions` | none | up to two links/buttons under the line (`label`, `href`/`onClick`) |
+| `avatar` | none | deliver as somebody else: a roster id or a `makeGuestAvatarEntry()` entry |
+
+#### Delivering as somebody else
+
+A message from a person lands differently when that person delivers it. Pass
+`avatar` and the companion swaps into that body for the length of the message,
+then swaps back:
+
+```js
+import { createWalkCompanion, makeGuestAvatarEntry } from '@three-ws/walk';
+
+const walk = createWalkCompanion();
+
+await walk.announce('Sarah says she is downstairs and cannot find your door', {
+ avatar: makeGuestAvatarEntry('https://three.ws/api/avatars/<id>/glb', { name: 'Sarah' }),
+});
+// Sarah walks on, says it, and the visitor's own companion is back afterwards.
+```
+
+The swap is never persisted: the visitor's chosen avatar is still theirs when
+the delivery is over. A guest GLB that fails to load leaves the current body in
+place and the line is still delivered, so a missing avatar never costs the
+message. This is what powers [the three.ws Companion](https://three.ws/companion),
+where each contact has their own body and voice.
Returns `false` when no avatar could be shown, so the caller can fall back to
its own UI. The message is rendered as text, never HTML. A delivery outranks
diff --git a/walk-sdk/test/roster.test.mjs b/walk-sdk/test/roster.test.mjs
index 0849d7806..d06a1f6bc 100644
--- a/walk-sdk/test/roster.test.mjs
+++ b/walk-sdk/test/roster.test.mjs
@@ -17,6 +17,7 @@ import {
defaultAvatar,
listCategories,
makeApiAvatarEntry,
+ makeGuestAvatarEntry,
resolveAvatarUrl,
} from '../src/roster.js';
@@ -134,3 +135,21 @@ test('resolveAvatarUrl: null entry and asset-less static entry resolve to null',
assert.equal(resolveAvatarUrl(null), null);
assert.equal(resolveAvatarUrl({ source: 'static', asset: null }), null);
});
+
+test('makeGuestAvatarEntry: a message from a contact can be delivered by their own GLB', () => {
+ const entry = makeGuestAvatarEntry('https://three.ws/api/avatars/abc/glb', { name: 'Sarah' });
+ assert.equal(entry.name, 'Sarah');
+ assert.equal(entry.rig, 'shared');
+ assert.deepEqual(entry.clips, DEFAULT_SHARED_CLIPS);
+ // The URL is used verbatim: a guest body is somebody else's avatar, not one
+ // of ours to resolve against assetBase.
+ assert.equal(resolveAvatarUrl(entry, { assetBase: 'https://cdn.example' }), 'https://three.ws/api/avatars/abc/glb');
+});
+
+test('makeGuestAvatarEntry: distinct URLs get distinct ids so a swap is detectable', () => {
+ const a = makeGuestAvatarEntry('/avatars/one.glb');
+ const b = makeGuestAvatarEntry('/avatars/two.glb');
+ assert.notEqual(a.id, b.id);
+ assert.equal(makeGuestAvatarEntry('/avatars/one.glb', { id: 'pinned' }).id, 'pinned');
+ assert.equal(resolveAvatarUrl(a, { assetBase: 'https://cdn.example' }), 'https://cdn.example/avatars/one.glb');
+});