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(portal): write the feature doc, the world spec, and the entry holders read
nirholasbdc8abfed7ee
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 825a2b42a..629fdfb29 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr## 2026-08-28- **Brownout** (`/brownout`): Every response from this API says where its data came from and how fresh it is, and every declared fallback has been proven by breaking the upstream it protects against, inside the real request path. Read the receipts: which provider refused, which one caught the request, and how old the answer was.+- **Brownout: proven fallbacks, not promised ones** (`/docs/brownout`): Every response says where its data came from and how fresh it is, and every fallback the API claims has been executed for real against a genuinely refusing provider, inside the request path a user hits.- **Companion** (`/companion`): A 3D companion that delivers your important messages in person. Connect your own Telegram bot, calendar, inbox, or phone, give each contact their own avatar and voice, and hear only what clears your bar.- **create-agent: one command, one 3D character** (`/docs/create-agent`): npm create @three-ws/agent turns a sentence into a rigged, downloadable 3D character with a working demo page. No account, no API key.- **Docs · 3D Vision: let an agent see the model** (`/docs/3d-vision`): Every text-to-3D API answers with a link to a binary an AI agent cannot open, so the agent that made the model cannot check its own work. This surface renders any GLB from several angles and hands the frames back as images a vision model actually sees, over MCP, REST or the @three-ws/see SDK.@@ -29,6 +30,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Model Diff** (`/diff`): Drop two .glb files and see exactly what changed: geometry, materials, textures, skeletons and animation clips, with git-style rename and move detection and a severity you can gate a build on. Overlay, wipe, or set the two models side by side in 3D. Runs in your browser, nothing is uploaded.- **Oracle Lab: the model, published** (`/oracle-lab`): The Oracle's conviction model in full: every bucket weight with the number of labeled launches behind it and what happened to them, the held-out reliability curve for each tier, the version history of every refit including the ones that were refused, and a live scorer that runs the real weights in your browser. Download it and reproduce any score offline.- **Portal** (`/portal`): Paste any web address and walk through it in 3D. Portal reads the page's real structure and builds a place from it: sections become buildings sized by what they say, links become doors you step into, images become billboards. Download the world as a GLB or embed it in your own site.+- **Portal: walk any website in 3D** (`/docs/portal`): Paste a web address and Portal builds a place out of it: sections become buildings sized by what they say, links become doors you step through, images become billboards. The API, the world spec, the npm package, the CLI and the MCP server behind /portal.- **Progressive Avatars** (`/stream`): A3S packs a GLB into nested layers whose first 50 KB is already a complete, skinned, spec-valid avatar, then refines it in place over plain HTTP range requests. Live side-by-side against a classic GLB load.- **Publishing to the Solana dApp Store** (`/docs/seeker-publishing`): The release runbook for the three.ws Seeker app: Publisher Portal setup, the release keystore, building and verifying a signed APK, and submitting it for review.- **Ship log** (`/ship`): Every release note joined to the commits that produced it, with a confidence score and the reasoning behind every link.@@ -48,6 +50,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Next on the roadmap: your agent on your home screen**: A fifth phase has been added to the public roadmap: native widgets. Right now three.ws is something you open. The plan is for the agent you own to sit on your home screen and your desktop, showing itself and one live number about it, refreshed by the system without you opening anything, with a tap that drops you back into the right screen. Android is first, because the Android app is already built and signed: three.ws ships as a real app for Solana Seeker, and as of today Google confirms the app's release key against the site, so a three.ws link opens inside the app instead of a browser tab. Windows 11 follows through the installed web app, which needs no separate store submission, then macOS and iOS through a shared widget extension. None of it is shipped yet. It is written down, scoped and public so you can hold us to it, and the phase is on the roadmap in the repo along with the work order behind it. `[docs]`- **One command turns a sentence into a rigged 3D character you can put on your site**: Type `npm create @three-ws/agent "a friendly cartoon astronaut"` in a terminal and about a minute later you have a folder: the 3D model with a real skeleton so it can be posed and animated, a demo page that works when you double click it, and the two lines of HTML that put the character on your own website. No account, no API key, no signup, and nothing to install first. It also works from a photo, and it can make plain objects instead of characters. The same free lane the website uses is behind it, so what you get in the terminal is what you get on three.ws. (`/docs/create-agent`) `[feature, sdk]`- **Photo uploads, avatar saves, launches and team tasks fail fast instead of hanging**: A handful of steps still had no time limit on the outside service they called. When that service accepted the connection and then went quiet, the request sat there until the platform killed it, and you got a spinner that ended in nothing: a photo-to-avatar upload that never came back, a saved model that never finished downloading, a coin launch stuck fetching its own thumbnail, an ordinals order whose status never loaded, a team task where one hired agent held up the whole run. Each of those now has a deadline and a clear answer when it is missed, and the ones that are safe to repeat retry once first. Anything that spends money or starts a generation is never repeated: it is bounded and then reported, so no upload is billed twice and no hire is paid twice. Saving a model from a link is also checked more tightly now, against the address it actually connects to and with the size limit applied while it downloads. `[improvement, fix, infra]`+- **Portal: paste any web address and walk it in 3D**: Type a website into /portal and it becomes a place you can walk. Every section of the page turns into a building whose height is how much that section actually says, every link becomes a door you step through (a door to the same site rebuilds the world there, so Back walks you through the sites you visited), every image becomes a billboard showing the real image, and every code block becomes a dark monolith. The colours come from the site's own theme colour, so a site looks like itself. You explore it with your own avatar, and the same world downloads as a 3D file you can open in Blender or view in AR, embeds in your own page with one line, and is readable by an AI agent through a new MCP server. Two things worth knowing: the same address always builds exactly the same city, so a link you share opens the world you walked, and Portal behaves like a polite crawler, reading each page once, saying who it is, and obeying robots.txt. (`/portal`) `[feature, sdk]`- **Report a bug and it arrives as a test that fails until it is fixed**: When you tell the agent in the corner that something is broken, it now sends what you actually did: the steps you took, the page, and the error the browser saw. Those steps compile into a real test that fails while the bug is there and passes once it is gone, so the slowest part of fixing anything (working out how to make it happen again) is done before anyone starts. You can see every step that gets attached before you send, and nothing you typed into a field is ever recorded, only how much. The recorder is open source and works on any site: install @three-ws/witness. (`/docs/witness`) `[feature, sdk, improvement]`- **Tell the agent in the corner what is broken**: The companion that walks your pages now listens. When a page actually fails, it turns and asks what you were doing, and the report it sends carries what you should never have to type: the page, the exact build it happened on, your screen size, and the errors the browser recorded at that moment. You can also open it any time from the control beside the avatar, and dictate instead of typing. Reports are grouped so that twenty people hitting one problem read as one problem, and every one of them is read by a person before anything changes. (`/docs/feedback`) `[feature, improvement]`- **The iOS app now exists in the repo, and the web half of it ships today**: three.ws is being packaged for the App Store as a native iOS app. The container and its Xcode project are in the repo, and the part that runs inside the website went live with this deploy: on iPhone the app will get a working share sheet, links that open the app instead of Safari, wallet sign-ins that return to the exact page you left, and a real offline screen. Nothing changes on the web. What is still outstanding is an Apple Developer organization account, app icons, and push notifications. (`/docs/ios-app`) `[feature, infra]`diff --git a/STRUCTURE.md b/STRUCTURE.mdindex 07cfd16f9..7b87fdc5c 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -90,6 +90,7 @@ bottom.| AR Forge (prompt → model → your room) | [public/ar-forge.html](public/ar-forge.html) `→ /ar` (self-contained page, CDN model-viewer + local meshopt decoder, no Vite registration needed; vercel route sets `xr-spatial-tracking` permissions-policy) | Live | Mobile-first app: one prompt hits the free NVIDIA lane (`POST /api/forge {backend:"nvidia"}`, poll `?job=`), the result renders in an AR-capable `<model-viewer>` with "View in your space" (WebXR / Scene Viewer / Quick Look). Non-AR devices get a QR handoff to `GET /api/ar?src=` (server-side UA routing) plus a copyable `/viewer?src=` share link. Deep link `/ar?src=<glb>&title=` reopens any shared model; recent forges persist in localStorage. Designed idle/working/failed/result states; https-only GLB guard. || Daily Forge (daily challenge + creator streak) | [pages/daily.html](pages/daily.html) `→ /daily` + [src/daily.js](src/daily.js), deterministic theme rotation [src/daily/daily-theme.js](src/daily/daily-theme.js), streak state machine [src/daily/creator-streak.js](src/daily/creator-streak.js) | Live | The **anonymous-first retention loop** the platform lacked: the logged-in streak system ([api/_lib/streaks.js](api/_lib/streaks.js)) needs an account, so the no-sign-up forge majority had no reason to return. Every UTC day resolves to one curated creative theme (the same for everyone, hashed from the date — no backend, no randomness) with a running "Day N" counter; forging today's theme on the free lane lights a localStorage streak (consecutive-day state machine: extend / reset-on-gap / never-double-count, `best` preserved, at-risk vs lapsed display), and milestones (3/7/14/30/50/100/365) fire a celebration. The generation lands in the shared recents so it's one tap from `/ar` and `/ar/studio`; a "Fresh from the community" strip reads `/api/forge-gallery?scope=community`. `changefreq: daily` in the sitemap. Tests: [tests/daily-theme.test.js](tests/daily-theme.test.js), [tests/creator-streak.test.js](tests/creator-streak.test.js). || AR Studio (multi-model live camera scene) | [pages/ar-studio.html](pages/ar-studio.html) `→ /ar/studio` + [src/ar-studio.js](src/ar-studio.js), multi-anchor WebXR session [src/ar/multi-place.js](src/ar/multi-place.js), pure scene math [src/ar/studio-scene.js](src/ar/studio-scene.js) | Live | The standalone multi-model AR surface: place ANY number of models/avatars into one live camera view (every earlier AR lane was single-model). Model sources: in-view forge (`POST /api/forge {backend:"nvidia"}` runs behind the live camera, result drops into the room), the forge gallery (`/api/forge-gallery`, yours + community tabs), recent forges (localStorage, shared with `/ar`), the CC0 Object Library (`/api/objects/library`, an Objects tray tab with client-side name/category search), a pasted GLB link, or repeatable `?src=` deep links (https/relative only). Rendering ladder: WebXR immersive-ar with one XRAnchor per placed model + always-armed reticle (Android), getUserMedia passthrough + gyro world-lock (iOS/everywhere), grid preview + drag-look + QR handoff (desktop). Gestures: tap select, drag move, pinch resize, two-finger twist rotate; per-model duplicate/rotate/remove, clear-with-undo. **Real device AR, not just the camera composite:** the AR control resolves what the device can actually do and routes there rather than defaulting every non-WebXR device to the composite: the immersive WebXR session where it exists, Apple Quick Look on iOS and Google Scene Viewer on Android otherwise (both selectable per-model from the selection bar too), and an honest "open this on a phone" QR prompt everywhere else. The button relabels itself to match ("Immersive" only where an immersive session is real). Quick Look reads USDZ, so the selected model's GLB is converted on the device through the same `usdz-pipeline.js` bake `/avatars/:id/ar` uses, not the camera-passthrough composite, which has no real-world plane detection or scale and previously shipped as the only iOS experience. Humanoids with no baked clips idle via the universal retarget ([src/irl/pin-idle.js](src/irl/pin-idle.js)); scene persists in localStorage and the whole ARRANGEMENT (models + transforms) round-trips through a base64url `#s=` hash on the share/QR URL, so a composed scene reopens exactly on any device. **Presence realism:** WebXR placements are lit by the real room via lighting-estimation ([src/ar/estimated-lighting.js](src/ar/estimated-lighting.js), three's `XREstimatedLight`, real primary-light direction/colour + a live environment cube map so metal/glass reflect the actual room, reverting to baked lights when the device isn't estimating) and occluded by real geometry via depth-sensing ([src/ar/depth-occlusion.js](src/ar/depth-occlusion.js)); the passthrough path matches room brightness AND colour by sampling the camera feed. Desktop keyboard controls (arrows nudge / R rotate / D duplicate / Delete). Photo capture composites camera + WebGL ([src/irl/share-frame.js](src/irl/share-frame.js)). Reachable from `/ar`, the forge AR panel, and the `/viewer` action sheet. **Shared rooms (build together, live):** "Share live" opens a room with a 6-char code; anyone who opens `/ar/studio?room=CODE` joins the same scene and every add / move / scale / rotate / remove delta-syncs in real time, with a live "N here" presence pill. New Colyseus room [multiplayer/src/rooms/StudioRoom.js](multiplayer/src/rooms/StudioRoom.js) + schema [multiplayer/src/studio-schemas.js](multiplayer/src/studio-schemas.js) (owner-gated edits, per-room/per-owner caps, per-client rate limit, https-only src validation, the same discipline as WalkRoom's object channel), client wrapper [src/ar/studio-net.js](src/ar/studio-net.js), and a shared logical coordinate frame [src/ar/studio-coords.js](src/ar/studio-coords.js) (relEast/relNorth/yawDeg) so every device agrees on placement; QR-marker colocalization ([src/irl/marker-anchor.js](src/irl/marker-anchor.js)) is the co-located "same physical table" upgrade. Runs on the same Colyseus host as /walk and /irl (a new room, not a new process). Tests: [tests/ar-studio-scene.test.js](tests/ar-studio-scene.test.js), [tests/ar-studio-coords.test.js](tests/ar-studio-coords.test.js), [tests/ar-estimated-lighting.test.js](tests/ar-estimated-lighting.test.js), [tests/studio-room.test.js](tests/studio-room.test.js). **Shipped as open source:** the same surface is extracted, generalized and published as [3d-ar-studio](https://www.npmjs.com/package/3d-ar-studio) (repo [nirholas/3D-AR-Studio](https://github.com/nirholas/3D-AR-Studio), demo https://nirholas.github.io/3D-AR-Studio/, MCP server `io.github.nirholas/3d-ar-studio`), so any site can embed a multi-model AR studio with one script tag. It defaults to OUR catalogue and generation lane (`/cdn/objects/library/manifest.json`, `/api/mcp-studio`, `/animations/manifest.json`, `/hdri/*`, `/api/ar`), which is why those surfaces answer open CORS. |+| Portal (any website as a walkable world) | Page [pages/portal.html](pages/portal.html) `→ /portal` + controller [src/portal/main.js](src/portal/main.js), renderer [src/portal/render.js](src/portal/render.js), styles [src/portal/portal.css](src/portal/portal.css); reader [api/_lib/portal/outline.js](api/_lib/portal/outline.js) + guarded fetch [api/_lib/portal/fetch-site.js](api/_lib/portal/fetch-site.js) + robots matcher [api/_lib/portal/robots.js](api/_lib/portal/robots.js); pure layout [packages/portal/src/layout.js](packages/portal/src/layout.js); GLB export [api/_lib/portal/world-glb.js](api/_lib/portal/world-glb.js); endpoint [api/portal.js](api/portal.js) `→ /api/portal` | Live | Paste an address and walk the page: each section becomes a building sized by its word count (log scale), each link a door (same-site doors rebuild the world there and push browser history, outside links open the page), each image a billboard loaded through `/api/img`, each code block a monolith, and the palette comes from the page's own `theme-color` or a hash of its host. The layout is a pure, seeded function so the browser, the GLB exporter, the MCP tools and the npm package all build the identical city from one link. Crawler manners are part of the product: a declared user agent, `robots.txt` honoured per RFC 9309, one fetch per page cached fleet-wide for an hour, and an IP-pinned SSRF guard with size and time ceilings. `format=glb` returns the world as glTF with named nodes. SDK + CLI + MCP server: [packages/portal/](packages/portal). Docs: [docs/portal.md](docs/portal.md). Spec: [specs/PORTAL_WORLD.md](specs/PORTAL_WORLD.md). Tests: [tests/portal-robots.test.js](tests/portal-robots.test.js), [tests/portal-outline.test.js](tests/portal-outline.test.js), [tests/portal-layout.test.js](tests/portal-layout.test.js), [tests/portal-endpoint.test.js](tests/portal-endpoint.test.js), [tests/e2e/portal.spec.js](tests/e2e/portal.spec.js) || IRL (agents in the real world) | [pages/irl.html](pages/irl.html) `→ /irl` + [src/irl.js](src/irl.js), WebXR placement [src/ar/webxr.js](src/ar/webxr.js) + pinch [src/ar/pinch-scale.js](src/ar/pinch-scale.js), animated Quick Look bake [src/usdz-animated.js](src/usdz-animated.js) (static fallback [src/usdz-pipeline.js](src/usdz-pipeline.js)), backend [api/irl/](api/irl) | Live | Pin an agent at a real GPS spot; discovery is presence-proof-gated ([docs/irl/THREAT-MODEL.md](docs/irl/THREAT-MODEL.md)). **Place in AR** leads the dock on AR-capable devices: WebXR hit-test anchoring on Android with two-finger pinch resize (25%..400%) persisted to the pin (`anchor_scale`; the pinch lands as a follow-up `PATCH /api/irl/pins {id, scale}` after the placement tap), and ARKit Quick Look on iOS with the idle clip baked into the USDZ so the agent moves instead of standing in a T-pose. Discovered pins are equally alive in the in-page camera view: every mounted humanoid GLB plays the retargeted idle clip via a per-pin mixer ([src/irl/pin-idle.js](src/irl/pin-idle.js), phase-randomized, LOD-bounded), camera-aware gaze composes on top of the running animation, and the scene renders with ACES tone mapping + IBL + soft shadows (e2e: [tests/e2e/irl-pin-idle.spec.js](tests/e2e/irl-pin-idle.spec.js)). Inbound `/irl?avatar=<glb>` is the living-agent handoff from `GET /api/ar?…&kind=avatar` (explicit `?avatar=` wins over a saved session). Money Drops and World Lines: [docs/irl.md](docs/irl.md). SDK: [packages/irl/](packages/irl). **Share** ([src/irl/share-frame.js](src/irl/share-frame.js), [api/irl/share.js](api/irl/share.js), [api/irl/share/[token].js](api/irl/share/%5Btoken%5D.js)) mints a permanent, unfurlable `/irl/s/:token` link from the captured AR photo for the pin you just placed - never a coordinate, owner-gated, falls back to the plain native share sheet with no active pin. **Analytics** ([api/_lib/irl-analytics.js](api/_lib/irl-analytics.js), [api/irl/analytics.js](api/irl/analytics.js)) is the first site-wide usage rollup for the feature - pins placed, nearby reads, placement method, shares, drop claims - aged out by the existing hourly reaper. || Verifiable 3D provenance (content credentials) | Spec [specs/PROVENANCE_3D.md](specs/PROVENANCE_3D.md), pure core [api/_lib/provenance-3d.js](api/_lib/provenance-3d.js), Solana anchor [api/_lib/provenance-anchor.js](api/_lib/provenance-anchor.js), MCP tools [api/_mcp3d/tools/provenance.js](api/_mcp3d/tools/provenance.js) (`verify_provenance` free, `anchor_provenance` paid $0.05), free REST verify [api/provenance.js](api/provenance.js) `→ /api/provenance`, viewer badge [public/viewer.html](public/viewer.html), docs [docs/provenance.md](docs/provenance.md). | Live (verify) · anchor gated on issuer key + devnet funds | C2PA-style signed content credentials for AI 3D: creator, prompt, model/provider, lineage, timestamp, and the GLB's sha256, ed25519-signed by the three.ws issuer with the credential hash anchored on Solana. Free public `verify_provenance` / `GET /api/provenance?src=…` recompute the hash and return `verified | tampered | unknown` (a single changed byte → tampered); the verify path and response are coin-clean (both stores). `anchor_provenance` signs + writes the SPL Memo anchor + stores the credential in R2. Tests: [tests/provenance-3d.test.js](tests/provenance-3d.test.js). Evidence: [prompts/store-submissions/_generated/provenance/](prompts/store-submissions/_generated/provenance/). Store-submission prompt 19. || OpenAI Select Partner (partner surface + announcement pack) | [pages/openai/index.html](pages/openai/index.html) `→ /openai`, badge assets [public/partners/openai/](public/partners/openai), announcement [blog/three-ws-openai-select-partner.html](blog/three-ws-openai-select-partner.html) `→ /blog/three-ws-openai-select-partner`, directory card in [pages/partners.html](pages/partners.html) `→ /partners`, press/social pack [marketing/openai-select-partner/](marketing/openai-select-partner/README.md), original OpenAI-supplied badge files + press-release template [OAI Select Tier Assets/](OAI%20Select%20Tier%20Assets/README.md) | Live | three.ws's OpenAI Partner Network Select-tier surface. `/openai` is the partner landing: the supplied badge (used unmodified, on a white plate), the four live OpenAI surfaces (the free keyless [3D Studio MCP connector](docs/mcp-studio.md) `→ /api/mcp-studio`, the custom-GPT Actions twin `→ /api/3d/studio`, [Spatial MCP](specs/SPATIAL_MCP.md), and [AR in ChatGPT](docs/chatgpt-ar.md)), the connect table, and the nine-tool list. The marketing pack holds badge-usage rules and the press-release draft, which is gated on OpenAI's written approval before publishing (see its README). |@@ -401,6 +402,7 @@ npm).| `@three-ws/mocap` | [packages/mocap/](packages/mocap) | `api/mocap/` | Motion-capture clips → avatar animation || `@three-ws/strategies` | [packages/strategies/](packages/strategies) | `api/strategies.js`, `dca-strategies.js`, copy/mirror engines | Automated trading strategies (DCA, copy, mirror) || `@three-ws/pumpfun-skills` | [packages/pumpfun-skills/](packages/pumpfun-skills) | [pump-fun-skills/](pump-fun-skills) | pump.fun create-coin / swap / fees skills (runtime mint) |+| `@three-ws/portal` | [packages/portal/](packages/portal) | `api/portal` | Any website as a walkable 3D world: pure layout, API client, CLI, MCP server || `@three-ws/irl` | [packages/irl/](packages/irl) | `api/irl/`, `_lib/geohash.js` | Geofenced real-world presence + nearby discovery || `@three-ws/sign-language` | [packages/sign-language/](packages/sign-language) | `/sign-language`, `/asl-alphabet`, signed chat replies | The ASL engine as a published bundle: text → one signed clip, zero runtime dependencies || `@three-ws/pose` | [packages/pose/](packages/pose) | `get_pose_seed`, `api/mcp-3d.js` | Pose-seed generation for rigged avatars |diff --git a/data/changelog.json b/data/changelog.jsonindex 943b60bda..ea5956ce1 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,16 @@{"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-08-28",+ "title": "Portal: paste any web address and walk it in 3D",+ "summary": "Type a website into /portal and it becomes a place you can walk. Every section of the page turns into a building whose height is how much that section actually says, every link becomes a door you step through (a door to the same site rebuilds the world there, so Back walks you through the sites you visited), every image becomes a billboard showing the real image, and every code block becomes a dark monolith. The colours come from the site's own theme colour, so a site looks like itself. You explore it with your own avatar, and the same world downloads as a 3D file you can open in Blender or view in AR, embeds in your own page with one line, and is readable by an AI agent through a new MCP server. Two things worth knowing: the same address always builds exactly the same city, so a link you share opens the world you walked, and Portal behaves like a polite crawler, reading each page once, saying who it is, and obeying robots.txt.",+ "tags": [+ "feature",+ "sdk"+ ],+ "link": "/portal"+ },{"date": "2026-08-28","title": "One command turns a sentence into a rigged 3D character you can put on your site",diff --git a/data/pages.json b/data/pages.jsonindex 39cb04075..9615a2fe9 100644--- a/data/pages.json+++ b/data/pages.json@@ -754,6 +754,22 @@"changefreq": "monthly","added": "2026-08-28"},+ {+ "path": "/docs/brownout",+ "title": "Brownout: proven fallbacks, not promised ones",+ "description": "Every response says where its data came from and how fresh it is, and every fallback the API claims has been executed for real against a genuinely refusing provider, inside the request path a user hits.",+ "priority": 0.6,+ "changefreq": "monthly",+ "added": "2026-08-28"+ },+ {+ "path": "/docs/portal",+ "title": "Portal: walk any website in 3D",+ "description": "Paste a web address and Portal builds a place out of it: sections become buildings sized by what they say, links become doors you step through, images become billboards. The API, the world spec, the npm package, the CLI and the MCP server behind /portal.",+ "priority": 0.6,+ "changefreq": "monthly",+ "added": "2026-08-28"+ },{"path": "/docs/glance","title": "Glance: agent cards for home screens",diff --git a/docs/portal.md b/docs/portal.mdnew file mode 100644index 000000000..58b882457--- /dev/null+++ b/docs/portal.md@@ -0,0 +1,122 @@+# Portal: walk any website in 3D++Paste a web address and Portal builds a place out of it. Every section of the page becomes a building sized by what it says, every link becomes a door you step through, every image becomes a billboard, every code block becomes a monolith. You walk it with your own avatar, hand the link to anyone, download the world as a `.glb`, embed it in your own site, or let an agent read the shape of a site over MCP.++Page: [/portal](https://three.ws/portal) · API: `/api/portal` · Package: [`@three-ws/portal`](../packages/portal/README.md) · Spec: [`specs/PORTAL_WORLD.md`](../specs/PORTAL_WORLD.md)++## Why it exists++Every tool that visualizes a website draws a node graph. A graph tells you a site has forty 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.++There is a second reason, and it is the one that matters to this platform: an agent that fetches a page gets a wall of text. Over Portal it gets the page's *shape*, which is small enough to reason about and spatial enough to hand back as somewhere a human can go. That is three.ws's whole thesis applied to the web that already exists.++## Walkthrough++1. Open [/portal](https://three.ws/portal) and type an address (`three.ws`, `en.wikipedia.org/wiki/Three.js`, your own site).+2. The build panel names each real step: asking the site and its `robots.txt`, reading the structure, laying out districts, rendering.+3. You arrive on the plaza, in front of an obelisk carrying the page title. Walk with `WASD` or the arrows, hold `Shift` to run, drag to look, and on a phone use the on-screen stick.+4. Buildings are labelled with their section headings. The taller one said more. The minimap shows the whole city with you in it.+5. Stand at a door and press `Enter`. A same-site door rebuilds the world at that address and pushes it into your browser history, so `Back` walks back through the sites you visited. An outside link opens the page it points at.+6. **Copy link** shares the exact world you are standing in. **Embed** copies an iframe snippet. **Download GLB** hands you the whole city as a glTF binary you can open in Blender, drop into Unity, or view in AR.++## How it works++Portal is two documents and one pure function.++**Reading the page** ([`api/_lib/portal/fetch-site.js`](../api/_lib/portal/fetch-site.js), [`outline.js`](../api/_lib/portal/outline.js)). The address is normalized, `robots.txt` is fetched and matched against our token, and the page is read once through the IP-pinned SSRF guard with a 3 MB ceiling and a 12 second deadline. The HTML becomes a `SiteOutline`: the heading spine, the weight of each section (words, paragraphs, code blocks), its links and its images. Chrome (`nav`, `header`, `footer`, `script`) is removed before reading, so a navigation menu never becomes a district full of doors.++**Laying out the world** ([`packages/portal/src/layout.js`](../packages/portal/src/layout.js)). `buildWorld(outline)` is pure: no network, no DOM, no three.js, and no randomness that is not seeded from the page's canonical URL. Sections land on a phyllotaxis spiral so districts never collide, height comes from word count on a log scale so one long essay cannot dwarf a city, and the palette comes from the page's own `theme-color` (or a stable hue hashed from its host). Because it is pure and seeded, the person who opens your link builds the identical city.++**Rendering it** ([`src/portal/render.js`](../src/portal/render.js)). A three.js scene with a gradient sky, a plaza, labelled buildings that fade their signage by distance, doors that brighten as you approach, and your avatar driven by the platform's universal clip library, so the rig walks and idles correctly rather than sliding in the bind pose. Billboards load the page's real images through our own image proxy, because a foreign host with no CORS header would otherwise render a black panel.++**Exporting it** ([`api/_lib/portal/world-glb.js`](../api/_lib/portal/world-glb.js)). The same world document, composed into one glTF binary with `@gltf-transform`: named nodes, instanced geometry, deduplicated materials, two lights, and an `asset.copyright` recording the page the structure came from.++## API++```bash+# The world, and the outline it was built from+curl "https://three.ws/api/portal?url=example.com"++# Just one of them+curl "https://three.ws/api/portal?url=example.com&include=world"+curl "https://three.ws/api/portal?url=example.com&include=outline"++# The same world as a 3D file+curl -o example.glb "https://three.ws/api/portal?url=example.com&format=glb"+```++| Parameter | Values | Default |+| --- | --- | --- |+| `url` | any public http(s) address, with or without a scheme | required |+| `include` | `both`, `world`, `outline` | `both` |+| `format` | `json`, `glb` | `json` |++The response carries `ok`, `cached`, `stale`, `built_at`, `user_agent`, and whichever documents you asked for. CORS is open, because the SDK runs in other people's pages and every byte is already public on the site it read.++Failures arrive as `{ "error": "<code>", "error_description": "<a sentence you can act on>" }` with codes `invalid_url`, `robots_disallowed`, `blocked_host`, `not_html`, `no_structure`, `too_large`, `unreachable`, `upstream_status`, `rate_limited`.++## SDK++```bash+npm install @three-ws/portal+```++```js+import { fetchWorld, describeWorld, mountPortal } from '@three-ws/portal';++const { world } = await fetchWorld('example.com');+console.log(describeWorld(world).tallest); // the section that says the most++mountPortal(document.querySelector('#stage'), { url: 'example.com', height: 560 });+```++The layout is exported on its own for anyone who wants to build worlds from their own data:++```js+import { buildWorld, collidersFor } from '@three-ws/portal/layout';+```++Full reference: [`packages/portal/README.md`](../packages/portal/README.md).++## 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+```++## MCP++```bash+claude mcp add portal -- npx -y @three-ws/portal portal-mcp+```++| Tool | Returns |+| --- | --- |+| `walk_site` | The world: districts, doors with their targets, billboards, plus a walkable link and a GLB URL |+| `site_shape` | The heading spine with the weight of each section. The cheap structural read |++## Manners++Portal is a crawler that runs on a visitor's request, and behaves like one. It identifies itself as `ThreeWSPortalBot/1.0 (+https://three.ws/portal)`, reads `robots.txt` before the page and honours a `Disallow` for that token with a clean refusal, fetches each page once (worlds are cached fleet-wide for an hour, so a link shared with a thousand people is one request to the origin), and stays inside a 3 MB, 12 second, SSRF-guarded budget. Rate limits are per address and fleet-wide, and a cached world never touches them.++## Embedding++```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>+```++`embed=1` hides the chrome that only makes sense on our own page. The **Embed** button copies this snippet for the world you are standing in.++## Tests++- [`tests/portal-robots.test.js`](../tests/portal-robots.test.js): the RFC 9309 rules, including group specificity, longest-match and the `Allow` tie-break.+- [`tests/portal-outline.test.js`](../tests/portal-outline.test.js): section attribution, nested prose counted once, chrome dropped, determinism, and the caps that bound a hostile page.+- [`tests/portal-layout.test.js`](../tests/portal-layout.test.js): determinism, log scaling, non-overlap, doors on walls rather than inside them, and a spawn that is never inside a solid.+- [`tests/portal-endpoint.test.js`](../tests/portal-endpoint.test.js): the response contract, error mapping, both rate-limit buckets, the GLB export, and the CORS preflight.+- [`tests/e2e/portal.spec.js`](../tests/e2e/portal.spec.js): a real browser builds a world from a real address and walks it, asserting the avatar actually moved.diff --git a/docs/start-here.md b/docs/start-here.mdindex 136ed8c0f..d1a594e79 100644--- a/docs/start-here.md+++ b/docs/start-here.md@@ -145,6 +145,7 @@ Curious what happens between the prompt and the model? [How the Forge works](./h- **Something too important for a badge?** → [Herald](./herald.md): the open SDK behind /herald, where a 3D character walks onto the page and says it out loud, with an interrupt budget (importance floor, quiet hours, dedupe, batching), an accessible card for machines with no GPU, a rail so CI or an AI agent can reach the tab you have open, and a CLI that announces when your build finishes- **Want strangers to be able to reach you, but not for free?** → [Knock](./knock.md): a priced door at /knock/<username> that anyone, human or agent, can pay to get one message through; the USDC settles straight to your wallet, your companion delivers it in person, and every refusal happens before the payment- **About to pay for something?** → [Checkout companion](./checkout-companion.md): the browser extension that reads a payment page before you pay, why the arithmetic is never a model's job, and why it never reads a form field+- **Curious what a website looks like as a place?** → [Portal](./portal.md): paste any address and walk it in 3D; sections become buildings sized by what they say, links become doors you step through, and the world downloads as a GLB, embeds in your page, or reaches an agent over MCP- **Did that re-export break the rig?** → [Model Diff](./model-diff.md): what actually changed between two GLBs, why a rename is not a rewrite, and the severity that tells you a dropped joint from a recolour- **Something broken on a page?** → [Feedback](./feedback.md): telling the corner companion what went wrong, what the browser attaches for you, and the boundary that keeps untrusted text from ever reaching anything with write access- **Showing off your work?** → [The creator portfolio](./creator-portfolio.md): everything on your public /u/username page, what makes an item public, and how following works from itdiff --git a/public/changelog.json b/public/changelog.jsonindex e2e831e75..2922fde2e 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-28T06:32:04.505Z",+ "generated_at": "2026-08-28T06:34:45.458Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -16,6 +16,16 @@"launch"]},+ {+ "date": "2026-08-28",+ "type": "launch",+ "title": "Brownout: proven fallbacks, not promised ones",+ "summary": "Every response says where its data came from and how fresh it is, and every fallback the API claims has been executed for real against a genuinely refusing provider, inside the request path a user hits.",+ "link": "/docs/brownout",+ "tags": [+ "launch"+ ]+ },{"date": "2026-08-28","type": "launch",@@ -236,6 +246,16 @@"launch"]},+ {+ "date": "2026-08-28",+ "type": "launch",+ "title": "Portal: walk any website in 3D",+ "summary": "Paste a web address and Portal builds a place out of it: sections become buildings sized by what they say, links become doors you step through, images become billboards. The API, the world spec, the npm package, the CLI and the MCP server behind /portal.",+ "link": "/docs/portal",+ "tags": [+ "launch"+ ]+ },{"date": "2026-08-28","type": "launch",@@ -438,6 +458,17 @@"infra"]},+ {+ "date": "2026-08-28",+ "type": "update",+ "title": "Portal: paste any web address and walk it in 3D",+ "summary": "Type a website into /portal and it becomes a place you can walk. Every section of the page turns into a building whose height is how much that section actually says, every link becomes a door you step through (a door to the same site rebuilds the world there, so Back walks you through the sites you visited), every image becomes a billboard showing the real image, and every code block becomes a dark monolith. The colours come from the site's own theme colour, so a site looks like itself. You explore it with your own avatar, and the same world downloads as a 3D file you can open in Blender or view in AR, embeds in your own page with one line, and is readable by an AI agent through a new MCP server. Two things worth knowing: the same address always builds exactly the same city, so a link you share opens the world you walked, and Portal behaves like a polite crawler, reading each page once, saying who it is, and obeying robots.txt.",+ "link": "/portal",+ "tags": [+ "feature",+ "sdk"+ ]+ },{"date": "2026-08-28","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex 7da770b3a..6022141b1 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -14,6 +14,14 @@<category>launch</category><description>Every response from this API says where its data came from and how fresh it is, and every declared fallback has been proven by breaking the upstream it protects against, inside the real request path. Read the receipts: which provider refused, which one caught the request, and how old the answer was.</description></item>+ <item>+ <title>Brownout: proven fallbacks, not promised ones</title>+ <link>https://three.ws/docs/brownout</link>+ <guid isPermaLink="false">2026-08-28:Brownout: proven fallbacks, not promised ones</guid>+ <pubDate>Fri, 28 Aug 2026 12:00:00 GMT</pubDate>+ <category>launch</category>+ <description>Every response says where its data came from and how fresh it is, and every fallback the API claims has been executed for real against a genuinely refusing provider, inside the request path a user hits.</description>+ </item><item><title>Companion</title><link>https://three.ws/companion</link>@@ -190,6 +198,14 @@<category>launch</category><description>Paste any web address and walk through it in 3D. Portal reads the page's real structure and builds a place from it: sections become buildings sized by what they say, links become doors you step into, images become billboards. Download the world as a GLB or embed it in your own site.</description></item>+ <item>+ <title>Portal: walk any website in 3D</title>+ <link>https://three.ws/docs/portal</link>+ <guid isPermaLink="false">2026-08-28:Portal: walk any website in 3D</guid>+ <pubDate>Fri, 28 Aug 2026 12:00:00 GMT</pubDate>+ <category>launch</category>+ <description>Paste a web address and Portal builds a place out of it: sections become buildings sized by what they say, links become doors you step through, images become billboards. The API, the world spec, the npm package, the CLI and the MCP server behind /portal.</description>+ </item><item><title>Progressive Avatars</title><link>https://three.ws/stream</link>@@ -342,6 +358,14 @@<category>improvement</category><description>A handful of steps still had no time limit on the outside service they called. When that service accepted the connection and then went quiet, the request sat there until the platform killed it, and you got a spinner that ended in nothing: a photo-to-avatar upload that never came back, a saved model that never finished downloading, a coin launch stuck fetching its own thumbnail, an ordinals order whose status never loaded, a team task where one hired agent held up the whole run. Each of those now has a deadline and a clear answer when it is missed, and the ones that are safe to repeat retry once first. Anything that spends money or starts a generation is never repeated: it is bounded and then reported, so no upload is billed twice and no hire is paid twice. Saving a model from a link is also checked more tightly now, against the address it actually connects to and with the size limit applied while it downloads.</description></item>+ <item>+ <title>Portal: paste any web address and walk it in 3D</title>+ <link>https://three.ws/portal</link>+ <guid isPermaLink="false">2026-08-28:Portal: paste any web address and walk it in 3D</guid>+ <pubDate>Fri, 28 Aug 2026 12:00:00 GMT</pubDate>+ <category>feature</category>+ <description>Type a website into /portal and it becomes a place you can walk. Every section of the page turns into a building whose height is how much that section actually says, every link becomes a door you step through (a door to the same site rebuilds the world there, so Back walks you through the sites you visited), every image becomes a billboard showing the real image, and every code block becomes a dark monolith. The colours come from the site's own theme colour, so a site looks like itself. You explore it with your own avatar, and the same world downloads as a 3D file you can open in Blender or view in AR, embeds in your own page with one line, and is readable by an AI agent through a new MCP server. Two things worth knowing: the same address always builds exactly the same city, so a link you share opens the world you walked, and Portal behaves like a polite crawler, reading each page once, saying who it is, and obeying robots.txt.</description>+ </item><item><title>Report a bug and it arrives as a test that fails until it is fixed</title><link>https://three.ws/docs/witness</link>diff --git a/public/features.json b/public/features.jsonindex 6c88fe11c..22e0d27f6 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-28T06:32:04.493Z",+ "generated_at": "2026-08-28T06:34:45.433Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",@@ -912,6 +912,26 @@"tags": [],"showcase": false},+ {+ "path": "/docs/brownout",+ "title": "Brownout: proven fallbacks, not promised ones",+ "description": "Every response says where its data came from and how fresh it is, and every fallback the API claims has been executed for real against a genuinely refusing provider, inside the request path a user hits.",+ "added": "2026-08-28",+ "auth": null,+ "indexable": true,+ "tags": [],+ "showcase": false+ },+ {+ "path": "/docs/portal",+ "title": "Portal: walk any website in 3D",+ "description": "Paste a web address and Portal builds a place out of it: sections become buildings sized by what they say, links become doors you step through, images become billboards. The API, the world spec, the npm package, the CLI and the MCP server behind /portal.",+ "added": "2026-08-28",+ "auth": null,+ "indexable": true,+ "tags": [],+ "showcase": false+ },{"path": "/docs/glance","title": "Glance: agent cards for home screens",diff --git a/public/llms-full.txt b/public/llms-full.txtindex 94d4de9e0..e6d95b87b 100644--- a/public/llms-full.txt+++ b/public/llms-full.txt@@ -558,6 +558,18 @@ URL: https://three.ws/docs/create-agentnpm create @three-ws/agent turns a sentence into a rigged, downloadable 3D character with a working demo page. No account, no API key.+### Brownout: proven fallbacks, not promised ones++URL: https://three.ws/docs/brownout++Every response says where its data came from and how fresh it is, and every fallback the API claims has been executed for real against a genuinely refusing provider, inside the request path a user hits.++### Portal: walk any website in 3D++URL: https://three.ws/docs/portal++Paste a web address and Portal builds a place out of it: sections become buildings sized by what they say, links become doors you step through, images become billboards. The API, the world spec, the npm package, the CLI and the MCP server behind /portal.+### Glance: agent cards for home screensURL: https://three.ws/docs/glancediff --git a/public/llms.txt b/public/llms.txtindex 5e107cc45..635dc5685 100644--- a/public/llms.txt+++ b/public/llms.txt@@ -119,6 +119,8 @@ Create and customize an agent.- [Widget Studio](https://three.ws/studio): Pick an avatar, configure embed options, copy a one-line snippet for your site.- [Artifact Viewer](https://three.ws/artifact): Renders Claude artifact bundles as standalone embeddable apps.- [create-agent: one command, one 3D character](https://three.ws/docs/create-agent): npm create @three-ws/agent turns a sentence into a rigged, downloadable 3D character with a working demo page. No account, no API key.+- [Brownout: proven fallbacks, not promised ones](https://three.ws/docs/brownout): Every response says where its data came from and how fresh it is, and every fallback the API claims has been executed for real against a genuinely refusing provider, inside the request path a user hits.+- [Portal: walk any website in 3D](https://three.ws/docs/portal): Paste a web address and Portal builds a place out of it: sections become buildings sized by what they say, links become doors you step through, images become billboards. The API, the world spec, the npm package, the CLI and the MCP server behind /portal.- [Glance: agent cards for home screens](https://three.ws/docs/glance): Put a three.ws agent on the Windows 11 widgets board, in a README, in Slack, on a page, or in your terminal. Endpoint, element, widget worker and npm client.- [Glance](https://three.ws/glance): Your three.ws agent on every home screen: a live card for the Windows 11 widgets board, a README, Slack, or any page.- [Widgets Gallery](https://three.ws/widgets): Pre-built chat, voice, and 3D-avatar widgets you can drop into any page.diff --git a/public/sitemap/index.html b/public/sitemap/index.htmlindex a6a281e95..af5f4b1f2 100644--- a/public/sitemap/index.html+++ b/public/sitemap/index.html@@ -83,7 +83,7 @@<main class="sm-wrap"><div class="sm-hero"><h1>Sitemap</h1>- <p>All 870 pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</p>+ <p>All 872 pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</p><div class="sm-formats"><a href="/sitemap.xml"><code>sitemap.xml</code> · for search engines</a><a href="/llms.txt"><code>llms.txt</code> · for AI agents</a>@@ -95,7 +95,7 @@</div><div class="sm-filter"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="11" cy="11" r="7"/><path d="m21 21-4.3-4.3"/></svg>- <input id="sm-filter-input" type="search" placeholder="Filter 870 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />+ <input id="sm-filter-input" type="search" placeholder="Filter 872 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" /><kbd aria-hidden="true">/</kbd></div><p class="sm-filter-count" id="sm-filter-count" role="status" aria-live="polite"></p>@@ -144,35 +144,35 @@</a></li><li>- <a href="/docs/glance">+ <a href="/docs/brownout"><span class="sm-new-date">Aug 28, 2026</span>- <span class="sm-title">Glance: agent cards for home screens</span>- <span class="sm-path">/docs/glance</span>- <span class="sm-desc">Put a three.ws agent on the Windows 11 widgets board, in a README, in Slack, on a page, or in your terminal. Endpoint, element, widget worker and npm client.</span>+ <span class="sm-title">Brownout: proven fallbacks, not promised ones</span>+ <span class="sm-path">/docs/brownout</span>+ <span class="sm-desc">Every response says where its data came from and how fresh it is, and every fallback the API claims has been executed for real against a genuinely refusing provider, inside the request path a user hits.</span></a></li><li>- <a href="/glance">+ <a href="/docs/portal"><span class="sm-new-date">Aug 28, 2026</span>- <span class="sm-title">Glance</span>- <span class="sm-path">/glance</span>- <span class="sm-desc">Your three.ws agent on every home screen: a live card for the Windows 11 widgets board, a README, Slack, or any page.</span>+ <span class="sm-title">Portal: walk any website in 3D</span>+ <span class="sm-path">/docs/portal</span>+ <span class="sm-desc">Paste a web address and Portal builds a place out of it: sections become buildings sized by what they say, links become doors you step through, images become billboards. The API, the world spec, the npm package, the CLI and the MCP server behind /portal.</span></a></li><li>- <a href="/diff">+ <a href="/docs/glance"><span class="sm-new-date">Aug 28, 2026</span>- <span class="sm-title">Model Diff</span>- <span class="sm-path">/diff</span>- <span class="sm-desc">Drop two .glb files and see exactly what changed: geometry, materials, textures, skeletons and animation clips, with git-style rename and move detection and a severity you can gate a build on. Overlay, wipe, or set the two models side by side in 3D. Runs in your browser, nothing is uploaded.</span>+ <span class="sm-title">Glance: agent cards for home screens</span>+ <span class="sm-path">/docs/glance</span>+ <span class="sm-desc">Put a three.ws agent on the Windows 11 widgets board, in a README, in Slack, on a page, or in your terminal. Endpoint, element, widget worker and npm client.</span></a></li><li>- <a href="/tty">+ <a href="/glance"><span class="sm-new-date">Aug 28, 2026</span>- <span class="sm-title">Terminal renderer</span>- <span class="sm-path">/tty</span>- <span class="sm-desc">curl three.ws/tty and a rigged 3D agent walks in your terminal. A software rasterizer streams ANSI frames over HTTP: no GPU, no WebGL, nothing to install. Also the @three-ws/tty CLI and library for rendering any GLB in a terminal.</span>+ <span class="sm-title">Glance</span>+ <span class="sm-path">/glance</span>+ <span class="sm-desc">Your three.ws agent on every home screen: a live card for the Windows 11 widgets board, a README, Slack, or any page.</span></a></li></ul>@@ -593,7 +593,7 @@<section class="sm-section" id="build"><header>- <h2>Build<span class="sm-count" data-count>66</span></h2>+ <h2>Build<span class="sm-count" data-count>68</span></h2><p class="sm-section-desc">Create and customize an agent.</p></header><ul class="sm-list">@@ -828,6 +828,20 @@<span class="sm-desc">npm create @three-ws/agent turns a sentence into a rigged, downloadable 3D character with a working demo page. No account, no API key.</span></a></li>+ <li>+ <a href="/docs/brownout">+ <span class="sm-title">Brownout: proven fallbacks, not promised ones</span>+ <span class="sm-path">/docs/brownout</span>+ <span class="sm-desc">Every response says where its data came from and how fresh it is, and every fallback the API claims has been executed for real against a genuinely refusing provider, inside the request path a user hits.</span>+ </a>+ </li>+ <li>+ <a href="/docs/portal">+ <span class="sm-title">Portal: walk any website in 3D</span>+ <span class="sm-path">/docs/portal</span>+ <span class="sm-desc">Paste a web address and Portal builds a place out of it: sections become buildings sized by what they say, links become doors you step through, images become billboards. The API, the world spec, the npm package, the CLI and the MCP server behind /portal.</span>+ </a>+ </li><li><a href="/docs/glance"><span class="sm-title">Glance: agent cards for home screens</span>diff --git a/specs/PORTAL_WORLD.md b/specs/PORTAL_WORLD.mdnew file mode 100644index 000000000..4aa3d0881--- /dev/null+++ b/specs/PORTAL_WORLD.md@@ -0,0 +1,134 @@+# Portal World v1++The wire format behind [`/api/portal`](../docs/portal.md). One web page, reduced to a place you can walk.++- **Endpoint:** `GET https://three.ws/api/portal?url=<address>`+- **Media types:** `application/json` (default), `model/gltf-binary` (`format=glb`)+- **Reference implementation:** [`packages/portal/src/layout.js`](../packages/portal/src/layout.js) (`buildWorld`), published as [`@three-ws/portal`](../packages/portal/README.md)+- **Companion specs:** [SPATIAL_MCP.md](SPATIAL_MCP.md) (returning 3D as a tool result), [EMBED_SPEC.md](EMBED_SPEC.md) (the 3D embed)++## Why it exists++Two documents could have been one. They are deliberately separate because they fail differently.++The **outline** is what a page says: its heading spine, the weight of each section, where it links, what it shows. Reading it needs the network, an HTML parser, a robots.txt check and a fetch budget. It can fail in a dozen ways that all mean "the web is the web".++The **world** is what that page looks like as a place. Building it needs nothing at all: no network, no DOM, no renderer, no clock, no randomness that is not seeded. Given the same outline it always returns the same world, byte for byte.++Keeping them apart is what makes a Portal link shareable. The person who opens your link runs the same pure function over the same cached outline and stands in the same city you did. It is also what lets the layout run in four places without drifting: the page renderer, the server's GLB exporter, the MCP tools, and anyone who installs the npm package.++## SiteOutline++```json+{+ "version": 1,+ "url": "https://example.com/docs",+ "canonical": "https://example.com/docs",+ "host": "example.com",+ "title": "Docs",+ "description": "How to use the thing.",+ "siteName": "Example",+ "themeColor": "#3366ff",+ "image": "https://example.com/og.png",+ "icon": "https://example.com/favicon.ico",+ "lang": "en",+ "words": 1840,+ "linkCounts": { "internal": 38, "external": 4 },+ "sections": [+ {+ "id": "getting-started",+ "level": 2,+ "heading": "Getting started",+ "summary": "Install it, then point it at a page.",+ "words": 210,+ "paragraphs": 6,+ "codeBlocks": 2,+ "links": [{ "href": "https://example.com/install", "text": "install", "internal": true }],+ "images": [{ "src": "https://example.com/shot.png", "alt": "The console" }]+ }+ ]+}+```++Rules a consumer can rely on:++- **Sections open at every `h1`, `h2` and `h3`**, in document order, and own everything until the next heading. A page whose prose starts before any heading gets one section named after the document title, so a page with no headings still has a place.+- **`id` is stable and unique.** It is a slug of the heading, suffixed on collision, so a world keeps its node names across rebuilds.+- **Prose is counted once.** A `<p>` inside a `<blockquote>` is one paragraph, not two, and `<pre><code>` is one code block, not two.+- **Chrome is not content.** `script`, `style`, `noscript`, `template`, `svg`, `iframe`, `form`, `nav`, `header` and `footer` are removed before reading, so a navigation menu never becomes a section full of doors.+- **Every list is bounded**: 24 sections, 8 links and 4 images per section, and clamped strings (see `LIMITS` in [`api/_lib/portal/outline.js`](../api/_lib/portal/outline.js)). One hostile page cannot produce an unbounded world.+- **Links are absolute `http(s)` URLs.** `mailto:`, `javascript:` and bare fragments are dropped. `internal` compares against the host of the page the link was found on.++## PortalWorld++```json+{+ "version": 1,+ "meta": { "url": "…", "canonical": "…", "host": "example.com", "title": "Docs",+ "description": "…", "siteName": "Example", "lang": "en",+ "seed": 2748619284, "words": 1840, "sections": 12,+ "links": { "internal": 38, "external": 4 } },+ "palette": { "primary": "#…", "secondary": "#…", "accent": "#…",+ "ground": "#…", "sky": "#…", "fog": "#…", "monolith": "#…" },+ "ground": { "radius": 74.2, "color": "#…", "sky": "#…", "fog": "#…" },+ "plaza": { "radius": 11, "monument": { "label": "Docs", "sub": "…", "h": 5.4 } },+ "spawn": { "x": 0, "z": 6.05, "yaw": 3.14159 },+ "districts": [{ "id": "d-getting-started", "sectionId": "getting-started", "x": 17, "z": 0, "radius": 9.1 }],+ "buildings": [{ "id": "b-getting-started", "sectionId": "getting-started", "kind": "hall",+ "label": "Getting started", "summary": "…", "words": 210,+ "x": 17, "z": 0, "w": 7.5, "d": 6.1, "h": 9.4, "rot": 3.14159,+ "color": "#…", "floors": 3 }],+ "doors": [{ "id": "door-getting-started-0", "buildingId": "b-getting-started",+ "href": "https://example.com/install", "label": "install", "internal": true,+ "x": 20.7, "z": 0, "yaw": 3.14159, "w": 1.6, "h": 2.6, "color": "#…" }],+ "props": [{ "id": "img-getting-started-0", "kind": "billboard", "x": 12, "z": 3,+ "yaw": 0, "w": 3.2, "h": 2, "src": "https://example.com/shot.png",+ "label": "The console", "color": "#…" }]+}+```++### The mapping++| On the page | In the world | Rule |+| --- | --- | --- |+| The page | The plaza and its obelisk | Always at the origin, radius `METRICS.plazaRadius` |+| A section | One district, one building | Placed on a phyllotaxis spiral: `angle = i · golden`, `radius = 17 + 7.6·√i` |+| Its word count | Building height | `log10(max(10, words))` scaled, clamped to `[3.5, 26]` metres |+| Its block count | Building footprint | Paragraph count widens it, clamped to `[4.5, 13]` metres |+| Heading level | Silhouette | `1 → tower`, `2 → hall`, `3 → kiosk` (kiosks cap at 6 m) |+| A link | A door on a wall | Two per face, starting at the plaza-facing wall, always flush and never inside |+| An image | A billboard | Fanned out behind the building, angled back toward the plaza |+| A code block | A monolith | Up to four, in a short row beside the building |+| `theme-color`, else the host | The palette | Theme hue when present, else `FNV-1a(host) % 360` |++### Invariants++Every one of these is covered by [`tests/portal-layout.test.js`](../tests/portal-layout.test.js):++1. **Deterministic.** `buildWorld(outline)` is pure. The seed is `FNV-1a(canonical || url)`, and all randomness runs through `seededRandom(seed)` (mulberry32).+2. **Bounded.** Height, footprint and ground radius are clamped; the ground always contains every building.+3. **Non-overlapping.** No two buildings intersect, at any section count up to the outline cap.+4. **Walkable.** `spawn` is outside every collider returned by `collidersFor(world)`.+5. **Log-scaled.** A section with five times the words is taller, but not five times taller.+6. **Additive versioning.** `version` is `1`. A consumer must ignore fields it does not know, and may assume the fields above keep their meaning within a major version.++### Doors are the navigation model++A door carries the real `href`. Internal doors rebuild the world at that address (the renderer pushes `/portal?url=…`, so the browser's back button walks back through the sites you visited). External doors open the page. A consumer that renders worlds without a browser (a game engine, a Blender import) can treat `doors` as an adjacency list and crawl the site as a graph.++## GLB export++`format=glb` returns the same world as glTF 2.0 binary: one node per building, door, billboard and monolith, named `building:<sectionId>` and so on, plus a ground disc, the plaza, the obelisk and two `KHR_lights_punctual` lights. Geometry is instanced from one box and one cylinder, and materials are deduplicated by colour, so a 24-district city is tens of kilobytes rather than tens of megabytes. The `asset.copyright` field records the page the structure came from.++## Manners++Portal is a crawler that runs on a person's request:++- Identifies as `ThreeWSPortalBot/1.0 (+https://three.ws/portal)`.+- Reads `robots.txt` first and honours a `Disallow` for that token with `403 robots_disallowed`. Matching follows RFC 9309: most specific user-agent group, longest matching rule, `Allow` wins a tie, `*` and `$` supported ([`api/_lib/portal/robots.js`](../api/_lib/portal/robots.js)).+- Fetches each page once; worlds are cached fleet-wide for an hour.+- Bounded at 3 MB of HTML and a 12 second deadline, through the IP-pinned SSRF guard, which re-validates every redirect hop.++## Error codes++`invalid_url`, `robots_disallowed`, `blocked_host`, `not_html`, `no_structure`, `too_large`, `unreachable`, `upstream_status`, `rate_limited`. Every one arrives as `{ "error": "<code>", "error_description": "<sentence a person can act on>" }`.diff --git a/specs/README.md b/specs/README.mdindex 4d246aa2f..d5f2ddfc0 100644--- a/specs/README.md+++ b/specs/README.md@@ -21,6 +21,7 @@ The specifications that define the three.ws embodied-agent platform: on-chain id- [`ECONOMY_CONTRACT_INVARIANTS.md`](./ECONOMY_CONTRACT_INVARIANTS.md): Economy Contract Invariants v1. The properties every value-bearing contract in [`contracts/`](../contracts) must hold for all reachable states and all callers, each with a stable id and a positive plus negative test that cites it.- [`ECONOMY_CONTRACT_THREAT_MODEL.md`](./ECONOMY_CONTRACT_THREAT_MODEL.md): Economy Contract Threat Model v1. The attacker's-eye companion to the invariants: what is worth stealing, which actor could try, what stops each attempt, and which risks are accepted rather than mitigated. Entry point for a review engagement is [`contracts/AUDIT-README.md`](../contracts/AUDIT-README.md).- [`PROVENANCE_3D.md`](./PROVENANCE_3D.md): Verifiable 3D Provenance v1. C2PA-style signed content credentials for AI-generated 3D: creator, prompt, model, lineage and the GLB's content hash, ed25519-signed and anchored on Solana. Verification is free and public.+- [`PORTAL_WORLD.md`](./PORTAL_WORLD.md): Portal World v1. The two documents behind `/api/portal`: the outline a web page is read into, and the deterministic, seeded world that outline lays out into. Pure layout, so the browser renderer, the GLB exporter, the MCP tools and the npm package all build the same city from the same link.- [`SIM_READINESS.md`](./SIM_READINESS.md): Simulation Readiness v1. The physics grade a 3D asset carries: watertightness, metric scale, mass and inertia, and a convex collision proxy, in four verdicts. Everything is derived from the mesh; anything unknowable from the geometry is reported as unknown rather than invented. Rides the provenance credential when signed.- [`SKILL_ROYALTY_SPLIT.md`](./SKILL_ROYALTY_SPLIT.md): Skill Royalty Split v1. How a paid skill call divides between the author and the platform, and how that division is recorded: exact integer arithmetic that conserves value and rounds toward the creator, who the author of record is, which wallet a payout resolves to, and the ledger invariants both earning lanes must hold. The contract the x402 rail, the accrual writer, the settle cron and the earnings surface all read from.