Docs / Walk / Chrome extension
Chrome extension
The three.ws Walk Avatar extension (v1.0.0) puts a floating 3D avatar on any website you visit. It walks alongside you and can read page sections aloud — a living browsing companion. It only ever runs on tabs you explicitly enable.
What it does
- Mounts your avatar on any site. The avatar is the same transparent
/walk-embediframe, injected into the current tab when you toggle it on. - Reads pages aloud (optional). With narration enabled, it detects the main article, tracks what's in view, and speaks visible sections using text-to-speech.
- Respects your rules. Per-site enabling plus an allowlist/blocklist, and it never auto-injects — it runs only where you ask.
Install
The extension is built from this repository and loaded unpacked. (It is prepared for the Chrome Web Store; a public listing is not yet available, so install it in developer mode.)
npm run build:extension- Open
chrome://extensions. - Enable Developer mode (top-right).
- Click Load unpacked.
- Select
dist/extension/.
npm run build:extension:prod, which emits dist/extension-<version>.zip.
Permissions
The extension requests the minimum it needs and injects only on explicit user action.
| Permission | Why |
|---|---|
storage | Persist your chosen avatar, walk speed, position, site rules, and narration settings (synced across your Chrome devices). |
activeTab | Read the current tab's hostname to label "Enable on this site" and relay your toggle to that tab. |
tabs | Keep the avatar in sync as you navigate, evaluate your site rules, and relay live setting changes to mounted tabs. |
scripting | Inject the avatar into your active tab — only when you turn it on, never automatically. |
host_permissions (<all_urls>) | Because you can enable the avatar on any site you visit. Injection still happens only on tabs you enable. |
host_permissions (three.ws) | Fetch your avatars, featured avatars, and TTS voices, and serve the walking iframe. |
The popup
Click the toolbar icon to open the popup:
- Account — your handle and a sign-in / sign-out control.
- Avatar picker — three tabs: My Avatars (signed in), Featured, and Recent (your last picks). Selecting one sets it as your walker.
- Walk speed — a slider from 0.5× to 2.0×.
- Enable on this site — a toggle that mounts/unmounts the avatar on the current tab, with the domain shown. It's disabled on restricted pages (
chrome://, etc.). - All settings → — opens the full options page.
Settings (options page)
| Setting | Options |
|---|---|
| Default avatar | Choose from My avatars or Featured. |
| Default position | Bottom right / left, top right / left, or follow cursor. |
| Default size | Small, Medium, Large, or custom width × height. |
| Walk speed | 0.5× – 2.0×. |
| Theme | Light, Dark, or Auto (samples the page background). |
| Read page sections aloud | Narration on/off (off by default). |
| Voice | Picked from the three.ws TTS voice list. |
| Allowlist | Domains where the avatar may appear (when set, only these). |
| Blocklist | Domains where it never appears (takes precedence). |
Read-aloud narration
With narration on, the extension parses the page's main article (using a bundled
Readability extractor), pulls out headings, paragraphs, list items, and
blockquotes, and watches which section is in view. When a section becomes the
focus it requests speech audio from the three.ws text-to-speech service and plays
it, while telling the avatar to show a speech bubble and switch to an idle pose.
You choose the voice, can mute mid-read, and narration honours
prefers-reduced-motion. Authors can mark sections with
data-walk-narrate (or skip them with data-walk-narrate="skip").