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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(rules): replace the banned dashes the push lint caught in the new surfaces
nirholas9b492cc80451
diff --git a/STRUCTURE.md b/STRUCTURE.mdindex 50c7e05b2..f21acefcc 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -224,7 +224,7 @@ bottom.| iOS App Store app | [ios/](ios): Capacitor shell + config [ios/capacitor.config.ts](ios/capacitor.config.ts), Xcode project [ios/native/App/](ios/native/App), web-side native bridge [ios/src/native-bridge.js](ios/src/native-bridge.js), offline shell [ios/shell/](ios/shell), listing copy [ios/publish/](ios/publish), app association handler in [api/wk.js](api/wk.js) | In-repo · project builds and the web half ships on every deploy · awaiting an Apple Developer organization account | three.ws as a native iOS app (`ws.three.app`). A Capacitor 8 shell whose WKWebView runs the live `https://three.ws`, so the app is never a version behind the site; what makes it an app is the native layer around it. `ios/src/native-bridge.js` ships with the SITE, not the .ipa (Capacitor injects its bridge into the remote page, so `window.Capacitor` exists on three.ws only inside the app): it supplies the `navigator.share` WKWebView does not have, routes off-site links to an in-app Safari sheet instead of stranding the app's only WebView, handles universal links and `threews://` wallet returns, holds the launch screen until the first real frame, and marks `html.ios-app`. The `three-ws-ios-native-bridge` plugin in [vite.config.js](vite.config.js) copies it into `dist/` content-hashed and injects it into every built page except the third-party embed entries (671 pages, `/viewer` and `/ar` included, which a `transformIndexHtml` could not reach because they are copied verbatim from `public/`). `GET /.well-known/apple-app-site-association` is served from the API rather than a static file because Apple demands an exact path, a JSON content type and no redirect; it answers `503 not_configured` until `APPLE_TEAM_ID` is set rather than publishing an association that would fail silently on device. Docs: [ios/README.md](ios/README.md), [docs/ios-app.md](docs/ios-app.md), App Review posture [ios/docs/REVIEW-RISK.md](ios/docs/REVIEW-RISK.md), submission [ios/docs/SUBMISSION.md](ios/docs/SUBMISSION.md). || Walk Avatar browser extension | [extensions/walk-avatar/](extensions/walk-avatar) — MV3 `manifest.json`, `background.js` | In-repo · Chrome Web Store release checklist staged ([RELEASE.md](extensions/walk-avatar/RELEASE.md)) | Walks your three.ws avatar across any site and reads pages aloud — a browsing companion built on the same rig as the [walk-sdk](walk-sdk). Ships its own store-required [PRIVACY.md](extensions/walk-avatar/PRIVACY.md), [PERMISSIONS.md](extensions/walk-avatar/PERMISSIONS.md), and [TERMS.md](extensions/walk-avatar/TERMS.md). || Checkout companion browser extension | [extensions/checkout-companion/](extensions/checkout-companion) (MV3: [extract.js](extensions/checkout-companion/extract.js), [content.js](extensions/checkout-companion/content.js), [panel.js](extensions/checkout-companion/panel.js), [background.js](extensions/checkout-companion/background.js)), analysis [api/_lib/companion/checkout.js](api/_lib/companion/checkout.js), endpoint [api/companion/checkout.js](api/companion/checkout.js) | In-repo | The companion at the moment money moves: on a checkout page it reports the total against the price you were shown, money the page did not itemise, fees named and summed, whether the charge repeats, and the cancellation terms. **Arithmetic is never the model's job** (integer minor units, computed server-side) and **no finding is ever a legal verdict** (`sanitizeModelFindings()` drops any that claims an amount or calls something illegal). With no model reachable the arithmetic findings still stand. The extension **never reads an input**: `collectText`/`collectAmounts` refuse form fields, iframes and editable regions structurally, and redaction runs in the browser before anything is sent; only the hostname travels and nothing about the page is stored. Docs: [docs/checkout-companion.md](docs/checkout-companion.md). Tests: [tests/companion-checkout.test.js](tests/companion-checkout.test.js), [tests/checkout-extract.test.js](tests/checkout-extract.test.js) |-| Desktop companion app | [apps/desktop/](apps/desktop) — Electron main [src/main.js](apps/desktop/src/main.js), preload [src/preload.cjs](apps/desktop/src/preload.cjs), stage [src/renderer/](apps/desktop/src/renderer) | In-repo · packaged with electron-builder (`npm run dist`), not yet published | A transparent, click-through, always-on-top character that strolls across the bottom of the desktop and walks over to deliver what cleared the user's bar. Subscribes to `/api/companion/stream` with the same bridge token the CLI stores, and drives the published [walk embed](pages/walk-embed.html) over its postMessage contract, so it carries no 3D code of its own. Not an npm workspace: it installs and builds on its own (see [apps/desktop/README.md](apps/desktop/README.md)). |+| Desktop companion app | [apps/desktop/](apps/desktop). Electron main [src/main.js](apps/desktop/src/main.js), preload [src/preload.cjs](apps/desktop/src/preload.cjs), stage [src/renderer/](apps/desktop/src/renderer) | In-repo · packaged with electron-builder (`npm run dist`), not yet published | A transparent, click-through, always-on-top character that strolls across the bottom of the desktop and walks over to deliver what cleared the user's bar. Subscribes to `/api/companion/stream` with the same bridge token the CLI stores, and drives the published [walk embed](pages/walk-embed.html) over its postMessage contract, so it carries no 3D code of its own. Not an npm workspace: it installs and builds on its own (see [apps/desktop/README.md](apps/desktop/README.md)). || DCC tool integrations (Blender, ComfyUI) | [integrations/](integrations) — [integrations/blender/](integrations/blender), [integrations/comfyui/](integrations/comfyui), shared Python client [integrations/_pyclient/](integrations/_pyclient) | In-repo | First-party plugins that drive the public Forge pipeline (`/api/forge`) from inside the tools artists already use, so a model is generated without leaving the DCC. Docs: [integrations/README.md](integrations/README.md) || Base58 difficulty model (the honest math) | [src/solana/vanity/base58-distribution.js](src/solana/vanity/base58-distribution.js), dispatch in [src/solana/vanity/validation.js](src/solana/vanity/validation.js); ported copies in [solana-agent-sdk/src/vanity/verify.ts](solana-agent-sdk/src/vanity/verify.ts) and [mcp-server/src/lib/base58-distribution.js](mcp-server/src/lib/base58-distribution.js), held in agreement by [tests/vanity-model-parity.test.js](tests/vanity-model-parity.test.js) | In-repo | The exact probability that a random Solana address matches a vanity pattern, and the single source of truth behind every quote, price, rarity tier, bounty payout and signed receipt. Base58 is a positional encoding of a 256-bit integer, so the *leading* character is not uniform: the 40 symbols `K`-`z` are 17.2x harder to lead with than `5`-`H`, a 58x spread the old flat 58ⁿ model erased. Models are versioned (`base58-exact/v2`, superseding `58^effectiveLength`) and receipts name theirs, so attestations issued before the correction still verify. Spec: [docs/PROTOCOL-vanity.md](docs/PROTOCOL-vanity.md#41-difficulty-model-versioning) || Vanity address grinder (Rust → WASM) | [crates/vanity-grinder/](crates/vanity-grinder) → compiled to [src/solana/vanity/wasm/](src/solana/vanity/wasm); consumed by [src/agent-vanity-grinder.js](src/agent-vanity-grinder.js), [src/agent-eth-vanity-card.js](src/agent-eth-vanity-card.js) | In-repo | The Rust source behind in-browser Solana/EVM vanity-address mining. Compiled to WebAssembly so grinding runs on the visitor's machine, never the server. Surfaced as the `vanity_grinder` MCP tool and the premium pre-ground inventory (`vanity_premium`). |diff --git a/api/render/animate.js b/api/render/animate.jsindex 93a9236d7..2758b805c 100644--- a/api/render/animate.js+++ b/api/render/animate.js@@ -1,8 +1,8 @@-// GET /api/render/animate — an animated avatar as a single image file.+// GET /api/render/animate: an animated avatar as a single image file.//// https://three.ws/api/render/animate?avatar=<id>&clip=wave// https://three.ws/api/render/animate?src=https://example.com/model.glb&clip=idle-// https://three.ws/api/render/animate → the clip catalog+// https://three.ws/api/render/animate (the clip catalog)//// The output is an animated PNG: one file, no player, no script, no WebGL. It// plays in every current browser, in a GitHub README, in a Notion page, in a@@ -16,16 +16,16 @@// the whole sequence. Twenty frames cost about as much as one chromium boot.//// Query parameters:-// avatar — avatar UUID (public avatars only), or-// src — any public GLB URL (SSRF-guarded, byte-capped)-// clip — clip name from the built-in motion library (default: idle)-// frames — 1..48 (default 20)-// fps — 1..30 (default 16)-// size — 64..640 square (default 320); width/height override it-// bg — 'transparent' or a hex colour (default: transparent)-// focus — full | bust | head (default: full)-// spin — 0..360 degrees of turntable spread across the loop (default: 0)-// t — seconds into the clip for the first frame (default: 0)+// avatar = avatar UUID (public avatars only), or+// src = any public GLB URL (SSRF-guarded, byte-capped)+// clip = clip name from the built-in motion library (default: idle)+// frames = 1..48 (default 20)+// fps = 1..30 (default 16)+// size = 64..640 square (default 320); width/height override it+// bg = 'transparent' or a hex colour (default: transparent)+// focus = full | bust | head (default: full)+// spin = 0..360 degrees of turntable spread across the loop (default: 0)+// t = seconds into the clip for the first frame (default: 0)//// A caller that wants one still frame should use /api/render/glb or// /api/avatar/render; this route always returns a loop.@@ -136,7 +136,7 @@ export default wrap(async function handler(req, res) {res,200,{- renders: 'animated PNG (APNG) — plays in any <img> tag, README or embed',+ renders: 'animated PNG (APNG). Plays in any <img> tag, README or embed.',usage: '/api/render/animate?avatar=<id>&clip=<name>',params: {avatar: 'avatar UUID (public avatars only)',diff --git a/docs/start-here.md b/docs/start-here.mdindex f3b2380d5..a6acab819 100644--- a/docs/start-here.md+++ b/docs/start-here.md@@ -141,13 +141,14 @@ Curious what happens between the prompt and the model? [How the Forge works](./h- **Following Solana traders?** → [KOL Tracker](./kol-tracker.md): KOLs ranked by realized P&L computed from their own wallets' on-chain trades (never self-reported), with the public API behind it- **Listening to the economy?** → [Agent Symphony](./agent-symphony.md): /symphony plays the live agent economy as generative music; every event type has a voice, and solo mode isolates one agent by ear- **Catching up on your inbox?** → [Notifications](./notifications.md): the bell, the /notifications center, category filters, and the full inbox API+- **About to pay for something?** → [Checkout companion](./checkout-companion.md): the browser extension that reads a payment page before you pay, why the arithmetic is never a model's job, and why it never reads a form field- **Something broken on a page?** → [Feedback](./feedback.md): telling the corner companion what went wrong, what the browser attaches for you, and the boundary that keeps untrusted text from ever reaching anything with write access- **Showing off your work?** → [The creator portfolio](./creator-portfolio.md): everything on your public /u/username page, what makes an item public, and how following works from it- **Exploring our history?** → [The Story So Far](./timeline.md): three.ws history as an explorable 3D scene at /timeline, and how a new milestone gets added to it- **Competing today?** → [Daily Match](./daily-match.md): live daily standings over real agent output (actions, trades, skill sales, launches), resetting 00:00 UTC- **Developer docs** → Read the [Introduction](./introduction.md) for the full technical picture- **Contributing code?** → [Shared utilities](./shared-utilities.md) — the modules to import instead of hand-rolling: sanitized Markdown, toasts, fuzzy search, retry/circuit-breaking, bounded caches and concurrency pools, and safe CSV export-- **Wondering what happens when a third-party service goes down?** → [Upstream resilience map](./resilience.md) — every external service this platform calls, what protects each call, and the degradation contract each endpoint is held to+- **Wondering what happens when a third-party service goes down?** → [Upstream resilience map](./resilience.md): every external service this platform calls, what protects each call, and the degradation contract each endpoint is held to- **Your agent needs a face?** → [OKX.AI marketplace services](./okx-marketplace.md) — the Agent Identity Studio and the pay-per-call 3D services other agents buy from us; demo identities at [/agent-identities](/agent-identities)- **Buying 3D asset work per call?** → [The 3D Asset Pipeline](./3d-pipeline.md) — pay a few cents in USDC to rig, remesh, make game-ready, stylize, or background-remove an asset; one call, one finished URL, no account or API key- **Want your agent to have a body?** → [Embodiment](./embody.md) — one $1 USDC call turns a prompt or image into a rigged, animated, voiced 3D avatar plus a one-tag embed for any website; no account, no separate rigging stepdiff --git a/packages/knock-mcp/src/tools/act.js b/packages/knock-mcp/src/tools/act.jsindex 9be4fb7aa..01d52fa84 100644--- a/packages/knock-mcp/src/tools/act.js+++ b/packages/knock-mcp/src/tools/act.js@@ -1,4 +1,4 @@-// `knock_act` — answer, dismiss, or block one knock. Authenticated write.+// `knock_act`: answer, dismiss, or block one knock. Authenticated write.import { z } from 'zod';import { apiRequest } from '../lib/api.js';diff --git a/packages/knock-mcp/src/tools/directory.js b/packages/knock-mcp/src/tools/directory.jsindex 8c9c0dfb2..17bdca5c0 100644--- a/packages/knock-mcp/src/tools/directory.js+++ b/packages/knock-mcp/src/tools/directory.js@@ -1,4 +1,4 @@-// `knock_directory` — everyone reachable right now. Read-only, no credential.+// `knock_directory`: everyone reachable right now. Read-only, no credential.import { z } from 'zod';import { apiRequest } from '../lib/api.js';diff --git a/packages/knock-mcp/src/tools/inbox.js b/packages/knock-mcp/src/tools/inbox.jsindex 9843d6840..ffbd1b4c5 100644--- a/packages/knock-mcp/src/tools/inbox.js+++ b/packages/knock-mcp/src/tools/inbox.js@@ -1,4 +1,4 @@-// `knock_inbox` — the knocks YOUR door has taken. Authenticated, read-only.+// `knock_inbox`: the knocks YOUR door has taken. Authenticated, read-only.import { z } from 'zod';import { apiRequest } from '../lib/api.js';diff --git a/packages/knock-mcp/src/tools/quote.js b/packages/knock-mcp/src/tools/quote.jsindex 172222e87..2ddada145 100644--- a/packages/knock-mcp/src/tools/quote.js+++ b/packages/knock-mcp/src/tools/quote.js@@ -1,4 +1,4 @@-// `knock_quote` — what it costs to reach one person. Read-only, no credential.+// `knock_quote`: what it costs to reach one person. Read-only, no credential.import { z } from 'zod';import { apiRequest } from '../lib/api.js';diff --git a/packages/knock-mcp/src/tools/receipt.js b/packages/knock-mcp/src/tools/receipt.jsindex 5260b6f4c..df8c29006 100644--- a/packages/knock-mcp/src/tools/receipt.js+++ b/packages/knock-mcp/src/tools/receipt.js@@ -1,4 +1,4 @@-// `knock_receipt` — what became of a knock you sent. Read-only, no credential.+// `knock_receipt`: what became of a knock you sent. Read-only, no credential.import { z } from 'zod';import { apiRequest } from '../lib/api.js';diff --git a/packages/knock-mcp/src/tools/send.js b/packages/knock-mcp/src/tools/send.jsindex b783dad35..1ffb99ebc 100644--- a/packages/knock-mcp/src/tools/send.js+++ b/packages/knock-mcp/src/tools/send.js@@ -1,4 +1,4 @@-// `knock_send` — get one message through to a person.+// `knock_send`: get one message through to a person.//// This tool deliberately CANNOT spend. A free door is sent immediately, because// nothing moves. A priced door returns the exact recipient, amount, token and