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
docs(examples): document sign() and playClip(), publish the hosted agent tree, and test the ASL entry point
nirholas8a4d6c321e5a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 387f1fa01..af5d6a2a4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **3D previews now wake up when you look at them**: Second half of the performance sweep. Every rotating 3D preview on the site (the Marketplace grid, the Discover directory, the home page's community strip, the Create page's base-avatar card) used to spin for as long as the tab stayed open, which kept the page busy even when nobody was watching. They now turn when they scroll into view, settle once they have turned far enough to read as 3D, and turn again when you hover or focus them, with no motion at all if your system asks for reduced motion. The Create page's card shows a picture of the base avatar straight away and loads the live, rotatable model when you reach for it, so opening the page no longer waits on a 748 KB download. Forge stops downloading the 3D viewer until you actually generate something. Three things that used to appear late and shove the page down (the site header, the Marketplace hero, the weekly theme strip) now hold their space from the first frame. Coin art in the /play world and Marketplace card art are fetched at the size they are displayed instead of at full resolution. (`/marketplace`) `[improvement, fix]`- **Claim threews.sol Subdomain: a clear account status in every case, a fit on small phones, and the light theme**: The /threews/claim page now tells you where you stand the moment it loads: a loading placeholder while it checks your account, a sign-in prompt if you are signed out, a link to set a username if your account has none, and a plain explanation with a link to change it if your username has characters a .sol name cannot hold (before, that case ended in a bare validation error with nowhere to go). If the account check or the availability check cannot reach three.ws, the page says so and offers a retry instead of going quiet; a failed mint keeps its reason on screen with a retry when the failure was temporary and a link to create an agent when a wallet is what is missing. The .threews.sol suffix no longer spills off the edge on 320px screens, every control has a visible keyboard focus ring, and the page follows the light theme instead of staying black. (`/threews/claim`) `[fix, improvement]`- **Documentation sweep: 164 docs re-checked against the code they describe**: Every doc the freshness gate flagged as describing code that had moved since it was written (174 of them, from the UX flow walkthroughs and the Oracle model write-up to the ops runbooks, tutorials, and the agent-abilities chapters) was re-read against the current code. 164 were corrected or extended: renamed routes now point at /agents/:id, retired model names and provider ladders are current, counts and thresholds match what ships, and the resilience work of the last month (last-good caches, typed 503s with Retry-After, the RPC read guards) is described where it applies. Along the way three things the docs promised were made true in the product: the Herald posting scope can now be minted from the dashboard key form, the translation script defaults to a Groq model that still exists, and the home page OpenAPI link opens the spec directly. (`/docs/freshness`) `[docs, fix]`+- **Examples now show everything an agent can do, not just how to embed one**: The examples page used to be six ways to put a 3D avatar on a page. It is now organised into four lanes covering the whole platform, and every example runs on the page against the live production APIs. Avatars and embeds keeps the inline viewer, the talking agent, the floating support bubble, your own chat UI, and the iframe widget. 3D models adds a free text-to-3D generator that returns a real mesh and renders it in place, a GLB inspector that measures any model against a triangle budget, the full 112-clip animation library playable on any rig, and the live feed of models autonomous agents bought with their own money. Agents adds an agent defined entirely as files, hosted so the manifest loads from any website, and an avatar that performs American Sign Language. Agent economy adds the x402 payment handshake, where a paid endpoint quotes its price, network, and asset without a request spending anything, and the record of coins launched through the platform. Two new methods came out of the work: sign() performs your own text in ASL for captions and accessibility overlays, and playClip() drives the shared animation library on any humanoid rig. A fix landed alongside them: an embedded avatar was painting an invisible block under itself that swallowed clicks on whatever the host page put below it. (`/examples`) `[feature, improvement, docs, fix]`- **Faster pages: the home page stops freezing itself, and every page sheds code it never ran**: A performance sweep of the home page, Create, Forge, Marketplace, Play, Docs, Discover and Chat, measured with Lighthouse and a CPU profiler. The home page's live agent no longer gets torn down by a 22-second timer while it is still loading (the teardown forced a WebGL context loss that froze the tab, and showed a false "couldn't load" message on slow connections), and the playground preview and the visitor-arena animation below the fold now wait until you scroll to them. The theme switcher stopped re-checking the page's light-mode support on every DOM change, which had cost the Marketplace almost nine seconds of main-thread time. The embed script at /agent-3d/latest is 25% smaller: its whitespace minifier was being undone by a later build step. The animation clip library is half its previous size with no visible change (numbers are stored at float precision instead of 17 digits). Web fonts now swap in without moving text, Forge gallery thumbnails load as small WebP tiles instead of full renders, and pages that only show the wallet tier badge no longer download the Solana wallet stack. (`/`) `[improvement, fix, infra]`- **Get Started wizard: avatars come back into the flow, the brain you pick is the brain you get, and sign-in happens at publish time**: The 5-step wizard at /start now finishes what it starts. Taking a selfie, writing a prompt, building in the studio, or using the editor brings the finished avatar straight back into the wizard instead of stranding you on the avatar page, and Upload GLB uses the same storage path as every other upload, so it works. The AI model you choose is now applied to the agent (before, it was collected and dropped), the embed snippet points at the real loader, and a signed-out visitor who reaches the publish step gets a sign-in panel that resumes exactly where they left off rather than a cryptic error. Helper pills no longer sit on top of the Continue button, off-screen steps are no longer tabbable, the price and wallet fields have names for screen readers, and failed price or wallet saves are reported instead of swallowed. (`/start`) `[fix, improvement]`- **Guided Tour page: real track counts, a clean fit on small phones, and a proper fallback when the outline is slow**: The Quick highlights and Full tour cards on /tour now show their real stop counts and minutes (they were being reset to placeholder text a moment after loading), the chapter list matches the tour itself and no longer lists the separate getting-started walkthrough as a chapter, the page no longer clips its right edge on 320px screens, and if the tour outline fails to load you get a clear message with a retry button instead of an empty section. (`/tour`) `[fix, improvement]`diff --git a/STRUCTURE.md b/STRUCTURE.mdindex 974a21a4b..1aeb42bec 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -44,7 +44,7 @@ bottom.| Model detail page (`/m/:id`) | [pages/model.html](pages/model.html) `→ /m/:id`, page module [src/model-page.js](src/model-page.js) + pure helpers [src/model-lib.js](src/model-lib.js) + [src/model.css](src/model.css), backend [api/forge-creation.js](api/forge-creation.js) (`?related=&view=` + voted state; `DELETE`, scoped to the owning `x-forge-client`, lets a creator erase a creation, its stored GLB, preview, and recorded source uploads included) and [api/forge-comments.js](api/forge-comments.js), store reads [api/_lib/forge-store.js](api/_lib/forge-store.js) (`getPublicCreation`/`listRelated`/`recordCreationView`), schema [api/_lib/migrations/20260805120000_model_page.sql](api/_lib/migrations/20260805120000_model_page.sql) | Live | Every finished forge model as a first-class page in the classic model-platform detail layout: interactive viewer hero with AR and fullscreen, title + creator card with a real follow button (follow graph), live triangle/vertex stats from `GET /api/3d/inspect` (nothing persisted, nothing invented), the full prompt as the description, honest attribute chips, anonymous likes shared with the Forge-Off vote rail (`forge_votes`, same `forge:cid` id), a real page-view counter (`forge_creations.view_count`), a signed-in comment thread (`forge_comments`, bell-notifies the creator via the `comment` event type), paid remix via the existing x402 rail, embed/share/download, and a same-category suggested-models rail. Linked from the Details button on `/creations` cards and the Forge showcase. Tests: [tests/model-lib.test.js](tests/model-lib.test.js) || Labs (hidden-gems hub) | [pages/labs.html](pages/labs.html) + [src/labs.js](src/labs.js) `→ /labs` | In-repo | Data-driven discovery hub: renders every `data/pages.json` entry flagged `showcase: true` as a live card (status check + iframe preview), filterable by category || Holo Sticker (procedural foil demo) | [pages/holo.html](pages/holo.html) `→ /holo`, app [src/holo.js](src/holo.js), styles [src/holo.css](src/holo.css) | Live | A real-time holographic foil sticker rendered with physical materials, fully procedural (no assets fetched): tilt it with the pointer, peel the corner (vertex-shader cylinder roll), switch foil styles, die-cut arbitrary typed text via a marching-squares vectorizer, and download the frame as a PNG |-| Examples gallery | [pages/examples.html](pages/examples.html) `→ /examples`, curated snippets [public/examples.js](public/examples.js), generated index renderer [public/examples-index.js](public/examples-index.js), styles [public/examples.css](public/examples.css) | Live | Two halves. The top is six copy-paste snippets that RUN on the page: each is a complete document loading the production CDN bundle into a sandboxed iframe, so "Run" executes exactly the code shown. The bottom is every example that ships in the repo (40 as of 2026-08-05), generated by [scripts/build-examples-index.mjs](scripts/build-examples-index.mjs) scanning every `examples/` directory into [data/examples.json](data/examples.json), mirrored to the served [public/examples.json](public/examples.json) by [scripts/mirror-examples-index.mjs](scripts/mirror-examples-index.mjs) (`npm run build:examples` runs both). Because it is scanned, the page cannot advertise a deleted example or miss an added one; each card carries the files it contains and the command that runs it. Tests: [tests/examples-page.test.js](tests/examples-page.test.js), [tests/examples-index.test.js](tests/examples-index.test.js) |+| Examples gallery | [pages/examples.html](pages/examples.html) `→ /examples`, curated snippets [public/examples.js](public/examples.js), generated index renderer [public/examples-index.js](public/examples-index.js), styles [public/examples.css](public/examples.css), hosted example tree [public/examples/](public/examples) built by [scripts/build-hosted-examples.mjs](scripts/build-hosted-examples.mjs) | Live | Two halves. The top is 14 copy-paste snippets that RUN on the page, grouped into four lanes (avatars and embeds, 3D models, agents, agent economy) behind a sticky jump nav: each is a complete document loading the production CDN bundle into an iframe, so "Run" executes exactly the code shown, and the model/agent/economy lanes call the live CORS-open production APIs rather than illustrating them (free text→3D at `/api/v1/ai/text-to-3d`, `/api/3d/inspect`, the 112-clip `/animations/manifest.json`, `/api/forged`, the 402 quote from `/api/x402/forge`, `/api/pump/launches`). The `agent-from-files` card loads a real manifest from `/examples/coach-leo/manifest.json`: `npm run build:examples` publishes [examples/coach-leo/](examples/coach-leo) and its wave skill into `public/examples/` with body/image URIs rewritten absolute, so the manifest resolves the same way off-site as it does here. The bottom is every example that ships in the repo, generated by [scripts/build-examples-index.mjs](scripts/build-examples-index.mjs) scanning every `examples/` directory into [data/examples.json](data/examples.json), mirrored to the served [public/examples.json](public/examples.json) by [scripts/mirror-examples-index.mjs](scripts/mirror-examples-index.mjs) (`npm run build:examples` runs all three). Because it is scanned, the page cannot advertise a deleted example or miss an added one; each card carries the files it contains and the command that runs it. Tests: [tests/examples-page.test.js](tests/examples-page.test.js), [tests/examples-index.test.js](tests/examples-index.test.js) || Cookbook (runnable recipes) | Index [pages/cookbook.html](pages/cookbook.html) `-> /cookbook`, recipe viewer [pages/recipe.html](pages/recipe.html) `-> /cookbook/<slug>`, manifest [public/cookbook-manifest.js](public/cookbook-manifest.js), styles [public/cookbook.css](public/cookbook.css), recipe prose [docs/cookbook/](docs/cookbook), runnable files [public/cookbook/recipes/](public/cookbook/recipes), notebook export [public/cookbook/self-correcting-3d/](public/cookbook/self-correcting-3d) | Live | The sibling of the Examples gallery, and deliberately a different thing: an example is a snippet you read on the page, a recipe is a file you download and run. Five recipes, each one executed against the live API before it was published: a standard-library text-to-3D CLI, a parallel asset-pack builder that emits a manifest plus a gallery, an MCP server that hands Claude Code or Cursor a 3D tool, a CI budget gate over [api/3d/inspect.js](api/3d/inspect.js), and the function-calling-plus-vision notebook also submitted to the OpenAI Cookbook. The manifest is the single source of truth for both surfaces; recipe prose is markdown under `docs/cookbook/` fetched by the viewer, so adding a recipe is a manifest entry plus a `.md` plus the file itself. Route order is load-bearing in both [vercel.json](vercel.json) and the dev middleware: the notebook's static export must be matched before the generic `/cookbook/<slug>` rule or the viewer shadows it. Docs: [public/cookbook/recipes/README.md](public/cookbook/recipes/README.md). Tests: [tests/cookbook.test.js](tests/cookbook.test.js) || Walkthroughs (interactive product tours from real frames) | Index [pages/walkthroughs.html](pages/walkthroughs.html) + [src/walkthroughs-index.js](src/walkthroughs-index.js) `→ /walkthroughs`, player [pages/walkthrough.html](pages/walkthrough.html) + [src/walkthrough.js](src/walkthrough.js) `→ /walkthroughs/<slug>` (routed in [vercel.json](vercel.json), mirrored by the Vite dev middleware in [vite.config.js](vite.config.js)), pure step geometry [src/walkthrough-geometry.js](src/walkthrough-geometry.js), generated manifest + screenshot sets [public/walkthroughs/](public/walkthroughs) captured by [scripts/capture-walkthroughs.mjs](scripts/capture-walkthroughs.mjs) | Live | Step-by-step guided tours (forge a 3D model, build an agent, embed an avatar, find an agent worth using) built from real frames captured on the live product: each step zooms and pans to the element it describes, cuts a spotlight around it, and anchors a callout, so it reads like a screen recording but is a handful of deep-linkable, keyboard-operable JPEGs that degrade to annotated stills under reduced motion. Index and player read the same generated manifest, so a walkthrough that did not capture cleanly cannot be advertised. Registered in [data/pages.json](data/pages.json). || Cross-entity search | [pages/search.html](pages/search.html) `→ /search`, backend [api/search.js](api/search.js) + query layer [api/_lib/cross-search.js](api/_lib/cross-search.js) | Live | The one search across every creation type — avatars, on-chain/Solana agents, forged 3D models, worlds, and coins. Federates (not one SQL UNION — the stores are genuinely heterogeneous, two of five aren't even in the same database) five parallel queries, normalizes into one card shape, and ranks by recency plus real signals (follower count via `user_follows`, remix count, view count) — see the file header in `api/search.js` for the full unify-vs-federate writeup. Model results carry a working "Remix — $0.25" action against the existing paid rail ([api/x402/remix-asset.js](api/x402/remix-asset.js)), reused from [pages/creations.html](pages/creations.html) rather than re-derived. Coin search checks three.ws's own launch directory (`pump_agent_mints`) first, then falls back to market-wide pump.fun/Birdeye search for broader coverage (those external matches carry no verified timestamp or creator profile, and are ranked/labelled accordingly). Linked from the Discover nav menu. |diff --git a/data/changelog.json b/data/changelog.jsonindex 07ef11bf5..772df63ff 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -25568,6 +25568,18 @@"fix"],"link": "/marketplace"+ },+ {+ "date": "2026-09-01",+ "title": "Examples now show everything an agent can do, not just how to embed one",+ "summary": "The examples page used to be six ways to put a 3D avatar on a page. It is now organised into four lanes covering the whole platform, and every example runs on the page against the live production APIs. Avatars and embeds keeps the inline viewer, the talking agent, the floating support bubble, your own chat UI, and the iframe widget. 3D models adds a free text-to-3D generator that returns a real mesh and renders it in place, a GLB inspector that measures any model against a triangle budget, the full 112-clip animation library playable on any rig, and the live feed of models autonomous agents bought with their own money. Agents adds an agent defined entirely as files, hosted so the manifest loads from any website, and an avatar that performs American Sign Language. Agent economy adds the x402 payment handshake, where a paid endpoint quotes its price, network, and asset without a request spending anything, and the record of coins launched through the platform. Two new methods came out of the work: sign() performs your own text in ASL for captions and accessibility overlays, and playClip() drives the shared animation library on any humanoid rig. A fix landed alongside them: an embedded avatar was painting an invisible block under itself that swallowed clicks on whatever the host page put below it.",+ "tags": [+ "feature",+ "improvement",+ "docs",+ "fix"+ ],+ "link": "/examples"}]}diff --git a/docs/web-component.md b/docs/web-component.mdindex 8d61d321d..e63b27687 100644--- a/docs/web-component.md+++ b/docs/web-component.md@@ -242,6 +242,45 @@ await el.play('dance', { loop: true });---+### `playClip(name, opts?)`++Plays a clip from the platform's shared animation library, retargeted onto whatever skeleton the loaded GLB carries. Unlike `play()`, which needs a clip that already exists inside the GLB, this resolves names from the public clip manifest at [`/animations/manifest.json`](https://three.ws/animations/manifest.json), so the same call works on a Mixamo rig, a VRM, a body scan, or a mesh you generated a minute ago.++```js+const clips = await (await fetch('https://three.ws/animations/manifest.json')).json();+el.playClip(clips[0].name, { userInitiated: true });+```++| Parameter | Type | Description |+|-----------|------|-------------|+| `name` | string | Clip name from the manifest, e.g. `idle`, `facepalm`, `av-idle-breath`. |+| `opts.fade_ms` | number | Cross-fade into the clip, in milliseconds. Defaults to `400`. |+| `opts.userInitiated` | boolean | Play even when the visitor has `prefers-reduced-motion` set. Pass `true` only when a real user gesture asked for the motion; ambient autoplay stays suppressed. |++The method honors each clip's own `loop` flag: looping clips loop, one-shot clips play once and settle back into idle without a snap at the boundary.++---++### `sign(text)`++Performs `text` in American Sign Language on the avatar without sending it to a brain. Words in the lexicon are signed, everything else fingerspells, in one continuous motion. Turns the engine on if the `sign-language` attribute has not already.++```js+const result = await el.sign('happy to meet you');+if (result) {+ console.log(result.signed); // words that came from the lexicon+ console.log(result.spelled); // words that fingerspelled+}+```++| Parameter | Type | Description |+|-----------|------|-------------|+| `text` | string | The utterance to perform. |++Resolves once the motion finishes, with `{ signed, spelled }`, or with `null` when the loaded rig has no finger bones to sign with. Use it for captions, accessibility overlays, and any surface that has its own text; the `sign-language` attribute covers the conversational case, where every assistant reply is signed automatically.++---+### `speak(text, opts?)`Triggers a speak animation on the avatar (lip-sync / talking gesture) without sending the text to the LLM. Use this to drive the avatar from your own logic.diff --git a/package.json b/package.jsonindex ae323cd63..37b740d9b 100644--- a/package.json+++ b/package.json@@ -149,7 +149,7 @@"demo:agent-wallet-bridge": "node scripts/agent-wallet-x402-bridge.mjs","dev:lib": "TARGET=lib vite","presence": "node scripts/three-ws-presence.mjs",- "build:examples": "node scripts/build-examples-index.mjs && node scripts/mirror-examples-index.mjs",+ "build:examples": "node scripts/build-examples-index.mjs && node scripts/mirror-examples-index.mjs && node scripts/build-hosted-examples.mjs","build:docs-search": "node scripts/build-docs-search-index.mjs","check:docs-search": "node scripts/build-docs-search-index.mjs --check","build:pages": "node scripts/build-page-index.mjs",diff --git a/public/changelog.json b/public/changelog.jsonindex a56c7550b..ca67158da 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-09-01T18:06:48.112Z",+ "generated_at": "2026-09-01T18:36:39.158Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -109,6 +109,19 @@"fix"]},+ {+ "date": "2026-09-01",+ "type": "update",+ "title": "Examples now show everything an agent can do, not just how to embed one",+ "summary": "The examples page used to be six ways to put a 3D avatar on a page. It is now organised into four lanes covering the whole platform, and every example runs on the page against the live production APIs. Avatars and embeds keeps the inline viewer, the talking agent, the floating support bubble, your own chat UI, and the iframe widget. 3D models adds a free text-to-3D generator that returns a real mesh and renders it in place, a GLB inspector that measures any model against a triangle budget, the full 112-clip animation library playable on any rig, and the live feed of models autonomous agents bought with their own money. Agents adds an agent defined entirely as files, hosted so the manifest loads from any website, and an avatar that performs American Sign Language. Agent economy adds the x402 payment handshake, where a paid endpoint quotes its price, network, and asset without a request spending anything, and the record of coins launched through the platform. Two new methods came out of the work: sign() performs your own text in ASL for captions and accessibility overlays, and playClip() drives the shared animation library on any humanoid rig. A fix landed alongside them: an embedded avatar was painting an invisible block under itself that swallowed clicks on whatever the host page put below it.",+ "link": "/examples",+ "tags": [+ "feature",+ "improvement",+ "docs",+ "fix"+ ]+ },{"date": "2026-09-01","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex 8cee7996c..c2421d7b0 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -86,6 +86,14 @@<category>docs</category><description>Every doc the freshness gate flagged as describing code that had moved since it was written (174 of them, from the UX flow walkthroughs and the Oracle model write-up to the ops runbooks, tutorials, and the agent-abilities chapters) was re-read against the current code. 164 were corrected or extended: renamed routes now point at /agents/:id, retired model names and provider ladders are current, counts and thresholds match what ships, and the resilience work of the last month (last-good caches, typed 503s with Retry-After, the RPC read guards) is described where it applies. Along the way three things the docs promised were made true in the product: the Herald posting scope can now be minted from the dashboard key form, the translation script defaults to a Groq model that still exists, and the home page OpenAPI link opens the spec directly.</description></item>+ <item>+ <title>Examples now show everything an agent can do, not just how to embed one</title>+ <link>https://three.ws/examples</link>+ <guid isPermaLink="false">2026-09-01:Examples now show everything an agent can do, not just how to embed one</guid>+ <pubDate>Tue, 01 Sep 2026 12:00:00 GMT</pubDate>+ <category>feature</category>+ <description>The examples page used to be six ways to put a 3D avatar on a page. It is now organised into four lanes covering the whole platform, and every example runs on the page against the live production APIs. Avatars and embeds keeps the inline viewer, the talking agent, the floating support bubble, your own chat UI, and the iframe widget. 3D models adds a free text-to-3D generator that returns a real mesh and renders it in place, a GLB inspector that measures any model against a triangle budget, the full 112-clip animation library playable on any rig, and the live feed of models autonomous agents bought with their own money. Agents adds an agent defined entirely as files, hosted so the manifest loads from any website, and an avatar that performs American Sign Language. Agent economy adds the x402 payment handshake, where a paid endpoint quotes its price, network, and asset without a request spending anything, and the record of coins launched through the platform. Two new methods came out of the work: sign() performs your own text in ASL for captions and accessibility overlays, and playClip() drives the shared animation library on any humanoid rig. A fix landed alongside them: an embedded avatar was painting an invisible block under itself that swallowed clicks on whatever the host page put below it.</description>+ </item><item><title>Faster pages: the home page stops freezing itself, and every page sheds code it never ran</title><link>https://three.ws/</link>diff --git a/public/examples.js b/public/examples.jsindex ffd1fa922..b6b0c224b 100644--- a/public/examples.js+++ b/public/examples.js@@ -370,7 +370,7 @@ const EXAMPLES = [id: 'animation-library',lane: 'models',title: 'The whole animation library, on any rig',- blurb: 'The clip manifest is public. Fetch it, build a control for every clip, and play them on a loaded avatar. Clips are retargeted onto whatever skeleton the GLB carries, so the same library drives a Mixamo rig, a VRM, an Avaturn scan, or a mesh you generated a minute ago.',+ blurb: 'The clip manifest is public. Fetch it, build a control for every clip, and play them on a loaded avatar. Clips are retargeted onto whatever skeleton the GLB carries, so the same library drives a Mixamo rig, a VRM, a body scan, or a mesh you generated a minute ago.',tags: ['animation', 'api'],docs: [{ label: 'Web component API', href: '/docs/web-component' },@@ -690,12 +690,16 @@ const EXAMPLES = [async function sign() {report.textContent = 'Compiling the utterance...';- // sign() performs text you supply: no brain, no round trip.- var result = await signer.sign(phrase.value);- report.textContent = result- ? 'signed: ' + (result.signed.join(', ') || 'none') +- ' · fingerspelled: ' + (result.spelled.join(', ') || 'none')- : 'This rig has no finger bones, so it will not sign.';+ try {+ // sign() performs text you supply: no brain, no round trip.+ var result = await signer.sign(phrase.value);+ report.textContent = result+ ? 'signed: ' + (result.signed.join(', ') || 'none') ++ ' · fingerspelled: ' + (result.spelled.join(', ') || 'none')+ : 'This rig has no finger bones, so it will not sign.';+ } catch (err) {+ report.textContent = 'Could not sign that: ' + err.message;+ }}document.getElementById('go').addEventListener('click', sign);diff --git a/public/features.json b/public/features.jsonindex 6092e5650..d79974a2e 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-09-01T18:06:48.084Z",+ "generated_at": "2026-09-01T18:36:39.145Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",diff --git a/tests/agent-avatar-sign.test.js b/tests/agent-avatar-sign.test.jsnew file mode 100644index 000000000..fbe783a42--- /dev/null+++ b/tests/agent-avatar-sign.test.js@@ -0,0 +1,111 @@+/**+ * AgentAvatar.sign(): performing caller-supplied text in ASL.+ *+ * tests/sign-speech.test.js pins the engine (text in, one clip out) and+ * tests/sign-rig.test.js pins the rig requirements. This file pins the half+ * neither can see: the public entry point an embed calls when it has its own+ * text (a caption track, an accessibility overlay) rather than an assistant+ * reply to sign.+ *+ * The two failures worth guarding are the ones the conversational path already+ * had answers for and a direct call could easily lose: signing without the+ * attribute having been set first (the caller should not have to enable the+ * engine by hand), and a rig with no finger bones, which must decline rather+ * than perform something wrong.+ */++import { describe, it, expect, beforeEach, vi } from 'vitest';++let AgentAvatar;++function makeRoot() {+ return {+ isObject3D: true,+ children: [],+ traverse(fn) {+ fn(this);+ },+ };+}++/**+ * The manager shape SignSpeaker drives: it injects a compiled clip and plays it+ * once. `canonical` is what supportsCanonicalClips() reports, i.e. whether the+ * loaded rig has the canonical skeleton the signing poses are authored against.+ */+function makeAnimationManager({ canonical = true } = {}) {+ const injected = [];+ const played = [];+ return {+ currentName: null,+ isLoaded: () => false,+ getAnimationDefs: () => [],+ play: () => Promise.resolve(true),+ crossfadeTo: () => {},+ supportsCanonicalClips: () => canonical,+ injectClip: (name, clip, opts) => injected.push({ name, clip, opts }),+ playOnce: (name, opts) => played.push({ name, opts }),+ injected,+ played,+ };+}++function makeAvatar(am) {+ return new AgentAvatar(+ { content: makeRoot(), animationManager: am, state: {} },+ {},+ {+ id: 'test',+ },+ );+}++beforeEach(async () => {+ vi.useRealTimers();+ if (!AgentAvatar) ({ AgentAvatar } = await import('../src/agent-avatar.js'));+});++describe('AgentAvatar.sign', () => {+ it('enables the engine on first use and performs the text', async () => {+ const am = makeAnimationManager();+ const avatar = makeAvatar(am);++ // No setSignLanguage(true) first: a caller with its own text should not+ // have to turn the engine on by hand.+ const result = await avatar.sign('hello friend');++ expect(result).toBeTruthy();+ expect(result.signed).toContain('HELLO');+ expect(am.injected).toHaveLength(1);+ expect(am.injected[0].clip.duration).toBeGreaterThan(0);+ expect(am.played).toHaveLength(1);+ expect(am.played[0].name).toBe(am.injected[0].name);+ }, 20000);++ it('reports which words were signed and which fingerspelled', async () => {+ const am = makeAnimationManager();+ const avatar = makeAvatar(am);++ const result = await avatar.sign('hello zqxj');++ expect(result.signed).toContain('HELLO');+ expect(result.spelled).toContain('ZQXJ');+ }, 20000);++ it('declines on a rig that cannot sign instead of performing something wrong', async () => {+ const am = makeAnimationManager({ canonical: false });+ const avatar = makeAvatar(am);++ expect(await avatar.sign('hello friend')).toBe(null);+ expect(am.injected).toHaveLength(0);+ expect(avatar.signLanguage).toBe(false);+ });++ it('ignores empty text without touching the rig', async () => {+ const am = makeAnimationManager();+ const avatar = makeAvatar(am);++ expect(await avatar.sign('')).toBe(null);+ expect(am.injected).toHaveLength(0);+ });+});