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/tour — a 3D guide that walks your live site and narrates it.
// =====================================================================
// A small avatar walks across the real page, spotlights each feature, points at
// it with a beam, and speaks a line about it — a guided product tour that runs
// on your actual DOM, not a slideshow. It survives full-page navigation (state
// in sessionStorage), offers Quick/Full tracks, a searchable chapter map, free
// roam, and adjustable voice/speed. `three` and `@three-ws/walk` are peer
// dependencies — bring your own copies.
//
// Quick start (auto-mount + deep-link, app-style):
//
// import { createFeatureTour } from '@three-ws/tour';
// const tour = createFeatureTour({
// curriculum: '/tour/curriculum.json', // or an inline object
// ttsEndpoint: '/api/tts/speak', // optional — captions pace without it
// });
// window.__featureTour = tour; // let your nav button call it
// tour.bootstrap(); // honour ?tour=… and rehydrate
//
// Or drive it yourself:
//
// const tour = createFeatureTour();
// tour.start('quick'); // begin the Quick-highlights track
// tour.resume(); // pick up an in-progress tour after a navigation
// tour.exit(); // tear everything down
import { TourDirector } from './director.js';
import { ExploreMode } from './explore.js';
import { resolveTourConfig } from './config.js';
import { createTourState, loadCurriculum } from './curriculum.js';
// Kept in lockstep with package.json's version by test/index.test.mjs, the
// CDN bundle reports this string, so a stale constant misidentifies the build.
export const VERSION = '0.5.2';
/**
* Create a tour controller. Returns a small object the host drives:
* `start(track)`, `resume()`, `exit()`, `isActive()`, `bootstrap()`, plus the
* live `director` once one exists.
*
* @param {object} [options] see resolveTourConfig for the full option list.
*/
export function createFeatureTour(options = {}) {
const config = resolveTourConfig(options);
const state = createTourState(config);
let director = null;
let explore = null;
const ensure = () => (director ||= new TourDirector(config));
// 'platformer' is explore with the platformer movement model.
const exploreConfigured = () => config.mode === 'explore' || config.mode === 'platformer';
// In explore/platformer mode, start() drives the checkpoint experience
// instead of the guided auto-tour — so the same nav button, ?tour deep link,
// and autostart all route to whichever mode the host configured.
async function startExplore() {
if (explore?.isActive()) return;
const curriculum =
config.curriculum && typeof config.curriculum === 'object'
? config.curriculum
: await loadCurriculum(config);
explore = new ExploreMode(config, curriculum);
return explore.start();
}
const control = {
get director() {
return director;
},
get explore() {
return explore;
},
get config() {
return config;
},
isActive() {
return explore?.isActive() === true || state.readState().active === true;
},
start(track) {
if (exploreConfigured()) return startExplore();
return ensure().start(track);
},
startExplore,
resume() {
if (exploreConfigured()) return startExplore();
return ensure().resume();
},
exit() {
explore?.exit();
director?.exit();
},
// Auto-mount / deep-link behaviour. Safe to call once on load. With the
// default deepLinkParam 'tour': `?tour=start` begins (optionally
// `&track=quick`), `?tour=0` exits, `?tour=1` (or an already-active tour)
// resumes. Never runs inside an embed/iframe.
bootstrap() {
if (typeof window === 'undefined') return;
if (window.top !== window.self) return; // never inside an embed/iframe
const params = new URLSearchParams(location.search);
const param = params.get(config.deepLinkParam);
if (param === 'start') {
if (exploreConfigured()) startExplore();
else ensure().start(params.get('track') === 'quick' ? 'quick' : 'full');
} else if (param === '0') {
control.exit();
} else if (param === '1' || (!exploreConfigured() && state.readState().active)) {
control.resume();
}
},
};
return control;
}
// Engine internals, exported for advanced/standalone use.
export { TourDirector } from './director.js';
export { ExploreMode } from './explore.js';
export { resolveTourConfig, DEFAULT_VOICES, DEFAULT_COPY } from './config.js';
export {
loadCurriculum,
createTourState,
buildPlaylist,
trackMeta,
stopIndexForPath,
sectionTitle,
normalizePath,
} from './curriculum.js';
// Curriculum authoring helper — turn a pages document into a tour curriculum.
export { buildCurriculum } from './build-curriculum.js';