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
/**
* Avatar snapshot capture + upload.
*
* Given a TalkScene-shaped renderer (anything that exposes
* `.renderer.domElement` as a WebGL canvas), grabs a JPEG poster of the
* current view and shuttles it through three.ws's existing thumbnail flow:
*
* POST /api/avatars/:id?action=presign-thumbnail → presigned PUT URL
* PUT <upload_url> → JPEG bytes
* POST /api/avatars/:id?action=auto-tag → sets thumbnail_key,
* runs Claude vision
* for tags + desc
*
* All three calls are real wires against the existing endpoints in
* api/avatars/_actions.js. The auto-tag step is best-effort: a failure
* there doesn't undo the thumbnail upload.
*
* Intended caller: avatar-edit.js after a successful Save. The render is
* driven through the already-mounted TalkScene so we don't pay for a second
* GLB load.
*/
import { log } from '../shared/log.js';
const JPEG_QUALITY = 0.86;
const MIN_BYTES = 2_000; // smaller than this means the canvas is blank
const MAX_BYTES = 2 * 1024 * 1024; // 2 MB ceiling (matches server-side cap)
/**
* Capture the current frame of the scene's WebGL canvas as a JPEG Blob.
*
* three.js renders with `preserveDrawingBuffer: false` by default, which
* means `canvas.toBlob` after the render-loop tick can hand back a blank
* frame. We force one render via the scene's renderer immediately before
* reading the pixels so the result is whatever's currently on screen.
*
* @param {{ renderer:any, scene:any, camera:any }} talkScene
* @returns {Promise<Blob>}
*/
export function captureSnapshotBlob(talkScene) {
if (!talkScene?.renderer || !talkScene.scene || !talkScene.camera) {
throw new Error('captureSnapshotBlob: scene/renderer/camera required');
}
// Force a synchronous render so toBlob sees a fresh frame even if the
// backing buffer was cleared by the previous tick.
talkScene.renderer.render(talkScene.scene, talkScene.camera);
const canvas = talkScene.renderer.domElement;
if (!canvas || typeof canvas.toBlob !== 'function') {
throw new Error('captureSnapshotBlob: renderer.domElement is not an HTMLCanvasElement');
}
return new Promise((resolve, reject) => {
canvas.toBlob(
(blob) => {
if (!blob) return reject(new Error('canvas.toBlob returned null'));
if (blob.size < MIN_BYTES) {
return reject(new Error('snapshot is suspiciously small — likely a blank frame'));
}
if (blob.size > MAX_BYTES) {
return reject(new Error(`snapshot too large: ${blob.size} > ${MAX_BYTES}`));
}
resolve(blob);
},
'image/jpeg',
JPEG_QUALITY,
);
});
}
/**
* End-to-end: capture → presign → PUT → auto-tag.
*
* Returns `{ ok: true, thumbKey, autoTagged }` on success. Throws on a
* presign or upload failure; logs and continues on auto-tag failure (the
* thumbnail itself is still in R2 and will get linked to the avatar by the
* next auto-tag call).
*
* @param {object} args
* @param {string} args.avatarId
* @param {{ renderer:any, scene:any, camera:any }} args.scene
* @returns {Promise<{ ok: true, thumbKey: string, autoTagged: object | null }>}
*/
export async function uploadAvatarSnapshot({ avatarId, scene }) {
if (!avatarId) throw new Error('uploadAvatarSnapshot: avatarId required');
const blob = await captureSnapshotBlob(scene);
// 1) Presign
const presignRes = await fetch(
`/api/avatars/${encodeURIComponent(avatarId)}?action=presign-thumbnail`,
{
method: 'POST',
credentials: 'include',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ avatar_id: avatarId, size_bytes: blob.size }),
},
);
if (!presignRes.ok) {
const j = await presignRes.json().catch(() => ({}));
throw new Error(j.error_description || `presign-thumbnail failed (${presignRes.status})`);
}
const { thumb_key, upload_url } = await presignRes.json();
if (!thumb_key || !upload_url) {
throw new Error('presign-thumbnail returned no upload target');
}
// 2) PUT bytes to R2
const putRes = await fetch(upload_url, {
method: 'PUT',
headers: { 'content-type': 'image/jpeg' },
body: blob,
});
if (!putRes.ok) {
throw new Error(`R2 upload failed (${putRes.status})`);
}
// 3) auto-tag — sets thumbnail_key on the avatar + best-effort tags via
// Claude vision. Failure here doesn't fail the snapshot.
let autoTagged = null;
try {
const tagRes = await fetch(
`/api/avatars/${encodeURIComponent(avatarId)}?action=auto-tag`,
{
method: 'POST',
credentials: 'include',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ avatar_id: avatarId, thumb_key }),
},
);
if (tagRes.ok) autoTagged = await tagRes.json();
} catch (err) {
log.warn('[snapshot] auto-tag failed, thumbnail still uploaded:', err?.message);
}
return { ok: true, thumbKey: thumb_key, autoTagged };
}
// Exported for tests + the rare caller that wants to inspect the constants.
export const SNAPSHOT_CONSTANTS = {
JPEG_QUALITY,
MIN_BYTES,
MAX_BYTES,
};