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(tty): document the terminal renderer and link it from the docs nav
nirholasb3b76c7d3726
diff --git a/docs/nav.json b/docs/nav.jsonindex 3360b3ead..e69e6fa9a 100644--- a/docs/nav.json+++ b/docs/nav.json@@ -917,6 +917,10 @@{"label": "Shared utilities","path": "shared-utilities"+ },+ {+ "label": "Terminal renderer",+ "path": "tty"}]},diff --git a/docs/tty.md b/docs/tty.mdnew file mode 100644index 000000000..662822c7e--- /dev/null+++ b/docs/tty.md@@ -0,0 +1,137 @@+# Terminal renderer++`curl three.ws/tty` and a rigged 3D agent walks in your terminal.++No GPU is involved, on either side. There is no WebGL, no browser, and nothing to+install. A software rasterizer decodes the model, evaluates its animation, blends+the joint matrices per vertex on the CPU, and rasterizes triangles into a buffer+the size of your terminal. Then it writes the result as coloured text.++```bash+curl three.ws/tty+```++Press Ctrl-C to stop it. It works in any terminal that renders colour: macOS+Terminal, iTerm2, Windows Terminal, GNOME Terminal, Alacritty, WezTerm, tmux, a+VS Code terminal, an SSH session on a box with no display.++## Why it exists++three.ws gives AI agents a body. AI agents increasingly live in a terminal. This+closes the gap: the same avatar that renders in WebGL on a web page renders in+the shell where the agent actually runs, with no client to install and no+graphics stack to negotiate.++It is also useful on its own. A rigged character, animating, is a good way to+check what a GLB actually contains before you wire it into anything.++## The endpoint++`GET /api/tty` streams frames as `text/plain`, paced in real time, so the+response body *is* the animation. It starts drawing before the model has finished+loading. Every parameter is optional.++| Parameter | Meaning | Default |+| --- | --- | --- |+| `avatar` | A public three.ws avatar id. The path form `/tty/<id>` sets this. | the default model |+| `src` | Any public GLB URL. | none |+| `w`, `h` | Columns and rows. One row is two vertical pixels. | 76 x 30 |+| `frames` | How many frames to send. `1` gives a still image. | 8 seconds worth |+| `fps` | Frames per second, 4 to 30. | 18 |+| `t` | Where in the clip to start, in seconds. | 0 |+| `spin` | Turntable speed in radians per second. `0` holds still. | 0.9 |+| `clip` | Animation name to play. | the first clip |+| `color` | `truecolor`, `ansi256`, or `mono`. | `ansi256` |+| `zoom` | 1 fits the model, higher moves closer. | 1 |+| `pitch` | Camera elevation in radians. | 0.08 |++```bash+# a specific avatar, wider, held still instead of spinning+curl 'three.ws/tty/8f2c1a90-1c4e-4b2b-9d77-3f0a1b2c3d4e?w=110&spin=0'++# any public GLB+curl 'three.ws/tty?src=https://example.com/robot.glb&frames=120'++# one frame of plain ASCII, for a README, a commit hook, or a motd+curl 'three.ws/tty?frames=1&color=mono&w=60'+```++Colour defaults to 256 rather than truecolor on purpose. `curl` forwards neither+`COLORTERM` nor `TERM`, so the server cannot know what you are running, and+guessing truecolor wrong sprays literal escape sequences across your screen.+Pass `color=truecolor` if you know your terminal handles it.++A browser asking for `/tty` gets [the page](https://three.ws/tty) instead of the+stream, because a browser renders escape codes as literal garbage. Add `?raw=1`+to see the bytes anyway.++### Limits++40 streams per IP per 10 minutes, in their own bucket so a terminal stream and a+browser render never starve each other. A single stream is capped at 600 frames+or 45 seconds. Private avatars never render: the endpoint is unauthenticated, so+it only serves models that are already public.++## Running it locally++The renderer is published as [`@three-ws/tty-3d`](https://www.npmjs.com/package/@three-ws/tty-3d).++```bash+# a local file+npx @three-ws/tty-3d ./avatar.glb++# anything on the web+npx @three-ws/tty-3d https://three.ws/avatars/default.glb --spin 1.4++# a still frame, piped somewhere+npx @three-ws/tty-3d avatar.glb --once --width 80 --color mono > frame.txt+```++Arrow keys orbit, `w`/`s` tilt, `+`/`-` zoom, space pauses, `q` quits.++Piping is safe: when stdout is not a terminal the default is a single frame, not+an infinite animation, so redirecting to a file terminates.++### As a library++```js+import { loadModel, createRenderer } from '@three-ws/tty-3d';++const model = await loadModel('./avatar.glb'); // path, https URL, or bytes+const renderer = createRenderer(model, { width: 80, height: 40 });++process.stdout.write(renderer.frame(1.25)); // one string per frame+```++`frame(time)` is pure: the same time always renders the same string. Full API in+the [package README](https://github.com/nirholas/three.ws/tree/main/packages/tty-3d).++## How it works++**Half blocks, not ASCII art.** Each cell is a `▀` with its own foreground and+background colour, so one character carries two independently coloured pixels.+That doubles vertical resolution and makes pixels square, because terminal cells+are roughly 1:2. It is why a sphere comes out round rather than squashed.++**Real skinning.** Joint matrices are evaluated per frame from the glTF animation+samplers and blended per vertex, so a rigged avatar moves its limbs. It is not a+spinning static mesh. `EXT_meshopt_compression` is decoded on the way in, because+most three.ws avatars ship compressed and a reader that skips the decoder reads+garbage vertex data rather than failing.++**Framing that holds still.** The camera radius is fixed from the widest frame of+the clip while the centre tracks the current pose. Fitting each frame alone makes+the camera breathe as the silhouette changes; fitting the union of every frame is+worse on anything with root motion, because the union is a corridor as long as+the character walks.++**Silhouette-first shading.** A key light, a fill light, and a rim term. At this+resolution the outline carries the shape, so faces turning away from the camera+are lifted rather than crushed to black.++## Related++- [Widget types](/docs/widgets) puts a live WebGL agent on a web page.+- [Avatars](/avatars) is where the models come from.+- The [roadmap](https://github.com/nirholas/three.ws#roadmap) covers native+ home-screen widgets, the other surface where an agent shows up outside a browser.diff --git a/extensions/checkout-companion/avatar.svg b/extensions/checkout-companion/avatar.svgnew file mode 100644index 000000000..8073b4cbc--- /dev/null+++ b/extensions/checkout-companion/avatar.svg@@ -0,0 +1,13 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-label="three.ws checkout companion">+ <defs>+ <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">+ <stop offset="0" stop-color="#6D5CFF"/>+ <stop offset="1" stop-color="#21D4C2"/>+ </linearGradient>+ </defs>+ <rect width="128" height="128" rx="28" fill="url(#g)"/>+ <path d="M36 40h56a6 6 0 0 1 6 6v40a6 6 0 0 1-6 6H36a6 6 0 0 1-6-6V46a6 6 0 0 1 6-6Z" fill="#ffffff" opacity=".94"/>+ <path d="M30 58h68" stroke="#6D5CFF" stroke-width="7" stroke-linecap="round" opacity=".55"/>+ <circle cx="86" cy="76" r="17" fill="#16181D"/>+ <path d="M79 76.5l5 5 10-11" stroke="#21D4C2" stroke-width="5" stroke-linecap="round" stroke-linejoin="round" fill="none"/>+</svg>diff --git a/extensions/checkout-companion/icons/icon-128.png b/extensions/checkout-companion/icons/icon-128.pngnew file mode 100644index 000000000..a32f1b2b8Binary files /dev/null and b/extensions/checkout-companion/icons/icon-128.png differdiff --git a/extensions/checkout-companion/icons/icon-16.png b/extensions/checkout-companion/icons/icon-16.pngnew file mode 100644index 000000000..7b254beadBinary files /dev/null and b/extensions/checkout-companion/icons/icon-16.png differdiff --git a/extensions/checkout-companion/icons/icon-32.png b/extensions/checkout-companion/icons/icon-32.pngnew file mode 100644index 000000000..d01629581Binary files /dev/null and b/extensions/checkout-companion/icons/icon-32.png differdiff --git a/extensions/checkout-companion/icons/icon-48.png b/extensions/checkout-companion/icons/icon-48.pngnew file mode 100644index 000000000..cfe879176Binary files /dev/null and b/extensions/checkout-companion/icons/icon-48.png differ