Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

chore(prompts): retire order 438, agent3d/avatar-page/marketplace GLB load fallback shipped

nirholas5806b9247dfa
diff --git a/prompts/finish/438-auto-agent3d-glb-load-fallback.md b/prompts/finish/438-auto-agent3d-glb-load-fallback.md
deleted file mode 100644
index 7d1aa634c..000000000
--- a/prompts/finish/438-auto-agent3d-glb-load-fallback.md
+++ /dev/null
@@ -1,106 +0,0 @@
-# 438. Give agent-3d and the entity-studio/marketplace viewers a client-side fallback when the body GLB fails to load
-
-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, no owner action required.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first. 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.
-- This is a bug fix: follow the test-first rule (CLAUDE.md, "Bug fixes are test-first"). Write the failing test first, confirm it fails for the stated reason, then fix the code, then confirm it passes. Commit the test with the fix.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates (spend/on-chain writes, push/deploy, posting externally, committing content referencing a crypto project other than `$THREE`, destroying unrecoverable data). This order touches none of them.
-- Concurrent agents share this worktree: stage explicit paths only (never `git add -A` or `git add .`), re-check `git status` and `git diff --staged` before committing.
-- The em-dash and en-dash characters are banned in everything you write.
-
-## Why this matters (measured 2026-10-25)
-
-Production's Cloudflare R2 bucket is still disabled at the account level:
-
- curl -s https://three.ws/api/healthz | python3 -c "import json,sys; d=json.load(sys.stdin); print([s for s in d['subsystems']['subsystems'] if s['name']=='object_storage'])"
- # {'name': 'object_storage', 'status': 'down', 'detail': 'bucket unreachable: Please enable R2 through the Cloudflare Dashboard.', ...}
-
-This is already tracked and owner-gated (`prompts/RUN-ORDER.md` OWNER-ACTIONS row 36). **This order does not touch R2.** It closes a separate, code-fixable gap: when the GLB body fails to load for any reason (this outage, a future one, or a single corrupt/missing object), three client surfaces show the user a dead end instead of recovering, even though the app already ships a local default avatar asset that does not depend on R2 at all.
-
-Live confirmation right now:
-
- curl -s -o /dev/null -w "HTTP %{http_code}\n" "https://three.ws/api/avatars/d39c5db1-779c-47eb-9c8c-e30231519cf3/glb"
- # HTTP 502
-
-Blast radius, from the already-completed, solo-reverified full-site sweep (`reports/page-audit-2026-10-24T20-43-27-109Z.json`, generated by `npm run audit:web`):
-
- python3 -c "
- import json
- d = json.load(open('reports/page-audit-2026-10-24T20-43-27-109Z.json'))
- routes = set()
- for p in d['pages']:
- for f in p.get('findings', []):
- if '/api/avatars/' in json.dumps(f) and 'glb' in json.dumps(f):
- routes.add(p['route'])
- print(len(routes))
- "
- # 538
-
-`HTTP 502 .../api/avatars/<id>/glb` is the single highest-blast-radius finding in the entire 1150-route audit (538 distinct routes), well ahead of every other finding type including the image-thumbnail 502s that order 437 already fixed (437's biggest single item was 69 routes). The same sweep logged `[agent-3d] boot failed TypeError: Failed to fetch` 64 times across the run, and a real, visible, unrecoverable error banner reading exactly **"Failed to load 3D model."** on at least six live pages with no retry or fallback affordance:
-
- /agents/00033e3e-2640-40d4-81cc-98c6c98c51a1
- /agents/0119e94c-48ca-485b-ad0c-1f2e28e3f583
- /avatars/0382d0f7-b430-478b-9ba8-cff591d7d862
- /marketplace/agents/00da7deb-0cc8-44e9-b9ba-f659835b604e
- /marketplace/agents/0f290230-48e0-4a39-9b32-3eb8d10a29a9
- /marketplace/agents/20ecfcc6-849e-4c12-b618-4c7c344cbc43
-
-By contrast, `/u/<username>` pages already degrade gracefully today ("Couldn't load the avatar... You can still chat or open the full walk") and the `/walk` companion widget already falls back client-side to a bundled `robot` asset on a GLB load failure (`walk-sdk/src/internal/load-avatar.js:135-143`, confirmed live via the console warning `[walk] avatar "..." failed to load, falling back to "robot" fetch`), which is immune to the R2 outage because `roster.js`'s `robot` entry (`source: 'static'`, `asset: '/animations/robotexpressive.glb'`) resolves to a same-origin static file, not `/api/avatars/:id/glb`. The three surfaces this order targets have no equivalent.
-
-Root cause, traced to exact lines, not guessed:
-
-1. `src/element.js:1957-1983` (the `<agent-3d>` web component's `boot()`): `uriCandidates(manifest.body?.uri)` only produces more than one candidate for `ipfs://`/`ar://` URIs (gateway fan-out). For the normal case, a plain HTTPS URL such as `https://three.ws/api/avatars/<id>/glb`, it returns an array of exactly one entry (`src/ipfs.js`'s `uriCandidates`, locked in by the existing test `tests/ipfs-uri-candidates.test.js:44-46`, `"returns one entry for a plain URL so callers can loop unconditionally"`). So the retry loop at lines 1966-1981 runs once, throws `bodyErr`, and that propagates straight to `boot()`'s catch block at `src/element.js:2448-2461`, which logs `[agent-3d] boot failed` and calls `this._showError(err)` (`src/element.js:3176-3214`, title `"Couldn't load agent"` for a chat-mode instance, or a quiet decoration fallback with no visible recovery for a bare avatar). There is no fallback to `https://three.ws/avatars/default.glb`, even though that exact URL already exists as the manifest-resolution fallback (`_defaultFallbackManifest()`, `src/element.js:2482-2492`) for a *different* failure (resolving the manifest itself, not loading its body). A body-load failure after a manifest was already resolved successfully never reaches that fallback.
-2. `src/avatar-page.js:819-828` (the shared entity-studio controller behind both `/agents/:id` and `/avatars/:id`, per `STRUCTURE.md`'s Entity studio row): the `<model-viewer>` mounted at `src/avatar-page.js:577-603` gets one `error` listener that sets `av-stage-loading`'s text to `'Failed to load 3D model.'` (line 827) and does nothing else. No retry, no fallback `src`, no recovery path.
-3. `src/marketplace.js:1636-1667` (`openAvatarModal`, the modal viewer on `/marketplace`): a programmatically created `<model-viewer>` gets an `error` listener (lines 1663-1667) that overwrites the loading label with `'Failed to load 3D model.'` and nothing else; a 15-second timeout (line 1659) separately writes a "try refreshing" message if `load`/`error` never fires at all. Same gap: no fallback `src`.
-
-The fix in all three places follows the pattern already proven live by `/walk`: on a GLB load failure, if the failing URL is not already the local default avatar, swap to the local default avatar GLB (`https://three.ws/avatars/default.glb`, same URL `_defaultFallbackManifest()` already uses, served from `public/avatars/default.glb` which exists on disk and is bundled with the app, not read through `/api/avatars/:id/glb` or R2) and show an honest, recoverable message instead of a dead end. Only if the fallback asset *also* fails does the final "couldn't load" state apply.
-
-This is distinct from and not already covered by any open order: `401` (vitest), `403` (docs freshness), `433` (account_link_codes migration), `435` (sentiment-pulse LKG), `436` (forge-finalize TTL reap) do not touch `element.js`, `avatar-page.js`, or `marketplace.js`. `437` explicitly named this exact gap in its own Never-blocked table as "a candidate for a future, separately-scoped order" and left `api/avatars/[id]/[action].js`'s `handleGlb` untouched on purpose (a server-side image placeholder cannot stand in for a binary 3D model); this order is that future order, and it fixes the problem client-side instead, matching the pattern that already works for `/walk`.
-
-## Task
-
-1. Re-derive the current state before changing anything:
- - `curl -s -o /dev/null -w "%{http_code}\n" "https://three.ws/api/avatars/d39c5db1-779c-47eb-9c8c-e30231519cf3/glb"` to confirm the live symptom (if it now returns 200, the live outage cleared, but the code gap is still real for the next outage or any single missing/corrupt GLB; proceed with the fix either way and say so in the report).
- - `curl -s -o /dev/null -w "%{http_code}\n" "https://three.ws/avatars/default.glb"` to confirm the fallback target itself is reachable and does not depend on R2 (it is a static file under `public/avatars/default.glb`, served from the app's own origin).
-2. Read `src/element.js` lines 1930-1995 (the body-load loop) and lines 2448-2461 (the boot catch block) and lines 2482-2492 (`_defaultFallbackManifest`) in full.
-3. In `src/element.js`, change the body-load failure path (around line 1982, `if (!loaded) throw bodyErr || new Error(...)`) so that before throwing, if `manifest.body?.uri` is not already `https://three.ws/avatars/default.glb` (compare the resolved candidate, not the raw URI, since IPFS URIs resolve to a gateway URL), it attempts exactly one more load against `https://three.ws/avatars/default.glb` via the same `viewer.load(...)` call used in the loop. On success: set `loadedCandidate`/`loadedGltf` from that result, mark the manifest in memory so this fallback is not retried again this boot (e.g. a local `usedFallbackBody = true` flag used later for logging/telemetry), and `console.warn('[agent-3d] body load failed on %s, falling back to the default avatar', candidate)` mirroring the existing gateway-retry warning style at line 1976. On failure of the fallback too: throw the original `bodyErr` unchanged, so `boot()`'s existing catch/`_showError`/`agent:error` path is reached exactly as it is today (no change to the fully-exhausted case).
-4. Still emit `agent:error` (or a new, additive `agent:body-fallback` event) when the fallback is used, so monitoring/telemetry can see how often this triggers; do not suppress the signal entirely just because the user now sees a working avatar. Keep this additive, do not remove or change the shape of the existing `agent:ready`/`agent:error` events for any other path.
-5. In `src/avatar-page.js`, change the `<model-viewer id="av-viewer">` `error` listener (lines 825-828) so that on the first `error`, if `viewer.src` is not already `https://three.ws/avatars/default.glb`, set `viewer.src = 'https://three.ws/avatars/default.glb'` and update `av-stage-loading`'s text to something honest and recoverable, matching the tone already proven on `/u/<username>` (e.g. `"Couldn't load this avatar's body. Showing a placeholder."`), rather than removing the element. Attach a second, one-time `error` listener for this fallback attempt specifically: if the fallback GLB itself also errors, then show the final `'Failed to load 3D model.'` text (today's behavior, now reached only when both the real asset and the local default both fail). On a successful fallback `load`, remove `av-stage-loading` exactly as the existing `load` listener (lines 820-824) already does.
-6. In `src/marketplace.js`'s `openAvatarModal` (lines 1636-1667), apply the same pattern to the modal `<model-viewer>`: on the first `error`, if `mv.getAttribute('src')` is not already the default GLB, set it to `https://three.ws/avatars/default.glb` and update the progress label to the same honest, recoverable text as task 5, clearing the 15-second timeout's eventual message if the fallback succeeds first. Only show `'Failed to load 3D model.'` if the fallback attempt also errors.
-7. Write the failing tests first.
- - `tests/src/element-boot-race.test.js` already mocks `../../src/viewer.js`'s `Viewer.load()` and drives `boot()` under jsdom (see its existing `vi.mock` setup). Add a new test in that file (or a new sibling file `tests/src/element-body-fallback.test.js` if that keeps the existing file's focus clean) that makes the mocked `Viewer.load()` reject for the real body URL and resolve for `https://three.ws/avatars/default.glb`, boots the element, and asserts: no `_showError` card appears (or `agent:error` for `phase: 'boot'` is not emitted / a new fallback event is emitted instead, matching whichever shape task 4 lands on), and the element reaches its ready state. Run it now against the unfixed code and confirm it fails for the right reason (the element currently shows the error card / emits `agent:error` because there is no fallback).
- - Add a second test in the same file: mock `Viewer.load()` to reject for both the real body URL and the default GLB URL, boot, and assert the existing error path is unchanged (`_showError`/`agent:error` still fires exactly as before). This should already pass before the fix (locks the fully-exhausted boundary); keep it to prove the fix did not touch that case.
- - For `src/avatar-page.js` and `src/marketplace.js`, check whether a jsdom test harness already exists for either file (`grep -rl "avatar-page\|marketplace" tests/src/ tests/`); if one exists, extend it with a `<model-viewer>` `error`-event simulation (dispatch a synthetic `error` event on the mounted/created element, since `<model-viewer>` itself needs no real WebGL for this unit) asserting the `src` swap and message text per tasks 5-6, both for the fallback-succeeds and fallback-also-fails cases. If no harness exists for either file, write a minimal one scoped only to this behavior (do not attempt to test the full page render), following the mocking style already used in `tests/src/element-boot-race.test.js`. Run every new test now and confirm each fails for the stated reason before touching the fix code.
-8. Apply the fixes per tasks 3-6, re-run every test added in task 7 and confirm all pass, then run the full suites that touch these files: `npx vitest run tests/src/element-boot-race.test.js tests/src/element-emit-realm.test.js tests/ipfs-uri-candidates.test.js` plus whichever file(s) task 7 added or extended for `avatar-page.js`/`marketplace.js`.
-9. Run `npm run check:rules -- --paths src/element.js src/avatar-page.js src/marketplace.js` plus the paths of every test file added or changed in task 7, and fix anything it flags.
-10. Read the full diff (`git diff src/element.js src/avatar-page.js src/marketplace.js`, plus the new/changed test files) and confirm every changed line traces to a task above.
-11. This fix cannot be verified against production from this session (no deploy in an evolve lane, and the live R2 outage may or may not still be active by the time this ships). The report must say plainly that the live `/agents/:id`, `/avatars/:id`, and `/marketplace` broken-avatar symptom is unverified-fixed in production until this ships; do not claim the live site already shows the fallback.
-
-## Done when
-
-- `src/element.js`'s body-load failure path falls back once to `https://three.ws/avatars/default.glb` before throwing, and only reaches the existing `_showError`/`agent:error` path if that fallback also fails; the fallback attempt is logged and surfaced via an event so it is observable.
-- `src/avatar-page.js`'s and `src/marketplace.js`'s `<model-viewer>` `error` listeners swap `src` to the default GLB and show a recoverable message on first failure, and only show the final `'Failed to load 3D model.'` text if the fallback GLB also fails.
-- New tests prove the fallback-succeeds case (no error card / fallback event instead of error event) and the fallback-also-fails case (existing error behavior unchanged), for all three surfaces, each confirmed to fail against the pre-fix code first.
-- `npx vitest run tests/src/element-boot-race.test.js tests/src/element-emit-realm.test.js tests/ipfs-uri-candidates.test.js` passes, plus every test file touched or added for `avatar-page.js`/`marketplace.js`.
-- `npm run check:rules -- --paths src/element.js src/avatar-page.js src/marketplace.js` (plus the touched test files) passes.
-- `git diff` reviewed; every changed line traces to a task above.
-- The fix is committed on `evolve` with explicit paths and a commit message naming the bug and the fix.
-- The report states plainly that the live production symptom's actual resolution is unverified until this ships (no deploy happens in this lane).
-- This file is removed, with a dated entry added to `prompts/finish/_context/production-100-PROGRESS.md` citing the fix commit SHA and what was verified.
-
-## Never blocked
-
-| Looks like a blocker | It is not | Do this |
-|---|---|---|
-| "The real fix is re-enabling R2 in the Cloudflare dashboard, so this whole order is owner-gated" | That is a separate, already-tracked fix (`RUN-ORDER.md` OWNER-ACTIONS row 36) for why storage is down. This order fixes what the user sees when any GLB body load fails, R2 outage or not, and needs zero Cloudflare access | Ship the client-side fallback. Do not wait on or reference the R2 dashboard action as a precondition |
-| "`https://three.ws/avatars/default.glb` could itself be down during the same outage, so this doesn't really fix anything" | It is a static file under `public/avatars/default.glb`, served from the app's own build output, not read through `/api/avatars/:id/glb` or any R2 lane; task 1's live curl check confirms this before any code changes | Verify it with the task-1 curl check and proceed; if it is somehow also unreachable, say so plainly in the report, but do not treat it as blocking the code change itself |
-| "This duplicates order 437" | 437 explicitly scoped out GLB/model endpoints and named this exact gap as a future order in its own Never-blocked table; it only ever touched `api/cdn-object.js` (an image-serving endpoint) | Proceed; this order touches `src/element.js`, `src/avatar-page.js`, and `src/marketplace.js`, none of which 437 touched |
-| "There's no existing test harness for `avatar-page.js`/`marketplace.js`'s `<model-viewer>` error handling, so this needs a design decision before it can be test-first" | `tests/src/element-boot-race.test.js` already demonstrates the exact mocking pattern needed (mock the viewer, dispatch/trigger the failure, assert on the resulting DOM/event state) for `element.js`; the same pattern applies directly to a `<model-viewer>` custom element, which needs no real WebGL to receive a dispatched `error` event in jsdom | Write a minimal new test file modeled on `element-boot-race.test.js`'s mocking style, scoped only to the `error`-listener behavior in task 5/6, not a full page render |
-| "The fallback changes what `agent:error` consumers see, which might break something downstream" | Task 4 requires keeping this additive: the existing `agent:ready`/`agent:error` event shapes are unchanged for every path except the new one where a fallback silently succeeds (which previously would have been a hard failure with no event consumers could have relied on receiving `agent:ready` for anyway) | Keep `agent:ready`/`agent:error` shapes unchanged; add a new event or a new field rather than repurposing an existing one if signaling the fallback is needed |
-
-## Report format
-
-State: the measured re-derivation from task 1, the failing tests' first (red) run output for each surface, the fix, the passing test run output, the `check:rules` result, the diff, and the commit SHA. End with one explicit line: "Live production symptom: unverified, pending deploy."
diff --git a/prompts/finish/_context/production-100-PROGRESS.md b/prompts/finish/_context/production-100-PROGRESS.md
index 2c8f897ce..bbfe89c6b 100644
--- a/prompts/finish/_context/production-100-PROGRESS.md
+++ b/prompts/finish/_context/production-100-PROGRESS.md
@@ -1888,3 +1888,17 @@ Verification: `npm run check:rules -- --paths api/cdn-object.js tests/cdn-object
Live production symptom: unverified, pending deploy. This is the evolve lane; no deploy happens here. `/rankings`, `/monitor` and every other page showing a broken `<img>` icon against `/cdn/thumb/*` stay broken until `three-ws-api` is redeployed with this change, at which point the same pages fall back to the flat placeholder instead of a broken-image icon for as long as the R2 outage (OWNER-ACTIONS row 36) lasts.
Left: nothing for this order's own scope. `prompts/finish/437-auto-cdn-image-placeholder-fallback.md` deleted in this closing commit.
+
+## 2026-10-25: order 438 (agent3d/entity-studio/marketplace GLB load fallback) closed
+
+Step 0 re-derived the live symptom: `curl -s -o /dev/null -w "%{http_code}" "https://three.ws/api/avatars/d39c5db1-779c-47eb-9c8c-e30231519cf3/glb"` still returned `502` (the R2 outage, OWNER-ACTIONS row 36, is still live); `curl -s -o /dev/null -w "%{http_code}" "https://three.ws/avatars/default.glb"` returned `200`, confirming the fallback target is reachable and same-origin, independent of R2.
+
+Did: read `src/element.js`'s body-load loop (around line 1960), the `boot()` catch block, and `_defaultFallbackManifest()` in full, plus `src/avatar-page.js`'s and `src/marketplace.js`'s `<model-viewer>` wiring named in the order. Added `src/shared/model-viewer-fallback.js` exporting `DEFAULT_AVATAR_GLB` and `wireModelViewerFallback(viewer, { onFallback, onFinalError })`, a small reusable helper: on a `<model-viewer>`'s first `error`, if its `src` is not already the default avatar, swap to it and call `onFallback`; attach a second one-time `error` listener for that attempt, calling `onFinalError` only if the fallback also fails. Wired this into `src/avatar-page.js`'s `#av-viewer` error listener and `src/marketplace.js`'s `openAvatarModal` modal viewer, both now showing "Couldn't load this avatar's body. Showing a placeholder." on the first failure and the original "Failed to load 3D model." only if the fallback also errors. In `src/element.js`'s body-load loop, added a one-shot fallback attempt against `DEFAULT_AVATAR_GLB` (imported from the new shared module, also now reused by `_defaultFallbackManifest()` instead of a duplicated literal) when every real gateway candidate fails and the candidate list did not already include the default; on success this sets `usedFallbackBody` and emits an additive `agent:body-fallback` event (new event, existing `agent:ready`/`agent:error` shapes unchanged) instead of throwing; on failure of the fallback too, the original `bodyErr` still throws unchanged into the existing `_showError`/`agent:error` path.
+
+Test-first: added `tests/src/element-body-fallback.test.js`, modeled on `tests/src/element-boot-race.test.js`'s mocking style but leaving `src/ipfs.js` unmocked (needed `uriCandidates`'s real single-entry behavior for a plain HTTPS URL). Two cases: fallback-succeeds (mocked `Viewer.load()` rejects the real body URL, resolves the default) and fallback-also-fails (rejects both). Ran both against the pre-fix code first by stashing just `src/element.js`'s diff (`git stash push -u` scoped to that one path, verified by SHA before popping) rather than touching the shared stash blindly: the fallback-succeeds case failed with the stated reason (`agent:error` fired, no `agent:body-fallback`, boot never reached `agent:ready`); the boundary case already passed unchanged, confirmed as the correct pre-existing behavior to preserve. Restored the fix (diffed byte-identical against a pre-stash backup copy) and reran: both pass. Added `tests/src/model-viewer-fallback.test.js` for the new shared helper directly (avatar-page.js and marketplace.js are both unimportable in isolation under jsdom without a full page's markup or a real-entity network round trip, matching the order's own "Never blocked" row on this exact question), confirmed red first by moving the new module aside (`Failed to resolve import`) before writing it, then green after restoring it.
+
+Verification: `npx vitest run tests/src/element-boot-race.test.js tests/src/element-emit-realm.test.js tests/ipfs-uri-candidates.test.js tests/src/element-body-fallback.test.js tests/src/model-viewer-fallback.test.js` passed 21/21, no regressions. `npm run check:rules -- --paths src/element.js src/avatar-page.js src/marketplace.js src/shared/model-viewer-fallback.js tests/src/element-body-fallback.test.js tests/src/model-viewer-fallback.test.js` exited 0. `git diff` reviewed: every changed line traces to the task list (the shared helper, its two call sites, the body-load loop's fallback branch and new event, the `_defaultFallbackManifest()` literal reuse, and the two new test files). `git status`/`git diff --staged --stat` showed only the six intended files staged before committing. Fix commit: `99ed7680b`.
+
+Live production symptom: unverified, pending deploy. This is the evolve lane; no deploy happens here. `/agents/:id`, `/avatars/:id`, and `/marketplace` stay broken for any visitor hitting a GLB load failure (the current R2 outage, or any future one, or a single corrupt/missing object) until `three-ws-api`/the frontend bundle is redeployed with this change, at which point all three surfaces degrade to the local default avatar with a recoverable message instead of a dead viewer.
+
+Left: nothing for this order's own scope. `prompts/finish/438-auto-agent3d-glb-load-fallback.md` deleted in this closing commit.