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(compose): update the scene-compose doc and land the conversions follow-up

nirholas03a387f04f32
diff --git a/docs/compose.md b/docs/compose.md
index 4ccc993b6..f14837400 100644
--- a/docs/compose.md
+++ b/docs/compose.md
@@ -15,8 +15,10 @@ The page is a Three.js scene with PMREM image-based lighting, soft shadows, expo
- **Forge from text.** The prompt box posts to `/api/forge` with an optional intent (accessory, item, scene, creature, vehicle) that becomes the model's category. The studio polls the job to completion, streaming staged progress, then loads the resulting GLB into the scene. Meshopt-compressed models are decoded on load. Generation runs on the platform's real text-to-3D lanes; a queued job restarts the timeout window so waiting for a GPU never counts against the run budget.
- **Transform gizmos.** Select any object and translate, rotate, or scale it with `TransformControls`. Toggle world/local space, turn on 0.25-unit grid snapping, and lock proportional scale. Every drag and every numeric-field edit is one undoable step in a 50-deep undo/redo stack.
- **Bone attachment.** When a rigged avatar is in the scene, any non-avatar item's inspector gains an "Attach to Bone" control. The avatar's bones are grouped into readable regions (Head, Torso, Left/Right Arm, Left/Right Leg, Fingers L/R) with the raw bone names cleaned of rig prefixes (`mixamorig:`, `CC_Base_`, `rig_`). Attaching parents the item to that bone at the origin, so it rides the bone; detaching returns it to world space.
-- **Scene tooling.** Click-to-select raycasting, a hierarchy panel with per-object visibility and rename (double-click), camera presets (front/back/left/right/top/isometric, plus Blender-style numpad keys), F to frame the selection, Ctrl+D to duplicate, a live triangle-and-object counter, screenshot export, and toast notifications for every action. Geometry, materials, and textures are disposed on removal, so long sessions do not leak memory.
-- **Bring your own avatar.** Load an avatar by URL, browse your gallery through `/api/explore`, or arrive with `?avatar=<id>` (resolved via `/api/avatars/<id>`) or `?glb=<url>`. If the avatar ships animations, its first clip (typically idle) plays automatically through an `AnimationMixer`.
+- **Scene tooling.** Click-to-select raycasting, a hierarchy panel with per-object visibility and rename (double-click), camera presets (front/back/left/right/top/isometric, plus Blender-style numpad keys), F to frame the selection, Ctrl+D to duplicate, a live triangle-and-object counter, screenshot export, and toast notifications for every action. Geometry, materials, and textures are disposed once the step that removed them can no longer be undone (it falls off the 50-deep history), so long sessions do not leak memory and undo still restores the real object.
+- **Bring your own avatar.** Load an avatar by pasting a GLB URL *or* a three.ws avatar id (both go through the same `/api/avatars/<id>` lookup), browse the public 3D avatars through `/api/explore?source=avatar&only3d=1`, or arrive with `?avatar=<id>` or `?glb=<url>`. If the avatar ships animations, its first clip (typically idle) plays automatically through an `AnimationMixer`. A model that cannot be loaded leaves a persistent inline explanation on the start panel, not a toast that vanishes before you can read it.
+- **A gallery that is never empty.** The Recent Creations strip shows the models this browser has forged. A first-time visitor has none, so the strip falls back to the live community showcase (`/api/forge-gallery?scope=community`) under the heading "Fresh from the Forge": real, public models you can click straight into the scene without waiting on a generation. Both reads go out together, so the fallback costs nothing in time.
+- **Works on a phone.** Below 900px the scene panel (hierarchy, inspector, bone attachment) becomes a drawer behind the ☰ button in the toolbar rather than disappearing, and the toolbar scrolls horizontally instead of pushing the canvas off screen. Every control is a real button with a focus state; the camera menu, avatar picker and shortcuts panel trap focus and return it to their trigger on Escape.
### Export vs. save outfit
@@ -24,7 +26,7 @@ There are two ways out. **Export GLB** bakes every visible, non-bone-attached ob
## Walkthrough
-1. Open [/compose](https://three.ws/compose). Load an avatar: paste a model URL, click "Browse" to pick from your gallery, or skip and compose props only.
+1. Open [/compose](https://three.ws/compose). Load an avatar: paste a model URL or an avatar id, click "Browse my avatars" to pick from the public 3D avatars, or skip and compose props only.
2. Choose an intent chip (for example, Accessory), pick a suggested prompt or type your own ("neon visor"), and forge it. Watch the progress bar; the item drops into the scene when it is done.
3. Select the item. In the inspector, open "Attach to Bone", choose Head from the region-grouped list, and click Attach. The visor snaps onto the head.
4. Switch the gizmo to scale (press R) and size it to fit. Use grid snap and proportional lock as needed.
@@ -68,7 +70,8 @@ curl -X PATCH 'https://three.ws/api/avatars/<avatarId>' \
- **Bone-attached items are excluded from Export GLB.** Export bakes visible, world-space objects; items parented to a bone belong to the avatar and are saved through Save outfit instead.
- **Generation can take minutes.** Full-quality bakes legitimately run past ten minutes; the studio's ceiling sits above the slowest real generation, and a queued job restarts the wait window. A genuinely failed or timed-out job surfaces an actionable error.
- **Undo is 50 deep.** Transforms, adds, and removes are undoable (Ctrl+Z / Ctrl+Y); a full scene wipe is not a single undo step.
-- **Ownership is client-keyed.** Forge creations and the gallery are scoped to a per-browser client key stored in local storage, so your generations follow the browser without an account.
+- **Ownership is client-keyed.** Forge creations and the gallery are scoped to a per-browser client key stored in local storage, so your generations follow the browser without an account. Until you have forged anything, the strip shows the public community showcase instead.
+- **A locally dropped GLB cannot be saved as an outfit.** A file dragged onto the drop zone lives at a `blob:` URL that dies with the tab, so Save outfit refuses it by name and points you at Export GLB (or uploading it through [/forge](https://three.ws/forge)) rather than persisting a link that breaks on reload.
## Related
diff --git a/docs/cosmos.md b/docs/cosmos.md
index cfaecadad..c2094f064 100644
--- a/docs/cosmos.md
+++ b/docs/cosmos.md
@@ -14,6 +14,10 @@ Cosmos runs on NVIDIA's Cosmos World Foundation Model family. The endpoint (`api
The lane reuses the platform `NVIDIA_API_KEY` (the free NIM tier). When that key is absent, the lane reports itself unconfigured (503) and the page degrades gracefully: the avatar still stands on a designed, slowly shifting aurora backdrop instead of a blank void.
+NVIDIA retires a hosted preview model without retiring its gateway path: the route keeps answering, and only an authenticated submit reveals that the function behind it is gone for your account. So the submit walks the published `cosmos-predict` routes in order and only gives up when every rung is gone, at which point it answers `503 {"error":"lane_unavailable"}` and the page shows the same designed offline state as an unconfigured deployment. Setting `NVIDIA_COSMOS_INVOKE_URL` opts out of the chain and pins one endpoint (a specific model, or a self-hosted Cosmos NIM), which is the lever for pointing the lane at a live function without a code change. Confirm what an account can actually reach with `node scripts/verify-nvidia-cosmos.mjs`.
+
+Upstream detail never reaches the browser. The gateway phrases a retired model as `Function '<uuid>': Not found for account '<id>'`; that is operator diagnostics (it carries the account id), so it is logged server-side and the caller gets a sentence it can act on instead.
+
On the page (`src/cosmos.js`), the avatar is a Google `<model-viewer>` with a transparent background. Five humanoid avatars ship bundled for instant selection (Aria, Kai, Michelle, X-Bot, Mona), and you can bring your own. The generate flow is real async with no fake timers: submit to `POST /api/cosmos`, then poll `GET /api/cosmos?job=<id>` every four seconds (with a five-minute ceiling), driving a real elapsed-based progress state. When the clip is ready it plays on canplay as a looping backdrop behind the avatar, a regenerate control appears, and the clip is available to download.
## Walkthrough
@@ -72,7 +76,9 @@ else {
- **Prompt** must be 3 to 300 characters; an optional integer `seed` makes a render reproducible.
- **Render time** is roughly 60 to 120 seconds on the shared free tier; the client shows a real elapsed progress state and gives up after five minutes with a "try a simpler prompt" message.
- **Unconfigured (503)**: when `NVIDIA_API_KEY` is absent, the page keeps the avatar on a designed aurora backdrop and tells you generation is offline. No mock clip is ever shown.
+- **Lane unavailable (503, `lane_unavailable`)**: the key is present but NVIDIA has retired every hosted `cosmos-predict` route this account can reach. Same designed offline state, and deliberately no Retry button: the request cannot succeed until an operator points `NVIDIA_COSMOS_INVOKE_URL` at a live function.
- **Rate limited (429)** and **invalid key (401)** surface with honest messages and, where provided, a retry-after hint.
+- **Unplayable clip**: a durable URL that will not decode drops the stage out of its finished state and offers a retry, rather than leaving a "done" stage with nothing in it.
- Output is a durable MP4; the avatar is a standard GLB rendered with `<model-viewer>`.
- Rate limits are per client IP on the shared 3D generation buckets.
diff --git a/src/coin3d/main.js b/src/coin3d/main.js
index 90bc11eab..9f176f094 100644
--- a/src/coin3d/main.js
+++ b/src/coin3d/main.js
@@ -1003,7 +1003,15 @@ function gradLabel(s) {
}
function applyMarket(m) {
- if (!m) return;
+ const sparkSlot = document.getElementById('c3d-spark');
+ if (!m) {
+ // No candles for this mint (a brand-new coin, or the history provider is
+ // down). Say so once rather than pulsing a skeleton that never resolves.
+ if (sparkSlot?.querySelector('.c3d-spark-empty')) {
+ sparkSlot.innerHTML = '<p class="c3d-spark-none">No price history yet.</p>';
+ }
+ return;
+ }
const priceEl = document.getElementById('c3d-price');
if (priceEl) priceEl.textContent = fmtPrice(m.price);
const volEl = document.getElementById('c3d-vol');
diff --git a/src/constellation/main.js b/src/constellation/main.js
index 73af4833b..9d4fb8863 100644
--- a/src/constellation/main.js
+++ b/src/constellation/main.js
@@ -73,7 +73,6 @@ let signedIn = false; // resolved once at boot; gates the Granite analysis call
// ---- status / overlay helpers ---------------------------------------------
function setStatus(kind, html) {
- console.log("DBG setStatus", kind, String(html).slice(0,60));
statusEl.classList.remove('live', 'off', 'err');
if (kind) statusEl.classList.add(kind);
statusText.innerHTML = html;
@@ -344,7 +343,6 @@ function setHovered(node) {
function onPointerMove(e) {
updatePointer(e);
const node = pickNode();
- console.log("DBG move", e.clientX, e.clientY, node && node.token.symbol);
if (node !== hovered) {
setHovered(node);
keyboardFocused = false;
@@ -367,7 +365,6 @@ function onPointerUp(e) {
// star the visitor was aiming at, and the scene keeps auto-rotating under the
// cursor between the hover and the release.
const node = pickNode() || hovered;
- console.log("DBG up pick=", !!pickNode(), "hovered=", hovered && hovered.token.symbol, "px=", pointerPx.join(","));
if (node) { keyboardFocused = false; selectNode(node.mesh.userData.index, { fromKeyboard: false }); }
}
@@ -455,7 +452,6 @@ function formatPrice(p) {
return `$${p.toExponential(2)}`;
}
function closePanel() {
- console.log("DBG closePanel", new Error().stack);
if (!panel.classList.contains('open')) return;
panel.classList.remove('open');
panel.setAttribute('aria-hidden', 'true');
diff --git a/src/conversions.js b/src/conversions.js
index b20944026..c9e481eb4 100644
--- a/src/conversions.js
+++ b/src/conversions.js
@@ -239,7 +239,7 @@ function renderSeller(data) {
<span class="cv-skill">${esc(q.skill)}</span>
${q.exhausted ? `<span class="pill pill-out">${esc(plural(q.exhausted, 'buyer waiting', 'buyers waiting'))}</span>` : ''}
</div>
- <div class="cv-agent">on <a href="/agent/${esc(q.agentId)}">${esc(q.agentName)}</a>${timeClause('last activity', q.lastActivity)}</div>
+ <div class="cv-agent">on <a href="${esc(q.agentUrl || `/agents/${q.agentId}`)}">${esc(q.agentName)}</a>${timeClause('last activity', q.lastActivity)}</div>
<div class="cv-metrics">
<span class="cv-metric"><b>${esc(q.activeTrials)}</b> ${q.activeTrials === 1 ? 'trial' : 'trials'} running</span>
<span class="cv-metric${q.lastRun ? ' is-hot' : ''}"><b>${esc(q.lastRun)}</b> on last run</span>
diff --git a/src/game/coincommunities.css b/src/game/coincommunities.css
index c2bad8687..6921c5135 100644
--- a/src/game/coincommunities.css
+++ b/src/game/coincommunities.css
@@ -839,19 +839,68 @@ html[data-bg="transparent"] #cc-lobby {
}
/* coin grid */
-.cc-section-title { font-size: 11px; text-transform: uppercase; letter-spacing: 0.18em; color: var(--cc-faint); margin: 10px 2px 14px; }
-.cc-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(224px, 1fr)); gap: 14px; }
+.cc-feed-head {
+ display: flex; align-items: center; justify-content: space-between; gap: 16px;
+ flex-wrap: wrap; margin: 4px 2px 14px;
+}
+.cc-feed-title { display: flex; align-items: baseline; gap: 10px; }
+.cc-section-title { font-size: 11px; text-transform: uppercase; letter-spacing: 0.18em; color: var(--cc-faint); margin: 0; }
+.cc-feed-count { color: var(--cc-dim); font-size: 12px; font-variant-numeric: tabular-nums; }
+.cc-sorts { display: flex; align-items: center; gap: 6px; flex-wrap: wrap; }
+.cc-sort {
+ cursor: pointer; font: inherit; font-size: 12px; font-weight: 600; letter-spacing: 0.02em;
+ min-height: 34px; padding: 0 13px; color: var(--cc-dim);
+ background: transparent; border: 1px solid var(--cc-edge-soft); border-radius: 999px;
+ transition: color 0.14s ease, border-color 0.14s ease, background 0.14s ease;
+}
+.cc-sort:hover { color: var(--cc-text); border-color: var(--cc-edge); }
+.cc-sort:focus-visible { outline: 2px solid var(--cc-edge-hi); outline-offset: 2px; }
+.cc-sort.cc-on { color: var(--cc-ink); background: #fff; border-color: #fff; box-shadow: var(--cc-glow); }
+
+.cc-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(232px, 1fr)); gap: 16px; }
.cc-card {
background: var(--cc-panel); border: 1px solid var(--cc-edge); border-radius: var(--cc-radius);
overflow: hidden; cursor: pointer; position: relative;
- transition: transform 0.12s ease, border-color 0.14s ease, box-shadow 0.14s ease;
+ transition: transform 0.16s cubic-bezier(0.2, 0.7, 0.2, 1), border-color 0.14s ease, box-shadow 0.14s ease;
display: flex; flex-direction: column;
-}
-.cc-card:hover { transform: translateY(-3px); border-color: var(--cc-edge-hi); box-shadow: var(--cc-shadow); }
-.cc-card:focus-visible { outline: none; transform: translateY(-3px); border-color: #fff; box-shadow: 0 0 0 1px #fff, var(--cc-shadow); }
-.cc-card-img { aspect-ratio: 16/10; background: var(--cc-bg2) center/cover no-repeat; position: relative; filter: saturate(0.96) contrast(1.03); transition: filter 0.25s ease; }
-.cc-card:hover .cc-card-img { filter: saturate(1.12) contrast(1.05); }
+ animation: cc-card-in 0.34s cubic-bezier(0.2, 0.7, 0.2, 1) both;
+ animation-delay: var(--cc-in-delay, 0ms);
+}
+@keyframes cc-card-in { from { opacity: 0; transform: translateY(10px); } }
+@media (prefers-reduced-motion: reduce) { .cc-card { animation: none; } }
+.cc-card:hover { transform: translateY(-4px); border-color: var(--cc-edge-hi); box-shadow: var(--cc-shadow), 0 0 28px rgba(255, 255, 255, 0.06); }
+.cc-card:focus-visible { outline: none; transform: translateY(-4px); border-color: #fff; box-shadow: 0 0 0 1px #fff, var(--cc-shadow); }
+.cc-card-img {
+ aspect-ratio: 16/10; background: var(--cc-bg2) center/cover no-repeat; position: relative;
+ filter: saturate(0.96) contrast(1.03); overflow: hidden;
+ transition: filter 0.25s ease, transform 0.4s cubic-bezier(0.2, 0.7, 0.2, 1);
+}
+.cc-card:hover .cc-card-img { filter: saturate(1.12) contrast(1.05); transform: scale(1.03); }
+@media (prefers-reduced-motion: reduce) { .cc-card:hover .cc-card-img { transform: none; } }
.cc-card-img::after { content: ""; position: absolute; inset: 0; background: linear-gradient(180deg, transparent 45%, rgba(6, 6, 7, 0.92)); }
+/* Identity mark under the artwork: visible only where the art is missing or the
+ gateway failed, so a card is never a blank grey rectangle. */
+.cc-card-mono {
+ position: absolute; inset: 0; z-index: 0; display: grid; place-items: center;
+ font-size: 40px; font-weight: 800; letter-spacing: 0.02em;
+ color: rgba(255, 255, 255, 0.14); background: var(--cc-bg2);
+}
+/* Live headcount over the artwork. Hidden at zero (see _coinCard): an empty
+ world is normal and "0 inside" is noise, not information. */
+.cc-card-pop {
+ position: absolute; left: 9px; bottom: 9px; z-index: 1;
+ display: inline-flex; align-items: baseline; gap: 6px;
+ padding: 4px 10px; border-radius: 999px;
+ background: rgba(6, 6, 7, 0.72); border: 1px solid var(--cc-edge);
+ backdrop-filter: blur(6px);
+ font-size: 11px; font-weight: 600; color: var(--cc-text); letter-spacing: 0.01em;
+}
+.cc-card-pop-dot {
+ align-self: center; width: 6px; height: 6px; border-radius: 50%;
+ background: var(--cc-live); box-shadow: var(--cc-glow); animation: cc-blink 1.8s infinite;
+}
+.cc-card-pop-n { font-variant-numeric: tabular-nums; font-weight: 800; }
+.cc-card-pop-l { color: var(--cc-dim); font-weight: 500; }
.cc-card-live {
position: absolute; top: 9px; left: 9px; z-index: 1;
display: inline-flex; align-items: center; gap: 6px;
@@ -1426,8 +1475,9 @@ body.is-zen #cc-photo-btn:hover, body.is-zen #cc-photo-btn:focus-visible { opaci
.cc-ping[data-grade="ok"] { color: #d8c08a; }
.cc-ping[data-grade="bad"] { color: #d88a8a; }
-/* Name field in the lobby avatar bar. */
-.cc-name-row { display: flex; align-items: center; gap: 12px; margin-bottom: 14px; }
+/* Name field in the lobby avatar bar. Sits inline in the identity row now, so
+ the bottom margin that used to separate it from the picker below is gone. */
+.cc-name-row { display: flex; align-items: center; gap: 12px; }
.cc-name-label {
color: var(--cc-dim); font-size: 12px; letter-spacing: 0.18em;
text-transform: uppercase; flex: none;