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.

test(coin3d): pin the route audit's findings and retire its work order

nirholas5de9c89bfcb0
diff --git a/prompts/swarm-100/route-coin3d.md b/prompts/swarm-100/route-coin3d.md
deleted file mode 100644
index 2e5278ac1..000000000
--- a/prompts/swarm-100/route-coin3d.md
+++ /dev/null
@@ -1,119 +0,0 @@
-# Route audit: /coin3d (Token in 3D)
-
-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==='/coin3d')console.log(JSON.stringify(g,null,2))"
-
-2. Find the serving implementation: grep "/coin3d" 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/coin3d
-
-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: /coin3d ("Token in 3D", section "crypto").
-Declared purpose: Any pump.fun token as a live 3D scene: a spinning coin medallion with the token's logo, top holders as a galaxy sized by balance, and a graduation ring tracking bonding-curve progress.
-
-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/coin3d. 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 /coin3d: 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-coin3d.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/tests/e2e/coin3d-page.spec.js b/tests/e2e/coin3d-page.spec.js
new file mode 100644
index 000000000..7d1c58c6e
--- /dev/null
+++ b/tests/e2e/coin3d-page.spec.js
@@ -0,0 +1,133 @@
+// /coin3d: the defects the route audit found, all of which reproduce on the
+// pre-fix page.
+//
+// 1. The page had no <h1> in any state but the populated one. Landing, loading
+// and both error states led with an <h2> under a heading that never
+// rendered, so the document had no top-level heading at all.
+//
+// 2. The landing card sized its grid track from its own max-content, so on a
+// 320px screen the "View in 3D" button and the third column of the launch
+// grid sat off-screen, and `body { overflow: hidden }` meant the card's own
+// footer links were clipped with no way to scroll to them.
+//
+// 3. Every failure produced the same "Token not found" copy, including a total
+// outage where nothing answered at all. A visitor with no connection was
+// told the coin does not exist.
+//
+// These tests deliberately avoid waiting on live token data: the landing and
+// the two error states need no upstream, so the spec is fast and deterministic
+// while still driving the real shipped module.
+
+import { test, expect } from '@playwright/test';
+import { collectPageErrors } from './_support.js';
+
+// The platform's own coin. Used only as a well-formed mint for the routing
+// assertions; no test here asserts on its market data.
+const THREE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
+
+/** Cut every data source the token view can reach, upstream ones included. */
+async function blackout(page) {
+ for (const glob of [
+ '**/api/pump-fun-mcp',
+ '**/api/pump/**',
+ '**/api/oracle/**',
+ '**/api.geckoterminal.com/**',
+ '**/api.dexscreener.com/**',
+ '**/lite-api.jup.ag/**',
+ ]) {
+ await page.route(glob, (route) => route.abort('failed'));
+ }
+}
+
+test('/coin3d leads every state with exactly one h1', async ({ page }) => {
+ const errors = collectPageErrors(page);
+
+ await page.goto('/coin3d', { waitUntil: 'domcontentloaded', timeout: 60_000 });
+ await expect(page.locator('h1')).toHaveCount(1);
+ await expect(page.locator('h1')).toHaveText('See any token in 3D');
+ // The landing is the empty state, and it is designed: it says what to do
+ // and offers a way in that needs no typing.
+ await expect(page.locator('#status')).toHaveAttribute('data-kind', 'empty');
+ await expect(page.locator(`a.c3d-three[href="?mint=${THREE_MINT}"]`)).toBeVisible();
+
+ // An unusable mint is an error state, not a blank scene.
+ await page.goto('/coin3d?mint=notavalidmint', {
+ waitUntil: 'domcontentloaded',
+ timeout: 60_000,
+ });
+ await expect(page.locator('#status')).toHaveAttribute('data-kind', 'error');
+ await expect(page.locator('h1')).toHaveCount(1);
+ await expect(page.locator('h1')).toHaveText('Invalid mint address');
+ // The recovery action is a real link back to the search, not a dead end.
+ await expect(page.locator('.status-action')).toHaveAttribute('href', '/coin3d');
+
+ expect(errors).toEqual([]);
+});
+
+test('/coin3d landing fits a 320px viewport and can be scrolled to its last link', async ({
+ page,
+}) => {
+ await page.setViewportSize({ width: 320, height: 640 });
+ await page.goto('/coin3d', { waitUntil: 'domcontentloaded', timeout: 60_000 });
+ await page.waitForSelector('.c3d-search button', { timeout: 60_000 });
+
+ const box = await page.evaluate(() => {
+ const de = document.documentElement;
+ const status = document.getElementById('status');
+ const card = document.querySelector('.c3d-landing');
+ return {
+ pageOverflows: de.scrollWidth > de.clientWidth,
+ overlayOverflows: status.scrollWidth > status.clientWidth,
+ cardRight: Math.round(card.getBoundingClientRect().right),
+ viewport: de.clientWidth,
+ };
+ });
+ expect(box.pageOverflows).toBe(false);
+ expect(box.overlayOverflows).toBe(false);
+ expect(box.cardRight).toBeLessThanOrEqual(box.viewport);
+
+ // The submit button is the whole point of the landing; it must be on screen.
+ await expect(page.locator('.c3d-search button')).toBeInViewport();
+
+ // The footer links live below the fold on a short screen. They are reachable
+ // because the overlay scrolls, even though the body never does.
+ const footer = page.locator('.c3d-landing-foot a', { hasText: 'Launch your own' });
+ await footer.scrollIntoViewIfNeeded();
+ await expect(footer).toBeInViewport();
+});
+
+test('/coin3d search rejects a malformed mint in place and routes a good one', async ({ page }) => {
+ await page.goto('/coin3d', { waitUntil: 'domcontentloaded', timeout: 60_000 });
+ await page.waitForSelector('#c3d-form', { timeout: 60_000 });
+
+ await page.fill('#c3d-mint-input', 'not-a-mint');
+ await page.click('#c3d-go');
+ await expect(page.locator('#c3d-err')).not.toBeEmpty();
+ // Rejected in place: the visitor keeps their typing and the page stays put.
+ expect(new URL(page.url()).search).toBe('');
+
+ // Typing again clears the complaint rather than leaving it stale.
+ await page.fill('#c3d-mint-input', THREE_MINT);
+ await expect(page.locator('#c3d-err')).toBeEmpty();
+
+ await page.click('#c3d-go');
+ await page.waitForURL(`**/coin3d?mint=${THREE_MINT}`, { timeout: 60_000 });
+});
+
+test('/coin3d says it could not reach the sources, rather than that the coin does not exist', async ({
+ page,
+}) => {
+ await blackout(page);
+ await page.goto(`/coin3d?mint=${THREE_MINT}`, {
+ waitUntil: 'domcontentloaded',
+ timeout: 60_000,
+ });
+
+ const status = page.locator('#status');
+ await expect(status).toHaveAttribute('data-kind', 'error', { timeout: 120_000 });
+ await expect(page.locator('h1')).toHaveText("Can't reach the data sources");
+ // Actionable: retrying this exact token is one click, and it is a real URL.
+ const action = page.locator('.status-action');
+ await expect(action).toHaveText('Retry');
+ await expect(action).toHaveAttribute('href', `/coin3d?mint=${THREE_MINT}`);
+});