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(glance): document the widget, and give the renderer its README
nirholasacdf89dc6ded
diff --git a/docs/glance.md b/docs/glance.mdnew file mode 100644index 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+[](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.mdnew file mode 100644index 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.0diff --git a/tests/api/render-cpu-lane.test.js b/tests/api/render-cpu-lane.test.jsnew file mode 100644index 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();+ });+});