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): specify the card format a third-party host has to render

nirholas3810bc131c2e
diff --git a/packages/portal/README.md b/packages/portal/README.md
new file mode 100644
index 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.md
new file mode 100644
index 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)