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 Feature 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,
readState,
writeState,
clearState,
readResume,
markCompleted,
buildPlaylist,
normalizePath,
stopIndexForPath,
sectionTitle,
TOUR_FALLBACK_SELECTORS,
TOUR_CONTENT_ROOT_SELECTOR,
} from './curriculum.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() {
this.curriculum = null;
this.playlist = [];
this.pos = 0;
this.index = 0;
this.track = 'full';
this.paused = false;
this.muted = false;
this.voice = 'nova';
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._soundNudge = null;
this._onKey = this._onKey.bind(this);
this._onUnlockGesture = this._onUnlockGesture.bind(this);
}
// ── Entry points ──────────────────────────────────────────────────────────
// Begin a fresh tour from the very first stop (called by the "Start tour"
// button / ?tour=start). `track` chooses Quick vs Full; voice/speed default to
// the visitor's remembered preferences. Navigates to stop 0's page if needed.
//
// `stopId` starts the tour at a named curriculum stop instead of the top. The
// Tour Atlas (/tour/atlas) links every one of its cards this way, so a visitor
// who found a feature in the atlas can drop the guide onto that exact stop
// rather than sitting through the run-up to it. An unknown id is ignored and
// the tour starts from the beginning, so a stale bookmark degrades to the
// normal experience instead of a dead link.
async start(track, stopId) {
this._showLoading();
await this._ensureCurriculum();
const prefs = readResume();
this.track = track || 'full';
this.voice = prefs.voice || 'nova';
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;
if (stopId) {
const abs = this.curriculum.stops.findIndex((s) => s.id === stopId);
// A stop outside the requested track (an onboarding stop while the
// visitor asked for 'full') is still reachable: switch to the track that
// actually contains it, exactly as the chapter panel's jump does.
if (abs >= 0) {
if (this.playlist.indexOf(abs) < 0) {
this.track = this.curriculum.stops[abs].section === 'onboarding' ? 'onboarding' : 'full';
this.playlist = buildPlaylist(this.curriculum, this.track);
}
const pos = this.playlist.indexOf(abs);
if (pos >= 0) {
this.pos = pos;
this.index = abs;
}
}
}
// Record that the account was actually offered the onboarding tour, so
// the server-side auto-start check (api/me.js `show_onboarding_tour`)
// never re-triggers it — even if the visitor abandons this run before
// the completion card fires.
if (this.track === 'onboarding') this._reportOnboardingProgress('seen');
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 = readState();
if (!state.active) return;
this._showLoading();
await this._ensureCurriculum();
this.paused = state.paused;
this.muted = state.muted;
this.voice = state.voice || 'nova';
this.speed = state.speed || 1;
this.track = state.track || 'full';
this.playlist = buildPlaylist(this.curriculum, this.track);
const here = stopIndexForPath(this.curriculum, location.pathname, this.playlist);
// Clamp the persisted index to the live curriculum: a curriculum that lost
// stops between deploys could otherwise point past the end and silently
// finish the tour on resume.
const wanted = Math.min(Math.max(0, state.index || 0), this.curriculum.stops.length - 1);
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;
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();
}
// ── Mounting ──────────────────────────────────────────────────────────────
async _mount() {
if (this.mounted) return;
this.mounted = true;
// The site-wide corner companion is the same kind of avatar — during the
// tour it would just be a second body on screen, 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();
// On touch browsers audio is gated behind a gesture (and that permission
// dies on every navigation the tour makes). Arm a one-time unlock on the
// first tap of this page, and show a "tap for voice" cue if a clip is
// blocked before then.
this.narrator.onBlocked = () => this._showSoundNudge();
this._armAudioUnlock();
this.avatar = new GuideAvatar();
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),
onAvatar: (entry) => this._setAvatar(entry),
onOpenChange: (open) => this.controls.setMenuOpen(open),
},
{
avatars: this.avatar.avatars(),
currentId: this.avatar.currentAvatarId(),
docsUrl: '/avatar-studio',
},
);
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);
this._hideLoading();
}
// ── 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);
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);
// Surface the unlock cue up front (not after a blocked play() round-trip) so
// a phone visitor knows one tap brings the voice.
if (!this.muted && this.narrator.needsUnlock()) this._showSoundNudge();
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];
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, switch to whichever track actually contains
// it — the Onboarding track for an onboarding-section stop (its own,
// disjoint playlist — see buildPlaylist), or the Full track for everything
// else — so every stop stays reachable from the chapter map regardless of
// which track the visitor started on.
_jumpToAbs(abs) {
if (this.playlist.indexOf(abs) < 0) {
const target = this.curriculum.stops[abs]?.section === 'onboarding' ? 'onboarding' : 'full';
this._applyTrack(target, { silent: true });
}
this._go(this._posForAbs(abs));
}
_togglePause() {
if (this.roam) return this._exitRoam(); // play rejoins the tour from roam
this.paused = !this.paused;
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;
writeState({ muted: this.muted });
this.controls.setMuted(this.muted);
this.narrator.cancel();
if (!this.paused && !this.roam) {
const token = ++this._runToken;
this._narrateAndMaybeAdvance(token);
}
}
// ── Mobile audio unlock ─────────────────────────────────────────────────────
// iOS/Android gate audio behind a user gesture, and the permission resets on
// every page the tour navigates to. We bless the narrator's audio element on
// the first tap of each page; until then a clip plays as a timed caption.
_armAudioUnlock() {
if (!this.narrator?.needsUnlock()) return; // desktop or already unlocked
document.addEventListener('pointerdown', this._onUnlockGesture, true);
document.addEventListener('touchend', this._onUnlockGesture, true);
}
_disarmAudioUnlock() {
document.removeEventListener('pointerdown', this._onUnlockGesture, true);
document.removeEventListener('touchend', this._onUnlockGesture, true);
}
async _onUnlockGesture() {
const ok = await this.narrator.unlock();
if (!ok) return; // that gesture wasn't enough — keep listening for the next
this._disarmAudioUnlock();
this._hideSoundNudge();
// Re-speak the current stop now that we have a voice, so unlocking mid-caption
// doesn't cost the visitor this stop's narration.
if (this.mounted && !this.paused && !this.offRoute && !this.roam) {
const token = ++this._runToken;
this._narrateAndMaybeAdvance(token);
}
}
_showSoundNudge() {
if (this._soundNudge || !this.narrator?.needsUnlock()) return;
ensureNudgeStyles();
const chip = document.createElement('button');
chip.type = 'button';
chip.className = 'tws-tour-soundcue';
chip.setAttribute('aria-label', "Tap to hear the guide's voice");
chip.innerHTML = '<span class="tws-tour-soundcue__icon" aria-hidden="true">🔊</span> Tap for the guide’s voice';
chip.addEventListener('click', () => this._onUnlockGesture());
document.body.appendChild(chip);
requestAnimationFrame(() => chip.classList.add('is-in'));
this._soundNudge = chip;
}
_hideSoundNudge() {
const chip = this._soundNudge;
if (!chip) return;
this._soundNudge = null;
chip.classList.remove('is-in');
setTimeout(() => chip.remove(), 300);
}
// ── 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];
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;
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.roam && this.mounted) {
const token = ++this._runToken;
this._narrateAndMaybeAdvance(token);
}
}
_setVoice(value) {
if (!value || value === this.voice) return;
this.voice = value;
writeState({ voice: value });
this.panel?.setVoice(value);
if (!this.paused && !this.offRoute && !this.roam && this.mounted) {
const token = ++this._runToken;
this._narrateAndMaybeAdvance(token);
}
}
// Swap the guide to any avatar the visitor picks. The guide persists the choice
// (shared with the site-wide Walk Companion) and resolves to the entry actually
// shown — the fallback if the pick failed to load — which we echo back to the
// panel so its button and the picker's check mark stay truthful.
async _setAvatar(entry) {
const shown = await this.avatar.setAvatar(entry);
if (shown?.id) this.panel?.setAvatarCurrent(shown.id);
}
// ── 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);
writeState({ paused: false });
this._go(this.pos);
}
// ── Corner-companion suppression (de-dupe the on-screen avatar) ──────────────
_suppressCompanion() {
const w = window.__walkCompanion;
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('walk-companion:change', this._onCompanionChange);
}
_restoreCompanion() {
if (this._onCompanionChange) {
window.removeEventListener('walk-companion:change', this._onCompanionChange);
this._onCompanionChange = null;
}
const w = window.__walkCompanion;
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;
writeState({ paused: true });
this.controls.setPaused(true);
this._syncControls();
this.panel?.setActive(this.index);
this.avatar.say('We stepped off the tour — press play and I’ll take you back to where we were.');
}
// ── Finish ────────────────────────────────────────────────────────────────
async _finish() {
const token = ++this._runToken;
this._stopBeam();
this.spotlight.highlight(null);
await this.avatar.park();
this.avatar.point();
const isOnboarding = this.track === 'onboarding';
const outro = isOnboarding
? "And that's the loop — avatar, world, markets, and now your own profile with your first creation on it. Everything you make from here shows up right there. Go make something else."
: "And that's the whole platform. You've seen how to build an agent, give it a body and a voice, take it on-chain, and put it to work. Go make something — I'll be around if you want to walk it again.";
await this._present(outro, token);
if (token !== this._runToken) return; // exited / navigated while the outro played
markCompleted();
clearState();
if (isOnboarding) this._reportOnboardingProgress('completed');
this._showCompletion();
}
// Persists onboarding-tour progress server-side (api/me.js) so the
// account-linked "should we auto-offer the tour" decision survives across
// browsers/devices, not just this browser's localStorage. Best-effort and
// silent on failure — the tour's own UX never depends on this succeeding,
// and a signed-out visitor (401) simply doesn't get server-side tracking.
_reportOnboardingProgress(flag) {
try {
fetch('/api/me', {
method: 'POST',
headers: { 'content-type': 'application/json' },
credentials: 'include',
body: JSON.stringify({ onboarding_tour: flag }),
keepalive: true,
}).catch(() => {});
} catch {
/* fetch unavailable / blocked — server-side tracking simply skips */
}
}
_showCompletion() {
const isOnboarding = this.track === 'onboarding';
const card = document.createElement('div');
card.className = 'tws-tour-done';
card.innerHTML = isOnboarding
? `
<div class="tws-tour-done__inner" role="dialog" aria-label="Onboarding complete">
<div class="tws-tour-done__title">You're set up 🎉</div>
<p class="tws-tour-done__body">Avatar made, world built, markets seen, profile live. Ready to take it on-chain?</p>
<div class="tws-tour-done__actions">
<a class="tws-tour-done__btn tws-tour-done__btn--primary" href="/create-agent">Launch a coin</a>
<a class="tws-tour-done__btn" href="/profile">See my profile</a>
<button class="tws-tour-done__btn" data-act="close">I'm good for now</button>
</div>
</div>`
: `
<div class="tws-tour-done__inner" role="dialog" aria-label="Tour complete">
<div class="tws-tour-done__title">Tour complete 🎉</div>
<p class="tws-tour-done__body">You've walked the whole of three.ws. Where to next?</p>
<div class="tws-tour-done__actions">
<a class="tws-tour-done__btn tws-tour-done__btn--primary" href="/create-agent">Build your agent</a>
<button class="tws-tour-done__btn" data-act="restart">Walk it again</button>
<button class="tws-tour-done__btn" data-act="close">Explore on my own</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') {
// Tear the finished tour fully down before starting a fresh one —
// otherwise _mount()'s `if (this.mounted) return` makes restart a
// no-op that reuses the old, half-cleared avatar and listeners.
this.exit();
this.start(this.track);
} else if (act === 'close') {
card.remove();
this.exit();
}
});
this._doneCard = card;
}
// A lightweight, honest loading state shown while the curriculum manifest and
// the guide GLB stream in — no fake progress bar, just a live "preparing" cue
// that clears the moment the real assets are mounted (or the load gives up).
_showLoading() {
if (this._loadingEl) return;
// bootstrap() can fire (via ?tour=/resume) before <body> is parsed — appending
// to a null document.body threw "Cannot read properties of null (reading
// 'appendChild')". Defer to DOMContentLoaded once, then mount normally.
if (typeof document === 'undefined' || !document.body) {
if (typeof document !== 'undefined') {
document.addEventListener('DOMContentLoaded', () => this._showLoading(), { once: true });
}
return;
}
ensureLoadingStyles();
const el = document.createElement('div');
el.className = 'tws-tour-loading';
el.setAttribute('role', 'status');
el.setAttribute('aria-live', 'polite');
el.innerHTML = `
<div class="tws-tour-loading__inner">
<div class="tws-tour-loading__orb" aria-hidden="true"></div>
<div class="tws-tour-loading__label">Waking your guide…</div>
</div>`;
document.body.appendChild(el);
requestAnimationFrame(() => el.classList.add('is-in'));
this._loadingEl = el;
}
_hideLoading() {
const el = this._loadingEl;
if (!el) return;
this._loadingEl = null;
el.classList.remove('is-in');
const drop = () => el.remove();
el.addEventListener('transitionend', drop, { once: true });
this._loadingDrop = setTimeout(drop, 600); // fallback if transitionend never fires
}
// ── Teardown ──────────────────────────────────────────────────────────────
exit() {
this._runToken++;
clearTimeout(this._advanceTimer);
clearState();
this._stopBeam();
this._beam?.remove();
this._disarmAudioUnlock();
this._hideSoundNudge();
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();
clearTimeout(this._loadingDrop);
this._loadingEl?.remove();
this._loadingEl = null;
this._restoreCompanion();
this.mounted = false;
}
// ── Target resolution ─────────────────────────────────────────────────────
// Curriculum anchors are broad on purpose (`form, .wizard, .step, button`),
// because one selector list has to survive across page redesigns. Run
// unscoped, though, document order hands them the site chrome: the nav
// renders before <main> on every page, so `/` spotlit the nav's "Create an
// agent" dropdown link instead of the hero CTA, `/docs` ringed the site nav
// instead of the docs sidebar, and `/create-agent` ringed a nav button
// instead of the wizard. scripts/capture-tour-atlas.mjs found all three.
//
// So: try every selector inside the page's main content first, and only fall
// back to the whole document when nothing in the content matched. A stop whose
// feature genuinely lives in the header (the nav search, the wallet button)
// still resolves on the second pass.
_resolveTarget(stop) {
const selectors = [...(stop.targets || []), ...TOUR_FALLBACK_SELECTORS];
const main = document.querySelector(TOUR_CONTENT_ROOT_SELECTOR);
const scopes = main ? [main, document] : [document];
for (const scope of scopes) {
for (const sel of selectors) {
let el;
try {
el = scope.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().
location.assign(path);
}
_onKey(e) {
if (this.panel?.open) return; // the panel owns the keyboard while it's up
if (isTypingTarget(e.target)) return;
// In free roam the visitor steers the guide with WASD / arrows — free-roam
// owns those keys; here we only let them toggle roam off or escape it.
if (this.roam) {
if (e.key === 'r' || e.key === 'R') this._toggleRoam();
else if (e.key === 'Escape') this._exitRoam();
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;
}
let _nudgeStyles = false;
function ensureNudgeStyles() {
if (_nudgeStyles) return;
_nudgeStyles = true;
const style = document.createElement('style');
style.textContent = `
.tws-tour-soundcue{position:fixed;left:50%;top:calc(env(safe-area-inset-top,0px) + 16px);transform:translateX(-50%) translateY(-12px);z-index:2147483450;display:inline-flex;align-items:center;gap:8px;min-height:44px;padding:10px 18px;border:1px solid rgba(122,162,255,.45);border-radius:99px;background:rgba(14,16,22,.94);backdrop-filter:blur(10px);color:#eaf0ff;font:700 14px/1 system-ui,-apple-system,'Segoe UI',sans-serif;box-shadow:0 12px 34px rgba(0,0,0,.5);cursor:pointer;opacity:0;transition:opacity .3s ease,transform .3s ease;-webkit-tap-highlight-color:transparent;animation:tws-soundcue-pulse 1.8s ease-in-out infinite}
.tws-tour-soundcue.is-in{opacity:1;transform:translateX(-50%) translateY(0)}
.tws-tour-soundcue:active{transform:translateX(-50%) translateY(0) scale(.96)}
.tws-tour-soundcue__icon{font-size:16px}
@keyframes tws-soundcue-pulse{0%,100%{box-shadow:0 12px 34px rgba(0,0,0,.5),0 0 0 0 rgba(122,162,255,.45)}50%{box-shadow:0 12px 34px rgba(0,0,0,.5),0 0 0 7px rgba(122,162,255,0)}}
@media (prefers-reduced-motion:reduce){.tws-tour-soundcue{animation:none;transition:opacity .2s ease}}
`;
document.head.appendChild(style);
}
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);
}
let _loadingStyles = false;
function ensureLoadingStyles() {
if (_loadingStyles) return;
_loadingStyles = true;
const style = document.createElement('style');
style.textContent = `
.tws-tour-loading{position:fixed;inset:0;z-index:2147483400;display:grid;place-items:center;background:rgba(6,8,12,.55);backdrop-filter:blur(5px);opacity:0;transition:opacity .3s ease;font-family:system-ui,-apple-system,'Segoe UI',sans-serif}
.tws-tour-loading.is-in{opacity:1}
.tws-tour-loading__inner{display:flex;flex-direction:column;align-items:center;gap:16px}
.tws-tour-loading__orb{width:54px;height:54px;border-radius:50%;background:conic-gradient(from 0deg,#7aa2ff,#9d7bff,#7aa2ff);-webkit-mask:radial-gradient(farthest-side,transparent calc(100% - 6px),#000 0);mask:radial-gradient(farthest-side,transparent calc(100% - 6px),#000 0);animation:tws-tour-spin 1s linear infinite}
.tws-tour-loading__label{color:#cdd5e6;font-size:14px;font-weight:600;letter-spacing:.01em}
@keyframes tws-tour-spin{to{transform:rotate(1turn)}}
@media (prefers-reduced-motion:reduce){.tws-tour-loading{transition:none}.tws-tour-loading__orb{animation-duration:2.4s}}
`;
document.head.appendChild(style);
}