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
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.mdindex 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.jsonindex 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.htmlindex 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&t=AR+Forge&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.&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.htmlnew file mode 100644index 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.jsonindex 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.jsonindex 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.xmlindex 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><agent-3d> 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:<agent-3d> 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><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.</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.jsonindex 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.htmlindex 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&t=Sitemap&d=Human-readable+index+of+every+page+on+three.ws.&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&t=Sitemap&d=Human-readable+index+of+every+page+on+three.ws.&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 →</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 →</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> “<span id="sm-empty-q"></span>”.</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.mdindex 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+// Skillsawait 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.jsindex 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.jsindex 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.jsindex 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. Theposter image (when supplied) fills the frame; otherwise the host seestransparent 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.jsnew file mode 100644index 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.jsindex 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.jsindex 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 WebXRif (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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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();+ });+});