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
feat(share): unfurl avatar links with the avatar's own card and fix discover dead links
nirholas5dbf8a10b4a4
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex db4cd9f69..6e119bd83 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-19- **Put any agent on-chain from your AI assistant: the Metaplex Agent Registry MCP server**: A new npm package, @three-ws/metaplex-agent-mcp, lets any AI assistant deploy an agent on-chain on Solana the exact way the three.ws Genesis 333 shipped: it mints a Metaplex Core asset and registers its EIP-8004 agent identity, so the agent appears on metaplex.com/agents with its own built-in wallet. Agents can sign with their own key, and people can sign with Phantom, Solflare, or any Solana wallet, with a preview-first confirm step before anything is spent. Every royalty, creator, plugin, and metadata field is customizable, and devnet rehearsal is free. (`/deployments`) `[sdk, feature]`+- **Shared avatar links now unfurl with the avatar itself, and profile views finally count**: Paste an avatar link into X, Discord, Telegram, or Slack and the preview now shows that avatar's rendered image, name, and description instead of the generic site card. The profile page also reports a view each time someone opens it, so the view counts that rank search and explore results reflect real traffic at last. Discover cards for agents without a coin no longer point at a dead address, and the sitemap hands search engines the current agent page URLs directly. `[improvement, fix]`## 2026-08-18diff --git a/api/_lib/migrations/20260819010000_economy_wallet_registry.sql b/api/_lib/migrations/20260819010000_economy_wallet_registry.sqlnew file mode 100644index 000000000..ecb0067b6--- /dev/null+++ b/api/_lib/migrations/20260819010000_economy_wallet_registry.sql@@ -0,0 +1,57 @@+-- economy_wallet_registry: a durable log of every wallet the economy has ever used.+--+-- Until now the only record of a platform wallet was the env var holding its+-- secret plus the code-level spec in api/_lib/solana-signers.js. That is a+-- snapshot, not a log: rotating a signer overwrites the env var and the previous+-- address survives nowhere except an operator's memory and the chain. Anyone+-- reconciling revenue, auditing a settle, or answering "what paid this fee in+-- July" had nothing authoritative to read.+--+-- This table is that log. One row per (role, address). Rotating a role inserts a+-- fresh row and retires the old one, so the lineage is queryable forever and the+-- old address stays attributable long after its key leaves the environment.+--+-- Secret material NEVER lands here. The row records WHERE the secret lives+-- (`secret_location`, e.g. the Cloud Run env var name), never the secret.+--+-- Idempotent.++begin;++create table if not exists economy_wallet_registry (+ id uuid primary key default gen_random_uuid(),+ role text not null,+ address text not null,+ network text not null default 'solana-mainnet',+ status text not null default 'pending',+ env_var text,+ secret_location text,+ purpose text,+ rotated_from text,+ notes text,+ created_at timestamptz not null default now(),+ activated_at timestamptz,+ retired_at timestamptz,+ constraint economy_wallet_registry_status_chk+ check (status in ('pending', 'active', 'retired'))+);++-- The same address may serve two roles, and a role accumulates many addresses+-- over its life, but a given pair is recorded once.+create unique index if not exists economy_wallet_registry_role_address_uniq+ on economy_wallet_registry (role, address, network);++-- Exactly one live wallet per role per network. This is the constraint that+-- makes a half-finished rotation impossible to leave behind: activating a fresh+-- wallet fails loudly until its predecessor is retired.+create unique index if not exists economy_wallet_registry_one_active_uniq+ on economy_wallet_registry (role, network)+ where status = 'active';++create index if not exists economy_wallet_registry_address_idx+ on economy_wallet_registry (address);++create index if not exists economy_wallet_registry_status_idx+ on economy_wallet_registry (status, network);++commit;diff --git a/api/avatar-detail-og.js b/api/avatar-detail-og.jsnew file mode 100644index 000000000..ad38609b9--- /dev/null+++ b/api/avatar-detail-og.js@@ -0,0 +1,148 @@+/**+ * SSR OG page for avatar detail (/avatars/:id)+ * --------------------------------------------+ * GET /api/avatar-detail-og?id=<avatarId>+ *+ * Wired via vercel.json: when a social crawler hits /avatars/<uuid>,+ * a User-Agent "has" condition rewrites to this endpoint. Returns a minimal+ * HTML page with OG + Twitter Card + Farcaster Frame meta so shared avatar+ * links unfurl with the avatar's real name, description, and rendered card.+ *+ * Real browsers never reach this route - the rewrite only fires for known+ * bot User-Agents. Mirrors api/agent-detail-og.js.+ */++import { sql } from './_lib/db.js';+import { cors, method, wrap } from './_lib/http.js';+import { env } from './_lib/env.js';+import { isUuid } from './_lib/validate.js';++export default wrap(async (req, res) => {+ if (cors(req, res, { methods: 'GET,OPTIONS' })) return;+ // Crawler-only SSR read. Without this, a POST answered with the 302+ // passthrough instead of the 405 the advertised Allow set promises.+ if (!method(req, res, ['GET'])) return;++ const url = new URL(req.url, 'http://x');+ const avatarId = url.searchParams.get('id');+ const origin = env.APP_ORIGIN || 'https://three.ws';++ if (!avatarId || !isUuid(avatarId)) {+ return passthrough(res, origin);+ }++ let avatar;+ try {+ [avatar] = await sql`+ SELECT a.id, a.name, a.description, a.tags, a.model_category,+ u.username AS owner_username+ FROM avatars a+ LEFT JOIN users u ON u.id = a.owner_id AND u.deleted_at IS NULL+ WHERE a.id = ${avatarId} AND a.deleted_at IS NULL AND a.visibility = 'public'+ LIMIT 1+ `;+ } catch {+ return passthrough(res, origin);+ }++ if (!avatar) return passthrough(res, origin);++ const title = avatar.name || 'Avatar';+ const baseDesc =+ avatar.description || 'A 3D avatar on three.ws - rigged, animated, and ready to become an agent.';+ const tags = avatar.tags || [];+ const tagSuffix = tags.length ? ` Tags: ${tags.slice(0, 4).join(', ')}${tags.length > 4 ? '…' : ''}.` : '';+ const byline = avatar.owner_username ? ` By @${avatar.owner_username}.` : '';+ const desc = baseDesc + byline + tagSuffix;++ // Unfurl with the rendered avatar card (api/avatar-og.js) - the avatar's own+ // turntable render with name plate, from real data. The card endpoint falls+ // back to the brand image if it can't render.+ const ogImage = `${origin}/api/avatars/${encodeURIComponent(avatarId)}/og`;++ const pageUrl = `${origin}/avatars/${avatarId}`;++ res.statusCode = 200;+ res.setHeader('content-type', 'text/html; charset=utf-8');+ res.setHeader('cache-control', 'public, max-age=60, s-maxage=600, stale-while-revalidate=3600');+ res.end(renderHtml({ avatarId, title, desc, pageUrl, ogImage, origin }));+});++function passthrough(res, origin) {+ res.statusCode = 302;+ res.setHeader('location', `${origin}/gallery`);+ res.setHeader('cache-control', 'no-cache');+ res.end();+}++function renderHtml({ avatarId, title, desc, pageUrl, ogImage, origin }) {+ const t = esc(title);+ const d = esc(desc);+ const avatarUrl = `/avatars/${avatarId}`;+ return `<!doctype html>+<html lang="en">+<head>+ <meta charset="utf-8">+ <meta http-equiv="X-UA-Compatible" content="IE=edge">+ <title>${t} · three.ws</title>+ <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">+ <meta name="description" content="${d}">+ <meta name="theme-color" content="#06070a">++ <meta property="og:type" content="profile">+ <meta property="og:site_name" content="three.ws">+ <meta property="og:title" content="${t} · three.ws">+ <meta property="og:description" content="${d}">+ <meta property="og:url" content="${esc(pageUrl)}">+ <meta property="og:image" content="${esc(ogImage)}">+ <meta property="og:image:width" content="1200">+ <meta property="og:image:height" content="630">+ <meta property="og:image:alt" content="${t} on three.ws">++ <meta name="twitter:card" content="summary_large_image">+ <meta name="twitter:title" content="${t} · three.ws">+ <meta name="twitter:description" content="${d}">+ <meta name="twitter:image" content="${esc(ogImage)}">+ <meta name="twitter:creator" content="@trythreews">++ <meta property="fc:frame" content="vNext">+ <meta property="fc:frame:image" content="${esc(ogImage)}">+ <meta property="fc:frame:image:aspect_ratio" content="1.91:1">+ <meta property="fc:frame:button:1" content="Meet ${t}">+ <meta property="fc:frame:button:1:action" content="link">+ <meta property="fc:frame:button:1:target" content="${esc(pageUrl)}">++ <link rel="canonical" href="${esc(pageUrl)}">+ <link rel="shortcut icon" href="/favicon.ico">++ <style>+ html,body{margin:0;padding:0;background:#06070a;color:#e0e0e0;font-family:Inter,system-ui,sans-serif;height:100%}+ .shell{display:grid;place-items:center;min-height:100vh;text-align:center;padding:2rem;gap:1rem}+ .shell a{color:#e0e0e0;text-decoration:underline;text-underline-offset:3px}+ .spinner{width:28px;height:28px;border:2px solid rgba(255,255,255,0.1);border-top-color:rgba(255,255,255,0.6);border-radius:50%;animation:spin 0.9s linear infinite;margin:0 auto}+ @keyframes spin{to{transform:rotate(360deg)}}+ p{margin:0;color:rgba(255,255,255,0.5);font-size:14px}+ </style>+</head>+<body>+ <noscript>+ <div class="shell">+ <h1>${t}</h1>+ <p>${d}</p>+ <p><a href="${esc(pageUrl)}">View avatar</a> · <a href="${esc(origin)}/gallery">Browse the gallery</a></p>+ </div>+ </noscript>+ <div class="shell" aria-live="polite">+ <div class="spinner" aria-hidden="true"></div>+ <p>Loading ${t}…</p>+ </div>+ <script>(function(){window.location.replace(${JSON.stringify(avatarUrl)});})()</script>+</body>+</html>`;+}++function esc(s) {+ return String(s ?? '').replace(/[&<>"']/g, (c) =>+ ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[c],+ );+}diff --git a/api/sitemap/[type].js b/api/sitemap/[type].jsindex 65dd044cd..807838738 100644--- a/api/sitemap/[type].js+++ b/api/sitemap/[type].js@@ -163,7 +163,7 @@ async function agentsSitemap() {limit ${MAX_URLS}`;return rows.map((r) => ({- loc: `${ORIGIN}/agent/${r.id}`,+ loc: `${ORIGIN}/agents/${r.id}`,lastmod: fmtDate(r.updated_at || r.created_at),changefreq: 'weekly',priority: '0.7',diff --git a/data/changelog.json b/data/changelog.jsonindex e38ff940d..595aec8a1 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -24610,6 +24610,15 @@"feature"],"link": "/deployments"+ },+ {+ "date": "2026-08-19",+ "title": "Shared avatar links now unfurl with the avatar itself, and profile views finally count",+ "summary": "Paste an avatar link into X, Discord, Telegram, or Slack and the preview now shows that avatar's rendered image, name, and description instead of the generic site card. The profile page also reports a view each time someone opens it, so the view counts that rank search and explore results reflect real traffic at last. Discover cards for agents without a coin no longer point at a dead address, and the sitemap hands search engines the current agent page URLs directly.",+ "tags": [+ "improvement",+ "fix"+ ]}]}diff --git a/public/changelog.json b/public/changelog.jsonindex 1a3f0b83a..88f516672 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-19T01:09:35.724Z",+ "generated_at": "2026-08-19T01:16:16.983Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -17,6 +17,17 @@"feature"]},+ {+ "date": "2026-08-19",+ "type": "update",+ "title": "Shared avatar links now unfurl with the avatar itself, and profile views finally count",+ "summary": "Paste an avatar link into X, Discord, Telegram, or Slack and the preview now shows that avatar's rendered image, name, and description instead of the generic site card. The profile page also reports a view each time someone opens it, so the view counts that rank search and explore results reflect real traffic at last. Discover cards for agents without a coin no longer point at a dead address, and the sitemap hands search engines the current agent page URLs directly.",+ "link": null,+ "tags": [+ "improvement",+ "fix"+ ]+ },{"date": "2026-08-18","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex 791bf6c28..bb14a5aee 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -14,6 +14,14 @@<category>sdk</category><description>A new npm package, @three-ws/metaplex-agent-mcp, lets any AI assistant deploy an agent on-chain on Solana the exact way the three.ws Genesis 333 shipped: it mints a Metaplex Core asset and registers its EIP-8004 agent identity, so the agent appears on metaplex.com/agents with its own built-in wallet. Agents can sign with their own key, and people can sign with Phantom, Solflare, or any Solana wallet, with a preview-first confirm step before anything is spent. Every royalty, creator, plugin, and metadata field is customizable, and devnet rehearsal is free.</description></item>+ <item>+ <title>Shared avatar links now unfurl with the avatar itself, and profile views finally count</title>+ <link>https://three.ws/changelog</link>+ <guid isPermaLink="false">2026-08-19:Shared avatar links now unfurl with the avatar itself, and profile views finally count</guid>+ <pubDate>Wed, 19 Aug 2026 12:00:00 GMT</pubDate>+ <category>improvement</category>+ <description>Paste an avatar link into X, Discord, Telegram, or Slack and the preview now shows that avatar's rendered image, name, and description instead of the generic site card. The profile page also reports a view each time someone opens it, so the view counts that rank search and explore results reflect real traffic at last. Discover cards for agents without a coin no longer point at a dead address, and the sitemap hands search engines the current agent page URLs directly.</description>+ </item><item><title>Agents and avatars now open in the same studio page</title><link>https://three.ws/agents</link>diff --git a/public/discover/discover.js b/public/discover/discover.jsindex 6ec63b557..a22ba658e 100644--- a/public/discover/discover.js+++ b/public/discover/discover.js@@ -496,7 +496,7 @@ function renderOnchainCard(item) {.map((s) => `<span class="explore-svc">${escapeHtml(s.name)}</span>`).join('');- const detailUrl = `/discover/a/${item.chainId}/${item.agentId}`;+ const detailUrl = item.detailUrl || `/a/${item.chainId}/${item.agentId}`;card.innerHTML = `<a class="explore-card-thumb" href="${escapeAttr(detailUrl)}">@@ -607,7 +607,13 @@ function renderSolanaCard(item) {.map((s) => `<span class="explore-svc">${escapeHtml(s)}</span>`).join('');- const detailUrl = `/discover/a/sol/${encodeURIComponent(item.asset)}`;+ // The API's detailUrl is authoritative: three.ws agents get their canonical+ // /agents/:id page, external registry rows their /discover/a/sol/:asset+ // detail. The local fallback covers a cached bundle outliving the API, and+ // only when the item actually has an asset; a platform agent without a mint+ // otherwise produced a dead /discover/a/sol/undefined link.+ const detailUrl = item.detailUrl+ || (item.asset ? `/discover/a/sol/${encodeURIComponent(item.asset)}` : `/agents/${encodeURIComponent(item.agentId)}`);card.innerHTML = `<a class="explore-card-thumb" href="${escapeAttr(detailUrl)}">diff --git a/tests/api/avatar-detail-og.test.js b/tests/api/avatar-detail-og.test.jsnew file mode 100644index 000000000..d23d72759--- /dev/null+++ b/tests/api/avatar-detail-og.test.js@@ -0,0 +1,90 @@+// /avatars/:id serves a static shell, so social crawlers used to unfurl every+// shared avatar link with the generic site card. The bot-UA rewrite now lands+// them on api/avatar-detail-og.js, which must render the avatar's real name,+// description, and rendered-image URL - and must never leak anything for a+// private or missing avatar (302 passthrough instead).++import { describe, it, expect, beforeEach, vi } from 'vitest';+import { makeReq, makeRes } from '../_helpers/monetization.js';++const sqlState = { rows: [], calls: 0 };++vi.mock('../../api/_lib/db.js', () => {+ const sql = vi.fn(async () => {+ sqlState.calls += 1;+ return sqlState.rows;+ });+ return { sql, isDbUnavailableError: () => false, isDbCapacityError: () => false };+});++const { default: handler } = await import('../../api/avatar-detail-og.js');++const AVATAR_ID = '00000000-0000-4000-8000-000000000042';++async function invokeHtml(reqOpts) {+ const req = makeReq(reqOpts);+ const res = makeRes();+ await handler(req, res);+ return { status: res.statusCode, headers: res.headers, html: res.body };+}++beforeEach(() => {+ sqlState.rows = [];+ sqlState.calls = 0;+});++describe('avatar-detail-og', () => {+ it('rejects a non-GET method with 405 before touching the db', async () => {+ const { status } = await invokeHtml({+ method: 'POST',+ url: `/api/avatar-detail-og?id=${AVATAR_ID}`,+ });+ expect(status).toBe(405);+ expect(sqlState.calls).toBe(0);+ });++ it('302-passthroughs a malformed id without querying', async () => {+ const { status, headers } = await invokeHtml({+ url: '/api/avatar-detail-og?id=not-a-uuid',+ });+ expect(status).toBe(302);+ expect(headers.location).toMatch(/\/gallery$/);+ expect(sqlState.calls).toBe(0);+ });++ it('302-passthroughs an unknown avatar', async () => {+ const { status, headers } = await invokeHtml({+ url: `/api/avatar-detail-og?id=${AVATAR_ID}`,+ });+ expect(status).toBe(302);+ expect(headers.location).toMatch(/\/gallery$/);+ expect(sqlState.calls).toBe(1);+ });++ it('renders OG meta from the avatar record for a public avatar', async () => {+ sqlState.rows = [+ {+ id: AVATAR_ID,+ name: 'Nova <Scout>',+ description: 'A chrome scout.',+ tags: ['scout', 'chrome'],+ model_category: 'avatar',+ owner_username: 'nirholas',+ },+ ];+ const { status, headers, html } = await invokeHtml({+ url: `/api/avatar-detail-og?id=${AVATAR_ID}`,+ });+ expect(status).toBe(200);+ expect(headers['content-type']).toContain('text/html');+ // Name is escaped, description + byline + tags flow into og:description.+ expect(html).toContain('Nova <Scout>');+ expect(html).toContain('A chrome scout.');+ expect(html).toContain('@nirholas');+ expect(html).toContain(`/api/avatars/${AVATAR_ID}/og`);+ expect(html).toContain(`/avatars/${AVATAR_ID}`);+ expect(html).toContain('og:image');+ expect(html).toContain('twitter:card');+ expect(html).toMatch(/rel="canonical"/);+ });+});