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.

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.js
index 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.js
index 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.js
new file mode 100644
index 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.js
index 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.js
index 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.js
index 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.js
index 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),