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(structure): map My Creations and cover the /cdn storage failover with a test

nirholas237662fad167
diff --git a/STRUCTURE.md b/STRUCTURE.md
index b78bc0807..d0e0db4e3 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -52,6 +52,7 @@ bottom.
| Cookbook (runnable recipes) | Index [pages/cookbook.html](pages/cookbook.html) `-> /cookbook`, recipe viewer [pages/recipe.html](pages/recipe.html) `-> /cookbook/<slug>`, manifest [public/cookbook-manifest.js](public/cookbook-manifest.js), styles [public/cookbook.css](public/cookbook.css), recipe prose [docs/cookbook/](docs/cookbook), runnable files [public/cookbook/recipes/](public/cookbook/recipes), notebook export [public/cookbook/self-correcting-3d/](public/cookbook/self-correcting-3d) | Live | The sibling of the Examples gallery, and deliberately a different thing: an example is a snippet you read on the page, a recipe is a file you download and run. Five recipes, each one executed against the live API before it was published: a standard-library text-to-3D CLI, a parallel asset-pack builder that emits a manifest plus a gallery, an MCP server that hands Claude Code or Cursor a 3D tool, a CI budget gate over [api/3d/inspect.js](api/3d/inspect.js), and the function-calling-plus-vision notebook also submitted to the OpenAI Cookbook. The manifest is the single source of truth for both surfaces; recipe prose is markdown under `docs/cookbook/` fetched by the viewer, so adding a recipe is a manifest entry plus a `.md` plus the file itself. Route order is load-bearing in both [vercel.json](vercel.json) and the dev middleware: the notebook's static export must be matched before the generic `/cookbook/<slug>` rule or the viewer shadows it. Docs: [public/cookbook/recipes/README.md](public/cookbook/recipes/README.md). Tests: [tests/cookbook.test.js](tests/cookbook.test.js) |
| Walkthroughs (interactive product tours from real frames) | Index [pages/walkthroughs.html](pages/walkthroughs.html) + [src/walkthroughs-index.js](src/walkthroughs-index.js) `→ /walkthroughs`, player [pages/walkthrough.html](pages/walkthrough.html) + [src/walkthrough.js](src/walkthrough.js) `→ /walkthroughs/<slug>` (routed in [vercel.json](vercel.json), mirrored by the Vite dev middleware in [vite.config.js](vite.config.js)), pure step geometry [src/walkthrough-geometry.js](src/walkthrough-geometry.js), generated manifest + screenshot sets [public/walkthroughs/](public/walkthroughs) captured by [scripts/capture-walkthroughs.mjs](scripts/capture-walkthroughs.mjs) | Live | Step-by-step guided tours (forge a 3D model, build an agent, embed an avatar, find an agent worth using) built from real frames captured on the live product: each step zooms and pans to the element it describes, cuts a spotlight around it, and anchors a callout, so it reads like a screen recording but is a handful of deep-linkable, keyboard-operable JPEGs that degrade to annotated stills under reduced motion. Index and player read the same generated manifest, so a walkthrough that did not capture cleanly cannot be advertised. Registered in [data/pages.json](data/pages.json). |
| Cross-entity search | [pages/search.html](pages/search.html) `→ /search` + page module [src/search-page.js](src/search-page.js), backend [api/search.js](api/search.js) + query layer [api/_lib/cross-search.js](api/_lib/cross-search.js) | Live | The one search across every creation type: avatars, on-chain/Solana agents, forged 3D models, worlds, and coins. Federates (not one SQL UNION, because the stores are genuinely heterogeneous and two of five are not even in the same database) five parallel queries, normalizes into one card shape, and ranks by recency plus real signals (follower count via `user_follows`, remix count, view count); see the file header in `api/search.js` for the full unify-vs-federate writeup. Model results carry a working "Remix, $0.25" action against the existing paid rail ([api/x402/remix-asset.js](api/x402/remix-asset.js)), reused from [pages/creations.html](pages/creations.html) rather than re-derived. Coin search checks three.ws's own launch directory (`pump_agent_mints`) first, then falls back to market-wide pump.fun/Birdeye search for broader coverage (those external matches carry no verified timestamp or creator profile, and are ranked/labelled accordingly). The page reads `?q=` and `?type=` from the URL before it paints the filter row, so a shared scoped link shows the filter it is actually applying; a type whose source returned nothing for the current query is dimmed from the real `counts` in the response. The backend answering `{enabled:false}` (creation stores unreachable) renders its own "search is warming up" state with a retry and live browse links, never a false "nothing matched". Enter runs the query without waiting out the debounce and Escape clears it. Linked from the Discover nav menu. |
+| My Creations (personal creation index) | [pages/mine.html](pages/mine.html) `→ /mine` (alias `→ /my-creations`) + page module [src/mine.js](src/mine.js), styles [src/mine.css](src/mine.css) | Live | The answer to "where did the thing I just made go?". One newest-first grid merging four real feeds: `/api/agents` and `/api/avatars/mine` (session-scoped), `/api/forge-gallery` (scoped to this browser's `forge:cid`, so a model forged before signing up is still findable), and `/api/users/:username/creations` (models, worlds and restyles forged while signed in on any device), de-duplicated by id. Cards carry Open, Edit (or "Forge again", which re-runs the original prompt through `/forge?prompt=`) and Copy link, with lazy `<model-viewer>` previews under a six-context budget. Signed out it still renders this browser's models behind a sign-in prompt rather than an empty void, and a total source failure renders an error state, never a false "you have nothing". Reachable from the nav's My creations button ([public/nav.html](public/nav.html), drawer row in [public/nav.js](public/nav.js), Build menu in [public/nav-data.js](public/nav-data.js)), the dashboard sidebar, the create-agent success screen, the /create hub, /forge's creations strip and /my-agents. Tests: [tests/mine-page.test.js](tests/mine-page.test.js) |
| Cross-surface rankings, streaks & badges | [pages/rankings.html](pages/rankings.html) `→ /rankings`, backend [api/leaderboard/unified.js](api/leaderboard/unified.js), streak/badge engine [api/_lib/streaks.js](api/_lib/streaks.js) (migration [api/_lib/migrations/20260712020000_leaderboard_streaks_badges.sql](api/_lib/migrations/20260712020000_leaderboard_streaks_badges.sql)), daily Top-10 badge sweep [api/cron/leaderboard-rollup.js](api/cron/leaderboard-rollup.js) | Live | Five real, queried leaderboard metrics — creations (forge models + worlds), remixes received, coin launches, followers, and walk distance (signed-in walkers, all-time) — ranked live with the viewer's own rank pinned even off-page. Every signed-in qualifying action (login, a finished forge model, a saved world, a `/walk` session) rolls a per-user daily streak in `user_streaks` via `recordDailyActivity()`, called from [api/_lib/auth.js](api/_lib/auth.js), [api/_lib/forge-store.js](api/_lib/forge-store.js), [api/_lib/diorama-store.js](api/_lib/diorama-store.js), and [api/walk/metrics.js](api/walk/metrics.js). Four real earned badges persist in `user_badges`: First Creation, Remixed (awarded in [api/x402/remix-asset.js](api/x402/remix-asset.js) when a remix lands on your creation), 7-Day Streak, and a daily-refreshed `top10_<metric>` per leaderboard. Streak + badges surface on the profile ([pages/profile.html](pages/profile.html)) and the Rankings page itself. Rejected metrics (documented in `api/leaderboard/unified.js`'s header): royalties earned in USD (the settlement record is a single overwritten JSONB column, not a cumulative ledger) and `/play` activity (no per-human-user session table exists). |
| create-agent (one command, one 3D character) | [packages/create-agent/](packages/create-agent) (client [src/forge.js](packages/create-agent/src/forge.js), scaffold [src/scaffold.js](packages/create-agent/src/scaffold.js), CLI [bin/create-agent.js](packages/create-agent/bin/create-agent.js)), server tools [api/_mcp-studio/tools.js](api/_mcp-studio/tools.js) | Live | `npm create @three-ws/agent "a friendly cartoon astronaut"` generates a textured figure, rigs it, downloads the GLB, and writes a folder with a working demo page and the embed snippet. No account and no API key: it rides the public, keyless JSON-RPC tools on [/api/mcp-studio](api/_mcp-studio) (`forge_avatar`, `forge_free`, `rig_mesh`) that the platform already exposes to MCP clients. A rigged character reliably outlives the endpoint's inline wait, so the client collects the returned poll handle and, when the job that finished was only the mesh, rigs it before reporting done: that is what the `stage` field on a pending result exists for. Progress is real elapsed time, never an invented bar. Docs [docs/create-agent.md](docs/create-agent.md). Tests: [tests/create-agent.test.js](tests/create-agent.test.js) |
| Glance (agent cards for home screens, READMEs and chat) | Page [public/glance/index.html](public/glance/index.html) `-> /glance` (+ [glance-page.js](public/glance/glance-page.js), [glance.css](public/glance/glance.css)), hosted element [public/glance/element.js](public/glance/element.js), endpoints [api/glance/card.js](api/glance/card.js) / [api/glance/mine.js](api/glance/mine.js) / [api/glance/token.js](api/glance/token.js) / [api/glance/template.js](api/glance/template.js), model [api/_lib/glance-card.js](api/_lib/glance-card.js), SVG [api/_lib/glance-svg.js](api/_lib/glance-svg.js), PNG [api/_lib/glance-png.js](api/_lib/glance-png.js), widget tokens [api/_lib/glance-tokens.js](api/_lib/glance-tokens.js) (`glance_widget_tokens`), Adaptive Card [api/_lib/glance-adaptive.js](api/_lib/glance-adaptive.js), Windows widget worker [public/glance-sw.js](public/glance-sw.js) (imported by the VitePWA service worker, manifest `widgets` member in [vite.config.js](vite.config.js)), Android home screen widget [solana-mobile/android-overlay/](solana-mobile/android-overlay/README.md) (applied by [solana-mobile/scripts/apply-overlay.mjs](solana-mobile/scripts/apply-overlay.mjs) inside `build-apk.sh`), macOS and iOS WidgetKit widget [apple/](apple/README.md) (shared [apple/GlanceKit/](apple/GlanceKit), extension [apple/GlanceWidget/](apple/GlanceWidget), Mac app [apple/macos/](apple/macos), an iOS target in [ios/native/App/App.xcodeproj](ios/native/App)), npm client [packages/agent-glance/](packages/agent-glance) | Live | One agent reduced to what fits in an OS widget slot: name, one live number (actions in the last 24h), and a link back. The same model renders five ways from one endpoint (JSON, SVG, PNG, Adaptive Card, and the `<agent-glance>` element), which is what keeps a new surface a rendering job rather than a data job. Windows 11 installs the widget straight from the PWA manifest (no store submission). Android ships it in the app (1.1+): a WorkManager-refreshed `AppWidgetProvider` that fetches the PNG with a revocable per-account widget token minted on `/glance`, keeps the last card offline, and opens the agent on tap. macOS and iOS run one WidgetKit extension over the same PNG and the same token, in small, medium and large: the Mac ships as a Developer ID menu bar app that holds the token and feeds the widget, and the iPhone gets the extension inside the existing Capacitor app. Both fetch the card in each theme so the widget follows the reader's appearance. `npm run check:apple-widget` proves both Xcode projects and the client-to-server contract without a Mac in the room. Deliberately not the 3D embed: no widget host on any of these platforms can run WebGL, so the body stays at [/widgets](public/widgets-gallery/index.html) and the status lives here. Private avatars never leak (the thumbnail is attached only for a public or unlisted avatar; everything else draws a generated monogram). Spec [specs/GLANCE_CARD.md](specs/GLANCE_CARD.md), docs [docs/glance.md](docs/glance.md), [docs/native-widgets.md](docs/native-widgets.md). Tests: [tests/glance-card.test.js](tests/glance-card.test.js), [tests/glance-png.test.js](tests/glance-png.test.js), [tests/glance-tokens.test.js](tests/glance-tokens.test.js), [tests/glance-sw.test.js](tests/glance-sw.test.js), [tests/agent-glance-sdk.test.js](tests/agent-glance-sdk.test.js), guard [scripts/check-apple-widget.mjs](scripts/check-apple-widget.mjs) |
diff --git a/tests/cdn-object-storage-failover.test.js b/tests/cdn-object-storage-failover.test.js
new file mode 100644
index 000000000..cfb288283
--- /dev/null
+++ b/tests/cdn-object-storage-failover.test.js
@@ -0,0 +1,112 @@
+/**
+ * /cdn/<key> failover, unit test.
+ *
+ * The signed read exists to dodge the public bucket domain's rate limit, not
+ * because the public domain is unavailable: the same bytes are readable there,
+ * unauthenticated, the whole time. On 2026-09-07 the R2 credential stopped
+ * verifying and this route answered `upstream_error` for every avatar, thumbnail
+ * and GLB on the site while `pub-….r2.dev` was serving those same keys with a
+ * 200. A credential fault now redirects there instead of 502ing the page.
+ *
+ * The redirect is deliberately uncacheable: the moment the credential is healthy
+ * again, traffic has to return to the signed path rather than sit pinned on the
+ * rate-limited domain by a cached hop.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const send = vi.fn();
+vi.mock('../api/_lib/r2.js', async (importOriginal) => {
+ const actual = await importOriginal();
+ return { ...actual, r2: { send: (...args) => send(...args) } };
+});
+
+const { default: handler } = await import('../api/cdn-object.js');
+
+const KEYS = ['S3_ENDPOINT', 'S3_BUCKET', 'S3_PUBLIC_DOMAIN', 'S3_ACCESS_KEY_ID', 'S3_SECRET_ACCESS_KEY'];
+let saved;
+
+function makeRes() {
+ return {
+ statusCode: 200,
+ headers: {},
+ body: '',
+ setHeader(k, v) {
+ this.headers[k.toLowerCase()] = String(v);
+ },
+ getHeader(k) {
+ return this.headers[k.toLowerCase()];
+ },
+ end(chunk) {
+ if (chunk) this.body += chunk;
+ this.ended = true;
+ return this;
+ },
+ };
+}
+
+const req = (key) => ({ method: 'GET', url: `/api/cdn-object?key=${key}`, headers: {}, query: { key } });
+
+function s3Error(name, message) {
+ const err = new Error(message);
+ err.name = name;
+ err.Code = name;
+ err.$metadata = { httpStatusCode: 403 };
+ return err;
+}
+
+beforeEach(() => {
+ saved = Object.fromEntries(KEYS.map((k) => [k, process.env[k]]));
+ process.env.S3_ENDPOINT = 'https://acct.r2.cloudflarestorage.com';
+ process.env.S3_BUCKET = 'three-ws';
+ process.env.S3_PUBLIC_DOMAIN = 'https://pub-example.r2.dev';
+ process.env.S3_ACCESS_KEY_ID = 'AKIAEXAMPLE';
+ process.env.S3_SECRET_ACCESS_KEY = 'secret';
+ send.mockReset();
+});
+
+afterEach(() => {
+ for (const k of KEYS) {
+ if (saved[k] === undefined) delete process.env[k];
+ else process.env[k] = saved[k];
+ }
+});
+
+describe('/cdn on a storage credential fault', () => {
+ it('redirects to the public bucket domain instead of 502ing the object', async () => {
+ send.mockRejectedValue(
+ s3Error(
+ 'SignatureDoesNotMatch',
+ 'The request signature we calculated does not match the signature you provided. Check your secret access key and signing method.',
+ ),
+ );
+ const res = makeRes();
+ await handler(req('thumb/abc.png'), res);
+ expect(res.statusCode).toBe(302);
+ expect(res.getHeader('location')).toBe('https://pub-example.r2.dev/thumb/abc.png');
+ });
+
+ it('never lets the fallback hop be cached', async () => {
+ send.mockRejectedValue(s3Error('InvalidAccessKeyId', 'The AWS Access Key Id you provided does not exist in our records.'));
+ const res = makeRes();
+ await handler(req('u/1/model.glb'), res);
+ expect(res.statusCode).toBe(302);
+ expect(res.getHeader('cache-control')).toBe('no-store');
+ });
+
+ it('still 404s a missing object rather than bouncing it to the public domain', async () => {
+ send.mockRejectedValue(s3Error('NoSuchKey', 'The specified key does not exist.'));
+ const res = makeRes();
+ await handler(req('thumb/gone.png'), res);
+ expect(res.statusCode).toBe(404);
+ });
+
+ it('keeps 502ing a fault that says nothing about our credentials', async () => {
+ const err = new Error('unexpected upstream state');
+ err.$metadata = { httpStatusCode: 500 };
+ send.mockRejectedValue(err);
+ const res = makeRes();
+ await handler(req('thumb/abc.png'), res);
+ expect(res.statusCode).toBe(502);
+ });
+});