@energy8platform/golem 0.3.0 → 0.5.0

package/dist/lib/tools.js

@@ -1,6 +1,6 @@
 // src/rig-api.ts
 import { z as z3 } from "zod";
-import { readFile as readFile9, writeFile as writeFile7, stat as stat2 } from "node:fs/promises";
+import { readFile as readFile9, writeFile as writeFile7, stat as stat2, mkdir as mkdir6, readdir as readdir4 } from "node:fs/promises";
 import { dirname as dirname8, join as join9, relative as relative2, isAbsolute } from "node:path";
 
 // src/rig-io.ts
@@ -289,6 +289,7 @@ var Key = z.object({
 });
 var Interpolation = { interpolation: z.enum(["segment", "pchip"]).optional() };
 var Track = z.discriminatedUnion("target", [
+  z.object({ target: z.literal("control"), id: Id, prop: z.literal("value"), ...Interpolation, keys: z.array(Key).min(1) }),
   z.object({ target: z.literal("bone"), id: Id, prop: BoneProp, ...Interpolation, keys: z.array(Key).min(1) }),
   z.object({ target: z.literal("slot"), id: Id, prop: SlotProp, ...Interpolation, keys: z.array(Key).min(1) }),
   z.object({ target: z.literal("deform"), id: Id, prop: DeformProp, ...Interpolation, keys: z.array(Key).min(1) }),
@@ -311,6 +312,25 @@ var Animation = z.object({
   /** if generated from a preset — keep params so the agent can re-tune instead of re-keying */
   preset: z.object({ name: z.string(), params: z.record(z.unknown()) }).optional()
 });
+var RigControl = z.object({
+  id: Id,
+  label: z.string().optional(),
+  min: z.number().finite(),
+  max: z.number().finite(),
+  default: z.number().finite()
+}).strict();
+var ControlValues = z.array(z.union([z.number().finite(), z.array(z.number().finite()).min(1)])).min(2);
+var ControlChannel = z.discriminatedUnion("target", [
+  z.object({ target: z.literal("bone"), id: Id, prop: BoneProp, values: ControlValues }).strict(),
+  z.object({ target: z.literal("slot"), id: Id, prop: z.literal("alpha"), values: ControlValues }).strict(),
+  z.object({ target: z.literal("deform"), id: Id, prop: z.literal("vertices"), values: ControlValues }).strict()
+]);
+var ControlBinding = z.object({
+  id: Id,
+  axes: z.array(z.object({ control: Id, keys: z.array(z.number().finite()).min(2).max(32) }).strict()).min(1).max(2),
+  /** Flattened grid, first axis varies fastest. Linear / bilinear interpolation. */
+  channels: z.array(ControlChannel).min(1)
+}).strict();
 var Reference = z.object({
   src: z.string(),
   opacity: z.number().min(0).max(1).default(0.5),
@@ -336,7 +356,9 @@ var RigSchema = z.object({
   ik: z.array(IkConstraint).default([]),
   transform: z.array(TransformConstraint).default([]),
   path: z.array(PathConstraint).default([]),
-  animations: z.array(Animation)
+  animations: z.array(Animation),
+  controls: z.array(RigControl).optional(),
+  controlBindings: z.array(ControlBinding).optional()
 });
 var RigDocument = z.preprocess((input) => {
   const v = input?.version;
@@ -411,6 +433,8 @@ function validate(doc) {
   dup(doc.ik, "ik");
   dup(doc.transform, "transform");
   dup(doc.path, "path");
+  dup(doc.controls ?? [], "control");
+  dup(doc.controlBindings ?? [], "control binding");
   const bones = new Set(doc.bones.map((b) => b.id));
   const assets = new Map(doc.assets.map((a) => [a.id, a]));
   const slots = new Set(doc.slots.map((s) => s.id));
@@ -485,13 +509,47 @@ function validate(doc) {
     for (const b of c.bones) if (!bones.has(b)) errs.push(`path "${c.id}": unknown bone "${b}"`);
     if (!slots.has(c.target)) errs.push(`path "${c.id}": unknown target slot "${c.target}"`);
   }
+  const controls = new Map((doc.controls ?? []).map((c) => [c.id, c]));
+  const driven = /* @__PURE__ */ new Set();
+  for (const c of controls.values()) if (!(c.min < c.max && c.default >= c.min && c.default <= c.max))
+    errs.push(`control "${c.id}": require min < max and default within range`);
+  for (const b of doc.controlBindings ?? []) {
+    const prefix = `control binding "${b.id}"`;
+    if (new Set(b.axes.map((a) => a.control)).size !== b.axes.length) errs.push(`${prefix}: axes must use different controls`);
+    for (const axis of b.axes) {
+      const c = controls.get(axis.control);
+      if (!c) errs.push(`${prefix}: unknown control "${axis.control}"`);
+      else if (axis.keys[0] !== c.min || axis.keys.at(-1) !== c.max) errs.push(`${prefix}: keys must span the control's full range`);
+      if (axis.keys.some((v, i) => i > 0 && v <= axis.keys[i - 1])) errs.push(`${prefix}: keys must be strictly increasing`);
+    }
+    const count = b.axes.reduce((n, a) => n * a.keys.length, 1);
+    for (const ch of b.channels) {
+      const key = `${ch.target}.${ch.id}.${ch.prop}`;
+      if (driven.has(key)) errs.push(`${prefix}: channel ${key} already owned by a binding`);
+      driven.add(key);
+      if (ch.values.length !== count) errs.push(`${prefix}: ${key} needs ${count} grid values`);
+      if (ch.target === "deform") {
+        const att = attachments.get(ch.id);
+        if (!att || att.type === "region") errs.push(`${prefix}: vertices need a mesh or path attachment`);
+        else {
+          const n = att.weights ? att.weights.reduce((s, a) => s + a.length * 2, 0) : att.vertices.length;
+          if (ch.values.some((v) => !Array.isArray(v) || v.length !== n)) errs.push(`${prefix}: ${key} needs arrays of ${n} offsets`);
+        }
+      } else {
+        if (!(ch.target === "bone" ? bones : slots).has(ch.id)) errs.push(`${prefix}: unknown ${ch.target} "${ch.id}"`);
+        if (ch.values.some((v) => typeof v !== "number")) errs.push(`${prefix}: ${key} needs numeric values`);
+        if (ch.target === "slot" && ch.values.some((v) => typeof v === "number" && (v < 0 || v > 1))) errs.push(`${prefix}: alpha must be in 0..1`);
+      }
+    }
+  }
   for (const a of doc.animations) {
     const tracks = /* @__PURE__ */ new Set();
     for (const t of a.tracks) {
       const tid = trackId(t);
       if (tracks.has(tid)) errs.push(`animation "${a.id}": duplicate track ${tid}`);
       tracks.add(tid);
-      const known = t.target === "bone" ? bones.has(t.id) : t.target === "slot" ? slots.has(t.id) : t.target === "deform" ? attachments.has(t.id) : t.target === "ik" ? iks.has(t.id) : t.target === "transform" ? transforms.has(t.id) : t.target === "path" ? paths.has(t.id) : true;
+      if (driven.has(tid)) errs.push(`animation "${a.id}": ${tid} is controlled by a binding; animate its control instead`);
+      const known = t.target === "bone" ? bones.has(t.id) : t.target === "slot" ? slots.has(t.id) : t.target === "deform" ? attachments.has(t.id) : t.target === "ik" ? iks.has(t.id) : t.target === "transform" ? transforms.has(t.id) : t.target === "path" ? paths.has(t.id) : t.target === "control" ? controls.has(t.id) : true;
       if (!known) errs.push(`animation "${a.id}": unknown ${t.target} "${t.id}"`);
       const bound = t.target === "deform" ? DEFORM_BOUNDS[t.prop] : void 0;
       const att = t.target === "deform" ? attachments.get(t.id) : void 0;
@@ -499,6 +557,10 @@ function validate(doc) {
       for (const k of t.keys) {
         if (k.t <= prev && prev >= 0) errs.push(`animation "${a.id}" ${tid}: keys not strictly increasing`);
         if (k.t > a.duration) errs.push(`animation "${a.id}" ${tid}: key at ${k.t}s exceeds duration`);
+        if (t.target === "control") {
+          const c = controls.get(t.id);
+          if (typeof k.v !== "number" || !Number.isFinite(k.v) || c && (k.v < c.min || k.v > c.max)) errs.push(`animation "${a.id}" ${tid}: control key outside its finite range`);
+        }
         if (t.target === "slot" && t.prop === "attachment") {
           if (k.v !== null && typeof k.v !== "string") errs.push(`animation "${a.id}" ${tid}: attachment key must be an attachment id or null`);
           else if (typeof k.v === "string") {
@@ -537,6 +599,65 @@ function parse(input) {
   return doc;
 }
 
+// src/rig-controls.ts
+function controlPose(doc, values2) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [id, value] of Object.entries(values2)) {
+    const c = doc.controls?.find((c2) => c2.id === id);
+    if (!c) throw new Error(`unknown control "${id}"`);
+    if (!Number.isFinite(value)) throw new Error(`control "${id}" must be finite`);
+    out.set(`control:${id}:value`, Math.max(c.min, Math.min(c.max, value)));
+  }
+  return out;
+}
+function bracket(keys, value) {
+  let i = 0;
+  while (i < keys.length - 2 && value > keys[i + 1]) i++;
+  return [i, Math.max(0, Math.min(1, (value - keys[i]) / (keys[i + 1] - keys[i])))];
+}
+function sampleBinding(binding, values2) {
+  const [x, u] = bracket(binding.axes[0].keys, values2[0]);
+  const [y, v] = binding.axes[1] ? bracket(binding.axes[1].keys, values2[1]) : [0, 0];
+  const width = binding.axes[0].keys.length, a = y * width + x;
+  const mix = (a2, b, u2) => a2 + (b - a2) * u2;
+  return binding.channels.map((ch) => {
+    const read = (i, j2) => j2 === void 0 ? ch.values[i] : ch.values[i][j2];
+    const at = (j2) => {
+      const top = mix(read(a, j2), read(a + 1, j2), u);
+      return binding.axes[1] ? mix(top, mix(read(a + width, j2), read(a + width + 1, j2), u), v) : top;
+    };
+    return Array.isArray(ch.values[0]) ? ch.values[0].map((_, j2) => at(j2)) : at();
+  });
+}
+function resolveControls(doc, input) {
+  if (!doc.controlBindings?.length) return input;
+  const out = new Map(input), controls = new Map(doc.controls?.map((c) => [c.id, c]));
+  for (const b of doc.controlBindings) {
+    const values2 = b.axes.map((axis) => {
+      const c = controls.get(axis.control);
+      const value = input.get(`control:${c.id}:value`) ?? c.default;
+      if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`control "${c.id}" must be finite`);
+      return Math.max(c.min, Math.min(c.max, value));
+    });
+    const sampled2 = sampleBinding(b, values2);
+    b.channels.forEach((ch, i) => out.set(`${ch.target}:${ch.id}:${ch.prop}`, sampled2[i]));
+  }
+  return out;
+}
+function controlCases(doc, probes) {
+  let cases = [{ label: "default", values: {} }];
+  if (!Object.keys(probes).length) throw new Error("select controls and sample values for the sweep");
+  for (const [id, values2] of Object.entries(probes)) {
+    const c = doc.controls?.find((c2) => c2.id === id);
+    if (!c) throw new Error(`unknown control "${id}"`);
+    if (!values2.length || values2.some((v) => !Number.isFinite(v) || v < c.min || v > c.max) || new Set(values2).size !== values2.length)
+      throw new Error(`control "${id}": probes must be unique finite values inside its range`);
+    if (cases.length * values2.length > 256) throw new Error("control sweep exceeds 256 poses; choose a smaller grid");
+    cases = cases.flatMap((p) => values2.map((v) => ({ label: p.label === "default" ? `${id}=${v}` : `${p.label}, ${id}=${v}`, values: { ...p.values, [id]: v } })));
+  }
+  return cases;
+}
+
 // src/rig-anim.ts
 var DEG2 = Math.PI / 180;
 var named = {
@@ -640,6 +761,7 @@ function blendPoses(from, to, w, restOf) {
 }
 function restValue(doc, key) {
   const [target, id, prop] = key.split(":");
+  if (target === "control") return doc.controls?.find((c) => c.id === id)?.default ?? 0;
   if (target === "bone") return doc.bones.find((b) => b.id === id).transform[prop];
   if (target === "slot") {
     const s = doc.slots.find((s2) => s2.id === id);
@@ -746,7 +868,9 @@ function updateSubtree(skel, root2) {
     for (const k of kids.get(id) ?? []) stack.push(k.id);
   }
 }
-function evaluate(doc, pose) {
+function evaluate(doc, pose, modifiers) {
+  pose = resolveControls(doc, pose);
+  if (modifiers) for (const modify of modifiers) pose = modify(new Map(pose));
   const skel = { doc, pose, bones: /* @__PURE__ */ new Map(), attachment: /* @__PURE__ */ new Map() };
   for (const b of boneOrder(doc)) {
     const s = localOf(doc, pose, b);
@@ -1972,6 +2096,9 @@ function updateBone(doc, id, patch) {
   const i = doc.bones.findIndex((b) => b.id === id);
   if (i < 0) throw new Error(`unknown bone "${id}"`);
   const cur = doc.bones[i];
+  for (const b of doc.controlBindings ?? []) for (const ch of b.channels)
+    if (ch.target === "bone" && ch.id === id && patch.transform?.[ch.prop] !== void 0)
+      throw new Error(`bone "${id}" ${ch.prop} is controlled by "${b.id}"; edit its keyforms`);
   const { parent, ...rest } = patch;
   const next = RigSchema.shape.bones.element.parse({
     ...cur,
@@ -2004,6 +2131,11 @@ function patchDrawOrder(doc, fn) {
   return { ...doc, animations: doc.animations.map((a) => ({ ...a, tracks: a.tracks.map((t) => t.target !== "drawOrder" ? t : { ...t, keys: t.keys.map((k) => ({ ...k, v: fn(k.v) })) }) })) };
 }
 function setSlot(doc, slot) {
+  if (slot.alpha !== void 0) {
+    for (const b of doc.controlBindings ?? [])
+      if (b.channels.some((ch) => ch.target === "slot" && ch.id === slot.id && ch.prop === "alpha"))
+        throw new Error(`slot "${slot.id}" alpha is controlled by "${b.id}"; edit its keyforms`);
+  }
   const cur = doc.slots.find((s) => s.id === slot.id);
   if (cur && slot.bone && slot.bone !== cur.bone) doc = rebindSlot(doc, slot.id, slot.bone).doc;
   const base = doc.slots.find((s) => s.id === slot.id);
@@ -2378,6 +2510,7 @@ function trackSummary(t) {
 function rename2(doc, kind, id, to) {
   if (!ID_RE.test(to)) throw new Error(`"${to}" is not a snake_case id`);
   if (to === id) return doc;
+  if (doc.controlBindings) doc = { ...doc, controlBindings: doc.controlBindings.map((b) => ({ ...b, channels: b.channels.map((ch) => ch.id === id && (kind === ch.target || kind === "attachment" && ch.target === "deform") ? { ...ch, id: to } : ch) })) };
   const sub = (v) => v === id ? to : v;
   const subKeys = (t, pred, f) => pred ? { ...t, keys: t.keys.map((k) => ({ ...k, v: f(k.v) })) } : t;
   const retrack = (target) => (t) => t.target === target && t.id === id ? { ...t, id: to } : t;
@@ -2459,6 +2592,8 @@ function describeAttachment(doc, att) {
 }
 function describe(doc, opts = {}) {
   const lines = [`${doc.meta.name} ${doc.meta.width}x${doc.meta.height}`];
+  for (const c of doc.controls ?? []) lines.push(`control ${c.id}: [${c.min}..${c.max}], default ${c.default}${c.label ? ` (${c.label})` : ""}`);
+  for (const b of doc.controlBindings ?? []) lines.push(`keyforms ${b.id}: ${b.axes.map((a) => `${a.control}[${a.keys.join(",")}]`).join(" \xD7 ")} \u2192 ${b.channels.map((c) => `${c.target}.${c.id}.${c.prop}`).join(", ")}`);
   if (doc.meta.notes) lines.push(`notes: ${doc.meta.notes}`);
   const kids = (id) => doc.bones.filter((b) => b.parent === id);
   const place = (s) => {
@@ -3158,8 +3293,8 @@ function motionQuality(doc, anim, opts = {}) {
       if (!skel.attachment.get(front) || !skel.attachment.get(back)) continue;
       const visible = (id) => {
         const slot = doc.slots.find((s) => s.id === id);
-        const color = pose.get(pk("slot", id, "color")) ?? colorToArray(slot.color);
-        return Number(pose.get(pk("slot", id, "alpha")) ?? slot.alpha) * color[3] > 0;
+        const color = skel.pose.get(pk("slot", id, "color")) ?? colorToArray(slot.color);
+        return Number(skel.pose.get(pk("slot", id, "alpha")) ?? slot.alpha) * color[3] > 0;
       };
       if (!visible(front) || !visible(back)) continue;
       const order = pose.get(pk("drawOrder", "order", "order"));
@@ -3234,6 +3369,7 @@ function checkRig(doc, opts = {}) {
   });
   const W = doc.meta.width, H = doc.meta.height;
   const overflowOf = (pose, slotId, skel) => {
+    pose = skel.pose;
     const pts = slotOutline(doc, pose, slotId, 4, skel);
     if (!pts) return void 0;
     const slot = doc.slots.find((s) => s.id === slotId), alphaV = pose.get(`slot:${slotId}:alpha`);
@@ -3432,6 +3568,7 @@ function checkRig(doc, opts = {}) {
       }
     }
     const vertexKeyed = new Set(a.tracks.filter((t) => t.target === "deform" && t.prop === "vertices").map((t) => t.id));
+    for (const b of doc.controlBindings ?? []) for (const ch of b.channels) if (ch.target === "deform") vertexKeyed.add(ch.id);
     const deformMeshes = meshes.filter((att) => vertexKeyed.has(att.id));
     const bonesMeshes = meshes.filter((att) => !vertexKeyed.has(att.id));
     const meshFolds = /* @__PURE__ */ new Map();
@@ -3768,11 +3905,13 @@ function diffDocs(a, b) {
     ["attachments", "attachment"],
     ["ik", "ik"],
     ["transform", "transform"],
-    ["path", "path"]
+    ["path", "path"],
+    ["controls", "control"],
+    ["controlBindings", "control binding"]
   ];
   for (const [kind, name] of kinds) {
-    const ma = new Map(a[kind].map((x) => [x.id, x]));
-    const mb = new Map(b[kind].map((x) => [x.id, x]));
+    const ma = new Map((a[kind] ?? []).map((x) => [x.id, x]));
+    const mb = new Map((b[kind] ?? []).map((x) => [x.id, x]));
     for (const [id, x] of mb) if (!ma.has(id)) out.push(`+ ${name} ${id} ${j(x)}`);
     for (const [id, x] of ma) {
       const y = mb.get(id);
@@ -4609,7 +4748,7 @@ function extractTemplate(doc, animId, name, groups = {}) {
   const tracks = [];
   const skipped = [];
   for (const t of anim.tracks) {
-    if (t.target === "drawOrder" || t.keys.some((k) => Array.isArray(k.v))) {
+    if (t.target === "control" || t.target === "drawOrder" || t.keys.some((k) => Array.isArray(k.v))) {
       skipped.push(trackId5(t));
       continue;
     }
@@ -4984,8 +5123,8 @@ function runGates(doc, config) {
     let active2 = 0, bad = 0;
     for (const t of ts) {
       const pose = poseOf(animation, t), s = evaluate(doc, pose);
-      const color = pose.get(pk("slot", slot.id, "color")) ?? colorToArray(slot.color);
-      const alpha = Number(pose.get(pk("slot", slot.id, "alpha")) ?? slot.alpha) * color[3];
+      const color = s.pose.get(pk("slot", slot.id, "color")) ?? colorToArray(slot.color);
+      const alpha = Number(s.pose.get(pk("slot", slot.id, "alpha")) ?? slot.alpha) * color[3];
       if (!s.attachment.get(slot.id) || alpha <= 0.01) continue;
       active2++;
       const v = bone(s, rule.bone, rule.prop === "rotation" ? "rotation" : "position", rule.space)[rule.prop === "y" ? 1 : 0];
@@ -5207,6 +5346,53 @@ function bakeSecondary(doc, animation, opts) {
   return next;
 }
 
+// src/rig-control-qa.ts
+function snapshot(doc, values2) {
+  const skel = evaluate(doc, controlPose(doc, values2));
+  return doc.slots.flatMap((slot) => {
+    const alpha = Number(skel.pose.get(`slot:${slot.id}:alpha`) ?? slot.alpha);
+    const points = slotOutline(doc, skel.pose, slot.id, 1, skel);
+    return points ? [{ id: slot.id, alpha, points }] : [];
+  });
+}
+function checkControlCases(doc, cases) {
+  const errors = [];
+  const rest = evaluate(doc, /* @__PURE__ */ new Map());
+  cases.forEach((c, index) => {
+    const skel = evaluate(doc, controlPose(doc, c.values));
+    for (const [id, b] of skel.bones) if (Object.values(b.world).some((v) => !Number.isFinite(v)))
+      errors.push({ case: index, subject: id, message: "non-finite bone transform" });
+    for (const att of doc.attachments) if (att.type === "mesh") {
+      const before = attachmentWorldVertices(rest, att.slot, att), after = attachmentWorldVertices(skel, att.slot, att);
+      if (after.some((v) => !Number.isFinite(v))) errors.push({ case: index, subject: att.id, message: "non-finite mesh vertices" });
+      else if (foldedTriangles(before, after, att.triangles).length || att.triangles.some((_, i) => i % 3 === 0 && Math.abs(triangleArea(before, ...att.triangles.slice(i, i + 3))) > 1e-8 && Math.abs(triangleArea(after, ...att.triangles.slice(i, i + 3))) < 1e-8))
+        errors.push({ case: index, subject: att.id, message: "mesh triangle reversed or collapsed" });
+    }
+  });
+  const neutral = JSON.stringify(snapshot(doc, {}));
+  const effects = (doc.controls ?? []).map((c) => ({
+    id: c.id,
+    geometryOrOpacityChanged: [c.min, c.max].some((v) => JSON.stringify(snapshot(doc, { [c.id]: v })) !== neutral)
+  }));
+  return {
+    passed: errors.length === 0,
+    errors,
+    effects,
+    scope: "Finite transforms and mesh orientation at the listed poses; individual control geometry/opacity effects. Images require visual review; this is not an artwork acceptance result."
+  };
+}
+function makeControlSweep(doc, probes) {
+  const cases = controlCases(doc, probes).map((c) => ({ ...c, values: { ...Object.fromEntries((doc.controls ?? []).map((p) => [p.id, p.default])), ...c.values } }));
+  const animation = {
+    id: "control_sweep",
+    duration: Math.max(1, cases.length - 1),
+    loop: false,
+    events: [],
+    tracks: (doc.controls ?? []).map((c) => ({ target: "control", id: c.id, prop: "value", keys: cases.map((p, i) => ({ t: i, v: p.values[c.id], ease: "step" })) }))
+  };
+  return { cases, doc: parse({ ...doc, animations: [animation] }), animation: animation.id, times: cases.map((_, i) => i) };
+}
+
 // src/rig-api.ts
 var tools = [];
 function tool(name, description, input, run) {
@@ -5270,7 +5456,80 @@ function previewCheck(doc, animation) {
   const a = animation ? doc.animations.find((x) => x.id === animation) : void 0;
   return a ? `check: OK for "${a.id}" (${a.tracks.length} tracks, ${a.duration}s${a.loop ? " loop" : ""})` : "check: OK (rest pose)";
 }
-var TrackRef = { interpolation: z3.enum(["segment", "pchip"]).optional().describe("pchip: smooth through numeric keys, preserving extrema; segment: per-key easing"), target: z3.enum(["bone", "slot", "deform", "ik", "transform", "path", "drawOrder"]), id: z3.string(), prop: z3.string() };
+var TrackRef = { interpolation: z3.enum(["segment", "pchip"]).optional().describe("pchip: smooth through numeric keys, preserving extrema; segment: per-key easing"), target: z3.enum(["bone", "slot", "deform", "ik", "transform", "path", "drawOrder", "control"]), id: z3.string(), prop: z3.string() };
+tool(
+  "rig_set_control",
+  "Create or replace a semantic control with a finite min/max/default range. Animate target=control, prop=value. Changing a range requires matching binding grids.",
+  { path: Path, control: RigControl },
+  async ({ path, control }) => mutate(path, (d) => ({ ...d, controls: [...(d.controls ?? []).filter((c) => c.id !== control.id), control] }))
+);
+tool(
+  "rig_set_control_binding",
+  "Create or replace a 1D/2D grid of absolute keyforms. First axis varies fastest. Channels support bone transforms, slot alpha and mesh/path vertex offsets. Each channel has one owner; animate controls rather than owned channels.",
+  { path: Path, binding: ControlBinding },
+  async ({ path, binding }) => mutate(path, (d) => ({ ...d, controlBindings: [...(d.controlBindings ?? []).filter((b) => b.id !== binding.id), binding] }))
+);
+tool(
+  "rig_remove_control_binding",
+  "Remove a control binding, restoring its channels to setup/animation values.",
+  { path: Path, id: z3.string() },
+  async ({ path, id }) => mutate(path, (d) => {
+    if (!d.controlBindings?.some((b) => b.id === id)) throw new Error(`unknown binding "${id}"`);
+    return { ...d, controlBindings: d.controlBindings.filter((b) => b.id !== id) };
+  })
+);
+tool(
+  "rig_remove_control",
+  "Remove an unused control and its animation tracks. Remove dependent bindings first.",
+  { path: Path, id: z3.string() },
+  async ({ path, id }) => mutate(path, (d) => {
+    if (!d.controls?.some((c) => c.id === id)) throw new Error(`unknown control "${id}"`);
+    if (d.controlBindings?.some((b) => b.axes.some((a) => a.control === id))) throw new Error("remove dependent control bindings first");
+    return { ...d, controls: d.controls.filter((c) => c.id !== id), animations: d.animations.map((a) => ({ ...a, tracks: a.tracks.filter((t) => t.target !== "control" || t.id !== id) })) };
+  })
+);
+tool(
+  "rig_sweep_controls",
+  "Render an explicit control grid (max 256 poses) through PixiJS, with PNGs, contact sheet and report tying cases to source/texture/renderer hashes. Geometry checks are not visual acceptance. Use a new output directory outside the packed rig.",
+  {
+    path: Path,
+    probes: z3.record(z3.array(z3.number().finite()).min(1)),
+    output: z3.string(),
+    scale: z3.number().positive().max(2).default(0.5),
+    region: z3.tuple([z3.number(), z3.number(), z3.number().positive(), z3.number().positive()]).optional()
+  },
+  async ({ path, probes, output, scale, region }) => {
+    try {
+      const raw = await readFile9(path, "utf8"), d = parse(JSON.parse(raw));
+      const sweep = makeControlSweep(d, probes), out = resolveFrom(path, output);
+      if (await exists2(out) && (await readdir4(out)).length) throw new Error("sweep output must be a new or empty directory");
+      const qa = checkControlCases(d, sweep.cases);
+      const r = await renderPreview(sweep.doc, { assetsDir: dirname8(path), animation: sweep.animation, times: sweep.times, scale, region, transparent: true });
+      await mkdir6(out, { recursive: true });
+      const frames = [];
+      for (let i = 0; i < r.frames.length; i++) {
+        const file = `pose-${String(i).padStart(3, "0")}.png`;
+        await writeFile7(join9(out, file), r.frames[i]);
+        frames.push({ file, sha256: sha256(r.frames[i]), ...sweep.cases[i] });
+      }
+      await writeFile7(join9(out, "sheet.png"), r.sheet);
+      const report = {
+        version: 1,
+        sourceRig: sha256(raw),
+        identity: r.identity,
+        scale,
+        region: region ?? null,
+        ...qa,
+        frames,
+        sheet: { file: "sheet.png", sha256: sha256(r.sheet) }
+      };
+      await saveJson(join9(out, "report.json"), report);
+      return { text: JSON.stringify({ output: out, poseCount: frames.length, ...qa }), image: r.sheet };
+    } catch (e) {
+      return fail(e);
+    }
+  }
+);
 var KeyIn = z3.object({
   t: z3.number().describe("seconds"),
   v: z3.union([z3.number(), z3.string(), z3.null(), z3.array(z3.number()), z3.array(z3.string())]),
@@ -6102,8 +6361,8 @@ tool(
       const r = await renderPreview(doc, { assetsDir: dirname8(path), ...opts });
       if (saveTo) await writeFile7(saveTo, r.sheet);
       if (framesDir) {
-        const { mkdir: mkdir6 } = await import("node:fs/promises");
-        await mkdir6(framesDir, { recursive: true });
+        const { mkdir: mkdir7 } = await import("node:fs/promises");
+        await mkdir7(framesDir, { recursive: true });
         const frames = r.frames.map((frame, i) => ({ file: `${String(i).padStart(6, "0")}.png`, sha256: sha256(frame) }));
         for (let i = 0; i < frames.length; i++) await writeFile7(join9(framesDir, frames[i].file), r.frames[i]);
         const manifest = {