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
// Notification herald: your agent delivers the important ones in person.
// ============================================================================
// The bell inbox (src/notifications.js) is a passive surface. It waits for you
// to notice a badge and open a panel. Some notifications deserve more than
// that: money landed, the generation you were waiting on finished, something
// happened to your account. For those, the corner companion (the avatar that
// already walks your pages, src/walk-companion.js) turns to you, waves, and
// says it out loud, with a link straight to the thing that happened.
//
// The rules, in order:
// 1. The visitor owns it. Announcements are a real delivery channel in the
// preference center (/dashboard/settings), gated per category exactly like
// push and email are (api/_lib/notify-prefs.js, channel "avatar"). The
// defaults announce sales, creations, and account events only.
// 2. Only fresh (under 15 minutes old), unread notifications are announced,
// and each id exactly once per browser. The ids already delivered live in
// localStorage, so a page navigation, a re-poll, or a second tab never
// repeats a line.
// 3. At most two lines per batch. Anything past that collapses into one
// "N more waiting" line that links to the inbox, so a backlog never turns
// into a monologue.
// 4. Nothing is announced into a background tab. The whole point is to tell
// someone who is actually here.
// 5. "Turn off" in the bubble silences this browser instantly, without
// touching the account-wide preference (which the settings page owns).
//
// The body comes from @three-ws/walk (walk-sdk/): `announce()` mounts the
// companion when it is off, delivers, and walks it back off. When it cannot
// render at all (no WebGL, an iframe, a route that already owns the corner) the
// message degrades to the normal toast, so a notification is never lost to a
// missing GPU.
//
// Fed by src/notifications.js on every poll. Everything heavy here (the
// companion module, the inbox helpers, TTS, toasts) is imported on demand, so
// a visitor with nothing to announce pays for a few hundred bytes and no more.
const ANNOUNCED_KEY = '3dagent:herald-announced';
const DEVICE_OFF_KEY = '3dagent:herald-off';
const PREFS_CACHE_KEY = '3dagent:herald-prefs';
// A notification older than this is history, not news: it belongs in the inbox,
// not in the avatar's mouth.
const FRESH_WINDOW_MS = 15 * 60_000;
// Preferences change rarely and cost a request; re-read them a few times an
// hour rather than on every poll.
const PREFS_TTL_MS = 10 * 60_000;
const MAX_PER_BATCH = 2;
// Remembered ids are only used to answer "did we already say this", so a small
// rolling window is enough. Old ids age out of the freshness window anyway.
const ANNOUNCED_CAP = 200;
// Bubble dwell: long enough to read a full line, scaled by length, capped so a
// verbose payload can never park the avatar on screen.
const BASE_HOLD_MS = 5200;
const HOLD_MS_PER_CHAR = 55;
const MAX_HOLD_MS = 12_000;
// Breathing room between two announcements so they read as two visits rather
// than one bubble mutating.
const GAP_MS = 900;
// ── Pure rules (unit-tested in tests/notification-herald.test.js) ────────────
/** How long a line stays up, scaled to its length. */
export function holdMsFor(text) {
const chars = String(text || '').length;
return Math.min(MAX_HOLD_MS, BASE_HOLD_MS + chars * HOLD_MS_PER_CHAR);
}
/** Is this notification recent enough to be worth interrupting for? */
export function isFresh(createdAt, now = Date.now()) {
const t = Date.parse(createdAt);
return Number.isFinite(t) && now - t < FRESH_WINDOW_MS && t - now < FRESH_WINDOW_MS;
}
/**
* Category for a notification type, using the map the server sends with the
* preferences (api/_lib/notify-prefs.js owns it). Unmapped types fall back to
* 'account' exactly as they do server-side, so a brand new type is never
* silently unannounceable.
*/
export function categoryFor(type, typeCategories) {
return (typeCategories && typeCategories[type]) || 'account';
}
/** Has the visitor left the avatar channel on for this category? */
export function announcesCategory(prefs, category) {
return prefs?.categories?.[category]?.avatar === true;
}
/**
* Choose what the avatar says out of everything the inbox is holding.
* @param {Array} notifications rows as returned by GET /api/notifications
* @param {{prefs:object, typeCategories:object, announced:Set<string>, now?:number, max?:number}} ctx
* @returns {{deliver: Array, overflow: number}} `deliver` newest first,
* `overflow` how many eligible ones did not fit in this batch.
*/
export function pickAnnouncements(
notifications,
{ prefs, typeCategories, announced, now = Date.now(), max = MAX_PER_BATCH },
) {
const eligible = (Array.isArray(notifications) ? notifications : []).filter(
(n) =>
n &&
n.id &&
!n.read_at &&
!announced.has(n.id) &&
isFresh(n.created_at, now) &&
announcesCategory(prefs, categoryFor(n.type, typeCategories)),
);
eligible.sort((a, b) => Date.parse(b.created_at) - Date.parse(a.created_at));
return {
deliver: eligible.slice(0, max),
overflow: Math.max(0, eligible.length - max),
};
}
// Types worth dancing about. Everything else arrives with a wave.
const CELEBRATED = new Set([
'skill_purchased',
'asset_purchased',
'sale',
'payment-earned',
'referral_earned',
'royalty_paid',
'pump_launch_filled',
'quest_complete',
'forge_complete',
]);
/**
* The gesture the avatar arrives with. Money and finished work get the
* celebration; everything else gets the wave every rig can perform.
*/
export function emoteFor(type) {
return CELEBRATED.has(type) ? 'dance' : 'wave';
}
// ── Local state (per browser) ────────────────────────────────────────────────
/** Ids claimed by this page, so a claim survives storage being unavailable. */
const _session = new Set();
/** Device-level mute, read once per page and flipped by the bubble's control. */
let _muted = null;
function readAnnounced() {
try {
const raw = localStorage.getItem(ANNOUNCED_KEY);
const list = raw ? JSON.parse(raw) : [];
return new Set(Array.isArray(list) ? list : []);
} catch {
// Storage disabled: nothing is remembered, so the freshness window and
// the in-memory set below are what stop a repeat within this page.
return new Set();
}
}
function markAnnounced(ids) {
for (const id of ids) _session.add(id);
try {
const raw = localStorage.getItem(ANNOUNCED_KEY);
const list = raw ? JSON.parse(raw) : [];
const next = (Array.isArray(list) ? list : []).concat(ids).slice(-ANNOUNCED_CAP);
localStorage.setItem(ANNOUNCED_KEY, JSON.stringify(next));
} catch {
/* storage disabled: the in-memory set still covers this page */
}
}
export function deviceMuted() {
try {
return localStorage.getItem(DEVICE_OFF_KEY) === '1';
} catch {
return false;
}
}
function muteDevice() {
try {
localStorage.setItem(DEVICE_OFF_KEY, '1');
} catch {
/* storage disabled: the mute lasts for this page only */
}
_muted = true;
}
// ── Preferences ──────────────────────────────────────────────────────────────
let _prefsPromise = null;
function readCachedPrefs() {
try {
const raw = sessionStorage.getItem(PREFS_CACHE_KEY);
if (!raw) return null;
const cached = JSON.parse(raw);
if (!cached || Date.now() - cached.ts > PREFS_TTL_MS) return null;
return { prefs: cached.prefs, typeCategories: cached.typeCategories };
} catch {
return null;
}
}
/**
* The visitor's channel matrix plus the server's type to category map. Returns
* null when it cannot be read, and a null result announces nothing: silence is
* the safe failure for a channel that interrupts.
*/
async function loadPrefs() {
const cached = readCachedPrefs();
if (cached) return cached;
if (_prefsPromise) return _prefsPromise;
_prefsPromise = (async () => {
try {
const res = await fetch('/api/notifications/preferences', { credentials: 'include' });
if (!res.ok) return null;
const body = await res.json();
const bundle = {
prefs: body?.prefs || null,
typeCategories: body?.type_categories || {},
};
if (!bundle.prefs) return null;
try {
sessionStorage.setItem(
PREFS_CACHE_KEY,
JSON.stringify({ ts: Date.now(), ...bundle }),
);
} catch {
/* storage disabled: re-fetch next batch */
}
return bundle;
} catch {
return null;
} finally {
_prefsPromise = null;
}
})();
return _prefsPromise;
}
// ── The companion body ───────────────────────────────────────────────────────
// public/nav.js injects this module only when the companion is switched on, so
// on a page where it is off we inject it ourselves and let `announce()` decide
// whether to summon and retreat. Same stable URL in dev and production
// (vite.config.js maps both).
const COMPANION_SRC = '/walk-companion.js';
const COMPANION_WAIT_MS = 8000;
const COMPANION_POLL_MS = 120;
function ensureCompanion() {
if (window.__walkCompanion) return Promise.resolve(window.__walkCompanion);
if (!document.querySelector(`script[src="${COMPANION_SRC}"]`)) {
const s = document.createElement('script');
s.type = 'module';
s.src = COMPANION_SRC;
document.head.appendChild(s);
}
return new Promise((resolve) => {
const deadline = Date.now() + COMPANION_WAIT_MS;
const poll = () => {
if (window.__walkCompanion) return resolve(window.__walkCompanion);
if (Date.now() > deadline) return resolve(null);
setTimeout(poll, COMPANION_POLL_MS);
};
poll();
});
}
// ── Voice ────────────────────────────────────────────────────────────────────
let _speaker = null;
/**
* Hand the avatar over to the message: page-section narration stops and stays
* quiet for the length of the delivery, so its caption never covers the bubble
* and its voice never talks over the line.
*/
function quietTheNarrator(ms) {
try {
window.__walkNarrator?.api?.suspend?.(ms);
} catch {
/* narrator not installed on this page */
}
}
/**
* Speak the line aloud, but only when the visitor already chose voice for the
* companion's narration ("walk:companion:narrate" = voice, set from the
* companion's own toggle). An announcement never introduces audio on its own.
*/
async function speakAloud(text) {
try {
const mod = await import('./walk-companion-narrator.js');
if (mod.narrationMode() !== 'voice') return;
if (!_speaker) _speaker = mod.createSpeaker();
_speaker.speak(text);
} catch {
/* no TTS available: the bubble already carries the message */
}
}
// ── Delivery ─────────────────────────────────────────────────────────────────
const queue = [];
let running = false;
/**
* Offer the inbox's current contents to the avatar. Safe to call on every poll:
* it is idempotent per notification id, cheap when nothing qualifies, and
* silent in a background tab.
* @param {Array} notifications rows from GET /api/notifications
*/
export async function consider(notifications) {
if (!Array.isArray(notifications) || notifications.length === 0) return;
if (_muted === null) _muted = deviceMuted();
if (_muted) return;
if (typeof document === 'undefined' || document.visibilityState !== 'visible') return;
const bundle = await loadPrefs();
if (!bundle) return;
const announced = readAnnounced();
for (const id of _session) announced.add(id);
const { deliver, overflow } = pickAnnouncements(notifications, {
prefs: bundle.prefs,
typeCategories: bundle.typeCategories,
announced,
});
if (deliver.length === 0) return;
// Claim before delivering: a sibling tab polling the same second must not
// say the same line, and a failed delivery must not queue up a retry loop.
markAnnounced(deliver.map((n) => n.id));
queue.push(...deliver.map((n) => ({ notification: n })));
if (overflow > 0) queue.push({ overflow });
if (!running) run();
}
async function run() {
running = true;
try {
while (queue.length) {
const item = queue.shift();
// The visitor may have muted mid-queue, or walked away from the tab.
if (_muted || document.visibilityState !== 'visible') break;
await deliver(item);
if (queue.length) await wait(GAP_MS);
}
} finally {
running = false;
}
}
/**
* The body that should deliver this line.
*
* A companion delivery carries whoever it is from: the contact's own avatar
* when the visitor gave that person one on /companion, the account's default
* companion body otherwise. `announce({ avatar })` swaps without persisting and
* restores the visitor's own avatar afterwards, so a message from Sarah really
* does arrive as Sarah and leaves your own companion where it was.
*/
async function guestAvatarFor(n) {
const url = n?.payload?.avatar_glb_url;
if (!url || typeof url !== 'string') return null;
if (!/^https?:\/\//i.test(url) && !url.startsWith('/')) return null;
try {
const { makeGuestAvatarEntry } = await import('../walk-sdk/src/roster.js');
return makeGuestAvatarEntry(url, { id: `companion:${url}`, name: n.payload.sender || 'Your contact' });
} catch {
// The roster module failed to load: deliver in the visitor's own body
// rather than losing the message.
return null;
}
}
async function deliver(item) {
const [{ TYPE_ICON, notifLabel, notifLink, trackInApp }, walk] = await Promise.all([
import('./notifications.js'),
ensureCompanion(),
]);
const n = item.notification;
const line = n
? notifLabel(n)
: `${item.overflow} more notification${item.overflow === 1 ? '' : 's'} waiting for you`;
const href = n ? notifLink(n) : '/notifications';
const icon = n ? TYPE_ICON[n.type] || '📣' : '🔔';
const hold = holdMsFor(line);
const actions = [];
if (href) {
actions.push({
label: 'Open',
href,
title: `Open: ${line}`,
onClick: () => {
if (n?.id) trackAvatarOpen(n.id, trackInApp);
},
});
}
actions.push({
label: 'Turn off',
title: 'Stop the avatar announcing notifications in this browser',
onClick: () => turnOff(),
});
if (!walk?.announce) return fallbackToast(line);
// Reserve the avatar for the length of the delivery plus its retraction.
quietTheNarrator(hold + 1200);
speakAloud(line);
const shown = await walk.announce(`${icon} ${line}`, {
hold,
tone: 'alert',
emote: n ? emoteFor(n.type) : 'wave',
actions,
avatar: n ? await guestAvatarFor(n) : null,
});
if (!shown) fallbackToast(line);
if (shown && n?.type === 'companion_delivery' && n.payload?.event_id) markCompanionDelivered(n.payload.event_id);
}
/**
* Tell the server the companion actually said this one out loud, so the same
* message is not waiting to be spoken again on the next device the visitor
* picks up. Fire and forget: the line has already been delivered either way.
*/
function markCompanionDelivered(eventId) {
import('./api.js')
.then(({ apiFetch }) => apiFetch(`/api/companion/events/${encodeURIComponent(eventId)}`, {
method: 'PATCH',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ delivered: true }),
}))
.catch(() => {
/* offline: the cron's own delivered_at stamp still covers it */
});
}
/**
* Record the click-through on the avatar channel so the delivery is measured
* like push and the inbox are (api/notifications/track).
*/
function trackAvatarOpen(id, trackInApp) {
fetch('/api/notifications/track', {
method: 'POST',
credentials: 'include',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ notification_id: id, channel: 'avatar', event: 'opened' }),
})
.then((res) => {
// The avatar channel is new; a browser talking to an older deploy
// gets a 400 back, and the open still deserves to be counted.
if (!res.ok) trackInApp(id, 'opened');
})
.catch(() => {
/* offline: the click still navigates, only the beacon is lost */
});
}
async function turnOff() {
muteDevice();
queue.length = 0;
try {
window.__walkCompanion?.instance?.hideBubble?.();
} catch {
/* companion already gone */
}
const { toast } = await import('./shared/toast.js');
toast('Your agent will stop announcing notifications in this browser. Per-category control lives in Settings.', {
variant: 'info',
duration: 6000,
});
}
async function fallbackToast(line) {
const { toast } = await import('./shared/toast.js');
toast(line, { variant: 'info', duration: 6000 });
}
function wait(ms) {
return new Promise((r) => setTimeout(r, ms));
}