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.

build(packages): register the portal, render and motion workspaces and their pages

nirholas92ba546a59f2
diff --git a/data/pages.json b/data/pages.json
index 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.json
index 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.md
index 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
```js
import { 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