summer-engine 3.1.0 → 3.2.0

package/dist/core/capabilities/inspect-resource.js

@@ -0,0 +1,376 @@
+/**
+ * inspect-resource — ONE implementation of `summer_inspect_resource` for both
+ * faces (src/mcp/tools/scene-tools.ts and tool-dispatch.ts).
+ *
+ * The engine's state:resource (StateProvider::resource_properties_state)
+ * reads a resource a NODE holds: it takes nodePath + property and answers
+ * "missing nodePath or property" to anything else. The tool used to send it
+ * only `path`, so every call failed, on a mesh .res or a .glb alike. Two forms
+ * now:
+ *
+ *   path               a resource FILE, loaded in the editor by a read-only
+ *                      RunSceneScript probe (undo none, no checkpoint; the
+ *                      path travels as base64 data, never as source):
+ *                        Mesh         AABB, surfaces (primitive, vertex and
+ *                                     index counts, attributes, triangles,
+ *                                     material), materials, blend shapes
+ *                        PackedScene  node count, the first nodes with their
+ *                                     types, instanced scenes and meshes, and
+ *                                     a pointer to summer_inspect_asset
+ *                        Texture2D    size
+ *                        every other  editor properties that differ from the
+ *                                     class default (defaults are counted)
+ *   nodePath+property  the engine endpoint, for a resource a node of the
+ *                      active scene holds (e.g. Floor + mesh).
+ */
+import { z } from "zod";
+import { missingEngineOpResult } from "../capability-skew.js";
+import { ToolInputError } from "../tool-errors.js";
+import { asRecord } from "../util/json.js";
+import { extractOpError, withOldEngineHint } from "./engine-receipt.js";
+import { buildRunSceneScriptOp } from "./scene-script.js";
+import { encodeScriptArgs } from "./placement-script.js";
+import { fitToBudget } from "./placement.js";
+export const INSPECT_RESOURCE_ARGS_TOKEN = "__SUMMER_RESOURCE_ARGS__";
+export const INSPECT_RESOURCE_FALLBACK = "read a text resource (.tres/.tscn) with summer_read_file, or pass nodePath + property for a resource a node of the open scene holds";
+const RES_FILE = /^res:\/\/[^\u0000-\u001f]+$/;
+// Mirrors library/tools/inspect-resource/resource.yaml input_schema (parity-tested).
+export const inspectResourceInputShape = {
+    path: z
+        .string()
+        .trim()
+        .min(1)
+        .max(512)
+        .refine((value) => RES_FILE.test(value) && !value.includes(".."), "path must be a res:// resource file without '..'")
+        .optional()
+        .describe("A resource FILE: 'res://materials/ground.tres', a mesh 'res://kit/meshes/wall_01.res', a texture, a shape, or a scene/model 'res://models/player.glb'. Loaded read-only in the editor."),
+    nodePath: z
+        .string()
+        .trim()
+        .min(1)
+        .max(256)
+        .optional()
+        .describe("With property: a node of the ACTIVE scene tab whose resource to read, e.g. 'Floor'. Do not combine with path."),
+    property: z
+        .string()
+        .trim()
+        .min(1)
+        .max(128)
+        .optional()
+        .describe("With nodePath: the node property holding the resource, e.g. 'mesh', 'material_override', 'shape', 'environment'."),
+};
+export const inspectResourceInputSchema = z.object(inspectResourceInputShape).strict();
+const TOOL = "summer_inspect_resource";
+const RESULT_TARGET_BYTES = 6000;
+function fail(failureReason, error, extra = {}) {
+    return { ok: false, tool: TOOL, failure_reason: failureReason, error, ...extra };
+}
+export async function inspectResource(client, args) {
+    const hasNodeForm = args.nodePath !== undefined || args.property !== undefined;
+    if (args.path !== undefined && hasNodeForm) {
+        throw new ToolInputError("Pass either path (a resource file) or nodePath + property (a resource a node holds), not both.");
+    }
+    if (args.path !== undefined)
+        return inspectResourceFile(client, args.path);
+    if (args.nodePath !== undefined && args.property !== undefined) {
+        return client.inspectNodeResource(args.nodePath, args.property);
+    }
+    if (hasNodeForm)
+        throw new ToolInputError("nodePath and property go together, e.g. nodePath 'Floor' + property 'mesh'.");
+    throw new ToolInputError("Pass path (a resource file, e.g. 'res://materials/ground.tres' or a mesh 'res://kit/meshes/wall_01.res'), or nodePath + property (e.g. 'Floor' + 'mesh').");
+}
+/** Load a resource file read-only in the editor and describe it compactly. */
+export async function inspectResourceFile(client, path) {
+    const missing = missingEngineOpResult(client, "RunSceneScript", INSPECT_RESOURCE_FALLBACK);
+    if (missing)
+        return { ...missing, tool: TOOL };
+    const { op, timeoutMs } = buildRunSceneScriptOp({
+        source: buildInspectResourceScript({ path }),
+        max_seconds: 20,
+        checkpoint: false,
+        undo: "none",
+    });
+    const receipt = await client.executeIdentityBoundOps([op], undefined, timeoutMs);
+    const hinted = asRecord(withOldEngineHint(receipt, "RunSceneScript", INSPECT_RESOURCE_FALLBACK));
+    if (hinted?.failure_reason === "engine_lacks_op")
+        return fail("engine_lacks_op", String(hinted.error), { op: "RunSceneScript" });
+    const envelope = asRecord(receipt) ?? {};
+    const results = Array.isArray(envelope.results) ? envelope.results : [];
+    const entry = asRecord(results.find((item) => asRecord(item)?.op === "RunSceneScript") ?? results[0]);
+    const envelopeError = extractOpError(receipt);
+    if (!entry || entry.ok === false || envelopeError) {
+        return fail("resource_probe_failed", `The resource probe (RunSceneScript) failed: ${String(entry?.error ?? envelopeError ?? "no result")}`);
+    }
+    const result = asRecord(entry.result);
+    if (!result)
+        return fail("resource_probe_failed", "The resource probe ran but returned no result.");
+    if (result.ok !== true) {
+        return fail(typeof result.failure_reason === "string" ? result.failure_reason : "resource_probe_failed", typeof result.error === "string" ? result.error : "The resource probe reported a failure.");
+    }
+    const { ok: _ok, ...rest } = result;
+    const out = { ok: true, tool: TOOL, source: "file", ...rest, evidence: "resource_loader" };
+    const mesh = asRecord(out.mesh);
+    const scene = asRecord(out.scene);
+    if (mesh)
+        out.mesh = fitToBudget(mesh, ["surfaces", "materials"], RESULT_TARGET_BYTES - 600);
+    if (scene)
+        out.scene = fitToBudget(scene, ["nodes", "meshes"], RESULT_TARGET_BYTES - 600);
+    return trimProps(out, RESULT_TARGET_BYTES);
+}
+function bytes(value) {
+    return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+/** Drop trailing props until the result fits; declare the cut. */
+function trimProps(out, target) {
+    const props = asRecord(out.props);
+    if (!props || bytes(out) <= target)
+        return out;
+    const keys = Object.keys(props);
+    const kept = (n) => Object.fromEntries(keys.slice(0, n).map((key) => [key, props[key]]));
+    let n = keys.length;
+    while (n > 0 && bytes({ ...out, props: kept(n) }) > target)
+        n--;
+    return { ...out, props: kept(n), truncated: { ...(asRecord(out.truncated) ?? {}), props: { shown: n, total: keys.length } } };
+}
+export function buildInspectResourceScript(args) {
+    return INSPECT_RESOURCE_PROBE_SOURCE.split(INSPECT_RESOURCE_ARGS_TOKEN).join(`"${encodeScriptArgs(args)}"`);
+}
+/** The probe source with its placeholder, for tests. */
+export function inspectResourceProbeTemplate() {
+    return INSPECT_RESOURCE_PROBE_SOURCE;
+}
+// Tabs are significant: GDScript indentation. String.raw keeps backslashes
+// literal; the source never contains a template placeholder.
+const INSPECT_RESOURCE_PROBE_SOURCE = String.raw `@tool
+extends RefCounted
+
+const ARGS_B64 = __SUMMER_RESOURCE_ARGS__
+const MAX_SURFACES = 48
+const MAX_PROPS = 80
+const MAX_NODES = 40
+const MAX_SCENE_MESHES = 24
+const MAX_VALUE_CHARS = 160
+const PRIMITIVES = ["points", "lines", "line_strip", "triangles", "triangle_strip"]
+
+
+func run(_ctx):
+	var args = JSON.parse_string(Marshalls.base64_to_utf8(ARGS_B64))
+	if typeof(args) != TYPE_DICTIONARY:
+		return _fail("bad_args", "resource probe arguments did not parse")
+	var path = String(args.get("path", ""))
+	if not ResourceLoader.exists(path):
+		return _fail("resource_not_found", "No resource at " + path)
+	var res = ResourceLoader.load(path)
+	if res == null:
+		return _fail("resource_load_failed", "ResourceLoader could not load " + path)
+	var out = {"ok": true, "path": path, "resource_type": res.get_class()}
+	if String(res.resource_name) != "":
+		out["resource_name"] = String(res.resource_name)
+	if res.get_script() != null:
+		out["script"] = String(res.get_script().resource_path)
+	if res is Mesh:
+		out["mesh"] = _mesh(res)
+	elif res is PackedScene:
+		out["scene"] = _scene(res)
+		out["next"] = "summer_inspect_asset measures this scene (AABB, origin, planes, ports, anchors, collision); summer_inspect_resource on one of its mesh paths lists that mesh's surfaces and materials"
+		return out
+	elif res is Texture2D:
+		out["texture"] = {"width": res.get_width(), "height": res.get_height()}
+	var pr = _props(res)
+	out["props"] = pr["props"]
+	out["props_at_default"] = pr["defaults"]
+	if pr["cut"] > 0:
+		out["props_cut"] = pr["cut"]
+	return out
+
+
+func _fail(reason, message):
+	return {"ok": false, "failure_reason": reason, "error": message}
+
+
+func _v3(v):
+	return [snappedf(v.x, 0.0001), snappedf(v.y, 0.0001), snappedf(v.z, 0.0001)]
+
+
+func _ref(r):
+	if r == null:
+		return null
+	var rec = {"class": r.get_class()}
+	var p = String(r.resource_path)
+	if p != "" and not p.contains("::"):
+		rec["path"] = p
+	else:
+		rec["embedded"] = true
+	if String(r.resource_name) != "":
+		rec["name"] = String(r.resource_name)
+	return rec
+
+
+func _material(mat):
+	if mat == null:
+		return null
+	var rec = _ref(mat)
+	if mat is BaseMaterial3D:
+		rec["albedo_color"] = var_to_str(mat.albedo_color)
+		if mat.albedo_texture != null:
+			rec["albedo_texture"] = _ref(mat.albedo_texture)
+		rec["transparency"] = int(mat.transparency)
+		rec["cull_mode"] = int(mat.cull_mode)
+	elif mat is ShaderMaterial and mat.shader != null:
+		rec["shader"] = _ref(mat.shader)
+	return rec
+
+
+func _format(f):
+	var names = []
+	var flags = [[Mesh.ARRAY_FORMAT_NORMAL, "normal"], [Mesh.ARRAY_FORMAT_TANGENT, "tangent"], [Mesh.ARRAY_FORMAT_COLOR, "color"], [Mesh.ARRAY_FORMAT_TEX_UV, "uv"], [Mesh.ARRAY_FORMAT_TEX_UV2, "uv2"], [Mesh.ARRAY_FORMAT_BONES, "bones"], [Mesh.ARRAY_FORMAT_WEIGHTS, "weights"], [Mesh.ARRAY_FORMAT_INDEX, "index"]]
+	for fl in flags:
+		if (int(f) & int(fl[0])) != 0:
+			names.append(fl[1])
+	return names
+
+
+func _mesh(mesh):
+	var bb = mesh.get_aabb()
+	var out = {"aabb": {"min": _v3(bb.position), "max": _v3(bb.end), "size": _v3(bb.size)}}
+	var count = mesh.get_surface_count()
+	out["surface_count"] = count
+	var surfaces = []
+	var materials = []
+	var seen = {}
+	var tris = 0
+	var verts_total = 0
+	for s in range(count):
+		var rec = {"index": s}
+		var prim = Mesh.PRIMITIVE_TRIANGLES
+		var vc = 0
+		var ic = 0
+		if mesh is ArrayMesh:
+			prim = mesh.surface_get_primitive_type(s)
+			vc = mesh.surface_get_array_len(s)
+			ic = mesh.surface_get_array_index_len(s)
+			if String(mesh.surface_get_name(s)) != "":
+				rec["name"] = String(mesh.surface_get_name(s))
+			rec["attributes"] = _format(mesh.surface_get_format(s))
+		else:
+			var arr = mesh.surface_get_arrays(s)
+			if arr.size() > Mesh.ARRAY_INDEX:
+				var va = arr[Mesh.ARRAY_VERTEX]
+				var ia = arr[Mesh.ARRAY_INDEX]
+				vc = va.size() if va != null else 0
+				ic = ia.size() if ia != null else 0
+		rec["primitive"] = PRIMITIVES[prim] if prim >= 0 and prim < PRIMITIVES.size() else str(prim)
+		rec["vertices"] = vc
+		rec["indices"] = ic
+		var n = ic if ic > 0 else vc
+		var t = 0
+		if prim == Mesh.PRIMITIVE_TRIANGLES:
+			t = floori(n / 3.0)
+		elif prim == Mesh.PRIMITIVE_TRIANGLE_STRIP:
+			t = maxi(n - 2, 0)
+		rec["triangles"] = t
+		tris += t
+		verts_total += vc
+		var mat = mesh.surface_get_material(s)
+		rec["material"] = _material(mat)
+		if mat != null:
+			var key = String(mat.resource_path) if String(mat.resource_path) != "" else str(mat.get_instance_id())
+			if not seen.has(key):
+				seen[key] = true
+				materials.append(_material(mat))
+		if surfaces.size() < MAX_SURFACES:
+			surfaces.append(rec)
+	out["surfaces"] = surfaces
+	if count > surfaces.size():
+		out["surfaces_cut"] = count - surfaces.size()
+	out["triangles"] = tris
+	out["vertices"] = verts_total
+	out["materials"] = materials
+	if mesh is ArrayMesh:
+		out["blend_shapes"] = mesh.get_blend_shape_count()
+	return out
+
+
+func _scene(ps):
+	var st = ps.get_state()
+	var n = st.get_node_count()
+	var nodes = []
+	var meshes = []
+	var seen = {}
+	var mesh_nodes = 0
+	for i in range(n):
+		var rec = {"path": String(st.get_node_path(i)), "type": String(st.get_node_type(i))}
+		var inst = st.get_node_instance(i)
+		if inst != null:
+			rec["instance"] = String(inst.resource_path)
+		for k in range(st.get_node_property_count(i)):
+			if String(st.get_node_property_name(i, k)) != "mesh":
+				continue
+			var m = st.get_node_property_value(i, k)
+			if not (m is Mesh):
+				continue
+			mesh_nodes += 1
+			var mref = _ref(m)
+			rec["mesh"] = mref
+			var key = String(m.resource_path) if String(m.resource_path) != "" else str(m.get_instance_id())
+			if not seen.has(key) and meshes.size() < MAX_SCENE_MESHES:
+				seen[key] = true
+				var bb = m.get_aabb()
+				var mrec = mref.duplicate()
+				mrec["surfaces"] = m.get_surface_count()
+				mrec["aabb_size"] = _v3(bb.size)
+				meshes.append(mrec)
+		if nodes.size() < MAX_NODES:
+			nodes.append(rec)
+	var out = {"node_count": n, "root_type": String(st.get_node_type(0)) if n > 0 else "", "nodes": nodes, "mesh_nodes": mesh_nodes, "meshes": meshes}
+	if n > nodes.size():
+		out["nodes_cut"] = n - nodes.size()
+	return out
+
+
+func _same(a, b):
+	if typeof(a) != typeof(b):
+		return false
+	return a == b
+
+
+func _value(v):
+	var t = typeof(v)
+	if t == TYPE_NIL or t == TYPE_BOOL or t == TYPE_INT or t == TYPE_FLOAT or t == TYPE_STRING or t == TYPE_STRING_NAME:
+		return v if t != TYPE_STRING_NAME else String(v)
+	if t == TYPE_OBJECT:
+		if v is Resource:
+			return _ref(v)
+		return v.get_class() if v != null else null
+	if t >= TYPE_PACKED_BYTE_ARRAY:
+		return type_string(t) + "(" + str(v.size()) + " items)"
+	var s = var_to_str(v)
+	if s.length() > MAX_VALUE_CHARS:
+		s = s.substr(0, MAX_VALUE_CHARS) + "..."
+	return s
+
+
+func _props(res):
+	var props = {}
+	var defaults = 0
+	var cut = 0
+	var cls = res.get_class()
+	var builtin = res.get_script() == null
+	var skip = PROPERTY_USAGE_GROUP | PROPERTY_USAGE_CATEGORY | PROPERTY_USAGE_SUBGROUP
+	for p in res.get_property_list():
+		var usage = int(p["usage"])
+		if (usage & PROPERTY_USAGE_EDITOR) == 0 or (usage & skip) != 0:
+			continue
+		var name = String(p["name"])
+		if name == "resource_path" or name == "resource_name" or name == "script":
+			continue
+		var v = res.get(name)
+		if builtin and _same(v, ClassDB.class_get_property_default_value(cls, name)):
+			defaults += 1
+			continue
+		if props.size() >= MAX_PROPS:
+			cut += 1
+			continue
+		props[name] = _value(v)
+	return {"props": props, "defaults": defaults, "cut": cut}
+`;

package/dist/core/capabilities/math3d.d.ts

@@ -0,0 +1,28 @@
+/**
+ * math3d — the little 3D math the read and placement helpers need, in
+ * Godot's conventions: a Basis is three ROWS (Transform3D literals list
+ * xx, xy, xz, yx, ... then the origin), Euler angles default to YXZ order,
+ * and a Node3D's local basis is rotation * scale.
+ */
+export type Vec3 = [number, number, number];
+export type Mat3 = [Vec3, Vec3, Vec3];
+export declare const IDENTITY3: Mat3;
+export declare function mulMat3(a: Mat3, b: Mat3): Mat3;
+export declare function applyMat3(m: Mat3, v: Vec3): Vec3;
+/** Inverse, or null for a singular basis. */
+export declare function invertMat3(m: Mat3): Mat3 | null;
+/** Godot Basis::from_euler (YXZ order, degrees) times scale: R * S. */
+export declare function basisFromEulerScale(rotDeg: Vec3, scale: Vec3): Mat3;
+/** "(1, 2, 3)" / "Vector3(1, 2, 3)" -> [1, 2, 3]. */
+export declare function parseVec3(value: unknown): Vec3 | null;
+/** A `Transform3D(12 numbers)` literal -> basis rows + origin. */
+export declare function parseTransform3D(value: string): {
+    basis: Mat3;
+    origin: Vec3;
+} | null;
+/** Vector3 literal at 3 decimals (for reports). */
+export declare function vec3Literal(v: Vec3): string;
+/** Vector3 literal for writing a position back: 12 significant digits
+ *  (beyond Godot's float32 storage) without binary-arithmetic noise. */
+export declare function vec3LiteralExact(v: Vec3): string;
+export declare function transformLiteral(basis: Mat3, origin: Vec3): string;

package/dist/core/capabilities/math3d.js

@@ -0,0 +1,88 @@
+/**
+ * math3d — the little 3D math the read and placement helpers need, in
+ * Godot's conventions: a Basis is three ROWS (Transform3D literals list
+ * xx, xy, xz, yx, ... then the origin), Euler angles default to YXZ order,
+ * and a Node3D's local basis is rotation * scale.
+ */
+export const IDENTITY3 = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+export function mulMat3(a, b) {
+    const out = [[0, 0, 0], [0, 0, 0], [0, 0, 0]];
+    for (let i = 0; i < 3; i++) {
+        for (let j = 0; j < 3; j++)
+            out[i][j] = a[i][0] * b[0][j] + a[i][1] * b[1][j] + a[i][2] * b[2][j];
+    }
+    return out;
+}
+export function applyMat3(m, v) {
+    return [
+        m[0][0] * v[0] + m[0][1] * v[1] + m[0][2] * v[2],
+        m[1][0] * v[0] + m[1][1] * v[1] + m[1][2] * v[2],
+        m[2][0] * v[0] + m[2][1] * v[1] + m[2][2] * v[2],
+    ];
+}
+/** Inverse, or null for a singular basis. */
+export function invertMat3(m) {
+    const [[a, b, c], [d, e, f], [g, h, i]] = m;
+    const A = e * i - f * h;
+    const B = -(d * i - f * g);
+    const C = d * h - e * g;
+    const det = a * A + b * B + c * C;
+    if (!Number.isFinite(det) || Math.abs(det) < 1e-12)
+        return null;
+    return [
+        [A / det, -(b * i - c * h) / det, (b * f - c * e) / det],
+        [B / det, (a * i - c * g) / det, -(a * f - c * d) / det],
+        [C / det, -(a * h - b * g) / det, (a * e - b * d) / det],
+    ];
+}
+/** Godot Basis::from_euler (YXZ order, degrees) times scale: R * S. */
+export function basisFromEulerScale(rotDeg, scale) {
+    const [x, y, z] = rotDeg.map((d) => (d * Math.PI) / 180);
+    const xm = [[1, 0, 0], [0, Math.cos(x), -Math.sin(x)], [0, Math.sin(x), Math.cos(x)]];
+    const ym = [[Math.cos(y), 0, Math.sin(y)], [0, 1, 0], [-Math.sin(y), 0, Math.cos(y)]];
+    const zm = [[Math.cos(z), -Math.sin(z), 0], [Math.sin(z), Math.cos(z), 0], [0, 0, 1]];
+    const s = [[scale[0], 0, 0], [0, scale[1], 0], [0, 0, scale[2]]];
+    return mulMat3(mulMat3(mulMat3(ym, xm), zm), s);
+}
+/** "(1, 2, 3)" / "Vector3(1, 2, 3)" -> [1, 2, 3]. */
+export function parseVec3(value) {
+    if (typeof value !== "string")
+        return null;
+    const match = /^\s*(?:Vector3)?\(\s*([-+0-9.eE]+)\s*,\s*([-+0-9.eE]+)\s*,\s*([-+0-9.eE]+)\s*\)\s*$/.exec(value);
+    if (!match)
+        return null;
+    const out = [Number(match[1]), Number(match[2]), Number(match[3])];
+    return out.every(Number.isFinite) ? out : null;
+}
+/** A `Transform3D(12 numbers)` literal -> basis rows + origin. */
+export function parseTransform3D(value) {
+    const match = /^\s*Transform3D\(([^)]*)\)\s*$/.exec(value);
+    if (!match)
+        return null;
+    const n = match[1].split(",").map((part) => Number(part.trim()));
+    if (n.length !== 12 || !n.every(Number.isFinite))
+        return null;
+    return {
+        basis: [[n[0], n[1], n[2]], [n[3], n[4], n[5]], [n[6], n[7], n[8]]],
+        origin: [n[9], n[10], n[11]],
+    };
+}
+function num3(value) {
+    const rounded = Math.round(value * 1000) / 1000;
+    return String(Object.is(rounded, -0) ? 0 : rounded);
+}
+/** Vector3 literal at 3 decimals (for reports). */
+export function vec3Literal(v) {
+    return `Vector3(${v.map(num3).join(", ")})`;
+}
+/** Vector3 literal for writing a position back: 12 significant digits
+ *  (beyond Godot's float32 storage) without binary-arithmetic noise. */
+export function vec3LiteralExact(v) {
+    return `Vector3(${v.map((value) => {
+        const clean = Number(value.toPrecision(12));
+        return String(Object.is(clean, -0) ? 0 : clean);
+    }).join(", ")})`;
+}
+export function transformLiteral(basis, origin) {
+    return `Transform3D(${[...basis[0], ...basis[1], ...basis[2], ...origin].map(num3).join(", ")})`;
+}

package/dist/core/capabilities/motion-generation.d.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+/** Shared MCP/CLI contract for POST /api/mcp/generate/motion.
+ *
+ *  Two backends are exposed:
+ *   - meshy-library: curated mocap clip by name on a Summer-rigged humanoid.
+ *   - text-to-motion: Summer-hosted text-to-motion model; animates any of the
+ *     caller's own rigged models (5-70 bones) from text prompts.
+ *  The Studio route also has "hunyuan-custom"; it stays hidden (it returns a
+ *  generic skeleton that is not retargeted onto the caller's rig). */
+export declare const MOTION_BACKENDS: readonly ["meshy-library", "text-to-motion"];
+export type MotionBackend = (typeof MOTION_BACKENDS)[number];
+export declare const motionGenerationArgsSchema: z.ZodObject<{
+    rigAssetId: z.ZodString;
+    backend: z.ZodDefault<z.ZodEnum<["meshy-library", "text-to-motion"]>>;
+    motionName: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodString>;
+    prompts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    takes: z.ZodOptional<z.ZodNumber>;
+    lockJoints: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    cfgScale: z.ZodOptional<z.ZodNumber>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    wait: z.ZodDefault<z.ZodBoolean>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "strip", z.ZodTypeAny, {
+    wait: boolean;
+    rigAssetId: string;
+    backend: "meshy-library" | "text-to-motion";
+    options?: Record<string, any> | undefined;
+    prompt?: string | undefined;
+    motionName?: string | undefined;
+    prompts?: string[] | undefined;
+    takes?: number | undefined;
+    lockJoints?: string[] | undefined;
+    cfgScale?: number | undefined;
+    idempotencyKey?: string | undefined;
+}, {
+    rigAssetId: string;
+    options?: Record<string, any> | undefined;
+    wait?: boolean | undefined;
+    prompt?: string | undefined;
+    backend?: "meshy-library" | "text-to-motion" | undefined;
+    motionName?: string | undefined;
+    prompts?: string[] | undefined;
+    takes?: number | undefined;
+    lockJoints?: string[] | undefined;
+    cfgScale?: number | undefined;
+    idempotencyKey?: string | undefined;
+}>;
+export type MotionGenerationArgs = z.input<typeof motionGenerationArgsSchema>;
+/** Validate the backend-specific rules zod cannot express on a flat shape and
+ *  build the request body. Returns an error message instead of throwing so
+ *  each face renders it its own way. */
+export declare function buildMotionRequestBody(args: MotionGenerationArgs): {
+    body: Record<string, unknown>;
+} | {
+    error: string;
+};
+/** Actionable hint for a server error code, if we know one. */
+export declare function motionErrorHint(code: unknown): string | undefined;
+/** Hint for a failed text-to-motion job ("text_motion: ..." failures are input
+ *  problems and the charge is refunded). */
+export declare function motionJobFailureHint(message: unknown): string | undefined;