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
// director.js — the brain of the tour. It walks the curriculum stop by stop:
// for each one it finds the real on-page element to showcase, spotlights it,
// walks the guide avatar over to point at it, draws a beam from the avatar to
// the feature, speaks the narration, and — unless paused — advances. When the
// next stop lives on another route it persists progress and navigates; the tour
// re-hydrates from sessionStorage on the new page and picks up exactly where it
// left off. One module owns all of that sequencing and every control.
//
// Navigation is expressed over a *playlist* — the ordered list of stop indices
// the chosen track visits (the Full track is every stop; the Quick track is the
// highlighted heroes). `pos` is where we are in that playlist; `index` is the
// absolute curriculum stop it points at. Switching tracks re-derives the
// playlist and re-anchors `pos` to the nearest stop, so the tour never loses its
// place. The chapter panel can jump to any stop, expanding to the Full track if
// the requested stop isn't in the current one.
import {
loadCurriculum,
createTourState,
buildPlaylist,
normalizePath,
stopIndexForPath,
sectionTitle,
} from './curriculum.js';
import { resolveTourConfig } from './config.js';
import { GuideAvatar } from './guide-avatar.js';
import { Spotlight } from './spotlight.js';
import { Narrator } from './narrator.js';
import { TourControls } from './controls.js';
import { ChapterPanel } from './chapters.js';
import { FreeRoam } from './free-roam.js';
const ADVANCE_BEAT_MS = 900; // pause between finishing a stop and moving on
const Z_BEAM = 2147483280;
const SPEED_CYCLE = [1, 1.25, 1.5, 0.75];
export class TourDirector {
constructor(config) {
this.config = config && config.keys ? config : resolveTourConfig(config);
this.state = createTourState(this.config);
this.curriculum = null;
this.playlist = [];
this.pos = 0;
this.index = 0;
this.track = 'full';
this.paused = false;
this.muted = false;
this.voice = this.config.defaultVoice;
this.speed = 1;
this.mounted = false;
this.offRoute = false;
this.roam = false;
this._runToken = 0;
this._advanceTimer = 0;
this._seenSections = new Set();
this._beamRaf = 0;
this._beamActive = false;
this._onKey = this._onKey.bind(this);
}
// ── Entry points ──────────────────────────────────────────────────────────
// Begin a fresh tour from the very first stop (called by the host's "Start
// tour" action / the deep-link). `track` chooses Quick vs Full; voice/speed
// default to the visitor's remembered preferences. Navigates to stop 0's page
// if needed.
async start(track) {
await this._ensureCurriculum();
const prefs = this.state.readResume();
this.track = track || 'full';
this.voice = prefs.voice || this.config.defaultVoice;
this.speed = prefs.speed || 1;
this.muted = false;
this.paused = false;
this._seenSections = new Set();
this.playlist = buildPlaylist(this.curriculum, this.track);
this.pos = 0;
this.index = this.playlist[0] ?? 0;
this.state.writeState({
active: true,
index: this.index,
track: this.track,
voice: this.voice,
speed: this.speed,
paused: false,
muted: false,
});
const first = this.curriculum.stops[this.index];
if (normalizePath(first.path) !== normalizePath()) {
this._navigate(first.path);
return;
}
await this._mount();
this._runCurrent();
}
// Re-hydrate on a normal page load when a tour is already in progress.
async resume() {
const state = this.state.readState();
if (!state.active) return;
await this._ensureCurriculum();
this.paused = state.paused;
this.muted = state.muted;
this.voice = state.voice || this.config.defaultVoice;
this.speed = state.speed || 1;
this.track = state.track || 'full';
this.playlist = buildPlaylist(this.curriculum, this.track);
const here = stopIndexForPath(this.curriculum, location.pathname);
const wanted = state.index || 0;
if (normalizePath(this.curriculum.stops[wanted]?.path) === normalizePath()) {
this.index = wanted; // arrived exactly where we were heading
this.offRoute = false;
} else if (here >= 0) {
this.index = here; // visitor hand-navigated to another stop's page
this.offRoute = false;
this.state.writeState({ index: here });
} else {
this.index = wanted; // wandered off the route entirely
this.offRoute = true;
}
this.pos = this._posForAbs(this.index);
await this._mount();
if (this.offRoute) {
this._showOffRoute();
} else {
this._runCurrent();
}
}
async _ensureCurriculum() {
if (!this.curriculum) this.curriculum = await loadCurriculum(this.config);
}
// ── Mounting ──────────────────────────────────────────────────────────────
async _mount() {
if (this.mounted) return;
this.mounted = true;
// A companion avatar (e.g. the @three-ws/walk corner mascot) would just be a
// second body on screen during the tour, so stand it down (and its
// click-to-walk, which would otherwise fight free roam) and bring it back
// when the tour ends.
this._suppressCompanion();
this._buildBeam();
this.spotlight = new Spotlight();
this.narrator = new Narrator(this.config);
this.avatar = new GuideAvatar(this.config);
await this.avatar.mount();
this.freeRoam = new FreeRoam(this.avatar);
this.controls = new TourControls({
onMenu: () => this.panel?.toggle(),
onPrev: () => this._go(this.pos - 1),
onNext: () => this._go(this.pos + 1),
onToggle: () => this._togglePause(),
onSeek: (i) => this._go(i),
onSpeed: () => this._cycleSpeed(),
onRoam: () => this._toggleRoam(),
onMute: () => this._toggleMute(),
onExit: () => this.exit(),
});
this.panel = new ChapterPanel(
this.curriculum,
{
onJump: (abs) => this._jumpToAbs(abs),
onTrack: (t) => this._applyTrack(t),
onSpeed: (v) => this._setSpeed(v),
onVoice: (v) => this._setVoice(v),
onOpenChange: (open) => this.controls.setMenuOpen(open),
},
this.config.voices,
);
this.controls.setMuted(this.muted);
this.controls.setPaused(this.paused);
this.controls.setSpeed(this.speed);
this.panel.setTrack(this.track);
this.panel.setSpeed(this.speed);
this.panel.setVoice(this.voice);
document.addEventListener('keydown', this._onKey);
}
// ── Running a stop ────────────────────────────────────────────────────────
async _runCurrent() {
const token = ++this._runToken;
clearTimeout(this._advanceTimer);
this.offRoute = false;
const stop = this.curriculum.stops[this.index];
if (!stop) return this._finish();
this._syncControls();
this.panel?.setActive(this.index);
this.state.writeState({ index: this.index });
// Chapter bridge — spoken once per section per session.
if (stop.sectionIntro && !this._seenSections.has(stop.section)) {
this._seenSections.add(stop.section);
await this.avatar.park();
if (token !== this._runToken) return;
this.avatar.point();
await this._present(stop.sectionIntro, token);
if (token !== this._runToken) return;
}
// Move to the feature and point at it.
const target = this._resolveTarget(stop);
if (target) {
await this.spotlight.highlight(target);
if (token !== this._runToken) return;
await this.avatar.approach(this.spotlight.getRect() || rectOf(target));
if (token !== this._runToken) return;
this._startBeam();
} else {
this.spotlight.highlight(null);
this._stopBeam();
await this.avatar.park();
if (token !== this._runToken) return;
}
this.avatar.point();
await this._narrateAndMaybeAdvance(token);
}
async _narrateAndMaybeAdvance(token) {
await this._present(this.curriculum.stops[this.index].narration, token);
if (token !== this._runToken) return;
if (this.paused) return;
this._advanceTimer = setTimeout(() => {
if (token === this._runToken) this._advance();
}, ADVANCE_BEAT_MS / this.speed);
}
// Show caption + speak; resolves when the voice (or timed fallback) ends.
async _present(text, token) {
this.avatar.say(text);
await this.narrator.speak(text, { muted: this.muted, voice: this.voice, speed: this.speed });
}
_advance() {
if (this.pos + 1 >= this.playlist.length) return this._finish();
this._go(this.pos + 1);
}
// Go to a playlist position (prev / next / scrub / advance / jump). Cancels
// anything in flight, then runs the stop here or navigates if it's off-page.
_go(pos) {
if (!this.playlist.length) return;
if (this.roam) {
// Any explicit navigation leaves free roam and resumes the guided tour.
this.roam = false;
this.freeRoam?.disable();
this.controls?.setRoam(false);
}
const clamped = Math.max(0, Math.min(this.playlist.length - 1, pos));
this._runToken++;
clearTimeout(this._advanceTimer);
this.narrator?.cancel();
this.pos = clamped;
this.index = this.playlist[clamped];
this.state.writeState({ index: this.index });
this.panel?.setActive(this.index);
const stop = this.curriculum.stops[this.index];
if (normalizePath(stop.path) === normalizePath()) {
this._runCurrent();
} else {
this._navigate(stop.path);
}
}
// Jump to an absolute curriculum stop from the chapter panel. If it isn't in
// the current track's playlist, expand to the Full track so every stop is
// reachable, then go to it.
_jumpToAbs(abs) {
if (this.playlist.indexOf(abs) < 0) this._applyTrack('full', { silent: true });
this._go(this._posForAbs(abs));
}
_togglePause() {
if (this.roam) return this._exitRoam(); // play rejoins the tour from roam
this.paused = !this.paused;
this.state.writeState({ paused: this.paused });
this.controls.setPaused(this.paused);
if (this.paused) {
clearTimeout(this._advanceTimer);
this.narrator.cancel();
this._runToken++; // freeze the current sequence
} else if (this.offRoute) {
this._go(this.pos);
} else {
// Resume re-narrates the current stop, then continues.
const token = ++this._runToken;
this._narrateAndMaybeAdvance(token);
}
}
_toggleMute() {
this.muted = !this.muted;
this.state.writeState({ muted: this.muted });
this.controls.setMuted(this.muted);
this.narrator.cancel();
if (!this.paused) {
const token = ++this._runToken;
this._narrateAndMaybeAdvance(token);
}
}
// ── Track / speed / voice ───────────────────────────────────────────────────
_applyTrack(track, { silent = false } = {}) {
if (track === this.track) return;
const abs = this.index;
this.track = track;
this.playlist = buildPlaylist(this.curriculum, track);
this.pos = this._posForAbs(abs);
this.index = this.playlist[this.pos];
this.state.writeState({ track, index: this.index });
this.panel?.setTrack(track);
this._syncControls();
if (!silent) this._go(this.pos); // re-anchor to the (possibly new) stop
}
_cycleSpeed() {
const i = SPEED_CYCLE.indexOf(this.speed);
this._setSpeed(SPEED_CYCLE[(i + 1) % SPEED_CYCLE.length]);
}
_setSpeed(value) {
const next = Math.min(2, Math.max(0.5, Number(value) || 1));
if (next === this.speed) return;
this.speed = next;
this.state.writeState({ speed: next });
this.controls?.setSpeed(next);
this.panel?.setSpeed(next);
// Re-narrate the current stop at the new rate if we're actively playing.
if (!this.paused && !this.offRoute && this.mounted) {
const token = ++this._runToken;
this._narrateAndMaybeAdvance(token);
}
}
_setVoice(value) {
if (!value || value === this.voice) return;
this.voice = value;
this.state.writeState({ voice: value });
this.panel?.setVoice(value);
if (!this.paused && !this.offRoute && this.mounted) {
const token = ++this._runToken;
this._narrateAndMaybeAdvance(token);
}
}
// ── Free roam ───────────────────────────────────────────────────────────────
// Hand the stage to the visitor: freeze the guided sequence and let them drive
// the guide around the page (free-roam.js). Toggling off — or any navigation /
// play — rejoins the tour at the current stop.
_toggleRoam() {
this.roam ? this._exitRoam() : this._enterRoam();
}
_enterRoam() {
if (this.roam) return;
this.roam = true;
this._runToken++; // freeze whatever the guide was doing
clearTimeout(this._advanceTimer);
this.narrator?.cancel();
this._stopBeam();
this.spotlight?.highlight(null);
this.avatar?.hideBubble();
this.panel?.close();
this.controls?.setRoam(true);
this.freeRoam?.enable();
}
_exitRoam() {
if (!this.roam) return;
this.roam = false;
this.freeRoam?.disable();
this.controls?.setRoam(false);
// Rejoining the tour means playing again from the current stop.
this.paused = false;
this.controls?.setPaused(false);
this.state.writeState({ paused: false });
this._go(this.pos);
}
// ── Companion suppression (de-dupe the on-screen avatar) ─────────────────────
_suppressCompanion() {
const cfg = this.config.companion;
if (!cfg) return;
const w = window[cfg.global];
if (!w) return;
this._companionWasOn = !!(w.instance?.mounted || (w.isEnabled && w.isEnabled()));
const hide = () => {
try {
if (w.instance?.mounted) w.instance.unmount();
} catch {
/* companion mid-mount — the change listener will catch it */
}
};
hide();
// The companion auto-mounts on load (and on playground return); re-hide it
// whenever it reappears while the tour owns the screen.
this._onCompanionChange = hide;
window.addEventListener(cfg.changeEvent, this._onCompanionChange);
}
_restoreCompanion() {
const cfg = this.config.companion;
if (cfg && this._onCompanionChange) {
window.removeEventListener(cfg.changeEvent, this._onCompanionChange);
this._onCompanionChange = null;
}
if (!cfg) return;
const w = window[cfg.global];
if (!w || !this._companionWasOn) return;
try {
if (!w.instance?.mounted) (w.instance ? w.instance.mount() : w.enable?.());
} catch {
/* non-fatal — the companion will re-mount on the next page load */
}
}
// Playlist position for an absolute stop index — exact match, else nearest.
_posForAbs(abs) {
const p = this.playlist.indexOf(abs);
if (p >= 0) return p;
let best = 0;
let bestD = Infinity;
this.playlist.forEach((a, i) => {
const d = Math.abs(a - abs);
if (d < bestD) {
bestD = d;
best = i;
}
});
return best;
}
// ── Off-route recovery ────────────────────────────────────────────────────
_showOffRoute() {
this._stopBeam();
this.spotlight.highlight(null);
this.avatar.park();
this.paused = true;
this.state.writeState({ paused: true });
this.controls.setPaused(true);
this._syncControls();
this.panel?.setActive(this.index);
this.avatar.say(this.config.copy.offRoute);
}
// ── Finish ────────────────────────────────────────────────────────────────
async _finish() {
const token = ++this._runToken;
this._stopBeam();
this.spotlight.highlight(null);
await this.avatar.park();
this.avatar.point();
await this._present(this.config.copy.outro, token);
if (token !== this._runToken) return;
this.state.markCompleted();
this.state.clearState();
document.removeEventListener('keydown', this._onKey);
this._showCompletion();
}
_showCompletion() {
const done = this.config.copy.completion;
const card = document.createElement('div');
card.className = 'tws-tour-done';
const primary = done.primary
? `<a class="tws-tour-done__btn tws-tour-done__btn--primary" href="${escAttr(done.primary.href)}">${escHtml(done.primary.label)}</a>`
: '';
card.innerHTML = `
<div class="tws-tour-done__inner" role="dialog" aria-label="Tour complete">
<div class="tws-tour-done__title">${escHtml(done.title)}</div>
<p class="tws-tour-done__body">${escHtml(done.body)}</p>
<div class="tws-tour-done__actions">
${primary}
<button class="tws-tour-done__btn" data-act="restart">${escHtml(done.restartLabel)}</button>
<button class="tws-tour-done__btn" data-act="close">${escHtml(done.closeLabel)}</button>
</div>
</div>`;
ensureDoneStyles();
document.body.appendChild(card);
requestAnimationFrame(() => card.classList.add('is-in'));
card.addEventListener('click', (e) => {
const act = e.target.closest('[data-act]')?.dataset.act;
if (act === 'restart') {
card.remove();
this.start(this.track);
} else if (act === 'close') {
card.remove();
this.exit();
}
});
this._doneCard = card;
}
// ── Teardown ──────────────────────────────────────────────────────────────
exit() {
this._runToken++;
clearTimeout(this._advanceTimer);
this.state.clearState();
this._stopBeam();
this._beam?.remove();
document.removeEventListener('keydown', this._onKey);
this.roam = false;
this.freeRoam?.disable();
this.narrator?.dispose();
this.spotlight?.dispose();
this.avatar?.dispose();
this.controls?.dispose();
this.panel?.dispose();
this._doneCard?.remove();
this._restoreCompanion();
this.mounted = false;
}
// ── Target resolution ─────────────────────────────────────────────────────
_resolveTarget(stop) {
const selectors = [
...(stop.targets || []),
'[data-tour-target]',
'main h1, .hero h1, h1',
'a.cta, .btn-primary, button[type="submit"], main a.button, .hero a',
];
for (const sel of selectors) {
let el;
try {
el = document.querySelector(sel);
} catch {
continue;
}
if (isVisible(el)) return el;
}
return null;
}
// ── Pointer beam (avatar → feature) ───────────────────────────────────────
_buildBeam() {
const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
svg.setAttribute('class', 'tws-tour-beam');
svg.style.cssText = `position:fixed;inset:0;width:100vw;height:100vh;z-index:${Z_BEAM};pointer-events:none;opacity:0;transition:opacity .3s ease`;
svg.innerHTML = `
<defs>
<marker id="tws-tour-arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
<path d="M0,0 L10,5 L0,10 z" fill="rgba(122,162,255,.95)"/>
</marker>
</defs>
<line class="tws-tour-beam__line" stroke="rgba(122,162,255,.9)" stroke-width="2.5" stroke-dasharray="2 7" stroke-linecap="round" marker-end="url(#tws-tour-arrow)"/>
`;
document.body.appendChild(svg);
this._beam = svg;
this._beamLine = svg.querySelector('.tws-tour-beam__line');
}
_startBeam() {
if (this._beamActive) return;
this._beamActive = true;
this._beam.style.opacity = '1';
const tick = () => {
if (!this._beamActive) return;
const rect = this.spotlight.getRect();
const head = this.avatar.headScreen();
if (rect && head) {
// Aim at the nearest edge of the feature, not dead-center, so the
// arrow lands on the box rather than burying itself inside it.
const tx = clamp(head.x, rect.left, rect.left + rect.width);
const ty = clamp(head.y, rect.top, rect.top + rect.height);
this._beamLine.setAttribute('x1', head.x);
this._beamLine.setAttribute('y1', head.y);
this._beamLine.setAttribute('x2', tx);
this._beamLine.setAttribute('y2', ty);
}
this._beamRaf = requestAnimationFrame(tick);
};
this._beamRaf = requestAnimationFrame(tick);
}
_stopBeam() {
this._beamActive = false;
cancelAnimationFrame(this._beamRaf);
if (this._beam) this._beam.style.opacity = '0';
}
// ── Misc ──────────────────────────────────────────────────────────────────
_syncControls() {
const stop = this.curriculum.stops[this.index];
this.controls.update({
chapter: sectionTitle(this.curriculum, stop.section),
index: this.pos,
total: this.playlist.length,
});
}
_navigate(path) {
// Progress is already persisted; the new page's bootstrap calls resume().
this.config.navigate(path);
}
_onKey(e) {
if (this.panel?.open) return; // the panel owns the keyboard while it's up
if (isTypingTarget(e.target)) return;
if (e.key === ' ' || e.key === 'k') {
e.preventDefault();
this._togglePause();
} else if (e.key === 'ArrowRight') {
this._go(this.pos + 1);
} else if (e.key === 'ArrowLeft') {
this._go(this.pos - 1);
} else if (e.key === 'm' || e.key === 'M') {
this._toggleMute();
} else if (e.key === 'c' || e.key === 'C') {
this.panel?.toggle();
} else if (e.key === 'r' || e.key === 'R') {
this._toggleRoam();
} else if (e.key === 'Escape') {
if (this.roam) this._exitRoam();
else this.exit();
}
}
}
// ── helpers ──────────────────────────────────────────────────────────────────
function clamp(n, lo, hi) {
return Math.min(hi, Math.max(lo, n));
}
function rectOf(el) {
const r = el.getBoundingClientRect();
return { left: r.left, top: r.top, width: r.width, height: r.height, cx: r.left + r.width / 2, cy: r.top + r.height / 2 };
}
function isVisible(el) {
if (!el || !el.isConnected) return false;
const r = el.getBoundingClientRect();
if (r.width < 4 || r.height < 4) return false;
const style = getComputedStyle(el);
return style.visibility !== 'hidden' && style.display !== 'none' && Number(style.opacity) > 0.05;
}
function isTypingTarget(el) {
if (!el) return false;
const tag = el.tagName;
return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || el.isContentEditable;
}
function escHtml(s) {
return String(s == null ? '' : s).replace(
/[&<>"']/g,
(c) => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[c],
);
}
function escAttr(s) {
return escHtml(s);
}
let _doneStyles = false;
function ensureDoneStyles() {
if (_doneStyles) return;
_doneStyles = true;
const style = document.createElement('style');
style.textContent = `
.tws-tour-done{position:fixed;inset:0;z-index:2147483500;display:grid;place-items:center;background:rgba(6,8,12,.6);backdrop-filter:blur(6px);opacity:0;transition:opacity .35s ease;font-family:system-ui,-apple-system,'Segoe UI',sans-serif}
.tws-tour-done.is-in{opacity:1}
.tws-tour-done__inner{background:#11141c;border:1px solid rgba(122,162,255,.25);border-radius:20px;padding:28px 30px;max-width:380px;text-align:center;box-shadow:0 30px 80px rgba(0,0,0,.5)}
.tws-tour-done__title{font-size:22px;font-weight:700;color:#f2f4f8;margin-bottom:8px}
.tws-tour-done__body{color:#aeb6c6;font-size:14px;line-height:1.5;margin:0 0 20px}
.tws-tour-done__actions{display:flex;flex-direction:column;gap:10px}
.tws-tour-done__btn{appearance:none;border:1px solid rgba(255,255,255,.14);background:rgba(255,255,255,.05);color:#eef1f6;padding:11px 16px;border-radius:11px;font-size:14px;font-weight:600;cursor:pointer;text-decoration:none;display:block;transition:background .18s ease,border-color .18s ease}
.tws-tour-done__btn:hover{background:rgba(255,255,255,.1)}
.tws-tour-done__btn--primary{background:linear-gradient(90deg,#7aa2ff,#9d7bff);color:#0b0e16;border-color:transparent}
.tws-tour-done__btn--primary:hover{filter:brightness(1.06)}
`;
document.head.appendChild(style);
}