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.
Contributing to @three-ws/page-agent
Thanks for helping build the best rigged 3D guide on the web. This package is
small, dependency-light (only three), and fully client-side — which makes it a
great place to contribute, whether you're adding an avatar, sharpening the
lipsync, or shipping a framework adapter.
- New to the codebase? Read the docs first — especially Building blocks, which mirrors the source layout.
- Releasing? That's PUBLISHING.md, not this file.
Dev setup
The package lives inside the three.ws monorepo but is self-contained.
git clone https://github.com/nirholas/three.ws
cd three.ws/page-agent-sdk
npm install # at the repo root if the workspace needs it
npm run build # → dist/page-agent.{mjs,global.js,css}
npm test # catalog + lipsync unit tests
Try your changes live
The example runs the unbundled source straight from disk via an import map — no build step between edits:
npx serve . # or any static server at the package root
# open http://localhost:3000/examples/index.html
Edit a file in src/, refresh, see it. (The example imports ../src/index.js.)
Project layout
Each module is one focused piece. Keep them that way.
| File | Responsibility |
|---|---|
src/index.js |
Public entry. Exports, <page-agent> registration, data-page-agent auto-init. |
src/page-agent.js |
The PageAgent controller: DOM chrome, drag, narration orchestration, events, collectSegments. |
src/stage.js |
AvatarStage — three.js scene, GLB load, framing, idle/talk animation, blink. |
src/narrator.js |
SpeechNarrator — Web Speech queue, voice selection, lipsync driving. |
src/lipsync.js |
The text→viseme engine: buildMorphMap, createLipsync, estimateDurationMs. |
src/picker.js |
AvatarPicker — accessible modal roster grid. |
src/catalog.js |
The rigged agent roster + getAgent/agentUrl/filterAgents. |
src/element.js |
The <page-agent> custom element. |
src/styles.js |
The injected stylesheet (also emitted as dist/page-agent.css). |
build.mjs |
esbuild: ESM (three external) + IIFE global (three inlined) + CSS. |
types/index.d.ts |
Hand-written types — keep in sync with the source. |
Code style
Match the surrounding code; consistency over preference.
- Tabs for indentation; semicolons; single quotes.
- ES modules, modern browser APIs, no transpilation assumptions beyond ES2020.
- No new runtime dependencies.
threeis the only peer; the engine stays dependency-free. (Dev tooling like esbuild is fine.) - No mocks, no placeholders, no
TODOs. Finish what you start. Real APIs only. - Handle errors at the boundary (load, speech). The graceful-degradation contract is sacred: if TTS fails or is muted, the avatar must still visibly "talk" and captions must still render — narration never silently stalls.
- Accessibility is not optional. Keep ARIA roles, focus management, keyboard
paths, and
prefers-reduced-motionsupport intact. - Run the linter and tests before opening a PR.
Testing
Unit tests run on Node's built-in test runner (no framework):
npm test
- Tests live in
test/as*.test.js. - The catalog and lipsync engine are pure and fully testable — add coverage for
any change there. See
test/catalog.test.jsfor the shape: every agent must be rigged, lipsync-classified, point at a.glb, carry a voice profile, and have a valid hex accent — these invariants are enforced. - DOM-heavy modules (
PageAgent,AvatarStage) aren't unit-tested yet — a jsdom-based harness is a welcome contribution (see ideas).
Add an agent to the catalog
The roster is deliberately diverse and every entry must be rigged — that's enforced by tests, not vibes. To add a guide:
Verify the rig. Your GLB needs a skinned mesh + armature, ideally an idle clip and ARKit visemes. Confirm with
buildMorphMap— see Custom avatars → Verifying your rig.Host the GLB where the catalog's
assetBaseserves it (or give the entry an absoluteurl). Don't commit large binaries to the repo without discussing it in the issue first.Add the entry to
src/catalog.js:{ id: 'rio', // stable, unique, kebab/slug name: 'Rio', tagline: 'Warm, energetic host', // one line for the picker card persona: "I'm Rio — I'll make this quick and fun.", // plain language, no jargon file: 'rio.glb', // filename under assetBase rig: 'rpm', // 'rpm' | 'mixamo' | 'studio' lipsync: 'viseme', // 'viseme' | 'jaw' | 'animation' presents: 'neutral', // 'female' | 'male' | 'neutral' | 'robot' style: 'stylized', // 'realistic' | 'stylized' | 'robot' framing: 'upper', // 'bust' | 'upper' | 'full' voice: { lang: 'en-US', pitch: 1.0, rate: 1.0, match: ['aria', 'jenny'] }, accent: '#10b981', // hex; used for UI chrome + highlights }Pick the right
lipsyncfor what the rig actually exposes (visemes → jaw → animation). Mis-declaring it makes the mouth look wrong.Tune the voice profile.
matchis an ordered list of case-insensitive substrings tried against installed system voices; add a couple of good cross-platform options, plus alang.Run
npm test— the catalog invariants must pass.Update the roster tables in
README.mdanddocs/api-reference.md.Add a line to the platform changelog if this ships to users.
Keep the roster diverse: variety of style, presents, and lipsync is a
feature, not clutter.
Improve the lipsync engine
src/lipsync.js is a deterministic text→viseme heuristic. It's
intentionally simple and dependency-free, but there's real headroom:
- A proper phoneme dictionary (grapheme→phoneme) for English, then other languages, would beat the per-character mapping.
- Coarticulation / blending between adjacent visemes for smoother mouths.
- An optional audio-driven mode: analyse
SpeechSynthesisoutput (or an<audio>element) with a Web AudioAnalyserNodeand drivejawOpenfrom amplitude for non-viseme rigs.
Keep the current API (createLipsync(text, morph, opts).tick/stop/done/totalMs)
stable, or add a new mode behind it. Cover changes with tests.
Ship a framework adapter
An official React wrapper exists (@three-ws/react).
Thin, well-typed adapters for Vue, Svelte, Solid, or Angular are very welcome —
follow the patterns in Framework integration:
construct in a mount hook, expose narrate/setAgent, dispose() on unmount.
Ideas worth building
Pick one, open an issue to claim it, and have at it. Roughly easy → ambitious:
- More languages — externalize the built-in strings (picker title/subtitle, the "not much text here" fallback line) and add locales.
- Persisted position — remember where a visitor dragged the agent.
- Theming API — expose CSS custom properties so hosts can restyle the chrome without overriding internals.
- jsdom test harness — unit-test
PageAgentDOM wiring, events, andcollectSegmentssegment selection. - Gesture cues in copy — let
data-narratecarry hints ([wave],[point]) that trigger the talk/gesture clip or aim the agent at the highlighted element. - Point at the segment — rotate/lean the avatar toward the element it's currently narrating.
- Audio-driven lipsync — the Web Audio analyser mode described above.
- Ask-me-anything mode — optional Web Speech recognition for voice questions, answered by a host-provided callback (bring-your-own LLM; the package stays backend-free by default).
- Streaming narration — accept an async iterator / stream of text so a host-side LLM can narrate as tokens arrive.
- Bundle diet — an entry that imports only the three.js bits used, to shrink the global build.
- More rigged agents — see above.
Each of these should preserve the core promises: client-side, no API key, accessible, graceful, one WebGL context.
Pull requests
- Branch from
main. Keep the change focused. npm run build && npm test— both green.- Update docs/types/roster tables touched by your change.
- Describe the why, with a before/after or a short clip for UI/3D changes.
- By contributing you agree your work is licensed under the project's Apache-2.0.
Questions or proposals → open an issue. Thank you for making it better. 🙌