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
// @three-ws/pose: a phrase in, a deterministic seed + the full Euler
// joint-rotation map for a rigged 3D avatar out.
//
// The zero-config path computes the pose LOCALLY: the pose_model algorithm is
// pure deterministic computation (token scoring + sha256) over the preset
// library this package bundles, so `poseSeed('wave hello')` needs no network,
// no key, and no payment, and returns the same result as the hosted tool.
//
// The hosted lane on the Streamable-HTTP MCP server at POST /api/mcp-3d stays
// available as an opt-in: pass `baseUrl`, `apiKey`, or `fetch` to createPose()
// and calls go over the wire as standard JSON-RPC `tools/call` requests.
// Keyless wire calls are x402-priced per call; OAuth principals (apiKey) run
// operator-funded. See README.md for the full reference.
import { createHttp, ThreeWsError } from './http.js';
import { resolvePoseLocal, resolvePresetLocal } from './local.js';
import { PRESETS, PRESET_GROUPS, getPresetById } from './pose-presets.js';
export { ThreeWsError, PaymentRequiredError, DEFAULT_BASE_URL } from './http.js';
export { PRESETS, PRESET_GROUPS } from './pose-presets.js';
const MCP_PATH = '/api/mcp-3d';
const TOOL_NAME = 'pose_model';
const PREVIEW_BASE = 'https://three.ws/pose';
const MAX_PROMPT = 500;
// The MCP server speaks Streamable HTTP: it may answer a tools/call with a
// JSON body or a single SSE frame, so we accept both content types.
const MCP_ACCEPT = 'application/json, text/event-stream';
/** Typed error for every @three-ws/pose failure. Mirrors ThreeWsError. */
export class PoseError extends ThreeWsError {
constructor(message, opts = {}) {
super(message, opts);
this.name = 'PoseError';
}
}
/**
* Create a Pose client. With no transport options this resolves poses locally
* (no network, no key, no payment). Passing `baseUrl`, `apiKey`, or `fetch`
* switches the client to the hosted pose_model tool on /api/mcp-3d: use that
* to reuse configuration (a payment-aware fetch for the x402 lane, an OAuth
* key for operator-funded calls, a custom origin) across many calls.
*
* @param {object} [options]
* @param {string} [options.baseUrl] API origin (default https://three.ws). Selects the hosted lane.
* @param {typeof fetch} [options.fetch] fetch implementation. Selects the hosted lane.
* @param {string} [options.apiKey] OAuth bearer, runs hosted calls operator-funded. Selects the hosted lane.
* @param {string} [options.previewBase] base URL for the returned previewUrl (local or hosted).
* @param {Record<string,string>} [options.headers]
*/
export function createPose(options = {}) {
const remote = Boolean(options.baseUrl || options.apiKey || options.fetch);
const request = remote ? createHttp(options) : null;
const previewBase = stripTrailingSlash(options.previewBase || PREVIEW_BASE);
let nextId = 1;
/**
* Resolve a natural-language pose description to a deterministic seed and the
* full joint-rotation map. `prompt` is a string, 1–500 characters.
*/
async function poseSeed(prompt, opts = {}) {
const text = typeof prompt === 'string' ? prompt : '';
if (text.length < 1 || text.length > MAX_PROMPT) {
throw new PoseError(
`poseSeed() needs a prompt of 1–${MAX_PROMPT} characters.`,
{ code: 'invalid_prompt' },
);
}
return remote ? callPoseModel(text, opts) : resolveLocally(text, opts);
}
/**
* Skip selection and resolve a specific preset by id. Seeds with the preset
* id as the prompt, so the same preset always returns the same seed.
*/
async function presetPose(presetId, opts = {}) {
if (!presetId || typeof presetId !== 'string' || !getPresetById(presetId)) {
const known = PRESETS.map((p) => p.id).join(', ');
throw new PoseError(
`Unknown preset "${presetId}". Known presets: ${known}.`,
{ code: 'invalid_prompt' },
);
}
if (remote) return callPoseModel(presetId, opts);
throwIfAborted(opts);
return shape(await resolvePresetLocal(presetId), previewBase);
}
// The zero-config lane: run the pose_model algorithm in-process over the
// bundled preset library, then normalize through the same shape() step the
// wire response goes through, so both lanes return identical PoseResults.
async function resolveLocally(prompt, opts) {
throwIfAborted(opts);
return shape(await resolvePoseLocal(prompt), previewBase);
}
// One JSON-RPC tools/call to pose_model, shaped into a PoseResult.
async function callPoseModel(prompt, opts) {
const envelope = {
jsonrpc: '2.0',
id: nextId++,
method: 'tools/call',
params: { name: TOOL_NAME, arguments: { prompt } },
};
const payload = await request(MCP_PATH, {
method: 'POST',
headers: { accept: MCP_ACCEPT, ...(opts.headers || {}) },
body: envelope,
signal: opts.signal,
});
// JSON-RPC envelope: a tool error rides in `error`; a tool result that
// itself failed rides in `result.isError`.
if (payload?.error) {
throw new PoseError(payload.error.message || 'The pose tool returned an error.', {
code: 'tool_error',
detail: payload.error.data ?? null,
body: payload,
});
}
const result = payload?.result;
if (result?.isError) {
const msg = result.content?.find((c) => c.type === 'text')?.text || 'The pose tool returned an error.';
throw new PoseError(msg, { code: 'tool_error', body: payload });
}
const sc = result?.structuredContent;
if (!sc || typeof sc !== 'object') {
throw new PoseError('Unexpected empty response from the pose tool.', {
code: 'tool_error',
body: payload,
});
}
return shape(sc, previewBase);
}
return { poseSeed, presetPose, listPresetGroups };
}
// A module-level default client for the zero-config path: `import { poseSeed }`.
let shared = null;
function defaultClient() {
return (shared ||= createPose());
}
/** Resolve a phrase to a deterministic seed + full joint-rotation map. */
export function poseSeed(prompt, opts) {
return defaultClient().poseSeed(prompt, opts);
}
/** Resolve a specific preset by id (skips prompt selection). */
export function presetPose(presetId, opts) {
return defaultClient().presetPose(presetId, opts);
}
/**
* The four pose groups, returned synchronously for menu scaffolding:
* ['Standing', 'Action', 'Sitting & Floor', 'Expressive']. From the real
* in-repo preset library — no network call.
*/
export function listPresetGroups() {
return [...PRESET_GROUPS];
}
// Normalize the tool's snake_case structuredContent into the camelCase
// PoseResult, rebasing the preview URL onto the configured previewBase and
// keeping a `.raw` escape hatch.
function shape(sc, previewBase) {
const presetId = sc.preset_id ?? null;
const seed = sc.seed ?? null;
const previewUrl =
presetId && seed
? `${previewBase}?seed=${encodeURIComponent(seed)}&preset=${encodeURIComponent(presetId)}`
: (sc.preview_url ?? null);
return {
seed,
presetId,
presetLabel: sc.preset_label ?? null,
group: sc.group ?? null,
parameters: sc.parameters ?? {},
previewUrl,
match: sc.match ?? null,
groups: Array.isArray(sc.groups) ? sc.groups : [...PRESET_GROUPS],
raw: sc,
};
}
function stripTrailingSlash(s) {
return String(s).replace(/\/+$/, '');
}
function throwIfAborted(opts) {
if (opts?.signal?.aborted) {
const e = new Error('The operation was aborted.');
e.name = 'AbortError';
throw e;
}
}