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): specify the card format a third-party host has to render
nirholas3810bc131c2e
diff --git a/packages/portal/README.md b/packages/portal/README.mdnew file mode 100644index 000000000..26a954872--- /dev/null+++ b/packages/portal/README.md@@ -0,0 +1,174 @@+<div align="center">++# @three-ws/portal++**Turn any website into a walkable 3D world.**++Paste an address; get a place. Every section becomes a building sized by what it+says, every link becomes a door you can step through, every image becomes a+billboard, every code block becomes a monolith. Walk it in the browser, download+it as a `.glb`, embed it in your own page, or hand it to an agent over MCP.++[Quick start](#quick-start) · [How a page becomes a place](#how-a-page-becomes-a-place) · [API](#api) · [CLI](#cli) · [MCP](#mcp) · [Manners](#manners)++</div>++---++## Why++Every tool that "visualizes a website" draws a node graph. A graph tells you a+site has 40 pages; it does not tell you which section carries the weight, where+the dead ends are, or what it feels like to arrive. A **place** does, because+size, distance and direction are things people read without being taught.++Portal turns the page you already have into that place, deterministically, with+no model in the loop: the same URL always builds the same city, so a link you+share opens the world you walked.++## Quick start++```bash+npm install @three-ws/portal+```++```js+import { fetchWorld, describeWorld } from '@three-ws/portal';++const { world } = await fetchWorld('example.com');+console.log(describeWorld(world));+// { host: 'example.com', sections: 2, doors: 1, tallest: { name: 'Example Domain', … } }+```++Put a live, walkable world on your own page:++```js+import { mountPortal } from '@three-ws/portal';++mountPortal(document.querySelector('#stage'), { url: 'example.com', height: 560 });+```++Or without any JavaScript at all:++```html+<iframe+ src="https://three.ws/portal?url=example.com&embed=1"+ width="100%" height="520" style="border:0;border-radius:14px"+ loading="lazy" title="Walk example.com in 3D"></iframe>+```++No key, no account, no wallet. `fetchWorld` reads the public three.ws Portal API,+which fetches the page once and caches the result for an hour.++## How a page becomes a place++The mapping is fixed, documented, and testable, which is what makes a world+predictable enough to share:++| On the page | In the world |+| --- | --- |+| The page itself | A plaza with an obelisk carrying the title |+| Each `h1`/`h2`/`h3` section | A district with one building |+| How many words a section has | The building's height, on a log scale |+| How many blocks it holds | The building's footprint |+| Each link | A door on the building's wall. Same-site doors rebuild the world where they point; outside links open the page |+| Each image | A billboard beside the building, showing the real image |+| Each code block | A monolith: a tall, dark, emissive slab |+| `theme-color`, or the host name | The palette, so a site looks like itself |++Layout is a pure function with a seeded PRNG. Call it yourself on any outline:++```js+import { buildWorld, collidersFor } from '@three-ws/portal/layout';++const world = buildWorld(outline); // no network, no DOM, no three.js+const solids = collidersFor(world); // circles, for your own player controller+```++## API++| Export | What it does |+| --- | --- |+| `fetchWorld(url, opts?)` | Build (or read from cache) `{ world, outline, cached, stale }` |+| `fetchOutline(url, opts?)` | The structural read only: headings, weights, links, images |+| `fetchWorldGlb(url, opts?)` | The world as a glTF binary (`ArrayBuffer`) |+| `mountPortal(el, { url, height? })` | Mount a live walkable world into an element |+| `embedSnippet(url, opts?)` | The same thing as an HTML string |+| `describeWorld(world)` | A compact summary: districts, doors, tallest section |+| `buildWorld(outline, opts?)` | The pure layout function |+| `collidersFor(world)` | Collision circles for the solids in a world |+| `paletteFor(outline)` | The deterministic palette for a site |+| `PortalError` | Every failure, carrying the API's own `code` |++`opts` accepts `endpoint` (default `https://three.ws/api/portal`), `fetch` (bring+your own), and `signal`.++Errors are typed rather than thrown as strings:++```js+import { fetchWorld, PortalError } from '@three-ws/portal';++try {+ await fetchWorld('example.com/private');+} catch (err) {+ if (err instanceof PortalError && err.code === 'robots_disallowed') {+ console.log('That site asks crawlers to stay out, so Portal does.');+ }+}+```++Codes you can branch on: `invalid_url`, `robots_disallowed`, `blocked_host`,+`not_html`, `no_structure`, `too_large`, `unreachable`, `upstream_status`,+`rate_limited`.++## CLI++```bash+npx @three-ws/portal three.ws # the world, summarized+npx @three-ws/portal three.ws --glb site.glb # save it as a 3D file+npx @three-ws/portal three.ws --json world.json # save the world document+npx @three-ws/portal three.ws --open # print the walkable link+```++```+ three.ws+ 24 districts · 1563 words · 42 doors (38 internal) · 2 billboards · 0 code monoliths++ ███████████··········· 109w Your 3D agent. In your room.+ █████████············· 66w Your agents don't just talk. They trade.+ █████················· 20w One tag. Any site.+```++## MCP++An agent that fetches a page gets a wall of text. Over MCP it can ask for the+page's *shape* instead.++```bash+claude mcp add portal -- npx -y @three-ws/portal portal-mcp+```++| Tool | Returns |+| --- | --- |+| `walk_site` | The world: districts, doors (with targets), billboards, plus a walkable link and a GLB URL |+| `site_shape` | The heading spine with the weight of each section. The cheap read |++Both accept any public URL and honour the same manners as the API.++## Manners++Portal is a crawler that runs on a person's request, and behaves like one:++- **It identifies itself** as `ThreeWSPortalBot/1.0 (+https://three.ws/portal)`.+- **It reads robots.txt first** and honours a `Disallow` for that token with a+ clean `robots_disallowed` error. Rules are matched per RFC 9309: most specific+ user-agent group, longest matching rule, `Allow` wins a tie.+- **It reads a page once.** Worlds are cached for an hour fleet-wide, so a link+ shared with a thousand people is one request to the origin.+- **It is bounded**: 3 MB of HTML, a 12 second deadline, and an SSRF guard that+ re-resolves the host, refuses private address ranges, and pins the socket to+ the address it validated.++## License++Apache-2.0. Built by [three.ws](https://three.ws).diff --git a/specs/GLANCE_CARD.md b/specs/GLANCE_CARD.mdnew file mode 100644index 000000000..2db3de9e6--- /dev/null+++ b/specs/GLANCE_CARD.md@@ -0,0 +1,109 @@+# Glance Card v1++The wire format behind [`/api/glance/card`](../docs/glance.md). One three.ws agent, reduced to what fits in an operating system widget slot, a README badge, or a chat unfurl.++- **Endpoint:** `GET https://three.ws/api/glance/card?agent=<uuid>`+- **Media types:** `application/json` (default), `image/svg+xml` (`format=svg`), Adaptive Card 1.6 JSON (`format=adaptive`)+- **Companion specs:** [3D_AGENT_CARD.md](3D_AGENT_CARD.md) (the on-chain identity document), [EMBED_SPEC.md](EMBED_SPEC.md) (the 3D embed)++## Why it exists++Every widget host the platform targets (the Windows 11 widgets board, Android app widgets, WidgetKit on Apple platforms) shares two constraints: none of them can execute WebGL, and each one wants a different container format. Without a pinned card, each surface would grow its own query against the agent tables and they would drift apart within a release.++v1 pins one model, computed once on the server, that every surface renders. Adding a surface is a rendering job, not a data job.++## Document++```json+{+ "version": 1,+ "id": "0f3a1c22-9b7e-4d51-8a10-2c6f5d90ab34",+ "name": "Atlas Scout",+ "description": "Watches the launch feed and reports what matters.",+ "url": "https://three.ws/agents/0f3a1c22-9b7e-4d51-8a10-2c6f5d90ab34",+ "createUrl": "https://three.ws/create",+ "image": "https://cdn.three.ws/u/…/thumb.png",+ "monogram": "AS",+ "accent": { "from": "hsl(235 82% 58%)", "to": "hsl(283 84% 46%)", "hue": 235 },+ "status": "active",+ "headline": "Working.",+ "metric": { "label": "Moves today", "value": 17 },+ "stats": [+ { "label": "This week", "value": 96 },+ { "label": "All time", "value": 412 },+ { "label": "Skills", "value": 4 }+ ],+ "lastAction": { "type": "skill.invoke", "at": "2026-08-28T11:00:00.000Z", "relative": "1h ago" },+ "bornAt": "2026-08-01T00:00:00.000Z",+ "ageDays": 27,+ "updatedAt": "2026-08-28T12:00:00.000Z",+ "ttl": 120+}+```++| Field | Type | Required | Notes |+| --- | --- | --- | --- |+| `version` | integer | yes | `1`. A consumer MUST ignore a document whose version it does not know. |+| `id` | uuid | yes | The platform agent id. |+| `name` | string | yes | At most 64 characters, already truncated server-side. |+| `description` | string \| null | yes | At most 160 characters. `null` when the agent has none. |+| `url` | url | yes | The agent's page. Where a tap on the card goes. |+| `createUrl` | url | yes | Where a card with nothing to show sends the viewer. |+| `image` | url \| null | yes | The avatar thumbnail. `null` unless the avatar's visibility is `public` or `unlisted`. |+| `monogram` | string | yes | One or two characters. What a renderer draws when `image` is `null`. |+| `accent` | object | yes | `{ from, to, hue }`, derived from `id`. Stable across requests. |+| `status` | enum | yes | `active` \| `idle` \| `new`. |+| `headline` | string | yes | One line, written for the status. |+| `metric` | object | yes | `{ label, value }`. The one number the card exists to show. |+| `stats` | array | yes | Exactly three `{ label, value }` entries. |+| `lastAction` | object \| null | yes | `{ type, at, relative }`, or `null` when the agent has never acted. |+| `bornAt` | ISO 8601 \| null | yes | When the agent was created. |+| `ageDays` | integer \| null | yes | Whole days since `bornAt`. |+| `updatedAt` | ISO 8601 | yes | When this document was computed. |+| `ttl` | integer | yes | Seconds the server considers this document fresh. |++`cache` (`"hit"` or `"miss"`) may also be present. It is a server diagnostic; consumers MUST NOT depend on it.++## Status++| Value | Meaning |+| --- | --- |+| `active` | The agent's last action is under 24 hours old. |+| `idle` | The agent has acted, but not in the last 24 hours. |+| `new` | The agent has never acted. |++A renderer SHOULD signal status visually (the reference renderers use a green, amber, or grey dot) and MUST render `headline` rather than inventing its own empty-state copy: a `new` agent's card is an invitation, not a zero.++## Conformance++A renderer conforms to Glance Card v1 if:++1. It renders `name`, `metric.value` and `metric.label` for every card.+2. It falls back to `monogram` over `accent` whenever `image` is `null`, and never renders a broken image element.+3. Activating the card opens `url`.+4. It refreshes no more often than `ttl` seconds.+5. It treats every string field as untrusted text: agent names and descriptions are user-supplied and MUST be escaped for the output format. The reference SVG renderer also strips XML control characters, which are the byte class that makes a document unparseable for one bad byte.++A producer conforms if it serves the fields above with an `ETag` and honours `if-none-match`.++## Sizes++The SVG rendering serves three sizes, chosen to match the slots the widget boards hand out:++| Name | Pixels | Slot |+| --- | --- | --- |+| `small` | 240x240 | Android 2x2, iOS small, Windows small |+| `medium` | 480x200 | Android 4x2, Windows medium, README badge |+| `large` | 480x300 | Windows large, a dashboard tile |++## Versioning++New optional fields are additive and do not bump `version`. Removing a field, changing a type, or changing the meaning of `metric` requires v2 served alongside v1; the `version` field is what lets a widget pinned a year ago keep rendering.++## Reference implementation++- Model: [api/_lib/glance-card.js](../api/_lib/glance-card.js)+- SVG: [api/_lib/glance-svg.js](../api/_lib/glance-svg.js)+- Adaptive Card: [api/_lib/glance-adaptive.js](../api/_lib/glance-adaptive.js)+- Endpoint: [api/glance/card.js](../api/glance/card.js)+- Conformance tests: [tests/glance-card.test.js](../tests/glance-card.test.js)