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(motion): serve the sentence-to-motion authoring lane over HTTP
nirholasd5c19fd41abc
diff --git a/api/_lib/rate-limit.js b/api/_lib/rate-limit.jsindex 0a1ecc81d..27c741955 100644--- a/api/_lib/rate-limit.js+++ b/api/_lib/rate-limit.js@@ -1910,6 +1910,14 @@ export const limits = {// go through the x402 lane and are limited by their own cost.knockSendIp: (ip) =>getLimiter('knock:send:ip', { limit: 8, window: '1 h' }).limit(ip),+ // Motion synthesis (/api/motion). Compiling a score is pure arithmetic and+ // deterministic, so it gets a generous local bucket an editor can type into.+ // Authoring one from a sentence can reach a language model, so it is metered+ // the way every other model-backed surface here is.+ motionCompile: (key) =>+ getLimiter('motion:compile', { limit: 240, window: '1 m', local: true }).limit(key),+ motionAuthor: (key) =>+ getLimiter('motion:author', { limit: 60, window: '10 m' }).limit(key),// Funnel tracking (opened/returned) — high local ceiling; one ping per// notification interaction, deduped server-side anyway.notifTrack: (userId) =>diff --git a/api/companion/checkout.js b/api/companion/checkout.jsindex c98d94e8a..e3382b1b9 100644--- a/api/companion/checkout.js+++ b/api/companion/checkout.js@@ -108,7 +108,7 @@ export default wrap(async function handler(req, res) {// Authorization header rather than a cookie for that caller, and it writes// nothing: there is no state for a hostile page to change by calling it.if (cors(req, res, { origins: '*', methods: 'POST,OPTIONS' })) return;- if (method(req, res, ['POST'])) return;+ if (!method(req, res, ['POST'])) return;const user = await callerFor(req, res);if (!user) {diff --git a/api/motion.js b/api/motion.jsnew file mode 100644index 000000000..b0a4ba404--- /dev/null+++ b/api/motion.js@@ -0,0 +1,149 @@+// Motion API: a sentence in, a real animation out.+// ---------------------------------------------------------------------------+// GET /api/motion?prompt=<text>[&loop=1][&effort=<name>][&lane=auto|fast|model]+// Compile a movement. Returns the clip, the Motion Score that produced+// it, and which lane wrote the score. Public.+//+// GET /api/motion?capabilities=1+// The score schema, the vocabulary, and the actions the model-free lane+// knows. This is what a tool definition or an editor is built from.+//+// POST /api/motion { score, name?, loop?, idle?, rootMotion?, fingers? }+// Compile a Motion Score directly, with no model involved. This is the+// path an editor uses: change a beat, recompile, see it move. Public.+//+// Nothing here is stored and nothing is generated twice: the compiler is+// deterministic, so the same prompt returns the same clip, and the response+// carries the score so a caller can edit and recompile without asking again.++import {+ compileScore,+ describeScore,+ motionCapabilities,+ validateScore,+} from '@three-ws/motion';+import { cors, json, error, method, wrap, readJson, rateLimited } from './_lib/http.js';+import { limits, clientIp } from './_lib/rate-limit.js';+import { getSessionUser } from './_lib/auth.js';+import { authorScore } from './_lib/motion-author.js';++export const maxDuration = 60;++/** Longest prompt worth reading: a movement description, not a screenplay. */+const MAX_PROMPT = 400;++const LANES = new Set(['auto', 'fast', 'model']);++export default wrap(async (req, res) => {+ if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*', credentials: true })) return;+ if (!method(req, res, ['GET', 'POST'])) return;++ const url = new URL(req.url, `http://${req.headers.host || 'x'}`);+ if (req.method === 'GET' && url.searchParams.has('capabilities')) {+ res.setHeader('cache-control', 'public, max-age=300, s-maxage=3600');+ return json(res, 200, motionCapabilities());+ }++ let userId = null;+ try { userId = (await getSessionUser(req))?.id ?? null; } catch { userId = null; }++ if (req.method === 'POST') return compileDirect(req, res, userId);+ return compileFromPrompt(req, res, url, userId);+});++async function compileFromPrompt(req, res, url, userId) {+ const prompt = (url.searchParams.get('prompt') || '').trim().slice(0, MAX_PROMPT);+ if (!prompt) {+ return error(res, 400, 'missing_prompt', 'Describe the movement, for example prompt=wave hello twice.');+ }++ const lane = LANES.has(url.searchParams.get('lane')) ? url.searchParams.get('lane') : 'auto';+ // Only the model lane costs anything, so only the model lane is metered+ // against the slower bucket; recognizing "wave" is free and should feel it.+ const rl = lane === 'fast'+ ? await limits.publicIp(clientIp(req))+ : await limits.motionAuthor(userId || clientIp(req));+ if (!rl.success) return rateLimited(res, rl);++ const options = readOptions(url.searchParams);++ let authored;+ try {+ authored = await authorScore(prompt, { ...options, lane, prefer: lane, userId });+ } catch (err) {+ return error(+ res,+ err.status ?? 500,+ err.code ?? 'author_failed',+ err.message,+ err.actions ? { actions: err.actions } : undefined,+ );+ }++ let compiled;+ try {+ compiled = compileScore(authored.score, options);+ } catch (err) {+ // The author lane validates before returning, so reaching here means the+ // solver disagreed with the validator, which is a bug worth naming rather+ // than a bad prompt.+ return error(res, 500, 'compile_failed', `The score validated but would not compile: ${err.message}`);+ }++ // Deterministic output: the same prompt is the same bytes, so the edge can+ // hold it. Short enough that a vocabulary change ships within the hour.+ res.setHeader('cache-control', 'public, max-age=600, s-maxage=3600');+ return json(res, 200, respond(compiled, { ...authored, prompt }));+}++async function compileDirect(req, res, userId) {+ const rl = await limits.motionCompile(userId || clientIp(req));+ if (!rl.success) return rateLimited(res, rl);++ const body = await readJson(req);+ if (!body || typeof body !== 'object') return error(res, 400, 'invalid_body', 'Send a JSON object with a score.');++ const check = validateScore(body.score);+ if (!check.ok) {+ return error(res, 400, 'invalid_score', check.error.message, { path: check.error.path });+ }++ const options = readOptions(new URLSearchParams(), body);+ const compiled = compileScore(body.score, { ...options, name: body.name });+ return json(res, 200, respond(compiled, { lane: 'direct', matched: null, provider: null, model: null, note: null, prompt: null }));+}++function readOptions(params, body = {}) {+ const flag = (name, fallback) => {+ if (body[name] != null) return body[name] !== false;+ const raw = params.get(name.toLowerCase());+ if (raw == null) return fallback;+ return raw !== '0' && raw !== 'false';+ };+ return {+ loop: flag('loop', false),+ idle: flag('idle', true),+ rootMotion: flag('rootMotion', true),+ fingers: flag('fingers', true),+ effort: body.effort ?? params.get('effort') ?? undefined,+ };+}++function respond(compiled, authored) {+ return {+ clip: compiled.clip,+ score: compiled.score,+ summary: describeScore(compiled.score),+ duration: compiled.clip.duration,+ tracks: compiled.clip.tracks.length,+ warnings: compiled.warnings,+ source: {+ lane: authored.lane,+ matched: authored.matched,+ provider: authored.provider,+ model: authored.model,+ note: authored.note,+ },+ prompt: authored.prompt ?? null,+ };+}diff --git a/herald-sdk/src/index.js b/herald-sdk/src/index.jsindex 24009052e..7eaab4e6b 100644--- a/herald-sdk/src/index.js+++ b/herald-sdk/src/index.js@@ -81,6 +81,9 @@ const PRUNE_EVERY = 20;* @param {(m: object) => Array<object>} [options.actionsFor] extra buttons on a* delivery; the default gives "Open" for a message with a url.* @param {object} [options.companion] a live @three-ws/walk control to reuse+ * @param {object} [options.avatarOptions] forwarded to createAvatarPresenter+ * (`walkModule`, `companionOptions`), for pages that serve their own build of+ * the companion rather than installing the package* @param {() => number} [options.now] clock seam, for tests*/export function createHerald(options = {}) {@@ -104,7 +107,9 @@ export function createHerald(options = {}) {let sincePrune = 0;const presenters = {- avatar: opts.presenters?.avatar || createAvatarPresenter({ companion: opts.companion }),+ avatar:+ opts.presenters?.avatar ||+ createAvatarPresenter({ companion: opts.companion, ...(opts.avatarOptions || {}) }),card: opts.presenters?.card || createCardPresenter(),};const voice =diff --git a/packages/portal/src/layout.js b/packages/portal/src/layout.jsindex bb98ab228..d5eab250a 100644--- a/packages/portal/src/layout.js+++ b/packages/portal/src/layout.js@@ -278,8 +278,13 @@ export function doorSlot(building, index, count) {const withinFace = index % perFace;const spread = count <= 1 ? 0 : (withinFace - (Math.min(perFace, count) - 1) / 2) * (building.w * 0.42);const yaw = building.rot + (face * Math.PI) / 2;- const half = (face % 2 === 0 ? building.d : building.w) / 2;- const along = face % 2 === 0 ? building.w : building.d;+ // `half` is the wall's distance from the centre ALONG the face normal, and+ // `along` is the wall's width across it. Faces 0 and 2 look down the+ // building's x axis, so they use w; faces 1 and 3 look down z and use d.+ // Swapping the two puts a door inside a non-square building, which is exactly+ // what tests/portal-layout.test.js checks for.+ const half = (face % 2 === 0 ? building.w : building.d) / 2;+ const along = face % 2 === 0 ? building.d : building.w;const offset = count <= 1 ? 0 : clamp(spread, -along * 0.35, along * 0.35);return {x: building.x + Math.cos(yaw) * half + Math.cos(yaw + Math.PI / 2) * offset,diff --git a/src/herald-embed.js b/src/herald-embed.jsindex af88eeb8b..c108e7762 100644--- a/src/herald-embed.js+++ b/src/herald-embed.js@@ -16,6 +16,12 @@import { createHerald } from '../herald-sdk/src/index.js';+// three.ws serves the companion at a stable, unhashed path (vite.config.js), so+// a visitor who never turned it on still gets a body for a delivery: the module+// installs `window.__walkCompanion` on import and the presenter picks it up.+// Exported so a page building its own herald passes the same thing.+export const WALK_ON_THREE_WS = { walkModule: '/walk-companion.js' };+export {createHerald,createAvatarPresenter,@@ -45,7 +51,7 @@ export default createHerald;// its own herald never pays for a second one.let ambient = null;function ensureAmbient() {- if (!ambient) ambient = createHerald({ voice: 'auto' });+ if (!ambient) ambient = createHerald({ voice: 'auto', avatarOptions: WALK_ON_THREE_WS });return ambient;}diff --git a/src/herald-page.js b/src/herald-page.jsindex 08c85669d..e989f641a 100644--- a/src/herald-page.js+++ b/src/herald-page.js@@ -56,6 +56,9 @@ function build() {herald = createHerald({presenter: els.presenter.value,+ // A visitor who never switched the companion on still gets a body: the+ // site serves it at /walk-companion.js.+ avatarOptions: { walkModule: '/walk-companion.js' },voice: els.voice.checked ? 'always' : 'off',rules: {minImportance: Number(els.floor.value),