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
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.mdindex 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 rnpm 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```jsimport { 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);-// [](https://three.ws/agents/...)+glanceMarkdown(agentId, { 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```jsimport { 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.++## LicenseApache-2.0diff --git a/packages/portal/src/index.js b/packages/portal/src/index.jsindex 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} urldiff --git a/packages/portal/src/mcp.js b/packages/portal/src/mcp.jsindex 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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]);+ }+ });+});