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
// three.ws "Getting started" guide — the first-5-minutes guided path.
//
// Self-mounting, like the activity feed: nav.js loads this on every page that
// carries the shared nav, and the bespoke pages that skip nav.js (home, create,
// app, dashboard…) include it directly. It does two things:
//
// 1. First run — for a brand-new / signed-out visitor landing on the homepage,
// a one-time welcome modal states the value in a line and routes them to
// "create your first avatar". Always skippable; shown at most once.
// 2. Always — a low-key launcher pill (bottom-right) that opens a resumable
// checklist: the free core path (create → give it a brain → embed) plus
// clearly-optional add-ons (own it on-chain, monetize). Progress persists
// across pages in localStorage and fills in as the user reaches each stage.
//
// The free core never asks for a wallet. Optional steps are tagged "Optional".
//
// Opt out per page with <html data-getting-started="off"> or
// window.__twsGuideOff = true. Other code can mark a step complete precisely via
// window.__twsGuide.complete('create') or a `three-ws:guide` CustomEvent
// ({ detail: { step: 'create' } }).
(function () {
'use strict';
if (window.__twsGuide) return; // idempotent — never double-mount
if (typeof document === 'undefined') return;
if (window.self !== window.top) return; // never inside an embedded iframe
if (document.documentElement.getAttribute('data-getting-started') === 'off') return;
if (window.__twsGuideOff) return;
// ── Storage keys ───────────────────────────────────────────────────────────
var PROGRESS_KEY = 'tws-guide:progress'; // { stepId: completedAtMs }
var WELCOME_KEY = 'tws-guide:welcome-seen'; // '1' once the modal has been shown
var OPEN_KEY = 'tws-guide:open'; // panel collapsed/expanded across pages
var HIDDEN_KEY = 'tws-guide:hidden'; // '1' if the user opted out entirely
var AUTH_HINT_KEY = '3dagent:auth-hint'; // written by the account layer
// ── Step definitions ────────────────────────────────────────────────────────
// `core` steps form the free path the welcome flow promises. `optional` steps
// are bonus and visibly tagged. `done(path, params)` is a passive milestone
// test run on every page; precise completion can also arrive via the public
// complete() API / `three-ws:guide` event.
var STEPS = [
{
id: 'create', core: true, glyph: '🧍',
title: 'Create your first avatar',
desc: 'Selfie, text prompt, or upload. Your 3D agent in a couple of minutes.',
href: '/create',
done: function (p, q) {
return (p.indexOf('/app') === 0 && q.has('agent')) ||
p.indexOf('/avatars/') === 0 ||
p.indexOf('/create/next') === 0 ||
(p.indexOf('/dashboard') === 0 && q.get('welcome') === '1');
},
},
{
id: 'brain', core: true, glyph: '🧠',
title: 'Give it a brain',
desc: 'Add a name, personality, and voice so it can talk back.',
href: '/brain',
done: function (p) { return p === '/brain' || p.indexOf('/brain/') === 0; },
},
{
id: 'embed', core: true, glyph: '🔗',
title: 'Embed it anywhere',
desc: 'Drop one line of HTML onto any site. It loads and animates itself.',
href: '/studio',
done: function (p) {
return p.indexOf('/studio') === 0 ||
p.indexOf('/dashboard/widgets') === 0 || p.indexOf('/dashboard/api') === 0;
},
},
{
id: 'onchain', core: false, glyph: '⛓',
title: 'Own it on-chain',
desc: 'Register your agent on-chain so its identity is verifiable.',
href: '/deploy',
done: function (p) {
return p.indexOf('/deploy') === 0 || p.indexOf('/onchain') === 0 || p.indexOf('/showcase') === 0;
},
},
{
id: 'monetize', core: false, glyph: '◎',
title: 'Monetize it',
desc: 'Charge for skills and collect creator fees from the agent economy.',
href: '/dashboard/monetize',
done: function (p) { return p.indexOf('/dashboard/monetize') === 0; },
},
];
var CORE = STEPS.filter(function (s) { return s.core; });
// Immersive / embed surfaces where a floating launcher would intrude. The
// guide stays silent here but still records any milestone reached.
var EXCLUDED = [
'/play', '/walk', '/walk-embed', '/club', '/city', '/xr', '/ar',
'/pose', '/mocap-studio', '/avatar-studio', '/avatar-embed',
'/agent-embed', '/a-embed',
];
// ── Storage helpers (non-fatal in private mode) ──────────────────────────────
function lsGet(k) { try { return localStorage.getItem(k); } catch (_) { return null; } }
function lsSet(k, v) { try { localStorage.setItem(k, v); } catch (_) {} }
function loadProgress() {
try { return JSON.parse(lsGet(PROGRESS_KEY) || '{}') || {}; } catch (_) { return {}; }
}
var progress = loadProgress();
function isDone(id) { return !!progress[id]; }
function coreDoneCount() {
return CORE.reduce(function (n, s) { return n + (isDone(s.id) ? 1 : 0); }, 0);
}
function allCoreDone() { return coreDoneCount() >= CORE.length; }
function isAuthed() {
try {
var raw = lsGet(AUTH_HINT_KEY);
return !!(raw && JSON.parse(raw).authed);
} catch (_) { return false; }
}
function currentPath() { return location.pathname.replace(/\/+$/, '') || '/'; }
function isExcludedRoute() {
var p = currentPath();
return EXCLUDED.some(function (x) { return p === x || p.indexOf(x + '/') === 0; });
}
// ── DOM utilities ────────────────────────────────────────────────────────────
// i18n key for a shell string — must match nav-data.js navKey and the offline
// harvester (scripts/i18n-nav-harvest.mjs) so the runtime (src/i18n.js) swaps
// these labels per locale.
function navKey(text) {
var s = String(text == null ? '' : text);
var h = 0x811c9dc5;
for (var i = 0; i < s.length; i++) {
h ^= s.charCodeAt(i);
h = Math.imul(h, 0x01000193);
}
return 'nav.' + (h >>> 0).toString(36);
}
function el(tag, cls, text) {
var n = document.createElement(tag);
if (cls) n.className = cls;
if (text != null) n.textContent = text;
return n;
}
// el() variant that tags the element for translation (static labels only —
// never dynamic text like counts or the ✓/glyph marks).
function elT(tag, cls, text) {
var n = el(tag, cls, text);
if (text != null && String(text).trim()) n.setAttribute('data-i18n', navKey(text));
return n;
}
function ensureCss() {
if (document.querySelector('link[href="/getting-started.css"]')) return;
var link = document.createElement('link');
link.rel = 'stylesheet';
link.href = '/getting-started.css';
document.head.appendChild(link);
}
// ── State ─────────────────────────────────────────────────────────────────────
var root, pill, pillRing, pillCount, panel, list, barFill, panelSub;
var open = lsGet(OPEN_KEY) === '1';
var hidden = lsGet(HIDDEN_KEY) === '1';
// ── Completion ────────────────────────────────────────────────────────────────
function complete(id, opts) {
if (!STEPS.some(function (s) { return s.id === id; })) return;
if (progress[id]) return;
progress[id] = Date.now();
lsSet(PROGRESS_KEY, JSON.stringify(progress));
if (root) {
renderSteps();
updatePill();
// A freshly-reached milestone is worth a gentle nudge open, but never
// while the user is mid-task on an immersive page.
if (!open && !hidden && !isExcludedRoute() && !(opts && opts.silent)) flashPill();
}
}
function flashPill() {
if (!pill) return;
pill.animate(
[{ transform: 'scale(1)' }, { transform: 'scale(1.08)' }, { transform: 'scale(1)' }],
{ duration: 420, easing: 'cubic-bezier(0.16,1,0.3,1)' }
);
}
// Detect milestones for the page we loaded on.
function detectMilestones() {
var p = currentPath();
var q = new URLSearchParams(location.search);
STEPS.forEach(function (s) {
if (!isDone(s.id) && s.done(p, q)) complete(s.id, { silent: true });
});
}
// ── Pill ───────────────────────────────────────────────────────────────────────
function buildPill() {
pill = el('button', 'twg-pill');
pill.type = 'button';
pillRing = el('span', 'twg-pill-ring');
var glyph = el('span', 'twg-pill-glyph', '✦');
glyph.setAttribute('aria-hidden', 'true');
pillRing.appendChild(glyph);
pill.appendChild(pillRing);
pill.appendChild(elT('span', 'twg-pill-label', 'Getting started'));
pillCount = el('span', 'twg-pill-count');
pill.appendChild(pillCount);
pill.addEventListener('click', expand);
return pill;
}
function updatePill() {
if (!pill) return;
var done = coreDoneCount();
var total = CORE.length;
var pct = Math.round((done / total) * 100);
pillRing.style.setProperty('--twg-pct', String(pct));
var complete = done >= total;
pill.classList.toggle('is-complete', complete);
pillCount.textContent = complete ? '✓ Done' : done + '/' + total;
pill.setAttribute(
'aria-label',
complete
? 'Getting started ✓ Done: all core steps complete. Open checklist.'
: 'Getting started ' + done + '/' + total + ': ' + done + ' of ' + total + ' steps done. Open checklist.'
);
}
// ── Panel ────────────────────────────────────────────────────────────────────────
function buildPanel() {
panel = el('div', 'twg-panel');
panel.hidden = true;
panel.setAttribute('role', 'region');
panel.setAttribute('aria-label', 'Getting started checklist');
var head = el('div', 'twg-head');
var headText = el('div', 'twg-head-text');
headText.appendChild(elT('h2', 'twg-title', 'Getting started'));
panelSub = el('p', 'twg-sub');
headText.appendChild(panelSub);
head.appendChild(headText);
var close = el('button', 'twg-close', '×');
close.type = 'button';
close.setAttribute('aria-label', 'Collapse checklist');
close.addEventListener('click', collapse);
head.appendChild(close);
panel.appendChild(head);
var bar = el('div', 'twg-bar');
barFill = el('div', 'twg-bar-fill');
bar.appendChild(barFill);
panel.appendChild(bar);
list = el('ul', 'twg-list');
panel.appendChild(list);
var foot = el('div', 'twg-foot');
foot.appendChild(el('span', 'twg-foot-note', '~5 min · no wallet needed'));
var replay = el('button', 'twg-link', '🎬 Replay guided tour');
replay.type = 'button';
replay.title = 'Walk avatar → world → markets → profile again, with a 3D guide';
replay.addEventListener('click', replayOnboardingTour);
foot.appendChild(replay);
var dismiss = el('button', 'twg-link', 'Hide this');
dismiss.type = 'button';
dismiss.addEventListener('click', hideForever);
foot.appendChild(dismiss);
panel.appendChild(foot);
return panel;
}
function stepRow(s) {
var done = isDone(s.id);
var row = el('a', 'twg-step' + (done ? ' is-done' : ''));
row.href = s.href;
row.setAttribute('role', 'listitem');
var mark = el('span', 'twg-step-mark');
mark.setAttribute('aria-hidden', 'true');
mark.textContent = done ? '✓' : String(s.glyph);
row.appendChild(mark);
var body = el('div', 'twg-step-body');
var title = el('div', 'twg-step-title');
title.appendChild(elT('span', null, s.title));
if (!s.core) title.appendChild(elT('span', 'twg-tag', 'Optional'));
body.appendChild(title);
body.appendChild(elT('div', 'twg-step-desc', s.desc));
row.appendChild(body);
var arrow = el('span', 'twg-step-arrow');
arrow.setAttribute('aria-hidden', 'true');
arrow.textContent = '→';
row.appendChild(arrow);
// Navigating to the step's surface is itself the milestone; mark it so the
// checklist reflects intent immediately even before the page loads.
row.addEventListener('click', function () { complete(s.id, { silent: true }); });
return row;
}
function renderSteps() {
if (!list) return;
list.textContent = '';
var doneN = coreDoneCount();
var totalN = CORE.length;
panel.classList.toggle('is-complete', doneN >= totalN);
panelSub.textContent = doneN >= totalN
? "Core path done. You've got an embeddable avatar, and bonus steps below."
: doneN + ' of ' + totalN + ' core steps complete';
barFill.style.width = Math.round((doneN / totalN) * 100) + '%';
list.appendChild(sectionLabel('Free · the core path'));
CORE.forEach(function (s) { list.appendChild(stepRow(s)); });
var optional = STEPS.filter(function (s) { return !s.core; });
if (optional.length) {
list.appendChild(sectionLabel('Optional add-ons'));
optional.forEach(function (s) { list.appendChild(stepRow(s)); });
}
}
function sectionLabel(text) {
var li = elT('li', 'twg-section-label', text);
li.setAttribute('role', 'presentation');
return li;
}
// ── Open/close ────────────────────────────────────────────────────────────────
function expand() {
open = true;
lsSet(OPEN_KEY, '1');
renderSteps();
panel.hidden = false;
pill.hidden = true;
}
function collapse() {
open = false;
lsSet(OPEN_KEY, '0');
panel.hidden = true;
pill.hidden = false;
updatePill();
pill.focus({ preventScroll: true });
}
function hideForever() {
hidden = true;
lsSet(HIDDEN_KEY, '1');
if (root) root.hidden = true;
}
// ── Welcome modal ──────────────────────────────────────────────────────────────
// Shown once, only to a signed-out visitor with no progress, on the homepage.
function shouldShowWelcome() {
if (hidden) return false;
if (lsGet(WELCOME_KEY) === '1') return false;
if (isAuthed()) return false;
if (coreDoneCount() > 0) return false;
var p = currentPath();
return p === '/' || p === '/home' || p.indexOf('/home/') === 0;
}
function showWelcome() {
lsSet(WELCOME_KEY, '1');
var overlay = el('div', 'twg-modal-overlay');
overlay.setAttribute('role', 'dialog');
overlay.setAttribute('aria-modal', 'true');
overlay.setAttribute('aria-labelledby', 'twg-modal-title');
var modal = el('div', 'twg-modal');
var art = el('div', 'twg-modal-art');
var artGlyph = el('div', 'twg-modal-art-glyph', '🤖');
artGlyph.setAttribute('aria-hidden', 'true');
art.appendChild(artGlyph);
modal.appendChild(art);
var body = el('div', 'twg-modal-body');
body.appendChild(el('p', 'twg-modal-eyebrow', 'Welcome to three.ws'));
var title = elT('h1', 'twg-modal-title', 'Give your AI a body, in about five minutes');
title.id = 'twg-modal-title';
body.appendChild(title);
body.appendChild(el('p', 'twg-modal-lede',
'Create a 3D AI avatar, give it a personality, and embed it on any site. The core path is free and needs no wallet.'));
var steps = el('ul', 'twg-modal-steps');
[['🧍', 'Create'], ['🧠', 'Add a brain'], ['🔗', 'Embed it']].forEach(function (pair) {
var li = el('li');
var ic = el('span', null, pair[0]);
ic.setAttribute('aria-hidden', 'true');
li.appendChild(ic);
li.appendChild(document.createTextNode(pair[1]));
steps.appendChild(li);
});
body.appendChild(steps);
var actions = el('div', 'twg-modal-actions');
var primary = el('a', 'twg-btn twg-btn-primary');
primary.href = '/create';
primary.appendChild(document.createTextNode('Create your first avatar'));
var arrow = el('span', null, '→');
arrow.setAttribute('aria-hidden', 'true');
primary.appendChild(arrow);
primary.addEventListener('click', function () { close(); });
var ghost = el('button', 'twg-btn twg-btn-ghost', 'Maybe later');
ghost.type = 'button';
ghost.addEventListener('click', close);
actions.appendChild(primary);
actions.appendChild(ghost);
body.appendChild(actions);
body.appendChild(el('p', 'twg-modal-fineprint', 'You can reopen this anytime from “Getting started”, bottom-right.'));
modal.appendChild(body);
overlay.appendChild(modal);
document.body.appendChild(overlay);
// Focus management + restore.
var prevFocus = document.activeElement;
var focusable = modal.querySelectorAll('a[href], button');
(focusable[0] || modal).focus({ preventScroll: true });
function close() {
document.removeEventListener('keydown', onKey, true);
overlay.remove();
if (prevFocus && prevFocus.focus) prevFocus.focus({ preventScroll: true });
}
function onKey(e) {
if (e.key === 'Escape') { e.preventDefault(); close(); return; }
if (e.key === 'Tab' && focusable.length) {
var first = focusable[0];
var lastEl = focusable[focusable.length - 1];
if (e.shiftKey && document.activeElement === first) { e.preventDefault(); lastEl.focus(); }
else if (!e.shiftKey && document.activeElement === lastEl) { e.preventDefault(); first.focus(); }
}
}
document.addEventListener('keydown', onKey, true);
overlay.addEventListener('click', function (e) { if (e.target === overlay) close(); });
}
// ── Onboarding guided tour (src/feature-tour/*, section: "onboarding") ──────
// A short, self-driving 3D-guide walkthrough chaining avatar → world →
// markets → profile, distinct from this checklist. Auto-offered once to a
// genuinely new, signed-in account (zero creations, server-confirmed via
// GET /api/me `show_onboarding_tour`) landing on a top-level entry route;
// always reachable afterward via the "Replay guided tour" link above.
var ONBOARDING_TOUR_ROUTES = ['/', '/home', '/dashboard', '/start'];
var ONBOARDING_TOUR_URL = '/start?tour=start&track=onboarding';
function isTourAlreadyActive() {
try {
var raw = sessionStorage.getItem('tws:tour:state');
return !!(raw && JSON.parse(raw).active === true);
} catch (_) { return false; }
}
function isOnboardingEligibleRoute() {
var p = currentPath();
for (var i = 0; i < ONBOARDING_TOUR_ROUTES.length; i++) {
if (p === ONBOARDING_TOUR_ROUTES[i]) return true;
}
return false;
}
function replayOnboardingTour() {
location.href = ONBOARDING_TOUR_URL;
}
// Best-effort, silent on any failure (signed out → 401, offline, etc.) —
// this must never block or error the page it runs on.
function maybeOfferOnboardingTour() {
if (hidden || !isAuthed() || isTourAlreadyActive() || !isOnboardingEligibleRoute()) return;
if (new URLSearchParams(location.search).get('tour')) return; // a tour deep-link is already in flight
fetch('/api/me', { credentials: 'include' })
.then(function (res) { return res.ok ? res.json() : null; })
.then(function (data) {
if (data && data.user && data.user.show_onboarding_tour) {
location.href = ONBOARDING_TOUR_URL;
}
})
.catch(function () {});
}
// Pull in the shared corner-stack wherever this widget runs — some pages
// include us directly without nav.js (which normally loads it). The stack
// adopts our tagged orphan when it initialises, so order doesn't matter.
function ensureCornerStack() {
if (window.twsCornerStack) return;
if (document.querySelector('script[src="/corner-stack.js"]')) return;
var s = document.createElement('script');
s.src = '/corner-stack.js';
s.defer = true;
(document.head || document.documentElement).appendChild(s);
}
// ── Mount ─────────────────────────────────────────────────────────────────────
function mount() {
ensureCss();
ensureCornerStack();
root = el('div', 'twg-root');
root.appendChild(buildPanel());
root.appendChild(buildPill());
// Flow into the shared corner-stack so it never overlaps the other
// bottom-right cards. The launcher pill owns the corner itself (highest
// priority). Falls back to a plain body mount if the stack isn't ready;
// the data-corner-priority tag lets it be adopted once the stack arrives.
root.setAttribute('data-corner-priority', '30');
if (window.twsCornerStack) window.twsCornerStack.mount(root);
else document.body.appendChild(root);
updatePill();
if (open) expand();
// Hide while any element is fullscreen (immersive 3D etc.).
document.addEventListener('fullscreenchange', function () {
if (root) root.hidden = hidden || !!document.fullscreenElement;
});
document.addEventListener('keydown', function (e) {
if (e.key === 'Escape' && open) collapse();
});
}
// ── Public surface ─────────────────────────────────────────────────────────────
window.__twsGuide = {
complete: complete,
open: function () { if (hidden) { hidden = false; lsSet(HIDDEN_KEY, '0'); if (root) root.hidden = false; } expand(); },
close: collapse,
progress: function () { return Object.assign({}, progress); },
isComplete: allCoreDone,
replayOnboardingTour: replayOnboardingTour,
};
// React to precise completion signals fired by other modules.
document.addEventListener('three-ws:guide', function (e) {
var step = e && e.detail && e.detail.step;
if (step) complete(step);
});
function boot() {
// Record progress regardless of where we are (cross-page resume).
detectMilestones();
// But only render the floating UI on non-immersive pages, when not opted out.
if (!hidden && !isExcludedRoute()) {
mount();
}
maybeOfferOnboardingTour();
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', boot);
} else {
boot();
}
})();