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(resilience): document the browser-side fallback helpers and announce the CDN and gateway recovery to holders

nirholas0cbfcf26eb0b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9020192e4..26825cb33 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,8 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **three.ws for Seeker** (`/seeker`): The home screen of the three.ws app on Solana Seeker: one-tap Seed Vault sign-in, selfie to avatar, your agents, the marketplace, and Seeker Genesis Token verification.
- **three.ws on Solana Seeker** (`/docs/seeker-app`): What the Seeker app adds on top of the website: Seed Vault sign-in, share-sheet capture, an offline shell, home-screen shortcuts, and Seeker Genesis Token verification.
- **A real home screen for the Seeker app, and a Seeker verified badge**: The three.ws app on Solana Seeker now opens on its own home screen at /seeker: one tap signs you in with Seed Vault, your agents are right there, and Create, Discover, and Chat are a thumb away. Seeker owners can prove it by checking for the Seeker Genesis Token in their wallet (a read, never a transaction); once verified, every agent they own shows a Seeker verified badge on its page. (`/seeker`) `[feature]`
+- **Agent pages, embeds and the camera tools keep working when a CDN or gateway is down**: The parts of the site that load files from someone else's server used to have exactly one place to get them. If that one host was slow, blocked by a corporate network, or rate-limiting the visitor, the result was a blank box with no explanation: an agent page with no avatar, a 3D preview that never appeared, mocap and sign-language input that refused to start, a deposit QR that showed a broken image. Each of those now tries every equivalent source in turn. Agent avatars retry across all four IPFS gateways, on-chain reads rotate through every public node for the chain, the 3D viewer loads its decoders from our own servers, the camera tools ship their code with the page, and a QR code that cannot be drawn falls back to text you can still copy. `[improvement, fix]`
+- **Every outside data source now has a backup**: Prices, DeFi stats, token data, pump.fun feeds, RPC reads and 3D generation providers all had single points of failure: one rate limit or outage upstream turned into a blank section or an error page. Every one of those reads now has a deadline, retries only on transient faults, a second and third source where one exists, and keeps serving the last good value (marked as stale) when everything upstream is down. In the browser, API calls time out instead of spinning forever, script and model loads try mirror CDNs, and payment flows report a failed confirmation with the transaction signature instead of showing nothing. `[improvement, fix, infra]`
- **Every tap target on the marketplace and your agents pages now fits a thumb**: On phones, the hearts, tags, author links and the write-with-agent button on marketplace cards were as small as 18 pixels tall, so browsing on a Seeker or any Android phone meant a lot of missed taps. All of them, plus the walk-companion controls and footer links, now sit inside 44 pixel tap areas without changing how the cards look. Measured on a real phone profile: the marketplace went from 1,352 undersized controls to zero. (`/marketplace`) `[improvement]`
- **Seeker app: stay signed in across restarts, and a submission path that matches today's dApp Store**: On Solana Seeker, the three.ws app now remembers your Seed Vault session when Android restarts the app in the background, so reopening it no longer asks you to approve again; a revoked session is dropped cleanly instead of failing every signature. The My Agents home-screen shortcut opens your own agents instead of the public index. Behind the scenes the store submission tooling was rebuilt for the Publisher Portal that Solana Mobile now uses, and the listing copy was rewritten to describe only what the app really does. (`/my-agents`) `[improvement, fix, infra]`
- **Share a photo or a 3D file straight into three.ws**: On Android (and the Seeker app) three.ws now appears in the share sheet. Share a photo from your camera roll and it lands in the selfie-to-avatar flow already attached; share a .glb and it opens the upload flow. Going offline inside the app shows a three.ws screen that reloads on its own when the connection is back, instead of a browser error, and the home-screen icon no longer gets its corners cropped on round or squircle launchers. (`/create`) `[feature, improvement]`
diff --git a/data/changelog.json b/data/changelog.json
index 5a58ce158..5af5d7726 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,15 @@
{
"$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-27",
+ "title": "Agent pages, embeds and the camera tools keep working when a CDN or gateway is down",
+ "summary": "The parts of the site that load files from someone else's server used to have exactly one place to get them. If that one host was slow, blocked by a corporate network, or rate-limiting the visitor, the result was a blank box with no explanation: an agent page with no avatar, a 3D preview that never appeared, mocap and sign-language input that refused to start, a deposit QR that showed a broken image. Each of those now tries every equivalent source in turn. Agent avatars retry across all four IPFS gateways, on-chain reads rotate through every public node for the chain, the 3D viewer loads its decoders from our own servers, the camera tools ship their code with the page, and a QR code that cannot be drawn falls back to text you can still copy.",
+ "tags": [
+ "improvement",
+ "fix"
+ ]
+ },
{
"date": "2026-08-27",
"title": "Every outside data source now has a backup",
diff --git a/docs/shared-utilities.md b/docs/shared-utilities.md
index 6c3189d90..69c187297 100644
--- a/docs/shared-utilities.md
+++ b/docs/shared-utilities.md
@@ -93,6 +93,41 @@ timeAgo('2026-07-29T10:00:00Z'); // "3m ago"
timeAgo(1783670400); // unix seconds, handled
```
+### Browser-side fallbacks: never depend on one host
+
+Four helpers exist so no page hinges on a single third-party host. Reach for
+them instead of writing a CDN URL, a gateway URL, or a price feed inline.
+
+```js
+import { fetchFirst, fetchFirstOrNull } from './shared/failover-fetch.js';
+import { getSolPriceUsd, getTokenPriceUsd, getBtcPriceUsd } from './shared/usd-price.js';
+import { ensureModelViewer, ensureModelViewerOrFallback } from './shared/model-viewer-loader.js';
+import { loadVision, visionWasmBase, modelUrl } from './shared/mediapipe-assets.js';
+import { uriCandidates } from './ipfs.js';
+import { readProvider } from './erc8004/chain-meta.js';
+```
+
+| Helper | Covers | Behaviour when a host is down |
+|---|---|---|
+| `fetchFirst(providers, opts)` | any ordered provider list | 4s per attempt, 60s cooldown on a failing provider, throws only when all miss |
+| `getSolPriceUsd` / `getTokenPriceUsd(mint)` / `getBtcPriceUsd` | USD quotes | 4 feeds each; returns the last real price, or null. Never a hardcoded rate |
+| `ensureModelViewerOrFallback(root)` | the `<model-viewer>` element | 3 CDNs, then every viewer in `root` becomes its poster image or a caption |
+| `loadVision()` / `visionWasmBase()` / `modelUrl(path)` | MediaPipe | module is bundled; runtime prefers `public/vendor/mediapipe`, then 2 CDNs |
+| `uriCandidates(uri)` | IPFS / Arweave content | one URL per gateway, including for a URL whose gateway was already chosen |
+| `readProvider(chainId)` | browser EVM reads | ethers `FallbackProvider` over every keyless node in `CHAIN_META`, quorum 1 |
+
+Two rules that are easy to get wrong:
+
+- **Resolve asset paths against `import.meta.url`, not the site root.** Inside a
+ third-party `<agent-3d>` embed a `/vendor/...` path resolves against the
+ *embedding* page and 404s. `new URL('../../vendor/mediapipe', import.meta.url)`
+ points at whichever origin served the module, which is what you want.
+- **A file under `public/` that is not a Vite input cannot import from `src/`.**
+ It ships as a raw copy, so the `/src/*` reference 404s in production
+ (`public/forever.js` keeps its feed list inline for exactly this reason).
+ Either register the page as a Rollup input in `vite.config.js` or stay
+ self-contained.
+
---
## Backend
diff --git a/public/changelog.json b/public/changelog.json
index 2ebb2dafb..5906fa996 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-08-27T05:50:04.377Z",
+ "generated_at": "2026-08-27T13:30:23.928Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -36,6 +36,29 @@
"feature"
]
},
+ {
+ "date": "2026-08-27",
+ "type": "update",
+ "title": "Agent pages, embeds and the camera tools keep working when a CDN or gateway is down",
+ "summary": "The parts of the site that load files from someone else's server used to have exactly one place to get them. If that one host was slow, blocked by a corporate network, or rate-limiting the visitor, the result was a blank box with no explanation: an agent page with no avatar, a 3D preview that never appeared, mocap and sign-language input that refused to start, a deposit QR that showed a broken image. Each of those now tries every equivalent source in turn. Agent avatars retry across all four IPFS gateways, on-chain reads rotate through every public node for the chain, the 3D viewer loads its decoders from our own servers, the camera tools ship their code with the page, and a QR code that cannot be drawn falls back to text you can still copy.",
+ "link": null,
+ "tags": [
+ "improvement",
+ "fix"
+ ]
+ },
+ {
+ "date": "2026-08-27",
+ "type": "update",
+ "title": "Every outside data source now has a backup",
+ "summary": "Prices, DeFi stats, token data, pump.fun feeds, RPC reads and 3D generation providers all had single points of failure: one rate limit or outage upstream turned into a blank section or an error page. Every one of those reads now has a deadline, retries only on transient faults, a second and third source where one exists, and keeps serving the last good value (marked as stale) when everything upstream is down. In the browser, API calls time out instead of spinning forever, script and model loads try mirror CDNs, and payment flows report a failed confirmation with the transaction signature instead of showing nothing.",
+ "link": null,
+ "tags": [
+ "improvement",
+ "fix",
+ "infra"
+ ]
+ },
{
"date": "2026-08-27",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index 4566173e9..3791a8707 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -30,6 +30,22 @@
<category>feature</category>
<description>The three.ws app on Solana Seeker now opens on its own home screen at /seeker: one tap signs you in with Seed Vault, your agents are right there, and Create, Discover, and Chat are a thumb away. Seeker owners can prove it by checking for the Seeker Genesis Token in their wallet (a read, never a transaction); once verified, every agent they own shows a Seeker verified badge on its page.</description>
</item>
+ <item>
+ <title>Agent pages, embeds and the camera tools keep working when a CDN or gateway is down</title>
+ <link>https://three.ws/changelog</link>
+ <guid isPermaLink="false">2026-08-27:Agent pages, embeds and the camera tools keep working when a CDN or gateway is down</guid>
+ <pubDate>Thu, 27 Aug 2026 12:00:00 GMT</pubDate>
+ <category>improvement</category>
+ <description>The parts of the site that load files from someone else's server used to have exactly one place to get them. If that one host was slow, blocked by a corporate network, or rate-limiting the visitor, the result was a blank box with no explanation: an agent page with no avatar, a 3D preview that never appeared, mocap and sign-language input that refused to start, a deposit QR that showed a broken image. Each of those now tries every equivalent source in turn. Agent avatars retry across all four IPFS gateways, on-chain reads rotate through every public node for the chain, the 3D viewer loads its decoders from our own servers, the camera tools ship their code with the page, and a QR code that cannot be drawn falls back to text you can still copy.</description>
+ </item>
+ <item>
+ <title>Every outside data source now has a backup</title>
+ <link>https://three.ws/changelog</link>
+ <guid isPermaLink="false">2026-08-27:Every outside data source now has a backup</guid>
+ <pubDate>Thu, 27 Aug 2026 12:00:00 GMT</pubDate>
+ <category>improvement</category>
+ <description>Prices, DeFi stats, token data, pump.fun feeds, RPC reads and 3D generation providers all had single points of failure: one rate limit or outage upstream turned into a blank section or an error page. Every one of those reads now has a deadline, retries only on transient faults, a second and third source where one exists, and keeps serving the last good value (marked as stale) when everything upstream is down. In the browser, API calls time out instead of spinning forever, script and model loads try mirror CDNs, and payment flows report a failed confirmation with the transaction signature instead of showing nothing.</description>
+ </item>
<item>
<title>Every tap target on the marketplace and your agents pages now fits a thumb</title>
<link>https://three.ws/marketplace</link>
diff --git a/public/features.json b/public/features.json
index 18e06f652..40c414479 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-08-27T05:50:04.361Z",
+ "generated_at": "2026-08-27T13:30:23.920Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",