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.
pages/
Source HTML for every static page surface on three.ws. Around 260 files. Each file here becomes a live page at a clean URL (for example pages/tracker.html serves at https://three.ws/tracker).
Subdirectories group related surfaces and keep their URL structure:
| Directory | Serves under | What it is |
|---|---|---|
agenc/ |
/agenc/* |
AgenC embodiment surfaces (embodied, room). |
aws/, aws-marketplace/ |
/aws, /aws-marketplace/* |
AWS partner and marketplace pages. |
billing/ |
/billing/* |
Billing surfaces (API keys). |
create/ |
/create/* |
Creation flows (video). |
dashboard-next/ |
/dashboard-next/* |
Next-gen dashboard. Pages here are auto-discovered by the build; no vite config edit needed. |
embodiment/, events/, features/, play/ |
matching paths | Feature detail pages, event pages, playable demos. |
ibm/, openai/ |
/ibm, /openai |
Partner pages (ibm/ bundles its own fonts and vendor assets). |
How a page becomes a live route
There is no automatic file-to-URL mapping in production. Four pieces must line up:
- Vite input (../vite.config.js). Every page is an explicit entry in
build.rollupOptions.input.npm run buildemits it todist/pages/<name>.html, then theflatten-pages-dirplugin moves root-level pages todist/<name>.html. Nested directories (features/, dashboard-next/, ...) keep their structure insidedist/. Exception:pages/dashboard-next/is auto-discovered bydiscoverDashboardNextInputs(), so files there need no config edit. - Route table (../vercel.json). A rewrite maps the clean URL to the built file:
{"src": "/tracker", "dest": "/tracker.html"}plus a twin for the trailing-slash form"/tracker/"(some routes use a single"/tracker/?"pattern instead).vercel.jsonis a LIVE config file. Production runs on Cloud Run, and ../server/index.mjs parses this route table at startup: phase-1 rewrite rules, then a filesystem phase overdist/, then post-filesystem 404 rules. - No
.htmlfallback exists. The server'sresolveStatic()serves an exact file path or a directory'sindex.html, nothing else. A page built todist/slug.htmlis a hard 404 at/sluguntil the vercel.json rewrite lands. This shipped twice (/timeline,/tracker), which is whycheck:pagesnow gates the build. - Page registry (../data/pages.json). The single source of truth for what exists on three.ws. It feeds the sitemap,
llms.txt,features.json, and the public changelog.
In dev (npm run dev, port 3000) a middleware in vite.config.js resolves /<slug> straight to pages/<slug>.html as a generic fallback. So a page can look fully routed in dev while being a 404 in production. Do not trust dev routing; trust check:pages.
What check:pages enforces
npm run check:pages runs ../scripts/check-pages.mjs. It loads every path declared in data/pages.json and resolves each one exactly the way the production server would, using ../scripts/lib/page-routing.mjs (an offline mirror of the server's route-table split, substitute(), hasMatches(), and resolveStatic()), against the local dist/. Any declared path that falls through to the 404 fallback fails the build and prints why: either the dist file exists but no rewrite maps the clean URL to it, or the page was never built (missing vite input entry). Resolution is checked as a bare anonymous GET, so cookie-gated or crawler-only routes correctly count as unreachable.
It runs automatically inside npm run build:gcp and again in npm run deploy:gcp. The same script sweeps the live site after deploy: npm run smoke:prod is check-pages.mjs --base https://three.ws.
npm run check:dist is separate: it verifies the built agent-3d library bundle in dist/agent-3d/ and its version manifest, not pages.
Page conventions
Read two or three neighboring pages before writing one. The established head structure, in order:
- Theme boot script first, before anything else in
<head>: the inline no-flash snippet that readslocalStorage.twx_themeand setsdata-themeon<html>. Copy it from any existing page. <meta charset>,<meta name="viewport">withviewport-fit=cover.<title>and<meta name="description">, both carryingdata-i18n/data-i18n-attrattributes (the i18n pipeline indocs/i18n.mdderives its catalog from these;scripts/i18n-annotate.mjscan add them).<link rel="canonical">with the fullhttps://three.ws/<slug>URL, favicon links,manifest.webmanifest.- Shared stylesheets:
/style.css,/nav.css,/footer.css(sources in ../public/). - OG and Twitter card meta. The image comes from the dynamic generator:
/api/page-og?s=<section>&t=<title>&d=<description>&p=/<slug>. - Page-scoped styles in an inline
<style>block, built entirely from the design tokens in ../public/style.css:--space-*,--text-*,--font-*,--weight-*,--color-*,--surface-*,--radius-*,--duration-*,--ease-*,--focus-ring-*. No hardcoded colors or spacing.
Body conventions:
<header><div id="nav-container"></div></header>plus<script src="/nav.js"></script>for the shared nav. Footer via<script src="/footer.js"></script>. Brand assets via/brand.js. The i18n runtime loads last:<script type="module" src="/i18n.js"></script>(built fromsrc/i18n.js, emitted at the dist root).- Page logic is either an inline
<script type="module">or a module insrc/referenced as<script type="module" src="/src/<page>.js"></script>. - Data comes from real
/api/*endpoints. In dev,/api/*proxies to production (override withDEV_API_PROXY). Never ship sample arrays or mocks. - Admin and other internal pages add
<meta name="robots" content="noindex, nofollow" />and are not registered indata/pages.json.
Quality bar (from CLAUDE.md, enforced at review): every interactive element has hover, active, and :focus-visible states; loading, empty, error, and populated states are all designed; layouts are responsive at 320, 768, and 1440 px with wide content scrolling in its own overflow-x: auto container; semantic HTML with ARIA labels on interactive elements.
Checklist: adding a new page
- Create
pages/<slug>.htmlfollowing the conventions above. Nested surfaces go in the matching subdirectory. - Add the entry to
build.rollupOptions.inputin ../vite.config.js:'<slug>': resolve(__dirname, 'pages/<slug>.html'). Skip this step only forpages/dashboard-next/. - Add the rewrite pair to the
routesarray in ../vercel.json, before the{"handle": "filesystem"}marker, next to the other page rewrites:{"src": "/<slug>", "dest": "/<slug>.html"}and{"src": "/<slug>/", "dest": "/<slug>.html"}. - Register the page in ../data/pages.json under the right section:
path,title,description,priority,changefreq, and theaddeddate (today,YYYY-MM-DD). Theaddeddate feeds the public changelog automatically; no separatedata/changelog.jsonentry is needed for a new page. - Run
npm run build:pagesto regenerate the discovery surfaces (public/llms.txt,public/llms-full.txt,public/sitemap/index.html,public/features.json,CHANGELOG.md,public/changelog.json,public/changelog.xml). It validates your entry and fails on a malformed one. Never edit those generated files by hand. - Build and verify reachability:
npm run build, thennpm run check:pages. Green means the declared path resolves to a real file through the real route table. - Exercise the page in a browser with
npm run dev(port 3000): real API calls in the network tab, no console errors, all states reachable. - If the page is a genuinely new product surface, add a row to ../STRUCTURE.md.
Deployment note: npm run build:gcp runs the full production build (which includes check:dist and check:pages), and npm run deploy:gcp ships it, then sweeps the live site with smoke:prod. Deploys need owner approval.