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
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.htmlindex 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.jsindex 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.mdindex 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 toits own UI. The message is rendered as text, never HTML. A delivery outranksdiff --git a/walk-sdk/test/roster.test.mjs b/walk-sdk/test/roster.test.mjsindex 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');+});