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
build(packages): register the portal, render and motion workspaces and their pages
nirholas92ba546a59f2
diff --git a/data/pages.json b/data/pages.jsonindex 48b491173..156fe0cbd 100644--- a/data/pages.json+++ b/data/pages.json@@ -746,6 +746,14 @@"changefreq": "monthly","added": "2026-04-17"},+ {+ "path": "/docs/glance",+ "title": "Glance: agent cards for home screens",+ "description": "Put a three.ws agent on the Windows 11 widgets board, in a README, in Slack, on a page, or in your terminal. Endpoint, element, widget worker and npm client.",+ "priority": 0.6,+ "changefreq": "monthly",+ "added": "2026-08-28"+ },{"path": "/glance","title": "Glance",diff --git a/package.json b/package.jsonindex 6985d9ce8..672bdc1c1 100644--- a/package.json+++ b/package.json@@ -123,6 +123,7 @@"packages/agent-runtime","packages/render","packages/glb-diff",+ "packages/witness","packages/portal","packages/tty-avatar"],@@ -204,7 +205,7 @@"audit:route-shadowing": "node scripts/audit-route-shadowing.mjs","audit:handlers": "node scripts/audit-empty-handlers.mjs","audit:x402-catalog": "node scripts/audit-x402-catalog.mjs",- "gate": "npm run check:conflicts && npm run check:claude && npm run check:vendored && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run audit:docs && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:guards && npm run audit:tour-atlas",+ "gate": "npm run check:conflicts && npm run check:claude && npm run check:vendored && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run audit:docs && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:guards && npm run audit:tour-atlas && npm run check:ios-icons","test:gate-3d": "vitest run tests/glb-canonicalize.test.js tests/animation-retarget.test.js tests/animation-retarget-rest-pollution.test.js tests/viewer-framing.test.js","audit:mcp-golden": "node scripts/audit-mcp-golden.mjs","audit:mcp-safety": "node scripts/audit-mcp-safety.mjs",@@ -292,7 +293,7 @@"build:avatar-studio": "npm run build --prefix character-studio","build:fast": "npm run build","build:vercel": "node scripts/build-vercel.mjs",- "apply:r2-cors": "node scripts/set-r2-cors.mjs || echo '[apply:r2-cors] skipped (missing creds or transient failure \u2014 see build log)'",+ "apply:r2-cors": "node scripts/set-r2-cors.mjs || echo '[apply:r2-cors] skipped (missing creds or transient failure — see build log)'","build:all": "npm run build:chat && (npm run build & npm run build:lib & wait)","release:lib": "npm run build:lib && npm run publish:lib","clean": "rm -rf dist/* dist-lib/* || true",@@ -394,6 +395,8 @@"okx:gauntlet": "node scripts/okx-e2e-gauntlet.mjs","check:conflicts": "node scripts/check-merge-conflicts.mjs","ios:sync": "npm --prefix ios install --silent && npm --prefix ios run sync",+ "ios:icons": "node ios/scripts/make-icons.mjs",+ "check:ios-icons": "node ios/scripts/make-icons.mjs --check","ios:open": "npm --prefix ios run open","clean:worktrees": "node scripts/clean-deploy-worktrees.mjs","prep:worktree": "node scripts/prepare-deploy-worktree.mjs",diff --git a/packages/render/README.md b/packages/render/README.mdindex 78bef6576..01fcf5b82 100644--- a/packages/render/README.md+++ b/packages/render/README.md@@ -1,12 +1,32 @@# @three-ws/render-**Render rigged, animated 3D avatars with no GPU, no WebGL, and no headless-browser.** A pure JavaScript software rasterizer for glTF/GLB that outputs PNG,-animated PNG, and truecolor terminal ANSI.+Render rigged, animated 3D avatars to PNG, animated PNG, or truecolor terminal+output. **No GPU. No WebGL. No headless browser.** A pure-JavaScript software+rasterizer that runs anywhere Node runs: a serverless handler, a cron job, a+container with 512 MB of RAM, a CI step, your laptop.-Everything is a pure function of bytes in and pixels out, so the same call works-in a serverless handler, a CLI, a cron job, or a test. No display, no driver, no-Chromium.+```bash+npx @three-ws/render https://three.ws/avatars/default.glb --out avatar.png+```++This is the renderer behind every server-side avatar picture on three.ws. It+replaced a headless-chromium pipeline that cost a 300 MB browser launch and+3-15 seconds per cold render with an in-process call that takes a few hundred+milliseconds and fetches nothing.++## Why this exists++Rendering a 3D model on a server has meant one of two things: a GPU, or a+headless browser pretending to be one. Both are heavy, and both fail in the+places you most want a picture: a social-card handler with a 30 second budget,+a batch job over a hundred thousand models, a machine with no display stack at+all.++There is a third option nobody ships, because it is a lot of work: rasterize it+yourself. That is what this package is. It parses the glTF, blends the bone+matrices on the CPU, walks the triangles with a z-buffer, samples the textures+through real mip pyramids, and writes the pixels out. It is fast because it+only ever does the work a still frame actually needs.## Install@@ -14,92 +34,215 @@ Chromium.npm install @three-ws/render```-## Library+`three` is the only required dependency (used for glTF parsing, animation+sampling and matrix maths, never for rendering). `sharp` is optional and only+decodes JPEG textures; PNG textures decode in-process with `zlib`. Without+`sharp`, a JPEG-textured model renders with its material colours instead of its+maps, and everything else is identical.++## Use it++### A still```js-import { writeFile } from 'node:fs/promises';import { renderAvatar, encodePng } from '@three-ws/render';+import { writeFile } from 'node:fs/promises';const { frames } = await renderAvatar('https://three.ws/avatars/default.glb', {- width: 512,- height: 512,- focus: 'head',+ width: 1200,+ height: 630,+ focus: 'full', // 'full' | 'bust' | 'head'+ background: { inner: '#1b2440', outer: '#05060c' },});-await writeFile('avatar.png', encodePng(frames[0]));++await writeFile('card.png', encodePng(frames[0]));```-Animate it, retargeting a clip from a second file onto this skeleton by bone name:+### An animation```jsimport { renderAvatar, encodeApng } from '@three-ws/render';+import { writeFile } from 'node:fs/promises';const { frames } = await renderAvatar('avatar.glb', {- animation: 'walk.glb',- clip: 'Walk',- frames: 36,- spin: 360,+ animation: 'walk.glb', // clips are retargeted onto this rig by bone name+ clip: 'walk',+ frames: 24,+ fps: 20,+ width: 320,+ height: 320,+ background: 'transparent',});-await writeFile('turntable.png', encodeApng(frames, { fps: 20 }));++await writeFile('walk.png', encodeApng(frames, { fps: 20 }));```-## In a terminal+Animated PNG rather than GIF on purpose: GIF would quantize the render to 256+colours and hard-edge the alpha, while APNG keeps the full 24-bit image and the+soft contact shadow, and every current browser plays it.-```bash-three-ws-tty avatar.glb-three-ws-tty https://three.ws/avatars/default.glb --focus head --spin 360 --loop-three-ws-tty avatar.glb --animation walk.glb --clip Walk --out walk.png --frames 36-three-ws-tty avatar.glb --clips # list the clips and exit+### A turntable, with no animation data at all++```js+const { frames } = await renderAvatar('prop.glb', { frames: 36, spin: 360 });```-| Option | Meaning |-| --- | --- |-| `--out <file>` | Write a PNG (animated PNG when `--frames` > 1) |-| `--width`, `--height` | Output size in pixels (default: fits the terminal) |-| `--focus <mode>` | `full`, `bust`, or `head` (default: `full`) |-| `--preset <name>` | `studio`, `terminal`, or `daylight` (default: `terminal` for a tty) |-| `--clip <name\|idx>` | Clip to play, from the model or from `--animation` |-| `--animation <file>` | GLB or clip JSON to retarget onto this rig |-| `--frames <n>` | Frame count (default: 1, or 36 with `--spin`) |-| `--fps <n>` | Frames per second (default: 20) |-| `--spin <deg>` | Turntable degrees across the loop |-| `--yaw`, `--pitch` | Camera angles (defaults: 26, 6) |-| `--bg <color>` | Hex colour, or `transparent` |-| `--loop` | Keep animating in the terminal until interrupted |-| `--blocks` | Force half-blocks even where inline images work |--The terminal output adapts to what the terminal can actually do: Kitty and iTerm2-get real inline images, everything else gets truecolor half-blocks, and a-256-colour fallback exists for terminals that need it. `detectTerminal()` is-exported if you want to make that decision yourself.+### In a terminal-## API+```js+import { renderAvatar, toHalfBlocks, detectTerminal } from '@three-ws/render';-| Export | What it does |-| --- | --- |-| `renderAvatar(source, options)` | Load and render in one call. Returns `{ model, frames }`. |-| `loadModel(source, options)` / `AvatarModel` | Load once, render many times. |-| `renderFrame(model, opts)` / `renderFrames(model, opts)` | The rasterizer. |-| `frameCamera()`, `PRESETS`, `FOCUS` | Camera framing, lighting presets, focus modes. |-| `encodePng(frame)` / `encodeApng(frames, opts)` | Pixels to bytes. |-| `toHalfBlocks()`, `toKitty()`, `toITerm()`, `to256()`, `detectTerminal()`, `CURSOR` | Terminal output. |-| `retargetClip()`, `normalizeBoneName()` | Retarget a clip onto a different humanoid rig by bone name. |-| `parseClipJson()`, `loadClipJson()` | Load clips from JSON, including [`@three-ws/motion`](../motion) output. |-| `parseGlb()`, `packGlb()`, `extractImages()`, `stripImages()` | GLB container surgery. |-| `decodeImage()`, `decodePng()`, `buildMipmaps()` | Texture decoding. |+const term = detectTerminal();+const { frames } = await renderAvatar('avatar.glb', { width: 60, height: 60, preset: 'terminal' });+process.stdout.write(toHalfBlocks(frames[0], { truecolor: term.truecolor }));+```-## Why this exists+Each terminal cell carries two vertical pixels (the upper half-block glyph,+foreground over background), so a 60-column render is 60x60 pixels rather than+60x30. On Kitty, Ghostty, WezTerm and iTerm2 the CLI sends the real PNG through+the terminal's own graphics protocol instead.-Rendering an avatar server-side normally means a GPU instance or a headless-browser: slow to start, expensive to keep, and awkward to run inside a request.-A software rasterizer that is a pure function of bytes has none of those-problems. It is fast enough for an `<img>` endpoint, deterministic enough for a-snapshot test, and small enough to run in a cron job.+## CLI-## Related+```+three-ws-tty <model.glb | url> [options]++ --out <file> write a PNG (animated PNG when --frames > 1)+ --width <n> output width in pixels (default: fits the terminal)+ --height <n> output height in pixels+ --focus <mode> full | bust | head (default: full)+ --preset <name> studio | terminal | daylight (default: terminal for tty)+ --clip <name|idx> clip to play, from the model or --animation+ --animation <file> GLB or clip JSON to retarget onto this rig+ --frames <n> frame count (default: 1, or 36 with --spin)+ --fps <n> frames per second (default: 20)+ --spin <deg> turntable degrees across the loop+ --yaw <deg> camera yaw (default: 26)+ --pitch <deg> camera pitch (default: 6)+ --bg <color> hex colour or 'transparent'+ --loop keep animating in the terminal until interrupted+ --blocks force half-blocks even where inline images work+ --clips list the model's clips and exit+```++```bash+# A headshot, ready for an avatar field+three-ws-tty avatar.glb --focus head --width 512 --out headshot.png-- [`@three-ws/motion`](../motion): generate the clip this renders.-- [`@three-ws/glb-diff`](../glb-diff): the structural check alongside the visual one.-- [`STRUCTURE.md`](../../STRUCTURE.md): where every three.ws surface lives.+# A looping wave, transparent, for a README+three-ws-tty avatar.glb --animation wave.glb --clip wave --frames 24 --bg transparent --out wave.png++# Look at a model you just downloaded, without opening anything+three-ws-tty ~/Downloads/model.glb --spin 360 --loop+```++## What it renders++- **Skinned humanoid avatars**, posed by real animation clips. Bone matrices are+ blended per vertex on the CPU, and normals ride the same matrix, so a walking+ avatar shades correctly instead of shimmering.+- **Meshopt-compressed and quantized glTF** (`EXT_meshopt_compression`,+ `KHR_mesh_quantization`), which is what most three.ws avatars ship as.+- **Textures** through box-filtered mip pyramids with trilinear sampling and a+ per-triangle level of detail, so a 1024px skin atlas on a 96px avatar reads as+ skin rather than noise.+- **Transparency**: alpha-masked hair and eyelash cards, and a depth-tested+ back-to-front blended pass for genuinely transparent materials.+- **A planar projected contact shadow**, blurred, so the model sits on a surface+ instead of floating.+- **Supersampled edges**, resolved through an ACES tonemap into straight-alpha+ RGBA.++## What it does not render++Stated plainly, because a renderer that lies about its coverage is worse than+one with gaps:++- **Draco-compressed geometry** (`KHR_draco_mesh_compression`) needs a decoder+ this package does not ship. It throws with a message telling you to re-export+ with `gltfpack -cc`.+- **KTX2 / Basis textures** are skipped; the material falls back to its base+ colour factor, which is a real colour, not a placeholder.+- **Morph targets / blendshapes** are not evaluated. Skeletal animation is.+- **PBR is approximated.** Base colour, roughness and emissive drive a+ Blinn-Phong studio rig with a rim light. There is no image-based lighting, no+ metallic reflection and no ray tracing. It is built to make an avatar look+ like itself in a card, not to be a path tracer.++## API++| Export | What it does |+|---|---|+| `renderAvatar(source, options)` | Load and render in one call. Returns `{ model, frames }`. |+| `AvatarModel.load(source, options)` | Load a GLB into a posable model. |+| `model.addClips(clips)` | Retarget clips onto this skeleton by bone name. |+| `model.play(nameOrIndex)` / `model.setTime(s)` | Pose the model. |+| `renderFrame(model, options)` | One RGBA frame. |+| `renderFrames(model, options)` | A frame list, with animation and turntable spin. |+| `frameCamera(bounds, options)` | The camera used for a given focus mode. |+| `encodePng(frame)` / `encodeApng(frames, { fps })` | Image bytes, no native dependency. |+| `toHalfBlocks(frame)` / `toKitty(png)` / `toITerm(png)` | Terminal output. |+| `detectTerminal()` | Columns, truecolor support, inline-image support. |+| `parseClipJson(json)` / `loadClipJson(url)` | three.js AnimationClip JSON. |+| `parseGlb` / `packGlb` / `stripImages` / `extractImages` | The GLB container layer. |+| `normalizeBoneName(name)` / `retargetClip(clip, skeleton)` | Rig-independent bone naming. |+| `PRESETS` / `FOCUS` | Named lighting rigs and framing modes. |++`source` is a URL, a file path, an `ArrayBuffer` or a typed array. Frames are+`{ width, height, data }` where `data` is straight-alpha RGBA, which is exactly+what `sharp`, `canvas`, `ImageData` and every encoder already expect.++### Options++| Option | Default | Meaning |+|---|---|---|+| `width` / `height` | `512` | Output size in pixels. |+| `supersample` | `2` | Render scale before the box-filtered resolve (1-4). |+| `preset` | `'studio'` | `studio`, `terminal` or `daylight`. |+| `focus` | `'full'` | `full`, `bust` or `head`. |+| `yaw` / `pitch` | `26` / `6` | Camera angles in degrees. |+| `fov` | `30` | Vertical field of view. |+| `background` | preset | `'transparent'`, `'#rrggbb'`, `[top, bottom]`, or `{ inner, outer }`. |+| `shadow` | preset | Contact-shadow strength, `0` to disable. |+| `frames` / `fps` | `1` / `24` | Animation length. |+| `spin` | `0` | Turntable degrees spread across the frames. |+| `clip` | `null` | Clip name or index to play. |+| `animation` | none | A second GLB whose clips are retargeted onto this rig. |+| `maxBytes` | 64 MB | Cap on the fetched model. |+| `maxTextureSize` | `1024` | Working texture resolution. |++## Rig support++Clips are bound by normalized bone name, so a Mixamo walk drives a Ready Player+Me body. `normalizeBoneName` collapses Mixamo (`mixamorig:LeftForeArm`), Ready+Player Me (`LeftForeArm`), VRM/VRoid (`J_Bip_L_UpperArm`), Blender+(`upper_arm.L`), and bare camelCase side suffixes (`shoulderL`) onto one key. A+clip whose rig shares fewer than four bones with the target is refused rather+than played as a scramble.++## Performance++Measured on one shared vCPU, rendering the default three.ws avatar (13k+triangles, six 512-1024px textures):++| Render | Time |+|---|---|+| Load and decode the model (once, then cached) | ~1.0 s |+| 512x512, 2x supersampled | ~520 ms |+| 1200x630 OG card, 2x supersampled | ~540 ms warm |+| 288x288, no supersampling | ~60 ms |+| 16-frame animation at 288x288 | ~910 ms |++Decoding dominates the first render, so hold the `AvatarModel` if you are+rendering the same avatar more than once.++## Where it runs on three.ws++- Every OG card and avatar thumbnail, through+ [`api/_lib/render-cpu.js`](../../api/_lib/render-cpu.js). The dispatcher in+ `api/_lib/render-glb.js` tries this lane first and keeps chromium as failover.+- [`GET /api/render/animate`](../../docs/api-reference.md), which turns any+ public avatar into an animated PNG you can drop in a README.## License