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.

docs(glance): document the widget, and give the renderer its README

nirholasacdf89dc6ded
diff --git a/docs/glance.md b/docs/glance.md
new file mode 100644
index 000000000..01cb80e69
--- /dev/null
+++ b/docs/glance.md
@@ -0,0 +1,157 @@
+# Glance: your agent on every home screen
+
+A **glance card** is one three.ws agent reduced to what fits in a slot: who it is, one live number, and a way back in. The same card renders on the Windows 11 widgets board, in a GitHub README, in a Slack message, on any web page, and in your terminal, from one public endpoint.
+
+Try it: [three.ws/glance](https://three.ws/glance).
+
+This is a different product from the [embeddable 3D widgets](https://three.ws/widgets). Those put your agent's **body** on a page. Glance puts your agent's **status** on a surface that cannot run WebGL, which is every operating system widget host there is.
+
+---
+
+## The fastest version
+
+An image, anywhere an image goes:
+
+```
+https://three.ws/api/glance/card?agent=<agent-id>&format=svg
+```
+
+```markdown
+[![My agent](https://three.ws/api/glance/card?agent=<agent-id>&format=svg)](https://three.ws/agents/<agent-id>)
+```
+
+A live card on a page:
+
+```html
+<script type="module" src="https://three.ws/glance/element.js"></script>
+<agent-glance agent="<agent-id>"></agent-glance>
+```
+
+In your terminal:
+
+```bash
+npx @three-ws/agent-glance <agent-id> --watch 60
+```
+
+Your agent id is the uuid in the URL of its profile page: `https://three.ws/agents/<agent-id>`.
+
+---
+
+## What is on the card
+
+Everything comes from real platform state. There is no sample card and no placeholder number.
+
+| Field | Where it comes from |
+| --- | --- |
+| `name`, `description` | `agent_identities` |
+| `image` | the agent's avatar thumbnail, **only** when that avatar is public or unlisted; otherwise `null` and the card draws a generated monogram |
+| `metric` | actions in the last 24 hours ("Moves today") |
+| `stats` | actions this week, actions all time, then skills (or days live when the agent has no skills yet) |
+| `lastAction` | the most recent entry in the agent's action log, with a relative time |
+| `status` | `active` (acted in the last 24h), `idle` (has acted, not today), `new` (has never acted) |
+| `headline` | the one-line state, written for the status: a `new` agent's card says what to do next rather than showing a bare zero |
+| `accent` | a stable colour pair derived from the agent id, so a card without a thumbnail still looks like that specific agent |
+
+The wire format is pinned in [specs/GLANCE_CARD.md](https://github.com/nirholas/three.ws/blob/main/specs/GLANCE_CARD.md).
+
+---
+
+## The endpoint
+
+### `GET /api/glance/card`
+
+Public, cacheable, side-effect free, no session required.
+
+| Parameter | Values | Default |
+| --- | --- | --- |
+| `agent` | agent uuid (required) | |
+| `format` | `json`, `svg`, `adaptive` | `json` |
+| `size` | `small` (240x240), `medium` (480x200), `large` (480x300). SVG only | `medium` |
+| `theme` | `auto`, `light`, `dark`. SVG only | `auto` |
+
+```bash
+curl -s "https://three.ws/api/glance/card?agent=<agent-id>" | jq '.metric'
+# { "label": "Moves today", "value": 17 }
+```
+
+The response carries an `ETag`; send it back as `if-none-match` and you get a `304`. Cards are cached for two minutes at the edge and served stale for ten while revalidating, so a widget board polling every fifteen minutes almost never touches the database.
+
+`theme=auto` puts both palettes inside the SVG behind a `prefers-color-scheme` media query, which GitHub and Slack both honour, so one URL is correct in light mode and dark mode.
+
+A missing agent answers `404` with a real card that says so, not a broken image. That matters when the card is sitting in someone's home screen slot.
+
+### `GET /api/glance/mine`
+
+Session-scoped. Returns `{ signedIn, card, agents, signInUrl, createUrl }` for the caller's own agent, plus the list of agents they own so a widget can be pointed at a different one. Signed out is a `200` with `signedIn: false`, not a `401`: a widget that renders an error is a widget people remove.
+
+### `GET /api/glance/template`
+
+The Adaptive Card template (version 1.6) that the Windows widgets board binds `/api/glance/mine` data to. `format=adaptive` on the card endpoint returns the same layout already bound, for hosts that do not template.
+
+---
+
+## On the Windows 11 widgets board
+
+three.ws declares a `widgets` member in its PWA manifest, so the widget installs with the app: no store submission, no separate download.
+
+1. Open [three.ws](https://three.ws) in Edge and install it (the install icon in the address bar).
+2. Open the widgets board (`Win + W`) and choose **Add widgets**.
+3. Pick **Agent glance**.
+
+The board then talks to the site's service worker, which supplies the data:
+
+| Event | What happens |
+| --- | --- |
+| `widgetinstall` | fetch `/api/glance/mine`, push it into the host |
+| `widgetresume` | render from the cached payload, then refresh |
+| `widgetclick` | refresh on demand |
+| `widgetuninstall` | drop the cached payload |
+| `periodicsync` | refresh every pinned widget on the platform's schedule |
+
+Two behaviours are deliberate: signed out renders a sign-in card rather than an error, and an offline machine renders the last card it saw, labelled `(offline)`, rather than an empty slot. The implementation is [public/glance-sw.js](https://github.com/nirholas/three.ws/blob/main/public/glance-sw.js), covered by `tests/glance-sw.test.js`.
+
+---
+
+## The `<agent-glance>` element
+
+```html
+<script type="module" src="https://three.ws/glance/element.js"></script>
+<agent-glance agent="<agent-id>" size="medium" theme="auto" refresh="300"></agent-glance>
+```
+
+| Attribute | Values | Default |
+| --- | --- | --- |
+| `agent` | agent uuid (required) | |
+| `size` | `small`, `medium`, `large` | `medium` |
+| `theme` | `auto`, `light`, `dark` | `auto` |
+| `refresh` | seconds between refreshes, `0` disables | `300` |
+| `origin` | override the API origin | `https://three.ws` |
+
+It is real DOM inside a shadow root, so it is selectable, focusable and readable by a screen reader, and it cannot inherit or leak your page's CSS. It draws a skeleton while loading, a retry affordance on failure, and keeps the last good card if a later refresh fails. It stops polling entirely while the tab is hidden or the element is off screen.
+
+Two events bubble: `glance:load` (detail is the card) and `glance:error` (detail is the error).
+
+---
+
+## The npm client
+
+```bash
+npm install @three-ws/agent-glance
+```
+
+```js
+import { fetchGlanceCard, glanceImageUrl, glanceMarkdown } from '@three-ws/agent-glance';
+
+const card = await fetchGlanceCard(id);
+console.log(`${card.name}: ${card.metric.value} ${card.metric.label.toLowerCase()}`);
+```
+
+Zero dependencies, bounded deadlines on every call, and a `GlanceError` that carries `status` and `agentId`. An id that is not a uuid throws before any network call, so a typo fails at build time rather than rendering a broken image forever. Full reference: [packages/agent-glance/README.md](https://github.com/nirholas/three.ws/blob/main/packages/agent-glance/README.md).
+
+---
+
+## Where this is going
+
+Glance is phase 5 of the [roadmap](https://github.com/nirholas/three.ws/blob/main/README.md#roadmap). Windows 11 and the web are live. Android is next (the signed `ws.three.app` shell already ships, the app widget provider is the remaining piece), then macOS and iOS through a shared WidgetKit extension. The scoped work order is [prompts/roadmap/native-widgets.md](https://github.com/nirholas/three.ws/blob/main/prompts/roadmap/native-widgets.md).
+
+Every one of those surfaces consumes the endpoint documented above. The card is the contract; the hosts are just slots.
diff --git a/packages/render/README.md b/packages/render/README.md
new file mode 100644
index 000000000..78bef6576
--- /dev/null
+++ b/packages/render/README.md
@@ -0,0 +1,106 @@
+# @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.
+
+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.
+
+## Install
+
+```bash
+npm install @three-ws/render
+```
+
+## Library
+
+```js
+import { writeFile } from 'node:fs/promises';
+import { renderAvatar, encodePng } from '@three-ws/render';
+
+const { frames } = await renderAvatar('https://three.ws/avatars/default.glb', {
+ width: 512,
+ height: 512,
+ focus: 'head',
+});
+await writeFile('avatar.png', encodePng(frames[0]));
+```
+
+Animate it, retargeting a clip from a second file onto this skeleton by bone name:
+
+```js
+import { renderAvatar, encodeApng } from '@three-ws/render';
+
+const { frames } = await renderAvatar('avatar.glb', {
+ animation: 'walk.glb',
+ clip: 'Walk',
+ frames: 36,
+ spin: 360,
+});
+await writeFile('turntable.png', encodeApng(frames, { fps: 20 }));
+```
+
+## In a terminal
+
+```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
+```
+
+| 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.
+
+## API
+
+| 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. |
+
+## Why this exists
+
+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.
+
+## Related
+
+- [`@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.
+
+## License
+
+Apache-2.0
diff --git a/tests/api/render-cpu-lane.test.js b/tests/api/render-cpu-lane.test.js
new file mode 100644
index 000000000..e8dbb667a
--- /dev/null
+++ b/tests/api/render-cpu-lane.test.js
@@ -0,0 +1,107 @@
+// The render dispatcher: CPU first, chromium as failover.
+//
+// Every server-side avatar picture on the platform goes through
+// renderGlbToPng: OG cards, avatar thumbnails, forge thumbnails, the batch
+// cron, /api/render/glb. As of the software rasterizer landing, that function
+// is a dispatcher rather than a chromium call, so these tests hold the two
+// properties every one of those callers depends on: the fast lane is actually
+// taken, and a model it cannot decode still comes back as a picture.
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const CPU_PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x63, 0x70, 0x75]);
+const BROWSER_PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x62, 0x72]);
+
+const renderGlbToPngCpu = vi.fn();
+
+vi.mock('../../api/_lib/render-cpu.js', () => ({
+ renderGlbToPngCpu: (...args) => renderGlbToPngCpu(...args),
+ renderGlbToApngCpu: vi.fn(),
+ isUnsupportedModelError: () => false,
+ clearModelCache: () => {},
+}));
+
+vi.mock('../../api/_lib/fetch-model.js', () => ({
+ fetchModel: vi.fn(async () => ({ bytes: new Uint8Array([1, 2, 3]) })),
+}));
+
+/** A puppeteer stand-in whose pages always screenshot successfully. */
+function fakeBrowser() {
+ return {
+ connected: true,
+ on() {},
+ async newPage() {
+ return {
+ async setViewport() {},
+ async setContent() {},
+ async waitForFunction() {},
+ async evaluate() {
+ return null;
+ },
+ async screenshot() {
+ return BROWSER_PNG;
+ },
+ async close() {},
+ };
+ },
+ };
+}
+
+beforeEach(() => {
+ renderGlbToPngCpu.mockReset();
+ delete process.env.RENDER_CPU_LANE;
+});
+
+afterEach(async () => {
+ const { __setBrowserForTests } = await import('../../api/_lib/render-glb.js');
+ __setBrowserForTests(null);
+ vi.restoreAllMocks();
+});
+
+describe('renderGlbToPng dispatcher', () => {
+ it('validates arguments before touching either lane', async () => {
+ const { renderGlbToPng } = await import('../../api/_lib/render-glb.js');
+ await expect(renderGlbToPng({})).rejects.toThrow(/glbUrl required/);
+ await expect(renderGlbToPng({ glbUrl: 42 })).rejects.toThrow(/glbUrl required/);
+ expect(renderGlbToPngCpu).not.toHaveBeenCalled();
+ });
+
+ it('takes the CPU lane and never boots a browser', async () => {
+ renderGlbToPngCpu.mockResolvedValue(CPU_PNG);
+ const { renderGlbToPng, __setBrowserForTests } = await import('../../api/_lib/render-glb.js');
+ // No browser is registered: if the dispatcher reached chromium at all,
+ // the launcher would run and this test would not return a PNG.
+ __setBrowserForTests(null);
+ const png = await renderGlbToPng({ glbUrl: 'https://example.com/a.glb', width: 200, height: 100 });
+ expect(png).toBe(CPU_PNG);
+ expect(renderGlbToPngCpu).toHaveBeenCalledWith(
+ expect.objectContaining({ glbUrl: 'https://example.com/a.glb', width: 200, height: 100 }),
+ );
+ });
+
+ it('falls back to chromium when the CPU lane cannot decode the model', async () => {
+ renderGlbToPngCpu.mockRejectedValue(new Error('KHR_draco_mesh_compression needs an external decoder'));
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const { renderGlbToPng, __setBrowserForTests } = await import('../../api/_lib/render-glb.js');
+ __setBrowserForTests(fakeBrowser());
+ const png = await renderGlbToPng({ glbUrl: 'https://example.com/draco.glb' });
+ expect(png).toBe(BROWSER_PNG);
+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('cpu lane fell back'), expect.anything());
+ });
+
+ it('falls back when the CPU lane returns nothing usable', async () => {
+ renderGlbToPngCpu.mockResolvedValue(Buffer.alloc(0));
+ const { renderGlbToPng, __setBrowserForTests } = await import('../../api/_lib/render-glb.js');
+ __setBrowserForTests(fakeBrowser());
+ expect(await renderGlbToPng({ glbUrl: 'https://example.com/empty.glb' })).toBe(BROWSER_PNG);
+ });
+
+ it('can be pinned back onto chromium without a deploy', async () => {
+ process.env.RENDER_CPU_LANE = 'off';
+ renderGlbToPngCpu.mockResolvedValue(CPU_PNG);
+ const { renderGlbToPng, __setBrowserForTests } = await import('../../api/_lib/render-glb.js');
+ __setBrowserForTests(fakeBrowser());
+ expect(await renderGlbToPng({ glbUrl: 'https://example.com/a.glb' })).toBe(BROWSER_PNG);
+ expect(renderGlbToPngCpu).not.toHaveBeenCalled();
+ });
+});