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(notifications): wire the avatar as a first-class delivery channel

nirholas20f50e8a60df
diff --git a/api/_lib/migrations/20260828160000_notification_events_avatar_channel.sql b/api/_lib/migrations/20260828160000_notification_events_avatar_channel.sql
new file mode 100644
index 000000000..0ae65762b
--- /dev/null
+++ b/api/_lib/migrations/20260828160000_notification_events_avatar_channel.sql
@@ -0,0 +1,15 @@
+begin;
+
+-- The avatar delivery channel: the corner companion walks on screen and says a
+-- notification out loud (src/notification-herald.js, channel "avatar" in
+-- api/_lib/notify-prefs.js). Its click-throughs belong in the same
+-- sent/opened/returned funnel every other channel is measured by, so the check
+-- constraint has to accept the new name.
+alter table notification_events
+ drop constraint if exists notification_events_channel_check;
+
+alter table notification_events
+ add constraint notification_events_channel_check
+ check (channel in ('in_app', 'push', 'email', 'telegram', 'avatar'));
+
+commit;
diff --git a/api/_lib/notify-prefs.js b/api/_lib/notify-prefs.js
index 07ea0e309..47ada763f 100644
--- a/api/_lib/notify-prefs.js
+++ b/api/_lib/notify-prefs.js
@@ -47,6 +47,11 @@ export const CATEGORIES = [
label: 'Creations',
description: 'A 3D generation you started finished (or failed) while you were away.',
},
+ {
+ key: 'companion',
+ label: 'Companion deliveries',
+ description: 'Your 3D companion has something from your own inbox, calendar, or phone worth hearing.',
+ },
{
key: 'account',
label: 'Account & security',
@@ -109,6 +114,8 @@ const TYPE_CATEGORY = {
pump_alert: 'alerts',
+ companion_delivery: 'companion',
+
forge_complete: 'creations',
forge_failed: 'creations',
@@ -269,6 +276,7 @@ const PUSH_COPY = {
irl_interaction: (p) => ['Met in person 📍', p.message ? `“${p.message}”` : 'Someone interacted with your agent in person'],
irl_reply: (p) => ['Agent replied 💬', p.message ? `“${p.message}”` : 'An agent replied to your message'],
pump_alert: (p) => ['Market alert 📈', p.summary || 'A token alert you configured just fired'],
+ companion_delivery: (p) => [p.sender ? `${p.sender} 👋` : 'Your companion 👋', p.line || p.title || 'Something worth your attention just came in'],
forge_complete: (p) => ['Your 3D model is ready ✨', p.prompt ? `"${String(p.prompt).slice(0, 80)}" finished generating` : 'Your generation finished. Tap to view it'],
forge_failed: (p) => ['Generation failed ⚠️', p.prompt ? `"${String(p.prompt).slice(0, 80)}" could not be generated. Tap to retry` : 'A generation could not be completed. Tap to retry'],
withdrawal_completed: () => ['Withdrawal complete ✅', 'Your withdrawal has been sent'],
diff --git a/api/notifications/track.js b/api/notifications/track.js
index 160a6e63e..6ff92248e 100644
--- a/api/notifications/track.js
+++ b/api/notifications/track.js
@@ -1,9 +1,11 @@
// POST /api/notifications/track: record a re-engagement funnel event.
//
-// { notification_id, channel: 'push'|'in_app', event: 'opened'|'returned' }
+// { notification_id, channel: 'push'|'in_app'|'avatar', event: 'opened'|'returned' }
//
// Closes the sent→opened→returned loop:
// • the service worker fires `opened` when a push notification is clicked,
+// • the corner companion fires `opened` when a visitor clicks through from a
+// notification it announced out loud (channel 'avatar'),
// • the app fires `returned` when it boots from a push-sourced open
// (?source=push), proving the notification actually pulled the user back.
//
@@ -22,7 +24,7 @@ import { parse } from '../_lib/validate.js';
const body = z.object({
notification_id: z.string().uuid().optional(),
- channel: z.enum(['push', 'in_app']),
+ channel: z.enum(['push', 'in_app', 'avatar']),
event: z.enum(['opened', 'returned']),
});
diff --git a/src/dashboard-next/pages/settings.js b/src/dashboard-next/pages/settings.js
index 7851fc415..df98326d1 100644
--- a/src/dashboard-next/pages/settings.js
+++ b/src/dashboard-next/pages/settings.js
@@ -313,7 +313,12 @@ function renderNotifications(resp, onRetry) {
// api/_lib/notify.js checks this before sending push/email, so a toggle here
// takes effect on the very next event, not just in the UI.
-const CHANNEL_LABEL = { in_app: 'In-app', push: 'Push', email: 'Email', telegram: 'Telegram' };
+const CHANNEL_LABEL = { in_app: 'In-app', push: 'Push', email: 'Email', telegram: 'Telegram', avatar: 'Avatar' };
+// One line of help per channel, shown under the table, because "Avatar" is not
+// self-explanatory the way Push and Email are.
+const CHANNEL_HINT = {
+ avatar: 'Avatar: your companion walks on screen and says it out loud while you are on the site. Turn it off for this browser only from the "Turn off" control in its bubble.',
+};
function renderNotificationPrefs(resp, onRetry) {
const panel = document.createElement('div');
@@ -338,14 +343,14 @@ function renderNotificationPrefs(resp, onRetry) {
const body = resp.data || {};
const categories = Array.isArray(body.categories) ? body.categories : [];
- const channels = Array.isArray(body.channels) ? body.channels : ['in_app', 'push', 'email', 'telegram'];
+ const channels = Array.isArray(body.channels) ? body.channels : ['in_app', 'push', 'email', 'telegram', 'avatar'];
const matrix = body.prefs?.categories || {};
const subscribedDevices = body.push?.subscribed_devices ?? 0;
panel.innerHTML = `
<div style="margin-bottom:14px">
<div class="dn-panel-title">Notification preferences</div>
- <div class="dn-panel-sub" style="margin:2px 0 0">Mute noisy categories per channel. Account and security events always stay in your bell so nothing important is silently lost, but you can still quiet their push, email and Telegram.</div>
+ <div class="dn-panel-sub" style="margin:2px 0 0">Mute noisy categories per channel. Account and security events always stay in your bell so nothing important is silently lost, but you can still quiet their push, email, Telegram and avatar announcements.</div>
</div>
${!categories.length ? emptyStateHTML({
icon: '',
@@ -396,6 +401,11 @@ function renderNotificationPrefs(resp, onRetry) {
</tbody>
</table>
</div>
+ ${channels.some((ch) => CHANNEL_HINT[ch]) ? `
+ <div style="margin-top:12px;font-size:12px;color:var(--nxt-ink-fade);display:grid;gap:4px">
+ ${channels.filter((ch) => CHANNEL_HINT[ch]).map((ch) => `<div>${esc(CHANNEL_HINT[ch])}</div>`).join('')}
+ </div>
+ ` : ''}
<div style="margin-top:12px;font-size:12px;color:var(--nxt-ink-fade)">
${subscribedDevices > 0
? `Push is enabled on ${subscribedDevices} device${subscribedDevices === 1 ? '' : 's'}.`
diff --git a/src/notifications.js b/src/notifications.js
index 98feafff0..be9394246 100644
--- a/src/notifications.js
+++ b/src/notifications.js
@@ -282,6 +282,7 @@ class NotificationInbox {
this._unread = data.unread_count || 0;
this._updateBadge();
if (this._open) this._renderBody();
+ this._offerToHerald();
if (share) {
writeNotifCache(this._notifications, this._unread);
try {
@@ -293,6 +294,19 @@ class NotificationInbox {
}
}
+ // Hand the current inbox to the notification herald, which decides whether
+ // anything in it is worth the corner avatar walking on and saying out loud
+ // (src/notification-herald.js owns every rule: per-category preference,
+ // freshness, per-id dedupe, batch cap). Loaded on demand and only when there
+ // is something unread at all, so a quiet inbox costs nothing.
+ _offerToHerald() {
+ if (!this._notifications.some((n) => !n.read_at)) return;
+ const list = this._notifications;
+ import('./notification-herald.js')
+ .then((herald) => herald.consider(list))
+ .catch(() => { /* chunk unavailable: the bell badge still carries it */ });
+ }
+
start() {
if (!isAuthed()) return;
// Seed the badge instantly from whatever a sibling tab fetched last, so a
diff --git a/src/walk-companion-narrator.js b/src/walk-companion-narrator.js
index 2299d093c..fd0d96f4c 100644
--- a/src/walk-companion-narrator.js
+++ b/src/walk-companion-narrator.js
@@ -78,6 +78,16 @@ function readMode() {
}
return 'caption'; // captions on, audio off, until the visitor opts in
}
+/**
+ * The visitor's saved narration mode, for other surfaces that want to respect
+ * the same opt-in before they play audio through the companion (the
+ * notification herald does, see src/notification-herald.js).
+ * @returns {'off'|'caption'|'voice'}
+ */
+export function narrationMode() {
+ return readMode();
+}
+
function writeMode(mode) {
try {
localStorage.setItem(PREF_KEY, mode);
@@ -221,12 +231,14 @@ function createCaption(getHost) {
}
// ── Spoken audio (real TTS, opt-in, autoplay-policy aware) ──────────────────────
+// Exported so other companion surfaces (the notification herald) speak through
+// the same endpoint, voice and autoplay discipline instead of minting their own.
// Fetches a full clip from POST /api/tts/speak and plays it. Never autoplays
// before a user gesture: the install flips a "gesture seen" flag on the first
// pointer/key interaction, and the very act of choosing "voice" is itself a
// gesture. If playback is rejected by autoplay policy we degrade silently to the
// caption (which is already on screen) — no fake audio, no error noise.
-function createSpeaker() {
+export function createSpeaker() {
let audio = null;
let controller = null;
let objectUrl = null;
@@ -505,6 +517,14 @@ export function installNarrator({ getInstance, getHostEl, storageKey } = {}) {
setMode,
cycleMode,
rescan: scheduleRescan,
+ // Stop whatever is being read right now without changing the mode. The
+ // notification herald calls this before an announcement so the avatar is
+ // never reading a page section over its own message.
+ silence() {
+ speaker.cancel();
+ caption.hide();
+ currentSection = null;
+ },
};
function uninstall() {
diff --git a/src/walk-companion.js b/src/walk-companion.js
index a38ce6ec5..34acfdc71 100644
--- a/src/walk-companion.js
+++ b/src/walk-companion.js
@@ -283,7 +283,10 @@ installClickToWalk({
// survives avatar swaps and playground round-trips. Default is caption-only —
// audio never plays without an explicit opt-in and a real user gesture.
const NARRATE_KEY = `${(walk.config?.keys?.enabled || 'three:companion:enabled').split(':')[0]}:companion:narrate`;
-installNarrator({
+// The handle is exposed because narration is no longer the only thing that
+// speaks through this avatar: src/notification-herald.js silences an in-flight
+// section read before the avatar delivers a notification out loud.
+window.__walkNarrator = installNarrator({
getInstance: () => walk.instance,
getHostEl: companionHost,
storageKey: NARRATE_KEY,
diff --git a/walk-sdk/src/companion.js b/walk-sdk/src/companion.js
index b7d2896d2..f70d7bcef 100644
--- a/walk-sdk/src/companion.js
+++ b/walk-sdk/src/companion.js
@@ -229,7 +229,7 @@ class WalkCompanion {
<button type="button" class="walk-companion-close" aria-label="Dismiss walk companion" title="Dismiss">×</button>
${pickerBtn}
<div class="walk-companion__skel" aria-hidden="true"></div>
- <div class="walk-companion-bubble" hidden></div>
+ <div class="walk-companion-bubble" role="status" aria-live="polite" aria-atomic="true" hidden></div>
<canvas class="walk-companion-canvas" width="${CANVAS_W}" height="${CANVAS_H}"></canvas>
`;
document.body.appendChild(host);
@@ -350,14 +350,22 @@ class WalkCompanion {
}
// ── Live avatar swap (from the picker) ────────────────────────────────────
- async setAvatar(idOrEntry) {
+ /**
+ * @param {string|object} idOrEntry roster id, or a roster-shaped entry.
+ * @param {object} [opts]
+ * @param {boolean} [opts.persist=true] remember the choice for next page.
+ * A guest delivery (announce({ avatar })) swaps without persisting, so the
+ * visitor's own companion is still theirs after the message is over.
+ * @param {boolean} [opts.chatter=true] say the "Switching…" / "Say hi" lines.
+ */
+ async setAvatar(idOrEntry, { persist = true, chatter = true } = {}) {
const entry =
typeof idOrEntry === 'string' ? resolveAvatarEntry(idOrEntry, this.config) : idOrEntry;
if (!entry) return;
- lsSet(this.config.keys.avatar, entry.id);
- this._picker?.setCurrent(entry.id);
+ if (persist) lsSet(this.config.keys.avatar, entry.id);
+ if (persist) this._picker?.setCurrent(entry.id);
if (!this.mounted || !this.rig) return; // will apply on next mount
- this._say('Switching…');
+ if (chatter) this._say('Switching…');
try {
const fallback = resolveAvatarEntry(this.config.defaultAvatarId, this.config);
const {
@@ -387,10 +395,10 @@ class WalkCompanion {
this.controller = controller;
this._currentEntry = active;
this._frame(model, this.rig, this.camera);
- this._say(`Say hi to ${active.name}!`);
+ if (chatter) this._say(`Say hi to ${active.name}!`);
} catch (err) {
log.warn('avatar swap failed:', err?.message || err);
- this._say('Couldn’t load that one — try another.');
+ if (chatter) this._say('Couldn’t load that one — try another.');
}
}
@@ -533,7 +541,7 @@ class WalkCompanion {
* @param {number} [opts.hold=5200] ms before the bubble retracts; 0 keeps it
* up until the next say()/hideBubble().
* @param {'neutral'|'alert'} [opts.tone='neutral'] 'alert' tints the bubble.
- * @param {Array<{label:string, href?:string, onClick?:Function}>} [opts.actions]
+ * @param {Array<{label:string, href?:string, title?:string, onClick?:Function}>} [opts.actions]
* @returns {boolean} false when there is no bubble to render into.
*/
say(text, { hold = BUBBLE_HOLD_MS, tone = 'neutral', actions = null } = {}) {
@@ -557,6 +565,12 @@ class WalkCompanion {
const el = document.createElement(action.href ? 'a' : 'button');
el.className = 'walk-companion-bubble-action';
el.textContent = action.label;
+ // A two-word pill is all that fits beside an avatar, so the full
+ // intent lives on the accessible name and the tooltip.
+ if (action.title) {
+ el.title = action.title;
+ el.setAttribute('aria-label', action.title);
+ }
if (action.href) el.href = action.href;
else el.type = 'button';
if (typeof action.onClick === 'function') {