Skip to content

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.

feat(agent-3d): match model-viewer's AR/variant/hotspot contract, drop the third-party CDN on /ar

nirholasa9c1e60323f4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9cef05356..2e973b604 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **Docs · Engine bridges** (`/docs/engine-bridges`): One Forge API contract, three real editor integrations: a Unity UPM package, a Godot addon, and an Unreal plugin, each generating a mesh from a prompt and importing it with the engine's own native glTF pipeline.
- **Docs · Engine QA** (`/docs/engine-qa`): A free real-time-engine fitness grade for any 3D model: draw calls, material count, texel density, a per-level LOD triangle budget, and whether the mesh is cheap and closed enough to use as its own physics collider.
+- **<agent-3d> gets model-viewer's AR contract: ar-modes, variants, hotspots, and /ar drops the third-party CDN**: <agent-3d> now matches the AR/viewer contract the market expects from model-viewer (Apache-2.0): ar-modes picks which launch paths to try (WebXR, Scene Viewer, Quick Look), ar-placement anchors floor or wall, ios-src supplies a pre-baked USDZ or the element generates a best-effort one on device, variant-name switches a GLB's real KHR_materials_variants materials live, and any element with slot="hotspot" tracks a 3D position and flies the camera to a saved orbit on click. /avatars/:id/ar and /agents/:id/ar (pages/ar.html) now run entirely on <agent-3d ar>; the page no longer loads a third-party viewer from a CDN. (`/avatars`) `[feature]`
- **Engine QA: a free real-time-engine fitness grade, plus real LOD chains**: A new free grade answers the question a game engine's import step asks that neither glTF validation nor simulation readiness does: draw calls, material count, texel density against the mesh's real-world size, a per-level triangle budget for a LOD chain, and whether the mesh is cheap and closed enough to use as its own physics collider. GET/POST /api/3d/engine-qa grades any public GLB (format=stl exports a watertight mesh for printing); the same browser-only checks run with zero network cost in Rig Doctor, and the full grade with a one-click upgrade in the GLB viewer, through a shared <engine-qa> panel component. The underlying LOD builder (packages/glb-tools's buildLodChain, real meshoptimizer decimation tagged with MSFT_lod) is now also available on generation: send { "lods": true } to POST /api/forge and the finished creation gets a combined LOD-chain variant alongside its delivered mesh, the same opt-in, fire-and-forget pattern as the existing web-delivery variant. (`/docs/engine-qa`) `[feature]`
- **Three new engine bridges: Unity, Godot, and Unreal, one prompt to a mesh in your editor**: A shared contract (specs/ENGINE_BRIDGE.md) and three real, independent implementations: a Unity UPM package that imports with glTFast, a Godot addon that imports with Godot's own native GLTFDocument, and an Unreal plugin that imports through Unreal's Interchange glTF pipeline. Each one calls only the public Forge API (POST /api/forge to submit, GET /api/forge?job=<id> to poll, a plain HTTPS GET to download), the same free-first routing and anonymous x-forge-client auth every other Forge caller gets, with the same four import settings (generate_colliders, import_materials, scale, destination) mapped onto each engine's own equivalent. A dropdown and a Generate button in each editor: type a prompt, get a mesh dropped into your scene. (`/docs/engine-bridges`) `[feature, sdk]`
diff --git a/data/changelog.json b/data/changelog.json
index 87850c325..67f60db0b 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,15 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-12",
+ "title": "<agent-3d> gets model-viewer's AR contract: ar-modes, variants, hotspots, and /ar drops the third-party CDN",
+ "link": "/avatars",
+ "summary": "<agent-3d> now matches the AR/viewer contract the market expects from model-viewer (Apache-2.0): ar-modes picks which launch paths to try (WebXR, Scene Viewer, Quick Look), ar-placement anchors floor or wall, ios-src supplies a pre-baked USDZ or the element generates a best-effort one on device, variant-name switches a GLB's real KHR_materials_variants materials live, and any element with slot=\"hotspot\" tracks a 3D position and flies the camera to a saved orbit on click. /avatars/:id/ar and /agents/:id/ar (pages/ar.html) now run entirely on <agent-3d ar>; the page no longer loads a third-party viewer from a CDN.",
+ "tags": [
+ "feature"
+ ]
+ },
{
"date": "2026-10-12",
"title": "Three new engine bridges: Unity, Godot, and Unreal, one prompt to a mesh in your editor",
diff --git a/pages/ar.html b/pages/ar.html
index cc7e415bf..b09a21243 100644
--- a/pages/ar.html
+++ b/pages/ar.html
@@ -32,12 +32,10 @@
<meta name="twitter:description" content="Type a prompt, get a real 3D model, and place it in your room: free text-to-3D with one-tap AR on any phone." data-i18n-attr="content:ar.meta_twitter_description" />
<meta name="twitter:image" content="https://three.ws/api/page-og?s=labs&amp;t=AR+Forge&amp;d=Type+a+prompt%2C+get+a+real+3D+model%2C+and+place+it+in+your+room%3A+free+text-to-3D+with+one-tap+AR+on+any+phone+%28WebXR%2C+Scene+Viewer%2C+Quick+Look%29+and+a+QR+handoff.&amp;p=%2Far" />
- <script
- type="module"
- src="https://cdn.jsdelivr.net/npm/@google/[email protected]/dist/model-viewer.min.js"
- integrity="sha384-wjsPzEO+lXOf7d9csIDfAQpPt2OKuUU3m0K9qsdKIuzX4N8czSF6hdh23eAbZa3p"
- crossorigin="anonymous"
- ></script>
+ <!-- Absolute, and it has to stay absolute: dist/agent-3d/ is written by
+ `npm run publish:lib` after the frontend build, so a root-relative
+ module src fails the build (see pages/home.html for the same note). -->
+ <script type="module" src="https://three.ws/agent-3d/latest/agent-3d.js"></script>
<script type="module" src="/src/ar-page.js"></script>
<style>
@@ -220,15 +218,14 @@
}
/* ── Model viewer ────────────────────────────── */
- model-viewer {
+ agent-3d#ar-viewer {
position: absolute;
inset: 0;
width: 100%;
height: 100%;
- --poster-color: transparent;
background: transparent;
}
- model-viewer::part(default-ar-button) {
+ agent-3d#ar-viewer::part(ar-button) {
display: none; /* we use our own button */
}
@@ -496,29 +493,12 @@
color: var(--on-accent);
}
</style>
- <script src="/model-viewer-meshopt.js"></script>
</head>
<body>
<div class="ar-bg" aria-hidden="true"></div>
<div id="ar-shell">
- <model-viewer
- id="ar-viewer"
- alt="Avatar"
- camera-controls
- auto-rotate
- rotation-per-second="12deg"
- interaction-prompt="none"
- exposure="1.1"
- shadow-intensity="0.8"
- shadow-softness="0.9"
- environment-image="neutral"
- tone-mapping="aces"
- ar
- ar-modes="webxr scene-viewer quick-look"
- ar-scale="auto"
- reveal="auto"
- ></model-viewer>
+ <agent-3d id="ar-viewer" eager ar ar-modes="webxr scene-viewer quick-look" ar-placement="floor"></agent-3d>
<header class="ar-topbar">
<a class="ar-back" id="ar-back-link" href="/marketplace">
diff --git a/public/agent-3d-ar-harness.html b/public/agent-3d-ar-harness.html
new file mode 100644
index 000000000..adfb2c474
--- /dev/null
+++ b/public/agent-3d-ar-harness.html
@@ -0,0 +1,27 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>agent-3d AR/variant/hotspot test harness</title>
+<!--
+ Playwright-only fixture for tests/e2e/agent-3d-ar.spec.js. Imports
+ /src/element.js directly so the spec exercises today's source instead of
+ the published https://three.ws/agent-3d/latest/agent-3d.js bundle that
+ every real page loads (that bundle only picks up source changes after a
+ deploy). Not linked from any nav; mirrors the existing
+ public/studio-deposit-harness.html convention.
+-->
+<style>html,body{margin:0;height:100%}agent-3d{display:block;width:480px;height:480px}</style>
+</head>
+<body>
+<agent-3d
+ id="a3d"
+ eager
+ src="/agent-3d-ar-harness-variants.glb"
+ ar
+ ar-modes="quick-look"
+ ios-src="/agent-3d-ar-harness-placeholder.usdz"
+><button slot="hotspot" id="hs" data-position="0 1 0" data-camera-orbit="30 70 2.5"></button></agent-3d>
+<script type="module" src="/src/element.js"></script>
+</body>
+</html>
diff --git a/public/changelog-recent.json b/public/changelog-recent.json
index 5c6ce9a06..1914fcfc5 100644
--- a/public/changelog-recent.json
+++ b/public/changelog-recent.json
@@ -1,11 +1,11 @@
{
- "generated_at": "2026-10-12T01:09:39.541Z",
+ "generated_at": "2026-10-12T02:18:07.365Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
- "total": 4038,
+ "total": 4039,
"complete": false,
"full_feed": "/changelog.json",
"entries": [
@@ -39,6 +39,16 @@
"launch"
]
},
+ {
+ "date": "2026-10-12",
+ "type": "update",
+ "title": "<agent-3d> gets model-viewer's AR contract: ar-modes, variants, hotspots, and /ar drops the third-party CDN",
+ "summary": "<agent-3d> now matches the AR/viewer contract the market expects from model-viewer (Apache-2.0): ar-modes picks which launch paths to try (WebXR, Scene Viewer, Quick Look), ar-placement anchors floor or wall, ios-src supplies a pre-baked USDZ or the element generates a best-effort one on device, variant-name switches a GLB's real KHR_materials_variants materials live, and any element with slot=\"hotspot\" tracks a 3D position and flies the camera to a saved orbit on click. /avatars/:id/ar and /agents/:id/ar (pages/ar.html) now run entirely on <agent-3d ar>; the page no longer loads a third-party viewer from a CDN.",
+ "link": "/avatars",
+ "tags": [
+ "feature"
+ ]
+ },
{
"date": "2026-10-12",
"type": "update",
@@ -1532,16 +1542,6 @@
"tags": [
"launch"
]
- },
- {
- "date": "2026-10-09",
- "type": "update",
- "title": "A build plan for the next 27 platform upgrades",
- "summary": "We surveyed the strongest open-source crypto and agent projects, compared them with three.ws, and wrote the plan for closing every gap: agents that learn skills from experience, a payer command line, on-chain spending budgets, more trading venues, safer chat trading and more.",
- "link": null,
- "tags": [
- "docs"
- ]
}
]
}
diff --git a/public/changelog.json b/public/changelog.json
index 62b0b0820..84f3e02d7 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-12T01:09:39.498Z",
+ "generated_at": "2026-10-12T02:18:07.341Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -36,6 +36,16 @@
"launch"
]
},
+ {
+ "date": "2026-10-12",
+ "type": "update",
+ "title": "<agent-3d> gets model-viewer's AR contract: ar-modes, variants, hotspots, and /ar drops the third-party CDN",
+ "summary": "<agent-3d> now matches the AR/viewer contract the market expects from model-viewer (Apache-2.0): ar-modes picks which launch paths to try (WebXR, Scene Viewer, Quick Look), ar-placement anchors floor or wall, ios-src supplies a pre-baked USDZ or the element generates a best-effort one on device, variant-name switches a GLB's real KHR_materials_variants materials live, and any element with slot=\"hotspot\" tracks a 3D position and flies the camera to a saved orbit on click. /avatars/:id/ar and /agents/:id/ar (pages/ar.html) now run entirely on <agent-3d ar>; the page no longer loads a third-party viewer from a CDN.",
+ "link": "/avatars",
+ "tags": [
+ "feature"
+ ]
+ },
{
"date": "2026-10-12",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index c301e4e8c..7be5acefa 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -30,6 +30,14 @@
<category>launch</category>
<description>A free real-time-engine fitness grade for any 3D model: draw calls, material count, texel density, a per-level LOD triangle budget, and whether the mesh is cheap and closed enough to use as its own physics collider.</description>
</item>
+ <item>
+ <title>&lt;agent-3d&gt; gets model-viewer's AR contract: ar-modes, variants, hotspots, and /ar drops the third-party CDN</title>
+ <link>https://three.ws/avatars</link>
+ <guid isPermaLink="false">2026-10-12:&lt;agent-3d&gt; gets model-viewer's AR contract: ar-modes, variants, hotspots, and /ar drops the third-party CDN</guid>
+ <pubDate>Mon, 12 Oct 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>&lt;agent-3d&gt; now matches the AR/viewer contract the market expects from model-viewer (Apache-2.0): ar-modes picks which launch paths to try (WebXR, Scene Viewer, Quick Look), ar-placement anchors floor or wall, ios-src supplies a pre-baked USDZ or the element generates a best-effort one on device, variant-name switches a GLB's real KHR_materials_variants materials live, and any element with slot=&quot;hotspot&quot; tracks a 3D position and flies the camera to a saved orbit on click. /avatars/:id/ar and /agents/:id/ar (pages/ar.html) now run entirely on &lt;agent-3d ar&gt;; the page no longer loads a third-party viewer from a CDN.</description>
+ </item>
<item>
<title>Engine QA: a free real-time-engine fitness grade, plus real LOD chains</title>
<link>https://three.ws/docs/engine-qa</link>
diff --git a/public/features.json b/public/features.json
index aa4ff4030..28b0ffc76 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-12T01:09:39.462Z",
+ "generated_at": "2026-10-12T02:18:07.327Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
diff --git a/public/sitemap/index.html b/public/sitemap/index.html
index 7f2f909f6..d099fb056 100644
--- a/public/sitemap/index.html
+++ b/public/sitemap/index.html
@@ -3,16 +3,16 @@
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
-<title>Sitemap · three.ws</title>
-<meta name="description" content="Human-readable index of every page on three.ws." />
+<title data-i18n="sitemap_index.meta_title">Sitemap · three.ws</title>
+<meta name="description" content="Human-readable index of every page on three.ws." data-i18n-attr="content:sitemap_index.meta_description"/>
<meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1" />
<link rel="canonical" href="https://three.ws/sitemap" />
<meta property="og:type" content="website" />
<meta property="og:site_name" content="three.ws" />
<meta property="og:locale" content="en_US" />
<meta property="og:url" content="https://three.ws/sitemap" />
-<meta property="og:title" content="Sitemap · three.ws" />
-<meta property="og:description" content="Human-readable index of every page on three.ws." />
+<meta property="og:title" content="Sitemap · three.ws" data-i18n-attr="content:sitemap_index.meta_og_title"/>
+<meta property="og:description" content="Human-readable index of every page on three.ws." data-i18n-attr="content:sitemap_index.meta_og_description"/>
<meta property="og:image" content="https://three.ws/api/page-og?s=main&amp;t=Sitemap&amp;d=Human-readable+index+of+every+page+on+three.ws.&amp;p=%2Fsitemap" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
@@ -20,8 +20,8 @@
<meta property="og:image:alt" content="Sitemap - three.ws" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site" content="@trythreews" />
-<meta name="twitter:title" content="Sitemap · three.ws" />
-<meta name="twitter:description" content="Human-readable index of every page on three.ws." />
+<meta name="twitter:title" content="Sitemap · three.ws" data-i18n-attr="content:sitemap_index.meta_twitter_title"/>
+<meta name="twitter:description" content="Human-readable index of every page on three.ws." data-i18n-attr="content:sitemap_index.meta_twitter_description"/>
<meta name="twitter:image" content="https://three.ws/api/page-og?s=main&amp;t=Sitemap&amp;d=Human-readable+index+of+every+page+on+three.ws.&amp;p=%2Fsitemap" />
<script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"WebPage","name":"Sitemap","description":"Human-readable index of every page on three.ws.","url":"https://three.ws/sitemap","isPartOf":{"@type":"WebSite","name":"three.ws","url":"https://three.ws"},"primaryImageOfPage":"https://three.ws/api/page-og?s=main&t=Sitemap&d=Human-readable+index+of+every+page+on+three.ws.&p=%2Fsitemap"}]}</script>
<link rel="alternate" type="application/xml" title="XML sitemap" href="/sitemap.xml" />
@@ -95,16 +95,16 @@
<header><div id="nav-container"></div></header>
<main class="sm-wrap">
<div class="sm-hero">
- <h1>Sitemap</h1>
+ <h1 data-i18n="sitemap_index.sitemap">Sitemap</h1>
<p><span>1061</span> <span data-i18n="sitemap_index.pages_grouped">pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</span></p>
<div class="sm-formats">
- <a href="/everything"><code>/everything</code> · browse by goal, not by section</a>
- <a href="/sitemap.xml"><code>sitemap.xml</code> · for search engines</a>
- <a href="/llms.txt"><code>llms.txt</code> · for AI agents</a>
- <a href="/llms-full.txt"><code>llms-full.txt</code> · long form</a>
- <a href="/api/features.json"><code>features.json</code> · machine manifest</a>
- <a href="/changelog"><code>changelog</code> · what's new</a>
- <a href="/openapi.json"><code>openapi.json</code> · HTTP API</a>
+ <a href="/everything" data-i18n-html="sitemap_index.browse_by_goal_not_by_section"><code>/everything</code> · browse by goal, not by section</a>
+ <a href="/sitemap.xml" data-i18n-html="sitemap_index.for_search_engines"><code>sitemap.xml</code> · for search engines</a>
+ <a href="/llms.txt" data-i18n-html="sitemap_index.for_ai_agents"><code>llms.txt</code> · for AI agents</a>
+ <a href="/llms-full.txt" data-i18n-html="sitemap_index.long_form"><code>llms-full.txt</code> · long form</a>
+ <a href="/api/features.json" data-i18n-html="sitemap_index.machine_manifest"><code>features.json</code> · machine manifest</a>
+ <a href="/changelog" data-i18n-html="sitemap_index.what_s_new"><code>changelog</code> · what's new</a>
+ <a href="/openapi.json" data-i18n-html="sitemap_index.http_api"><code>openapi.json</code> · HTTP API</a>
</div>
</div>
<div class="sm-filter">
@@ -114,8 +114,8 @@
</div>
<p class="sm-filter-count" role="status" aria-live="polite"><span id="sm-filter-count"></span><span id="sm-filter-hint" aria-hidden="true"></span></p>
<section class="sm-new" id="sm-new" aria-labelledby="sm-new-title">
- <h2 id="sm-new-title">Newest<a class="sm-new-more" href="/changelog">full changelog &rarr;</a></h2>
- <p class="sm-section-desc">The 9 most recently launched pages, straight to the live surface.</p>
+ <h2 id="sm-new-title" data-i18n-html="sitemap_index.newestfull_changelog">Newest<a class="sm-new-more" href="/changelog">full changelog &rarr;</a></h2>
+ <p class="sm-section-desc" data-i18n="sitemap_index.the_9_most_recently_launched_pages_straight">The 9 most recently launched pages, straight to the live surface.</p>
<ul class="sm-list">
<li>
<a href="/docs/event-markets-staking">
@@ -192,22 +192,22 @@
</ul>
</section>
<nav class="sm-toc" aria-label="Sections">
- <a href="#main">Main</a>
- <a href="#build">Build</a>
- <a href="#labs">Labs</a>
- <a href="#crypto">Crypto</a>
- <a href="#agent-tools">Agent Tools</a>
- <a href="#account">Account</a>
- <a href="#learn">Learn</a>
- <a href="#blog">Blog</a>
- <a href="#legal">Legal</a>
- <a href="#machine">Machine-readable</a>
- <a href="#news">News</a>
+ <a href="#main" data-i18n="sitemap_index.main">Main</a>
+ <a href="#build" data-i18n="sitemap_index.build">Build</a>
+ <a href="#labs" data-i18n="sitemap_index.labs">Labs</a>
+ <a href="#crypto" data-i18n="sitemap_index.crypto">Crypto</a>
+ <a href="#agent-tools" data-i18n="sitemap_index.agent_tools">Agent Tools</a>
+ <a href="#account" data-i18n="sitemap_index.account">Account</a>
+ <a href="#learn" data-i18n="sitemap_index.learn">Learn</a>
+ <a href="#blog" data-i18n="sitemap_index.blog">Blog</a>
+ <a href="#legal" data-i18n="sitemap_index.legal">Legal</a>
+ <a href="#machine" data-i18n="sitemap_index.machine_readable">Machine-readable</a>
+ <a href="#news" data-i18n="sitemap_index.news">News</a>
</nav>
<section class="sm-section" id="main">
<header>
<h2><span data-i18n="sitemap_index.section_main">Main</span><span class="sm-count" data-count>71</span></h2>
- <p class="sm-section-desc">Entry points into the product.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.entry_points_into_the_product">Entry points into the product.</p>
</header>
<ul class="sm-list">
<li>
@@ -713,7 +713,7 @@
<section class="sm-section" id="build">
<header>
<h2><span data-i18n="sitemap_index.section_build">Build</span><span class="sm-count" data-count>92</span></h2>
- <p class="sm-section-desc">Create and customize an agent.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.create_and_customize_an_agent">Create and customize an agent.</p>
</header>
<ul class="sm-list">
<li>
@@ -1366,7 +1366,7 @@
<section class="sm-section" id="labs">
<header>
<h2><span data-i18n="sitemap_index.section_labs">Labs</span><span class="sm-count" data-count>26</span></h2>
- <p class="sm-section-desc">Experimental features actively shipping. Expect fast iteration.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.experimental_features_actively_shipping_expe">Experimental features actively shipping. Expect fast iteration.</p>
</header>
<ul class="sm-list">
<li>
@@ -1557,7 +1557,7 @@
<section class="sm-section" id="crypto">
<header>
<h2><span data-i18n="sitemap_index.section_crypto">Crypto</span><span class="sm-count" data-count>170</span></h2>
- <p class="sm-section-desc">On-chain features: pay-per-call, token launches, vanity wallets.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.on_chain_features_pay_per_call_token">On-chain features: pay-per-call, token launches, vanity wallets.</p>
</header>
<ul class="sm-list">
<li>
@@ -2756,7 +2756,7 @@
<section class="sm-section" id="agent-tools">
<header>
<h2><span data-i18n="sitemap_index.section_agent-tools">Agent Tools</span><span class="sm-count" data-count>11</span></h2>
- <p class="sm-section-desc">Manage, talk to, and deploy individual agents.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.manage_talk_to_and_deploy_individual_agents">Manage, talk to, and deploy individual agents.</p>
</header>
<ul class="sm-list">
<li>
@@ -2842,7 +2842,7 @@
<section class="sm-section" id="account">
<header>
<h2><span data-i18n="sitemap_index.section_account">Account</span><span class="sm-count" data-count>15</span></h2>
- <p class="sm-section-desc">Sign-in, dashboard, billing.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.sign_in_dashboard_billing">Sign-in, dashboard, billing.</p>
</header>
<ul class="sm-list">
<li>
@@ -2956,7 +2956,7 @@
<section class="sm-section" id="learn">
<header>
<h2><span data-i18n="sitemap_index.section_learn">Learn</span><span class="sm-count" data-count>498</span></h2>
- <p class="sm-section-desc">Docs, tutorials, and reference.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.docs_tutorials_and_reference">Docs, tutorials, and reference.</p>
</header>
<ul class="sm-list">
<li>
@@ -6451,7 +6451,7 @@
<section class="sm-section" id="blog">
<header>
<h2><span data-i18n="sitemap_index.section_blog">Blog</span><span class="sm-count" data-count>39</span></h2>
- <p class="sm-section-desc">Long-form announcements, launches, and writing from three.ws.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.long_form_announcements_launches_and_writing">Long-form announcements, launches, and writing from three.ws.</p>
</header>
<ul class="sm-list">
<li>
@@ -6805,7 +6805,7 @@
<section class="sm-section" id="machine">
<header>
<h2><span data-i18n="sitemap_index.section_machine">Machine-readable</span><span class="sm-count" data-count>18</span></h2>
- <p class="sm-section-desc">Indexes and well-known files for crawlers and AI agents.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.indexes_and_well_known_files_for_crawlers">Indexes and well-known files for crawlers and AI agents.</p>
</header>
<ul class="sm-list">
<li>
@@ -6940,7 +6940,7 @@
<section class="sm-section" id="news">
<header>
<h2><span data-i18n="sitemap_index.section_news">News</span><span class="sm-count" data-count>112</span></h2>
- <p class="sm-section-desc">Product launches, integrations, and announcements from three.ws.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.product_launches_integrations_and_announceme">Product launches, integrations, and announcements from three.ws.</p>
</header>
<ul class="sm-list">
<li>
@@ -7731,10 +7731,10 @@
</section>
<div class="sm-empty" id="sm-empty" hidden>
<p><span data-i18n="sitemap_index.no_pages_match">No pages match</span> &ldquo;<span id="sm-empty-q"></span>&rdquo;.</p>
- <p class="sm-empty-hint">Try a shorter word, or search everything: global search covers agents, coins, and skills too.</p>
+ <p class="sm-empty-hint" data-i18n="sitemap_index.try_a_shorter_word_or_search_everything">Try a shorter word, or search everything: global search covers agents, coins, and skills too.</p>
<div class="sm-empty-actions">
- <button type="button" id="sm-empty-clear">Clear filter</button>
- <a id="sm-empty-search" href="/search">Search all of three.ws</a>
+ <button type="button" id="sm-empty-clear" data-i18n="sitemap_index.clear_filter">Clear filter</button>
+ <a id="sm-empty-search" href="/search" data-i18n="sitemap_index.search_all_of_three_ws">Search all of three.ws</a>
</div>
</div>
</main>
diff --git a/specs/EMBED_SPEC.md b/specs/EMBED_SPEC.md
index 7f561f7c9..35c610149 100644
--- a/specs/EMBED_SPEC.md
+++ b/specs/EMBED_SPEC.md
@@ -68,6 +68,10 @@ name-plate) is **opt-in**:
| `camera-controls` | boolean | off | orbit, pan, zoom |
| `auto-rotate` | boolean | off | slow Y-axis rotation |
| `ar` | boolean | off | WebXR / Scene Viewer / Quick Look |
+| `ar-modes` | space-separated list | `webxr scene-viewer quick-look` | which AR launch paths `activateAR()` is allowed to try, in order |
+| `ar-placement` | `floor` \| `wall` | `floor` | surface the AR session should anchor to (Scene Viewer honors both; WebXR and Quick Look are floor-only) |
+| `ios-src` | URL to a `.usdz` | none | pre-authored USDZ for Quick Look; when omitted, the element generates a best-effort USDZ from the GLB on device |
+| `variant-name` | string | none | selects a `KHR_materials_variants` material variant baked into the GLB; unset or unknown restores the default materials |
| `shadows` | boolean | on | contact + soft shadows |
| `exposure` | number | 1.0 | tone-map exposure |
| `background` | CSS color or `transparent` | transparent | canvas clear color |
@@ -242,6 +246,15 @@ element.removeAttribute('avatar-chat'); // re-enable
<!-- AR button (inherits <model-viewer> pattern) -->
<button slot="ar-button">View in your space</button>
+ <!-- Hotspots: any element works. data-position places it in 3D (world
+ space, "x y z"); data-camera-orbit "theta phi radius" (optional,
+ degrees/degrees/world units) flies the camera there on click, paired
+ with an optional data-camera-target "x y z". A hotspot with no
+ data-camera-orbit is a plain label that just tracks its 3D position. -->
+ <button slot="hotspot" data-position="0 1.2 0.3" data-camera-orbit="20 75 2" data-camera-target="0 1.2 0">
+ Chest rig
+ </button>
+
<!-- Custom chat UI override -->
<div slot="chat">
<!-- host their own chat; hook events below -->
@@ -269,6 +282,10 @@ All events bubble and compose (`composed: true`).
| `memory:write` | `{ key, type }` | memory updated |
| `chain:resolved` | `{ chain, agentId, cid }` | on-chain lookup succeeded |
| `chain:tx` | `{ hash, kind }` | registration / update tx submitted |
+| `agent:ar-status` | `{ message }` | progress text while an on-device USDZ generates for Quick Look |
+| `agent:ar-ready` | `{ canActivateAR }` | AR target configured; `activateAR()` is safe to call (may still be `canActivateAR: false` on a device with no usable AR mode) |
+| `agent:variants-ready`| `{ names }` | the GLB's `KHR_materials_variants` list parsed (names only; fires once per load) |
+| `agent:variant-changed`| `{ name, requested, ok }`| `variant-name` applied; `ok` is `false` when `requested` did not match a known variant (default materials were restored) |
## JS API
@@ -285,6 +302,14 @@ await el.wave({ style: 'enthusiastic' });
await el.lookAt('user');
await el.play('clip-name');
+// AR, mirrors <model-viewer>'s own names
+el.canActivateAR; // true once a usable AR mode (WebXR / Scene Viewer / Quick Look) is ready
+await el.activateAR(); // launches whichever mode ar-modes and the device both allow
+
+// KHR_materials_variants
+el.availableVariants; // names baked into the loaded GLB, or []
+el.variantName = 'Red'; // switch live; set to null to restore the default materials
+
// Skills
await el.installSkill('ipfs://bafy.../dance/');
el.uninstallSkill('dance');
@@ -456,6 +481,10 @@ All bundle responses ship `access-control-allow-origin: *` and `cross-origin-res
## Changelog
+### 2026-10-12 (AR/variant/hotspot contract, not an `<agent-3d>` version bump)
+
+- Added `ar-modes`, `ar-placement`, `ios-src`, and `variant-name` attributes, `canActivateAR` / `activateAR()` / `availableVariants` / `variantName` JS API, `agent:ar-status` / `agent:ar-ready` / `agent:variants-ready` / `agent:variant-changed` events, and the `slot="hotspot"` (`data-position`, `data-normal`, `data-camera-orbit`, `data-camera-target`) camera-fly-to pattern. `pages/ar.html` (`/avatars/:id/ar`, `/agents/:id/ar`) now runs entirely on `<agent-3d ar>`; it no longer loads a third-party viewer CDN.
+
### 2026-07-08 (embed v1 sibling runtime, not an `<agent-3d>` version bump)
- Added **[Token Gating](#token-gating)**: server-verified on-chain SPL-balance gating for the embed v1 asset resolver (`/api/embed/resolve`, `<three-d>`) — gate config, the `gate-verify` SIWS flow, resolver locked/unlocked responses, short-lived access tokens, anti-abuse rate limits, and the widget's locked-state UI contract.
diff --git a/src/ar-page.js b/src/ar-page.js
index fb05bbf7f..34c945a5e 100644
--- a/src/ar-page.js
+++ b/src/ar-page.js
@@ -1,15 +1,13 @@
/**
* /avatars/:id/ar and /agents/:id/ar: the dedicated AR experience page
*
- * Fetches the entity (an avatar directly, or an agent's bound body), loads it
- * into a full-screen model-viewer with AR enabled.
- * If the avatar has a pre-generated usdz_url, sets it as ios-src immediately.
- * Otherwise converts the GLB to USDZ in-browser and sets a temporary object URL
- * so Quick Look works in the current session.
+ * Fetches the entity (an avatar directly, or an agent's bound body) and loads
+ * it into a full-screen <agent-3d ar>. The element owns AR end to end: it
+ * uses the avatar's pre-generated usdz_url (ios-src) when present, otherwise
+ * generates one in-browser on demand, and reports progress via the
+ * agent:ar-status / agent:ar-ready events wired in renderPage() below.
*/
-import { glbBlobToUsdzBlob } from './usdz-pipeline.js';
-import { glbBlobToAnimatedUsdzBlob, DEFAULT_AR_ANIMATION } from './usdz-animated.js';
import { log } from './shared/log.js';
import { mountViewSwitcher } from './view-switcher.js';
@@ -28,8 +26,6 @@ let avatarId = mode === 'avatar' ? entityId : '';
const $ = (id) => document.getElementById(id);
-let usdzObjectUrl = null;
-
async function init() {
if (!entityId) {
showError(
@@ -66,14 +62,7 @@ async function init() {
}
renderPage(avatar, glbUrl);
-
- if (avatar.usdz_url) {
- applyUsdzSrc(avatar.usdz_url);
- setArReady();
- } else {
- // Auto-generate USDZ so AR works in this session
- generateUsdz(glbUrl);
- }
+ setStatus('Preparing AR preview…');
}
async function fetchAvatar(id) {
@@ -141,10 +130,16 @@ function renderPage(avatar, glbUrl) {
});
$('ar-share-btn').addEventListener('click', () => shareAvatar(avatar));
-}
-function applyUsdzSrc(src) {
- $('ar-viewer').setAttribute('ios-src', src);
+ // <agent-3d ar> owns USDZ generation (on-device, animated-first with a
+ // static fallback) and AR-mode detection; it reports progress through
+ // these events instead of us driving the pipeline by hand.
+ viewer.addEventListener('agent:ar-status', (e) => setStatus(e.detail?.message));
+ viewer.addEventListener('agent:ar-ready', () => {
+ setArReady();
+ setStatus('AR preview ready');
+ setTimeout(() => setStatus(null), 2000);
+ });
}
function setArReady() {
@@ -161,52 +156,6 @@ function setStatus(msg) {
el.hidden = false;
}
-// Prefer a living, animated avatar in AR; fall back to the proven static bake
-// if the avatar can't be animated (no rig, clip won't retarget, fetch fails).
-// Either way the user gets a correct avatar — animation is upside, never a gate.
-async function buildArUsdz(glbBlob) {
- try {
- setStatus('Bringing your avatar to life…');
- const animResp = await fetch(DEFAULT_AR_ANIMATION);
- if (!animResp.ok) throw new Error(`animation fetch ${animResp.status}`);
- const animationGlbBlob = await animResp.blob();
- return await glbBlobToAnimatedUsdzBlob(glbBlob, { animationGlbBlob });
- } catch (err) {
- log.warn('[ar-page] animated USDZ unavailable, using static:', err?.message);
- setStatus('Generating AR preview…');
- return glbBlobToUsdzBlob(glbBlob);
- }
-}
-
-async function generateUsdz(glbUrl) {
- const btn = $('ar-launch-btn');
- setStatus('Preparing AR preview…');
- btn.disabled = true;
- btn.setAttribute('aria-busy', 'true');
-
- try {
- setStatus('Downloading model…');
- const r = await fetch(glbUrl);
- if (!r.ok) throw new Error(`GLB fetch ${r.status}`);
- const glbBlob = await r.blob();
-
- const usdzBlob = await buildArUsdz(glbBlob);
-
- if (usdzObjectUrl) URL.revokeObjectURL(usdzObjectUrl);
- usdzObjectUrl = URL.createObjectURL(usdzBlob);
- applyUsdzSrc(usdzObjectUrl);
-
- setArReady();
- setStatus('AR preview ready');
- setTimeout(() => setStatus(null), 2000);
- } catch (err) {
- $('ar-status').classList.add('is-error');
- setStatus(`Couldn't generate AR preview: ${err.message}`);
- btn.disabled = false;
- btn.removeAttribute('aria-busy');
- }
-}
-
/**
* Replace the whole shell with a designed error state.
*
@@ -314,8 +263,4 @@ document.addEventListener('DOMContentLoaded', () => {
log.error('[ar-page] init error', err);
showError('Something went wrong loading this avatar.', { retry: true });
});
-
- window.addEventListener('beforeunload', () => {
- if (usdzObjectUrl) URL.revokeObjectURL(usdzObjectUrl);
- });
});
diff --git a/src/ar/scene-viewer.js b/src/ar/scene-viewer.js
index 6ee098827..780a765c8 100644
--- a/src/ar/scene-viewer.js
+++ b/src/ar/scene-viewer.js
@@ -9,10 +9,13 @@ export function canUseSceneViewer() {
return isAndroid();
}
-export function openSceneViewer(glbURL, { title = '', link = '' } = {}) {
+export function openSceneViewer(glbURL, { title = '', link = '', placement = 'floor' } = {}) {
const params = new URLSearchParams({ file: glbURL, mode: 'ar_preferred' });
if (title) params.set('title', title);
if (link) params.set('link', link);
+ // Scene Viewer defaults to floor placement; this is its documented switch
+ // for wall-mountable models (art, screens, anything meant to hang).
+ if (placement === 'wall') params.set('enable_vertical_placement', 'true');
// S.browser_fallback_url ensures the user lands back on the page if ARCore
// is missing rather than ending up on an error screen.
diff --git a/src/element.js b/src/element.js
index 211548aba..2858e7be7 100644
--- a/src/element.js
+++ b/src/element.js
@@ -1,8 +1,10 @@
// <agent-3d> — the web component that ships the whole framework in one tag.
// See specs/EMBED_SPEC.md
-import { Box3, Color } from 'three';
+import { Box3, Color, Vector3 } from 'three';
import { Viewer } from './viewer.js';
+import { createVariantController } from './khr-variants.js';
+import { buildBestEffortArUsdz } from './usdz-animated.js';
import { Runtime, skillAccessFromAgentDetail } from './runtime/index.js';
import { SkillPaymentModal, PaymentChip } from './payment-modal.js';
import { SceneController } from './runtime/scene.js';
@@ -481,6 +483,21 @@ const BASE_STYLE = `
transition: opacity 0.4s;
pointer-events: none;
}
+ /* Hotspot layer: see the <slot name="hotspot"> comment in _renderShell.
+ The layer itself never blocks orbit-drag/click-through; only a slotted
+ hotspot element (positioned by _updateHotspots) takes pointer events. */
+ .hotspot-layer {
+ position: absolute;
+ inset: 0;
+ overflow: hidden;
+ pointer-events: none;
+ }
+ .hotspot-layer ::slotted([slot="hotspot"]) {
+ position: absolute;
+ left: 0;
+ top: 0;
+ pointer-events: auto;
+ }
/* Loading state — an invisible status region while the GLB streams in. The
poster image (when supplied) fills the frame; otherwise the host sees
transparent until the avatar paints. No silhouette placeholder. Kept as a
@@ -729,6 +746,12 @@ class Agent3DElement extends HTMLElement {
'wallet',
'sign-language',
'sonar',
+ 'poster',
+ 'ar',
+ 'ar-modes',
+ 'ar-placement',
+ 'ios-src',
+ 'variant-name',
];
}
@@ -745,6 +768,15 @@ class Agent3DElement extends HTMLElement {
this._manifest = null;
this._mounted = false;
this._booting = false;
+ // Bumped on every teardown/reboot so a stale _wirePostLoadMedia() run
+ // (variant parsing, USDZ generation) from a previous boot can tell it
+ // has been superseded and stop touching this element.
+ this._bootToken = 0;
+ this._variantController = null;
+ this._generatedUsdzUrl = null;
+ this._bodyUrl = null;
+ this._hotspotLayerEl = null;
+ this._hotspotSlotEl = null;
this._listening = false;
this._pillActive = false;
this._mqNarrow = null;
@@ -884,6 +916,8 @@ class Agent3DElement extends HTMLElement {
this._loadingEl = null;
this._stageEl = null;
this._posterEl = null;
+ this._hotspotLayerEl = null;
+ this._hotspotSlotEl = null;
this._nameplateEl = null;
this._chatEl = null;
this._inputEl = null;
@@ -965,6 +999,11 @@ class Agent3DElement extends HTMLElement {
this._applyLayout();
if (name === 'background') this._applyBackground();
if (name === 'name-plate') this._applyNamePlate();
+ if (name === 'poster' && this._posterEl) {
+ this._posterEl.style.backgroundImage = newVal ? `url(${newVal})` : '';
+ }
+ if (name === 'variant-name') this._applyVariantName();
+ if (['ar', 'ar-modes', 'ar-placement', 'ios-src'].includes(name)) this._refreshAR();
if (name === 'tracked-mint') {
this._detachTradeReactions?.();
this._detachTradeReactions = newVal
@@ -1033,6 +1072,23 @@ class Agent3DElement extends HTMLElement {
if (this.getAttribute('poster')) {
poster.style.backgroundImage = `url(${this.getAttribute('poster')})`;
}
+ // Hotspot layer: a <slot name="hotspot"> over the stage. Each assigned
+ // light-DOM child self-describes a world position (data-position, and
+ // optionally data-normal) that gets projected to screen space every
+ // frame, and an optional saved camera view (data-camera-orbit /
+ // data-camera-target) that fires on click. Inserted before the poster
+ // so the (DOM-order-stacked) poster still covers hotspots while loading.
+ const hotspotLayer = document.createElement('div');
+ hotspotLayer.className = 'hotspot-layer';
+ hotspotLayer.part = 'hotspot-layer';
+ const hotspotSlot = document.createElement('slot');
+ hotspotSlot.name = 'hotspot';
+ hotspotLayer.appendChild(hotspotSlot);
+ hotspotLayer.addEventListener('click', (e) => this._onHotspotClick(e));
+ this.shadowRoot.appendChild(hotspotLayer);
+ this._hotspotLayerEl = hotspotLayer;
+ this._hotspotSlotEl = hotspotSlot;
+
this.shadowRoot.appendChild(poster);
this._posterEl = poster;
@@ -1778,6 +1834,7 @@ class Agent3DElement extends HTMLElement {
async _boot() {
if (this._booting || this._mounted) return;
+ this._bootToken++;
this._renderShell();
this._booting = true;
try {
@@ -1863,6 +1920,7 @@ class Agent3DElement extends HTMLElement {
this._viewer = viewer;
viewer._afterAnimateHooks = viewer._afterAnimateHooks || [];
viewer._afterAnimateHooks.push(() => this._updateBubblePosition());
+ viewer._afterAnimateHooks.push(() => this._updateHotspots());
// Apply the embed surface attributes (`background`, `name-plate`) now
// that the viewer exists. They are also re-applied on attribute change.
// A bare avatar carries no name-plate unless the embedder asks for one.
@@ -1900,12 +1958,15 @@ class Agent3DElement extends HTMLElement {
// gateway (ipfs.io rate-limits browsers routinely) used to leave a
// third-party embed with a name and no avatar and no way to recover.
const bodyCandidates = uriCandidates(manifest.body?.uri);
+ let loadedCandidate = null;
+ let loadedGltf = null;
if (bodyCandidates.length) {
let bodyErr;
let loaded = false;
for (const candidate of bodyCandidates) {
try {
- await viewer.load(candidate, '', new Map());
+ loadedGltf = await viewer.load(candidate, '', new Map());
+ loadedCandidate = candidate;
loaded = true;
break;
} catch (err) {
@@ -1953,6 +2014,12 @@ class Agent3DElement extends HTMLElement {
requestAnimationFrame(_nudge);
}
}
+ if (loadedGltf && loadedCandidate) {
+ this._bodyUrl = loadedCandidate;
+ // Fire-and-forget: variant parsing and AR/USDZ generation are
+ // progressive enhancements that must never hold up agent:ready.
+ this._wirePostLoadMedia(loadedCandidate, loadedGltf, this._bootToken);
+ }
this._scene = new SceneController(viewer);
// Initial playback. Chat avatars idle-loop (then walk on stream); bare
// decoration avatars honor the `clip` attribute, the clip's manifest
@@ -2566,6 +2633,154 @@ class Agent3DElement extends HTMLElement {
this._thoughtBubbleEl.dataset.tailDir = bubbleBottom < headRelY ? 'up' : 'down';
}
+ // --- Hotspots (slot="hotspot", data-position/data-normal, data-camera-orbit/data-camera-target) ---
+
+ _parseVec3(value) {
+ if (!value) return null;
+ const parts = value.trim().split(/\s+/).map(Number);
+ if (parts.length !== 3 || parts.some((n) => Number.isNaN(n))) return null;
+ return new Vector3(parts[0], parts[1], parts[2]);
+ }
+
+ _updateHotspots() {
+ const slot = this._hotspotSlotEl;
+ if (!slot || !this._viewer) return;
+ const elements = slot.assignedElements ? slot.assignedElements() : [];
+ for (const el of elements) {
+ const worldPos = this._parseVec3(el.dataset.position);
+ const screen = worldPos && this._viewer.projectToScreen(worldPos);
+ if (!screen) {
+ el.hidden = true;
+ continue;
+ }
+ el.hidden = screen.behindCamera;
+ el.style.transform = `translate(-50%, -50%) translate(${screen.x}px, ${screen.y}px)`;
+ }
+ }
+
+ // Saved-camera-view hotspots fly the orbit camera there on click/tap; a
+ // hotspot with no data-camera-orbit is a plain label/marker and does nothing.
+ _onHotspotClick(e) {
+ const target = e.target.closest?.('[data-camera-orbit]');
+ if (!target || !this._viewer) return;
+ const orbit = this._parseVec3(target.dataset.cameraOrbit);
+ if (!orbit) return;
+ const camTarget = this._parseVec3(target.dataset.cameraTarget) || new Vector3(0, 0, 0);
+ this._viewer.setCameraOrbit(orbit.x, orbit.y, orbit.z, camTarget);
+ }
+
+ // --- KHR_materials_variants ---
+
+ async _applyVariantName() {
+ if (!this._variantController) return;
+ const name = this.getAttribute('variant-name') || null;
+ const ok = await this._variantController.select(name);
+ this._viewer?.invalidate?.();
+ this._emit(
+ 'agent:variant-changed',
+ { name: this._variantController.current, requested: name, ok },
+ { bubbles: true, composed: true },
+ );
+ }
+
+ async _setupVariants(bytes, gltf, token) {
+ let controller = null;
+ try {
+ controller = await createVariantController(bytes, gltf);
+ } catch (err) {
+ log.warn('[agent-3d] KHR_materials_variants parsing failed', err);
+ }
+ if (token !== this._bootToken) return;
+ this._variantController = controller;
+ if (!controller) return;
+ this._emit(
+ 'agent:variants-ready',
+ { names: controller.names.slice() },
+ { bubbles: true, composed: true },
+ );
+ if (this.hasAttribute('variant-name')) await this._applyVariantName();
+ }
+
+ // --- AR (ar, ar-modes, ar-placement, ios-src) ---
+
+ async _fetchBodyBytes(url) {
+ const res = await fetch(url);
+ if (!res.ok) throw new Error(`glb fetch ${res.status}`);
+ return res.arrayBuffer();
+ }
+
+ async _setupAR(glbUrl, bytes, token) {
+ if (!this._viewer) return;
+ if (!this.hasAttribute('ar')) {
+ await this._viewer.setARTarget(null, null);
+ return;
+ }
+ const modes = (this.getAttribute('ar-modes') || 'webxr scene-viewer quick-look')
+ .trim()
+ .split(/\s+/)
+ .filter(Boolean);
+ const placement = this.getAttribute('ar-placement') === 'wall' ? 'wall' : 'floor';
+
+ let usdzUrl = this.getAttribute('ios-src') || null;
+ if (!usdzUrl && modes.includes('quick-look')) {
+ try {
+ const usdzBlob = await buildBestEffortArUsdz(new Blob([bytes]), {
+ onStatus: (message) => {
+ if (token !== this._bootToken) return;
+ this._emit('agent:ar-status', { message }, { bubbles: true, composed: true });
+ },
+ });
+ if (token !== this._bootToken) return;
+ usdzUrl = URL.createObjectURL(usdzBlob);
+ if (this._generatedUsdzUrl) URL.revokeObjectURL(this._generatedUsdzUrl);
+ this._generatedUsdzUrl = usdzUrl;
+ } catch (err) {
+ // Quick Look just stays unavailable; Scene Viewer / WebXR still work.
+ log.warn('[agent-3d] on-device USDZ generation failed', err);
+ }
+ }
+ if (token !== this._bootToken) return;
+ await this._viewer.setARTarget(glbUrl, usdzUrl, { modes, placement });
+ if (token !== this._bootToken) return;
+ this._emit(
+ 'agent:ar-ready',
+ { canActivateAR: this._viewer.canActivateAR },
+ { bubbles: true, composed: true },
+ );
+ }
+
+ async _refreshAR() {
+ if (!this._mounted || !this._viewer) return;
+ if (!this.hasAttribute('ar')) {
+ await this._viewer.setARTarget(null, null);
+ return;
+ }
+ if (!this._bodyUrl) return;
+ const token = this._bootToken;
+ try {
+ const bytes = await this._fetchBodyBytes(this._bodyUrl);
+ if (token !== this._bootToken) return;
+ await this._setupAR(this._bodyUrl, bytes, token);
+ } catch (err) {
+ log.warn('[agent-3d] AR attribute refresh failed', err);
+ }
+ }
+
+ async _wirePostLoadMedia(glbUrl, gltf, token) {
+ let bytes;
+ try {
+ bytes = await this._fetchBodyBytes(glbUrl);
+ } catch (err) {
+ log.warn('[agent-3d] could not re-fetch body bytes for variants/AR', err);
+ return;
+ }
+ if (token !== this._bootToken) return;
+ await Promise.allSettled([
+ this._setupVariants(bytes, gltf, token),
+ this._setupAR(glbUrl, bytes, token),
+ ]);
+ }
+
_appendStreamChunkToChat(chunk) {
if (!this._chatEl || !chunk) return;
if (!this._streamingMsgEl) {
@@ -3061,6 +3276,14 @@ class Agent3DElement extends HTMLElement {
}
_teardown() {
+ // Invalidate any in-flight _wirePostLoadMedia() run from this boot.
+ this._bootToken++;
+ this._variantController = null;
+ this._bodyUrl = null;
+ if (this._generatedUsdzUrl) {
+ URL.revokeObjectURL(this._generatedUsdzUrl);
+ this._generatedUsdzUrl = null;
+ }
// A torn-down element must not leave a microphone open or a tone playing.
this.stopSonar();
_untrackLiveViewer(this);
@@ -3146,6 +3369,31 @@ class Agent3DElement extends HTMLElement {
// --- Public JS API ---
+ /** True once an AR launch path (Quick Look, Scene Viewer, or WebXR) is ready on this device. Mirrors `<model-viewer>`. */
+ get canActivateAR() {
+ return !!this._viewer?.canActivateAR;
+ }
+
+ /** Launch AR via whichever path `canActivateAR` found. Mirrors `<model-viewer>`'s `activateAR()`. */
+ async activateAR() {
+ if (!this._mounted) await this._waitForReady();
+ return (await this._viewer?.activateAR?.()) ?? false;
+ }
+
+ /** Variant names declared by the loaded GLB's KHR_materials_variants data, or `[]` if it has none. */
+ get availableVariants() {
+ return this._variantController?.names.slice() ?? [];
+ }
+
+ get variantName() {
+ return this.getAttribute('variant-name') || null;
+ }
+
+ set variantName(name) {
+ if (name) this.setAttribute('variant-name', name);
+ else this.removeAttribute('variant-name');
+ }
+
say(text, opts = {}) {
if (this._pendingSay) {
this._pendingSay = { text, opts };
diff --git a/src/khr-variants.js b/src/khr-variants.js
new file mode 100644
index 000000000..45d4b4df4
--- /dev/null
+++ b/src/khr-variants.js
@@ -0,0 +1,157 @@
+// KHR_materials_variants runtime support for <agent-3d>.
+//
+// three.js's own GLTFLoader has no native support for this extension (it is
+// not among three/examples/jsm's registered extensions), so the variant
+// table is read by a second, isomorphic glTF-Transform parse of the same raw
+// GLB bytes already fetched to load the model, then cross-referenced against
+// GLTFLoader's own `parser.associations` map (which records, for every
+// loaded three.js object, which glTF JSON mesh/primitive it came from) to
+// find the exact THREE.Mesh each variant mapping targets.
+//
+// glTF-Transform (Apache-2.0, https://github.com/donmccurdy/glTF-Transform)
+// is already a project dependency; this mirrors the WebIO usage pattern in
+// src/gltf-inspect.js.
+
+import { WebIO } from '@gltf-transform/core';
+import { ALL_EXTENSIONS, KHRMaterialsVariants } from '@gltf-transform/extensions';
+
+/**
+ * Read a GLB/glTF's KHR_materials_variants data, independent of any three.js
+ * scene. Returns null when the asset doesn't use the extension.
+ *
+ * @param {ArrayBuffer|Uint8Array} glbBytes
+ * @returns {Promise<null | {
+ * names: string[],
+ * primitives: Array<{
+ * meshIndex: number,
+ * primitiveIndex: number,
+ * byVariant: Map<string, number>,
+ * defaultMaterialIndex: number|null,
+ * }>,
+ * }>}
+ */
+export async function parseVariantTable(glbBytes) {
+ const bytes = glbBytes instanceof Uint8Array ? glbBytes : new Uint8Array(glbBytes);
+ const io = new WebIO().registerExtensions(ALL_EXTENSIONS);
+ let doc;
+ try {
+ doc = await io.readBinary(bytes);
+ } catch {
+ return null;
+ }
+ const root = doc.getRoot();
+ const usesVariants = root
+ .listExtensionsUsed()
+ .some((e) => e.extensionName === KHRMaterialsVariants.EXTENSION_NAME);
+ if (!usesVariants) return null;
+
+ const materials = root.listMaterials();
+ const meshes = root.listMeshes();
+ const names = [];
+ const primitives = [];
+
+ for (let meshIndex = 0; meshIndex < meshes.length; meshIndex++) {
+ const prims = meshes[meshIndex].listPrimitives();
+ for (let primitiveIndex = 0; primitiveIndex < prims.length; primitiveIndex++) {
+ const prim = prims[primitiveIndex];
+ const list = prim.getExtension(KHRMaterialsVariants.EXTENSION_NAME);
+ if (!list) continue;
+
+ const byVariant = new Map();
+ for (const mapping of list.listMappings()) {
+ const materialIndex = materials.indexOf(mapping.getMaterial());
+ if (materialIndex < 0) continue;
+ for (const variant of mapping.listVariants()) {
+ const name = variant.getName();
+ if (!name) continue;
+ if (!names.includes(name)) names.push(name);
+ byVariant.set(name, materialIndex);
+ }
+ }
+ if (!byVariant.size) continue;
+
+ const defaultMaterial = prim.getMaterial();
+ const defaultIdx = defaultMaterial ? materials.indexOf(defaultMaterial) : -1;
+ primitives.push({
+ meshIndex,
+ primitiveIndex,
+ byVariant,
+ defaultMaterialIndex: defaultIdx < 0 ? null : defaultIdx,
+ });
+ }
+ }
+
+ if (!names.length || !primitives.length) return null;
+ return { names, primitives };
+}
+
+/**
+ * Build a live variant controller for an already-loaded three.js glTF scene.
+ *
+ * @param {ArrayBuffer|Uint8Array} glbBytes, the raw bytes used to load `gltf`
+ * @param {object} gltf, the object three.js's GLTFLoader resolved (`{ scene, parser, ... }`)
+ * @returns {Promise<null | {
+ * names: string[],
+ * current: string|null,
+ * select(name: string|null): Promise<boolean>,
+ * }>}
+ */
+export async function createVariantController(glbBytes, gltf) {
+ const table = await parseVariantTable(glbBytes);
+ if (!table) return null;
+
+ const parser = gltf?.parser;
+ const scene = gltf?.scene;
+ if (!parser || !scene) return null;
+
+ // Index every mesh primitive in the loaded scene by the same
+ // (meshIndex, primitiveIndex) keys parseVariantTable produced, using
+ // GLTFLoader's own node->JSON-index bookkeeping.
+ const targets = new Map();
+ scene.traverse((obj) => {
+ if (!obj.isMesh) return;
+ const assoc = parser.associations.get(obj);
+ if (!assoc || assoc.meshes == null) return;
+ targets.set(`${assoc.meshes}:${assoc.primitives ?? 0}`, obj);
+ });
+
+ const resolved = table.primitives
+ .map((p) => ({ ...p, mesh: targets.get(`${p.meshIndex}:${p.primitiveIndex}`) }))
+ .filter((p) => p.mesh);
+ if (!resolved.length) return null;
+
+ // parser.getDependency caches by (type, index) itself, but caching here
+ // too avoids a redundant Map lookup + promise alloc on every select().
+ const materialCache = new Map();
+ async function getMaterial(materialIndex) {
+ if (materialIndex == null) return null;
+ if (materialCache.has(materialIndex)) return materialCache.get(materialIndex);
+ const material = await parser.getDependency('material', materialIndex);
+ materialCache.set(materialIndex, material);
+ return material;
+ }
+
+ let current = null;
+
+ /** @param {string|null} name: null (or an unknown name) restores each primitive's default material. */
+ async function select(name) {
+ const known = name != null && table.names.includes(name);
+ await Promise.all(
+ resolved.map(async (p) => {
+ const materialIndex = known ? p.byVariant.get(name) ?? p.defaultMaterialIndex : p.defaultMaterialIndex;
+ const material = await getMaterial(materialIndex);
+ if (material) p.mesh.material = material;
+ }),
+ );
+ current = known ? name : null;
+ return known;
+ }
+
+ return {
+ names: table.names.slice(),
+ get current() {
+ return current;
+ },
+ select,
+ };
+}
diff --git a/src/usdz-animated.js b/src/usdz-animated.js
index c8c722651..5b7df65c8 100644
--- a/src/usdz-animated.js
+++ b/src/usdz-animated.js
@@ -26,8 +26,10 @@ import {
_bakedLocalPositions,
_coerceMaterialsToStandard,
_ensureNormals,
+ glbBlobToUsdzBlob,
} from './usdz-pipeline.js';
import { retargetClipToObject } from './animation-retarget.js';
+import { log } from './shared/log.js';
// Default idle that ships in public/animations — a slow breathing loop that
// reads as "alive" the instant the avatar lands in AR.
@@ -303,3 +305,29 @@ export async function glbBlobToAnimatedUsdzBlob(glbBlob, opts = {}) {
return new Blob([_packUsdz(files)], { type: 'model/vnd.usdz+zip' });
}
+
+/**
+ * Best-effort USDZ for iOS Quick Look: prefer a living, animated avatar;
+ * fall back to the proven static bake if the avatar can't be animated (no
+ * rig, clip won't retarget, fetch fails). Either way the caller gets a
+ * correct USDZ: animation is upside, never a gate. Shared by `<agent-3d>`'s
+ * own AR wiring and anything else that needs on-device USDZ from a GLB.
+ *
+ * @param {Blob} glbBlob
+ * @param {object} [opts]
+ * @param {(message: string) => void} [opts.onStatus] progress text for a host UI
+ * @returns {Promise<Blob>}
+ */
+export async function buildBestEffortArUsdz(glbBlob, { onStatus } = {}) {
+ try {
+ onStatus?.('Bringing your avatar to life…');
+ const animResp = await fetch(DEFAULT_AR_ANIMATION);
+ if (!animResp.ok) throw new Error(`animation fetch ${animResp.status}`);
+ const animationGlbBlob = await animResp.blob();
+ return await glbBlobToAnimatedUsdzBlob(glbBlob, { animationGlbBlob });
+ } catch (err) {
+ log.warn('[usdz-animated] animated USDZ unavailable, using static:', err?.message);
+ onStatus?.('Generating AR preview…');
+ return glbBlobToUsdzBlob(glbBlob);
+ }
+}
diff --git a/src/viewer.js b/src/viewer.js
index 7b4c0dcc3..674c5cbb2 100644
--- a/src/viewer.js
+++ b/src/viewer.js
@@ -916,6 +916,23 @@ export class Viewer {
};
}
+ /**
+ * Project a world-space point to CSS pixels on the canvas, for hotspot
+ * placement. `behindCamera` is true once the point is behind the near
+ * plane (NDC z > 1), the one case translate(x,y) alone renders wrong
+ * (a point behind the camera projects to a flipped position in front).
+ */
+ projectToScreen(worldPos) {
+ if (!this.activeCamera || !this.renderer) return null;
+ const pos = worldPos.clone().project(this.activeCamera);
+ const canvas = this.renderer.domElement;
+ return {
+ x: (pos.x * 0.5 + 0.5) * canvas.clientWidth,
+ y: (-pos.y * 0.5 + 0.5) * canvas.clientHeight,
+ behindCamera: pos.z > 1,
+ };
+ }
+
render(deltaTime = 0) {
// Additive bloom bleeds bright highlights into neighbouring pixels —
// including the alpha-0 background. Over a transparent canvas that halo
@@ -1108,35 +1125,58 @@ export class Viewer {
* Update the AR button visibility and target URLs after a model loads.
* @param {string|null} glbUrl — absolute or relative URL to the GLB (for Android/WebXR)
* @param {string|null} usdzUrl — absolute or relative URL to a USDZ (for iOS Quick Look)
+ * @param {{modes?: string[], placement?: 'floor'|'wall'}} [opts]
+ * `modes` allow-lists which AR launch paths may be used (mirrors
+ * `<model-viewer>`'s `ar-modes` tokens: "webxr", "scene-viewer",
+ * "quick-look"); omitted or empty means all three. `placement` only
+ * reaches Scene Viewer today (WebXR hit-testing here is floor-only).
*/
- async setARTarget(glbUrl, usdzUrl = null) {
+ async setARTarget(glbUrl, usdzUrl = null, { modes, placement } = {}) {
this._arGlbUrl = glbUrl;
this._arUsdzUrl = usdzUrl;
+ this._arModes = modes && modes.length ? modes : ['webxr', 'scene-viewer', 'quick-look'];
+ this._arPlacement = placement === 'wall' ? 'wall' : 'floor';
if (!this._arBtn) return;
const hasGlb = !!glbUrl;
const hasUsdz = !!usdzUrl;
- const iosOk = hasUsdz && canUseQuickLook();
- const androidOk = hasGlb && canUseSceneViewer();
- const webxrOk = hasGlb && (await WebXRSession.isSupported());
+ const iosOk = hasUsdz && this._arModes.includes('quick-look') && canUseQuickLook();
+ const androidOk = hasGlb && this._arModes.includes('scene-viewer') && canUseSceneViewer();
+ const webxrOk =
+ hasGlb && this._arModes.includes('webxr') && (await WebXRSession.isSupported());
this._arBtn.hidden = !(iosOk || androidOk || webxrOk);
}
- async _launchAR() {
- if (canUseQuickLook() && this._arUsdzUrl) {
+ /** True once `setARTarget()` has found at least one usable AR launch path on this device. */
+ get canActivateAR() {
+ return !!this._arBtn && !this._arBtn.hidden;
+ }
+
+ /**
+ * Launch AR on whichever path this device and the `ar-modes` allow-list
+ * both support: on-device USDZ via iOS Quick Look, a Scene Viewer intent
+ * on Android, or a WebXR immersive-ar session otherwise. A second call
+ * while a WebXR session is live ends it instead (the button doubles as
+ * an exit control). Returns whether a launch path ran.
+ */
+ async activateAR() {
+ const modes = this._arModes || ['webxr', 'scene-viewer', 'quick-look'];
+ if (modes.includes('quick-look') && canUseQuickLook() && this._arUsdzUrl) {
openQuickLook(this._arUsdzUrl);
- } else if (canUseSceneViewer() && this._arGlbUrl) {
- openSceneViewer(this._arGlbUrl);
- } else if (this._arGlbUrl) {
- // Desktop WebXR
+ return true;
+ } else if (modes.includes('scene-viewer') && canUseSceneViewer() && this._arGlbUrl) {
+ openSceneViewer(this._arGlbUrl, { placement: this._arPlacement });
+ return true;
+ } else if (modes.includes('webxr') && this._arGlbUrl) {
+ // Desktop/Android WebXR
if (this._xrSession) {
await this._xrSession.end();
this._xrSession = null;
this._arBtn.classList.remove('ar-btn--active');
- return;
+ return true;
}
this._xrSession = new WebXRSession(this, {
onEnd: () => {
@@ -1146,7 +1186,25 @@ export class Viewer {
});
await this._xrSession.start();
this._arBtn.classList.add('ar-btn--active');
+ return true;
}
+ return false;
+ }
+
+ /**
+ * Tween the camera to a saved orbit, used by hotspot click-to-fly-to-view.
+ * @param {number} thetaDeg azimuthal angle in degrees
+ * @param {number} phiDeg polar angle in degrees (0 = straight down +Y)
+ * @param {number} radius distance from `target`
+ * @param {Vector3} [target]
+ */
+ setCameraOrbit(thetaDeg, phiDeg, radius, target = new Vector3(0, 0, 0)) {
+ if (!this.controls || !this.activeCamera) return false;
+ const theta = (thetaDeg * Math.PI) / 180;
+ const phi = (phiDeg * Math.PI) / 180;
+ const offset = new Vector3().setFromSphericalCoords(radius, phi, theta);
+ this._tweenCamera(target.clone().add(offset), target.clone(), 700);
+ return true;
}
resize() {
@@ -2023,11 +2081,14 @@ export class Viewer {
'</svg>' +
'<span class="ar-btn__label">AR</span>';
arBtn.hidden = true;
- arBtn.addEventListener('click', () => this._launchAR());
+ arBtn.part = 'ar-button';
+ arBtn.addEventListener('click', () => this.activateAR());
this.el.appendChild(arBtn);
this._arBtn = arBtn;
this._arGlbUrl = null;
this._arUsdzUrl = null;
+ this._arModes = ['webxr', 'scene-viewer', 'quick-look'];
+ this._arPlacement = 'floor';
this._xrSession = null;
if (isMobile) {
diff --git a/tests/agent-3d-ar-contract.test.js b/tests/agent-3d-ar-contract.test.js
new file mode 100644
index 000000000..380c39dcb
--- /dev/null
+++ b/tests/agent-3d-ar-contract.test.js
@@ -0,0 +1,134 @@
+/**
+ * <agent-3d>'s model-viewer-compatible AR/variant/hotspot contract:
+ * ar, ar-modes, ar-placement, ios-src, variant-name, poster, and the
+ * slot="hotspot" camera-fly-to pattern (work order 073).
+ *
+ * src/viewer.js constructs a real WebGLRenderer, so booting the element for
+ * real needs a browser (see tests/e2e/agent-3d-ar.spec.js for that). These
+ * tests pin the wiring statically: the attributes are observed, every
+ * attribute change reaches the right handler, and the public JS API mirrors
+ * model-viewer's names so pages/ar.html's existing click handler keeps
+ * working unmodified.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const read = (p) => readFileSync(resolve(__dirname, p), 'utf8');
+
+const element = read('../src/element.js');
+const viewer = read('../src/viewer.js');
+const sceneViewer = read('../src/ar/scene-viewer.js');
+
+describe('agent-3d observed attributes', () => {
+ it('observes every new AR/variant attribute', () => {
+ for (const attr of ['poster', 'ar', 'ar-modes', 'ar-placement', 'ios-src', 'variant-name']) {
+ expect(element).toContain(`'${attr}'`);
+ }
+ });
+
+ it('routes ar/ar-modes/ar-placement/ios-src changes to _refreshAR', () => {
+ expect(element).toMatch(/\['ar', 'ar-modes', 'ar-placement', 'ios-src'\].*_refreshAR/);
+ });
+
+ it('routes variant-name changes to _applyVariantName', () => {
+ expect(element).toMatch(/name === 'variant-name'.*_applyVariantName/);
+ });
+});
+
+describe('agent-3d public JS API mirrors model-viewer', () => {
+ it('exposes canActivateAR and activateAR()', () => {
+ expect(element).toContain('get canActivateAR()');
+ expect(element).toContain('async activateAR()');
+ });
+
+ it('exposes availableVariants and a variantName accessor pair', () => {
+ expect(element).toContain('get availableVariants()');
+ expect(element).toContain('get variantName()');
+ expect(element).toContain('set variantName(');
+ });
+});
+
+describe('agent-3d variant wiring', () => {
+ it('imports the KHR_materials_variants controller', () => {
+ expect(element).toContain("from './khr-variants.js'");
+ });
+
+ it('builds the controller after the body loads and emits agent:variants-ready', () => {
+ expect(element).toContain('_setupVariants(bytes, gltf, token)');
+ expect(element).toContain('createVariantController(bytes, gltf)');
+ expect(element).toContain("'agent:variants-ready'");
+ });
+
+ it('emits agent:variant-changed when variant-name is applied', () => {
+ expect(element).toContain("'agent:variant-changed'");
+ });
+});
+
+describe('agent-3d AR wiring', () => {
+ it('imports the shared best-effort USDZ builder instead of duplicating it', () => {
+ expect(element).toContain("from './usdz-animated.js'");
+ expect(element).toContain('buildBestEffortArUsdz(');
+ });
+
+ it('only generates an on-device USDZ when ios-src was not already supplied', () => {
+ expect(element).toMatch(/let usdzUrl = this\.getAttribute\('ios-src'\) \|\| null;[\s\S]{0,200}if \(!usdzUrl/);
+ });
+
+ it('emits agent:ar-status while generating and agent:ar-ready once armed', () => {
+ expect(element).toContain("'agent:ar-status'");
+ expect(element).toContain("'agent:ar-ready'");
+ });
+
+ it('cancels a stale AR/variant setup against a reboot via _bootToken', () => {
+ expect(element).toContain('this._bootToken++');
+ expect(element).toMatch(/if \(token !== this\._bootToken\) return;/);
+ });
+
+ it('revokes a generated USDZ object URL on teardown', () => {
+ expect(element).toMatch(/_teardown\(\)\s*\{[\s\S]{0,400}URL\.revokeObjectURL\(this\._generatedUsdzUrl\)/);
+ });
+});
+
+describe('agent-3d hotspot slot', () => {
+ it('renders a real <slot name="hotspot"> over the stage', () => {
+ expect(element).toContain("hotspotSlot.name = 'hotspot'");
+ });
+
+ it('projects each assigned hotspot element to screen space every frame', () => {
+ expect(element).toContain('_updateHotspots()');
+ expect(element).toContain('projectToScreen(worldPos)');
+ });
+
+ it('flies the camera to a saved orbit on hotspot click via data-camera-orbit', () => {
+ expect(element).toContain('data-camera-orbit');
+ expect(element).toContain('setCameraOrbit(');
+ });
+});
+
+describe('Viewer AR surface (src/viewer.js)', () => {
+ it('setARTarget accepts an ar-modes allow-list and ar-placement', () => {
+ expect(viewer).toMatch(/setARTarget\(glbUrl, usdzUrl = null, \{ modes, placement \} = \{\}\)/);
+ });
+
+ it('exposes canActivateAR and activateAR() honoring the configured modes', () => {
+ expect(viewer).toContain('get canActivateAR()');
+ expect(viewer).toContain('async activateAR()');
+ expect(viewer).toContain('this._arModes');
+ });
+
+ it('exposes setCameraOrbit() and projectToScreen() for hotspots', () => {
+ expect(viewer).toContain('setCameraOrbit(thetaDeg, phiDeg, radius, target');
+ expect(viewer).toContain('projectToScreen(worldPos)');
+ });
+});
+
+describe('Scene Viewer wall placement (src/ar/scene-viewer.js)', () => {
+ it('sets enable_vertical_placement only for wall placement', () => {
+ expect(sceneViewer).toContain("placement === 'wall'");
+ expect(sceneViewer).toContain('enable_vertical_placement');
+ });
+});
diff --git a/tests/e2e/agent-3d-ar.spec.js b/tests/e2e/agent-3d-ar.spec.js
new file mode 100644
index 000000000..6172a35b2
--- /dev/null
+++ b/tests/e2e/agent-3d-ar.spec.js
@@ -0,0 +1,186 @@
+import { test, expect } from '@playwright/test';
+import { Document, NodeIO } from '@gltf-transform/core';
+import { ALL_EXTENSIONS, KHRMaterialsVariants } from '@gltf-transform/extensions';
+
+// Work order 073: <agent-3d>'s model-viewer-compatible AR/variant/hotspot
+// contract. Drives a real Chromium against the dev server's /src/element.js
+// (not the published CDN bundle, which only reflects today's source after a
+// deploy) using public/agent-3d-ar-harness.html.
+//
+// Fidelity: the GLB is a real glTF-Transform-built KHR_materials_variants
+// asset, loaded over the real network by the real GLTFLoader and parsed a
+// second time by the real khr-variants.js controller, exactly as production
+// does. Only the GLB's own bytes are route-intercepted, because a durable
+// avatar record is per-deployment DB state, not something a test box has
+// (same rationale as tests/e2e/embodiment-embed.spec.js's persona stub).
+
+const GLB_URL = '**/agent-3d-ar-harness-variants.glb';
+const IOS_UA =
+ 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1';
+
+async function buildVariantGlb() {
+ const doc = new Document();
+ const buffer = doc.createBuffer();
+
+ const positions = doc
+ .createAccessor()
+ .setType('VEC3')
+ .setArray(new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]))
+ .setBuffer(buffer);
+ const prim = doc.createPrimitive().setAttribute('POSITION', positions);
+
+ const matRed = doc.createMaterial('Red').setBaseColorFactor([1, 0, 0, 1]);
+ const matBlue = doc.createMaterial('Blue').setBaseColorFactor([0, 0, 1, 1]);
+ prim.setMaterial(matRed);
+
+ const variantExt = doc.createExtension(KHRMaterialsVariants);
+ const varRed = variantExt.createVariant('Red');
+ const varBlue = variantExt.createVariant('Blue');
+ const mapRed = variantExt.createMapping().setMaterial(matRed).addVariant(varRed);
+ const mapBlue = variantExt.createMapping().setMaterial(matBlue).addVariant(varBlue);
+ const mappingList = variantExt.createMappingList().addMapping(mapRed).addMapping(mapBlue);
+ prim.setExtension('KHR_materials_variants', mappingList);
+
+ const mesh = doc.createMesh('VariantTestMesh').addPrimitive(prim);
+ const node = doc.createNode().setMesh(mesh);
+ const scene = doc.createScene().addChild(node);
+ doc.getRoot().setDefaultScene(scene);
+
+ const io = new NodeIO().registerExtensions(ALL_EXTENSIONS);
+ return io.writeBinary(doc);
+}
+
+function watchErrors(page) {
+ const errors = [];
+ page.on('pageerror', (err) => errors.push(String(err?.message || err)));
+ return errors;
+}
+
+test.describe('agent-3d AR/variant/hotspot contract', () => {
+ test('variant switching works on a real KHR_materials_variants GLB', async ({ page }) => {
+ const glbBytes = await buildVariantGlb();
+ await page.route(GLB_URL, (route) =>
+ route.fulfill({ status: 200, contentType: 'model/gltf-binary', body: Buffer.from(glbBytes) }),
+ );
+ const errors = watchErrors(page);
+
+ await page.goto('/agent-3d-ar-harness.html', { waitUntil: 'domcontentloaded' });
+
+ await expect
+ .poll(() => page.evaluate(() => document.getElementById('a3d').availableVariants), {
+ timeout: 60_000,
+ })
+ .toEqual(['Red', 'Blue']);
+
+ const colorOf = () =>
+ page.evaluate(() => {
+ let mesh = null;
+ document.getElementById('a3d')._viewer.scene.traverse((o) => {
+ if (o.isMesh && o.name === 'VariantTestMesh') mesh = o;
+ });
+ return mesh.material.color.getHexString();
+ });
+
+ expect(await colorOf()).toBe('ff0000');
+
+ const changed = page.evaluate(
+ () =>
+ new Promise((resolve) => {
+ document.getElementById('a3d').addEventListener('agent:variant-changed', (e) => resolve(e.detail), {
+ once: true,
+ });
+ }),
+ );
+ await page.evaluate(() => {
+ document.getElementById('a3d').variantName = 'Blue';
+ });
+ expect(await changed).toEqual({ name: 'Blue', requested: 'Blue', ok: true });
+ expect(await colorOf()).toBe('0000ff');
+
+ expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+ });
+
+ test('ar + ios-src arms canActivateAR and launches Quick Look via the rel=ar anchor', async ({ browser }) => {
+ const context = await browser.newContext({ userAgent: IOS_UA });
+ const page = await context.newPage();
+ try {
+ const glbBytes = await buildVariantGlb();
+ await page.route(GLB_URL, (route) =>
+ route.fulfill({ status: 200, contentType: 'model/gltf-binary', body: Buffer.from(glbBytes) }),
+ );
+ // Quick Look is Safari-only behavior: real Safari intercepts the
+ // rel="ar" anchor click and never navigates, but Chromium (even with
+ // the iOS UA spoofed) treats it as a plain link and follows it. A
+ // capturing document-level listener installed before the page's own
+ // scripts run stops that follow-through so the test can observe the
+ // real anchor the product code built without losing the page.
+ await page.addInitScript(() => {
+ document.addEventListener(
+ 'click',
+ (e) => {
+ if (e.target.closest?.('a[rel="ar"]')) e.preventDefault();
+ },
+ { capture: true },
+ );
+ });
+ const errors = watchErrors(page);
+
+ await page.goto('/agent-3d-ar-harness.html', { waitUntil: 'domcontentloaded' });
+
+ await expect
+ .poll(() => page.evaluate(() => document.getElementById('a3d').canActivateAR), { timeout: 60_000 })
+ .toBe(true);
+
+ await page.evaluate(() => document.getElementById('a3d').activateAR());
+
+ expect(await page.evaluate(() => document.querySelector('a[rel="ar"]')?.getAttribute('href'))).toBe(
+ '/agent-3d-ar-harness-placeholder.usdz',
+ );
+
+ expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+ } finally {
+ await context.close();
+ }
+ });
+
+ test('clicking a hotspot flies the camera to its saved orbit', async ({ page }) => {
+ const glbBytes = await buildVariantGlb();
+ await page.route(GLB_URL, (route) =>
+ route.fulfill({ status: 200, contentType: 'model/gltf-binary', body: Buffer.from(glbBytes) }),
+ );
+ const errors = watchErrors(page);
+
+ await page.goto('/agent-3d-ar-harness.html', { waitUntil: 'domcontentloaded' });
+ await expect
+ .poll(() => page.evaluate(() => document.getElementById('a3d').availableVariants.length), {
+ timeout: 60_000,
+ })
+ .toBeGreaterThan(0);
+
+ // The hotspot layer only positions assigned elements once the viewer is
+ // rendering frames; wait for a real projected position before clicking.
+ await expect
+ .poll(() => page.evaluate(() => document.getElementById('hs').style.transform))
+ .toMatch(/translate/);
+
+ const before = await page.evaluate(() => {
+ const v = document.getElementById('a3d')._viewer;
+ return { pos: v.activeCamera.position.toArray(), target: v.controls.target.toArray() };
+ });
+
+ // The hotspot's projected screen position depends on the default camera
+ // framing, which can land outside Playwright's own viewport bounds even
+ // though the element is correctly positioned over the canvas; dispatch a
+ // real click directly rather than requiring on-screen pointer coordinates.
+ await page.evaluate(() => document.getElementById('hs').click());
+ await page.waitForTimeout(900);
+
+ const after = await page.evaluate(() => {
+ const v = document.getElementById('a3d')._viewer;
+ return { pos: v.activeCamera.position.toArray(), target: v.controls.target.toArray() };
+ });
+
+ expect(after.pos).not.toEqual(before.pos);
+ expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+ });
+});
diff --git a/tests/e2e/ar-page.spec.js b/tests/e2e/ar-page.spec.js
new file mode 100644
index 000000000..6dc1c1ba7
--- /dev/null
+++ b/tests/e2e/ar-page.spec.js
@@ -0,0 +1,65 @@
+import { test, expect } from '@playwright/test';
+
+/**
+ * pages/ar.html (/avatars/:id/ar, /agents/:id/ar): the dedicated AR
+ * experience page. Work order 073 retired its third-party model-viewer CDN
+ * dependency in favor of <agent-3d ar>; this proves that end to end against
+ * a real Chromium: no request ever reaches the CDN, the element mounts a
+ * real canvas, and the existing "Place in your space" button wiring
+ * (canActivateAR / activateAR(), unchanged in src/ar-page.js) still arms
+ * once <agent-3d>'s own agent:ar-ready event fires.
+ *
+ * Avatar auth/DB state is stubbed exactly as tests/e2e/avatar-edit.spec.js
+ * does (same real public GLB), because a durable avatar record is
+ * per-deployment DB state, not something a test box has.
+ */
+
+const AVATAR_FIXTURE = {
+ avatar: {
+ id: 'test-avatar',
+ owner_id: 'test-owner',
+ name: 'Test Avatar',
+ model_url: '/avatars/default.glb',
+ },
+};
+
+const THIRD_PARTY_VIEWER_HOSTS = [/cdn\.jsdelivr\.net/, /unpkg\.com/, /cdnjs\.cloudflare\.com/];
+
+test('the AR page never requests a third-party viewer CDN and mounts <agent-3d>', async ({ page }) => {
+ await page.route('**/api/avatars/test-avatar', (route) => route.fulfill({ json: AVATAR_FIXTURE }));
+
+ // pages/ar.html loads <agent-3d> from the published
+ // https://three.ws/agent-3d/latest/agent-3d.js CDN bundle, same as every
+ // real page: that bundle only reflects today's source after a deploy.
+ // Redirect it to this run's own /src/element.js so the test proves the
+ // actual wiring just shipped, not whatever is currently in production.
+ await page.route('**/agent-3d/latest/agent-3d.js', (route) =>
+ route.fulfill({ status: 302, headers: { location: new URL('/src/element.js', process.env.E2E_ORIGIN).toString() } }),
+ );
+
+ const thirdPartyRequests = [];
+ page.on('request', (req) => {
+ const url = req.url();
+ if (THIRD_PARTY_VIEWER_HOSTS.some((re) => re.test(url))) thirdPartyRequests.push(url);
+ });
+ const errors = [];
+ page.on('pageerror', (err) => errors.push(String(err?.message || err)));
+
+ await page.goto('/avatars/test-avatar/ar', { waitUntil: 'domcontentloaded' });
+
+ // The element that replaced <model-viewer>, not the CDN component.
+ await expect(page.locator('agent-3d#ar-viewer')).toBeAttached();
+ await expect(page.locator('model-viewer')).toHaveCount(0);
+
+ // It really boots: a WebGL canvas renders inside the element's shadow DOM.
+ await expect
+ .poll(() => page.evaluate(() => document.getElementById('ar-viewer')?.shadowRoot?.querySelector('canvas')))
+ .toBeTruthy();
+
+ // The existing launch button wiring (src/ar-page.js, unchanged) still arms
+ // once <agent-3d>'s own agent:ar-ready event fires.
+ await expect(page.locator('#ar-launch-btn')).toBeEnabled({ timeout: 60_000 });
+
+ expect(thirdPartyRequests, `unexpected third-party requests: ${thirdPartyRequests.join(', ')}`).toEqual([]);
+ expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+});
diff --git a/tests/khr-variants.test.js b/tests/khr-variants.test.js
new file mode 100644
index 000000000..800cbce62
--- /dev/null
+++ b/tests/khr-variants.test.js
@@ -0,0 +1,144 @@
+/**
+ * src/khr-variants.js: KHR_materials_variants runtime support.
+ *
+ * three.js's GLTFLoader has no native support for this extension, so these
+ * tests build a real glTF-Transform Document with two materials and two
+ * variants, write it to GLB bytes, load those bytes through three.js's own
+ * GLTFLoader (exactly as <agent-3d> does), and verify the controller swaps
+ * the live THREE.Mesh's material to match the glTF-Transform mapping table.
+ * No mocks: every byte is a real binary glTF asset.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { Document, NodeIO } from '@gltf-transform/core';
+import { ALL_EXTENSIONS, KHRMaterialsVariants } from '@gltf-transform/extensions';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+
+import { parseVariantTable, createVariantController } from '../src/khr-variants.js';
+
+function loadThree(bytes) {
+ return new Promise((resolve, reject) => {
+ new GLTFLoader().parse(
+ bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
+ '',
+ resolve,
+ reject,
+ );
+ });
+}
+
+async function buildVariantGlb() {
+ const doc = new Document();
+ const buffer = doc.createBuffer();
+
+ const positions = doc
+ .createAccessor()
+ .setType('VEC3')
+ .setArray(new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]))
+ .setBuffer(buffer);
+ const prim = doc.createPrimitive().setAttribute('POSITION', positions);
+
+ const matRed = doc.createMaterial('Red').setBaseColorFactor([1, 0, 0, 1]);
+ const matBlue = doc.createMaterial('Blue').setBaseColorFactor([0, 0, 1, 1]);
+ prim.setMaterial(matRed);
+
+ const variantExt = doc.createExtension(KHRMaterialsVariants);
+ const varRed = variantExt.createVariant('Red');
+ const varBlue = variantExt.createVariant('Blue');
+ const mapRed = variantExt.createMapping().setMaterial(matRed).addVariant(varRed);
+ const mapBlue = variantExt.createMapping().setMaterial(matBlue).addVariant(varBlue);
+ const mappingList = variantExt.createMappingList().addMapping(mapRed).addMapping(mapBlue);
+ prim.setExtension('KHR_materials_variants', mappingList);
+
+ const mesh = doc.createMesh().addPrimitive(prim);
+ const node = doc.createNode().setMesh(mesh);
+ const scene = doc.createScene().addChild(node);
+ doc.getRoot().setDefaultScene(scene);
+
+ const io = new NodeIO().registerExtensions(ALL_EXTENSIONS);
+ return io.writeBinary(doc);
+}
+
+async function buildPlainGlb() {
+ const doc = new Document();
+ const buffer = doc.createBuffer();
+ const positions = doc
+ .createAccessor()
+ .setType('VEC3')
+ .setArray(new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]))
+ .setBuffer(buffer);
+ const prim = doc.createPrimitive().setAttribute('POSITION', positions);
+ prim.setMaterial(doc.createMaterial('Plain'));
+ const mesh = doc.createMesh().addPrimitive(prim);
+ const node = doc.createNode().setMesh(mesh);
+ const scene = doc.createScene().addChild(node);
+ doc.getRoot().setDefaultScene(scene);
+ const io = new NodeIO().registerExtensions(ALL_EXTENSIONS);
+ return io.writeBinary(doc);
+}
+
+describe('parseVariantTable', () => {
+ it('reads variant names and the material mapping from a real GLB', async () => {
+ const bytes = await buildVariantGlb();
+ const table = await parseVariantTable(bytes);
+ expect(table).not.toBeNull();
+ expect(table.names).toEqual(['Red', 'Blue']);
+ expect(table.primitives).toHaveLength(1);
+ expect(table.primitives[0].byVariant.get('Red')).toBe(0);
+ expect(table.primitives[0].byVariant.get('Blue')).toBe(1);
+ expect(table.primitives[0].defaultMaterialIndex).toBe(0);
+ });
+
+ it('returns null for a GLB that does not use the extension', async () => {
+ const bytes = await buildPlainGlb();
+ expect(await parseVariantTable(bytes)).toBeNull();
+ });
+
+ it('returns null for bytes that are not a valid glTF/GLB', async () => {
+ expect(await parseVariantTable(new Uint8Array([1, 2, 3]))).toBeNull();
+ });
+});
+
+describe('createVariantController', () => {
+ it('swaps the live THREE.Mesh material when selecting a variant', async () => {
+ const bytes = await buildVariantGlb();
+ const gltf = await loadThree(bytes);
+ const controller = await createVariantController(bytes, gltf);
+
+ expect(controller).not.toBeNull();
+ expect(controller.names).toEqual(['Red', 'Blue']);
+ expect(controller.current).toBeNull();
+
+ let mesh = null;
+ gltf.scene.traverse((o) => {
+ if (o.isMesh) mesh = o;
+ });
+ expect(mesh.material.color.getHex()).toBe(0xff0000);
+
+ const ok = await controller.select('Blue');
+ expect(ok).toBe(true);
+ expect(controller.current).toBe('Blue');
+ expect(mesh.material.color.getHex()).toBe(0x0000ff);
+
+ const restored = await controller.select(null);
+ expect(restored).toBe(false);
+ expect(controller.current).toBeNull();
+ expect(mesh.material.color.getHex()).toBe(0xff0000);
+ });
+
+ it('select() with an unknown name restores the default and reports false', async () => {
+ const bytes = await buildVariantGlb();
+ const gltf = await loadThree(bytes);
+ const controller = await createVariantController(bytes, gltf);
+
+ const ok = await controller.select('Nonexistent');
+ expect(ok).toBe(false);
+ expect(controller.current).toBeNull();
+ });
+
+ it('returns null for a GLB without the extension', async () => {
+ const bytes = await buildPlainGlb();
+ const gltf = await loadThree(bytes);
+ expect(await createVariantController(bytes, gltf)).toBeNull();
+ });
+});