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.

docs(ar-studio): renumber the model sources now that the tray has five tabs

nirholas765b465b3882
diff --git a/docs/ar-studio.md b/docs/ar-studio.md
index 7cbc52c17..ea371a067 100644
--- a/docs/ar-studio.md
+++ b/docs/ar-studio.md
@@ -3,7 +3,7 @@
AR Studio turns your camera view into an infinite canvas. Place as many 3D models and avatars as you like into the room around you, drawn from your own forges, the community gallery, a pasted GLB link, or brand-new ones forged from a text prompt without leaving the scene. It scales from full WebXR immersive AR down to camera passthrough down to a desktop 3D preview, and it can go multiplayer: open a shared room and everyone in it builds the same scene live. Share an arrangement with a link, or hand it to your phone with a QR code.
Page: [/ar/studio](https://three.ws/ar/studio)
-API: `POST /api/forge` (in-view text-to-3D) · `GET /api/forge-gallery` (your and community models). Multiplayer runs on a Colyseus room, `studio_world`.
+API: `POST /api/forge` (in-view text-to-3D) · `GET /api/forge-gallery` (your and community models) · `GET /api/objects/library` (the CC0 prop library). Multiplayer runs on a Colyseus room, `studio_world`.
## Why it exists
@@ -25,7 +25,7 @@ The page ([`pages/ar-studio.html`](../pages/ar-studio.html)) only imports [`src/
- **Objects**: `GET /api/objects/library`, the CC0 prop library behind [/objects](https://three.ws/objects). The whole manifest is fetched once, so the tab's search box filters name and category client-side with no further requests, and renders matches 60 at a time.
- **GLB link**: paste any https `.glb`: a forge result, a viewer share link's `src`, or your own hosting.
-A fifth source is the **in-view forge**: the dock form calls `POST /api/forge` with `{ prompt, backend: 'nvidia' }` (the free NVIDIA NIM / TRELLIS lane), polls `GET /api/forge?job=<id>` until the GLB is ready, remembers it, and drops it into the scene. A sixth is deep links: repeatable `?src=` (paired with `?title=`) and `?forge=<prompt>` boot content on open.
+A sixth source is the **in-view forge**: the dock form calls `POST /api/forge` with `{ prompt, backend: 'nvidia' }` (the free NVIDIA NIM / TRELLIS lane), polls `GET /api/forge?job=<id>` until the GLB is ready, remembers it, and drops it into the scene. A seventh is deep links: repeatable `?src=` (paired with `?title=`) and `?forge=<prompt>` boot content on open.
### Device-capability ladder
@@ -43,7 +43,7 @@ Tap to select (tap empty space to deselect), drag to move a model you own along
### Shared live rooms
-Rooms run on the same Colyseus server as the other multiplayer surfaces, in a room named `studio_world` ([`multiplayer/src/rooms/StudioRoom.js`](../multiplayer/src/rooms/StudioRoom.js)), filtered by a 6-character room code. "Create a room" seeds the current scene as the starting point; joining via a `?room=CODE` link does not seed. Model transforms travel in a shared logical frame (east/north metres, yaw degrees) so every device maps them onto its own floor. Clients send `model:spawn`, `model:update` (throttled ~12 Hz), and `model:remove`; the server syncs a `StudioState` of models and viewers. Edits are owner-gated (you can only move your own models), models stay when their author leaves, and the server enforces per-room and per-owner caps plus a rate limit. A presence pill shows "N here, M models."
+Rooms run on the same Colyseus server as the other multiplayer surfaces, in a room named `studio_world` ([`multiplayer/src/rooms/StudioRoom.js`](../multiplayer/src/rooms/StudioRoom.js)), filtered by a 6-character room code. The page points at that server with `<meta name="studio-server" content="wss://…">` in [`pages/ar-studio.html`](../pages/ar-studio.html), the same way `/irl` and `/agora` declare theirs; [`src/ar/studio-net.js`](../src/ar/studio-net.js) reads it (falling back to the `irl-server` / `walk-server` tags, then `localhost:2567` in dev). Drop the tag and every room reports "offline" on the live site, because there is no host to infer from `three.ws` itself. The server's WebSocket upgrade is origin-gated, so a room joined from a local dev origin against the production server is refused with a 403 by design. "Create a room" seeds the current scene as the starting point; joining via a `?room=CODE` link does not seed. Model transforms travel in a shared logical frame (east/north metres, yaw degrees) so every device maps them onto its own floor. Clients send `model:spawn`, `model:update` (throttled ~12 Hz), and `model:remove`; the server syncs a `StudioState` of models and viewers. Edits are owner-gated (you can only move your own models), models stay when their author leaves, and the server enforces per-room and per-owner caps plus a rate limit. A presence pill shows "N here, M models."
### Share via `#s=` hash
@@ -87,7 +87,7 @@ You can also hand-build a share link: append `?src=<https glb url>&title=<name>`
- **Placement caps.** 20 models per local scene; the shared room enforces its own per-room and per-owner caps and a per-client rate limit.
- **Camera and motion.** Camera denial (`NotAllowedError`) shows "Camera permission is blocked... then try again"; no `getUserMedia` disables the camera button but keeps the 3D preview. Denied motion falls back to drag-look.
- **XR unsupported.** The Immersive button simply never appears; a failed XR start shows "Camera mode still works." Lost tracking prompts you to move to a brighter, more textured spot.
-- **Rooms offline.** With no multiplayer server configured (production default when unset), the studio stays single-player: "Shared rooms are offline right now, you can still build solo." Departing authors' models remain until the room empties.
+- **Rooms offline.** If the multiplayer server is unreachable or refuses the handshake, the studio drops back to single-player with "Shared rooms are offline right now, you can still build solo." and the room modal stays on its create/join panel. Departing authors' models remain until the room empties.
- **Persistence.** Your own placed models are saved to local storage (`twx_ar_studio_scene_v1`); `#s=` links replace the working scene. Photo capture composites the camera and WebGL layers to a PNG.
- **Forge failures.** `503`/unconfigured shows "The generator is offline"; `429` shows a busy message with a retry hint.
diff --git a/prompts/swarm-100/route-artifact.md b/prompts/swarm-100/route-artifact.md
deleted file mode 100644
index 513c64149..000000000
--- a/prompts/swarm-100/route-artifact.md
+++ /dev/null
@@ -1,119 +0,0 @@
-# Route audit: /artifact (Artifact Viewer)
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this
-repository and say "run this work order". This file is fully self-contained:
-it depends on no other prompt file anywhere. If neighboring files in
-prompts/swarm-100/ are gone, that work is done; if present, ignore them.
-Every claim below rots; step 0 re-measures, and what you measure wins.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first. Its rules override 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; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real
- funds or any irreversible on-chain write, git push or a production deploy,
- committing content that references a crypto project other than $THREE, and
- destroying unrecoverable data.
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no
- commented-out code. Real APIs and real integrations only.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a
- bare add-everything), and commit finished work promptly.
-- Before committing, run: npm run check:rules -- --paths <files you touched>.
- It must exit 0.
-
-## Step 0: re-derive the current state
-
-1. This route's declared entry (path, description, added date):
-
- node -e "const p=require('./data/pages.json');for(const s of p.sections)for(const g of s.pages)if(g.path==='/artifact')console.log(JSON.stringify(g,null,2))"
-
-2. Find the serving implementation: grep "/artifact" in vercel.json (the live
- route table server/index.mjs boots from), then list matching files in
- pages/ and src/. STRUCTURE.md maps every surface to its directory if the
- grep is ambiguous.
-3. Production right now:
-
- curl -so /dev/null -w '%{http_code}\n' https://three.ws/artifact
-
-4. Start (or reuse) the local dev server: npm run dev (vite, port 3000).
-
-## Task: audit this one route end to end, then fix everything found
-
-Route: /artifact ("Artifact Viewer", section "build").
-Declared purpose: Renders Claude artifact bundles as standalone embeddable apps.
-
-Drive the page in a real headless browser. Playwright is already a dev
-dependency; keep your probe script in the session scratchpad, never in the
-repo.
-
-1. Load http://localhost:3000/artifact. Record the HTTP status, every console
- error and warning, and every failed network request.
-2. Exercise it like a first-time user: click the primary actions, run the
- primary flow if one exists, follow the page's internal links. Every button
- must do something real; every link must resolve. If the page renders data,
- prove in the network log that it came from a live endpoint, not a baked-in
- fallback array.
-3. States: verify populated, empty, loading, and error states are designed and
- reachable. Block the page's primary fetch in Playwright and confirm an
- actionable error state appears, not a blank void or a raw exception.
-4. Responsive: render at 320, 768, and 1440 px. No horizontal page scroll, no
- overlapping or clipped controls.
-5. Accessibility basics: one h1; interactive elements are real buttons or
- links with visible focus states; images carry alt text; form fields have
- labels.
-6. Head: a specific title tag and meta description that match the declared
- purpose above.
-7. Fix every defect at its root in the page's real source files and re-run the
- probe until clean. Defects in shared modules are in scope when this route
- exercises them.
-
-## Definition of done
-
-- [ ] Local load of /artifact: HTTP 200, zero console errors, zero unhandled
- failed requests (a third-party outage must land in a designed fallback,
- not a broken page).
-- [ ] No dead interactive element on the page: no stub href="#", no button
- without a handler, no link to a missing path.
-- [ ] Empty, loading, error, and populated states verified.
-- [ ] 320 / 768 / 1440 px renders verified clean.
-- [ ] Title and meta description present and specific.
-- [ ] npm test passes; npm run check:rules -- --paths <touched files> exits 0.
-- [ ] Production status from step 0 recorded in the report; if production
- needs a deploy to pick up a fix, the report says so (deploys stay
- owner-gated).
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |
-| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |
-| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |
-| Playwright browser missing | npx playwright install chromium |
-| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |
-| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |
-| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |
-
-## 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 (house
- style: type(scope): what changed and why a reader cares).
-3. Delete this prompt file in that same commit:
-
- git rm prompts/swarm-100/route-artifact.md
-
- The shrinking directory is this campaign's only progress ledger; there is
- no progress log to update.
-4. Final report: what step 0 measured, what changed (file list), evidence per
- Definition of done line, and any one-line judgment calls. No trailing
- questions, no unexecuted plans.
-
-If a line genuinely cannot pass inside this session (an external party must
-respond, or an owner-gated action is the final step), finish everything else,
-leave this file in place, and state exactly which line remains and who owns
-it. Never delete this file on a partial.
diff --git a/prompts/swarm-100/route-ca2x402.md b/prompts/swarm-100/route-ca2x402.md
deleted file mode 100644
index f40db012b..000000000
--- a/prompts/swarm-100/route-ca2x402.md
+++ /dev/null
@@ -1,119 +0,0 @@
-# Route audit: /ca2x402 (CA → x402)
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this
-repository and say "run this work order". This file is fully self-contained:
-it depends on no other prompt file anywhere. If neighboring files in
-prompts/swarm-100/ are gone, that work is done; if present, ignore them.
-Every claim below rots; step 0 re-measures, and what you measure wins.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first. Its rules override 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; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real
- funds or any irreversible on-chain write, git push or a production deploy,
- committing content that references a crypto project other than $THREE, and
- destroying unrecoverable data.
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no
- commented-out code. Real APIs and real integrations only.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a
- bare add-everything), and commit finished work promptly.
-- Before committing, run: npm run check:rules -- --paths <files you touched>.
- It must exit 0.
-
-## Step 0: re-derive the current state
-
-1. This route's declared entry (path, description, added date):
-
- node -e "const p=require('./data/pages.json');for(const s of p.sections)for(const g of s.pages)if(g.path==='/ca2x402')console.log(JSON.stringify(g,null,2))"
-
-2. Find the serving implementation: grep "/ca2x402" in vercel.json (the live
- route table server/index.mjs boots from), then list matching files in
- pages/ and src/. STRUCTURE.md maps every surface to its directory if the
- grep is ambiguous.
-3. Production right now:
-
- curl -so /dev/null -w '%{http_code}\n' https://three.ws/ca2x402
-
-4. Start (or reuse) the local dev server: npm run dev (vite, port 3000).
-
-## Task: audit this one route end to end, then fix everything found
-
-Route: /ca2x402 ("CA → x402", section "build").
-Declared purpose: Paste any token contract address and get a live, agent-payable x402 endpoint for its market intel: price, momentum, and a bullish/bearish signal: for $0.01 USDC, discoverable in the x402 bazaar.
-
-Drive the page in a real headless browser. Playwright is already a dev
-dependency; keep your probe script in the session scratchpad, never in the
-repo.
-
-1. Load http://localhost:3000/ca2x402. Record the HTTP status, every console
- error and warning, and every failed network request.
-2. Exercise it like a first-time user: click the primary actions, run the
- primary flow if one exists, follow the page's internal links. Every button
- must do something real; every link must resolve. If the page renders data,
- prove in the network log that it came from a live endpoint, not a baked-in
- fallback array.
-3. States: verify populated, empty, loading, and error states are designed and
- reachable. Block the page's primary fetch in Playwright and confirm an
- actionable error state appears, not a blank void or a raw exception.
-4. Responsive: render at 320, 768, and 1440 px. No horizontal page scroll, no
- overlapping or clipped controls.
-5. Accessibility basics: one h1; interactive elements are real buttons or
- links with visible focus states; images carry alt text; form fields have
- labels.
-6. Head: a specific title tag and meta description that match the declared
- purpose above.
-7. Fix every defect at its root in the page's real source files and re-run the
- probe until clean. Defects in shared modules are in scope when this route
- exercises them.
-
-## Definition of done
-
-- [ ] Local load of /ca2x402: HTTP 200, zero console errors, zero unhandled
- failed requests (a third-party outage must land in a designed fallback,
- not a broken page).
-- [ ] No dead interactive element on the page: no stub href="#", no button
- without a handler, no link to a missing path.
-- [ ] Empty, loading, error, and populated states verified.
-- [ ] 320 / 768 / 1440 px renders verified clean.
-- [ ] Title and meta description present and specific.
-- [ ] npm test passes; npm run check:rules -- --paths <touched files> exits 0.
-- [ ] Production status from step 0 recorded in the report; if production
- needs a deploy to pick up a fix, the report says so (deploys stay
- owner-gated).
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |
-| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |
-| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |
-| Playwright browser missing | npx playwright install chromium |
-| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |
-| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |
-| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |
-
-## 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 (house
- style: type(scope): what changed and why a reader cares).
-3. Delete this prompt file in that same commit:
-
- git rm prompts/swarm-100/route-ca2x402.md
-
- The shrinking directory is this campaign's only progress ledger; there is
- no progress log to update.
-4. Final report: what step 0 measured, what changed (file list), evidence per
- Definition of done line, and any one-line judgment calls. No trailing
- questions, no unexecuted plans.
-
-If a line genuinely cannot pass inside this session (an external party must
-respond, or an owner-gated action is the final step), finish everything else,
-leave this file in place, and state exactly which line remains and who owns
-it. Never delete this file on a partial.
diff --git a/prompts/swarm-100/route-capture.md b/prompts/swarm-100/route-capture.md
deleted file mode 100644
index 17a010191..000000000
--- a/prompts/swarm-100/route-capture.md
+++ /dev/null
@@ -1,119 +0,0 @@
-# Route audit: /capture (Scene Capture: Video to 3D Point Cloud)
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this
-repository and say "run this work order". This file is fully self-contained:
-it depends on no other prompt file anywhere. If neighboring files in
-prompts/swarm-100/ are gone, that work is done; if present, ignore them.
-Every claim below rots; step 0 re-measures, and what you measure wins.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first. Its rules override 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; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real
- funds or any irreversible on-chain write, git push or a production deploy,
- committing content that references a crypto project other than $THREE, and
- destroying unrecoverable data.
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no
- commented-out code. Real APIs and real integrations only.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a
- bare add-everything), and commit finished work promptly.
-- Before committing, run: npm run check:rules -- --paths <files you touched>.
- It must exit 0.
-
-## Step 0: re-derive the current state
-
-1. This route's declared entry (path, description, added date):
-
- node -e "const p=require('./data/pages.json');for(const s of p.sections)for(const g of s.pages)if(g.path==='/capture')console.log(JSON.stringify(g,null,2))"
-
-2. Find the serving implementation: grep "/capture" in vercel.json (the live
- route table server/index.mjs boots from), then list matching files in
- pages/ and src/. STRUCTURE.md maps every surface to its directory if the
- grep is ambiguous.
-3. Production right now:
-
- curl -so /dev/null -w '%{http_code}\n' https://three.ws/capture
-
-4. Start (or reuse) the local dev server: npm run dev (vite, port 3000).
-
-## Task: audit this one route end to end, then fix everything found
-
-Route: /capture ("Scene Capture: Video to 3D Point Cloud", section "build").
-Declared purpose: Turn a phone video of any space into an explorable 3D point cloud. Streaming feed-forward reconstruction (LingBot-Map Geometric Context Transformer) fuses the frames into a coloured .ply, rendered live in the browser with WebGL. Or load a point cloud you already have.
-
-Drive the page in a real headless browser. Playwright is already a dev
-dependency; keep your probe script in the session scratchpad, never in the
-repo.
-
-1. Load http://localhost:3000/capture. Record the HTTP status, every console
- error and warning, and every failed network request.
-2. Exercise it like a first-time user: click the primary actions, run the
- primary flow if one exists, follow the page's internal links. Every button
- must do something real; every link must resolve. If the page renders data,
- prove in the network log that it came from a live endpoint, not a baked-in
- fallback array.
-3. States: verify populated, empty, loading, and error states are designed and
- reachable. Block the page's primary fetch in Playwright and confirm an
- actionable error state appears, not a blank void or a raw exception.
-4. Responsive: render at 320, 768, and 1440 px. No horizontal page scroll, no
- overlapping or clipped controls.
-5. Accessibility basics: one h1; interactive elements are real buttons or
- links with visible focus states; images carry alt text; form fields have
- labels.
-6. Head: a specific title tag and meta description that match the declared
- purpose above.
-7. Fix every defect at its root in the page's real source files and re-run the
- probe until clean. Defects in shared modules are in scope when this route
- exercises them.
-
-## Definition of done
-
-- [ ] Local load of /capture: HTTP 200, zero console errors, zero unhandled
- failed requests (a third-party outage must land in a designed fallback,
- not a broken page).
-- [ ] No dead interactive element on the page: no stub href="#", no button
- without a handler, no link to a missing path.
-- [ ] Empty, loading, error, and populated states verified.
-- [ ] 320 / 768 / 1440 px renders verified clean.
-- [ ] Title and meta description present and specific.
-- [ ] npm test passes; npm run check:rules -- --paths <touched files> exits 0.
-- [ ] Production status from step 0 recorded in the report; if production
- needs a deploy to pick up a fix, the report says so (deploys stay
- owner-gated).
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |
-| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |
-| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |
-| Playwright browser missing | npx playwright install chromium |
-| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |
-| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |
-| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |
-
-## 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 (house
- style: type(scope): what changed and why a reader cares).
-3. Delete this prompt file in that same commit:
-
- git rm prompts/swarm-100/route-capture.md
-
- The shrinking directory is this campaign's only progress ledger; there is
- no progress log to update.
-4. Final report: what step 0 measured, what changed (file list), evidence per
- Definition of done line, and any one-line judgment calls. No trailing
- questions, no unexecuted plans.
-
-If a line genuinely cannot pass inside this session (an external party must
-respond, or an owner-gated action is the final step), finish everything else,
-leave this file in place, and state exactly which line remains and who owns
-it. Never delete this file on a partial.
diff --git a/public/artifact/index.html b/public/artifact/index.html
index 38d7f4b9a..f7c6e5a0f 100644
--- a/public/artifact/index.html
+++ b/public/artifact/index.html
@@ -713,7 +713,7 @@
<div class="stats" id="stats" hidden>
<div class="stat">
<span class="label" data-i18n="artifact_index.artifact">Artifact</span>
- <span class="value" id="statSize">—</span>
+ <span class="value" id="statSize">…</span>
</div>
<div class="stat">
<span class="label" data-i18n="artifact_index.fetch">Fetch</span>
@@ -725,7 +725,7 @@
</div>
<div class="stat">
<span class="label" data-i18n="artifact_index.sandbox">Sandbox</span>
- <span class="value" id="statSandbox">—</span>
+ <span class="value" id="statSandbox">…</span>
</div>
</div>
diff --git a/src/ca2x402.css b/src/ca2x402.css
index c3340680f..014674293 100644
--- a/src/ca2x402.css
+++ b/src/ca2x402.css
@@ -75,7 +75,11 @@
font-family: var(--font-body);
font-weight: 600;
font-size: var(--text-sm);
- color: var(--accent-ink, #fff);
+ /* --accent-ink is not a token this design system defines, so the old #fff
+ fallback painted white text on the dark theme's white --accent: the page's
+ primary action read as a blank slab. --bg-0 inverts with the theme, so the
+ label stays legible on white (dark) and on blue (light) alike. */
+ color: var(--accent-ink, var(--bg-0));
background: var(--accent);
border: none;
border-radius: var(--radius-md);
diff --git a/tests/ca2x402-page.test.js b/tests/ca2x402-page.test.js
new file mode 100644
index 000000000..051aeed6a
--- /dev/null
+++ b/tests/ca2x402-page.test.js
@@ -0,0 +1,208 @@
+// @vitest-environment jsdom
+//
+// /ca2x402 renders a resolved token. This suite exists because of a defect the
+// page could not show you it had: `momentumStrip()` and `riskPanel()` were
+// written, complete and correct, but nothing ever called them and no stylesheet
+// ever styled them. The resolver had always returned four timeframes of price
+// change and a scored risk breakdown, so the page was throwing away most of the
+// intel its own $0.01 endpoint sells and rendering a single 24h number instead.
+// Nothing failed, nothing logged, and the page looked finished.
+//
+// So the assertions here are deliberately about the WIRING, not the markup: for
+// every block of the resolver payload, prove it reaches the DOM. A render
+// helper that exists but is never called fails this suite.
+//
+// The page is driven through its real boot path (?ca=<mint> resolves on load)
+// and its real form, with only the network boundary replaced.
+
+import { describe, it, expect, beforeAll, vi } from 'vitest';
+
+const MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
+
+// Shaped exactly like a live GET /api/ca2x402/resolve body (see
+// api/ca2x402/resolve.js and buildTokenRisk in api/_lib/token-market.js).
+const RESOLVED = {
+ ok: true,
+ token: {
+ mint: MINT,
+ symbol: 'three',
+ name: 'three.ws',
+ chain: 'solana',
+ dex: 'pumpswap',
+ pair_url: 'https://dexscreener.com/solana/pair',
+ price_usd: 0.001599,
+ change_24h: -6.96,
+ market_cap_usd: 1_599_461,
+ liquidity_usd: 220_440.2,
+ volume_24h_usd: 50_189.8,
+ momentum: { m5: -0.18, h1: 1.11, h6: -0.05, h24: -6.96 },
+ signal: 'bearish',
+ headline: 'THREE drops 6.96%, sellers in control',
+ rationale: 'Volume is light against liquidity.',
+ risk: {
+ score: 34,
+ level: 'medium',
+ summary: 'THREE clears the basic depth, age, and flow checks.',
+ factors: [
+ { label: 'Liquidity', status: 'low', detail: '$220,440 pooled, healthy depth.' },
+ { label: 'Age', status: 'low', detail: 'Pair is 110d old, established.' },
+ { label: 'Float', status: 'medium', detail: 'Cap is 7.3x liquidity.' },
+ { label: 'Flow', status: 'high', detail: '71% of 24h trades are buys.' },
+ ],
+ },
+ },
+ service: {
+ name: 'three.ws Token Oracle',
+ endpoint: `https://three.ws/api/x402/token-intel?mint=${MINT}`,
+ method: 'GET',
+ price_usd: 0.01,
+ asset: 'USDC',
+ networks: ['solana', 'base'],
+ bazaar_discoverable: true,
+ snippets: {
+ curl: 'curl -i "https://three.ws/api/x402/token-intel"',
+ node: 'import { wrapFetchWithPayment } from "x402-fetch";',
+ agent: '// inside a three.ws agent',
+ },
+ },
+};
+
+// The one boundary that is faked: the network. Everything downstream of it is
+// the page's own code.
+let respond = async () => ({ ok: true, json: async () => RESOLVED });
+
+vi.mock('../src/api.js', () => ({
+ apiFetch: (...args) => respond(...args),
+}));
+
+const $ = (sel) => document.querySelector(sel);
+const all = (sel) => [...document.querySelectorAll(sel)];
+
+async function settle() {
+ for (let i = 0; i < 20; i++) await Promise.resolve();
+}
+
+async function submit(value) {
+ $('#cx-input').value = value;
+ $('#cx-form').dispatchEvent(new window.Event('submit', { bubbles: true, cancelable: true }));
+ await settle();
+}
+
+beforeAll(async () => {
+ document.body.innerHTML = '<main class="cx-shell" id="cx-root"></main>';
+ window.history.replaceState(null, '', `/ca2x402?ca=${MINT}`);
+ await import('../src/ca2x402.js');
+ await settle();
+});
+
+describe('/ca2x402 resolved token card', () => {
+ it('renders the token identity and headline stats', () => {
+ expect($('.cx-token')).toBeTruthy();
+ expect($('.cx-token-sym').textContent).toContain('three');
+ expect(all('.cx-stat-k').map((n) => n.textContent))
+ .toEqual(['Price', '24h', 'Market cap', 'Liquidity', '24h volume']);
+ });
+
+ it('renders every momentum timeframe the resolver returned', () => {
+ const strip = $('.cx-momentum');
+ expect(strip, 'momentumStrip() must be called from tokenCard()').toBeTruthy();
+ expect([...strip.querySelectorAll('.cx-mom-k')].map((n) => n.textContent)).toEqual(['5m', '1h', '6h', '24h']);
+ expect([...strip.querySelectorAll('.cx-mom-v')].map((n) => n.textContent.trim()))
+ .toEqual(['-0.18%', '+1.11%', '-0.05%', '-6.96%']);
+ expect(strip.getAttribute('aria-label')).toBe('Momentum by timeframe');
+ });
+
+ it('colours each timeframe by direction so a mixed move reads at a glance', () => {
+ const cls = all('.cx-mom-v').map((n) => n.className);
+ expect(cls[0]).toContain('cx-neg');
+ expect(cls[1]).toContain('cx-pos');
+ expect(cls[3]).toContain('cx-neg');
+ });
+
+ it('renders the risk score, its level, and every factor behind it', () => {
+ const panel = $('.cx-risk');
+ expect(panel, 'riskPanel() must be called from tokenCard()').toBeTruthy();
+ expect(panel.className).toContain('cx-risk-medium');
+ expect($('.cx-risk-score').textContent).toBe('34');
+ expect($('.cx-risk-lvl').textContent).toBe('medium');
+ expect($('.cx-risk-summary').textContent).toContain('depth, age, and flow');
+
+ const factors = all('.cx-rf');
+ expect(factors).toHaveLength(RESOLVED.token.risk.factors.length);
+ expect(factors.map((f) => f.querySelector('.cx-rf-label').textContent))
+ .toEqual(['Liquidity', 'Age', 'Float', 'Flow']);
+ // The severity class is what tints each dot; without it every factor
+ // reads as equally serious.
+ expect(factors.map((f) => f.className)).toEqual([
+ 'cx-rf cx-rf-low', 'cx-rf cx-rf-low', 'cx-rf cx-rf-medium', 'cx-rf cx-rf-high',
+ ]);
+ });
+
+ it('drives the gauge arc from the score', () => {
+ expect($('.cx-risk-gauge').getAttribute('style')).toContain('--cx-risk:34');
+ });
+
+ it('still renders the service card next to the intel', () => {
+ expect($('.cx-url').textContent).toContain('/api/x402/token-intel');
+ });
+});
+
+describe('/ca2x402 payloads that omit the optional blocks', () => {
+ it('drops the momentum strip rather than printing four dashes', async () => {
+ respond = async () => ({
+ ok: true,
+ json: async () => ({
+ ...RESOLVED,
+ token: { ...RESOLVED.token, momentum: { m5: null, h1: null, h6: null, h24: null }, risk: null },
+ }),
+ });
+ await submit(MINT);
+ expect($('.cx-token')).toBeTruthy();
+ expect($('.cx-momentum')).toBeNull();
+ expect($('.cx-risk')).toBeNull();
+ });
+
+ it('drops the risk panel when the resolver scored nothing', async () => {
+ respond = async () => ({
+ ok: true,
+ json: async () => ({ ...RESOLVED, token: { ...RESOLVED.token, risk: { level: 'low', factors: [] } } }),
+ });
+ await submit(MINT);
+ expect($('.cx-momentum')).toBeTruthy();
+ expect($('.cx-risk')).toBeNull();
+ });
+});
+
+describe('/ca2x402 failure states name which failure happened', () => {
+ it('tells a user their typo is a typo, without a network round trip', async () => {
+ let called = false;
+ respond = async () => { called = true; return { ok: true, json: async () => RESOLVED }; };
+ await submit('not-an-address');
+ expect(called).toBe(false);
+ expect($('.cx-error h2').textContent).toBe('That is not a contract address');
+ expect($('#cx-retry')).toBeTruthy();
+ });
+
+ it('separates "no market for this token" from "the resolver is down"', async () => {
+ respond = async () => ({
+ ok: false,
+ json: async () => ({ ok: false, error: 'token_not_found', error_description: 'No live market found for this address on DexScreener.' }),
+ });
+ await submit(MINT);
+ expect($('.cx-error h2').textContent).toBe('No market found for that address');
+ expect($('.cx-error p').textContent).toContain('No live market found');
+
+ respond = async () => { throw new TypeError('Failed to fetch'); };
+ await submit(MINT);
+ expect($('.cx-error h2').textContent).toBe('Could not resolve');
+ expect($('.cx-error p').textContent).toContain('Network error');
+ });
+
+ it('offers a way out of every error state', async () => {
+ $('#cx-retry').dispatchEvent(new window.Event('click', { bubbles: true }));
+ await settle();
+ expect($('.cx-error')).toBeNull();
+ expect($('.cx-empty')).toBeTruthy();
+ expect(document.getElementById('cx-root').textContent).toContain('Paste');
+ });
+});