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): let a person tune the avatar presenter and the quiet window
nirholas2dcdecd9fdfa
diff --git a/api/companion/settings.js b/api/companion/settings.jsindex 3be4ddff4..39be89e0d 100644--- a/api/companion/settings.js+++ b/api/companion/settings.js@@ -27,8 +27,19 @@ const patchBody = z.object({const postBody = z.object({ rotate_token: z.literal(true) });+// The bridge URL is copy-pasted into an iOS Shortcut and a shell script, so it+// has to be the one that actually works from where the page was served. Behind+// the load balancer that is the forwarded proto; on a laptop talking to a local+// server over http, guessing https produced a URL whose every request died with+// ERR_SSL_PROTOCOL_ERROR, including the page's own "Send a test" button.+function originOf(req) {+ const forwarded = String(req.headers['x-forwarded-proto'] || '').split(',')[0].trim();+ const proto = forwarded || (req.socket?.encrypted ? 'https' : 'http');+ return `${proto}://${req.headers.host || 'three.ws'}`;+}+function shape(row, req) {- const origin = `${req.headers['x-forwarded-proto'] || 'https'}://${req.headers.host || 'three.ws'}`;+ const origin = originOf(req);return {settings: {enabled: row.enabled,diff --git a/herald-sdk/src/presenters/avatar.js b/herald-sdk/src/presenters/avatar.jsindex ea2f91f53..55dff4eaf 100644--- a/herald-sdk/src/presenters/avatar.js+++ b/herald-sdk/src/presenters/avatar.js@@ -7,30 +7,39 @@// CDN build) and hand it a line.//// Resolution order, cheapest first:-// 1. `window.__walkCompanion`: three.ws pages already run one, and reusing+// 1. A companion the integrator passed in (`companion` option). If you+// already build one, hand it over: nothing else has to resolve.+// 2. `window.__walkCompanion`: three.ws pages already run one, and reusing// it means the visitor's own avatar delivers the message instead of a// second character appearing beside it.-// 2. A companion the integrator passed in (`companion` option).-// 3. `import('@three-ws/walk')`: bundlers resolve this at build time.-// 4. `import(cdn)`: a plain <script type="module"> page with no bundler.+// 3. `walkModule`: a module URL (or bare specifier) to import at runtime.+// Either it exports `createWalkCompanion`, or it installs the global on+// import, which is how the three.ws build serves it at /walk-companion.js.// Every rung is optional. If none resolve, `ready()` is false and the runtime// falls back to the card presenter, which needs nothing at all.--const DEFAULT_CDN = 'https://three.ws/agent-3d/latest/walk.mjs';+//+// The import is deliberately NOT a static specifier: a bundler that resolved+// `@three-ws/walk` at build time would make an optional peer dependency a hard+// build-time one, and a missing dist/ would fail the whole build rather than+// costing one delivery its 3D body./*** @param {object} [opts]* @param {object} [opts.companion] a control object from createWalkCompanion()* @param {object} [opts.companionOptions] options used when this presenter* creates its own companion (avatars, defaultAvatarId, assetBase, apiBase...)- * @param {string|null} [opts.cdn] module URL used when the package is absent+ * @param {string|null} [opts.walkModule] module URL or specifier to import when+ * no companion was passed and none is live on the page* @param {(name: string) => any} [opts.globalLookup] test seam for window lookups+ * @param {(spec: string) => Promise<any>} [opts.importModule] test seam for the+ * dynamic import*/export function createAvatarPresenter({companion = null,companionOptions = null,- cdn = DEFAULT_CDN,+ walkModule = null,globalLookup = (name) => globalThis?.[name],+ importModule = (spec) => import(/* @vite-ignore */ spec),} = {}) {let control = companion;let resolving = null;@@ -41,13 +50,23 @@ export function createAvatarPresenter({resolving = (async () => {const live = globalLookup('__walkCompanion');if (live && typeof live.announce === 'function') return live;+ if (!walkModule) return null;- const mod = await importWalk(cdn);- if (!mod?.createWalkCompanion) return null;- const created = mod.createWalkCompanion(companionOptions || {});- // Never flip the visitor's persisted companion preference on: the- // SDK borrows the corner for a message and gives it straight back.- return created;+ let mod = null;+ try {+ mod = await importModule(walkModule);+ } catch {+ return null;+ }+ if (typeof mod?.createWalkCompanion === 'function') {+ // Never flip the visitor's persisted companion preference on: the+ // SDK borrows the corner for a message and gives it straight back.+ return mod.createWalkCompanion(companionOptions || {});+ }+ // A module that installs the global on import (the three.ws build at+ // /walk-companion.js) rather than exporting a factory.+ const installed = globalLookup('__walkCompanion');+ return installed && typeof installed.announce === 'function' ? installed : null;})().catch(() => null).then((resolved) => {@@ -92,18 +111,3 @@ export function createAvatarPresenter({return { name: 'avatar', ready, present, stop, get control() { return control; } };}--// Kept separate so a bundler that cannot resolve the optional package still-// produces a working build: the failure is caught and the CDN rung runs.-async function importWalk(cdn) {- try {- return await import(/* @vite-ignore */ '@three-ws/walk');- } catch {- if (!cdn) return null;- try {- return await import(/* @vite-ignore */ cdn);- } catch {- return null;- }- }-}diff --git a/src/stream-demo.js b/src/stream-demo.jsindex cb603d2be..6f1ec7839 100644--- a/src/stream-demo.js+++ b/src/stream-demo.js@@ -61,7 +61,12 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));* Meter a byte payload against a downlink budget.* Resolves only once the last byte would have arrived at the given rate.*/-async function meter(byteLength, bytesPerSecond, onProgress) {+function abortError() {+ return new DOMException('The run was superseded', 'AbortError');+}++async function meter(byteLength, bytesPerSecond, onProgress, signal) {+ if (signal?.aborted) throw abortError();if (!Number.isFinite(bytesPerSecond)) {onProgress?.(byteLength);return;@@ -69,15 +74,19 @@ async function meter(byteLength, bytesPerSecond, onProgress) {const totalMs = (byteLength / bytesPerSecond) * 1000;const started = performance.now();let delivered = 0;- // Tick often enough to animate, rarely enough to stay cheap.+ // Tick often enough to animate, rarely enough to stay cheap. Changing the+ // avatar or the downlink mid-run must stop this loop, or a superseded run+ // keeps writing into panels the new run has already reset.while (delivered < byteLength) {await sleep(Math.min(50, Math.max(8, totalMs / 40)));+ if (signal?.aborted) throw abortError();const elapsed = performance.now() - started;delivered = Math.min(byteLength, (elapsed / 1000) * bytesPerSecond);onProgress?.(delivered);}const remaining = totalMs - (performance.now() - started);if (remaining > 0) await sleep(remaining);+ if (signal?.aborted) throw abortError();onProgress?.(byteLength);}@@ -240,8 +249,7 @@ async function runClassic(panel, avatar, bytesPerSecond, signal) {panel.log(`GET ${avatar.src}`);panel.log(`${fmtBytes(buffer.byteLength)} to download before the first pixel`);- await meter(buffer.byteLength, bytesPerSecond, (delivered) => panel.progress(delivered, buffer.byteLength));- if (signal.aborted) return null;+ await meter(buffer.byteLength, bytesPerSecond, (delivered) => panel.progress(delivered, buffer.byteLength), signal);const loader = new GLTFLoader();await configureLoader(loader);@@ -270,7 +278,7 @@ async function runStream(panel, avatar, bytesPerSecond, signal) {const buffer = new Uint8Array(await response.arrayBuffer());await meter(buffer.byteLength, bytesPerSecond, (delivered) => {panel.progress(transferred + delivered, totalBytes);- });+ }, signal);transferred += buffer.byteLength;return {ok: response.ok,@@ -301,7 +309,6 @@ async function runStream(panel, avatar, bytesPerSecond, signal) {};panel.statusEl.textContent = 'refining';await player.refine();- if (signal.aborted) return null;panel.stage.playClips(player.animations);panel.finish();panel.bytesEl.textContent = fmtBytes(transferred);