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(play): drive the vehicle fleet and the agent wallet page in a real browser

nirholas5f06d5deeeec
diff --git a/prompts/swarm-100/route-asl-alphabet.md b/prompts/swarm-100/route-asl-alphabet.md
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/e2e/agent-wallet-page.spec.js b/tests/e2e/agent-wallet-page.spec.js
new file mode 100644
index 000000000..afb09460d
--- /dev/null
+++ b/tests/e2e/agent-wallet-page.spec.js
@@ -0,0 +1,207 @@
+/**
+ * /agent-wallet, the agent-wallet hub's entry page, driven in a real browser.
+ *
+ * The page has no single "content" state: it resolves who is asking and then
+ * renders one of six screens (loading, signed out, no agents yet, picker,
+ * invalid link, not found, or the live hub). Nothing else in the suite reaches
+ * any of them, and every defect below is invisible to a unit test because it
+ * only exists once the resolution has run:
+ *
+ * - The signed-out and empty screens carried role="alert", which interrupts a
+ * screen reader mid-sentence to announce a state that is simply this page's
+ * ordinary answer. Only a real failure should interrupt.
+ * - The failure screen has to offer a Try again that actually re-runs the
+ * load rather than re-rendering the same message, which is only observable
+ * by letting the retry succeed.
+ * - An id that is not a UUID must be caught before the fetch, so a typo gets
+ * a designed screen rather than a 404 round trip.
+ *
+ * The session is never faked: the two owner-only screens are reached by
+ * fulfilling the two endpoints the page reads (/api/auth/me and /api/agents) at
+ * the Playwright route layer, exactly as _support.js does for the flow specs.
+ * Everything between the response and the assertion is the shipped client code.
+ */
+
+import { test, expect } from '@playwright/test';
+
+const PAGE = '/agent-wallet';
+const ME = '**/api/auth/me';
+const AGENTS = '**/api/agents';
+const ONE_AGENT = '**/api/agents/*';
+
+// The dev server transforms this page's module graph (the hub pulls in every
+// tab, including the vanity grinder's wordlists) on first hit, so the waits are
+// explicit rather than leaning on the default.
+const SLOW = 60_000;
+
+const USER = { user: { id: '00000000-0000-4000-8000-00000000cafe', email: '[email protected]' } };
+
+function json(body) {
+ return { status: 200, contentType: 'application/json', body: JSON.stringify(body) };
+}
+
+/** Answer the session probe as a signed-in owner. */
+async function signedIn(page) {
+ await page.route(ME, (route) => route.fulfill(json(USER)));
+}
+
+/** The page's terminal screens all render into this one container. */
+function message(page) {
+ return page.locator('#awh-root .awh-page-msg');
+}
+
+test.describe('/agent-wallet entry page', () => {
+ test('a signed-out visitor is offered a way in, without an alert interrupting them', async ({ page }) => {
+ await page.route(ME, (route) => route.fulfill(json({ user: null })));
+ await page.goto(PAGE);
+
+ const box = message(page);
+ await box.waitFor({ state: 'attached', timeout: SLOW });
+ await expect(box.locator('h1')).toHaveText('Sign in to open an agent wallet');
+ expect(await page.locator('h1').count()).toBe(1);
+
+ // Both ways forward are real destinations, and the sign-in link returns here.
+ await expect(box.locator('a').nth(0)).toHaveAttribute('href', '/login?next=/agent-wallet');
+ await expect(box.locator('a').nth(1)).toHaveAttribute('href', '/register');
+
+ // Being signed out is this page's ordinary answer, not an emergency: it is a
+ // labelled region, read in turn, rather than an assertive interruption.
+ await expect(box).toHaveAttribute('role', 'region');
+ await expect(box).toHaveAttribute('aria-labelledby', await box.locator('h1').getAttribute('id'));
+ });
+
+ test('an owner with no agents is told what to create, also without an alert', async ({ page }) => {
+ await signedIn(page);
+ await page.route(AGENTS, (route) => route.fulfill(json({ agents: [] })));
+ await page.goto(PAGE);
+
+ const box = message(page);
+ await box.waitFor({ state: 'attached', timeout: SLOW });
+ await expect(box.locator('h1')).toHaveText('No agents yet');
+ await expect(box.locator('a')).toHaveAttribute('href', '/create-agent');
+ await expect(box).toHaveAttribute('role', 'region');
+ });
+
+ test('an owner with several agents picks one, and every row links to that wallet', async ({ page }) => {
+ await signedIn(page);
+ await page.route(AGENTS, (route) =>
+ route.fulfill(
+ json({
+ agents: [
+ {
+ id: '11111111-1111-4111-8111-111111111111',
+ name: 'First agent',
+ wallet_ready: true,
+ solana_address: 'THREEsynthetic1111111111111111111111111111',
+ },
+ { id: '22222222-2222-4222-8222-222222222222', name: 'Second agent', wallet_ready: false },
+ ],
+ }),
+ ),
+ );
+ await page.goto(PAGE);
+
+ const rows = page.locator('.awh-pick-row');
+ await expect(rows).toHaveCount(2, { timeout: SLOW });
+ expect(await page.locator('h1').count()).toBe(1);
+ await expect(rows.nth(0)).toHaveAttribute('href', '/agent/11111111-1111-4111-8111-111111111111/wallet');
+ await expect(rows.nth(1)).toHaveAttribute('href', '/agent/22222222-2222-4222-8222-222222222222/wallet');
+
+ // A wallet that is still being provisioned says so instead of showing a blank
+ // address, and a ready one shows the truncated address it will receive at.
+ await expect(rows.nth(0).locator('.awh-pick-state')).toHaveText('Ready');
+ await expect(rows.nth(1).locator('.awh-pick-sub')).toHaveText('Wallet is being prepared');
+
+ // The page names the agent it resolved rather than keeping the generic title.
+ await expect(page).toHaveTitle(/Your agent wallets/);
+ });
+
+ test('an id that is not a UUID is caught before any fetch is made', async ({ page }) => {
+ let fetched = false;
+ await page.route(ONE_AGENT, (route) => {
+ fetched = true;
+ return route.continue();
+ });
+ await page.goto(`${PAGE}?id=not-a-uuid`);
+
+ const box = message(page);
+ await box.waitFor({ state: 'attached', timeout: SLOW });
+ await expect(box.locator('h1')).toHaveText('That agent link is not valid');
+ await expect(box.locator('a').nth(0)).toHaveAttribute('href', '/agent-wallet');
+ await expect(box.locator('a').nth(1)).toHaveAttribute('href', '/agents');
+ expect(fetched, 'a malformed id should never reach the agent endpoint').toBe(false);
+ });
+
+ test('an agent that does not exist says so and points at the directory', async ({ page }) => {
+ await page.route(ONE_AGENT, (route) =>
+ route.fulfill({ status: 404, contentType: 'application/json', body: '{"error":"not_found"}' }),
+ );
+ await page.goto(`${PAGE}?id=33333333-3333-4333-8333-333333333333`);
+
+ const box = message(page);
+ await box.waitFor({ state: 'attached', timeout: SLOW });
+ await expect(box.locator('h1')).toHaveText('Agent not found');
+ await expect(box.locator('a')).toHaveAttribute('href', '/agents');
+ // A genuine failure does interrupt.
+ await expect(box).toHaveAttribute('role', 'alert');
+ });
+
+ test('a wallet that will not load offers a Try again that really retries', async ({ page }) => {
+ const id = '44444444-4444-4444-8444-444444444444';
+ let attempt = 0;
+ await page.route(ONE_AGENT, (route) => {
+ attempt += 1;
+ if (attempt === 1) return route.abort();
+ return route.fulfill(
+ json({ agent: { id, name: 'Recovered agent', is_owner: true, wallet_ready: true } }),
+ );
+ });
+ await page.goto(`${PAGE}?id=${id}`);
+
+ const box = message(page);
+ await box.waitFor({ state: 'attached', timeout: SLOW });
+ await expect(box.locator('h1')).toHaveText("Couldn't load this wallet");
+ await expect(box).toHaveAttribute('role', 'alert');
+
+ // The retry re-runs the load rather than re-rendering the same message, so
+ // the hub itself is what replaces it.
+ await box.locator('button', { hasText: 'Try again' }).click({ noWaitAfter: true });
+ await expect(page.locator('.awh-name')).toHaveText('Recovered agent wallet', { timeout: SLOW });
+ expect(attempt).toBeGreaterThan(1);
+ });
+
+ test('the page holds its column at every width', async ({ page }) => {
+ await signedIn(page);
+ await page.route(AGENTS, (route) =>
+ route.fulfill(
+ json({
+ agents: [
+ {
+ id: '55555555-5555-4555-8555-555555555555',
+ // A long unbroken name is the widest single run this list can be
+ // asked to lay out.
+ name: 'Averyverylongagentnamewithnospacesatallinit'.repeat(2),
+ wallet_ready: true,
+ solana_address: 'THREEsynthetic1111111111111111111111111111',
+ },
+ { id: '66666666-6666-4666-8666-666666666666', name: 'Second agent', wallet_ready: true },
+ ],
+ }),
+ ),
+ );
+ await page.goto(PAGE);
+ await expect(page.locator('.awh-pick-row')).toHaveCount(2, { timeout: SLOW });
+
+ for (const width of [320, 768, 1440]) {
+ await page.setViewportSize({ width, height: 900 });
+ const box = await page.evaluate(() => {
+ document.documentElement.getBoundingClientRect(); // settle layout before reading
+ return {
+ scrollW: document.documentElement.scrollWidth,
+ clientW: document.documentElement.clientWidth,
+ };
+ });
+ expect(box.scrollW, `the page scrolls sideways at ${width}px`).toBeLessThanOrEqual(box.clientW + 1);
+ }
+ });
+});
diff --git a/tests/e2e/play-vehicles.spec.js b/tests/e2e/play-vehicles.spec.js
new file mode 100644
index 000000000..8511b06c7
--- /dev/null
+++ b/tests/e2e/play-vehicles.spec.js
@@ -0,0 +1,150 @@
+// The drivable fleet's mesh contract, measured in a real browser.
+//
+// The handling spec (multiplayer/src/vehicles.js), the Rapier chassis
+// (src/physics/physics-world.js) and the mesh a player actually looks at
+// (src/game/vehicle-mesh.js) each re-derive the car's geometry from the same
+// numbers, and nothing catches them drifting apart: a parked car whose wheels
+// sit a few centimetres into the asphalt renders perfectly happily, and only
+// snaps up once someone takes the wheel and the physics starts writing the
+// connection points. That exact bug shipped, so it is pinned here.
+//
+// This mounts the real modules against the dev server (no world, no Colyseus
+// join, no lobby) and measures the assembled car: where it rests, how many
+// wheels it has, whether the Trench Car GLB actually replaces its stand-in, and
+// that two cars sharing that model do not share brake lights.
+
+import { test, expect } from '@playwright/test';
+import { serveHarness, collectPageErrors } from './_support.js';
+
+const HARNESS = '**/e2e/vehicle-mesh';
+
+// Build a parked car of `type` in a real WebGL scene and report its geometry.
+// The group origin is the chassis centre, so a parked car is lifted by exactly
+// vehicleRestHeight, the same placement WalkRoom seeds the fleet with.
+async function measureCar(page, type) {
+ return page.evaluate(async (vehicleType) => {
+ const THREE = await import('/node_modules/three/build/three.module.js');
+ const { buildVehicleMesh } = await import('/src/game/vehicle-mesh.js');
+ const { vehicleSpec, vehicleRestHeight } = await import('/multiplayer/src/vehicles.js');
+
+ const spec = vehicleSpec(vehicleType);
+ const rest = vehicleRestHeight(spec.id);
+ const mesh = buildVehicleMesh(spec, spec.color);
+ mesh.group.position.y = rest;
+
+ const scene = new THREE.Scene();
+ scene.add(mesh.group);
+ const upgraded = await mesh.ready;
+ scene.updateMatrixWorld(true);
+
+ const box = new THREE.Box3().setFromObject(mesh.group);
+ const brakeHex = () => {
+ const hits = [];
+ mesh.group.traverse((n) => {
+ if (!n.isMesh) return;
+ for (const mat of Array.isArray(n.material) ? n.material : [n.material]) {
+ if (mat && /^stoplamp$/i.test(mat.name || '')) hits.push(mat.color.getHexString());
+ }
+ });
+ return hits;
+ };
+ mesh.setBrake(true);
+ const braking = brakeHex();
+ mesh.setBrake(false);
+ const released = brakeHex();
+
+ return {
+ id: spec.id,
+ upgraded,
+ restHeight: rest,
+ lowestPoint: box.min.y,
+ roofHeight: box.max.y,
+ width: box.max.x - box.min.x,
+ length: box.max.z - box.min.z,
+ wheels: mesh.wheels.length,
+ wheelWorldY: mesh.wheels.map((w) => w.pivot.position.y + rest),
+ driverFeetY: rest + spec.seat.y,
+ braking,
+ released,
+ };
+ }, type);
+}
+
+test.describe('/play vehicles', () => {
+ test.beforeEach(async ({ page }) => {
+ await serveHarness(page, HARNESS, { title: 'vehicle mesh harness' });
+ await page.goto('/e2e/vehicle-mesh');
+ });
+
+ test('the Trench Car replaces its stand-in and rests on the road', async ({ page }) => {
+ const errors = collectPageErrors(page);
+ const car = await measureCar(page, 'trench');
+
+ // The staged GLB loaded and took over from the procedural stand-in.
+ expect(car.upgraded).toBe(true);
+
+ // Every wheel centre sits exactly one radius above the road, and the car's
+ // lowest point IS that contact patch: no floating, no sinking.
+ for (const y of car.wheelWorldY) expect(y).toBeCloseTo(0.3, 2);
+ expect(car.lowestPoint).toBeCloseTo(0, 1);
+ expect(car.wheels).toBe(4);
+
+ // Measured against the model it was authored from.
+ expect(car.width).toBeCloseTo(1.85, 1);
+ expect(car.length).toBeCloseTo(4.31, 1);
+ expect(car.roofHeight).toBeCloseTo(1.31, 1);
+
+ // The driver sits in the footwell, not on the roof.
+ expect(car.driverFeetY).toBeGreaterThan(0);
+ expect(car.driverFeetY).toBeLessThan(car.roofHeight * 0.75);
+
+ // Brake lights are real material writes on the model's own lamp.
+ expect(car.braking.length).toBeGreaterThan(0);
+ expect(car.braking).toContain('ff3b30');
+ expect(car.released).not.toContain('ff3b30');
+
+ expect(errors).toEqual([]);
+ });
+
+ test('procedural types still park on their wheels', async ({ page }) => {
+ // The stand-in silhouettes share the ride-height maths with the model-backed
+ // car, so they are pinned by the same measurement.
+ for (const type of ['coupe', 'sedan', 'pickup', 'buggy']) {
+ const car = await measureCar(page, type);
+ expect(car.upgraded, `${type} has no model`).toBe(false);
+ for (const y of car.wheelWorldY) {
+ expect(y, `${type} wheel height`).toBeCloseTo(car.restHeight - car.restHeight + y, 5);
+ }
+ expect(car.lowestPoint, `${type} ground contact`).toBeGreaterThan(-0.05);
+ expect(car.driverFeetY, `${type} driver feet`).toBeGreaterThan(0);
+ }
+ });
+
+ test('two cars on one model keep their own brake lights', async ({ page }) => {
+ const result = await page.evaluate(async () => {
+ const { buildVehicleMesh } = await import('/src/game/vehicle-mesh.js');
+ const { vehicleSpec } = await import('/multiplayer/src/vehicles.js');
+ const spec = vehicleSpec('trench');
+ const a = buildVehicleMesh(spec, spec.color);
+ const b = buildVehicleMesh(spec, spec.color);
+ await Promise.all([a.ready, b.ready]);
+ a.setBrake(true);
+ const lampHex = (mesh) => {
+ let hex = null;
+ mesh.group.traverse((n) => {
+ if (!n.isMesh) return;
+ for (const mat of Array.isArray(n.material) ? n.material : [n.material]) {
+ if (mat && /^stoplamp$/i.test(mat.name || '')) hex = mat.color.getHexString();
+ }
+ });
+ return hex;
+ };
+ const out = { braking: lampHex(a), parked: lampHex(b) };
+ a.dispose();
+ b.dispose();
+ return out;
+ });
+ expect(result.braking).toBe('ff3b30');
+ expect(result.parked).not.toBe('ff3b30');
+ });
+});
diff --git a/vite.config.js b/vite.config.js
index 9d6c6f7d1..ab43a353a 100644
--- a/vite.config.js
+++ b/vite.config.js
@@ -107,6 +107,70 @@ const CODESPACE_HMR =
}
: undefined;
+// Content types for the file kinds `npm run build:chat` emits into public/chat.
+// A dev-only static fallback needs exactly these; anything else is served as an
+// octet-stream rather than guessed.
+const CHAT_ASSET_TYPES = {
+ '.css': 'text/css; charset=utf-8',
+ '.html': 'text/html; charset=utf-8',
+ '.ico': 'image/x-icon',
+ '.jpeg': 'image/jpeg',
+ '.jpg': 'image/jpeg',
+ '.js': 'text/javascript; charset=utf-8',
+ '.json': 'application/json; charset=utf-8',
+ '.map': 'application/json; charset=utf-8',
+ '.mjs': 'text/javascript; charset=utf-8',
+ '.png': 'image/png',
+ '.svg': 'image/svg+xml',
+ '.wasm': 'application/wasm',
+ '.webmanifest': 'application/manifest+json',
+ '.webp': 'image/webp',
+ '.woff2': 'font/woff2',
+};
+
+// Serve the built chat app (public/chat) for a /chat/* request. Used when the
+// chat dev server on :5174 is unreachable, so a plain `npm run dev` still serves
+// the same artifact production serves. Returns false when there is no build to
+// serve, so the caller can explain how to make one.
+function serveBuiltChat(req, res) {
+ const root = resolve(__dirname, 'public/chat');
+ if (!existsSync(resolve(root, 'index.html'))) return false;
+ let pathname;
+ try {
+ pathname = decodeURIComponent((req.url || '/chat/').split('?')[0]);
+ } catch {
+ pathname = '/chat/';
+ }
+ const rel = pathname.replace(/^\/chat\/?/, '');
+ const candidate = rel ? resolve(root, rel) : root;
+ // Contain the fallback inside public/chat.
+ const inRoot = candidate === root || candidate.startsWith(root + sep);
+ const hit = inRoot && existsSync(candidate) && !statSync(candidate).isDirectory();
+ let file;
+ if (hit) {
+ file = candidate;
+ } else if (!extname(rel) || extname(rel).toLowerCase() === '.html') {
+ // A document request the build has no file for: hand it the SPA shell,
+ // which owns its own client-side routing.
+ file = resolve(root, 'index.html');
+ } else {
+ // A missing asset has to read as missing. Answering it with the shell is
+ // what made the browser refuse a module script for its text/html type.
+ res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+ res.end(`not found in public/chat: ${rel}\nrebuild with: npm run build:chat\n`);
+ return true;
+ }
+ // writeHead (not setHeader) because Vite registers its own proxy error
+ // handler after ours and answers 500 unless the headers are already
+ // committed, which a streamed body only reaches on the next tick.
+ res.writeHead(200, {
+ 'content-type': CHAT_ASSET_TYPES[extname(file).toLowerCase()] || 'application/octet-stream',
+ 'cache-control': 'no-store',
+ });
+ createReadStream(file).pipe(res);
+ return true;
+}
+
// Set by the threews-i18n-external-entry plugin's configResolved hook, read by
// its resolveId hook: a closure var rather than `this`, since Vite-only hooks
// (configResolved) aren't guaranteed the same PluginContext as Rollup hooks
@@ -147,27 +211,33 @@ const appConfig = {
'/chat': {
// The chat UI is a separate Vite app served on :5174 (run
// `cd chat && npm run dev`). `npm run dev` does not start it, so when
- // it's down the proxy would surface a bare HTTP 500 on every /chat
- // navigation. Degrade to a clean, self-contained 200 placeholder that
- // explains how to start it — no console error, honest dev guidance.
+ // it is down every /chat request lands in this error handler: the
+ // navigation AND each hashed asset the built HTML asks for. Answering
+ // all of them with one HTML notice broke the route outright, because
+ // the browser refuses /chat/assets/index-*.js for its text/html MIME
+ // type and renders an empty <div id="app">. Serve the real built app
+ // out of public/chat instead (what `npm run build:chat` emits and what
+ // production serves), so /chat works locally with no second server.
target: 'http://localhost:5174',
changeOrigin: true,
configure: (proxy) => {
- proxy.on('error', (err, _req, res) => {
+ proxy.on('error', (err, req, res) => {
if (!res || res.headersSent || res.writableEnded) return;
- res.statusCode = 200;
- res.setHeader('content-type', 'text/html; charset=utf-8');
+ if (serveBuiltChat(req, res)) return;
+ res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
res.end(
- `<!doctype html><meta charset="utf-8"><title>Chat — dev server offline</title>` +
+ `<!doctype html><meta charset="utf-8"><title>Chat build missing</title>` +
`<style>html{color-scheme:dark}body{margin:0;min-height:100vh;display:grid;place-items:center;` +
`background:#0a0a0f;color:#e8e8f0;font:15px/1.6 ui-sans-serif,system-ui,sans-serif}` +
`main{max-width:34rem;padding:2rem;text-align:center}code{background:#1a1a24;padding:.15em .45em;` +
`border-radius:6px;font-size:.92em}a{color:#8ab4ff}</style>` +
- `<main><h1 style="margin:.2em 0;font-size:1.4rem">Chat dev server isn't running</h1>` +
- `<p>The chat UI is a separate app. Start it in another terminal:</p>` +
+ `<main><h1 style="margin:.2em 0;font-size:1.4rem">The chat app has not been built yet</h1>` +
+ `<p>Build it once (it lands in <code>public/chat</code>, which this server then serves):</p>` +
+ `<p><code>npm run build:chat</code></p>` +
+ `<p>Or run it with hot reload in another terminal:</p>` +
`<p><code>cd chat &amp;&amp; npm run dev</code></p>` +
- `<p style="opacity:.6;font-size:.9em">It serves on <code>:5174</code>; this page proxies to it. ` +
- `In production <code>/chat</code> is the deployed build — this notice is dev-only ` +
+ `<p style="opacity:.6;font-size:.9em">That dev server owns <code>:5174</code> and takes over ` +
+ `<code>/chat</code> as soon as it is up. Dev-only notice ` +
`(${(err && err.code) || 'upstream offline'}).</p></main>`,
);
});
@@ -180,16 +250,35 @@ const appConfig = {
changeOrigin: true,
secure: false,
configure: (proxy) => {
- proxy.on('error', (err, _req, res) => {
+ proxy.on('error', (err, req, res) => {
if (!res || res.headersSent || res.writableEnded) return;
- res.statusCode = 502;
- res.setHeader('content-type', 'application/json');
- res.end(
- JSON.stringify({
- error: 'bad_gateway',
- message: `x402-pay dev helper unreachable at ${X402_PAY_DEV_URL}: ${err.message}`,
- }),
- );
+ const message =
+ `x402-pay dev helper unreachable at ${X402_PAY_DEV_URL}: ${err.message}. ` +
+ `Start it with: node scripts/dev-x402-pay-server.mjs`;
+ // A read-only probe (the pay-wallet picker's ?balance=1 and ?agents=1)
+ // gets the handler's real "no wallet here" shape, so dev renders the
+ // designed neutral state instead of a red network error on every load.
+ // These never fail over to the upstream: a paid call has to settle from
+ // the locally funded helper, so a POST stays a hard 502 rather than
+ // quietly spending production's wallet. writeHead (not setHeader)
+ // because Vite registers its own proxy error handler after this one and
+ // answers 500 unless the headers are already committed.
+ if ((req.method || 'GET').toUpperCase() === 'GET') {
+ res.writeHead(200, { 'content-type': 'application/json' });
+ return res.end(
+ JSON.stringify({
+ configured: false,
+ code: 'wallet_unconfigured',
+ error: message,
+ address: null,
+ sol: 0,
+ usdc: 0,
+ agents: [],
+ }),
+ );
+ }
+ res.writeHead(502, { 'content-type': 'application/json' });
+ res.end(JSON.stringify({ error: 'bad_gateway', message }));
});
},
},