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
fix(walk): show the real top walkers on /walk instead of an empty board
nirholas5b492a8f93ae
diff --git a/STRUCTURE.md b/STRUCTURE.mdindex dc203dd1a..4fa395f0c 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -17,7 +17,8 @@ bottom.| Web renderer / viewer | [avatar-sdk/](avatar-sdk) `→ /viewer` | Published as `@three-ws/avatar` | `<agent-3d>` web component || Agent shell (companion identity + agentic ⌘K + persistent navigation) | [src/agents/guest-agent.js](src/agents/guest-agent.js), [src/shared/agent-names.js](src/shared/agent-names.js), [src/walk-companion-identity.js](src/walk-companion-identity.js), [public/search.js](public/search.js), [src/view-transitions.js](src/view-transitions.js), [src/shell/page-lifecycle.js](src/shell/page-lifecycle.js) | Live | The agent IS the interface: every visitor gets a named ephemeral agent in the first five seconds (auto-summoned corner companion with an identity chip; “Claim →” prefills /create-agent and POST /api/agents makes it real); the ⌘K palette executes real commands in place (forge → free text→3D lane, digest → clustered news, price → live market data, ask → streamed /api/chat) and announces completions so the companion reacts; pages marked data-shell (`/markets`, `/coins`) navigate by swapping only the main element so the agent and shell never unload (page modules re-init via onPageReady). Docs: [docs/agent-shell.md](docs/agent-shell.md). Tests: [tests/search-commands.test.js](tests/search-commands.test.js), [tests/guest-agent.test.js](tests/guest-agent.test.js), [tests/agent-names.test.js](tests/agent-names.test.js) || Walk companion + playground | [walk-sdk/](walk-sdk) `→ /walk-companion.js` | Published as `@three-ws/walk` | Corner mascot + full-page stroll/platformer playground + diverse avatar picker. App entries: [src/walk-companion.js](src/walk-companion.js), [src/walk-playground.js](src/walk-playground.js) |-| The walkaround world (`/walk`) | [pages/temporary.html](pages/temporary.html) `→ /temporary`, app [src/walk.js](src/walk.js), environments [src/walk-environments.js](src/walk-environments.js) + [public/environments/](public/environments), multiplayer [src/walk-net.js](src/walk-net.js) → `walk_world`, day/night [src/walk-day-night.js](src/walk-day-night.js), radar [src/game/hud/minimap.js](src/game/hud/minimap.js), companions [src/walk-npcs.js](src/walk-npcs.js), agent desks [src/walk-agent-desk.js](src/walk-agent-desk.js) | Live | Walk your avatar through six real staged environments (park, cyberpunk street, beach, gallery, void, office) with physics-driven locomotion on a heightfield, four camera modes, gestures, voice chat, trails, capture, and live peers. **Time of day is real and shared:** the same deterministic world clock `/play` runs on ([src/shared/world-clock.js](src/shared/world-clock.js)) drives the sun arc, sky gradient, light levels, and IBL strength, so two people in the same world always agree on whether it is night. The sky crossfades on a wider curve than the light levels, so dawn and dusk linger instead of flipping. Armed for outdoor stages only (indoor/void keep their authored manifest lighting) and paused while AR passthrough owns the rig. **The radar is `/play`'s:** `/walk` mounts the same rotating GTA-style minimap the world HUD uses, with a compass, the walkable-disc boundary ring, and live blips for peers (their nameplate colours), NPC companions, live agent desks, the guide's named landmarks, and scenery. Click or tap it to set a walk-to waypoint (`Minimap.worldFromScreen()` inverts the rotating projection); `M` or the dock button toggles it and the choice persists. **Frame pacing is shared too:** the loop runs through [src/shared/frame-governor.js](src/shared/frame-governor.js) (60fps focused, 30 unfocused, 30 under power saver) and the controls overlay carries the cross-surface Power-saver switch. Tests: [tests/walk-day-night.test.js](tests/walk-day-night.test.js), [tests/minimap-projection.test.js](tests/minimap-projection.test.js) |+| The walkaround world (`/temporary`) | [pages/temporary.html](pages/temporary.html) `→ /temporary`, app [src/walk.js](src/walk.js), environments [src/walk-environments.js](src/walk-environments.js) + [public/environments/](public/environments), multiplayer [src/walk-net.js](src/walk-net.js) → `walk_world`, day/night [src/walk-day-night.js](src/walk-day-night.js), radar [src/game/hud/minimap.js](src/game/hud/minimap.js), companions [src/walk-npcs.js](src/walk-npcs.js), agent desks [src/walk-agent-desk.js](src/walk-agent-desk.js) | Live | Walk your avatar through six real staged environments (park, cyberpunk street, beach, gallery, void, office) with physics-driven locomotion on a heightfield, four camera modes, gestures, voice chat, trails, capture, and live peers. **Time of day is real and shared:** the same deterministic world clock `/play` runs on ([src/shared/world-clock.js](src/shared/world-clock.js)) drives the sun arc, sky gradient, light levels, and IBL strength, so two people in the same world always agree on whether it is night. The sky crossfades on a wider curve than the light levels, so dawn and dusk linger instead of flipping. Armed for outdoor stages only (indoor/void keep their authored manifest lighting) and paused while AR passthrough owns the rig. **The radar is `/play`'s:** `/temporary` mounts the same rotating GTA-style minimap the world HUD uses, with a compass, the walkable-disc boundary ring, and live blips for peers (their nameplate colours), NPC companions, live agent desks, the guide's named landmarks, and scenery. Click or tap it to set a walk-to waypoint (`Minimap.worldFromScreen()` inverts the rotating projection); `M` or the dock button toggles it and the choice persists. **Frame pacing is shared too:** the loop runs through [src/shared/frame-governor.js](src/shared/frame-governor.js) (60fps focused, 30 unfocused, 30 under power saver) and the controls overlay carries the cross-surface Power-saver switch. Tests: [tests/walk-day-night.test.js](tests/walk-day-night.test.js), [tests/minimap-projection.test.js](tests/minimap-projection.test.js) |+| Walk landing + one-tag embed (`/walk`) | [pages/walk-landing.html](pages/walk-landing.html) `→ /walk`, embed app [pages/walk-embed.html](pages/walk-embed.html) `→ /walk/app` and `→ /walk-embed` ([src/walk-embed.js](src/walk-embed.js)), board [pages/walk-leaderboard.html](pages/walk-leaderboard.html) `→ /walk-leaderboard`, ranking API [api/walk/leaderboard.js](api/walk/leaderboard.js), curated quotes [data/walk-social.json](data/walk-social.json) | Live | The marketing entry for Walk and the surface the `→ /walk` route actually serves (the walkaround world above is at `/temporary`). Live demo embeds across six environments, the copyable one-tag iframe snippet, the Chrome extension pitch, and a top-three teaser off the real all-time distance ranking, which reads `rows` straight from the leaderboard endpoint and falls back to designed empty and retryable error states. The five showcase iframes carry `tabindex="-1"`; the four joystick demos stay keyboard-reachable and get a scripted focus ring, because an iframe whose document holds focus matches no focus pseudo-class. Page copy is mirrored in the `walk_landing` namespace of [public/locales/en.json](public/locales/en.json), which the i18n runtime applies over the served HTML, so the two must be edited together. || Live Docs (runnable code samples) | Pure decisions [public/docs-live-core.js](public/docs-live-core.js), runner [public/docs-live.js](public/docs-live.js), styles [public/docs-live.css](public/docs-live.css), mounted by the docs viewer [docs/index.html](docs/index.html) | Live | Every code sample across the ~318 documentation pages is editable, and the runnable ones execute in place: an `html` snippet containing `<agent-3d>` renders a real animated avatar in a sandboxed frame directly under the code, a single-`curl` `bash` block sends a real request and reports status, latency, size, body and response headers, and a `js` snippet runs as a module with its console streamed back. Slots such as `$API_KEY` or `<agent-id>` become input fields, with credential-shaped names held in memory and never written to storage. The safety split is the design: everything deciding what a reader may fire lives in the pure core and is unit-tested rather than trusted to a click handler. Only three.ws hosts are reachable, any path that can move funds or mint is refused outright on every verb, writes arm before they send, every fetch goes out with `credentials: omit`, and frames run `sandbox="allow-scripts"` without `allow-same-origin`. Authors opt a block out with `<!-- live:off -->`. Loaded lazily after the first page render, so a page with no runnable samples costs nothing. Docs: [docs/live-docs.md](docs/live-docs.md) `→ /docs/live-docs`. Tests: [tests/docs-live-core.test.js](tests/docs-live-core.test.js) || Docs World (immersive 3D docs) | [pages/docs-world.html](pages/docs-world.html) `→ /docs/world`, app [src/docs-world/](src/docs-world) (world/player/controls/overlays), styles [public/docs-world.css](public/docs-world.css), shared manifest [docs/nav.json](docs/nav.json) | Live | The documentation as a walkable place: each section of the docs sidebar is a glowing pavilion on a ring; walk up (WASD / touch joystick, four shared camera modes via [src/game/camera-modes.js](src/game/camera-modes.js)) or tap one to list its pages, and read the live markdown in an in-world DOM reader ([src/shared/markdown.js](src/shared/markdown.js)). One content source: both surfaces read `docs/nav.json` + `/docs/<slug>.md`, so classic and immersive docs cannot drift. Deep links mirror the classic hash routes (`/docs/world#forge`); the classic header's "3D world" button carries the open page across. Avatar is the platform's default rigged body (the same one `/walk` uses, since the agent mannequin ships unskinned and cannot be clip-driven) or any rigged GLB via `?avatar=`, animated by the canonical clip library. No-WebGL devices get a designed fallback routing to `/docs`. Docs: [docs/docs-world.md](docs/docs-world.md). Tests: [tests/docs-world.test.js](tests/docs-world.test.js) || React avatar creator | [avatar-sdk/](avatar-sdk) `→ /react` `/creator` | Published as `@three-ws/avatar` | Same package, React subpath |diff --git a/pages/walk-landing.html b/pages/walk-landing.htmlindex 133372daa..3c6f82b13 100644--- a/pages/walk-landing.html+++ b/pages/walk-landing.html@@ -194,6 +194,17 @@border: 0;background: transparent;}+ /* The joystick demos are drivable from the keyboard, so they keep their+ tab stop. An iframe paints no focus ring of its own, and once focus+ crosses into its document the element matches none of :focus,+ :focus-within or :focus-visible, so the class below is toggled from+ script. The offset is negative because .wl-frame clips its overflow,+ which would swallow a ring drawn outside the iframe's edge. */+ .wl-frame iframe.is-frame-focused,+ .wl-ext-mock-frame iframe.is-frame-focused {+ outline: var(--focus-ring-width) solid var(--focus-ring-color);+ outline-offset: calc(-1 * var(--focus-ring-width));+ }.wl-frame-chrome {display: flex;align-items: center;@@ -707,6 +718,7 @@<iframesrc="/walk-embed?env=void&autoplay=true&controls=none&orbit=false"title="Live demo: a 3D avatar walking in the void environment"+ tabindex="-1"allow="accelerometer; gyroscope"></iframe><span class="wl-frame-hint" data-i18n="walk_landing.live_walking_now">Live · walking now</span>@@ -784,6 +796,7 @@<iframedata-src="/walk-embed?env=studio&autoplay=true&controls=none&orbit=false"title="Step preview: a generated avatar idling in the studio"+ tabindex="-1"loading="lazy"></iframe></div>@@ -798,6 +811,7 @@<iframedata-src="/walk-embed?env=sunset&autoplay=true&controls=none&orbit=false"title="Step preview: an avatar walking at sunset"+ tabindex="-1"loading="lazy"></iframe></div>@@ -812,6 +826,7 @@<iframedata-src="/walk-embed?env=void&autoplay=true&controls=none&orbit=false"title="Step preview: an avatar walking, ready to embed"+ tabindex="-1"loading="lazy"></iframe></div>@@ -878,6 +893,7 @@<iframedata-src="/walk-embed?autoplay=true&controls=none&orbit=false&ground=false"title="A walking avatar overlaid on a web page"+ tabindex="-1"loading="lazy"></iframe></div>@@ -1043,6 +1059,38 @@lazyFrames.forEach((f) => frameIo.observe(f));}+ // ── Keyboard focus ring for the drivable demos ───────────────+ // Focus crossing into an iframe blurs the top window and leaves the+ // element matching no focus pseudo-class, so the ring is applied here+ // instead. Only the joystick demos take focus; the showcase frames+ // carry tabindex="-1" and are skipped.+ const focusableFrames = [...document.querySelectorAll('.wl-frame iframe, .wl-ext-mock-frame iframe')]+ .filter((f) => f.tabIndex > -1);+ const syncFrameFocus = () => {+ for (const f of focusableFrames) {+ f.classList.toggle('is-frame-focused', f === document.activeElement);+ }+ };+ // Window blur announces focus entering a frame, but tabbing from one+ // frame straight to the next never returns focus here, so no event+ // reports it. Watch while focus sits in a frame, and stop as soon as+ // it comes back to the page.+ let framePoll = 0;+ const watchFrameFocus = () => {+ syncFrameFocus();+ if (framePoll) return;+ framePoll = window.setInterval(() => {+ syncFrameFocus();+ if (document.activeElement?.tagName !== 'IFRAME') {+ window.clearInterval(framePoll);+ framePoll = 0;+ }+ }, 100);+ };+ window.addEventListener('blur', watchFrameFocus);+ window.addEventListener('focus', syncFrameFocus);+ document.addEventListener('focusin', syncFrameFocus);+// ── Scroll reveal ────────────────────────────────────────────const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;const reveals = document.querySelectorAll('.wl-reveal');