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
chore(prompts): retire work order 073, agent-3d AR/variant/hotspot contract shipped and verified
nirholasa7a8bc95e561
diff --git a/prompts/finish/073-best3d-07-agent3d-ar-viewer-contract.md b/prompts/finish/073-best3d-07-agent3d-ar-viewer-contract.mddeleted file mode 100644index 62cc84442..000000000--- a/prompts/finish/073-best3d-07-agent3d-ar-viewer-contract.md+++ /dev/null@@ -1,54 +0,0 @@-# best3d 07: The <agent-3d> AR and viewer contract--How to run: paste this file's repo path into a fresh Claude Code chat in this repository and say "run this work order". Runnable now, no gate.--## Operating clause (binding)--- Read CLAUDE.md first, then [_context/best3d-00-CONTEXT.md](_context/best3d-00-CONTEXT.md). CLAUDE.md overrides everything, including this file.-- Finish 100% in this session. Never end the turn with a question, an option list, or an unexecuted plan. A judgment call goes in one line of the final report.-- The only permitted stops are the CLAUDE.md stop-and-ask gates: irreversible spend, git push or deploy, external posting, committing content that names a crypto project other than $THREE, destroying unrecoverable data. Batch every such ask into ONE message at the end.-- Commercial vendors are "Vendor A, B..." in every committed file. Open-source projects are named and credited.-- Verify each upstream license from its LICENSE file before adopting (see the license rules in the context file). Reference-only means build our own, never copy code.-- No mocks, fake data, placeholders, unfinished-work markers or commented-out code. The em-dash and en-dash characters are banned.-- Concurrent agents share this worktree: stage explicit paths only and commit finished work promptly.-- Before committing, run `npm run check:rules -- --paths <files you touched>`. It must exit 0.--## Why this matters--model-viewer (Apache-2.0) defines the contract the market expects: ar-modes, on-device USDZ, ar-placement, variant-name, hotspots, poster and skeleton loading. `<agent-3d>` has none, and `/ar` loads a third-party viewer from a CDN.--Source of the finding: [docs/research/3d-landscape-2026-10.md](../../docs/research/3d-landscape-2026-10.md).--## Step 0: re-derive the current state-- grep -n "model-viewer" -r pages src public --include=*.html --include=*.js | head; sed -n 1,40p src/usdz-pipeline.js--## Tasks--1. Add attributes: `ar`, `ar-modes`, `ar-placement`, `variant-name` (KHR_materials_variants via the gltf-transform variants API), `poster`, and hotspot slots with saved camera views.-2. AR launch: WebXR where available, Quick Look via on-device USDZ from `src/usdz-pipeline.js`, Scene Viewer intent on Android.-3. Retire the CDN viewer on `/ar`; use the element.-4. Spec the attributes in `specs/`; update embed docs; add tests; changelog.--## Definition of done--- [ ] `/ar` makes no request to a third-party viewer CDN.-- [ ] Variant switching works on a real KHR_materials_variants GLB.-- [ ] `npm test` passes for the touched areas and `npm run audit:docs` reports nothing new.-- [ ] Docs, STRUCTURE.md row where a surface or directory landed, and a `data/changelog.json` entry (then `npm run build:pages`).--## Never blocked--| Blocker | Resolution (act, do not ask) |-|---|---|-| Missing credential or env var | Follow the credential row of the CLAUDE.md self-unblock playbook; read it from the Cloud Run service with `node scripts/read-service-env.mjs`. |-| GPU quota | File the increase, route to another region or class, continue. |-| Upstream repo moved or changed license | Re-read the LICENSE file; if no longer permissive, switch to reference-only and build our own. |-| Weights missing | Stage them from `gs://three-ws-model-weights` or the upstream README. |--## Close out (required)--1. Verify every Definition of done line with the actual command output in front of you. Never claim a line you did not verify.-2. Commit with explicit paths and a subject that describes the diff (`type(scope): what changed and why a reader cares`).-3. If every line passes, delete this file in that commit (`git rm prompts/finish/073-best3d-07-agent3d-ar-viewer-contract.md`) and append a dated entry to [_context/best3d-PROGRESS.md](_context/best3d-PROGRESS.md) with the commit SHAs. If an owner action or outside party is the last step, finish everything else, leave this file, and log exactly what remains and who owns it.-4. Final report: what step 0 measured; what changed (files and SHAs); evidence per Definition of done line; the single batched owner message if any; one-line judgment calls. No trailing questions.diff --git a/prompts/finish/_context/best3d-PROGRESS.md b/prompts/finish/_context/best3d-PROGRESS.mdindex c9681d254..54b9c80f4 100644--- a/prompts/finish/_context/best3d-PROGRESS.md+++ b/prompts/finish/_context/best3d-PROGRESS.md@@ -39,3 +39,15 @@ Append a dated entry per closed order, with commit SHAs.- `npm run check:rules -- --paths <all touched files>` exit 0 (one real finding caught and fixed first: 2 em-dash characters in `ThreeWsClient.cs` XML doc comments, replaced with commas).- One judgment call: `specs/ENGINE_BRIDGE.md` originally described `generate_colliders` as using "the engine's own convex-hull generator" for all three engines. Unity (`MeshCollider.convex`) and Godot (`ConvexPolygonShape3D`) do generate a convex hull; Unreal's importer instead builds a bounding-box proxy (`UBodySetup`/`FKBoxElem`), since I could not confidently cite a stable UE5 convex-hull-generation API without compile-time verification and a fabricated API call would be worse than a simpler, definitely-correct one. Reworded the spec to state the per-engine mechanism precisely instead of overclaiming convex-hull parity.- Commits: `40b30a5d0` (spec, three packages, docs, STRUCTURE.md row, pages.json/changelog.json entries, rebuilt artifacts).+- 2026-10-12: order 073 (`<agent-3d>` AR/viewer contract) built, tested and committed; closed.+ - Step 0: `grep -n "model-viewer" -r pages src public` found the CDN `<script>` and `<model-viewer>` element in `pages/ar.html` only (`pages/ar-view.html`'s `/ar/view`, a separate generic "place any model" feature, was judged out of scope: the order's own docstring in `src/ar-page.js` names `/avatars/:id/ar` and `/agents/:id/ar` as the target). `src/usdz-pipeline.js` already had a static USDZ exporter; `src/usdz-animated.js` (same turn) added an animated-first `buildBestEffortArUsdz` that falls back to it.+ - Task 1-2: `src/element.js` gained `ar`, `ar-modes`, `ar-placement`, `ios-src`, `variant-name` observed attributes, `canActivateAR`/`activateAR()`/`availableVariants`/`variantName` JS API mirroring `<model-viewer>`, a real `KHR_materials_variants` reader (`src/khr-variants.js`, a second glTF-Transform parse of the raw GLB bytes cross-referenced against three.js GLTFLoader's material associations, since GLTFLoader has no native support for the extension), and a `slot="hotspot"` layer (`data-position`/`data-normal` projected to screen space every frame, `data-camera-orbit`/`data-camera-target` flying the orbit camera on click). `src/viewer.js` added `setARTarget(glbUrl, usdzUrl, {modes, placement})`, `canActivateAR`/`activateAR()` honoring the configured `ar-modes` allow-list (WebXR, Scene Viewer intent, Quick Look anchor), and `setCameraOrbit()`/`projectToScreen()` for hotspots. `src/ar/scene-viewer.js` added `enable_vertical_placement` for `ar-placement="wall"`.+ - Task 3: `pages/ar.html` no longer loads any third-party CDN; its `<model-viewer>` element and CSS were replaced with `<agent-3d id="ar-viewer" eager ar ar-modes="webxr scene-viewer quick-look" ar-placement="floor">`. `src/ar-page.js` dropped its hand-rolled USDZ generation (`applyUsdzSrc`/`buildArUsdz`/`generateUsdz` deleted) in favor of the element's own `agent:ar-status`/`agent:ar-ready` events.+ - Task 4: `specs/EMBED_SPEC.md` documents the five new attributes, the hotspot slot contract, four new events, and the AR/variant JS API. `data/changelog.json` got the user-facing entry; `npm run build:pages` regenerated `CHANGELOG.md` and `public/changelog*.json`/`.xml`/`features.json`/`sitemap/index.html`. No `STRUCTURE.md` row: both existing rows (`<agent-3d>` web component; the AR lane under the entity-studio row) already cover these surfaces without naming the retired CDN, so neither needed correction, and no new top-level surface or directory landed (the new `public/agent-3d-ar-harness.html` Playwright fixture follows the same undocumented-harness precedent as `public/studio-deposit-harness.html`).+ - Tests, real assets, no mocks: `tests/khr-variants.test.js` and `tests/agent-3d-ar-contract.test.js` build real glTF-Transform GLBs and load them through three.js's own `GLTFLoader` (54/54 passed with the two existing usdz test files that import the touched modules). `tests/e2e/agent-3d-ar.spec.js` drives real Chromium against a new local-source-importing harness page (every real page's `<agent-3d>` ships from the production CDN bundle, which only reflects source after a deploy, so a harness importing `src/element.js` directly was required to exercise today's code) and proves variant switching on a real `KHR_materials_variants` GLB, Quick Look's `rel="ar"` anchor arming under an iOS UA, and hotspot click-to-fly-camera (3 passed, re-run `--repeat-each=2` for stability). `tests/e2e/ar-page.spec.js` drives the real `pages/ar.html` end to end, redirecting its CDN script request to local `src/element.js` (`page.route('**/agent-3d/latest/agent-3d.js', ...)`, a glob pattern, not a literal URL string: the literal form silently failed to intercept the redirect chain) and confirms zero third-party-CDN requests, a real canvas, and the launch button arming via `agent:ar-ready`.+ - DoD line 1 (`/ar` makes no third-party CDN request): verified by `tests/e2e/ar-page.spec.js` (1 passed), which fails its own `thirdPartyRequests` assertion if one occurs.+ - DoD line 2 (variant switching on a real KHR_materials_variants GLB): verified by `tests/khr-variants.test.js` and the first `tests/e2e/agent-3d-ar.spec.js` test, both against a real glTF-Transform-authored GLB with two materials and two variants.+ - DoD line 3 (`npm test` passes for touched areas; `npm run audit:docs` reports nothing new): full `npx vitest run` showed 39 failed files / 73 failed tests out of 2378/35388, all pre-existing and unrelated (e.g. `tests/api/v1-rest-router.test.js`'s idempotency-key tests, last touched in an unrelated commit), the same pre-existing concurrent-agent-drift pattern logged for prior orders in this campaign; a targeted run of every touched/related vitest file plus the new Playwright specs passed in full. `npm run audit:docs` reported its pre-existing 16 findings (unpublished docs, dead links in unrelated `apps/hq`/`hubs/*` trees), none naming this order's files.+ - `npm run check:rules -- --paths <all touched files>` exit 0 (one real finding caught and fixed first: `check-rules`'s commented-out-code heuristic flagged a prose line in `specs/EMBED_SPEC.md`, `// AR (mirrors <model-viewer>'s names)`, because it parsed as a comment ending in a function-call close-paren; reworded to `// AR, mirrors <model-viewer>'s own names`).+ - One judgment call: `pages/ar-view.html` (`/ar/view`) also loads the model-viewer CDN but is a separate, generic "place any 3D model" feature unrelated to the avatar/agent AR experience this order targets; left untouched as out of scope rather than silently expanding or silently ignoring it.+ - Commits: `a9c1e6032` (element/viewer/scene-viewer/ar-page/ar.html, khr-variants.js, usdz-animated.js em-dash fix, specs, changelog, tests, harness fixture, rebuilt artifacts).