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.
Narrating your page 🟢→🟡
The agent's superpower is talking visitors through your page. This guide covers exactly what it reads, how to control it, and how to script richer tours.
Two kinds of speech
| Method | What it does |
|---|---|
narrate(text) |
Speak one line you provide. |
narratePage() |
Walk the page — speak each content segment in order, highlighting and scrolling to each one. |
The script-tag / element auto-narrate setting calls narratePage() on load.
greeting calls narrate() once.
What narratePage() reads
When the agent tours the page, it builds an ordered list of segments. It picks the first of these sources that yields anything:
- Your selector — elements matching the CSS selector you pass
(
narratePage({ selector: '.tour' })orauto-narrate=".tour"). [data-narrate]elements — anything you've explicitly tagged.- Heading fallback — visible
h1/h2/h3insidemain/article(then page-wideh1/h2), each paired with its following lead paragraph.
A few rules worth knowing:
- Each segment's spoken text is trimmed and capped at 600 characters — keep tagged blocks tight, or split them.
- The heading fallback stops after 12 segments so an untagged page doesn't turn into a monologue. Tag your content to go beyond that.
- Hidden elements (
display:none,visibility:hidden, zero-size) are skipped.
Marking up a guided page
Speak custom copy for an element
Put the words in the attribute. The element's visible text stays whatever it
was — data-narrate is what gets spoken:
<h1 data-narrate="Welcome to the dashboard — here's where your day starts.">
Dashboard
</h1>
Tag a block to read its own text
An empty data-narrate means "read this element's text content":
<section data-narrate>
Your trial includes every feature. No credit card until you're ready.
</section>
Control the order
By default tagged elements are read in DOM order. Override with
data-narrate-order (lower numbers first):
<div data-narrate data-narrate-order="2">Second.</div>
<div data-narrate data-narrate-order="1">First, even though it's lower in the page.</div>
Scope a tour to one region
Pass a selector so only part of the page is toured:
<page-agent avatar="sol" auto-narrate=".product-tour"></page-agent>
guide.narratePage({ selector: '.product-tour > *' });
Greeting first
narratePage({ greet: true }) speaks the agent's persona line before the page
walk — a natural "Hi, I'm Nova, let me show you around." auto-narrate does this
for you. To use your own greeting instead, call narrate() first, then tour:
const guide = new PageAgent({ agent: 'nova' });
guide.on('ready', async () => {
await guide.narrate('Welcome back, friend!');
guide.narratePage(); // greet:false — your line already played
});
Driving narration from your app
narrate() and narratePage() return promises that resolve when speech
finishes, so you can sequence them:
await guide.narrate('First, connect your wallet.');
await guide.narrate('Now pick a network.');
guide.narrate('Done — you're ready to trade.');
Use { interrupt: true } to cut off whatever's playing and speak immediately
(great for click handlers):
helpButton.addEventListener('click', () => {
guide.narrate('This saves your draft without publishing.', { interrupt: true });
});
Stop everything with guide.stop().
React to the tour with events
guide
.on('segment', ({ text, el }) => {
// Fired as each segment begins. `el` is the DOM node being read.
el.classList.add('being-read');
})
.on('caption', (text) => {
// The live caption string, or null when speech ends.
})
.on('state', (s) => {
document.body.dataset.guideSpeaking = s === 'speaking';
});
On the <page-agent> element the same events arrive as DOM CustomEvents:
document.querySelector('page-agent')
.addEventListener('page-agent:segment', (e) => console.log(e.detail.text));
The agent already outlines the current segment in the active guide's accent color and smooth-scrolls it into view — you usually don't need to do anything for a polished tour.
Patterns
A short, scripted welcome instead of a full read:
<page-agent avatar="sol" greeting="Hey! New here? Hit the tour button anytime."></page-agent>
A "Take the tour" button that starts the walk on demand:
tourBtn.addEventListener('click', () => guide.narratePage({ greet: true }));
Route-aware narration in a SPA — re-tour when the view changes:
router.afterEach(() => {
guide.stop();
guide.narratePage({ selector: '[data-view] [data-narrate]' });
});
More of these in the Recipes cookbook.