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(walk-sdk): let a message be delivered by the sender's own avatar
nirholas587bd94369d6
diff --git a/tests/notification-herald.test.js b/tests/notification-herald.test.jsnew file mode 100644index 000000000..c99be7374--- /dev/null+++ b/tests/notification-herald.test.js@@ -0,0 +1,161 @@+// Unit tests for the notification herald's decision rules+// (src/notification-herald.js): what the corner avatar is allowed to walk on+// screen and say out loud, and what it must stay quiet about.+//+// Only the pure exports are exercised here. The module touches no DOM at import+// time on purpose (every browser dependency is a dynamic import inside a+// function), so it loads in the node test environment as-is.++import { describe, it, expect } from 'vitest';+import {+ holdMsFor,+ isFresh,+ categoryFor,+ announcesCategory,+ pickAnnouncements,+ emoteFor,+} from '../src/notification-herald.js';+import { typeCategoryMap } from '../api/_lib/notify-prefs.js';++const NOW = Date.parse('2026-08-28T12:00:00.000Z');+const ago = (ms) => new Date(NOW - ms).toISOString();++const TYPES = typeCategoryMap();++// Announce sales; stay quiet about everything else.+const PREFS = {+ categories: {+ sales: { in_app: true, push: true, email: true, telegram: false, avatar: true },+ social: { in_app: true, push: true, email: false, telegram: false, avatar: false },+ account: { in_app: true, push: true, email: true, telegram: false, avatar: true },+ },+};++function notif(over = {}) {+ return {+ id: over.id || 'n1',+ type: over.type || 'sale',+ payload: over.payload || {},+ read_at: over.read_at ?? null,+ created_at: over.created_at || ago(60_000),+ };+}++describe('holdMsFor', () => {+ it('scales the dwell with the length of the line', () => {+ expect(holdMsFor('short')).toBeLessThan(holdMsFor('a considerably longer line of copy'));+ });++ it('never parks the avatar on screen, however long the payload', () => {+ expect(holdMsFor('x'.repeat(5000))).toBe(12_000);+ });++ it('handles a missing line without throwing', () => {+ expect(holdMsFor(undefined)).toBeGreaterThan(0);+ });+});++describe('isFresh', () => {+ it('accepts a notification from the last quarter hour', () => {+ expect(isFresh(ago(60_000), NOW)).toBe(true);+ expect(isFresh(ago(14 * 60_000), NOW)).toBe(true);+ });++ it('rejects anything older: that is inbox history, not news', () => {+ expect(isFresh(ago(16 * 60_000), NOW)).toBe(false);+ expect(isFresh(ago(48 * 3600_000), NOW)).toBe(false);+ });++ it('rejects a far-future timestamp and unparseable input', () => {+ expect(isFresh(new Date(NOW + 3600_000).toISOString(), NOW)).toBe(false);+ expect(isFresh('not a date', NOW)).toBe(false);+ expect(isFresh(undefined, NOW)).toBe(false);+ });+});++describe('categoryFor', () => {+ it('uses the map the server sends', () => {+ expect(categoryFor('sale', TYPES)).toBe('sales');+ expect(categoryFor('follow', TYPES)).toBe('social');+ expect(categoryFor('forge_complete', TYPES)).toBe('creations');+ });++ it('falls back to account for an unmapped type, exactly like the server', () => {+ expect(categoryFor('brand_new_type', TYPES)).toBe('account');+ expect(categoryFor('sale', undefined)).toBe('account');+ });+});++describe('announcesCategory', () => {+ it('requires an explicit true: an absent matrix announces nothing', () => {+ expect(announcesCategory(PREFS, 'sales')).toBe(true);+ expect(announcesCategory(PREFS, 'social')).toBe(false);+ expect(announcesCategory(PREFS, 'irl')).toBe(false);+ expect(announcesCategory(null, 'sales')).toBe(false);+ expect(announcesCategory({}, 'sales')).toBe(false);+ });+});++describe('pickAnnouncements', () => {+ const base = { prefs: PREFS, typeCategories: TYPES, announced: new Set(), now: NOW };++ it('announces a fresh, unread, opted-in notification', () => {+ const { deliver, overflow } = pickAnnouncements([notif()], base);+ expect(deliver.map((n) => n.id)).toEqual(['n1']);+ expect(overflow).toBe(0);+ });++ it('skips read, stale, muted-category, and already-announced rows', () => {+ const rows = [+ notif({ id: 'read', read_at: ago(1000) }),+ notif({ id: 'stale', created_at: ago(60 * 60_000) }),+ notif({ id: 'muted', type: 'follow' }),+ notif({ id: 'said' }),+ ];+ const { deliver } = pickAnnouncements(rows, {+ ...base,+ announced: new Set(['said']),+ });+ expect(deliver).toEqual([]);+ });++ it('delivers newest first', () => {+ const rows = [+ notif({ id: 'older', created_at: ago(9 * 60_000) }),+ notif({ id: 'newer', created_at: ago(60_000) }),+ ];+ expect(pickAnnouncements(rows, base).deliver.map((n) => n.id)).toEqual(['newer', 'older']);+ });++ it('caps the batch at two and reports the rest as overflow', () => {+ const rows = [1, 2, 3, 4, 5].map((i) =>+ notif({ id: `n${i}`, created_at: ago(i * 60_000) }),+ );+ const { deliver, overflow } = pickAnnouncements(rows, base);+ expect(deliver.map((n) => n.id)).toEqual(['n1', 'n2']);+ expect(overflow).toBe(3);+ });++ it('tolerates junk input rather than throwing at delivery time', () => {+ expect(pickAnnouncements(null, base).deliver).toEqual([]);+ expect(pickAnnouncements([null, {}, notif()], base).deliver.map((n) => n.id)).toEqual(['n1']);+ });++ it('an unmapped type follows the account row, which announces by default', () => {+ const rows = [notif({ id: 'x', type: 'brand_new_type' })];+ expect(pickAnnouncements(rows, base).deliver.map((n) => n.id)).toEqual(['x']);+ });+});++describe('emoteFor', () => {+ it('celebrates money and finished work', () => {+ expect(emoteFor('sale')).toBe('dance');+ expect(emoteFor('royalty_paid')).toBe('dance');+ expect(emoteFor('forge_complete')).toBe('dance');+ });++ it('waves for everything else, including a type it has never seen', () => {+ expect(emoteFor('forge_failed')).toBe('wave');+ expect(emoteFor('brand_new_type')).toBe('wave');+ });+});diff --git a/walk-sdk/src/companion.js b/walk-sdk/src/companion.jsindex f70d7bcef..abe5caeed 100644--- a/walk-sdk/src/companion.js+++ b/walk-sdk/src/companion.js@@ -814,11 +814,16 @@ export function createWalkCompanion(opts = {}) {* @param {string} [opts.emote='wave'] gesture played on arrival; falls back* to a wave on rigs that don't carry it.* @param {Array<{label:string, href?:string, onClick?:Function}>} [opts.actions]+ * @param {string|object} [opts.avatar] deliver as somebody else: a roster+ * id, or an entry from `makeGuestAvatarEntry(glbUrl, { name })`. The+ * swap is not persisted and the visitor's own avatar comes back once+ * the message is over, which is what lets a message from a contact be+ * delivered by that contact's own body.* @returns {Promise<boolean>} false when no avatar could be shown (route* excluded, no WebGL, inside an iframe) so the caller can fall back to* its own UI. True once the message is on screen.*/- async announce(message, { hold = 7000, tone = 'alert', emote = 'wave', actions } = {}) {+ async announce(message, { hold = 7000, tone = 'alert', emote = 'wave', actions, avatar = null } = {}) {if (!message) return false;const summoned = !instance?.mounted;// Transient only when the visitor has not turned the companion on: an@@ -831,17 +836,43 @@ export function createWalkCompanion(opts = {}) {if (!instance.mounted) return false;}const inst = instance;++ // Guest delivery: whoever the message is from arrives in their own+ // body, and the visitor's companion is restored afterwards. A swap+ // that fails leaves the current avatar in place and the line is+ // still delivered, so a missing GLB never costs the message.+ let restore = null;+ if (avatar) {+ const guest = typeof avatar === 'string' ? resolveAvatarEntry(avatar, config) : avatar;+ const currentId = inst._currentEntry?.id || lsGet(config.keys.avatar) || config.defaultAvatarId;+ if (guest && guest.id !== currentId) {+ restore = inst._currentEntry || resolveAvatarEntry(currentId, config);+ await inst.setAvatar(guest, { persist: false, chatter: false });+ }+ }+try {if (!inst.controller?.playEmote?.(emote)) inst.controller?.playWave?.();} catch {/* rig without emotes: the bubble still carries the message */}inst.say(message, { hold, tone, actions });- if (!transient) return true;- await new Promise((r) => setTimeout(r, hold + ANNOUNCE_RETREAT_MS));- // The visitor may have turned the companion on (or swapped instances)- // while it was delivering; never yank it away in that case.- if (!isEnabled() && instance === inst && inst.mounted) inst.unmount();++ const settle = async () => {+ await new Promise((r) => setTimeout(r, hold + ANNOUNCE_RETREAT_MS));+ if (instance !== inst || !inst.mounted) return;+ if (restore) await inst.setAvatar(restore, { persist: false, chatter: false });+ // The visitor may have turned the companion on (or swapped+ // instances) while it was delivering; never yank it away then.+ if (transient && !isEnabled() && instance === inst && inst.mounted) inst.unmount();+ };+ // A persistent companion returns as soon as the line is up; only a+ // summoned-for-this-message one waits for its own retreat.+ if (!transient) {+ if (restore) settle();+ return true;+ }+ await settle();return true;},diff --git a/walk-sdk/src/index.js b/walk-sdk/src/index.jsindex 643f6906e..603984d6c 100644--- a/walk-sdk/src/index.js+++ b/walk-sdk/src/index.js@@ -46,6 +46,7 @@ export {defaultAvatar,listCategories,makeApiAvatarEntry,+ makeGuestAvatarEntry,resolveAvatarUrl,} from './roster.js';diff --git a/walk-sdk/src/roster.js b/walk-sdk/src/roster.jsindex 4c3deca03..bd2700702 100644--- a/walk-sdk/src/roster.js+++ b/walk-sdk/src/roster.js@@ -260,6 +260,32 @@ export function makeApiAvatarEntry(id, { name, accent } = {}) {};}+/**+ * Build a roster-shaped entry for a GLB served from anywhere: a contact's+ * avatar, an avatar generated from a selfie, a customer's own character. The+ * URL is used verbatim (absolute URLs pass through resolveAvatarUrl untouched),+ * and the rig is driven by the shared retargeted library, which is what lets an+ * arbitrary humanoid GLB walk and gesture without shipping its own clips.+ *+ * @param {string} url absolute or root-relative GLB URL.+ * @param {{ id?:string, name?:string, accent?:string, rig?:'shared'|'embedded' }} [opts]+ */+export function makeGuestAvatarEntry(url, { id, name, accent, rig = 'shared' } = {}) {+ return {+ id: id || `guest:${url}`,+ name: name || 'Guest',+ emoji: '👤',+ blurb: 'A guest avatar delivering a message.',+ category: 'Guests',+ asset: url,+ source: 'static',+ rig,+ clips: DEFAULT_SHARED_CLIPS,+ accent: accent || '#7aa2ff',+ tags: ['guest'],+ };+}+/*** Resolve the GLB URL for a roster entry.* - static entries: `assetBase` + the entry's asset path.