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.

test(3d): cover the model diff API and skeleton parity across rigs

nirholas007ce833d833
diff --git a/packages/agent-glance/README.md b/packages/agent-glance/README.md
index abaf97c09..8a7d54dad 100644
--- a/packages/agent-glance/README.md
+++ b/packages/agent-glance/README.md
@@ -1,24 +1,16 @@
# @three-ws/agent-glance
-**A three.ws agent, on any surface that has a slot.** One agent, one live number, one link back in: the same card renders on the Windows 11 widgets board, in a GitHub README, in a Slack message, on a web page, and in your terminal.
+**Put a three.ws agent on any surface that has a slot.** Home screen widgets,
+README badges, Slack unfurls, terminal dashboards, and a live `<agent-glance>`
+web component.
-```bash
-npx @three-ws/agent-glance 0f3a1c22-9b7e-4d51-8a10-2c6f5d90ab34
-```
-
-```
-╭──────────────────────────────────────────────────────────────────╮
-│ Atlas Scout ● active │
-│ Watches the launch feed and reports what matters. │
-│ │
-│ 17 moves today │
-│ This week 96 All time 412 Skills 4 │
-│ │
-│ https://three.ws/agents/0f3a1c22-9b7e-4d51-8a10-2c6f5d90ab34 │
-╰──────────────────────────────────────────────────────────────────╯
-```
+A glance card is one agent reduced to what fits in a small rectangle: who it is,
+one live number, and a way back into it. The platform serves that card as JSON,
+as an SVG image, and as an Adaptive Card. This package is the client for all
+three, with no dependencies and no build step.
-Zero dependencies. Works in Node 18+, a browser, a service worker, and an edge runtime. Every call is bounded by a deadline, because a card is decoration on someone else's page and must never be the reason it hangs.
+Every function works in a browser, in Node 18+, in a service worker, and in an
+edge runtime. The only I/O is `fetch`.
## Install
@@ -26,106 +18,100 @@ Zero dependencies. Works in Node 18+, a browser, a service worker, and an edge r
npm install @three-ws/agent-glance
```
-## The card
-
-A glance card is public, cacheable, and side-effect free. It reads real platform state: the agent, its avatar (only when that avatar is public or unlisted), and its action log.
+## Read a card
```js
import { fetchGlanceCard } from '@three-ws/agent-glance';
const card = await fetchGlanceCard('0f3a1c22-9b7e-4d51-8a10-2c6f5d90ab34');
-
-card.name; // 'Atlas Scout'
-card.status; // 'active' | 'idle' | 'new'
-card.metric; // { label: 'Moves today', value: 17 }
-card.stats; // [{ label: 'This week', value: 96 }, ...]
-card.lastAction; // { type: 'skill.invoke', at: '...', relative: '1h ago' } | null
-card.url; // 'https://three.ws/agents/0f3a1c22-...'
+console.log(card.name, card.metric.value, card.metric.label);
```
-The full field list is in [specs/GLANCE_CARD.md](https://github.com/nirholas/three.ws/blob/main/specs/GLANCE_CARD.md).
-
-## An image for a README or Slack
+## Put it in a README
```js
-import { glanceImageUrl, glanceMarkdown } from '@three-ws/agent-glance';
-
-glanceImageUrl(id, { size: 'medium', theme: 'auto' });
-// https://three.ws/api/glance/card?agent=...&format=svg&size=medium&theme=auto
+import { glanceMarkdown } from '@three-ws/agent-glance';
-glanceMarkdown(id);
-// [![three.ws agent](https://three.ws/api/glance/card?...)](https://three.ws/agents/...)
+glanceMarkdown(agentId, { size: 'medium', theme: 'auto' });
+// [![three.ws agent](https://three.ws/api/glance/card?agent=...&format=svg&size=medium&theme=auto)](https://three.ws/agents/...)
```
-Sizes are `small` (240x240), `medium` (480x200) and `large` (480x300). Theme `auto` ships both palettes inside the SVG and lets `prefers-color-scheme` choose, which GitHub and Slack both honour.
+The SVG endpoint is the one for any host that only takes a picture: a README, a
+Slack message, an issue comment. `glanceImageUrl()` gives you the bare URL.
-## A live card on a page
+## Put it on a page
-The element is hosted by three.ws, so a page needs no bundler and no npm install:
+```js
+import { glanceEmbedHtml } from '@three-ws/agent-glance';
+glanceEmbedHtml(agentId, { size: 'large', theme: 'dark' });
+```
```html
<script type="module" src="https://three.ws/glance/element.js"></script>
-<agent-glance agent="0f3a1c22-9b7e-4d51-8a10-2c6f5d90ab34" size="medium" theme="auto"></agent-glance>
+<agent-glance agent="0f3a1c22-9b7e-4d51-8a10-2c6f5d90ab34" size="large" theme="dark"></agent-glance>
```
-It is real DOM, not an image: hoverable, focusable, and readable by a screen reader. It refreshes every 5 minutes (`refresh="0"` disables it) and stops entirely while the tab is hidden or the element is off screen. `glanceEmbedHtml(id)` prints that snippet for you.
+The live element updates on its own; the image URL is the no-script fallback.
-## An Adaptive Card
-
-For a host that renders Adaptive Cards directly (the Windows widgets board, Teams, any Adaptive Card renderer):
+## Put it in a widget board
```js
import { fetchGlanceAdaptiveCard } from '@three-ws/agent-glance';
-const adaptive = await fetchGlanceAdaptiveCard(id); // version 1.6, already bound
+const adaptive = await fetchGlanceAdaptiveCard(agentId);
```
-## CLI
+For any host that renders an Adaptive Card directly: the Windows widgets board,
+Teams, or your own renderer.
+
+## Put it in a terminal
```bash
-agent-glance <agent-id> # the card, in your terminal
-agent-glance <agent-id> --watch 60 # redraw every 60 seconds
-agent-glance <agent-id> --json # the raw model
-agent-glance <agent-id> --markdown # a README snippet
-agent-glance <agent-id> --html # an embed snippet
-agent-glance <agent-id> --svg card.svg # write the image to a file
+agent-glance 0f3a1c22-9b7e-4d51-8a10-2c6f5d90ab34
+agent-glance <id> --watch 30
+agent-glance <id> --markdown
+agent-glance <id> --svg card.svg
```
-Options: `--size`, `--theme`, `--origin`, `--no-color`.
+| Option | Meaning |
+| --- | --- |
+| `--json` | The card model as JSON |
+| `--markdown` | A README snippet, image linked to the agent |
+| `--html` | An embed snippet for a web page |
+| `--svg <file>` | Write the card image to a file |
+| `--watch [seconds]` | Redraw on an interval (default 60) |
+| `--size <s>` | `small`, `medium`, `large` (default `medium`) |
+| `--theme <t>` | `auto`, `light`, `dark` (default `auto`) |
+| `--origin <url>` | API origin (default `https://three.ws`) |
+| `--no-color` | Plain text, no ANSI |
+
+`renderGlanceAnsi(card, opts)` is exported, so any dashboard that lives in a
+shell can draw the same card the CLI does.
## API
| Export | What it does |
| --- | --- |
-| `fetchGlanceCard(id, opts?)` | The card model. Throws `GlanceError` on a bad id, a 404, or an unreachable host. |
-| `fetchGlanceAdaptiveCard(id, opts?)` | The same card as a bound Adaptive Card. |
-| `glanceCardUrl(id, opts?)` | The JSON endpoint URL. |
-| `glanceImageUrl(id, opts?)` | The SVG endpoint URL. |
-| `glanceMarkdown(id, opts?)` | A README snippet. |
-| `glanceEmbedHtml(id, opts?)` | A page embed snippet. |
-| `renderGlanceAnsi(card, opts?)` | The card as ANSI for a terminal. |
-| `GlanceError` | Carries `status` and `agentId`. |
-
-Options common to all of them: `origin` (default `https://three.ws`), `size`, `theme`, plus `timeoutMs`, `signal` and `fetchImpl` on the fetchers.
-
-## Errors
-
-Every failure is one class, and it says what to do:
-
-```js
-try {
- await fetchGlanceCard(id);
-} catch (err) {
- err.status; // 404 when the agent is not on three.ws, 0 when the host was unreachable
- err.agentId;
-}
-```
-
-An id that is not a uuid throws before any network call, so a typo in a README fails at build time rather than rendering a broken image forever.
+| `fetchGlanceCard(id, opts?)` | The card model as JSON |
+| `fetchGlanceAdaptiveCard(id, opts?)` | The same card shaped as an Adaptive Card |
+| `glanceCardUrl(id, opts?)` | The JSON endpoint URL |
+| `glanceImageUrl(id, opts?)` | The `<img>`-ready SVG URL |
+| `glanceMarkdown(id, opts?)` | A README snippet |
+| `glanceEmbedHtml(id, opts?)` | A page embed snippet |
+| `renderGlanceAnsi(card, opts?)` | The card drawn for a terminal |
+| `GLANCE_ORIGIN`, `GLANCE_SIZES`, `GLANCE_THEMES` | The accepted values, as data |
+| `GlanceError` | Thrown with `status` and `agentId` attached, so a caller can tell a missing agent from an unreachable API |
+
+All fetching functions take `{ origin, timeoutMs, signal, fetchImpl }`. Pass
+`fetchImpl` to run against a mock-free test server or a custom transport.
## Related
- The live playground and install guide: [three.ws/glance](https://three.ws/glance)
- Docs: [three.ws/docs/glance](https://three.ws/docs/glance)
-- Embeddable 3D avatars (a different product: the agent's body, on your page): [three.ws/widgets](https://three.ws/widgets)
+- The wire format: [specs/GLANCE_CARD.md](https://github.com/nirholas/three.ws/blob/main/specs/GLANCE_CARD.md)
+- Embeddable 3D avatars, a different product (the agent's body, on your page): [three.ws/widgets](https://three.ws/widgets)
+- [`STRUCTURE.md`](../../STRUCTURE.md): where every three.ws surface lives.
+
+## License
Apache-2.0
diff --git a/packages/portal/src/index.js b/packages/portal/src/index.js
index 0c06e8f6f..60e9f48b9 100644
--- a/packages/portal/src/index.js
+++ b/packages/portal/src/index.js
@@ -68,6 +68,32 @@ export async function fetchWorld(url, opts = {}) {
return { world: body.world, outline: body.outline, cached: !!body.cached, stale: !!body.stale };
}
+/**
+ * Read a page's structure without building a world: the heading spine, the
+ * weight of each section, and where it links. Cheaper over the wire than a
+ * world, and the right call when you want to compare pages rather than walk one.
+ * @param {string} url
+ * @param {{ endpoint?: string, fetch?: typeof fetch, signal?: AbortSignal }} [opts]
+ * @returns {Promise<{ outline: object, cached: boolean, stale: boolean }>}
+ */
+export async function fetchOutline(url, opts = {}) {
+ const impl = opts.fetch || globalThis.fetch;
+ if (!impl) throw new PortalError('no_fetch', 'No fetch implementation available. Pass one as opts.fetch.', 0);
+ const res = await impl(endpointFor(url, { ...opts, include: 'outline' }), {
+ headers: { accept: 'application/json' },
+ signal: opts.signal,
+ });
+ const body = await res.json().catch(() => null);
+ if (!res.ok || !body?.outline) {
+ throw new PortalError(
+ body?.error || `http_${res.status}`,
+ body?.error_description || `Portal could not read ${url}.`,
+ res.status,
+ );
+ }
+ return { outline: body.outline, cached: !!body.cached, stale: !!body.stale };
+}
+
/**
* The same world as a glTF binary, ready for Blender, Unity, AR, or any viewer.
* @param {string} url
diff --git a/packages/portal/src/mcp.js b/packages/portal/src/mcp.js
index 300f48e06..aec7f5781 100755
--- a/packages/portal/src/mcp.js
+++ b/packages/portal/src/mcp.js
@@ -27,7 +27,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
-import { fetchWorld, describeWorld, PORTAL_API, PORTAL_PAGE, PortalError } from './index.js';
+import { fetchWorld, fetchOutline, describeWorld, PORTAL_API, PORTAL_PAGE, PortalError } from './index.js';
const endpoint = process.env.PORTAL_API || PORTAL_API;
const page = process.env.PORTAL_PAGE || PORTAL_PAGE;
@@ -100,8 +100,7 @@ export function createServer() {
},
async ({ url }) => {
try {
- const { outline, cached } = await fetchWorld(url, { endpoint, include: 'outline' });
- if (!outline) throw new PortalError('no_outline', 'The API returned no outline for that page.', 502);
+ const { outline, cached } = await fetchOutline(url, { endpoint });
return ok({
source: url,
cached,
diff --git a/tests/model-diff-api.test.js b/tests/model-diff-api.test.js
new file mode 100644
index 000000000..88c9bd865
--- /dev/null
+++ b/tests/model-diff-api.test.js
@@ -0,0 +1,172 @@
+// Tests for the free 3D Diff endpoint (/api/3d/diff), its catalog descriptor,
+// and the diff_models MCP tool.
+//
+// The engine itself is covered exhaustively in packages/glb-diff/tests; what is
+// under test here is the HTTP contract around it, which is where a caller gets
+// hurt. Every one of these cases is a 4xx a CI job has to be able to tell apart
+// from a real regression, so they are asserted individually rather than as
+// "does not 500".
+
+import { describe, expect, it } from 'vitest';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import diffHandler from '../api/3d/diff.js';
+import diffEntry from '../api/_lib/3d-catalog/diff.js';
+import { loadCatalog, normalizeEntry } from '../api/_lib/3d-catalog/index.js';
+import { toolDefs } from '../api/_mcp/tools/models.js';
+import { describeModel, diffDescriptions } from '@three-ws/glb-diff';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+function mockRes() {
+ return {
+ statusCode: 200,
+ _headers: {},
+ _body: '',
+ setHeader(k, v) {
+ this._headers[k.toLowerCase()] = v;
+ },
+ getHeader(k) {
+ return this._headers[k.toLowerCase()];
+ },
+ end(b) {
+ this._body = b || '';
+ },
+ get headersSent() {
+ return false;
+ },
+ get writableEnded() {
+ return false;
+ },
+ get json() {
+ try {
+ return JSON.parse(this._body);
+ } catch {
+ return null;
+ }
+ },
+ };
+}
+
+function mockReq({ method = 'GET', query = {}, headers = {} } = {}) {
+ return {
+ method,
+ url: '/api/3d/diff',
+ query,
+ headers: { accept: 'application/json', origin: 'http://localhost:3000', ...headers },
+ socket: { remoteAddress: '127.0.0.1' },
+ };
+}
+
+async function call(query, method = 'GET') {
+ const res = mockRes();
+ await diffHandler(mockReq({ method, query }), res);
+ return res;
+}
+
+describe('GET /api/3d/diff contract', () => {
+ it('rejects a method it does not serve and advertises what it does', async () => {
+ const res = mockRes();
+ await diffHandler(mockReq({ method: 'DELETE' }), res);
+ expect(res.statusCode).toBe(405);
+ expect(res.getHeader('allow')).toContain('GET');
+ });
+
+ it('names which side is missing rather than saying "missing url"', async () => {
+ const res = await call({ a: 'https://three.ws/avatars/xbot.glb' });
+ expect(res.statusCode).toBe(400);
+ expect(res.json.error).toBe('missing_url');
+ expect(res.json.error_description).toContain('"b"');
+ });
+
+ it('refuses a private address without reaching for it', async () => {
+ const res = await call({ a: 'http://127.0.0.1/model.glb', b: 'https://three.ws/avatars/xbot.glb' });
+ expect(res.statusCode).toBe(400);
+ expect(res.json.error).toBe('invalid_url');
+ expect(res.json.error_description).toContain('"a"');
+ });
+
+ it('refuses a scheme that is not http(s)', async () => {
+ const res = await call({ a: 'file:///etc/passwd', b: 'https://three.ws/avatars/xbot.glb' });
+ expect(res.statusCode).toBe(400);
+ expect(res.json.error).toBe('invalid_url');
+ });
+
+ it('rejects an output format it cannot produce', async () => {
+ const res = await call({ a: 'https://three.ws/avatars/xbot.glb', b: 'https://three.ws/avatars/xbot.glb', format: 'yaml' });
+ expect(res.statusCode).toBe(400);
+ expect(res.json.error).toBe('invalid_format');
+ expect(res.json.error_description).toContain('markdown');
+ });
+});
+
+describe('catalog registration', () => {
+ it('publishes a descriptor the assembler accepts', () => {
+ const normalized = normalizeEntry(diffEntry, 'diff.js');
+ expect(normalized).toBeTruthy();
+ expect(normalized.path).toBe('/api/3d/diff');
+ expect(normalized.methods).toContain('GET');
+ expect(diffEntry.free).toBe(true);
+ expect(diffEntry.keyless).toBe(true);
+ });
+
+ it('appears in the assembled free-3D-API catalog', async () => {
+ const entries = await loadCatalog({ fresh: true });
+ expect(entries.map((e) => e.path)).toContain('/api/3d/diff');
+ });
+
+ it('documents both inputs and the severity field callers gate on', () => {
+ expect(diffEntry.inputSchema.required).toEqual(['a', 'b']);
+ expect(diffEntry.outputSchema.properties.severity.enum).toEqual([
+ 'none',
+ 'cosmetic',
+ 'minor',
+ 'major',
+ 'breaking',
+ ]);
+ });
+});
+
+describe('diff_models MCP tool', () => {
+ const tool = toolDefs.find((t) => t.name === 'diff_models');
+
+ it('is registered beside the other model tools', () => {
+ expect(tool).toBeTruthy();
+ expect(tool.inputSchema.required).toEqual(['before', 'after']);
+ expect(tool.inputSchema.additionalProperties).toBe(false);
+ });
+
+ it('declares itself read-only and non-destructive so a client may auto-approve it', () => {
+ expect(tool.annotations.readOnlyHint).toBe(true);
+ expect(tool.annotations.destructiveHint).toBe(false);
+ });
+});
+
+// One end-to-end pass over real rigged assets in this repo. The endpoint above
+// is covered without network; this proves the engine the endpoint calls agrees
+// with what the page and the CLI would report for the same two files.
+describe('the engine behind the endpoint, on real avatars', () => {
+ it('finds only the clip difference between two exports of one rig', async () => {
+ const [a, b] = await Promise.all([
+ readFile(path.join(REPO_ROOT, 'animation-sources/xbot-idle.glb')),
+ readFile(path.join(REPO_ROOT, 'animation-sources/xbot-walk.glb')),
+ ]);
+ const changes = diffDescriptions(
+ await describeModel(new Uint8Array(a), { name: 'xbot-idle.glb' }),
+ await describeModel(new Uint8Array(b), { name: 'xbot-walk.glb' }),
+ );
+ expect(changes.sections.meshes.changed).toBe(0);
+ expect(changes.sections.skins.changed).toBe(0);
+ expect(changes.sections.animations.renamed).toEqual([{ from: 'idle', to: 'walk', name: 'walk' }]);
+ });
+
+ it('calls a model compared with itself identical', async () => {
+ const bytes = new Uint8Array(await readFile(path.join(REPO_ROOT, 'animation-sources/xbot-idle.glb')));
+ const description = await describeModel(bytes, { name: 'xbot-idle.glb' });
+ const changes = diffDescriptions(description, description);
+ expect(changes.identical).toBe(true);
+ expect(changes.severity).toBe('none');
+ });
+});
diff --git a/tests/motion-skeleton-parity.test.js b/tests/motion-skeleton-parity.test.js
new file mode 100644
index 000000000..3b05e37cc
--- /dev/null
+++ b/tests/motion-skeleton-parity.test.js
@@ -0,0 +1,37 @@
+// The published motion package carries its own copy of the reference skeleton,
+// because it runs standalone on npm and cannot import out of `src/`. Both files
+// are written by scripts/build-canonical-rest.mjs from one measurement pass.
+//
+// This test is what makes that copy safe. If the two ever disagree, every clip
+// @three-ws/motion emits is authored against a different body than the one the
+// site retargets onto, and the symptom downstream is "the animation looks
+// slightly wrong" with nothing pointing back here. Re-run the generator to fix
+// a failure; do not edit either file by hand.
+
+import { describe, it, expect } from 'vitest';
+
+import * as site from '../src/animation-canonical-rest.js';
+import * as pkg from '../packages/motion/src/rig/skeleton-data.js';
+
+const TABLES = ['CANONICAL_REST', 'CANONICAL_REST_WORLD', 'CANONICAL_REST_POSITION', 'CANONICAL_PARENT'];
+
+describe('the motion package and the site share one reference skeleton', () => {
+ it('exports the same four tables', () => {
+ for (const table of TABLES) {
+ expect(site[table], `src/animation-canonical-rest.js is missing ${table}`).toBeTruthy();
+ expect(pkg[table], `packages/motion skeleton-data.js is missing ${table}`).toBeTruthy();
+ }
+ });
+
+ it('covers the same bones', () => {
+ for (const table of TABLES) {
+ expect(Object.keys(pkg[table]).sort()).toEqual(Object.keys(site[table]).sort());
+ }
+ });
+
+ it('holds identical values, to the last bit', () => {
+ for (const table of TABLES) {
+ expect(pkg[table], `${table} drifted; re-run npm run build:canonical-rest`).toEqual(site[table]);
+ }
+ });
+});